Documentation
¶
Overview ¶
Package sshx: SSH readiness probing and client invocation for forks.
Index ¶
- func Args(port int, user, key string) []string
- func Dial(port int, user, password, keyPath string) (*ssh.Client, error)
- func EncodePowerShell(command string) string
- func EnsureKey(path, comment string) (string, error)
- func Exec(port int, user, password, keyPath, command string) (int, error)
- func ExecScript(ctx context.Context, timeout time.Duration, port int, ...) (int, error)
- func ExecStreams(port int, user, password, keyPath, command string, stdout, stderr io.Writer) (int, error)
- func PullFrom(port int, user, password, keyPath, remote, local string, ...) error
- func PushTo(port int, user, password, keyPath, local, remote string, ...) error
- func QuotePOSIX(argv []string) string
- func QuotePOSIXArg(a string) string
- func QuotePowerShell(argv []string) string
- func QuotePowerShellArg(a string) string
- func WaitReady(port int, timeout time.Duration) error
- type OutputBuffer
- type TimeoutError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Args ¶
Args builds ssh client arguments for a fork. Host keys rotate with every fork, so strict checking and known-hosts persistence are disabled. UserKnownHostsFile=NUL is the Windows null device (host is Windows-only for now).
func Dial ¶ added in v0.1.2
Dial opens an SSH connection to a fork's forwarded port on loopback. The Go client rather than ssh.exe, so password auth works non-interactively. Host key checking is off: fork host keys rotate on every clone.
func EncodePowerShell ¶ added in v0.1.2
EncodePowerShell encodes a command for `powershell -EncodedCommand`: UTF-16LE, then base64. It is the only way to hand PowerShell a command through a shell that parses the line first and cannot be quoted out of it - cmd.exe splits on & and | inside every quoting it has. Base64 has neither, nor a space, quote or dollar, so the line survives any shell on the way.
func EnsureKey ¶ added in v0.1.2
EnsureKey returns the authorized_keys line for the ed25519 key at path, generating the pair and writing path and path+".pub" if it is not there yet. An existing key is reused rather than regenerated: a fresh one would lock terrarium out of the goldens the old one was installed in.
Both the cloud-init seed and the Windows unattended install put the public half in the guest this way, so they share the generator: every golden terrarium builds ends up key-based, whatever the OS.
func ExecScript ¶ added in v0.1.2
func ExecScript(ctx context.Context, timeout time.Duration, port int, user, password, keyPath, command string, stdin io.Reader, stdout, stderr io.Writer) (int, error)
ExecScript is ExecStreams with a ceiling on how long to wait and an optional script fed to the command's own stdin, for the shells that read one there: `sh -s`, `powershell -Command -`. That is the one way to hand a guest a multi-line script without it passing through anybody's quoting on the way.
Whatever the command printed before the deadline has already been written to stdout and stderr, which is the only thing left to go on when it hangs.
func ExecStreams ¶
func ExecStreams(port int, user, password, keyPath, command string, stdout, stderr io.Writer) (int, error)
ExecStreams is Exec with the guest's output redirected, so callers that need to inspect it (first-boot orchestration) can.
func PullFrom ¶ added in v0.1.2
func PullFrom(port int, user, password, keyPath, remote, local string, recursive, parents bool) error
PullFrom copies a guest file or directory to the host over its SSH port.
func PushTo ¶ added in v0.1.2
PushTo copies a host file or directory into a guest over its SSH port.
func QuotePOSIX ¶ added in v0.1.2
QuotePOSIX joins argv into the single command string an SSH session carries, quoting each element so the guest's shell rebuilds the exact argv. Without it the guest re-splits arguments on spaces and reads |, $, backticks and globs inside them as its own syntax: `bash -c 'a; b'` word-splits and the | in a sed expression becomes a remote pipe. Shell features are still available, they just have to be asked for - as an argument to `bash -c` rather than by accident.
func QuotePOSIXArg ¶ added in v0.1.2
QuotePOSIXArg is QuotePowerShellArg for a POSIX shell.
func QuotePowerShell ¶ added in v0.1.2
QuotePowerShell joins argv into the one command string an SSH session carries to a guest whose default shell is PowerShell. Single quotes are the only PowerShell quoting that expands nothing at all - $var, backticks and $(...) stay literal inside them - and a single quote is written twice to spell itself.
A quoted first element would be a string expression rather than a command, so it gets the call operator: `& 'C:\Program Files\x.exe'` runs the program, 'C:\Program Files\x.exe' on its own just prints the path.
func QuotePowerShellArg ¶ added in v0.1.2
QuotePowerShellArg quotes one whole string as a single PowerShell argument. It is for the wrappers that build a command line by hand - `cmd /c <line>` - where the line is one argument to a program, not an argv PowerShell should re-split.
Types ¶
type OutputBuffer ¶
type OutputBuffer struct {
// contains filtered or unexported fields
}
OutputBuffer collects a command's output. The ssh client copies stdout and stderr on separate goroutines, so passing one plain bytes.Buffer as both would race.
func (*OutputBuffer) String ¶
func (b *OutputBuffer) String() string
String is safe to call while the command is still running.
type TimeoutError ¶
TimeoutError reports a command that outlived its deadline. The SSH session cannot be cancelled from the client, so the guest is still running it.
func (*TimeoutError) Error ¶
func (e *TimeoutError) Error() string
Source Files