guix.texi

Again in case of test failures, please send @email{bug-guix@@gnu.org}
all the details.

@node Setting Up the Daemon
@section Setting Up the Daemon

@cindex daemon
Operations such as building a package or running the garbage collector
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.  See also @ref{Substitutes}, for information on how to allow
the daemon to download pre-built binaries.

@menu
* Build Environment Setup::     Preparing the isolated build environment.
* Daemon Offload Setup::        Offloading builds to remote machines.
* SELinux Support::             Using an SELinux policy for the daemon.
@end menu

@node Build Environment Setup
@subsection Build Environment Setup

@cindex build environment
In a standard multi-user setup, Guix and its daemon---the
@command{guix-daemon} program---are installed by the system
administrator; @file{/gnu/store} is owned by @code{root} and
@command{guix-daemon} runs as @code{root}.  Unprivileged users may use
Guix tools to build packages or otherwise access the store, and the
daemon will do it on their behalf, ensuring that the store is kept in a
consistent state, and allowing built packages to be shared among users.

@cindex build users
When @command{guix-daemon} runs as @code{root}, you may not want package
build processes themselves to run as @code{root} too, for obvious
security reasons.  To avoid that, a special pool of @dfn{build users}
should be created for use by build processes started by the daemon.
These build users need not have a shell and a home directory: they will
just be used when the daemon drops @code{root} privileges in build
processes.  Having several such users allows the daemon to launch
distinct build processes under separate UIDs, which guarantees that they
do not interfere with each other---an essential feature since builds are
regarded as pure functions (@pxref{Introduction}).

On a GNU/Linux system, a build user pool may be created like this (using
Bash syntax and the @code{shadow} commands):

