ssh

Documentation

Overview

Package ssh is a collection of ssh utilities for executing remote ssh commands on hosts.

TODO(jaredbennett/otabek): Move this out from under the wifirouter execs to a general location

Some common, simple bash command functions are included in this package as well, but more complex or uncommon bash command functions should not be included in this package. Rather, those should be closer to their usage and have unit tests.

Index

• func CatFile(ctx context.Context, sshRunner Runner, remoteFilePath string) (string, error)
• func Reboot(ctx context.Context, sshRunner Runner, reconnectDelay time.Duration, ...) error
• func RecreateDir(ctx context.Context, sshRunner Runner, remoteDirPath string) error
• func TestFileExists(ctx context.Context, sshRunner Runner, remoteFilePath string) (bool, error)
• func TestPath(ctx context.Context, sshRunner Runner, testFlag, remotePath string) (bool, error)
• func TryAccess(ctx context.Context, sshRunner Runner) error
• func WgetURL(ctx context.Context, sshRunner Runner, timeout time.Duration, ...) (stdout, stderr string, httpErrorResponseCode int, err error)
• type Access
• type RunResult
• type Runner

Functions

func CatFile

func CatFile(ctx context.Context, sshRunner Runner, remoteFilePath string) (string, error)

CatFile runs `cat <remoteFilePath>` on the host and returns the stdout (the file contents) as a string.

func Reboot

func Reboot(ctx context.Context, sshRunner Runner, reconnectDelay time.Duration, reconnectInterval time.Duration, reconnectTimeout time.Duration) error

Reboot runs `reboot` on the host and then waits for the reboot to complete. The reboot is seen as finished when the device is ssh-able again.

func RecreateDir

func RecreateDir(ctx context.Context, sshRunner Runner, remoteDirPath string) error

RecreateDir will delete (if it exists) and then recreate the directory at remoteDirPath on the remote host.

func TestFileExists

func TestFileExists(ctx context.Context, sshRunner Runner, remoteFilePath string) (bool, error)

TestFileExists checks the remote host for a file's existence at remoteFilePath by running `test -f <remoteFilePath>` on the remote host.

Returns: - (true, nil) if a regular file is found at the given path on the host - (false, nil) if no file was found - (false, non-nil error) if it is unable to determine if the file exists or not

func TestPath

func TestPath(ctx context.Context, sshRunner Runner, testFlag, remotePath string) (bool, error)

TestPath runs `test <testFlag> <remotePath>` on the host and returns the result of the test.

Returns:

• (true, nil) if the run exit code is 0, meaning the test passed
• (false, nil) if the run exit code is 1, meaning the test ran successfully but did not pass
• (false, non-nil error) if the exit code was any other value, meaning that the test did not execute successfully on the remote host

func TryAccess

func TryAccess(ctx context.Context, sshRunner Runner) error

TryAccess will attempt to run a simple bash command, `true`, on the host over ssh to validate that it can connect to the device and run a command.

func WgetURL

func WgetURL(ctx context.Context, sshRunner Runner, timeout time.Duration, downloadURL string, additionalWgetArgs ...string) (stdout, stderr string, httpErrorResponseCode int, err error)

WgetURL will run "wget <downloadURL> [additionalWgetArgs...]" on the host.

On wget run success, just the stdout of wget is returned with an empty stdout, 0 HTTP response code (wget does not provide it on success), and a nil error.

On wget run failure, the stdout, the stderr, the HTTP error response code, and an err is returned. The HTTP error response code will be attempted to be parsed from stderr, but if it is not found it will be -1.

Types

type Access

type Access interface {
	// Run executes command on device by SSH related to resource name.
	Run(ctx context.Context, request *tlw.RunRequest) *tlw.RunResult
}

Access provides a single method for executing ssh commands on devices.

type RunResult

type RunResult interface {
	// GetCommand returns the full command executed on the resource over ssh.
	GetCommand() string
	// GetStdout returns the stdout of the command execution.
	GetStdout() string
	// GetStderr returns the stderr of the command execution.
	GetStderr() string
	// GetExitCode returns the exit code of the command execution.
	GetExitCode() int32
}

RunResult provides functions for retrieving the result of an ssh command call.

type Runner

type Runner interface {
	// Run executes the given command with its arguments on a host over ssh. The
	// stdout of the command execution is returned. If the command returns a
	// non-zero exit code, a non-nil error is returned.
	//
	// Can be used as a components.Runner.
	Run(ctx context.Context, timeout time.Duration, cmd string, args ...string) (string, error)

	// RunInBackground starts to execute the given command with its arguments on a
	// host over ssh, but does so in a background process and does not wait for it
	// to finish before returning. A non-nil error is returned when it fails to
	// start the command execution.
	RunInBackground(ctx context.Context, timeout time.Duration, cmd string, args ...string) error

	// RunForResult executes the given command with its arguments on a host over
	// ssh. A RunResult is returned, which can be used to determine the success
	// of the command execution.
	RunForResult(ctx context.Context, timeout time.Duration, inBackground bool, cmd string, args ...string) RunResult
}

Runner provides functions for executing ssh commands on a host.