ssh

Documentation

Overview

Package ssh allows to manage SSH connections and send commands through them.

Index

• func CheckPrivateSshConnection(t testing.TestingT, publicHost Host, privateHost Host, command string) string
• func CheckPrivateSshConnectionE(t testing.TestingT, publicHost Host, privateHost Host, command string) (string, error)
• func CheckSshCommand(t testing.TestingT, host Host, command string) string
• func CheckSshCommandE(t testing.TestingT, host Host, command string) (string, error)
• func CheckSshCommandWithRetry(t testing.TestingT, host Host, command string, retries int, ...) string
• func CheckSshCommandWithRetryE(t testing.TestingT, host Host, command string, retries int, ...) (string, error)
• func CheckSshConnection(t testing.TestingT, host Host)
• func CheckSshConnectionE(t testing.TestingT, host Host) error
• func CheckSshConnectionWithRetry(t testing.TestingT, host Host, retries int, sleepBetweenRetries time.Duration, ...)
• func CheckSshConnectionWithRetryE(t testing.TestingT, host Host, retries int, sleepBetweenRetries time.Duration, ...) error
• func Close(t testing.TestingT, closeable Closeable, ignoreErrors ...string)
• func FetchContentsOfFile(t testing.TestingT, host Host, useSudo bool, filePath string) string
• func FetchContentsOfFileE(t testing.TestingT, host Host, useSudo bool, filePath string) (string, error)
• func FetchContentsOfFiles(t testing.TestingT, host Host, useSudo bool, filePaths ...string) map[string]string
• func FetchContentsOfFilesE(t testing.TestingT, host Host, useSudo bool, filePaths ...string) (map[string]string, error)
• func NoOpHostKeyCallback(hostname string, remote net.Addr, key ssh.PublicKey) error
• func ScpDirFrom(t testing.TestingT, options ScpDownloadOptions, useSudo bool)
• func ScpDirFromE(t testing.TestingT, options ScpDownloadOptions, useSudo bool) error
• func ScpFileFrom(t testing.TestingT, host Host, remotePath string, localDestination *os.File, ...)
• func ScpFileFromE(t testing.TestingT, host Host, remotePath string, localDestination *os.File, ...) error
• func ScpFileTo(t testing.TestingT, host Host, mode os.FileMode, remotePath, contents string)
• func ScpFileToE(t testing.TestingT, host Host, mode os.FileMode, remotePath, contents string) error
• type Closeable
• type Host
• type JumpHostSession
  • func (jumpHost *JumpHostSession) Cleanup(t testing.TestingT)
• type KeyPair
  • func GenerateRSAKeyPair(t testing.TestingT, keySize int) *KeyPair
  • func GenerateRSAKeyPairE(t testing.TestingT, keySize int) (*KeyPair, error)
• type ScpDownloadOptions
• type SshAgent
  • func NewSshAgent(t testing.TestingT, socketDir string, socketFile string) (*SshAgent, error)
  • func SshAgentWithKeyPair(t testing.TestingT, keyPair *KeyPair) *SshAgent
  • func SshAgentWithKeyPairE(t testing.TestingT, keyPair *KeyPair) (*SshAgent, error)
  • func SshAgentWithKeyPairs(t testing.TestingT, keyPairs []*KeyPair) *SshAgent
  • func SshAgentWithKeyPairsE(t testing.TestingT, keyPairs []*KeyPair) (*SshAgent, error)
  • func (s *SshAgent) SocketFile() string
  • func (s *SshAgent) Stop()
• type SshConnectionOptions
  • func (options *SshConnectionOptions) ConnectionString() string
• type SshSession
  • func (sshSession *SshSession) Cleanup(t testing.TestingT)

Functions

func CheckPrivateSshConnection

func CheckPrivateSshConnection(t testing.TestingT, publicHost Host, privateHost Host, command string) string

CheckPrivateSshConnection attempts to connect to privateHost (which is not addressable from the Internet) via a separate publicHost (which is addressable from the Internet) and then executes "command" on privateHost and returns its output. It is useful for checking that it's possible to SSH from a Bastion Host to a private instance.

func CheckPrivateSshConnectionE

func CheckPrivateSshConnectionE(t testing.TestingT, publicHost Host, privateHost Host, command string) (string, error)

CheckPrivateSshConnectionE attempts to connect to privateHost (which is not addressable from the Internet) via a separate publicHost (which is addressable from the Internet) and then executes "command" on privateHost and returns its output. It is useful for checking that it's possible to SSH from a Bastion Host to a private instance.

func CheckSshCommand

func CheckSshCommand(t testing.TestingT, host Host, command string) string

CheckSshCommand checks that you can connect via SSH to the given host and run the given command. Returns the stdout/stderr.

func CheckSshCommandE

