ssh

package
v0.0.0-...-9d78121 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 4, 2020 License: LGPL-3.0 Imports: 31 Imported by: 78

Documentation

Overview

Package ssh contains utilities for dealing with SSH connections, key management, and so on. All SSH-based command executions in Juju should use the Command/ScpCommand functions in this package.

Index

Constants

View Source 
const JujuCommentPrefix = "Juju:"

Any ssh key added to the authorised keys list by Juju will have this prefix. This allows Juju to know which keys have been added externally and any such keys will always be retained by Juju when updating the authorised keys file.

View Source 
const PublicKeySuffix = ".pub"

PublicKeySuffix is the file extension for public key files.

Variables

View Source 
var Cancelled = errors.New("command timed out")

Cancelled is an error indicating that a command timed out.

View Source 
var KeyBits = 2048

KeyBits is used to determine the number of bits to use for the RSA keys created using the GenerateKey function.

Functions

func AddKeys 

func AddKeys(user string, newKeys ...string) error

AddKeys adds the specified ssh keys to the authorized_keys file for user. Returns an error if there is an issue with *any* of the supplied keys.

func ClearClientKeys 

func ClearClientKeys()

ClearClientKeys clears the client keys cached in memory.

func Copy 

func Copy(args []string, options *Options) error

Copy is a short-cut for DefaultClient.Copy.

func CopyReader 

func CopyReader(host, filename string, r io.Reader, options *Options) error

CopyReader sends the reader's data to a file on the remote host over SSH.

func DeleteKeys 

func DeleteKeys(user string, keyIds ...string) error

DeleteKeys removes the specified ssh keys from the authorized ssh keys file for user. keyIds may be either key comments or fingerprints. Returns an error if there is an issue with *any* of the keys to delete.

func EnsureJujuComment 

func EnsureJujuComment(key string) string

func ExecuteCommandOnMachine 

func ExecuteCommandOnMachine(args ExecParams) (utilexec.ExecResponse, error)

ExecuteCommandOnMachine will execute the command passed through on the host specified. This is done using ssh, and passing the commands through /bin/bash. If the command is not finished within the timeout specified, an error is returned. Any output captured during that time is also returned in the remote response.

func GenerateKey 

func GenerateKey(comment string) (private, public string, err error)

GenerateKey makes a 2048 bit RSA no-passphrase SSH capable key. The bit size is actually controlled by the KeyBits var. The private key returned is encoded to ASCII using the PKCS1 encoding. The public key is suitable to be added into an authorized_keys file, and has the comment passed in as the comment part of the key.

func GoCryptoKnownHostsFile 

func GoCryptoKnownHostsFile() string

GoCryptoKnownHostsFile returns the known_hosts file used by the golang.org/x/crypto/ssh-based client by default.

func KeyFingerprint 

func KeyFingerprint(key string) (fingerprint, comment string, err error)

KeyFingerprint returns the fingerprint and comment for the specified key in authorized_key format. Fingerprints are generated according to RFC4716. See ttp://www.ietf.org/rfc/rfc4716.txt, section 4.

func ListKeys 

func ListKeys(user string, mode ListMode) ([]string, error)

ListKeys returns either the full keys or key comments from the authorized ssh keys file for user.

func LoadClientKeys 

func LoadClientKeys(dir string) error

LoadClientKeys loads the client SSH keys from the specified directory, and caches them as a process-wide global. If the directory does not exist, it is created; if the directory did not exist, or contains no keys, it is populated with a new key pair.

If the directory exists, then all pairs of files where one has the same name as the other + ".pub" will be loaded as private/public key pairs.

Calls to LoadClientKeys will clear the previously loaded keys, and recompute the keys.

func PrivateKeyFiles 

func PrivateKeyFiles() []string

PrivateKeyFiles returns the filenames of private SSH keys loaded by LoadClientKeys.

func PublicKey 

func PublicKey(privateKey []byte, comment string) (string, error)

PublicKey returns the public key for any private key. The public key is suitable to be added into an authorized_keys file, and has the comment passed in as the comment part of the key.

func PublicKeyFiles 

func PublicKeyFiles() []string

PublicKeyFiles returns the filenames of public SSH keys loaded by LoadClientKeys.

func ReplaceKeys 

func ReplaceKeys(user string, newKeys ...string) error

ReplaceKeys writes the specified ssh keys to the authorized_keys file for user, replacing any that are already there. Returns an error if there is an issue with *any* of the supplied keys.

func SetGoCryptoKnownHostsFile 

func SetGoCryptoKnownHostsFile(file string)

SetGoCryptoKnownHostsFile returns the known_hosts file used by the golang.org/x/crypto/ssh-based client.

