sshtools

README

Scylla SSH tools

Package sshtools provides a wrapper around SSH client with the following features:

• Context aware (dial and execution),
• Keepalive enabled,
• Can copy files using SCP.

License

Copyright (C) 2017 ScyllaDB

This project is distributed under the Apache 2.0 license. See the LICENSE file for details. It contains software from:

• Hashicorp Terraform, licensed under the MPL-2 license

Documentation

Index

• func StartKeepalive(client *ssh.Client, interval time.Duration, countMax int, done <-chan struct{})
• type Cmd
  • func (c *Cmd) Wait() error
• type Communicator
  • func NewCommunicator(host string, config Config, dial DialContextFunc, logger Logger) *Communicator
  • func (c *Communicator) Connect(ctx context.Context) (err error)
  • func (c *Communicator) Disconnect()
  • func (c *Communicator) Start(ctx context.Context, cmd *Cmd) error
  • func (c *Communicator) Upload(ctx context.Context, path string, perm os.FileMode, src io.Reader) error
• type Config
  • func DefaultConfig() Config
  • func (c Config) KeepaliveEnabled() bool
  • func (c Config) Validate() (err error)
  • func (c Config) WithIdentityFileAuth(user string, identityFile []byte) (Config, error)
  • func (c Config) WithPasswordAuth(user, passwd string) Config
• type DialContextFunc
  • func ContextDialer(dialer *net.Dialer) DialContextFunc
• type ExitError
  • func (e *ExitError) Error() string
• type Logger

Functions

func StartKeepalive

func StartKeepalive(client *ssh.Client, interval time.Duration, countMax int, done <-chan struct{})

StartKeepalive starts sending server keepalive messages until done channel is closed.

Types

type Cmd

type Cmd struct {
	// Command is the command to run remotely. This is executed as if
	// it were a shell command, so you are expected to do any shell escaping
	// necessary.
	Command string

	// Stdin specifies the process's standard input. If Stdin is nil,
	// the process reads from an empty bytes.Buffer.
	Stdin io.Reader

	// Stdout and Stderr represent the process's standard output and error.
	//
	// If either is nil, it will be set to ioutil.Discard.
	Stdout io.Writer
	Stderr io.Writer
	// contains filtered or unexported fields
}

Cmd represents a remote command being prepared or run.

func (*Cmd) Wait

func (c *Cmd) Wait() error

Wait waits for the remote command completion or cancellation. Wait may return an error from the communicator, or an ExitError if the process exits with a non-zero exit status.

type Communicator

type Communicator struct {

	// OnDial is a listener that may be set to track openning SSH connection to
	// the remote host. It is called for both successful and failed trials.
	OnDial func(host string, err error)
	// OnConnClose is a listener that may be set to track closing of SSH
	// connection.
	OnConnClose func(host string)
	// contains filtered or unexported fields
}

Communicator allows for executing commands on a remote host over SSH, it is not thread safe. New communicator is not connected by default, however, calling Start or Upload on not connected communicator would try to establish SSH connection before executing.

func NewCommunicator

func NewCommunicator(host string, config Config, dial DialContextFunc, logger Logger) *Communicator

func (*Communicator) Connect

func (c *Communicator) Connect(ctx context.Context) (err error)

Connect must be called to connect the communicator to remote host. It can be called multiple times, in that case the current SSH connection is closed and a new connection is established.

func (*Communicator) Disconnect

func (c *Communicator) Disconnect()

Disconnect closes the current SSH connection.

func (*Communicator) Start

func (c *Communicator) Start(ctx context.Context, cmd *Cmd) error

Start starts the specified command but does not wait for it to complete. Each command is executed in a new SSH session. If context is canceled the session is immediately closed and error is returned.

The cmd Wait method will return the exit code and release associated resources once the command exits.

func (*Communicator) Upload

func (c *Communicator) Upload(ctx context.Context, path string, perm os.FileMode, src io.Reader) error

Upload creates a file with a given path and permissions and content on a remote host. If context is canceled the upload is interrupted, file is not saved and error is returned.

type Config

type Config struct {
	ssh.ClientConfig `json:"-" yaml:"-"`
	// Port specifies the port number to connect on the remote host.
	Port int `yaml:"port"`
	// ServerAliveInterval specifies an interval to send keepalive message
	// through the encrypted channel and request a response from the server.
	ServerAliveInterval time.Duration `yaml:"server_alive_interval"`
	// ServerAliveCountMax specifies the number of server keepalive messages
	// which may be sent without receiving any messages back from the server.
	// If this threshold is reached while server keepalive messages are being sent,
	// ssh will disconnect from the server, terminating the session.
	ServerAliveCountMax int `yaml:"server_alive_count_max"`
	// Pty specifies if a pty should be associated with sessions on remote
	// hosts. Enabling pty would make Scylla banner to be printed to commands'
	// stdout.
	Pty bool `yaml:"pty"`
}

Config specifies SSH configuration.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config initialized with default values.

func (Config) KeepaliveEnabled

func (c Config) KeepaliveEnabled() bool

KeepaliveEnabled returns true if SSH keepalive should be enabled.

func (Config) Validate

func (c Config) Validate() (err error)

Validate checks if all the fields are properly set.

func (Config) WithIdentityFileAuth

func (c Config) WithIdentityFileAuth(user string, identityFile []byte) (Config, error)

WithIdentityFileAuth returns a copy of c with added user and identity file authentication method.

func (Config) WithPasswordAuth

func (c Config) WithPasswordAuth(user, passwd string) Config

WithPasswordAuth returns a copy of c with added user and password authentication method.

type DialContextFunc

type DialContextFunc func(ctx context.Context, network, addr string, config *ssh.ClientConfig) (*ssh.Client, error)

DialContextFunc creates SSH connection to host with a given address.

func ContextDialer

func ContextDialer(dialer *net.Dialer) DialContextFunc

ContextDialer returns DialContextFunc based on dialer to make net connections.

type ExitError

type ExitError struct {
	Command    string
	ExitStatus int
	Err        error
}

ExitError is returned by Wait to indicate an error while executing the remote command, or a non-zero exit status.

func (*ExitError) Error

func (e *ExitError) Error() string

type Logger

type Logger interface {
	Println(v ...interface{})
}

Logger is the minimal interface Communicator needs for logging. Note that log.Logger from the standard library implements this interface, and it is easy to implement by custom loggers, if they don't do so already anyway.