ssh

Documentation

Index

• type Client
  • func NewClient(cfg *Config) (*Client, error)
  • func (cl *Client) Close() error
  • func (cl *Client) OpenSession(ctx context.Context) (*Session, error)
  • func (cl *Client) Run(ctx context.Context, cmd *command.Command, dst any, opts ...RunOption) (*parser.RawResult, error)
• type Config
  • func NewConfig(user, host string, port int, opts ...ConfigOption) (*Config, error)
  • func (c *Config) ClientConfig() (*ssh.ClientConfig, error)
• type ConfigOption
  • func WithAgentAuth() ConfigOption
  • func WithEnvVars(envVars map[string]string) ConfigOption
  • func WithKeepAlive(keepAlive time.Duration) ConfigOption
  • func WithKeyBytesAuth(keyBytes []byte, passphrase string) ConfigOption
  • func WithKnownHosts(path string) ConfigOption
  • func WithMaxSessions(maxSessions int) ConfigOption
  • func WithPasswordAuth(password string) ConfigOption
  • func WithPort(p int) ConfigOption
  • func WithPrivateKeyPathAuth(path, passphrase string) ConfigOption
  • func WithRetry(count int, interval time.Duration) ConfigOption
  • func WithSudoPassword(password string) ConfigOption
  • func WithTimeout(timeout time.Duration) ConfigOption
  • func WithWorkdir(path string) ConfigOption
• type RunOption
  • func WithEnvVar(key, value string) RunOption
  • func WithStderr(stderr io.Writer) RunOption
  • func WithStdin(stdin io.Reader) RunOption
  • func WithStdout(stdout io.Writer) RunOption
  • func WithStreaming() RunOption
  • func WithoutBuffering() RunOption
• type SCPOption
  • func WithBufferSize(bufSize int) SCPOption
  • func WithScpBinPath(path string) SCPOption
• type SCPTransfer
  • func NewSCPTransfer(client *Client) *SCPTransfer
  • func (t *SCPTransfer) Copy(ctx context.Context, spec *rexec.FileSpec, opts ...SCPOption) error
• type SFTPOption
  • func WithSFTPBufferSize(n int) SFTPOption
• type SFTPTransfer
  • func NewSFTPTransfer(client *Client) *SFTPTransfer
  • func (t *SFTPTransfer) Copy(ctx context.Context, spec *rexec.FileSpec, opts ...SFTPOption) error
• type Session
  • func (w *Session) Close() error

Types

type Client

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

Client runs shell commands over an SSH connection

func NewClient

func NewClient(cfg *Config) (*Client, error)

NewClient dials the SSH server using cfg, retrying on failure, and starts a keepalive loop. Returns an SSH Client or error

func (*Client) Close

func (cl *Client) Close() error

Close shuts down keepalive and closes the SSH connection

func (*Client) OpenSession

func (cl *Client) OpenSession(ctx context.Context) (*Session, error)

OpenSession acquires a session slot, opens a new SSH session, or returns an error

func (*Client) Run

func (cl *Client) Run(ctx context.Context, cmd *command.Command, dst any, opts ...RunOption) (*parser.RawResult, error)

Run executes cmd on the remote host, captures stdout/stderr, exit code, and duration, and applies cmd.Parser to dst if provided

type Config

type Config struct {
	Host string // *remote host IP or hostname
	Port int    // *SSH port number
	User string // *SSH username
	// contains filtered or unexported fields
}

Config holds settings for establishing and managing an SSH connection

func NewConfig

func NewConfig(user, host string, port int, opts ...ConfigOption) (*Config, error)

NewConfig creates a Config with required user, host, port and applies any options. Returns an error if any option fails or required fields are invalid

func (*Config) ClientConfig

func (c *Config) ClientConfig() (*ssh.ClientConfig, error)

ClientConfig builds the underlying *ssh.ClientConfig, gathering auth methods in priority order (agent → keyPath/bytes → password) and setting the Host-key callback

type ConfigOption

type ConfigOption func(*Config) error

ConfigOption customizes SSH Config settings

func WithAgentAuth

func WithAgentAuth() ConfigOption

WithAgentAuth enables SSH agent-based authentication

func WithEnvVars

func WithEnvVars(envVars map[string]string) ConfigOption

WithEnvVars merges provided environment variables into the remote session

func WithKeepAlive

