ssh

Documentation

Index

• Constants
• func ContextFromNewChannel(nch ssh.NewChannel, opts ...tracing.Option) (context.Context, ssh.NewChannel)
• func ContextFromRequest(req *ssh.Request, opts ...tracing.Option) context.Context
• func NewClientConn(ctx context.Context, conn net.Conn, addr string, config *ssh.ClientConfig, ...) (ssh.Conn, <-chan ssh.NewChannel, <-chan *ssh.Request, error)
• type Channel
  • func NewTraceChannel(ch ssh.Channel, opts ...tracing.Option) *Channel
  • func (c *Channel) SendRequest(ctx context.Context, name string, wantReply bool, payload []byte) (bool, error)
• type Client
  • func Dial(ctx context.Context, network, addr string, config *ssh.ClientConfig, ...) (*Client, error)
  • func NewClient(c ssh.Conn, chans <-chan ssh.NewChannel, reqs <-chan *ssh.Request, ...) *Client
  • func NewClientConnWithDeadline(ctx context.Context, conn net.Conn, addr string, config *ssh.ClientConfig, ...) (*Client, error)
  • func (c *Client) DialContext(ctx context.Context, n, addr string) (net.Conn, error)
  • func (c *Client) NewSession(ctx context.Context) (*Session, error)
  • func (c *Client) OpenChannel(ctx context.Context, name string, data []byte) (*Channel, <-chan *ssh.Request, error)
  • func (c *Client) SendRequest(ctx context.Context, name string, wantReply bool, payload []byte) (bool, []byte, error)
• type Envelope
• type NewChannel
  • func NewTraceNewChannel(nch ssh.NewChannel) *NewChannel
  • func (n NewChannel) ExtraData() []byte
• type Session
  • func (s *Session) CombinedOutput(ctx context.Context, cmd string) ([]byte, error)
  • func (s *Session) Output(ctx context.Context, cmd string) ([]byte, error)
  • func (s *Session) RequestPty(ctx context.Context, term string, h, w int, termmodes ssh.TerminalModes) error
  • func (s *Session) RequestSubsystem(ctx context.Context, subsystem string) error
  • func (s *Session) Run(ctx context.Context, cmd string) error
  • func (s *Session) SendRequest(ctx context.Context, name string, wantReply bool, payload []byte) (bool, error)
  • func (s *Session) Setenv(ctx context.Context, name, value string) error
  • func (s *Session) Shell(ctx context.Context) error
  • func (s *Session) Signal(ctx context.Context, sig ssh.Signal) error
  • func (s *Session) Start(ctx context.Context, cmd string) error
  • func (s *Session) WindowChange(ctx context.Context, h, w int) error

Constants

const (
	// TracingRequest is sent by clients to server to pass along tracing context.
	TracingRequest = "tracing@goteleport.com"

	// TracingChannel is a SSH channel used to indicate that servers support tracing.
	TracingChannel = "tracing"
)

Functions

func ContextFromNewChannel

func ContextFromNewChannel(nch ssh.NewChannel, opts ...tracing.Option) (context.Context, ssh.NewChannel)

ContextFromNewChannel extracts any tracing data provided via an Envelope in the ssh.NewChannel ExtraData. If the ExtraData contains an Envelope, then the context returned will have tracing data populated from the remote tracing context and the ssh.NewChannel wrapped in a TraceCh so that the original ExtraData from the client is exposed instead of the Envelope payload.

func ContextFromRequest

func ContextFromRequest(req *ssh.Request, opts ...tracing.Option) context.Context

ContextFromRequest extracts any tracing data provided via an Envelope in the ssh.Request payload. If the payload contains an Envelope, then the context returned will have tracing data populated from the remote tracing context and the ssh.Request payload will be replaced with the original payload from the client.

func NewClientConn

func NewClientConn(ctx context.Context, conn net.Conn, addr string, config *ssh.ClientConfig, opts ...tracing.Option) (ssh.Conn, <-chan ssh.NewChannel, <-chan *ssh.Request, error)

NewClientConn creates a new SSH client connection that is passed tracing context so that spans may be correlated properly over the ssh connection.

Types

type Channel

type Channel struct {
	ssh.Channel
	// contains filtered or unexported fields
}

Channel is a wrapper around ssh.Channel that adds tracing support.

func NewTraceChannel

func NewTraceChannel(ch ssh.Channel, opts ...tracing.Option) *Channel

NewTraceChannel creates a new Channel.

func (*Channel) SendRequest

func (c *Channel) SendRequest(ctx context.Context, name string, wantReply bool, payload []byte) (bool, error)

SendRequest sends a global request, and returns the reply. If tracing is enabled, the provided payload is wrapped in an Envelope to forward any tracing context.

type Client

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

Client is a wrapper around ssh.Client that adds tracing support.

func Dial

func Dial(ctx context.Context, network, addr string, config *ssh.ClientConfig, opts ...tracing.Option) (*Client, error)

Dial starts a client connection to the given SSH server. It is a convenience function that connects to the given network address, initiates the SSH handshake, and then sets up a Client. For access to incoming channels and requests, use net.Dial with NewClientConn instead.

func NewClient

func NewClient(c ssh.Conn, chans <-chan ssh.NewChannel, reqs <-chan *ssh.Request, opts ...tracing.Option) *Client

