ssh

package
v2.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 9, 2026 License: Apache-2.0 Imports: 24 Imported by: 5

Documentation

Overview

Package ssh provides a rig protocol implementation for SSH connections.

Index

Constants

This section is empty.

Variables

View Source
var ConfigParser *sshconfig.Parser

ConfigParser is an instance of rig/v2/sshconfig.Parser - it is exported here for weird design decisions made in rig v0.x and will be removed in rig v2 final.

Setting it to nil disables the ssh config layer completely, including OpenSSH's built-in defaults. To drop only the config files while keeping those defaults, use Config.IgnoreSSHConfig or WithoutSSHConfig instead.

View Source
var (

	// ErrChecksumMismatch is returned when the checksum of an uploaded file does not match expectation.
	ErrChecksumMismatch = errors.New("checksum mismatch")
)

Functions

func DefaultPasswordCallback

func DefaultPasswordCallback() (string, error)

DefaultPasswordCallback is a default implementation for PasswordCallback.

func ParseSSHPrivateKey

func ParseSSHPrivateKey(key []byte, callback PasswordCallback) ([]ssh.AuthMethod, error)

ParseSSHPrivateKey is a convenience utility to parses a private key and return []ssh.AuthMethod to be used in SSH{} AuthMethods field. This way you can avoid importing golang.org/x/crypto/ssh in your code and handle the passphrase prompt in a callback function.

Types

type Config

type Config struct {
	log.LoggerInjectable `yaml:"-" json:"-"`
	Address              string           `` /* 147-byte string literal not displayed */
	User                 string           `` /* 136-byte string literal not displayed */
	Port                 int              `` /* 154-byte string literal not displayed */
	KeyPath              *string          `yaml:"keyPath,omitempty" json:"keyPath,omitempty" validate:"omitempty" jsonschema:"description=Path to SSH private key"`
	Bastion              *Config          `yaml:"bastion,omitempty" json:"bastion,omitempty" jsonschema:"description=Optional bastion host"`
	PasswordCallback     PasswordCallback `yaml:"-" json:"-"`

	// SSHConfigOptions provides supplementary ssh_config options that fill gaps not
	// covered by the native fields above. They take priority over ~/.ssh/config but
	// yield to any native field that is explicitly set. Keys are ssh_config directive
	// names (case-insensitive), e.g. {"Ciphers": "aes128-ctr", "StrictHostKeyChecking": false}.
	// Booleans are accepted for options that take yes/no values. Only options that rig
	// reads from the config are acted upon; others are stored but silently ignored at
	// connection time. An unknown key name is an error.
	// See docs/ssh-config-precedence.md for the full precedence rules.
	// YAML key: options.
	SSHConfigOptions sshconfig.OptionArguments `` /* 127-byte string literal not displayed */

	// IgnoreSSHConfig disables reading the OpenSSH client configuration files
	// (~/.ssh/config and the system-wide ssh_config) when setting up this
	// connection, mirroring "ssh -F none". OpenSSH's built-in defaults and any
	// SSHConfigOptions given above are still applied, so only file-derived
	// settings are dropped.
	//
	// Use this to opt out when a config file cannot be parsed or contains
	// directives that should not influence rig. The setting is inherited by the
	// bastion connection.
	// YAML key: ignoreSSHConfig.
	IgnoreSSHConfig bool `` /* 155-byte string literal not displayed */

	// AuthMethods can be used to pass in a list of crypto/ssh.AuthMethod objects
	// for example to use a private key from memory:
	//   ssh.PublicKeys(privateKey)
	// For convenience, you can use ParseSSHPrivateKey() to parse a private key:
	//   authMethods, err := ssh.ParseSSHPrivateKey(key, rig.DefaultPassphraseCallback)
	AuthMethods []ssh.AuthMethod `yaml:"-" json:"-"`
}

Config describes an SSH connection's configuration.

func (*Config) Connection

func (c *Config) Connection() (protocol.Connection, error)

Connection returns a new Connection object based on the configuration.

func (*Config) SetDefaults

func (c *Config) SetDefaults()

SetDefaults sets the default values for the configuration.

func (*Config) String

func (c *Config) String() string

