diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 122 |
1 files changed, 113 insertions, 9 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index a637614fbb..48e4631836 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -175,13 +175,24 @@ your goal is to share the store with Nix. @cindex daemon Operations such as building a package or running the garbage collector -are all performed by a specialized process, the @dfn{Guix daemon}, on +are all performed by a specialized process, the @dfn{build daemon}, on behalf of clients. Only the daemon may access the store and its associated database. Thus, any operation that manipulates the store goes through the daemon. For instance, command-line tools such as @command{guix package} and @command{guix build} communicate with the daemon (@i{via} remote procedure calls) to instruct it what to do. +The following sections explain how to prepare the build daemon's +environment. + +@menu +* Build Environment Setup:: Preparing the isolated build environment. +* Daemon Offload Setup:: Offloading builds to remote machines. +@end menu + +@node Build Environment Setup +@subsection Build Environment Setup + In a standard multi-user setup, Guix and its daemon---the @command{guix-daemon} program---are installed by the system administrator; @file{/nix/store} is owned by @code{root} and @@ -256,14 +267,6 @@ user @file{nobody}; a writable @file{/tmp} directory. @end itemize -Finally, you may want to generate a key pair to allow the daemon to -export signed archives of files from the store (@pxref{Invoking guix -archive}): - -@example -# guix archive --generate-key -@end example - If you are installing Guix as an unprivileged user, it is still possible to run @command{guix-daemon}. However, build processes will not be isolated from one another, and not from the rest of the system. @@ -271,6 +274,107 @@ Thus, build processes may interfere with each other, and may access programs, libraries, and other files available on the system---making it much harder to view them as @emph{pure} functions. + +@node Daemon Offload Setup +@subsection Using the Offload Facility + +@cindex offloading +The build daemon can @dfn{offload} derivation builds to other machines +running Guix, using the @code{offload} @dfn{build hook}. When that +feature is enabled, a list of user-specified build machines is read from +@file{/etc/guix/machines.scm}; anytime a build is requested, for +instance via @code{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., @file{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 @file{/etc/guix/machines.scm} is---not surprisingly!---a Scheme file +whose return value must be a list of @code{build-machine} objects. In +practice, it typically looks like this: + +@example +(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") + "/.ssh/id-rsa-for-guix")))) +@end example + +@noindent +In the example above we specify a list of two build machines, one for +the @code{x86_64} architecture and one for the @code{mips64el} +architecture. The compulsory fields for a @code{build-machine} +declaration are: + +@table @code + +@item name +The remote machine's host name. + +@item system +The remote machine's system type. + +@item user +The user account to use when connecting to the remote machine over SSH. +Note that the SSH key pair must @emph{not} be passphrase-protected, to +allow non-interactive logins. + +@end table + +@noindent +A number of optional fields may be optionally specified: + +@table @code + +@item private-key +The SSH private key file to use when connecting to the machine. + +@item parallel-builds +The number of builds that may run in parallel on the machine (1 by +default.) + +@item speed +A ``relative speed factor''. The offload scheduler will tend to prefer +machines with a higher speed factor. + +@item features +A list of strings denoting specific features supported by the machine. +An example is @code{"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. + +@end table + +The @code{guix} command must be in the search path on the build +machines, since offloading works by invoking the @code{guix archive} and +@code{guix build} commands. + +There's one last thing to do once @file{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 need to generate a +key pair to allow the daemon to export signed archives of files from the +store (@pxref{Invoking guix archive}): + +@example +# guix archive --generate-key +@end example + +@noindent +Thus, when receiving files, a machine's build daemon can make sure they +are genuine, have not been tampered with, and that they are signed by an +authorized key. + + @node Invoking guix-daemon @section Invoking @command{guix-daemon} |