ssh

Documentation

Overview

Package ssh provides an implementation of the invoke.Environment interface for remote command execution over SSH.

It wraps "golang.org/x/crypto/ssh" and supports:

• Interactive sessions with PTY allocation
• Signal propagation (Interrupt, Kill)
• File transfers (Upload/Download) via SFTP

Usage:

env, err := ssh.New(
    ssh.WithHost("example.com"),
    ssh.WithUser("deploy"),
    ssh.WithKeyPath("~/.ssh/id_ed25519"),
    ssh.WithInsecureSkipVerify(true), // testing only
)

Index

• func DefaultKnownHosts() (ssh.HostKeyCallback, error)
• type Config
  • func NewConfig(host, username string) Config
  • func NewFromSSHConfig(alias, path string) (Config, error)
  • func NewFromSSHConfigReader(alias string, r io.Reader) (Config, error)
  • func (c Config) ToClientConfig() (*ssh.ClientConfig, error)
  • func (c Config) Validate() error
  • func (c Config) WithDefaults() Config
• type Environment
  • func New(opts ...Option) (*Environment, error)
  • func NewFromClient(client *ssh.Client, config Config) *Environment
  • func (e *Environment) Close() error
  • func (e *Environment) Download(ctx context.Context, remotePath, localPath string, opts ...invoke.FileOption) error
  • func (e *Environment) LookPath(ctx context.Context, file string) (string, error)
  • func (e *Environment) Run(ctx context.Context, cmd *invoke.Command) (*invoke.Result, error)
  • func (e *Environment) Start(ctx context.Context, cmd *invoke.Command) (invoke.Process, error)
  • func (e *Environment) TargetOS() invoke.TargetOS
  • func (e *Environment) Upload(ctx context.Context, localPath, remotePath string, opts ...invoke.FileOption) error
• type Option
  • func WithConfig(c Config) Option
  • func WithHost(host string) Option
  • func WithInsecureSkipVerify(skip bool) Option
  • func WithKeyPath(path string) Option
  • func WithPassword(password string) Option
  • func WithPort(port int) Option
  • func WithUser(user string) Option
• type Process
  • func (p *Process) Close() error
  • func (p *Process) Signal(sig os.Signal) error
  • func (p *Process) Wait() (*invoke.Result, error)

Functions

func DefaultKnownHosts

func DefaultKnownHosts() (ssh.HostKeyCallback, error)

DefaultKnownHosts returns a HostKeyCallback that verifies the host key against strict entries in the user's ~/.ssh/known_hosts file.

Types

type Config

type Config struct {
	// Connection details
	Host string // Hostname or IP address
	Port int    // Port number (default 22)
	User string // Username to authenticate as

	// Authentication methods (tried in order)
	PrivateKey     string // PEM encoded private key content (string)
	PrivateKeyPath string // Path to private key file (e.g. "~/.ssh/id_rsa")
	Password       string // Password for authentication (use sparingly)
	UseAgent       bool   // If true, attempt to connect to SSH_AUTH_SOCK

	// Connection settings
	Timeout            time.Duration       // Connection timeout (default 10s)
	HostKeyCheck       ssh.HostKeyCallback // Callback to verify host key. You normally generate this from known_hosts.
	InsecureSkipVerify bool                // If true, disables strict host key checking. Use ONLY for testing.
	OS                 invoke.TargetOS     // Target operating system (default OSLinux). Used for path separators contexts.
}

Config holds all parameters required to establish an SSH connection.

func NewConfig

func NewConfig(host, username string) Config

NewConfig creates a Config with safe defaults. Note: It does NOT set a default HostKeyCheck. You must provide one or set InsecureSkipVerify=true.

func NewFromSSHConfig

func NewFromSSHConfig(alias, path string) (Config, error)

NewFromSSHConfig loads configuration from an SSH config file (e.g. ~/.ssh/config). logic mirrors OpenSSH: reads specific path or default ~/.ssh/config.

func NewFromSSHConfigReader

func NewFromSSHConfigReader(alias string, r io.Reader) (Config, error)

NewFromSSHConfigReader parses configuration config data. It resolves the alias to the actual HostName, User, Port, and IdentityFile.

func (Config) ToClientConfig

func (c Config) ToClientConfig() (*ssh.ClientConfig, error)

ToClientConfig converts the local Config struct to the underlying ssh.ClientConfig.

func (Config) Validate

func (c Config) Validate() error

Validate ensures all required fields are present.

func (Config) WithDefaults

func (c Config) WithDefaults() Config

WithDefaults sets default values for zero-valued fields.

type Environment

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

Environment implements invoke.Environment for SSH execution.

func New

func New(opts ...Option) (*Environment, error)

New establishes a new SSH connection.

func NewFromClient

func NewFromClient(client *ssh.Client, config Config) *Environment

NewFromClient creates a new SSH environment from an existing client.

func (*Environment) Close

func (e *Environment) Close() error

Close closes the underlying SSH connection.

func (*Environment) Download

func (e *Environment) Download(ctx context.Context, remotePath, localPath string, opts ...invoke.FileOption) error

Download copies a remote file/dir to the local path using SFTP.

func (*Environment) LookPath

func (e *Environment) LookPath(ctx context.Context, file string) (string, error)

LookPath searches for an executable on the remote host using 'command -v'.

func (*Environment) Run

func (e *Environment) Run(ctx context.Context, cmd *invoke.Command) (*invoke.Result, error)

Run executes a command synchronously on the remote server.

func (*Environment) Start

func (e *Environment) Start(ctx context.Context, cmd *invoke.Command) (invoke.Process, error)

Start opens a NEW SSH session for the command.

func (*Environment) TargetOS

func (e *Environment) TargetOS() invoke.TargetOS

TargetOS returns the operating system as configured.

func (*Environment) Upload

func (e *Environment) Upload(ctx context.Context, localPath, remotePath string, opts ...invoke.FileOption) error

Upload copies a local file/dir to the remote path using SFTP.

type Option

type Option func(*Config)

Option defines a functional option for the SSH provider.

func WithConfig

func WithConfig(c Config) Option

WithConfig returns an Option that sets multiple fields from a Config struct. Useful for legacy compatibility or bulk configuration.

func WithHost

func WithHost(host string) Option

WithHost sets the target hostname.

func WithInsecureSkipVerify

func WithInsecureSkipVerify(skip bool) Option

WithInsecureSkipVerify enables/disables strict host key checking.

func WithKeyPath

func WithKeyPath(path string) Option

WithKeyPath sets the path to the private key file.

func WithPassword

func WithPassword(password string) Option

WithPassword sets the SSH password.

func WithPort

func WithPort(port int) Option

WithPort sets the SSH port.

func WithUser

func WithUser(user string) Option

WithUser sets the SSH user.

type Process

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

Process implements invoke.Process for SSH execution.

func (*Process) Close

func (p *Process) Close() error

Close terminates the SSH session.

func (*Process) Signal

func (p *Process) Signal(sig os.Signal) error

Signal sends a signal to the remote process.

func (*Process) Wait

func (p *Process) Wait() (*invoke.Result, error)

Wait blocks until the command completes and returns the result.