NewClient creates a new Client.

The server being connected to is probed to determine if it supports ssh tracing. This is done by attempting to open a TracingChannel channel. If the channel is successfully opened then all payloads delivered to the server will be wrapped in an Envelope with tracing context. All Session and Channel created from the returned Client will honor the clients view of whether they should provide tracing context.

func NewClientConnWithDeadline

func NewClientConnWithDeadline(ctx context.Context, conn net.Conn, addr string, config *ssh.ClientConfig, opts ...tracing.Option) (*Client, error)

NewClientConnWithDeadline establishes new client connection with specified deadline

func (*Client) DialContext

func (c *Client) DialContext(ctx context.Context, n, addr string) (net.Conn, error)

DialContext initiates a connection to the addr from the remote host. The resulting connection has a zero LocalAddr() and RemoteAddr().

func (*Client) NewSession

func (c *Client) NewSession(ctx context.Context) (*Session, error)

NewSession creates a new SSH session that is passed tracing context so that spans may be correlated properly over the ssh connection.

func (*Client) OpenChannel

func (c *Client) OpenChannel(ctx context.Context, name string, data []byte) (*Channel, <-chan *ssh.Request, error)

OpenChannel tries to open a channel. If tracing is enabled, the provided payload is wrapped in an Envelope to forward any tracing context.

func (*Client) SendRequest

func (c *Client) SendRequest(ctx context.Context, name string, wantReply bool, payload []byte) (bool, []byte, error)

SendRequest sends a global request, and returns the reply. If tracing is enabled, the provided payload is wrapped in an Envelope to forward any tracing context.

type Envelope

type Envelope struct {
	PropagationContext tracing.PropagationContext
	Payload            []byte
}

Envelope wraps the payload of all ssh messages with tracing context. Any servers that reply to a TracingChannel will attempt to parse the Envelope for all received requests and ensure that the original payload is provided to the handlers.

type NewChannel

type NewChannel struct {
	ssh.NewChannel
	Envelope Envelope
}

NewChannel is a wrapper around ssh.NewChannel that allows an Envelope to be provided to new channels.

func NewTraceNewChannel

func NewTraceNewChannel(nch ssh.NewChannel) *NewChannel

NewTraceNewChannel wraps the ssh.NewChannel in a new NewChannel

The provided ssh.NewChannel will have any Envelope provided via ExtraData extracted so that the original payload can be provided to callers of NewCh.ExtraData.

func (NewChannel) ExtraData

func (n NewChannel) ExtraData() []byte

ExtraData returns the arbitrary payload for this channel, as supplied by the client. This data is specific to the channel type.

type Session

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

Session is a wrapper around ssh.Session that adds tracing support

func (*Session) CombinedOutput

func (s *Session) CombinedOutput(ctx context.Context, cmd string) ([]byte, error)

CombinedOutput runs cmd on the remote host and returns its combined standard output and standard error.

func (*Session) Output

func (s *Session) Output(ctx context.Context, cmd string) ([]byte, error)

Output runs cmd on the remote host and returns its standard output.

func (*Session) RequestPty

func (s *Session) RequestPty(ctx context.Context, term string, h, w int, termmodes ssh.TerminalModes) error

RequestPty requests the association of a pty with the session on the remote host.

func (*Session) RequestSubsystem

func (s *Session) RequestSubsystem(ctx context.Context, subsystem string) error

RequestSubsystem requests the association of a subsystem with the session on the remote host. A subsystem is a predefined command that runs in the background when the ssh session is initiated.

func (*Session) Run

func (s *Session) Run(ctx context.Context, cmd string) error

Run runs cmd on the remote host. Typically, the remote server passes cmd to the shell for interpretation. A Session only accepts one call to Run, Start, Shell, Output, or CombinedOutput.

The returned error is nil if the command runs, has no problems copying stdin, stdout, and stderr, and exits with a zero exit status.

If the remote server does not send an exit status, an error of type *ExitMissingError is returned. If the command completes unsuccessfully or is interrupted by a signal, the error is of type *ExitError. Other error types may be returned for I/O problems.

func (*Session) SendRequest

func (s *Session) SendRequest(ctx context.Context, name string, wantReply bool, payload []byte) (bool, error)

SendRequest sends an out-of-band channel request on the SSH channel underlying the session.

func (*Session) Setenv

func (s *Session) Setenv(ctx context.Context, name, value string) error

Setenv sets an environment variable that will be applied to any command executed by Shell or Run.

func (*Session) Shell

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

Shell starts a login shell on the remote host. A Session only accepts one call to Run, Start, Shell, Output, or CombinedOutput.

func (*Session) Signal

func (s *Session) Signal(ctx context.Context, sig ssh.Signal) error

Signal sends the given signal to the remote process. sig is one of the SIG* constants.

func (*Session) Start

func (s *Session) Start(ctx context.Context, cmd string) error

Start runs cmd on the remote host. Typically, the remote server passes cmd to the shell for interpretation. A Session only accepts one call to Run, Start or Shell.

func (*Session) WindowChange

func (s *Session) WindowChange(ctx context.Context, h, w int) error

WindowChange informs the remote host about a terminal window dimension change to h rows and w columns.