func CheckSshCommandE(t testing.TestingT, host Host, command string) (string, error)

CheckSshCommandE checks that you can connect via SSH to the given host and run the given command. Returns the stdout/stderr.

func CheckSshCommandWithRetry

func CheckSshCommandWithRetry(t testing.TestingT, host Host, command string, retries int, sleepBetweenRetries time.Duration, f ...func(testing.TestingT, Host, string) (string, error)) string

CheckSshCommandWithRetry checks that you can connect via SSH to the given host and run the given command until max retries have been exceeded. Returns the stdout/stderr.

func CheckSshCommandWithRetryE

func CheckSshCommandWithRetryE(t testing.TestingT, host Host, command string, retries int, sleepBetweenRetries time.Duration, f ...func(testing.TestingT, Host, string) (string, error)) (string, error)

func CheckSshConnection

func CheckSshConnection(t testing.TestingT, host Host)

CheckSshConnection checks that you can connect via SSH to the given host and fail the test if the connection fails.

func CheckSshConnectionE

func CheckSshConnectionE(t testing.TestingT, host Host) error

CheckSshConnectionE checks that you can connect via SSH to the given host and return an error if the connection fails.

func CheckSshConnectionWithRetry

func CheckSshConnectionWithRetry(t testing.TestingT, host Host, retries int, sleepBetweenRetries time.Duration, f ...func(testing.TestingT, Host) error)

CheckSshConnectionWithRetry attempts to connect via SSH until max retries has been exceeded and fails the test if the connection fails

func CheckSshConnectionWithRetryE

func CheckSshConnectionWithRetryE(t testing.TestingT, host Host, retries int, sleepBetweenRetries time.Duration, f ...func(testing.TestingT, Host) error) error

CheckSshConnectionWithRetryE attempts to connect via SSH until max retries has been exceeded and returns an error if the connection fails

func Close

func Close(t testing.TestingT, closeable Closeable, ignoreErrors ...string)

Close closes a Closeable.

func FetchContentsOfFile

func FetchContentsOfFile(t testing.TestingT, host Host, useSudo bool, filePath string) string

FetchContentsOfFile connects to the given host via SSH and fetches the contents of the file at the given filePath. If useSudo is true, then the contents will be retrieved using sudo. This method returns the contents of that file.

func FetchContentsOfFileE

func FetchContentsOfFileE(t testing.TestingT, host Host, useSudo bool, filePath string) (string, error)

FetchContentsOfFileE connects to the given host via SSH and fetches the contents of the file at the given filePath. If useSudo is true, then the contents will be retrieved using sudo. This method returns the contents of that file.

func FetchContentsOfFiles

func FetchContentsOfFiles(t testing.TestingT, host Host, useSudo bool, filePaths ...string) map[string]string

FetchContentsOfFiles connects to the given host via SSH and fetches the contents of the files at the given filePaths. If useSudo is true, then the contents will be retrieved using sudo. This method returns a map from file path to contents.

func FetchContentsOfFilesE

func FetchContentsOfFilesE(t testing.TestingT, host Host, useSudo bool, filePaths ...string) (map[string]string, error)

FetchContentsOfFilesE connects to the given host via SSH and fetches the contents of the files at the given filePaths. If useSudo is true, then the contents will be retrieved using sudo. This method returns a map from file path to contents.

func NoOpHostKeyCallback

func NoOpHostKeyCallback(hostname string, remote net.Addr, key ssh.PublicKey) error

NoOpHostKeyCallback is an ssh.HostKeyCallback that does nothing. Only use this when you're sure you don't want to check the host key at all (e.g., only for testing and non-production use cases).

func ScpDirFrom

func ScpDirFrom(t testing.TestingT, options ScpDownloadOptions, useSudo bool)

ScpDirFrom downloads all the files from remotePath on the given host using SCP.

func ScpDirFromE

func ScpDirFromE(t testing.TestingT, options ScpDownloadOptions, useSudo bool) error

ScpDirFromE downloads all the files from remotePath on the given host using SCP and returns an error if the process fails. NOTE: only files within remotePath will be downloaded. This function will not recursively download subdirectories or follow symlinks.

func ScpFileFrom

func ScpFileFrom(t testing.TestingT, host Host, remotePath string, localDestination *os.File, useSudo bool)

ScpFileFrom downloads the file from remotePath on the given host using SCP.

func ScpFileFromE

func ScpFileFromE(t testing.TestingT, host Host, remotePath string, localDestination *os.File, useSudo bool) error

ScpFileFromE downloads the file from remotePath on the given host using SCP and returns an error if the process fails.

func ScpFileTo

func ScpFileTo(t testing.TestingT, host Host, mode os.FileMode, remotePath, contents string)

ScpFileToE uploads the contents using SCP to the given host and fails the test if the connection fails.

