jepsen.control

Provides control over a remote node. There’s a lot of dynamically bound state in this namespace because we want to make it as simple as possible for scripts to open connections to various nodes.

Note that a whole bunch of this namespace refers to things as ‘ssh’, although they really can apply to any remote, not just SSH.

&&

A literal &&

*dir*

dynamic

Working directory

*dummy*

dynamic

When true, don’t actually use SSH

*host*

dynamic

Current hostname

*password*

dynamic

Password (for login)

*port*

dynamic

SSH listening port

*private-key-path*

dynamic

SSH identity file

*remote*

dynamic

The remote to use for remote control actions

*retries*

dynamic

How many times to retry conns

*session*

dynamic

Current control session wrapper

*strict-host-key-checking*

dynamic

Verify SSH host keys

*sudo*

dynamic

User to sudo to

*sudo-password*

dynamic

Password for sudo, if needed

*trace*

dynamic

Shall we trace commands?

*username*

dynamic

Username

cd

macro

(cd dir & body)

Evaluates forms in the given directory.

clj-ssh

The clj-ssh SSH remote. This used to be the default.

cmd-context

(cmd-context)

Constructs a context map for a command’s execution from dynamically bound vars.

conn-spec

(conn-spec)

jepsen.control originally stored everything–host, post, etc.–in separate dynamic variables. Now, we store these things in a conn-spec map, which can be passed to remotes without creating cyclic dependencies. This function exists to support the transition from those variables to a conn-spec, and constructs a conn spec from current var bindings.

debug-data

(debug-data)

Construct a map of SSH data for debugging purposes.

disconnect

(disconnect remote)

Close a Remote session.

download

(download remote-paths local-path)

Copies remote paths to local node.

env

(env env)

We often want to construct env vars for a process. This function takes a map of environment variable names (any Named type, e.g. :HOME, “HOME”) to values (which are coerced using (str value)), and constructs a Literal string, suitable for passing to exec, which binds those environment variables.

Callers of this function (especially indirectly, as with start-stop-daemon), may wish to construct env var strings themselves. Passing a string s to this function simply returns (lit s). Passing a Literal l to this function returns l. nil is passed through unchanged.

escape

(escape s)

Escapes a thing for the shell.

Nils are empty strings.

Literal wrappers are passed through directly.

The special keywords :>, :>>, and :< map to their corresponding shell I/O redirection operators.

Named things like keywords and symbols use their name, escaped. Strings are escaped like normal.

Sequential collections and sets have each element escaped and space-separated.

exec

(exec & commands)

Takes a shell command and arguments, runs the command, and returns stdout, throwing if an error occurs. Escapes all arguments.

exec*

(exec* & commands)

Like exec, but does not escape.

expand-path

(expand-path path)

Expands path relative to the current directory.

file->path

(file->path x)

Takes an object, if it’s an instance of java.io.File, gets the path, otherwise returns the object

just-stdout

(just-stdout result)

Returns the stdout from an ssh result, trimming any newlines at the end.

lit

(lit s)

A literal string to be passed, unescaped, to the shell.

on

macro

(on host & body)

Opens a session to the given host and evaluates body there; and closes session when body completes.

on-many

macro

(on-many hosts & body)

Takes a list of hosts, executes body on each host in parallel, and returns a map of hosts to return values.

on-nodes

(on-nodes test f)(on-nodes test nodes f)

Given a test, evaluates (f test node) in parallel on each node, with that node’s SSH connection bound. If nodes is provided, evaluates only on those nodes in particular.

session

(session host)

Returns a Remote bound to the given host.

ssh

The default (SSHJ-backed) remote.

ssh*

(ssh* action)

Evaluates an SSH action against the current host. Retries packet corrupt errors.

su

macro

(su & body)

sudo root …

sudo

macro

(sudo user & body)

Evaluates forms with a particular user.

throw-on-nonzero-exit

(throw-on-nonzero-exit {:keys [exit action], :as result})

Throws when an SSH result has nonzero exit status.

trace

macro

(trace & body)

Evaluates forms with command tracing enabled.

upload

(upload local-paths remote-path)

Copies local path(s) to remote node and returns the remote path.

upload-resource!

(upload-resource! resource-name remote-path)

Uploads a local JVM resource (as a string) to the given remote path.

with-remote

macro

(with-remote remote & body)

Takes a remote and evaluates body with that remote in that scope.

with-session

macro

(with-session host session & body)

Binds a host and session and evaluates body. Does not open or close session; this is just for the namespace dynamic state.

with-ssh

macro

(with-ssh ssh & body)

Takes a map of SSH configuration and evaluates body in that scope. Catches JSchExceptions and re-throws with all available debugging context. Options:

:dummy? :username :password :sudo-password :private-key-path :strict-host-key-checking

with-test-nodes

macro

(with-test-nodes test & body)

Given a test, evaluates body in parallel on each node, with that node’s SSH connection bound.

wrap-cd

(wrap-cd cmd)

Wraps command by changing to the current bound directory first.

wrap-sudo

(wrap-sudo cmd)

Wraps command in a sudo subshell.

wrap-trace

(wrap-trace arg)

Logs argument to console when tracing is enabled.

|

A literal pipe character.