ssh

README

go-ssh

An SSH client layer for talking to shared-hosting accounts, extracted from rehost.

• Config.Resolve honors ~/.ssh/config (ProxyJump yields an honest error); the auth chain runs agent → identity files → password/keyboard-interactive prompts behind a Prompter interface.
• known_hosts verification with TOFU confirmation; changed keys hard-fail; HostKeyAlgorithms follow what known_hosts already holds for the target.
• Run (non-zero exit is not a Go error), Stream/StreamPipe for long pipelines, OpenSSH keepalives, and Probe — one sentinel-delimited POSIX script (with a sequential fallback for restricted shells) that maps a host's shell, home and tool inventory.
• ShellQuote, exercised by an adversarial round-trip suite through real sh -c.

import ssh "github.com/pietervanleuven/go-ssh"

The transport-free contract — Result, the Runner interface, ShellQuote, FirstLine, and the capability Probe — lives in the remote subpackage. Packages that only consume command output can depend on it alone and stay free of the dial stack; the root package aliases these names, so both import paths name identical types:

import "github.com/pietervanleuven/go-ssh/remote"

Apache-2.0.

Documentation

Overview

Package ssh provides the connection layer to remote hosts: dialing with agent/key/password auth, ~/.ssh/config respect, known_hosts verification, command execution, and the remote capability probe.

Index

• Constants
• func FirstLine(s string) string
• func ProbedTools() []string
• func ShellQuote(s string) string
• type AuthMethod
• type Capabilities
  • func Probe(ctx context.Context, client *Client) (*Capabilities, error)
• type Client
  • func Dial(ctx context.Context, cfg Config, p Prompter) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) RemoteIP() string
  • func (c *Client) Run(ctx context.Context, cmd string) (Result, error)
  • func (c *Client) Stream(ctx context.Context, cmd string, w io.Writer) (Result, error)
  • func (c *Client) StreamPipe(ctx context.Context, cmd string, stdin io.Reader, w io.Writer) (Result, error)
• type Config
  • func (c Config) Addr() string
  • func (c Config) Resolve() (Config, error)
• type Prompter
• type Result
• type Tool

Constants

const DefaultRunTimeout = 10 * time.Minute

DefaultRunTimeout bounds every buffered command (Run): those are bounded by intent — probes, listings, size measurements — and a hung one must not hang a non-interactive run forever. Streamed transfers (Stream) carry no default deadline: dumps and tar pipes legitimately run for hours.

const DefaultTimeout = 15 * time.Second

DefaultTimeout bounds the TCP dial + handshake.

Functions

func FirstLine

func FirstLine(s string) string

FirstLine returns the trimmed first line of command output; see remote.FirstLine.

func ProbedTools

func ProbedTools() []string

ProbedTools returns the canonical display order of probed tools.

func ShellQuote

func ShellQuote(s string) string

ShellQuote makes s survive a POSIX shell unchanged; see remote.ShellQuote.

Types

type AuthMethod

type AuthMethod string

AuthMethod selects how to authenticate. Empty means auto: agent, then default keys, then password prompt.

const (
	AuthAuto     AuthMethod = ""
	AuthAgent    AuthMethod = "agent"
	AuthKey      AuthMethod = "key"
	AuthPassword AuthMethod = "password"
)

type Capabilities

type Capabilities = remote.Capabilities

Capabilities is what a remote host offers. See remote.Capabilities.

func Probe

func Probe(ctx context.Context, client *Client) (*Capabilities, error)

Probe detects the connected host's capabilities — see remote.Probe, which this wraps with the client's own host and user identity.

type Client

type Client struct {

	// Config is the resolved configuration the connection was made with.
	Config Config
	// contains filtered or unexported fields
}

Client is an established SSH connection.

func Dial

func Dial(ctx context.Context, cfg Config, p Prompter) (*Client, error)

Dial resolves cfg against ~/.ssh/config and connects. Host keys are verified against ~/.ssh/known_hosts: unknown hosts go through a TOFU confirmation, changed keys always fail hard.

func (*Client) Close

func (c *Client) Close() error

Close terminates the connection.

func (*Client) RemoteIP

func (c *Client) RemoteIP() string

RemoteIP is the IP address the connection actually reached — the host's real identity even when Config.Host is an alias or CNAME.

func (*Client) Run

func (c *Client) Run(ctx context.Context, cmd string) (Result, error)

Run executes one command in a fresh session. A non-zero exit status is not a Go error — capability probes expect commands to fail; only transport and session failures are returned as errors. Commands are cut off after DefaultRunTimeout (or the caller's earlier deadline).

func (*Client) Stream

func (c *Client) Stream(ctx context.Context, cmd string, w io.Writer) (Result, error)

Stream executes cmd, writing its stdout to w as the data arrives — for payloads (database dumps, tar streams) that must never be buffered whole. Result.Stdout stays empty; stderr is captured for diagnostics. Cancelling ctx closes the session (how a capped measurement stops a stream); the bytes written before that remain valid.

func (*Client) StreamPipe

func (c *Client) StreamPipe(ctx context.Context, cmd string, stdin io.Reader, w io.Writer) (Result, error)

StreamPipe is Stream with the command's stdin fed from a reader — the primitive for relays that pipe bytes *into* a remote process (a tar extraction, a NUL-delimited file list). A nil stdin leaves the remote stdin closed, which is exactly Stream.

type Config

type Config struct {
	Host    string
	Port    int
	User    string
	Auth    AuthMethod
	KeyPath string
	Timeout time.Duration
	// contains filtered or unexported fields
}

Config describes how to reach one host. Host may be a hostname or a ~/.ssh/config alias; zero values are filled by Resolve.

func (Config) Addr

func (c Config) Addr() string

Addr returns the resolved dial address.

func (Config) Resolve

func (c Config) Resolve() (Config, error)

Resolve applies ~/.ssh/config (HostName, Port, User, IdentityFile) and defaults. Explicit Config values always win over ssh_config values.

type Prompter

type Prompter interface {
	// Password asks for a password or key passphrase.
	Password(prompt string) (string, error)
	// ConfirmHostKey asks whether to trust an unknown host key (TOFU).
	ConfirmHostKey(host, keyType, fingerprint string) (bool, error)
}

Prompter supplies the interactive pieces of dialing. A non-TTY run passes an implementation that fails with remediation guidance instead of hanging.

type Result

type Result = remote.Result

Result is the outcome of one remote command. The type lives in the remote subpackage so consumers of command output need not depend on the dial stack; the alias keeps the root API complete and the types identical.

type Tool

type Tool = remote.Tool

Tool is one probed remote binary. It lives in the remote subpackage; this alias keeps the root API complete for callers that already dial here.