Documentation
¶
Overview ¶
Package ssh provides a rig protocol implementation for SSH connections.
Index ¶
- Variables
- func DefaultPasswordCallback() (string, error)
- func ParseSSHPrivateKey(key []byte, callback PasswordCallback) ([]ssh.AuthMethod, error)
- type Config
- type Connection
- func (c *Connection) Connect(ctx context.Context) error
- func (c *Connection) Dial(network, address string) (net.Conn, error)
- func (c *Connection) Disconnect()
- func (c *Connection) ExecInteractive(ctx context.Context, cmd string, stdin io.Reader, stdout, stderr io.Writer) error
- func (c *Connection) IPAddress() string
- func (c *Connection) IsConnected() bool
- func (c *Connection) IsWindows() bool
- func (c *Connection) Protocol() string
- func (c *Connection) ProtocolName() string
- func (c *Connection) SetDefaults(ctx context.Context)
- func (c *Connection) StartProcess(ctx context.Context, cmd string, stdin io.Reader, stdout, stderr io.Writer) (protocol.Waiter, error)
- func (c *Connection) String() string
- type Option
- type Options
- type PasswordCallback
Constants ¶
This section is empty.
Variables ¶
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.
var ( // ErrChecksumMismatch is returned when the checksum of an uploaded file does not match expectation. ErrChecksumMismatch = errors.New("checksum mismatch") )
Functions ¶
func DefaultPasswordCallback ¶
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.
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 ¶
WithKeepAlive sets the keep-alive interval 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 ¶
NewOptions creates a new Options struct with the given options applied.
type PasswordCallback ¶
PasswordCallback is a function that is called when a passphrase is needed to decrypt a private key.
Source Files
¶
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 |