sshutil

Documentation

Index

• Variables
• func CloseAgent()
• type Client
  • func Dial(host string, timeout time.Duration) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Exec(cmd string) (stdout, stderr []byte, exitCode int, err error)
  • func (c *Client) ExecInteractive(cmd string, stdin io.Reader, stdout, stderr io.Writer) (exitCode int, err error)
  • func (c *Client) ExecPTY(cmd string, stdout, stderr io.Writer) (exitCode int, err error)
  • func (c *Client) ExecStream(cmd string, stdout, stderr io.Writer) (exitCode int, err error)
  • func (c *Client) ExecStreamContext(ctx context.Context, cmd string, stdout, stderr io.Writer) (exitCode int, err error)
  • func (c *Client) GetAddress() string
  • func (c *Client) GetHost() string
  • func (c *Client) NewSession() (Session, error)
  • func (c *Client) SendRequest(name string, wantReply bool, payload []byte) (bool, []byte, error)
  • func (c *Client) Shell(stdin io.Reader, stdout, stderr io.Writer) error
• type EncryptedKeyError
  • func (e *EncryptedKeyError) Error() string
• type HostKeyMismatchError
  • func (e *HostKeyMismatchError) Error() string
  • func (e *HostKeyMismatchError) Suggestion() string
• type SSHClient
• type SSHHostEntry
  • func FilterHostsWithKeys(hosts []SSHHostEntry) []SSHHostEntry
  • func ParseSSHConfig() ([]SSHHostEntry, error)
  • func ParseSSHConfigFile(configPath string) ([]SSHHostEntry, error)
  • func (h SSHHostEntry) Description() string
  • func (h SSHHostEntry) HasIdentityFile() bool
• type Session

Variables

var StrictHostKeyChecking = true

StrictHostKeyChecking controls host key verification behavior. When true (default), host keys are verified against ~/.ssh/known_hosts. When false, host key verification is skipped (insecure, for CI/automation).

var WarningHandler func(message string)

WarningHandler is a function that handles warning messages. If nil, warnings are printed to stderr via log.Printf.

Functions

func CloseAgent

func CloseAgent()

CloseAgent closes all SSH agent connections (both default and per-host). This should be called when the application is shutting down.

Types

type Client

type Client struct {
	*ssh.Client
	Host    string // The original host/alias used to connect
	Address string // The resolved address (host:port)
}

Client wraps an SSH connection with additional metadata.

func Dial

func Dial(host string, timeout time.Duration) (*Client, error)

Dial establishes an SSH connection to the specified host. The host can be:

• An SSH config alias (e.g., "myserver")
• A hostname (e.g., "192.168.1.100")
• A user@hostname (e.g., "user@192.168.1.100")
• A hostname:port (e.g., "192.168.1.100:2222")

Connection settings are resolved from ~/.ssh/config when available.

func (*Client) Close

func (c *Client) Close() error

Close closes the SSH connection.

func (*Client) Exec

func (c *Client) Exec(cmd string) (stdout, stderr []byte, exitCode int, err error)

Exec runs a command on the remote host and returns the output. Returns stdout, stderr, exit code, and any error. Exit code is -1 if the command couldn't be executed at all.

func (*Client) ExecInteractive

func (c *Client) ExecInteractive(cmd string, stdin io.Reader, stdout, stderr io.Writer) (exitCode int, err error)

ExecInteractive runs a command with full stdin/stdout/stderr handling. This allows for interactive commands where input is needed.

func (*Client) ExecPTY

func (c *Client) ExecPTY(cmd string, stdout, stderr io.Writer) (exitCode int, err error)

ExecPTY runs a command with a pseudo-terminal allocated. This is useful for commands that expect an interactive terminal. Returns the exit code and any error.

func (*Client) ExecStream

func (c *Client) ExecStream(cmd string, stdout, stderr io.Writer) (exitCode int, err error)

ExecStream runs a command and streams output to the provided writers. Returns the exit code and any error. Exit code is -1 if the command couldn't be executed at all.

func (*Client) ExecStreamContext

func (c *Client) ExecStreamContext(ctx context.Context, cmd string, stdout, stderr io.Writer) (exitCode int, err error)

ExecStreamContext runs a command with context cancellation support. When the context is cancelled, SIGINT is sent to the remote process. Returns the exit code and any error. Exit code is -1 if the command couldn't be executed at all.

func (*Client) GetAddress

func (c *Client) GetAddress() string

GetAddress returns the resolved host:port address.

func (*Client) GetHost

func (c *Client) GetHost() string

