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.
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.
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.
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.
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.
ssh*
(ssh* action)Evaluates an SSH action against the current host. Retries packet corrupt errors.
throw-on-nonzero-exit
(throw-on-nonzero-exit {:keys [exit action], :as result})Throws when an SSH result has nonzero exit status.
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.