@c See https://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
@c for why `-G' is needed.
@example
# groupadd --system guixbuild
# for i in `seq -w 1 10`;
  do
    useradd -g guixbuild -G guixbuild           \
            -d /var/empty -s `which nologin`    \
            -c "Guix build user $i" --system    \
            guixbuilder$i;
  done
@end example

@noindent
The number of build users determines how many build jobs may run in
parallel, as specified by the @option{--max-jobs} option
(@pxref{Invoking guix-daemon, @option{--max-jobs}}).  To use
@command{guix system vm} and related commands, you may need to add the
build users to the @code{kvm} group so they can access @file{/dev/kvm},
using @code{-G guixbuild,kvm} instead of @code{-G guixbuild}
(@pxref{Invoking guix system}).

The @code{guix-daemon} program may then be run as @code{root} with the
following command@footnote{If your machine uses the systemd init system,
dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
file in @file{/etc/systemd/system} will ensure that
@command{guix-daemon} is automatically started.  Similarly, if your
machine uses the Upstart init system, drop the
@file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
file in @file{/etc/init}.}:

@example
# guix-daemon --build-users-group=guixbuild
@end example

@cindex chroot
@noindent
This way, the daemon starts build processes in a chroot, under one of
the @code{guixbuilder} users.  On GNU/Linux, by default, the chroot
environment contains nothing but:

@c Keep this list in sync with libstore/build.cc! -----------------------
@itemize
@item
a minimal @code{/dev} directory, created mostly independently from the
host @code{/dev}@footnote{``Mostly'', because while the set of files
that appear in the chroot's @code{/dev} is fixed, most of these files
can only be created if the host has them.};

@item
the @code{/proc} directory; it only shows the processes of the container
since a separate PID name space is used;

@item
@file{/etc/passwd} with an entry for the current user and an entry for
user @file{nobody};

@item
@file{/etc/group} with an entry for the user's group;

@item
@file{/etc/hosts} with an entry that maps @code{localhost} to
@code{127.0.0.1};

@item
a writable @file{/tmp} directory.
@end itemize

You can influence the directory where the daemon stores build trees
@i{via} the @env{TMPDIR} environment variable.  However, the build tree
within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0},
where @var{name} is the derivation name---e.g., @code{coreutils-8.24}.
This way, the value of @env{TMPDIR} does not leak inside build
environments, which avoids discrepancies in cases where build processes
capture the name of their build tree.

@vindex http_proxy
@vindex https_proxy
The daemon also honors the @env{http_proxy} and @env{https_proxy}
environment variables for HTTP and HTTPS downloads it performs, be it
for fixed-output derivations (@pxref{Derivations}) or for substitutes
(@pxref{Substitutes}).

If you are installing Guix as an unprivileged user, it is still possible
to run @command{guix-daemon} provided you pass @option{--disable-chroot}.
However, build processes will not be isolated from one another, and not
from the rest of the system.  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
@cindex build hook
When desired, the build daemon can @dfn{offload} derivation builds to
other machines running Guix, using the @code{offload} @dfn{build
hook}@footnote{This feature is available only when
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} is
present.}.  When that feature is enabled, a list of user-specified build
machines is read from @file{/etc/guix/machines.scm}; every time a build
is requested, for instance via @code{guix build}, the daemon attempts to
offload it to one of the machines that satisfy the constraints of the
derivation, in particular its system types---e.g., @code{x86_64-linux}.
A single machine can have multiple system types, either because its
architecture natively supports it, via emulation
(@pxref{transparent-emulation-qemu, Transparent Emulation with QEMU}),
or both.  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 offload facility comes with a basic scheduler that
attempts to select the best machine.  The best machine is chosen among
the available machines based on criteria such as:

@enumerate
@item
The availability of a build slot.  A build machine can have as many
build slots (connections) as the value of the @code{parallel-builds}
field of its @code{build-machine} object.

@item
Its relative speed, as defined via the @code{speed} field of its
@code{build-machine} object.

@item
Its load.  The normalized machine load must be lower than a threshold
value, configurable via the @code{overload-threshold} field of its
@code{build-machine} object.

@item
Disk space availability.  More than a 100 MiB must be available.
@end enumerate

The @file{/etc/guix/machines.scm} file typically looks like this:

@lisp
(list (build-machine
        (name "eightysix.example.org")
        (systems (list "x86_64-linux" "i686-linux"))
        (host-key "ssh-ed25519 AAAAC3Nza@dots{}")
        (user "bob")
        (speed 2.))     ;incredibly fast!

      (build-machine
        (name "armeight.example.org")
        (systems (list "aarch64-linux"))
        (host-key "ssh-rsa AAAAB3Nza@dots{}")
        (user "alice")
        (private-key
         (string-append (getenv "HOME")
                        "/.ssh/identity-for-guix"))))
@end lisp

@noindent
In the example above we specify a list of two build machines, one for
the @code{x86_64} and @code{i686} architectures and one for the
@code{aarch64} architecture.

In fact, this file is---not surprisingly!---a Scheme file that is
evaluated when the @code{offload} hook is started.  Its return value
must be a list of @code{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 (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
Avahi in Guile Scheme Programs}).  The @code{build-machine} data type is
detailed below.

@deftp {Data Type} build-machine
This data type represents build machines to which the daemon may offload
builds.  The important fields are:

@table @code

@item name
The host name of the remote machine.

@item systems
The system types the remote machine supports---e.g., @code{(list
"x86_64-linux" "i686-linux")}.

@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.

@item host-key
This must be the machine's SSH @dfn{public host key} in OpenSSH format.
This is used to authenticate the machine when we connect to it.  It is a
long string that looks like this:

@example
ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org
@end example

If the machine is running the OpenSSH daemon, @command{sshd}, the host
key can be found in a file such as
@file{/etc/ssh/ssh_host_ed25519_key.pub}.

If the machine is running the SSH daemon of GNU@tie{}lsh,
@command{lshd}, the host key is in @file{/etc/lsh/host-key.pub} or a
similar file.  It can be converted to the OpenSSH format using
@command{lsh-export-key} (@pxref{Converting keys,,, lsh, LSH Manual}):

@example
$ lsh-export-key --openssh < /etc/lsh/host-key.pub
ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{}
@end example

@end table

A number of optional fields may be specified:

@table @asis

@item @code{port} (default: @code{22})
Port number of SSH server on the machine.

@item @code{private-key} (default: @file{~root/.ssh/id_rsa})
The SSH private key file to use when connecting to the machine, in
OpenSSH format.  This key must not be protected with a passphrase.

Note that the default value is the private key @emph{of the root
account}.  Make sure it exists if you use the default.

@item @code{compression} (default: @code{"zlib@@openssh.com,zlib"})
@itemx @code{compression-level} (default: @code{3})
The SSH-level compression methods and compression level requested.

Note that offloading relies on SSH compression to reduce bandwidth usage
when transferring files to and from build machines.

@item @code{daemon-socket} (default: @code{"/var/guix/daemon-socket/socket"})
File name of the Unix-domain socket @command{guix-daemon} is listening
to on that machine.

@item @code{overload-threshold} (default: @code{0.6})
The load threshold above which a potential offload machine is
disregarded by the offload scheduler.  The value roughly translates to
the total processor usage of the build machine, ranging from 0.0 (0%) to
1.0 (100%).  It can also be disabled by setting
@code{overload-threshold} to @code{#f}.

@item @code{parallel-builds} (default: @code{1})
The number of builds that may run in parallel on the machine.

@item @code{speed} (default: @code{1.0})
A ``relative speed factor''.  The offload scheduler will tend to prefer
machines with a higher speed factor.

@item @code{features} (default: @code{'()})
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
@end deftp

The @command{guix} command must be in the search path on the build
machines.  You can check whether this is the case by running:

@example
ssh build-machine guix repl --version
@end example

There is 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 first need to
generate a key pair on each machine 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
Each build machine must authorize the key of the master machine so that
it accepts store items it receives from the master:

@example
# guix archive --authorize < master-public-key.txt
@end example

@noindent
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 @i{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.

@cindex offload test
To test whether your setup is operational, run this command on the
master node:

@example
# guix offload test
@end example

This will attempt to connect to each of the build machines specified in
@file{/etc/guix/machines.scm}, make sure Guix is
available on each machine, attempt to export to the machine and import
from it, and report any error in the process.

If you want to test a different machine file, just specify it on the
command line:

@example
# guix offload test machines-qualif.scm
@end example

Last, you can test the subset of the machines whose name matches a
regular expression like this:

@example
# guix offload test machines.scm '\.gnu\.org$'
@end example

@cindex offload status
To display the current load of all build hosts, run this command on the
main node:

@example
# guix offload status
@end example


@node SELinux Support
@subsection SELinux Support

@cindex SELinux, daemon policy
@cindex mandatory access control, SELinux
@cindex security, guix-daemon
Guix includes an SELinux policy file at @file{etc/guix-daemon.cil} that
can be installed on a system where SELinux is enabled, in order to label
Guix files and to specify the expected behavior of the daemon.  Since
Guix System does not provide an SELinux base policy, the daemon policy cannot
be used on Guix System.

@subsubsection Installing the SELinux policy
@cindex SELinux, policy installation
To install the policy run this command as root:

@example
semodule -i etc/guix-daemon.cil
@end example

Then relabel the file system with @code{restorecon} or by a different
mechanism provided by your system.

Once the policy is installed, the file system has been relabeled, and
the daemon has been restarted, it should be running in the
@code{guix_daemon_t} context.  You can confirm this with the following
command:

@example
ps -Zax | grep guix-daemon
@end example

Monitor the SELinux log files as you run a command like @code{guix build
hello} to convince yourself that SELinux permits all necessary
operations.

@subsubsection Limitations
@cindex SELinux, limitations

This policy is not perfect.  Here is a list of limitations or quirks
that should be considered when deploying the provided SELinux policy for
the Guix daemon.

@enumerate
@item
@code{guix_daemon_socket_t} isn’t actually used.  None of the socket
operations involve contexts that have anything to do with
@code{guix_daemon_socket_t}.  It doesn’t hurt to have this unused label,
but it would be preferrable to define socket rules for only this label.

@item
@code{guix gc} cannot access arbitrary links to profiles.  By design,
the file label of the destination of a symlink is independent of the
file label of the link itself.  Although all profiles under
$localstatedir are labelled, the links to these profiles inherit the
label of the directory they are in.  For links in the user’s home
directory this will be @code{user_home_t}.  But for links from the root
user’s home directory, or @file{/tmp}, or the HTTP server’s working
directory, etc, this won’t work.  @code{guix gc} would be prevented from
reading and following these links.

@item
The daemon’s feature to listen for TCP connections might no longer work.
This might require extra rules, because SELinux treats network sockets
differently from files.

@item
Currently all files with a name matching the regular expression
@code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} are assigned the
label @code{guix_daemon_exec_t}; this means that @emph{any} file with
that name in any profile would be permitted to run in the
@code{guix_daemon_t} domain.  This is not ideal.  An attacker could
build a package that provides this executable and convince a user to
install and run it, which lifts it into the @code{guix_daemon_t} domain.
At that point SELinux could not prevent it from accessing files that are
allowed for processes in that domain.

You will need to relabel the store directory after all upgrades to
@file{guix-daemon}, such as after running @code{guix pull}.  Assuming the
store is in @file{/gnu}, you can do this with @code{restorecon -vR /gnu},
or by other means provided by your operating system.

We could generate a much more restrictive policy at installation time,
so that only the @emph{exact} file name of the currently installed
@code{guix-daemon} executable would be labelled with
@code{guix_daemon_exec_t}, instead of using a broad regular expression.
The downside is that root would have to install or upgrade the policy at
installation time whenever the Guix package that provides the
effectively running @code{guix-daemon} executable is upgraded.
@end enumerate

@node Invoking guix-daemon
@section Invoking @command{guix-daemon}

The @command{guix-daemon} program implements all the functionality to
access the store.  This includes launching build processes, running the
garbage collector, querying the availability of a build result, etc.  It
is normally run as @code{root} like this:

@example
# guix-daemon --build-users-group=guixbuild
@end example

@noindent
For details on how to set it up, @pxref{Setting Up the Daemon}.

@cindex chroot
@cindex container, build environment
@cindex build environment
@cindex reproducible builds
By default, @command{guix-daemon} launches build processes under
different UIDs, taken from the build group specified with
@option{--build-users-group}.  In addition, each build process is run in a
chroot environment that only contains the subset of the store that the
build process depends on, as specified by its derivation
(@pxref{Programming Interface, derivation}), plus a set of specific
system directories.  By default, the latter contains @file{/dev} and
@file{/dev/pts}.  Furthermore, on GNU/Linux, the build environment is a
@dfn{container}: in addition to having its own file system tree, it has
a separate mount name space, its own PID name space, network name space,
etc.  This helps achieve reproducible builds (@pxref{Features}).

When the daemon performs a build on behalf of the user, it creates a
build directory under @file{/tmp} or under the directory specified by
its @env{TMPDIR} environment variable.  This directory is shared with
the container for the duration of the build, though within the container,
the build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}.

The build directory is automatically deleted upon completion, unless the
build failed and the client specified @option{--keep-failed}
(@pxref{Common Build Options, @option{--keep-failed}}).

The daemon listens for connections and spawns one sub-process for each session
started by a client (one of the @command{guix} sub-commands).  The
@command{guix processes} command allows you to get an overview of the activity
on your system by viewing each of the active sessions and clients.
@xref{Invoking guix processes}, for more information.

The following command-line options are supported:

@table @code
@item --build-users-group=@var{group}
Take users from @var{group} to run build processes (@pxref{Setting Up
the Daemon, build users}).

@item --no-substitutes
@cindex substitutes
Do not use substitutes for build products.  That is, always build things
locally instead of allowing downloads of pre-built binaries
(@pxref{Substitutes}).

When the daemon runs with @option{--no-substitutes}, clients can still
explicitly enable substitution @i{via} the @code{set-build-options}
remote procedure call (@pxref{The Store}).

@anchor{daemon-substitute-urls}
@item --substitute-urls=@var{urls}
Consider @var{urls} the default whitespace-separated list of substitute
source URLs.  When this option is omitted,
@indicateurl{https://@value{SUBSTITUTE-SERVER}} is used.

This means that substitutes may be downloaded from @var{urls}, as long
as they are signed by a trusted signature (@pxref{Substitutes}).

@xref{Getting Substitutes from Other Servers}, for more information on
how to configure the daemon to get substitutes from other servers.

@cindex offloading
@item --no-offload
Do not use offload builds to other machines (@pxref{Daemon Offload
Setup}).  That is, always build things locally instead of offloading
builds to remote machines.

@item --cache-failures
Cache build failures.  By default, only successful builds are cached.

When this option is used, @command{guix gc --list-failures} can be used
to query the set of store items marked as failed; @command{guix gc
--clear-failures} removes store items from the set of cached failures.
@xref{Invoking guix gc}.

@item --cores=@var{n}
@itemx -c @var{n}
Use @var{n} CPU cores to build each derivation; @code{0} means as many
as available.

The default value is @code{0}, but it may be overridden by clients, such
as the @option{--cores} option of @command{guix build} (@pxref{Invoking
guix build}).

The effect is to define the @env{NIX_BUILD_CORES} environment variable
in the build process, which can then use it to exploit internal
parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.

@item --max-jobs=@var{n}
@itemx -M @var{n}
Allow at most @var{n} build jobs in parallel.  The default value is
@code{1}.  Setting it to @code{0} means that no builds will be performed
locally; instead, the daemon will offload builds (@pxref{Daemon Offload
Setup}), or simply fail.

@item --max-silent-time=@var{seconds}
When the build or substitution process remains silent for more than
@var{seconds}, terminate it and report a build failure.

The default value is @code{0}, which disables the timeout.

The value specified here can be overridden by clients (@pxref{Common
Build Options, @option{--max-silent-time}}).

@item --timeout=@var{seconds}
Likewise, when the build or substitution process lasts for more than
@var{seconds}, terminate it and report a build failure.

The default value is @code{0}, which disables the timeout.

The value specified here can be overridden by clients (@pxref{Common
Build Options, @option{--timeout}}).

@item --rounds=@var{N}
Build each derivation @var{n} times in a row, and raise an error if
consecutive build results are not bit-for-bit identical.  Note that this
setting can be overridden by clients such as @command{guix build}
(@pxref{Invoking guix build}).

When used in conjunction with @option{--keep-failed}, the differing
output is kept in the store, under @file{/gnu/store/@dots{}-check}.
This makes it easy to look for differences between the two results.

@item --debug
Produce debugging output.

This is useful to debug daemon start-up issues, but then it may be
overridden by clients, for example the @option{--verbosity} option of
@command{guix build} (@pxref{Invoking guix build}).

@item --chroot-directory=@var{dir}
Add @var{dir} to the build chroot.

Doing this may change the result of build processes---for instance if
they use optional dependencies found in @var{dir} when it is available,
and not otherwise.  For that reason, it is not recommended to do so.
Instead, make sure that each derivation declares all the inputs that it
needs.

@item --disable-chroot
Disable chroot builds.

Using this option is not recommended since, again, it would allow build
processes to gain access to undeclared dependencies.  It is necessary,
though, when @command{guix-daemon} is running under an unprivileged user
account.

@item --log-compression=@var{type}
Compress build logs according to @var{type}, one of @code{gzip},
@code{bzip2}, or @code{none}.

Unless @option{--lose-logs} is used, all the build logs are kept in the
@var{localstatedir}.  To save space, the daemon automatically compresses
them with Bzip2 by default.

@item --discover[=yes|no]
Whether to discover substitute servers on the local network using mDNS
and DNS-SD.

This feature is still experimental.  However, here are a few
considerations.

@enumerate
@item
It might be faster/less expensive than fetching from remote servers;
@item
There are no security risks, only genuine substitutes will be used
(@pxref{Substitute Authentication});
@item
An attacker advertising @command{guix publish} on your LAN cannot serve
you malicious binaries, but they can learn what software you’re
installing;
@item
Servers may serve substitute over HTTP, unencrypted, so anyone on the
LAN can see what software you’re installing.
@end enumerate

It is also possible to enable or disable substitute server discovery at
run-time by running:

@example
herd discover guix-daemon on
herd discover guix-daemon off
@end example

@item --disable-deduplication
@cindex deduplication
Disable automatic file ``deduplication'' in the store.

By default, files added to the store are automatically ``deduplicated'':
if a newly added file is identical to another one found in the store,
the daemon makes the new file a hard link to the other file.  This can
noticeably reduce disk usage, at the expense of slightly increased
input/output load at the end of a build process.  This option disables
this optimization.

@item --gc-keep-outputs[=yes|no]
Tell whether the garbage collector (GC) must keep outputs of live
derivations.

@cindex GC roots
@cindex garbage collector roots
When set to @code{yes}, the GC will keep the outputs of any live
derivation available in the store---the @file{.drv} files.  The default
is @code{no}, meaning that derivation outputs are kept only if they are
reachable from a GC root.  @xref{Invoking guix gc}, for more on GC
roots.

@item --gc-keep-derivations[=yes|no]
Tell whether the garbage collector (GC) must keep derivations
corresponding to live outputs.

When set to @code{yes}, as is the case by default, the GC keeps
derivations---i.e., @file{.drv} files---as long as at least one of their
outputs is live.  This allows users to keep track of the origins of
items in their store.  Setting it to @code{no} saves a bit of disk
space.

In this way, setting @option{--gc-keep-derivations} to @code{yes} causes
liveness to flow from outputs to derivations, and setting
@option{--gc-keep-outputs} to @code{yes} causes liveness to flow from
derivations to outputs.  When both are set to @code{yes}, the effect is
to keep all the build prerequisites (the sources, compiler, libraries,
and other build-time tools) of live objects in the store, regardless of
whether these prerequisites are reachable from a GC root.  This is
convenient for developers since it saves rebuilds or downloads.

@item --impersonate-linux-2.6
On Linux-based systems, impersonate Linux 2.6.  This means that the
kernel's @command{uname} system call will report 2.6 as the release number.

This might be helpful to build programs that (usually wrongfully) depend
on the kernel version number.

@item --lose-logs
Do not keep build logs.  By default they are kept under
@file{@var{localstatedir}/guix/log}.

@item --system=@var{system}
Assume @var{system} as the current system type.  By default it is the
architecture/kernel pair found at configure time, such as
@code{x86_64-linux}.

@item --listen=@var{endpoint}
Listen for connections on @var{endpoint}.  @var{endpoint} is interpreted
as the file name of a Unix-domain socket if it starts with
@code{/} (slash sign).  Otherwise, @var{endpoint} is interpreted as a
host name or host name and port to listen to.  Here are a few examples:

@table @code
@item --listen=/gnu/var/daemon
Listen for connections on the @file{/gnu/var/daemon} Unix-domain socket,
creating it if needed.

@item --listen=localhost
@cindex daemon, remote access
@cindex remote access to the daemon
@cindex daemon, cluster setup
@cindex clusters, daemon setup
Listen for TCP connections on the network interface corresponding to
@code{localhost}, on port 44146.

@item --listen=128.0.0.42:1234
Listen for TCP connections on the network interface corresponding to
@code{128.0.0.42}, on port 1234.
@end table

This option can be repeated multiple times, in which case
@command{guix-daemon} accepts connections on all the specified
endpoints.  Users can tell client commands what endpoint to connect to
by setting the @env{GUIX_DAEMON_SOCKET} environment variable
(@pxref{The Store, @env{GUIX_DAEMON_SOCKET}}).

@quotation Note
The daemon protocol is @emph{unauthenticated and unencrypted}.  Using
@option{--listen=@var{host}} is suitable on local networks, such as
clusters, where only trusted nodes may connect to the build daemon.  In
other cases where remote access to the daemon is needed, we recommend
using Unix-domain sockets along with SSH.
@end quotation

When @option{--listen} is omitted, @command{guix-daemon} listens for
connections on the Unix-domain socket located at
@file{@var{localstatedir}/guix/daemon-socket/socket}.
@end table


@node Application Setup
@section Application Setup

@cindex foreign distro
When using Guix on top of GNU/Linux distribution other than Guix System---a
so-called @dfn{foreign distro}---a few additional steps are needed to
get everything in place.  Here are some of them.

@subsection Locales

@anchor{locales-and-locpath}
@cindex locales, when not on Guix System
@vindex LOCPATH
@vindex GUIX_LOCPATH
Packages installed @i{via} Guix will not use the locale data of the
host system.  Instead, you must first install one of the locale packages
available with Guix and then define the @env{GUIX_LOCPATH} environment
variable:

@example
$ guix install glibc-locales
$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
@end example

Note that the @code{glibc-locales} package contains data for all the
locales supported by the GNU@tie{}libc and weighs in at around
917@tie{}MiB@.  Alternatively, the @code{glibc-utf8-locales} is smaller but
limited to a few UTF-8 locales.

The @env{GUIX_LOCPATH} variable plays a role similar to @env{LOCPATH}
(@pxref{Locale Names, @env{LOCPATH},, libc, The GNU C Library Reference
Manual}).  There are two important differences though:

@enumerate
@item
@env{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
provided by foreign distros.  Thus, using @env{GUIX_LOCPATH} allows you
to make sure the programs of the foreign distro will not end up loading
incompatible locale data.

@item
libc suffixes each entry of @env{GUIX_LOCPATH} with @code{/X.Y}, where
@code{X.Y} is the libc version---e.g., @code{2.22}.  This means that,
should your Guix profile contain a mixture of programs linked against
different libc version, each libc version will only try to load locale
data in the right format.
@end enumerate

This is important because the locale data format used by different libc
versions may be incompatible.

@subsection Name Service Switch

@cindex name service switch, glibc
@cindex NSS (name service switch), glibc
@cindex nscd (name service caching daemon)
@cindex name service caching daemon (nscd)
When using Guix on a foreign distro, we @emph{strongly recommend} that
the system run the GNU C library's @dfn{name service cache daemon},
@command{nscd}, which should be listening on the
@file{/var/run/nscd/socket} socket.  Failing to do that, applications
installed with Guix may fail to look up host names or user accounts, or
may even crash.  The next paragraphs explain why.

@cindex @file{nsswitch.conf}
The GNU C library implements a @dfn{name service switch} (NSS), which is
an extensible mechanism for ``name lookups'' in general: host name
resolution, user accounts, and more (@pxref{Name Service Switch,,, libc,
The GNU C Library Reference Manual}).

@cindex Network information service (NIS)
@cindex NIS (Network information service)
Being extensible, the NSS supports @dfn{plugins}, which provide new name
lookup implementations: for example, the @code{nss-mdns} plugin allow
resolution of @code{.local} host names, the @code{nis} plugin allows
user account lookup using the Network information service (NIS), and so
on.  These extra ``lookup services'' are configured system-wide in
@file{/etc/nsswitch.conf}, and all the programs running on the system
honor those settings (@pxref{NSS Configuration File,,, libc, The GNU C
Reference Manual}).

When they perform a name lookup---for instance by calling the
@code{getaddrinfo} function in C---applications first try to connect to
the nscd; on success, nscd performs name lookups on their behalf.  If
the nscd is not running, then they perform the name lookup by
themselves, by loading the name lookup services into their own address
space and running it.  These name lookup services---the
@file{libnss_*.so} files---are @code{dlopen}'d, but they may come from
the host system's C library, rather than from the C library the
application is linked against (the C library coming from Guix).

And this is where the problem is: if your application is linked against
Guix's C library (say, glibc 2.24) and tries to load NSS plugins from
another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will
likely crash or have its name lookups fail unexpectedly.

Running @command{nscd} on the system, among other advantages, eliminates
this binary incompatibility problem because those @code{libnss_*.so}
files are loaded in the @command{nscd} process, not in applications
themselves.

@subsection X11 Fonts

@cindex fonts
The majority of graphical applications use Fontconfig to locate and
load fonts and perform X11-client-side rendering.  The @code{fontconfig}
package in Guix looks for fonts in @file{$HOME/.guix-profile}
by default.  Thus, to allow graphical applications installed with Guix
to display fonts, you have to install fonts with Guix as well.
Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and
@code{font-gnu-freefont}.

@cindex @code{fc-cache}
@cindex font cache
Once you have installed or removed fonts, or when you notice an
application that does not find fonts, you may need to install Fontconfig
and to force an update of its font cache by running:

@example
guix install fontconfig
fc-cache -rv
@end example

To display text written in Chinese languages, Japanese, or Korean in
graphical applications, consider installing
@code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}.  The former
has multiple outputs, one per language family (@pxref{Packages with
Multiple Outputs}).  For instance, the following command installs fonts
for Chinese languages:

@example
guix install font-adobe-source-han-sans:cn
@end example

@cindex @code{xterm}
Older programs such as @command{xterm} do not use Fontconfig and instead
rely on server-side font rendering.  Such programs require to specify a
full name of a font using XLFD (X Logical Font Description), like this:

@example
-*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1
@end example

To be able to use such full names for the TrueType fonts installed in
your Guix profile, you need to extend the font path of the X server:

@c Note: 'xset' does not accept symlinks so the trick below arranges to
@c get at the real directory.  See <https://bugs.gnu.org/30655>.
@example
xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir))
@end example

@cindex @code{xlsfonts}
After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
to make sure your TrueType fonts are listed there.


@subsection X.509 Certificates

@cindex @code{nss-certs}
The @code{nss-certs} package provides X.509 certificates, which allow
programs to authenticate Web servers accessed over HTTPS.

When using Guix on a foreign distro, you can install this package and
define the relevant environment variables so that packages know where to
look for certificates.  @xref{X.509 Certificates}, for detailed
information.

@subsection Emacs Packages

@cindex @code{emacs}
When you install Emacs packages with Guix, the Elisp files are placed
under the @file{share/emacs/site-lisp/} directory of the profile in
which they are installed.  The Elisp libraries are made available to
Emacs through the @env{EMACSLOADPATH} environment variable, which is
set when installing Emacs itself.

Additionally, autoload definitions are automatically evaluated at the
initialization of Emacs, by the Guix-specific
@code{guix-emacs-autoload-packages} procedure.  If, for some reason, you
want to avoid auto-loading the Emacs packages installed with Guix, you
can do so by running Emacs with the @option{--no-site-file} option
(@pxref{Init File,,, emacs, The GNU Emacs Manual}).


@node Upgrading Guix
@section Upgrading Guix

@cindex Upgrading Guix, on a foreign distro

To upgrade Guix, run:

@example
guix pull
@end example

@xref{Invoking guix pull}, for more information.

@cindex upgrading Guix for the root user, on a foreign distro
@cindex upgrading the Guix daemon, on a foreign distro
@cindex @command{guix pull} for the root user, on a foreign distro

On a foreign distro, you can upgrade the build daemon by running:

@example
sudo -i guix pull
@end example

@noindent
followed by (assuming your distro uses the systemd service management
tool):

@example
systemctl restart guix-daemon.service
@end example

On Guix System, upgrading the daemon is achieved by reconfiguring the
system (@pxref{Invoking guix system, @code{guix system reconfigure}}).

@c TODO What else?

@c *********************************************************************
@node System Installation
@chapter System Installation