When desired, the build daemon can offload
derivation builds to other machines
running Guix, using the
offload build hook. When that
feature is enabled, a list of user-specified build machines is read from
/etc/guix/machines.scm; anytime a build is requested, for
guix build, the daemon attempts to offload it to one
of the machines that satisfies the derivation’s constraints, in
particular its system type—e.g., x86_64-linux. Missing
prerequisites for the build are copied over SSH to the target machine,
which then proceeds with the build; upon success the output(s) of the
build are copied back to the initial machine.
The /etc/guix/machines.scm file typically looks like this:
(list (build-machine (name "eightysix.example.org") (system "x86_64-linux") (user "bob") (speed 2.)) ; incredibly fast! (build-machine (name "meeps.example.org") (system "mips64el-linux") (user "alice") (private-key (string-append (getenv "HOME") "/.lsh/identity-for-guix"))))
In the example above we specify a list of two build machines, one for
x86_64 architecture and one for the
In fact, this file is—not surprisingly!—a Scheme file that is
evaluated when the
offload hook is started. Its return value
must be a list of
build-machine objects. While this example
shows a fixed list of build machines, one could imagine, say, using
DNS-SD to return a list of potential build machines discovered in the
local network (see Guile-Avahi in Using
Avahi in Guile Scheme Programs). The
build-machine data type is
This data type represents build machines the daemon may offload builds to. The important fields are:
The remote machine’s host name.
The remote machine’s system type—e.g.,
The user account to use when connecting to the remote machine over SSH. Note that the SSH key pair must not be passphrase-protected, to allow non-interactive logins.
A number of optional fields may be specified:
Port number of the machine’s SSH server (default: 22).
The SSH private key file to use when connecting to the machine.
Currently offloading uses GNU lsh as its SSH client (see (GNU lsh Manual)Invoking lsh). Thus, the key file here must be an lsh key file. This may change in the future, though.
The number of builds that may run in parallel on the machine (1 by default.)
A “relative speed factor”. The offload scheduler will tend to prefer machines with a higher speed factor.
A list of strings denoting specific features supported by the machine.
An example is
"kvm" for machines that have the KVM Linux modules
and corresponding hardware support. Derivations can request features by
name, and they will be scheduled on matching build machines.
guix command must be in the search path on the build
machines, since offloading works by invoking the
guix archive and
guix build commands. In addition, the Guix modules must be in
$GUILE_LOAD_PATH on the build machine—you can check whether
this is the case by running:
lsh build-machine guile -c '(use-modules (guix config))'
There’s one last thing to do once machines.scm is in place. As explained above, when offloading, files are transferred back and forth between the machine stores. For this to work, you first need to generate a key pair on each machine to allow the daemon to export signed archives of files from the store (see Invoking guix archive):
# guix archive --generate-key
Each build machine must authorize the key of the master machine so that it accepts store items it receives from the master:
# guix archive --authorize < master-public-key.txt
Likewise, the master machine must authorize the key of each build machine.
All the fuss with keys is here to express pairwise mutual trust relations between the master and the build machines. Concretely, when the master receives files from a build machine (and vice versa), its build daemon can make sure they are genuine, have not been tampered with, and that they are signed by an authorized key.