func ScpFileToE

func ScpFileToE(t testing.TestingT, host Host, mode os.FileMode, remotePath, contents string) error

ScpFileToE uploads the contents using SCP to the given host and return an error if the process fails.

Types

type Closeable

type Closeable interface {
	Close() error
}

Closeable can be closed.

type Host

type Host struct {
	Hostname    string // host name or ip address
	SshUserName string // user name
	// set one or more authentication methods,
	// the first valid method will be used
	SshKeyPair       *KeyPair  // ssh key pair to use as authentication method (disabled by default)
	SshAgent         bool      // enable authentication using your existing local SSH agent (disabled by default)
	OverrideSshAgent *SshAgent // enable an in process `SshAgent` for connections to this host (disabled by default)
	Password         string    // plain text password (blank by default)
	CustomPort       int       // port number to use to connect to the host (port 22 will be used if unset)
}

Host is a remote host.

type JumpHostSession

type JumpHostSession struct {
	JumpHostClient        *ssh.Client
	HostVirtualConnection net.Conn
	HostConnection        ssh.Conn
}

JumpHostSession is a session with a jump host.

func (*JumpHostSession) Cleanup

func (jumpHost *JumpHostSession) Cleanup(t testing.TestingT)

Cleanup cleans the jump host session up.

type KeyPair

type KeyPair struct {
	PublicKey  string
	PrivateKey string
}

KeyPair is a public and private key pair that can be used for SSH access.

func GenerateRSAKeyPair

func GenerateRSAKeyPair(t testing.TestingT, keySize int) *KeyPair

GenerateRSAKeyPair generates an RSA Keypair and return the public and private keys.

func GenerateRSAKeyPairE

func GenerateRSAKeyPairE(t testing.TestingT, keySize int) (*KeyPair, error)

GenerateRSAKeyPairE generates an RSA Keypair and return the public and private keys.

type ScpDownloadOptions

type ScpDownloadOptions struct {
	FileNameFilters []string //File names to match. May include bash-style wildcards. E.g., *.log.
	MaxFileSizeMB   int      //Don't grab any files > MaxFileSizeMB
	RemoteDir       string   //Copy from this directory on the remote machine
	LocalDir        string   //Copy RemoteDir to this directory on the local machine
	RemoteHost      Host     //Connection information for the remote machine
}

type SshAgent

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

func NewSshAgent

func NewSshAgent(t testing.TestingT, socketDir string, socketFile string) (*SshAgent, error)

Create SSH agent, start it in background and returns control back to the main thread You should stop the agent to cleanup files afterwards by calling `defer s.Stop()`

func SshAgentWithKeyPair

func SshAgentWithKeyPair(t testing.TestingT, keyPair *KeyPair) *SshAgent

Instantiates and returns an in-memory ssh agent with the given KeyPair already added You should stop the agent to cleanup files afterwards by calling `defer sshAgent.Stop()`

func SshAgentWithKeyPairE

func SshAgentWithKeyPairE(t testing.TestingT, keyPair *KeyPair) (*SshAgent, error)

func SshAgentWithKeyPairs

func SshAgentWithKeyPairs(t testing.TestingT, keyPairs []*KeyPair) *SshAgent

func SshAgentWithKeyPairsE

func SshAgentWithKeyPairsE(t testing.TestingT, keyPairs []*KeyPair) (*SshAgent, error)

Instantiates and returns an in-memory ssh agent with the given KeyPair(s) already added You should stop the agent to cleanup files afterwards by calling `defer sshAgent.Stop()`

func (*SshAgent) SocketFile

func (s *SshAgent) SocketFile() string

expose socketFile variable

func (*SshAgent) Stop

func (s *SshAgent) Stop()

Stop and clean up SSH agent

type SshConnectionOptions

type SshConnectionOptions struct {
	Username    string
	Address     string
	Port        int
	AuthMethods []ssh.AuthMethod
	Command     string
	JumpHost    *SshConnectionOptions
}

SshConnectionOptions are the options for an SSH connection.

func (*SshConnectionOptions) ConnectionString

func (options *SshConnectionOptions) ConnectionString() string

ConnectionString returns the connection string for an SSH connection.

type SshSession

type SshSession struct {
	Options  *SshConnectionOptions
	Client   *ssh.Client
	Session  *ssh.Session
	JumpHost *JumpHostSession
	Input    *func(io.WriteCloser)
}

SshSession is a container object for all resources created by an SSH session. The reason we need this is so that we can do a single defer in a top-level method that calls the Cleanup method to go through and ensure all of these resources are released and cleaned up.

func (*SshSession) Cleanup

func (sshSession *SshSession) Cleanup(t testing.TestingT)

Cleanup cleans up an existing SSH session.