Documentation
¶
Overview ¶
Package ssh executes commands and transfers files on a remote host over SSH. It implements invoke.Environment, verified against the invoketest contract suite.
Commands are delivered to the remote login shell as a single, shell-safe command line (the SSH protocol carries a command string, not an argv), with environment variables sent out of band so they do not appear in the remote process table. Host-key verification is fail-closed: a connection requires known_hosts, an explicit callback, or an explicit insecure override.
Index ¶
- type Config
- type Environment
- func (e *Environment) Capabilities() invoke.Capabilities
- func (e *Environment) Close() error
- func (e *Environment) Download(ctx context.Context, remotePath, localPath string, ...) error
- func (e *Environment) LookPath(ctx context.Context, name string) (string, error)
- func (e *Environment) OS() invoke.TargetOS
- func (e *Environment) Start(ctx context.Context, cmd invoke.Command, stdio invoke.IO) (invoke.Process, error)
- func (e *Environment) Upload(ctx context.Context, localPath, remotePath string, ...) error
- type Option
- func WithAgent() Option
- func WithCommandLineEnv() Option
- func WithHostKeyCallback(cb ssh.HostKeyCallback) Option
- func WithInsecureIgnoreHostKey() Option
- func WithKeepAlive(d time.Duration) Option
- func WithKnownHosts(path string) Option
- func WithPassword(password string) Option
- func WithPort(port int) Option
- func WithPrivateKey(path string) Option
- func WithPrivateKeyPassphrase(passphrase string) Option
- func WithTimeout(d time.Duration) Option
- func WithUser(user string) Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Host is the target hostname or address. Required.
Host string
// Port is the target port; zero means 22.
Port int
// User is the login user; empty means the current OS user.
User string
// Password enables password authentication when non-empty.
Password string
// PrivateKeyPath is a private key file for public-key authentication.
PrivateKeyPath string
// PrivateKeyPassphrase decrypts an encrypted PrivateKeyPath.
PrivateKeyPassphrase string
// UseAgent enables authentication via the SSH agent at SSH_AUTH_SOCK.
UseAgent bool
// HostKeyCallback verifies the server's host key. It is required:
// [New] fails closed if none is provided and no known_hosts source
// is configured. Use [WithKnownHosts], [WithHostKeyCallback], or —
// for tests only — [WithInsecureIgnoreHostKey].
HostKeyCallback ssh.HostKeyCallback
// Timeout bounds connection establishment; zero means 30s.
Timeout time.Duration
// KeepAlive is how often to probe the server so a silently dropped
// connection is discovered. Zero means 30s; negative disables it.
KeepAlive time.Duration
// CommandLineEnv allows environment variables the server refuses to
// accept out of band to be carried on the command line instead. See
// [WithCommandLineEnv] for what that exposes.
CommandLineEnv bool
// contains filtered or unexported fields
}
Config holds the settings for connecting to an SSH target. Callers normally build it with New and the With options rather than by hand; NewFromConfig accepts one directly.
type Environment ¶
type Environment struct {
// contains filtered or unexported fields
}
Environment is a connection to a remote host over SSH.
func New ¶
New connects to host over SSH and returns an Environment for it.
ctx bounds establishing the connection only. It does not govern the Environment afterwards, which lives until Close.
func NewFromConfig ¶
func NewFromConfig(ctx context.Context, cfg *Config) (*Environment, error)
NewFromConfig connects using a Config assembled directly. ctx bounds establishing the connection, as in New.
func (*Environment) Capabilities ¶
func (e *Environment) Capabilities() invoke.Capabilities
Capabilities reports the SSH target's optional features. Terminal allocation is available, the protocol carrying a pseudo-terminal request natively, and SFTP preserves symbolic links.
Signal delivery is declared with a caveat this provider cannot resolve for itself. The protocol carries a signal request, and the servers this library is tested against act on it — a real OpenSSH server and the in-process one, both of which the signal contracts run against. But the request is sent without asking for a reply, there being no answer worth waiting for, so a server that discards it cannot be told apart from one that obeyed. A container can be asked whether it holds a shell, which is why the docker provider conditions this capability on the answer; a server offers nothing equivalent to ask.
A server not known to honor signals can be put to the question directly: run invoketest.Verify against it and the signal contracts report what it actually does, once, rather than every connection paying for a guess.
func (*Environment) Close ¶
func (e *Environment) Close() error
Close closes the SSH connection, terminating processes still running.
func (*Environment) Download ¶
func (e *Environment) Download(ctx context.Context, remotePath, localPath string, opts ...invoke.TransferOption) error
Download copies a remote file or directory tree to the local filesystem over SFTP, with the same semantics as Upload.
func (*Environment) LookPath ¶
LookPath resolves name on the remote host via the shell's command -v.
func (*Environment) OS ¶
func (e *Environment) OS() invoke.TargetOS
OS reports the remote operating system, detected once at connect time.
func (*Environment) Start ¶
func (e *Environment) Start(ctx context.Context, cmd invoke.Command, stdio invoke.IO) (invoke.Process, error)
Start launches cmd on the remote host and returns a handle to it.
func (*Environment) Upload ¶
func (e *Environment) Upload(ctx context.Context, localPath, remotePath string, opts ...invoke.TransferOption) error
Upload copies a local file or directory tree to the remote host over SFTP, with the transfer semantics shared by every provider: atomic temp-and-rename delivery, mode preservation, and the configured symlink and special-file policy.
type Option ¶
type Option func(*Config)
Option configures a Config.
func WithAgent ¶
func WithAgent() Option
WithAgent enables authentication via the running SSH agent.
func WithCommandLineEnv ¶
func WithCommandLineEnv() Option
WithCommandLineEnv allows environment variables to be carried on the remote command line when the server refuses to accept them out of band.
A server accepts only the variables its AcceptEnv setting names, and the stock setting names none. Without this option a refusal fails the command rather than running it without its environment. With it, the refused variables are exported on the command line — where they appear in the remote process table and every account on the host can read them. Do not use it to pass secrets.
func WithHostKeyCallback ¶
func WithHostKeyCallback(cb ssh.HostKeyCallback) Option
WithHostKeyCallback sets the host-key verification callback directly.
func WithInsecureIgnoreHostKey ¶
func WithInsecureIgnoreHostKey() Option
WithInsecureIgnoreHostKey disables host-key verification. It is unsafe against man-in-the-middle attacks and intended only for tests.
func WithKeepAlive ¶
WithKeepAlive sets how often the connection is probed so a silently dropped link is discovered. A non-positive interval disables probing.
func WithKnownHosts ¶
WithKnownHosts verifies the server against the given known_hosts file, and constrains host-key negotiation to the algorithms recorded there for this host so a host known under one key type is not rejected when the server offers another.
func WithPassword ¶
WithPassword enables password authentication.
func WithPrivateKey ¶
WithPrivateKey enables public-key authentication using the key at path.
func WithPrivateKeyPassphrase ¶
WithPrivateKeyPassphrase supplies the passphrase for an encrypted key.
func WithTimeout ¶
WithTimeout sets the connection establishment timeout.
Source Files