ssh

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
  • func (c *Config) Connection() (protocol.Connection, error)
  • func (c *Config) SetDefaults()
  • func (c *Config) String() string
  • func (c *Config) Validate() error
• type Connection
  • func NewConnection(cfg Config, opts ...Option) (*Connection, error)
  • func (c *Connection) Connect() error
  • func (c *Connection) Dial(network, address string) (net.Conn, error)
  • func (c *Connection) Disconnect()
  • func (c *Connection) ExecInteractive(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) SetDefaults()
  • 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
  • func WithKeepAlive(d time.Duration) Option
  • func WithLogger(l log.Logger) Option
• type Options
  • func NewOptions(opts ...Option) *Options
• type PasswordCallback

Variables

var (

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

var SSHConfigGetAll = ssh_config.GetAll

SSHConfigGetAll by default points to ssh_config package's GetAll() function you can override it with your own implementation for testing purposes.

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:"-"`
	Address              string           `yaml:"address" validate:"required,hostname_rfc1123|ip"`
	User                 string           `yaml:"user" validate:"required" default:"root"`
	Port                 int              `yaml:"port" default:"22" validate:"gt=0,lte=65535"`
	KeyPath              *string          `yaml:"keyPath" validate:"omitempty"`
	Bastion              *Config          `yaml:"bastion,omitempty"`
	PasswordCallback     PasswordCallback `yaml:"-"`

	// 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:"-"`
}

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. Error is currently always nil.

func (*Connection) Connect

func (c *Connection) Connect() 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(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.

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.

func (*Connection) Protocol

func (c *Connection) Protocol() string

Protocol returns the protocol name, "SSH".

func (*Connection) SetDefaults

func (c *Connection) SetDefaults()

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.

type Options

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

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.