ssh

package module
v2.0.0-beta.2 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

View Source 
var ErrNoAuthMethod = errors.New("no authentication method defined")

ErrNoAuthMethod is returned when no authentication method (key pair, agent, or password) is configured on a Host.

Functions

func CheckPrivateSSHConnectionContext 

func CheckPrivateSSHConnectionContext(t testing.TestingT, ctx context.Context, publicHost *Host, privateHost *Host, command string) string

CheckPrivateSSHConnectionContext 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. This will fail the test if the connection fails. The ctx parameter supports cancellation and timeouts.

func CheckPrivateSSHConnectionContextE 

func CheckPrivateSSHConnectionContextE(t testing.TestingT, ctx context.Context, publicHost *Host, privateHost *Host, command string) (string, error)

CheckPrivateSSHConnectionContextE 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. The ctx parameter supports cancellation and timeouts.

func CheckSSHCommandContext 

func CheckSSHCommandContext(t testing.TestingT, ctx context.Context, host *Host, command string) string

CheckSSHCommandContext checks that you can connect via SSH to the given host and run the given command. Returns the stdout/stderr. This will fail the test if the connection fails. The ctx parameter supports cancellation and timeouts.

func CheckSSHCommandContextE 

func CheckSSHCommandContextE(t testing.TestingT, ctx context.Context, host *Host, command string) (string, error)

CheckSSHCommandContextE checks that you can connect via SSH to the given host and run the given command. Returns the stdout/stderr. The ctx parameter supports cancellation and timeouts.

func CheckSSHCommandWithRetryContext 

func CheckSSHCommandWithRetryContext(t testing.TestingT, ctx context.Context, host *Host, command string, retries int, sleepBetweenRetries time.Duration, f ...func(testing.TestingT, context.Context, *Host, string) (string, error)) string

CheckSSHCommandWithRetryContext 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. This will fail the test if the connection fails. The ctx parameter supports cancellation and timeouts.

func CheckSSHCommandWithRetryContextE 

func CheckSSHCommandWithRetryContextE(t testing.TestingT, ctx context.Context, host *Host, command string, retries int, sleepBetweenRetries time.Duration, f ...func(testing.TestingT, context.Context, *Host, string) (string, error)) (string, error)

CheckSSHCommandWithRetryContextE checks that you can connect via SSH to the given host and run the given command until max retries has been exceeded. Returns an error if the command fails after max retries has been exceeded. The ctx parameter supports cancellation and timeouts.

func CheckSSHConnectionContext 

func CheckSSHConnectionContext(t testing.TestingT, ctx context.Context, host *Host)

CheckSSHConnectionContext checks that you can connect via SSH to the given host. This will fail the test if the connection fails. The ctx parameter supports cancellation and timeouts.

func CheckSSHConnectionContextE 

func CheckSSHConnectionContextE(t testing.TestingT, ctx context.Context, host *Host) error

CheckSSHConnectionContextE checks that you can connect via SSH to the given host and returns an error if the connection fails. The ctx parameter supports cancellation and timeouts.

func CheckSSHConnectionWithRetryContext 

func CheckSSHConnectionWithRetryContext(t testing.TestingT, ctx context.Context, host *Host, retries int, sleepBetweenRetries time.Duration, f ...func(testing.TestingT, context.Context, *Host) error)

CheckSSHConnectionWithRetryContext attempts to connect via SSH until max retries has been exceeded. This will fail the test if the connection fails. The ctx parameter supports cancellation and timeouts.

func CheckSSHConnectionWithRetryContextE 

func CheckSSHConnectionWithRetryContextE(t testing.TestingT, ctx context.Context, host *Host, retries int, sleepBetweenRetries time.Duration, f ...func(testing.TestingT, context.Context, *Host) error) error

CheckSSHConnectionWithRetryContextE attempts to connect via SSH until max retries has been exceeded and returns an error if the connection fails. The ctx parameter supports cancellation and timeouts.

func Close 

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

Close closes a Closeable.

func FetchContentsOfFileContext 

func FetchContentsOfFileContext(t testing.TestingT, ctx context.Context, host *Host, useSudo bool, filePath string) string

FetchContentsOfFileContext 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. Returns the contents of that file. This will fail the test if the connection fails. The ctx parameter supports cancellation and timeouts.

func FetchContentsOfFileContextE 

func FetchContentsOfFileContextE(t testing.TestingT, ctx context.Context, host *Host, useSudo bool, filePath string) (string, error)

FetchContentsOfFileContextE 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. Returns the contents of that file. The ctx parameter supports cancellation and timeouts.

func FetchContentsOfFilesContext 

func FetchContentsOfFilesContext(t testing.TestingT, ctx context.Context, host *Host, useSudo bool, filePaths ...string) map[string]string

