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.WithDefaultKnownHosts(),
)
Index ¶
- func DefaultKnownHosts() (ssh.HostKeyCallback, error)
- type Config
- type 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 WithDefaultKnownHosts() Option
- func WithHost(host string) Option
- func WithHostKeyCheck(callback ssh.HostKeyCallback) Option
- func WithInsecureSkipVerify(skip bool) Option
- func WithKeyPath(path string) Option
- func WithKnownHosts(path string) Option
- func WithPassword(password string) Option
- func WithPort(port int) Option
- func WithPrivateKey(key string) Option
- func WithTargetOS(os invoke.TargetOS) Option
- func WithTimeout(timeout time.Duration) Option
- func WithUseAgent(use bool) Option
- func WithUser(user string) Option
- type Process
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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.
// contains filtered or unexported fields
}
Config holds all parameters required to establish an SSH connection.
func NewConfig ¶
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 ¶
NewFromSSHConfig loads configuration from an SSH config file (e.g. ~/.ssh/config). logic mirrors OpenSSH: reads specific path or default ~/.ssh/config.
func NewFromSSHConfigReader ¶
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) WithDefaults ¶
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 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 ¶
LookPath searches for an executable on the remote host using 'command -v'.
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 ¶
WithConfig returns an Option that sets multiple fields from a Config struct. Useful for legacy compatibility or bulk configuration.
func WithDefaultKnownHosts ¶
func WithDefaultKnownHosts() Option
WithDefaultKnownHosts sets the host key callback to verify against the user's default known_hosts file.
func WithHostKeyCheck ¶
func WithHostKeyCheck(callback ssh.HostKeyCallback) Option
WithHostKeyCheck sets the host key verification callback.
func WithInsecureSkipVerify ¶
WithInsecureSkipVerify enables/disables strict host key checking. Use only for testing.
func WithKeyPath ¶
WithKeyPath sets the path to the private key file.
func WithKnownHosts ¶
WithKnownHosts sets the host key callback to verify against the given known_hosts file path.
func WithPrivateKey ¶
WithPrivateKey sets the PEM-encoded private key content directly.
func WithTargetOS ¶
WithTargetOS sets the target operating system for path handling.
func WithTimeout ¶
WithTimeout sets the SSH connection timeout.
func WithUseAgent ¶
WithUseAgent enables SSH agent authentication.
Source Files