guix.texi

The daemon also honors the @code{http_proxy} environment variable for
HTTP 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 @code{--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 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} file typically looks like this:

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

      (build-machine
        (name "meeps.example.org")
        (system "mips64el-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} architecture and one for the @code{mips64el}
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 system
The system type of the remote machine---e.g., @code{"x86_64-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{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 Guile and the Guix modules are
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.

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
@code{--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 @code{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{Invoking guix build, @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 @code{--no-substitutes}, clients can still
explicitly enable substitution @i{via} the @code{set-build-options}
remote procedure call (@pxref{The Store}).

@item --substitute-urls=@var{urls}
@anchor{daemon-substitute-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}).

@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 @code{--cores} option of @command{guix build} (@pxref{Invoking
guix build}).

The effect is to define the @code{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, @code{--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, @code{--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 @code{--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 @code{--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 --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 ``yes'', the GC will keep the outputs of any live derivation
available in the store---the @code{.drv} files.  The default is ``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 ``yes'', as is the case by default, the GC keeps
derivations---i.e., @code{.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 ``no'' saves a bit of disk space.

In this way, setting @code{--gc-keep-derivations} to ``yes'' causes liveness
to flow from outputs to derivations, and setting @code{--gc-keep-outputs} to
``yes'' causes liveness to flow from derivations to outputs.  When both are
set to ``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 @code{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
@code{@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 @code{GUIX_DAEMON_SOCKET} environment variable
(@pxref{The Store, @code{GUIX_DAEMON_SOCKET}}).

@quotation Note
The daemon protocol is @emph{unauthenticated and unencrypted}.  Using
@code{--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 @code{--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 @code{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
110@tie{}MiB.  Alternatively, the @code{glibc-utf8-locales} is smaller but
limited to a few UTF-8 locales.

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

@enumerate
@item
@code{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
provided by foreign distros.  Thus, using @code{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 @code{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-ttf}.

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.

@cindex @code{fc-cache}
@cindex font cache
After installing fonts you may have to refresh the font cache to use
them in applications.  The same applies when applications installed via
Guix do not seem to find fonts.  To force rebuilding of the font cache
run @code{fc-cache -rv}.  The @code{fc-cache} command is provided by
the @code{fontconfig} package.

@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 may be placed
either in @file{$HOME/.guix-profile/share/emacs/site-lisp/} or in
sub-directories of
@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}.  The latter
directory exists because potentially there may exist thousands of Emacs
packages and storing all their files in a single directory may not be
reliable (because of name conflicts).  So we think using a separate
directory for each package is a good idea.  It is very similar to how
the Emacs package system organizes the file structure (@pxref{Package
Files,,, emacs, The GNU Emacs Manual}).

By default, Emacs (installed with Guix) ``knows'' where these packages
are placed, so you do not need to perform any configuration.  If, for
some reason, you want to avoid auto-loading Emacs packages installed
with Guix, you can do so by running Emacs with @code{--no-site-file}
option (@pxref{Init File,,, emacs, The GNU Emacs Manual}).

@subsection The GCC toolchain

@cindex GCC
@cindex ld-wrapper

Guix offers individual compiler packages such as @code{gcc} but if you
are in need of a complete toolchain for compiling and linking source
code what you really want is the @code{gcc-toolchain} package.  This
package provides a complete GCC toolchain for C/C++ development,
including GCC itself, the GNU C Library (headers and binaries, plus
debugging symbols in the @code{debug} output), Binutils, and a linker
wrapper.

The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
passed to the linker, add corresponding @code{-rpath} arguments, and
invoke the actual linker with this new set of arguments.  You can instruct the
wrapper to refuse to link against libraries not in the store by setting the
@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}.

@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

@cindex installing Guix System
@cindex Guix System, installation
This section explains how to install Guix System
on a machine.  Guix, as a package manager, can
also be installed on top of a running GNU/Linux system,
@pxref{Installation}.

@ifinfo
@quotation Note
@c This paragraph is for people reading this from tty2 of the
@c installation image.
You are reading this documentation with an Info reader.  For details on
how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU
Info}.  Hit @kbd{l} afterwards to come back here.

Alternately, run @command{info info} in another tty to keep the manual
available.
@end quotation
@end ifinfo

@menu
* Limitations::                 What you can expect.
* Hardware Considerations::     Supported hardware.
* USB Stick and DVD Installation::  Preparing the installation medium.
* Preparing for Installation::  Networking, partitioning, etc.
* Guided Graphical Installation::  Easy graphical installation.
* Manual Installation::         Manual installation for wizards.
* After System Installation::   When installation succeeded.
* Installing Guix in a VM::     Guix System playground.
* Building the Installation Image::  How this comes to be.
@end menu

@node Limitations
@section Limitations

We consider Guix System to be ready for a wide range of ``desktop'' and server
use cases.  The reliability guarantees it provides---transactional upgrades
and rollbacks, reproducibility---make it a solid foundation.

Nevertheless, before you proceed with the installation, be aware of the
following noteworthy limitations applicable to version @value{VERSION}:

@itemize
@item
Support for the Logical Volume Manager (LVM) is missing.

@item
More and more system services are provided (@pxref{Services}), but some
may be missing.

@item
GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
as well as a number of X11 window managers.  However, KDE is currently
missing.
@end itemize

More than a disclaimer, this is an invitation to report issues (and success
stories!), and to join us in improving it.  @xref{Contributing}, for more
info.


@node Hardware Considerations
@section Hardware Considerations

@cindex hardware support on Guix System
GNU@tie{}Guix focuses on respecting the user's computing freedom.  It
builds around the kernel Linux-libre, which means that only hardware for
which free software drivers and firmware exist is supported.  Nowadays,
a wide range of off-the-shelf hardware is supported on
GNU/Linux-libre---from keyboards to graphics cards to scanners and
Ethernet controllers.  Unfortunately, there are still areas where
hardware vendors deny users control over their own computing, and such
hardware is not supported on Guix System.

@cindex WiFi, hardware support
One of the main areas where free drivers or firmware are lacking is WiFi
devices.  WiFi devices known to work include those using Atheros chips
(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
driver, and those using Broadcom/AirForce chips (BCM43xx with
Wireless-Core Revision 5), which corresponds to the @code{b43-open}
Linux-libre driver.  Free firmware exists for both and is available
out-of-the-box on Guix System, as part of @code{%base-firmware}
(@pxref{operating-system Reference, @code{firmware}}).

@cindex RYF, Respects Your Freedom
The @uref{https://www.fsf.org/, Free Software Foundation} runs
@uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a
certification program for hardware products that respect your freedom
and your privacy and ensure that you have control over your device.  We
encourage you to check the list of RYF-certified devices.

Another useful resource is the @uref{https://www.h-node.org/, H-Node}
web site.  It contains a catalog of hardware devices with information
about their support in GNU/Linux.


@node USB Stick and DVD Installation
@section USB Stick and DVD Installation

An ISO-9660 installation image that can be written to a USB stick or
burnt to a DVD can be downloaded from
@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.@var{system}.iso.xz},
where @var{system} is one of:

@table @code
@item x86_64-linux
for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;

@item i686-linux
for a 32-bit GNU/Linux system on Intel-compatible CPUs.
@end table

@c start duplication of authentication part from ``Binary Installation''
Make sure to download the associated @file{.sig} file and to verify the
authenticity of the image against it, along these lines:

@example
$ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig
$ gpg --verify guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig
@end example

If that command fails because you do not have the required public key,
then run this command to import it:

@example
$ wget @value{OPENPGP-SIGNING-KEY-URL} \
      -qO - | gpg --import -
@end example

@noindent
and rerun the @code{gpg --verify} command.

Take note that a warning like ``This key is not certified with a trusted
signature!'' is normal.

@c end duplication

This image contains the tools necessary for an installation.
It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.

@unnumberedsubsec Copying to a USB Stick

To copy the image to a USB stick, follow these steps:

@enumerate
@item
Decompress the image using the @command{xz} command:

@example
xz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz
@end example

@item
Insert a USB stick of 1@tie{}GiB or more into your machine, and determine
its device name.  Assuming that the USB stick is known as @file{/dev/sdX},
copy the image with:

@example
dd if=guix-system-install-@value{VERSION}.@var{system}.iso of=/dev/sdX
sync
@end example

Access to @file{/dev/sdX} usually requires root privileges.
@end enumerate

@unnumberedsubsec Burning on a DVD

To copy the image to a DVD, follow these steps:

@enumerate
@item
Decompress the image using the @command{xz} command:

@example
xz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz
@end example

@item
Insert a blank DVD into your machine, and determine
its device name.  Assuming that the DVD drive is known as @file{/dev/srX},
copy the image with:

@example
growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.@var{system}.iso
@end example