FetchContentsOfFilesContext 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. Returns a map from file path to contents. This will fail the test if the connection fails. The ctx parameter supports cancellation and timeouts.

func FetchContentsOfFilesContextE 

func FetchContentsOfFilesContextE(t testing.TestingT, ctx context.Context, host *Host, useSudo bool, filePaths ...string) (map[string]string, error)

FetchContentsOfFilesContextE 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. Returns a map from file path to contents. The ctx parameter supports cancellation and timeouts.

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 SCPDirFromContext 

func SCPDirFromContext(t testing.TestingT, ctx context.Context, options *SCPDownloadOptions, useSudo bool)

SCPDirFromContext downloads all the files from remotePath on the given host using SCP. This will fail the test if the connection fails. The ctx parameter supports cancellation and timeouts.

func SCPDirFromContextE 

func SCPDirFromContextE(t testing.TestingT, ctx context.Context, options *SCPDownloadOptions, useSudo bool) error

SCPDirFromContextE downloads all the files from remotePath on the given host using SCP and returns an error if the process fails. Only files within remotePath will be downloaded. This function will not recursively download subdirectories or follow symlinks. The ctx parameter supports cancellation and timeouts.

func SCPFileFromContext 

func SCPFileFromContext(t testing.TestingT, ctx context.Context, host *Host, remotePath string, localDestination *os.File, useSudo bool)

SCPFileFromContext downloads the file from remotePath on the given host using SCP. This will fail the test if the connection fails. The ctx parameter supports cancellation and timeouts.

func SCPFileFromContextE 

func SCPFileFromContextE(t testing.TestingT, ctx context.Context, host *Host, remotePath string, localDestination *os.File, useSudo bool) error

SCPFileFromContextE downloads the file from remotePath on the given host using SCP and returns an error if the process fails. The ctx parameter supports cancellation and timeouts.

func SCPFileToContext 

func SCPFileToContext(t testing.TestingT, ctx context.Context, host *Host, mode os.FileMode, remotePath, contents string)

SCPFileToContext uploads the contents using SCP to the given host. This will fail the test if the connection fails. The ctx parameter supports cancellation and timeouts.

func SCPFileToContextE 

func SCPFileToContextE(t testing.TestingT, ctx context.Context, host *Host, mode os.FileMode, remotePath, contents string) error

SCPFileToContextE uploads the contents using SCP to the given host and returns an error if the process fails. The ctx parameter supports cancellation and timeouts.

func SaveSSHKeyPair 

func SaveSSHKeyPair(t testing.TestingT, testFolder string, keyPair *KeyPair)

SaveSSHKeyPair serializes and saves an SSH key pair into the given folder. This allows you to create an SSH key pair during setup and to reuse that key pair later during validation and teardown.

The key pair is saved with teststate.SaveRedacted so that KeyPair.PrivateKey is not written to the test log.

Types

type Closeable 

type Closeable interface {
	Close() error
}

Closeable can be closed.

type Host 

type Host struct {
	// SshKeyPair is the SSH key pair to use for authentication. Disabled by default.
	SshKeyPair *KeyPair //nolint:staticcheck,revive // preserving existing field name
	// OverrideSshAgent enables an in-process [SSHAgent] for connections to this host. Disabled by default.
	OverrideSshAgent *SSHAgent //nolint:staticcheck,revive // preserving existing field name
	// Hostname is the host name or IP address.
	Hostname string
	// SshUserName is the SSH user name.
	SshUserName string //nolint:staticcheck,revive // preserving existing field name
	// Password is the plain text password for authentication. Blank by default.
	Password string
	// CustomPort is the port number to use to connect to the host. Port 22 is used if unset.
	CustomPort int
	// SshAgent enables authentication using the existing local SSH agent. Disabled by default.
	SshAgent bool //nolint:staticcheck,revive // preserving existing field name
}

Host is a remote host. Set one or more authentication methods on the host; the first valid method will be used.

func (*Host) GetPort 

func (h *Host) GetPort() int

GetPort returns the port to use for SSH connections. If Host.CustomPort is set, it returns that value; otherwise, it returns the default SSH port 22.

type JumpHostSession 

type JumpHostSession struct {
	// JumpHostClient is the SSH client for the jump host.
	JumpHostClient *ssh.Client
	// HostVirtualConnection is the virtual connection to the target host through the jump host.
	HostVirtualConnection net.Conn
	// HostConnection is the SSH connection to the target host.
	HostConnection ssh.Conn
}

JumpHostSession is a session with a jump host used for tunneling SSH connections.

func (*JumpHostSession) Cleanup 

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

Cleanup cleans the jump host session up.

type KeyPair 

