SshSession

An SSH connection to one server, used to run commands. Each command runs in its own channel, so state such as the working directory or exported variables does not carry over to the next command; chain commands in one call ("cd /opt/app && ls"). If the connection was closed or dropped, the next command reconnects.

• Kind Object
• Library Ssh
• Category Remote & Infrastructure
• Functions 4

How to get one

1. Ssh .newSession()
2. SshSession

local session = Ssh.newSession(username, password, host)

Returned by

• Ssh.newSession()
• Ssh.newSessionWithKey()

Functions

• exec string Runs a command on the server and returns its output as a string.
• execTrimmed string Same as exec(command, true): runs the command and returns the output without leading and trailing whitespace (such as the final newline), which is what you want for single values.
• run SshResult Runs a command and returns a table with its exit code and both output streams, for scripts that need to know whether the command succeeded.
• close self Closes the connection to the server.

exec()

session.exec(command: string)→stringsession.exec(command: string, trimOutput: boolean)→stringsession.exec(command: string, trimOutput: boolean, timeout: number)→string

Runs a command on the server and returns its output as a string. The call waits until the command has finished, for at most the timeout (300 seconds unless you pass another number of seconds as third argument); a command that runs longer is stopped and raises "Command timed out". The output is the standard output; when that is empty, the standard error output is returned instead. The exit code is not returned here: use `run` when you need it. Raises "Failed to execute command: ... Error: ..." when connecting, logging in or running fails.

Parameters

command string

Command line, run by the user's shell on the server

trimOutput boolean optional

true to remove leading and trailing whitespace from the output; default false

timeout number optional

Time limit in seconds; default 300

Returns

string Standard output of the command, or standard error when stdout is empty

Example

local listing = session.exec("ls -1 /var/backups")
local host = session.exec("hostname", true)
local report = session.exec("./long-report.sh", true, 900)

execTrimmed()

session.execTrimmed(command: string)→stringsession.execTrimmed(command: string, timeout: number)→string

Same as exec(command, true): runs the command and returns the output without leading and trailing whitespace (such as the final newline), which is what you want for single values. The optional second argument is the time limit in seconds (default 300).

Parameters

command string

Command line, run by the user's shell on the server

timeout number optional

Time limit in seconds; default 300

Returns

string The command output without leading and trailing whitespace

Example

local version = session.execTrimmed("cat /opt/app/VERSION")

run()

session.run(command: string)→SshResultsession.run(command: string, timeout: number)→SshResult

Runs a command and returns a table with its exit code and both output streams, for scripts that need to know whether the command succeeded. The exit code is -1 when the server did not report one. The time limit is 300 seconds unless you pass another number of seconds as second argument; a command that runs longer is stopped and raises "Command timed out". Raises "Failed to execute command: ..." when connecting, logging in or running fails; a non-zero exit code is not an error.

Parameters

command string

Command line, run by the user's shell on the server

timeout number optional

Time limit in seconds; default 300

Returns

SshResult The outcome of a command run with session.run.

Fields of SshResult

exitCode number

exit code of the command; 0 means success, -1 when the server did not report one

stdout string

everything the command wrote to standard output

stderr string

everything the command wrote to standard error

All table shapes

Example

local result = session.run("systemctl is-active myapp")
Assert.equals(0, result.exitCode, result.stderr)
print(result.stdout)

close()

session.close()→self

Closes the connection to the server. Errors while closing are ignored. Running another command afterwards connects again.

Returns

self chainable The session itself, so calls can be chained.