GetHost returns the original host/alias used to connect.

func (*Client) NewSession

func (c *Client) NewSession() (Session, error)

NewSession creates a new SSH session. This satisfies the SSHClient interface for liveness checks. Note: The exec methods use c.Client.NewSession() directly to get the full *ssh.Session.

func (*Client) SendRequest

func (c *Client) SendRequest(name string, wantReply bool, payload []byte) (bool, []byte, error)

SendRequest sends a global request on the SSH connection. This is a lightweight way to check connection liveness without the overhead of creating a new session (~100-200ms savings).

func (*Client) Shell

func (c *Client) Shell(stdin io.Reader, stdout, stderr io.Writer) error

Shell starts an interactive shell session. The caller is responsible for handling stdin/stdout/stderr.

type EncryptedKeyError

type EncryptedKeyError struct {
	Path string
}

EncryptedKeyError is returned when an SSH key requires a passphrase.

func (*EncryptedKeyError) Error

func (e *EncryptedKeyError) Error() string

type HostKeyMismatchError

type HostKeyMismatchError struct {
	Hostname     string
	ReceivedType string
	KnownHosts   string
	Want         []knownhosts.KnownKey
}

HostKeyMismatchError provides helpful context when known_hosts verification fails.

func (*HostKeyMismatchError) Error

func (e *HostKeyMismatchError) Error() string

func (*HostKeyMismatchError) Suggestion

func (e *HostKeyMismatchError) Suggestion() string

Suggestion returns actionable steps to fix the host key mismatch.

type SSHClient

type SSHClient interface {
	// Exec runs a command and returns stdout, stderr, and exit code.
	// Exit code is -1 if the command couldn't be executed at all.
	// A non-zero exit code with nil error means the command ran but failed.
	Exec(cmd string) (stdout, stderr []byte, exitCode int, err error)

	// ExecStream runs a command and streams output to the provided writers.
	// Returns the exit code and any error.
	ExecStream(cmd string, stdout, stderr io.Writer) (exitCode int, err error)

	// ExecStreamContext runs a command with context cancellation support.
	// When the context is cancelled, SIGINT is sent to the remote process.
	// Returns the exit code and any error.
	ExecStreamContext(ctx context.Context, cmd string, stdout, stderr io.Writer) (exitCode int, err error)

	// Close closes the SSH connection.
	Close() error

	// GetHost returns the original host/alias used to connect.
	GetHost() string

	// GetAddress returns the resolved host:port address.
	GetAddress() string

	// NewSession creates a new SSH session for command execution or liveness checks.
	// The returned session should be closed after use.
	NewSession() (Session, error)

	// SendRequest sends a global request on the SSH connection.
	// Used for lightweight operations like keep-alive checks without creating a session.
	// Returns whether the request was accepted, the response payload, and any error.
	SendRequest(name string, wantReply bool, payload []byte) (bool, []byte, error)
}

SSHClient defines the interface for SSH command execution. Both the real Client and mock implementations satisfy this interface.

This interface enables testing of SSH-dependent code without requiring actual SSH connections. The mock implementation provides a virtual filesystem that responds realistically to common shell commands.

type SSHHostEntry

type SSHHostEntry struct {
	Alias        string // The Host pattern (alias)
	Hostname     string // The HostName value (actual host to connect to)
	User         string // The User value
	Port         string // The Port value
	IdentityFile string // The IdentityFile value
}

SSHHostEntry represents a parsed host entry from SSH config.

func FilterHostsWithKeys

func FilterHostsWithKeys(hosts []SSHHostEntry) []SSHHostEntry

FilterHostsWithKeys returns only hosts that have identity files configured or where default SSH keys exist.

func ParseSSHConfig

func ParseSSHConfig() ([]SSHHostEntry, error)

ParseSSHConfig parses ~/.ssh/config and returns all host entries. It filters out wildcards and includes hosts, returning only concrete host aliases.

func ParseSSHConfigFile

func ParseSSHConfigFile(configPath string) ([]SSHHostEntry, error)

ParseSSHConfigFile parses the specified SSH config file.

func (SSHHostEntry) Description

func (h SSHHostEntry) Description() string

Description returns a user-friendly description of the host.

func (SSHHostEntry) HasIdentityFile

func (h SSHHostEntry) HasIdentityFile() bool

HasIdentityFile returns true if the host has an IdentityFile configured or if default keys exist in ~/.ssh/

type Session

type Session interface {
	io.Closer
}

Session represents an SSH session that can be closed. This is a minimal interface for the ssh.Session type.