func SplitAuthorisedKeys 

func SplitAuthorisedKeys(keyData string) []string

SplitAuthorisedKeys extracts a key slice from the specified key data, by splitting the key data into lines and ignoring comments and blank lines.

func StripCRReader 

func StripCRReader(reader io.Reader) io.Reader

StripCRReader returns a new io.Reader wrapper that strips carriage returns.

func WrapStdin 

func WrapStdin(reader io.Reader) io.Reader

WrapStdin returns the original stdin stream on nix platforms.

Types

type AuthorisedKey 

type AuthorisedKey struct {
	Type    string
	Key     []byte
	Comment string
}

func ParseAuthorisedKey 

func ParseAuthorisedKey(line string) (*AuthorisedKey, error)

ParseAuthorisedKey parses a non-comment line from an authorized_keys file and returns the constituent parts. Based on description in "man sshd".

type Client 

type Client interface {
	// Command returns a Command for executing a command
	// on the specified host. Each Command is executed
	// within its own SSH session.
	//
	// Host is specified in the format [user@]host.
	Command(host string, command []string, options *Options) *Cmd

	// Copy copies file(s) between local and remote host(s).
	// Paths are specified in the scp format, [[user@]host:]path. If
	// any extra arguments are specified in extraArgs, they are passed
	// verbatim.
	Copy(args []string, options *Options) error
}

Client is an interface for SSH clients to implement 

var DefaultClient Client

DefaultClient is the default SSH client for the process.

If the OpenSSH client is found in $PATH, then it will be used for DefaultClient; otherwise, DefaultClient will use an embedded client based on go.crypto/ssh.

type Cmd 

type Cmd struct {
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
	// contains filtered or unexported fields
}

Cmd represents a command to be (or being) executed on a remote host.

func Command 

func Command(host string, command []string, options *Options) *Cmd

Command is a short-cut for DefaultClient.Command.

func (*Cmd) CombinedOutput 

func (c *Cmd) CombinedOutput() ([]byte, error)

CombinedOutput runs the command, and returns the combined stdout/stderr output and result of executing the command.

func (*Cmd) Kill 

func (c *Cmd) Kill() error

Kill kills the started command.

func (*Cmd) Output 

func (c *Cmd) Output() ([]byte, error)

Output runs the command, and returns the stdout output and result of executing the command.

func (*Cmd) Run 

func (c *Cmd) Run() error

Run runs the command, and returns the result as an error.

func (*Cmd) Start 

func (c *Cmd) Start() error

Start starts the command running, but does not wait for it to complete. If the command could not be started, an error is returned.

func (*Cmd) StderrPipe 

func (c *Cmd) StderrPipe() (io.ReadCloser, error)

StderrPipe creates a pipe and connects it to the command's stderr. The write end of the pipe is assigned to c.Stderr.

func (*Cmd) StdinPipe 

func (c *Cmd) StdinPipe() (io.WriteCloser, error)

StdinPipe creates a pipe and connects it to the command's stdin. The read end of the pipe is assigned to c.Stdin.

func (*Cmd) StdoutPipe 

func (c *Cmd) StdoutPipe() (io.ReadCloser, error)

StdoutPipe creates a pipe and connects it to the command's stdout. The write end of the pipe is assigned to c.Stdout.

func (*Cmd) Wait 

func (c *Cmd) Wait() error

Wait waits for the started command to complete, and returns the result as an error.

type ExecParams 

type ExecParams struct {
	IdentityFile string
	Host         string
	Command      string
	Timeout      time.Duration
}

ExecParams are used for the parameters for ExecuteCommandOnMachine.

type GoCryptoClient 

type GoCryptoClient struct {
	// contains filtered or unexported fields
}

GoCryptoClient is an implementation of Client that uses the embedded go.crypto/ssh SSH client.

GoCryptoClient is intentionally limited in the functionality that it enables, as it is currently intended to be used only for non-interactive command execution.

func NewGoCryptoClient 

func NewGoCryptoClient(signers ...ssh.Signer) (*GoCryptoClient, error)

NewGoCryptoClient creates a new GoCryptoClient.

If no signers are specified, NewGoCryptoClient will use the private key generated by LoadClientKeys.

func (*GoCryptoClient) Command 

func (c *GoCryptoClient) Command(host string, command []string, options *Options) *Cmd

Command implements Client.Command.

func (*GoCryptoClient) Copy 

func (c *GoCryptoClient) Copy(args []string, options *Options) error

Copy implements Client.Copy.

Copy is currently unimplemented, and will always return an error.

type ListMode 

type ListMode bool
var (
	FullKeys     ListMode = true
	Fingerprints ListMode = false
)

