Ssh

library

Runs commands on remote servers over SSH. Ssh.newSession (password) and Ssh.newSessionWithKey (private key) return an SshSession. Things to know: the connection is opened lazily by the first command, so wrong credentials or an unreachable host show up there, not in newSession. Host keys: by default any server key is accepted (a warning is logged once per host); pass the server's SHA256 fingerprint as the optional last argument of newSession to pin it, or run the agent with agent.ssh.strictHostKeys=true to require a pinned fingerprint or a known_hosts entry. A command is stopped after 300 seconds unless you pass another time limit, and session.run also returns the exit code. Keep passwords and private keys in secrets: secret("name"). Close sessions with session.close() or Ssh.close().

Kind Library, a global in every script
Category Remote & Infrastructure
Functions 3

Objects

SshSession

Functions

newSession SshSession Creates an SSH session that logs in with a password.
newSessionWithKey SshSession Creates an SSH session that logs in with a private key.
close self Closes every SSH session opened with Ssh.newSession or Ssh.newSessionWithKey in this script.

`newSession()`

Ssh.newSession(username: string, password: string, host: string)→SshSessionSsh.newSession(username: string, password: string, host: string, port: number)→SshSessionSsh.newSession(username: string, password: string, host: string, port: number, fingerprint?: string)→SshSession

Creates an SSH session that logs in with a password. Nothing is sent over the network yet: the connection and login happen when the first command is executed. The optional fingerprint is the server's SHA256 host key fingerprint (as printed by `ssh-keygen -l`, with or without the "SHA256:" prefix); when given, a server with another key is rejected.

Parameters

username string: User name on the server
password string: Password; use secret()
host string: Host name or IP address of the server
port number optional: SSH port; 22 when left out
fingerprint string optional: SHA256 fingerprint of the server's host key, to pin it

Returns

SshSession An SSH connection to one server, used to run commands.

Example

local session = Ssh.newSession("deploy", secret("deploy_password"), "app01.example.com")
print(session.execTrimmed("uname -a"))
session.close()

`newSessionWithKey()`

Ssh.newSessionWithKey(username: string, sshKey: string, host: string)→SshSessionSsh.newSessionWithKey(username: string, sshKey: string, host: string, port: number)→SshSessionSsh.newSessionWithKey(username: string, sshKey: string, host: string, port: number, fingerprint?: string)→SshSession

Creates an SSH session that logs in with a private key. The key is the text of the key itself (the "-----BEGIN ... PRIVATE KEY-----" block), not a file path, so store it in a secret. Keys protected by a passphrase are not supported. Connection and login happen when the first command is executed. The optional fingerprint pins the server's SHA256 host key fingerprint, as in newSession.

Parameters

username string: User name on the server
sshKey string: Private key text (PEM/OpenSSH), from a secret
host string: Host name or IP address of the server
port number optional: SSH port; 22 when left out
fingerprint string optional: SHA256 fingerprint of the server's host key, to pin it

Returns

SshSession An SSH connection to one server, used to run commands.

Example

local session = Ssh.newSessionWithKey("deploy", secret("deploy_private_key"), "app01.example.com", 2222)
local status = session.execTrimmed("systemctl is-active myapp")
Assert.equals("active", status)
session.close()

`close()`

Ssh.close()→self

Closes every SSH session opened with Ssh.newSession or Ssh.newSessionWithKey in this script.

Returns

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