String returns a string representation of the configuration.

func (*Config) Validate

func (c *Config) Validate() error

Validate returns an error if the configuration is invalid.

type Connection

type Connection struct {
	log.LoggerInjectable `yaml:"-"`
	Config               `yaml:",inline"`
	// contains filtered or unexported fields
}

Connection describes an SSH connection.

func NewConnection

func NewConnection(cfg Config, opts ...Option) (*Connection, error)

NewConnection creates a new SSH connection.

It returns an error when the configuration cannot be resolved: an unrecognized or invalid key in SSHConfigOptions, an ssh config that fails to apply, or a ProxyJump that cannot be parsed. Nothing is dialed here, so a connection it returns has not yet contacted the host.

func (*Connection) Connect

func (c *Connection) Connect(ctx context.Context) error

Connect opens the SSH connection.

func (*Connection) Dial

func (c *Connection) Dial(network, address string) (net.Conn, error)

Dial initiates a connection to the addr from the remote host.

func (*Connection) Disconnect

func (c *Connection) Disconnect()

Disconnect closes the SSH connection.

func (*Connection) ExecInteractive

func (c *Connection) ExecInteractive(ctx context.Context, cmd string, stdin io.Reader, stdout, stderr io.Writer) error

ExecInteractive executes a command on the host and passes stdin/stdout/stderr as-is to the session. The session is closed when ctx is cancelled. Nil streams default to os.Stdin/os.Stdout/os.Stderr.

func (*Connection) IPAddress

func (c *Connection) IPAddress() string

IPAddress returns the connection address.

func (*Connection) IsConnected

func (c *Connection) IsConnected() bool

IsConnected returns true if the connection is open.

func (*Connection) IsWindows

func (c *Connection) IsWindows() bool

IsWindows is true when the host is running windows. The result is cached after the first probe; subsequent calls are O(1). For reliable context propagation, Connect should be called first — detection is also triggered during Connect using the connect context.

func (*Connection) Protocol

func (c *Connection) Protocol() string

Protocol returns the protocol family, "SSH".

func (*Connection) ProtocolName

func (c *Connection) ProtocolName() string

ProtocolName returns the implementation name, "SSH".

func (*Connection) SetDefaults

func (c *Connection) SetDefaults(ctx context.Context)

SetDefaults sets various default values.

func (*Connection) StartProcess

func (c *Connection) StartProcess(ctx context.Context, cmd string, stdin io.Reader, stdout, stderr io.Writer) (protocol.Waiter, error)

StartProcess executes a command on the remote host and uses the passed in streams for stdin, stdout and stderr. It returns a Waiter with a .Wait() function that blocks until the command finishes and returns an error if the exit code is not zero.

func (*Connection) String

func (c *Connection) String() string

String returns the connection's printable name.

type Option

type Option func(*Options)

Option is a function that sets some option on the Options struct.

func WithKeepAlive

func WithKeepAlive(d time.Duration) Option

WithKeepAlive sets the keep-alive interval option.

func WithLogger

func WithLogger(l log.Logger) Option

WithLogger sets the logger option.

func WithoutSSHConfig added in v2.2.0

func WithoutSSHConfig() Option

WithoutSSHConfig disables reading the OpenSSH client configuration files (~/.ssh/config and the system-wide ssh_config), mirroring "ssh -F none". OpenSSH's built-in defaults still apply. This is the functional-option equivalent of setting Config.IgnoreSSHConfig.

type Options

type Options struct {
	log.LoggerInjectable
	KeepAliveInterval *time.Duration
	IgnoreSSHConfig   bool
}

Options for the SSH client.

func NewOptions

func NewOptions(opts ...Option) *Options

NewOptions creates a new Options struct with the given options applied.

type PasswordCallback

type PasswordCallback func() (secret string, err error)

PasswordCallback is a function that is called when a passphrase is needed to decrypt a private key.

Directories

Path Synopsis
Package agent provides a client implementation for the SSH agent.
Package agent provides a client implementation for the SSH agent.
Package hostkey implements a callback for the ssh.ClientConfig.HostKeyCallback
Package hostkey implements a callback for the ssh.ClientConfig.HostKeyCallback

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL