sshutil

README

sshutil

Forked from fuchsia's sshutil

Changes

Added:

• Export the underlying ssh.Client's NewSession() method.

License

Original works by The Fuchsia Authors licensed under the terms of hte BSD-style License from the Fuchsia project.

Modifications licensed under the same terms under the terms of the BSD License.

Documentation

Index

• Constants
• func DefaultConnectBackoff() retry.Backoff
• func DefaultSSHConfig(privateKey []byte) (*ssh.ClientConfig, error)
• func DefaultSSHConfigFromSigners(signers ...ssh.Signer) (*ssh.ClientConfig, error)
• func GeneratePrivateKey() ([]byte, error)
• func IsConnectionError(err error) bool
• type Client
  • func NewClient(ctx context.Context, resolver Resolver, config *ssh.ClientConfig, ...) (*Client, error)
  • func (c *Client) Client() *ssh.Client
  • func (c *Client) Close()
  • func (c *Client) ConnectTo(ctx context.Context, resolver Resolver, config *ssh.ClientConfig, ...) (*Client, error)
  • func (c *Client) LocalAddr() net.Addr
  • func (c *Client) NewSFTPClient() (*sftp.Client, error)
  • func (c *Client) Reconnect(ctx context.Context) error
  • func (c *Client) ReconnectWithBackoff(ctx context.Context, backoff retry.Backoff) error
  • func (c *Client) RegisterDisconnectListener(ch chan struct{})
  • func (c *Client) Run(ctx context.Context, command []string, stdout io.Writer, stderr io.Writer) error
  • func (c *Client) Start(ctx context.Context, command []string, stdout io.Writer, stderr io.Writer) (*Session, error)
• type Conn
  • func (c *Conn) Close()
  • func (c *Conn) NewSFTPClient() (*sftp.Client, error)
  • func (c *Conn) RegisterDisconnectListener(ch chan struct{})
  • func (c *Conn) Run(ctx context.Context, command []string, stdout io.Writer, stderr io.Writer) error
  • func (c *Conn) Start(ctx context.Context, command []string, stdout io.Writer, stderr io.Writer) (*Session, error)
• type ConnectionError
  • func (e ConnectionError) Error() string
  • func (e ConnectionError) Unwrap() error
• type ConstantAddrResolver
  • func (a ConstantAddrResolver) Resolve(ctx context.Context) (net.Addr, error)
• type Resolver
• type Session
  • func (s *Session) Close()
  • func (s *Session) Run(ctx context.Context, command []string) error
  • func (s *Session) Start(ctx context.Context, command []string) error
  • func (s *Session) Wait(ctx context.Context) error

Constants

const (
	// Default SSH server port.
	SSHPort = 22

	// Default RSA key size.
	RSAKeySize = 2048
)

Functions

func DefaultConnectBackoff

func DefaultConnectBackoff() retry.Backoff

DefaultConnectBackoff is a sensible default for SSH clients.

func DefaultSSHConfig

func DefaultSSHConfig(privateKey []byte) (*ssh.ClientConfig, error)

DefaultSSHConfig returns a basic SSH client configuration.

func DefaultSSHConfigFromSigners

func DefaultSSHConfigFromSigners(signers ...ssh.Signer) (*ssh.ClientConfig, error)

DefaultSSHConfigFromSigners returns a basic SSH client configuration.

func GeneratePrivateKey

func GeneratePrivateKey() ([]byte, error)

GeneratePrivateKey generates a private SSH key.

func IsConnectionError

func IsConnectionError(err error) bool

IsConnectionError determines whether the given error is a ConnectionError. This is a common check that we include in sshutil to save callers a line of code.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(
	ctx context.Context,
	resolver Resolver,
	config *ssh.ClientConfig,
	connectBackoff retry.Backoff,
) (*Client, error)

NewClient creates a new ssh client to the address.

func (*Client) Client

func (c *Client) Client() *ssh.Client

Client returns the underlying *ssh.Client

func (*Client) Close

func (c *Client) Close()

Close the ssh client connection.

func (*Client) ConnectTo