type KeyPair struct {
	// PublicKey is the SSH public key in authorized_keys format.
	PublicKey string
	// PrivateKey is the PEM-encoded SSH private key.
	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.

func LoadSSHKeyPair 

func LoadSSHKeyPair(t testing.TestingT, testFolder string) *KeyPair

LoadSSHKeyPair loads and unserializes an SSH key pair from the given folder. This allows you to reuse an SSH key pair that was created during an earlier setup step in later validation and teardown steps.

type SCPDownloadOptions 

type SCPDownloadOptions struct {
	// RemoteDir is the directory on the remote machine to copy files from.
	RemoteDir string
	// LocalDir is the directory on the local machine to copy files to.
	LocalDir string
	// FileNameFilters are file name patterns to match. May include bash-style wildcards (e.g., *.log).
	FileNameFilters []string
	// RemoteHost is the connection information for the remote machine.
	RemoteHost Host
	// MaxFileSizeMB is the maximum file size in megabytes to download. Files larger than this are skipped.
	MaxFileSizeMB int
}

SCPDownloadOptions configures the parameters for downloading files from a remote host via SCP.

type SSHAgent 

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

SSHAgent is an in-process SSH agent that can be used for SSH authentication in tests.

func NewSSHAgent 

func NewSSHAgent(t testing.TestingT, ctx context.Context, socketDir string, socketFile string) (*SSHAgent, error)

NewSSHAgent creates an SSH agent, starts it in the background, and returns control back to the main thread. You should stop the agent to clean up files afterwards by calling defer s.Stop(). The ctx parameter is used when establishing the Unix socket listener.

func SSHAgentWithKeyPair 

func SSHAgentWithKeyPair(t testing.TestingT, ctx context.Context, keyPair *KeyPair) *SSHAgent

SSHAgentWithKeyPair creates and returns an in-memory SSH agent with the given KeyPair already added. You should stop the agent to clean up files afterwards by calling defer sshAgent.Stop(). This will fail the test if there is an error. The ctx parameter is used when establishing the Unix socket listener.

func SSHAgentWithKeyPairE 

func SSHAgentWithKeyPairE(t testing.TestingT, ctx context.Context, keyPair *KeyPair) (*SSHAgent, error)

SSHAgentWithKeyPairE creates and returns an in-memory SSH agent with the given KeyPair already added. You should stop the agent to clean up files afterwards by calling defer sshAgent.Stop(). The ctx parameter is used when establishing the Unix socket listener.

func SSHAgentWithKeyPairs 

func SSHAgentWithKeyPairs(t testing.TestingT, ctx context.Context, keyPairs []*KeyPair) *SSHAgent

SSHAgentWithKeyPairs creates and returns an in-memory SSH agent with the given KeyPairs already added. You should stop the agent to clean up files afterwards by calling defer sshAgent.Stop(). This will fail the test if there is an error. The ctx parameter is used when establishing the Unix socket listener.

func SSHAgentWithKeyPairsE 

func SSHAgentWithKeyPairsE(t testing.TestingT, ctx context.Context, keyPairs []*KeyPair) (*SSHAgent, error)

SSHAgentWithKeyPairsE creates and returns an in-memory SSH agent with the given KeyPairs already added. You should stop the agent to clean up files afterwards by calling defer sshAgent.Stop(). The ctx parameter is used when establishing the Unix socket listener.

func (*SSHAgent) Agent 

func (s *SSHAgent) Agent() agent.Agent

Agent returns the underlying ssh agent.Agent used by this SSHAgent.

func (*SSHAgent) SocketDir 

func (s *SSHAgent) SocketDir() string

SocketDir returns the path to the directory containing the SSH agent's Unix socket.

func (*SSHAgent) SocketFile 

func (s *SSHAgent) SocketFile() string

SocketFile returns the path to the SSH agent's Unix socket file.

func (*SSHAgent) Stop 

func (s *SSHAgent) Stop()

Stop stops the SSH agent, closes its listener, and removes the socket directory.

type SSHConnectionOptions 

type SSHConnectionOptions struct {
	// JumpHost is the optional jump host connection options for tunneling.
	JumpHost *SSHConnectionOptions
	// Username is the SSH user name.
	Username string
	// Address is the host address.
	Address string
	// Command is the command to run on the remote host.
	Command string
	// AuthMethods are the SSH authentication methods to use.
	AuthMethods []ssh.AuthMethod
	// Port is the SSH port number.
	Port int
}

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 are the SSH connection options.
	Options *SSHConnectionOptions
	// Client is the SSH client.
	Client *ssh.Client
	// Session is the SSH session.
	Session *ssh.Session
	// JumpHost is the optional jump host session for tunneling.
	JumpHost *JumpHostSession
	// Input is an optional function that writes to the session's stdin pipe.
	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.

Source Files

View all Source files

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.