ssh

ssh :: { destination, useSubstitutes, …​ } → String → String

A ssh invocation with automatic copying of command dependencies.

For example, this copies hello to a remote host and runs it:

mkEffect {
  effectScript = ''
    echo "log from effect sandbox"
    ${effects.ssh { destination = "my-host"; } ''
      set -euo pipefail
      echo "log from remote host"
      ${hello}/bin/hello -g 'Hello from a remote host'
    ''}
  '';
}

Essential Parameters

Remote commands (positional argument 2)

A string containing the commands to execute on the remote host. Its dependencies are automatically copied to the remote host.

Make sure to reference packages that match the remote host architecture. For example:

let
  nixpkgs = /* ... */;
  aarch64Pkgs = import nixpkgs { system = "aarch64-linux"; config = {}; overlays = [] };
in
mkEffect {
  effectScript = ''
    echo "log from effect sandbox"
    ${effects.ssh { destination = "my-aarch64-host"; } ''
      set -euo pipefail
      echo "log from remote host"
      ${aarch64Pkgs.hello}/bin/hello -g 'Hello from a remote host'
    ''}
  '';
}

destination

Hostname to SSH to. This is inserted as an unquoted argument, so you can use bash variables.

"destination, which may be specified as either [user@]hostname or a URI of the form ssh://[user@]hostname[:port.]"
— `man 1 ssh`

compress

Default: false. When set to true, apply gzip compression. Compression may be a bottleneck on fast networks.

inheritVariables

A list of strings representing the bash variables and environment variables will be copied from the client before running the remote command.

This is similar to the SendEnv option in ssh, but does not rely on the server’s AcceptEnv configuration. Furthermore, it can copy bash variables that have not been export-ed. Such variables remain un-export-ed.

Parameters

buildOnDestination

Default: false. Whether to build the command and its dependencies on the remote.

This is useful when bootstrapping a new agent without setting it up as a remote builder first.

Builds that are deferred to the destination are by definition not built during the "build phase" of CI. This means that you may encounter a build failure after the job’s effects are started. For this reason, you might want to enable this only temporarily, or you could add attributes to the job for relevant packages and checks.

The latter option has the benefit that packages will be in your binary cache, to speed up realisation on the remote, similar to when buildOnDestination is false.

Evaluation still happens in CI, as well as builds for "import from derivation" if needed.

destinationPkgs

Only needed when buildOnDestination is true.

Some functions, such as runNixDarwin will set a default value for you.

A Nixpkgs instance that is buildable on the destination.

This parameter is part of a workaround for no builtins.storePath in pure mode (nix issue).

compressClosure

Default: value of compress. Whether to compress the store paths.

compressSession

Default: value of compress. Whether to compress the SSH session after copying store paths.

sshOptions

Default: "". Extra options to pass to the ssh invocations, which includes child processes of nix-copy-closure. Will be split and interpolated by bash.

ssh

Default: pkgs.openssh. Which SSH package to use. The default comes from the pkgs argument that was passed to the hercules-ci-effects call, or self where the overlay was inserted.

nix

Default: pkgs.nix. Which Nix package to use for nix-copy-closure. The default comes from the pkgs argument that was passed to the hercules-ci-effects call, or self where the overlay was inserted.

nix-copy-closureOptions

Default: "". Extra options to pass to the nix-copy-closure invocation. Will be split and interpolated by bash.

See useSubstitutes.

useSubstitutes

Default: true. Whether to use substition (binary caches) on the remote host.

Using substitutes on the remote host is usually faster because the store paths on the substituter have been compressed (and decompression is fast) and/or the remote host has a better connection to the substituter than to the client.

You can choose to disable this if your agent runs in the network you deploy.

Return value

A string containing a single bash statement that connects to the remote host, etc.

The string context will include dependencies used on the remote host and, by default, includes references to the nix and openssh packages.

See also