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
- type Client
- 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
- 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.
Variables ¶
This section is empty.
Functions ¶
func FirstLine ¶
FirstLine returns the trimmed first line of command output — the useful part of stderr for an error message — or "no error output" when there is none.
func ProbedTools ¶
func ProbedTools() []string
ProbedTools returns the canonical display order of probed tools.
func ShellQuote ¶
ShellQuote wraps s in single quotes, escaping any embedded ones, so it survives a POSIX shell unchanged.
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 struct {
Host string `json:"host"`
User string `json:"user,omitempty"`
Shell string `json:"shell,omitempty"`
Uname string `json:"uname,omitempty"`
Home string `json:"home,omitempty"`
PHPVersion string `json:"php_version,omitempty"`
Tools map[string]Tool `json:"tools"`
}
Capabilities is what a remote host offers. It is the input for the Phase 1 check gate and framework recipes.
func Probe ¶
func Probe(ctx context.Context, client *Client) (*Capabilities, error)
Probe detects the host's capabilities: shell, uname, home, PHP version and tool availability. It prefers a single compound POSIX script (one round trip — shared hosts are slow and may cap sessions) and degrades to one command per session for restricted shells.
func (*Capabilities) Has ¶
func (c *Capabilities) Has(tool string) bool
Has reports whether a tool was found on the host.
func (*Capabilities) Summary ¶
func (c *Capabilities) Summary() string
Summary is a compact one-line host descriptor (shell and PHP) for progress output; the full picture is in the capability report.
func (*Capabilities) Target ¶
func (c *Capabilities) Target() string
Target is the user@host identity of the probed host, or just the host when no user is known. Which sites exist can differ per user (vhost setups), so the user is part of a host's identity in reports.
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 ¶
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) RemoteIP ¶
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 ¶
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 ¶
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.
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.