type OpenSSHClient 

type OpenSSHClient struct{}

OpenSSHClient is an implementation of Client that uses the ssh and scp executables found in $PATH.

func NewOpenSSHClient 

func NewOpenSSHClient() (*OpenSSHClient, error)

NewOpenSSHClient creates a new OpenSSHClient. If the ssh and scp programs cannot be found in $PATH, then an error is returned.

func (*OpenSSHClient) Command 

func (c *OpenSSHClient) Command(host string, command []string, options *Options) *Cmd

Command implements Client.Command.

func (*OpenSSHClient) Copy 

func (c *OpenSSHClient) Copy(args []string, userOptions *Options) error

Copy implements Client.Copy.

type Options 

type Options struct {
	// contains filtered or unexported fields
}

Options is a client-implementation independent SSH options set.

func (*Options) AllowPasswordAuthentication 

func (o *Options) AllowPasswordAuthentication()

AllowPasswordAuthentication allows the SSH client to prompt the user for a password.

Password authentication is disallowed by default.

func (*Options) EnablePTY 

func (o *Options) EnablePTY()

EnablePTY forces the allocation of a pseudo-TTY.

Forcing a pseudo-TTY is required, for example, for sudo prompts on the target host.

func (*Options) SetHostKeyAlgorithms 

func (o *Options) SetHostKeyAlgorithms(algos ...string)

SetHostKeyAlgorithms sets the host key types that the client will accept from the server, in order of preference. If not specified, the client implementation may choose its own defaults.

func (*Options) SetIdentities 

func (o *Options) SetIdentities(identityFiles ...string)

SetIdentities sets a sequence of paths to private key/identity files to use when attempting login. Client implementations may attempt to use additional identities, but must give preference to the ones specified here.

func (*Options) SetKnownHostsFile 

func (o *Options) SetKnownHostsFile(file string)

SetKnownHostsFile sets the host's fingerprint to be saved in the given file.

Host fingerprints are saved in ~/.ssh/known_hosts by default.

func (*Options) SetPort 

func (o *Options) SetPort(port int)

SetPort sets the SSH server port to connect to.

func (*Options) SetProxyCommand 

func (o *Options) SetProxyCommand(command ...string)

SetProxyCommand sets a command to execute to proxy traffic through.

func (*Options) SetStrictHostKeyChecking 

func (o *Options) SetStrictHostKeyChecking(value StrictHostChecksOption)

SetStrictHostKeyChecking sets the desired host key checking behaviour. It takes one of the StrictHostChecksOption constants. See also EnableStrictHostKeyChecking.

type RunningCmd 

type RunningCmd struct {
	// SSHCmd is the command the was started.
	SSHCmd *Cmd

	// Stdout and Stderr are the output streams the command is using.
	Stdout bytes.Buffer
	Stderr bytes.Buffer
}

RunningCmd represents a command that has been started.

func StartCommandOnMachine 

func StartCommandOnMachine(params ExecParams) (*RunningCmd, error)

StartCommandOnMachine executes the command on the given host. The command is run in a Bash shell over an SSH connection. All output is captured. A RunningCmd is returned that may be used to wait for the command to finish running.

func (*RunningCmd) Wait 

func (cmd *RunningCmd) Wait() (result utilexec.ExecResponse, _ error)

Wait waits for the command to complete and returns the result.

func (*RunningCmd) WaitWithCancel 

func (cmd *RunningCmd) WaitWithCancel(cancel <-chan struct{}) (utilexec.ExecResponse, error)

WaitWithCancel waits for the command to complete and returns the result. If cancel is closed before the result was returned, then it takes longer than the provided timeout then Cancelled is returned.

type StrictHostChecksOption 

type StrictHostChecksOption int

StrictHostChecksOption defines the possible values taken by Option.SetStrictHostKeyChecking(). 

const (
	// StrictHostChecksDefault configures the default,
	// implementation-specific, behaviour.
	//
	// For the OpenSSH implementation, this elides the
	// StrictHostKeyChecking option, which means the
	// user's personal configuration will be used.
	//
	// For the go.crypto implementation, the default is
	// the equivalent of "ask".
	StrictHostChecksDefault StrictHostChecksOption = iota

	// StrictHostChecksNo disables strict host key checking.
	StrictHostChecksNo

	// StrictHostChecksYes enabled strict host key checking
	// enabled. Target hosts must appear in known_hosts file or
	// connections will fail.
	StrictHostChecksYes

	// StrictHostChecksAsk will cause openssh to ask the user about
	// hosts that don't appear in known_hosts file.
	StrictHostChecksAsk
)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.