gossh

README

Gossh (go-ssh)

Gossh provides a simple set of wrapper functions for interacting with remote servers over SSH.

Below is a sample of the provided functions - see GoDoc for comprehensive docs:

CreateSSHClient - Creates an SSH client using configurable timeouts and deadlines. Keys can be provided inline as well as being automatically sourced from the local SSH agent.

RunRemoteCommand - Runs a command on a remote server using configurable timeouts and deadlines.

RunLocalCommand - Runs a command on the local server (by shelling out, not via SSH).

CopyFileToServer - Copies a file from the local server to a remote server using SCP over SSH.

CopyFileStreamToServer - Copies a file stream from the local server to a remote server using SCP over SSH.

CopyFileFromServer - Copies a file from a remote server to the local server using SCP over SSH.

Documentation

Index

• Constants
• Variables
• func CopyFileFromServer(user string, host string, port uint32, localPath string, remotePath string, ...) error
• func CopyFileStreamToServer(user string, host string, port uint32, contents io.Reader, size int64, ...) error
• func CopyFileToServer(user string, host string, port uint32, localPath string, remotePath string, ...) error
• func CreateSSHClient(user string, host string, port uint32, connectionTimeout time.Duration, ...) (*ssh.Client, net.Conn, error)
• func RunLocalCommand(command string) ([]byte, []byte, error)
• func RunRemoteCommand(user string, host string, port uint32, command string, ...) error

Constants

const (
	// DefaultSSHPort can conveniently be passed as the port argument to functions
	// in this package.
	DefaultSSHPort uint32 = 22
	// DefaultSSHConnectionTimeout can conveniently be passed as the connection
	// timeout argument to functions in this package.
	DefaultSSHConnectionTimeout = time.Second * 30
)

Variables

var (
	// Now can be overridden to supply a custom clock. Useful for tests.
	Now = time.Now
	// SSHAuthSockEnvVarName contains the name of the environment variable that
	// points to the local SSH agent's unix socket.
	SSHAuthSockEnvVarName = "SSH_AUTH_SOCK"
)

Functions

func CopyFileFromServer

func CopyFileFromServer(
	user string,
	host string,
	port uint32,
	localPath string,
	remotePath string,
	perm os.FileMode,
	connectionTimeout time.Duration,
	absoluteDeadline time.Time,
	privateKeys ...[]byte) error

CopyFileFromServer copies file from remotePath on host to localPath over SCP, setting perm on the local file copy.

func CopyFileStreamToServer

func CopyFileStreamToServer(
	user string,
	host string,
	port uint32,
	contents io.Reader,
	size int64,
	perm os.FileMode,
	remotePath string,
	connectionTimeout time.Duration,
	absoluteDeadline time.Time,
	privateKeys ...[]byte) error

CopyFileStreamToServer copies a single file with contents to remotePath on the specified host over SSH using SCP.

func CopyFileToServer

func CopyFileToServer(
	user string,
	host string,
	port uint32,
	localPath string,
	remotePath string,
	connectionTimeout time.Duration,
	absoluteDeadline time.Time,
	privateKeys ...[]byte) error

CopyFileToServer copies a single file from localPath to remotePath on the specified host over SSH using SCP.

func CreateSSHClient

func CreateSSHClient(
	user string,
	host string,
	port uint32,
	connectionTimeout time.Duration,
	absoluteDeadline time.Time,
	privateKeys ...[]byte) (*ssh.Client, net.Conn, error)

CreateSSHClient creates an SSH client that is configured to use the local SSH agent and any specified private keys to facilitate authentication.

func RunLocalCommand

func RunLocalCommand(command string) ([]byte, []byte, error)

RunLocalCommand executes the specified command on the local host's bash shell.

func RunRemoteCommand

func RunRemoteCommand(
	user string,
	host string,
	port uint32,
	command string,
	connectionTimeout time.Duration,
	absoluteDeadline time.Time,
	idleTimeout time.Duration,
	stdOutAndErr chan string,
	privateKeys ...[]byte) error

RunRemoteCommand runs command on host:port as user. stdOutAndErr will be passed a multiplexed stream containing stdout and stderr from the command. This chan MUST be drained or command will deadlock. stdOutAndErr chan will be closed once all data is read or an error occurs connectionTimeout is the maximum amount of time to wait for the TCP connection to establish. absoluteDeadline is the absolute time after which all i/o operations will fail with timeout errors. idleTimeout is the maximum amount of time to wait for activity (e.g. receiving a line on stdout) after which all i/o operations will fail with timeout errors. (non-zero exit code) then an error will be returned. If an error occurs running the command, or the command fails, an error will be returned, otherwise nil will be returned.