func WithKeepAlive(keepAlive time.Duration) ConfigOption

WithKeepAlive sets the TCP keepalive interval

func WithKeyBytesAuth

func WithKeyBytesAuth(keyBytes []byte, passphrase string) ConfigOption

WithKeyBytesAuth enables private key authentication using in-memory key bytes

func WithKnownHosts

func WithKnownHosts(path string) ConfigOption

WithKnownHosts sets the path to a known_hosts file for host key checking

func WithMaxSessions

func WithMaxSessions(maxSessions int) ConfigOption

WithMaxSessions - set max concurrent sessions for connection. You can see it on host in /etc/ssh/sshd_config. Recommend value between 1 and 4

func WithPasswordAuth

func WithPasswordAuth(password string) ConfigOption

WithPasswordAuth enables password-based SSH authentication

func WithPort

func WithPort(p int) ConfigOption

WithPort overrides the SSH port

func WithPrivateKeyPathAuth

func WithPrivateKeyPathAuth(path, passphrase string) ConfigOption

WithPrivateKeyPathAuth enables private key authentication from a file

func WithRetry

func WithRetry(count int, interval time.Duration) ConfigOption

WithRetry sets connection retry count and interval

func WithSudoPassword

func WithSudoPassword(password string) ConfigOption

WithSudoPassword configures a password for sudo -S on the remote host

func WithTimeout

func WithTimeout(timeout time.Duration) ConfigOption

WithTimeout sets the dial timeout

func WithWorkdir

func WithWorkdir(path string) ConfigOption

WithWorkdir sets the remote working directory

type RunOption

type RunOption func(*runConfig)

RunOption configures a single SSH command execution

func WithEnvVar

func WithEnvVar(key, value string) RunOption

WithEnvVar adds or overrides an environment variable for this run

func WithStderr

func WithStderr(stderr io.Writer) RunOption

WithStderr sets a custom writer for live stderr

func WithStdin

func WithStdin(stdin io.Reader) RunOption

WithStdin sets the input reader for the command

func WithStdout

func WithStdout(stdout io.Writer) RunOption

WithStdout sets a custom writer for live stdout

func WithStreaming

func WithStreaming() RunOption

WithStreaming enables real-time streaming of stdout and stderr as data arrives

func WithoutBuffering

func WithoutBuffering() RunOption

WithoutBuffering disables internal buffering of output, so only provided stdout/stderr writers receive data

type SCPOption

type SCPOption func(config *scpConfig)

SCPOption customizes scpConfig for a transfer

func WithBufferSize

func WithBufferSize(bufSize int) SCPOption

WithBufferSize sets a custom bufio buffer size

func WithScpBinPath

func WithScpBinPath(path string) SCPOption

WithScpBinPath sets a custom scp binary path

type SCPTransfer

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

SCPTransfer implements FileTransfer by piping data through `scp -t`

func NewSCPTransfer

func NewSCPTransfer(client *Client) *SCPTransfer

NewSCPTransfer initializes an SCPTransfer using an SSH client

func (*SCPTransfer) Copy

func (t *SCPTransfer) Copy(ctx context.Context, spec *rexec.FileSpec, opts ...SCPOption) error

Copy uploads spec.Content to the remote host via scp. It ensures the remote directory exists, starts scp in "to" mode, then sends file header, data, and handles acknowledgments

type SFTPOption

type SFTPOption func(*sftpConfig)

SFTPOption customizes SFTP transfer behavior

func WithSFTPBufferSize

func WithSFTPBufferSize(n int) SFTPOption

WithSFTPBufferSize sets the buffer size for io.Copy

type SFTPTransfer

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

SFTPTransfer implements FileTransfer over SSH using the SFTP subsystem

func NewSFTPTransfer

func NewSFTPTransfer(client *Client) *SFTPTransfer

NewSFTPTransfer creates an SFTPTransfer tied to the given SSH client

func (*SFTPTransfer) Copy

func (t *SFTPTransfer) Copy(ctx context.Context, spec *rexec.FileSpec, opts ...SFTPOption) error

Copy uploads spec.Content to spec.TargetDir on the remote host via SFTP. It creates directories, writes the file, and applies permissions

type Session

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

Session wraps gossh.Session to release a session slot when closed

func (*Session) Close

func (w *Session) Close() error

Close closes the SSH session and frees a slot in sessionLimiter