func (c *Client) ConnectTo(
	ctx context.Context,
	resolver Resolver,
	config *ssh.ClientConfig,
	connectBackoff retry.Backoff,
) (*Client, error)

ConnectTo ...

func (*Client) LocalAddr

func (c *Client) LocalAddr() net.Addr

LocalAddr returns the local address being used by the underlying ssh.Client.

func (*Client) NewSFTPClient

func (c *Client) NewSFTPClient() (*sftp.Client, error)

NewSFTPClient returns an SFTP client that uses the currently underlying ssh.Client. The SFTP client will become unresponsive if the ssh connection is closed and/or refreshed.

func (*Client) Reconnect

func (c *Client) Reconnect(ctx context.Context) error

Reconnect will disconnect and then reconnect the client, using the client's `connectBackoff` to determine the retry strategy.

func (*Client) ReconnectWithBackoff

func (c *Client) ReconnectWithBackoff(ctx context.Context, backoff retry.Backoff) error

ReconnectWithBackoff will disconnect the client from the server if connected, then reconnect to the server, with a retry strategy based on the given backoff.

func (*Client) RegisterDisconnectListener

func (c *Client) RegisterDisconnectListener(ch chan struct{})

RegisterDisconnectListener adds a waiter that gets notified when the ssh client is disconnected.

func (*Client) Run

func (c *Client) Run(ctx context.Context, command []string, stdout io.Writer, stderr io.Writer) error

Run a command to completion on the remote device and write STDOUT and STDERR to the passed in io.Writers.

func (*Client) Start

func (c *Client) Start(ctx context.Context, command []string, stdout io.Writer, stderr io.Writer) (*Session, error)

Start a command on the remote device and write STDOUT and STDERR to the passed in io.Writers

type Conn

type Conn struct {
	*ssh.Client
	// contains filtered or unexported fields
}

Conn is a wrapper around ssh that supports keepalive and auto-reconnection.

func (*Conn) Close

func (c *Conn) Close()

Close the ssh client connections.

func (*Conn) NewSFTPClient

func (c *Conn) NewSFTPClient() (*sftp.Client, error)

NewSFTPClient returns an SFTP client that uses the currently underlying ssh.Client. The SFTP client will become unresponsive if the ssh connection is closed and/or refreshed.

func (*Conn) RegisterDisconnectListener

func (c *Conn) RegisterDisconnectListener(ch chan struct{})

RegisterDisconnectListener adds a waiter that gets notified when the ssh client is disconnected.

func (*Conn) Run

func (c *Conn) Run(ctx context.Context, command []string, stdout io.Writer, stderr io.Writer) error

Run a command to completion on the remote device and write STDOUT and STDERR to the passed in io.Writers.

func (*Conn) Start

func (c *Conn) Start(ctx context.Context, command []string, stdout io.Writer, stderr io.Writer) (*Session, error)

Start a command on the remote device and write STDOUT and STDERR to the passed in io.Writers.

type ConnectionError

type ConnectionError struct {
	Err error
}

ConnectionError is an all-purpose error indicating that a client has become unresponsive.

func (ConnectionError) Error

func (e ConnectionError) Error() string

func (ConnectionError) Unwrap

func (e ConnectionError) Unwrap() error

type ConstantAddrResolver

type ConstantAddrResolver struct {
	Addr net.Addr
}

ConstantAddrResolver allows a constant address to be resolved to itself.

func (ConstantAddrResolver) Resolve

func (a ConstantAddrResolver) Resolve(ctx context.Context) (net.Addr, error)

type Resolver

type Resolver interface {
	Resolve(ctx context.Context) (net.Addr, error)
}

Resolver produces a `net.Addr` for the sshutil connections. It abstracts over how the address is produced in order to support non-DNS based names, such as how Fuchsia devices can be discovered through a MAC-address based name.

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session is a wrapper around ssh.Session that allows operations to be canceled.

func (*Session) Close

func (s *Session) Close()

func (*Session) Run

func (s *Session) Run(ctx context.Context, command []string) error

func (*Session) Start

func (s *Session) Start(ctx context.Context, command []string) error

func (*Session) Wait

func (s *Session) Wait(ctx context.Context) error