Documentation
¶
Overview ¶
Package ssh provides means to communicate with remote host through SSH.
Index ¶
- Constants
- Variables
- func DialProxyCommand(ctx context.Context, hostPort, proxyCommand string) (net.Conn, error)
- func ParseTarget(target string, o *Options) error
- type Cmd
- func (c *Cmd) Abort()
- func (c *Cmd) CombinedOutput(opts ...RunOption) ([]byte, error)
- func (c *Cmd) DumpLog(ctx context.Context) error
- func (c *Cmd) Output(opts ...RunOption) ([]byte, error)
- func (c *Cmd) Run(opts ...RunOption) error
- func (c *Cmd) Start() error
- func (c *Cmd) StderrPipe() (io.ReadCloser, error)
- func (c *Cmd) StdinPipe() (io.WriteCloser, error)
- func (c *Cmd) StdoutPipe() (io.ReadCloser, error)
- func (c *Cmd) Wait(opts ...RunOption) error
- type Conn
- func (s *Conn) Close(ctx context.Context) error
- func (s *Conn) CommandContext(ctx context.Context, name string, args ...string) *Cmd
- func (s *Conn) Dial(addr, net string) (net.Conn, error)
- func (s *Conn) ForwardLocalToRemote(network, localAddr, remoteAddr string, errFunc func(error)) (*Forwarder, error)
- func (s *Conn) ForwardRemoteToLocal(network, remoteAddr, localAddr string, errFunc func(error)) (*Forwarder, error)
- func (s *Conn) GenerateRemoteAddress(port int) (string, error)
- func (s *Conn) ListenTCP(addr *net.TCPAddr) (net.Listener, error)
- func (s *Conn) NewForwarder(localAddr, remoteAddr string, errFunc func(error)) (*Forwarder, error)
- func (s *Conn) Ping(ctx context.Context, timeout time.Duration) error
- type Forwarder
- type Options
- type Platform
- type RunOption
Constants ¶
const DumpLogOnError = exec.DumpLogOnError
DumpLogOnError instructs to dump logs if the executed command fails (i.e., exited with non-zero status code).
Variables ¶
var DefaultPlatform = &Platform{BuildShellCommand: shellCmd}
DefaultPlatform represents a system with a generic POSIX shell.
Functions ¶
func DialProxyCommand ¶
DialProxyCommand creates a new connection using the specified proxy command.
func ParseTarget ¶
ParseTarget parses target (of the form "[<user>@]host[:<port>]") and fills the User, Hostname, and Port fields in o, using reasonable defaults for unspecified values.
Types ¶
type Cmd ¶
type Cmd struct {
// Args holds command line arguments, including the command as Args[0].
Args []string
// Dir specifies the working directory of the command.
// If Dir is the empty string, Run runs the command in the default directory,
// typically the home directory of the SSH user.
Dir string
// Stdin specifies the process's standard input.
Stdin io.Reader
// Stdout specifies the process's standard output.
Stdout io.Writer
// Stderr specifies the process's standard error.
Stderr io.Writer
// contains filtered or unexported fields
}
Cmd represents an external command being prepared or run on a remote host.
This type implements the almost exactly the same interface as Cmd in os/exec.
func (*Cmd) Abort ¶
func (c *Cmd) Abort()
Abort requests to abort the command execution.
This method does not block, but you still need to call Wait. It is safe to call this method while calling Wait/Run/Output/CombinedOutput in another goroutine. After calling this method, Wait/Run/Output/CombinedOutput will return immediately. This method can be called at most once.
func (*Cmd) CombinedOutput ¶
CombinedOutput runs the command and returns its combined standard output and standard error.
The command is aborted when ctx's deadline is reached.
func (*Cmd) DumpLog ¶
DumpLog logs details of the executed external command, including uncaptured output.
This function must be called after Wait.
func (*Cmd) Output ¶
Output runs the command and returns its standard output.
The command is aborted when ctx's deadline is reached.
func (*Cmd) Run ¶
Run starts the specified command and waits for it to complete.
The command is aborted when ctx's deadline is reached.
func (*Cmd) StderrPipe ¶
func (c *Cmd) StderrPipe() (io.ReadCloser, error)
StderrPipe returns a pipe that will be connected to the command's standard error when the command starts.
The returned pipe is closed automatically when the context deadline is reached, Abort is called, or Wait/Run/Output/CombinedOutput sees the command exit. Thus it is incorrect to call Wait while reading from the pipe, or to use StderrPipe with Run/Output/CombinedOutput. See the os/exec documentation for details.
func (*Cmd) StdinPipe ¶
func (c *Cmd) StdinPipe() (io.WriteCloser, error)
StdinPipe returns a pipe that will be connected to the command's standard input when the command starts.
Close the pipe to send EOF to the remote process.
Important difference with os/exec:
The returned pipe is NOT closed automatically. Wait/Run/Output/CombinedOutput may block until you close the pipe explicitly.
func (*Cmd) StdoutPipe ¶
func (c *Cmd) StdoutPipe() (io.ReadCloser, error)
StdoutPipe returns a pipe that will be connected to the command's standard output when the command starts.
The returned pipe is closed automatically when the context deadline is reached, Abort is called, or Wait/Run/Output/CombinedOutput sees the command exit. Thus it is incorrect to call Wait while reading from the pipe, or to use StdoutPipe with Run/Output/CombinedOutput. See the os/exec documentation for details.
func (*Cmd) Wait ¶
Wait waits for the command to exit and waits for any copying to stdin or copying from stdout or stderr to complete.
This method can be called only if the command was started by Start. It is an error to call this method multiple times, but it will not panic as long as it is not called in parallel.
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn represents an SSH connection to another computer.
func New ¶
New establishes an SSH connection to the host described in o. Callers are responsible to call Conn.Close after using it.
func (*Conn) CommandContext ¶
CommandContext returns the Cmd struct to execute the named program with the given arguments.
It is fine to call this method with nil receiver; subsequent method calls will just fail.
func (*Conn) Dial ¶
Dial initiates a connection to the addr from the remote host. The resulting connection has a zero LocalAddr() and RemoteAddr().
func (*Conn) ForwardLocalToRemote ¶
func (s *Conn) ForwardLocalToRemote(network, localAddr, remoteAddr string, errFunc func(error)) (*Forwarder, error)
ForwardLocalToRemote creates a new Forwarder that forwards connections from localAddr to remoteAddr using s. network is passed to net.Listen. Only TCP networks are supported. localAddr is passed to net.Listen and typically takes the form "host:port" or "ip:port". remoteAddr uses the same format but is resolved by the remote SSH server. If non-nil, errFunc will be invoked asynchronously on a goroutine with connection or forwarding errors.
func (*Conn) ForwardRemoteToLocal ¶
func (s *Conn) ForwardRemoteToLocal(network, remoteAddr, localAddr string, errFunc func(error)) (*Forwarder, error)
ForwardRemoteToLocal creates a new Forwarder that forwards connections from DUT to localaddr. network is passed to net.Dial. Only TCP networks are supported. remoteAddr is resolved by the remote SSH server and typically takes the form "host:port" or "ip:port". localAddr takes the same format but is passed to net.Listen on the local machine. If non-nil, errFunc will be invoked asynchronously on a goroutine with connection or forwarding errors.
func (*Conn) GenerateRemoteAddress ¶
GenerateRemoteAddress generates an address corresponding to the same one as we are currently connected to, but on a different port.
func (*Conn) NewForwarder ¶
NewForwarder creates a new Forwarder that forwards connections from localAddr to remoteAddr using s. Deprecated. Use ForwardLocalToRemote instead for naming consistency.
type Forwarder ¶
type Forwarder struct {
// contains filtered or unexported fields
}
Forwarder creates a listener that forwards TCP connections to another host over an already-established SSH connection.
A pictoral explanation:
Local | SSH Host | Remote -----------------------------------+----------------+-------------
(local-to-remote)
[client] <- TCP -> [Forwarder] <- SSH -> [sshd] <- TCP -> [server]
(remote-to-local)
[server] <- TCP -> [Forwarder] <- SSH -> [sshd] <- TCP -> [client]
func (*Forwarder) ListenAddr ¶
ListenAddr returns the address used to listen for connections.
type Options ¶
type Options struct {
// User is the username to user when connecting.
User string
// Hostname is the SSH server's hostname.
Hostname string
// KeyFile is an optional path to an unencrypted SSH private key.
KeyFile string
// KeyDir is an optional path to a directory (typically $HOME/.ssh) containing standard
// SSH keys (id_dsa, id_rsa, etc.) to use if authentication via KeyFile is not accepted.
// Only unencrypted keys are used.
KeyDir string
// ProxyCommand specifies the command to use to connect to the DUT.
ProxyCommand string
// ConnectTimeout contains a timeout for establishing the TCP connection.
ConnectTimeout time.Duration
// ConnectRetries contains the number of times to retry after a connection failure.
// Each attempt waits up to ConnectTimeout.
ConnectRetries int
// ConnectRetryInterval contains the minimum amount of time between connection attempts.
// This can be set to avoid quickly burning through all retries if errors are returned
// immediately (e.g. connection refused while the SSH daemon is restarting).
// The time spent trying to connect counts against this interval.
ConnectRetryInterval time.Duration
// WarnFunc (if non-nil) is used to log non-fatal errors encountered while connecting to the host.
WarnFunc func(string)
// Platform describes the operating system running on the SSH server. This controls how certain
// commands will be executed on the remote system. If nil, assumes a ChromeOS system.
Platform *Platform
}
Options contains options used when connecting to an SSH server.
type Platform ¶
type Platform struct {
// BuildShellCommand builds the shell command required to execute the given command
// in the given directory on the target platform. args[0] is the name of the command
// to be executed. If dir is empty (""), use the default working directory.
BuildShellCommand func(dir string, args []string) string
}
Platform defines platform-specific behaviours for SSH connections.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package linuxssh provides Linux specific operations conducted via SSH TODO(oka): now that this file is not used from framework, simplify the code.
|
Package linuxssh provides Linux specific operations conducted via SSH TODO(oka): now that this file is not used from framework, simplify the code. |