guix.texi

@item --expose=@var{source}[=@var{target}]
For containers, expose the file system @var{source} from the host system
as the read-only file system @var{target} within the container.  If
@var{target} is not specified, @var{source} is used as the target mount
point in the container.

The example below spawns a Guile REPL in a container in which the user's
home directory is accessible read-only via the @file{/exchange}
directory:

@example
guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
@end example

@item --share=@var{source}[=@var{target}]
For containers, share the file system @var{source} from the host system
as the writable file system @var{target} within the container.  If
@var{target} is not specified, @var{source} is used as the target mount
point in the container.

The example below spawns a Guile REPL in a container in which the user's
home directory is accessible for both reading and writing via the
@file{/exchange} directory:

@example
guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile
@end example
@end table

@command{guix environment}
also supports all of the common build options that @command{guix
build} supports (@pxref{Common Build Options}).


@node Invoking guix publish
@section Invoking @command{guix publish}

@cindex @command{guix publish}
The purpose of @command{guix publish} is to enable users to easily share
their store with others, who can then use it as a substitute server
(@pxref{Substitutes}).

When @command{guix publish} runs, it spawns an HTTP server which allows
anyone with network access to obtain substitutes from it.  This means
that any machine running Guix can also act as if it were a build farm,
since the HTTP interface is compatible with Hydra, the software behind
the @code{hydra.gnu.org} build farm.

For security, each substitute is signed, allowing recipients to check
their authenticity and integrity (@pxref{Substitutes}).  Because
@command{guix publish} uses the signing key of the system, which is only
readable by the system administrator, it must be started as root; the
@code{--user} option makes it drop root privileges early on.

The signing key pair must be generated before @command{guix publish} is
launched, using @command{guix archive --generate-key} (@pxref{Invoking
guix archive}).

The general syntax is:

@example
guix publish @var{options}@dots{}
@end example

Running @command{guix publish} without any additional arguments will
spawn an HTTP server on port 8080:

@example
guix publish
@end example

Once a publishing server has been authorized (@pxref{Invoking guix
archive}), the daemon may download substitutes from it:

@example
guix-daemon --substitute-urls=http://example.org:8080
@end example

By default, @command{guix publish} compresses archives on the fly as it
serves them.  This ``on-the-fly'' mode is convenient in that it requires
no setup and is immediately available.  However, when serving lots of
clients, we recommend using the @option{--cache} option, which enables
caching of the archives before they are sent to clients---see below for
details.  The @command{guix weather} command provides a handy way to
check what a server provides (@pxref{Invoking guix weather}).

As a bonus, @command{guix publish} also serves as a content-addressed
mirror for source files referenced in @code{origin} records
(@pxref{origin Reference}).  For instance, assuming @command{guix
publish} is running on @code{example.org}, the following URL returns the
raw @file{hello-2.10.tar.gz} file with the given SHA256 hash
(represented in @code{nix-base32} format, @pxref{Invoking guix hash}):

@example
http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i
@end example

Obviously, these URLs only work for files that are in the store; in
other cases, they return 404 (``Not Found'').

The following options are available:

@table @code
@item --port=@var{port}
@itemx -p @var{port}
Listen for HTTP requests on @var{port}.

@item --listen=@var{host}
Listen on the network interface for @var{host}.  The default is to
accept connections from any interface.

@item --user=@var{user}
@itemx -u @var{user}
Change privileges to @var{user} as soon as possible---i.e., once the
server socket is open and the signing key has been read.

@item --compression[=@var{level}]
@itemx -C [@var{level}]
Compress data using the given @var{level}.  When @var{level} is zero,
disable compression.  The range 1 to 9 corresponds to different gzip
compression levels: 1 is the fastest, and 9 is the best (CPU-intensive).
The default is 3.

Unless @option{--cache} is used, compression occurs on the fly and
the compressed streams are not
cached.  Thus, to reduce load on the machine that runs @command{guix
publish}, it may be a good idea to choose a low compression level, to
run @command{guix publish} behind a caching proxy, or to use
@option{--cache}.  Using @option{--cache} has the advantage that it
allows @command{guix publish} to add @code{Content-Length} HTTP header
to its responses.

@item --cache=@var{directory}
@itemx -c @var{directory}
Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory}
and only serve archives that are in cache.

When this option is omitted, archives and meta-data are created
on-the-fly.  This can reduce the available bandwidth, especially when
compression is enabled, since this may become CPU-bound.  Another
drawback of the default mode is that the length of archives is not known
in advance, so @command{guix publish} does not add a
@code{Content-Length} HTTP header to its responses, which in turn
prevents clients from knowing the amount of data being downloaded.

Conversely, when @option{--cache} is used, the first request for a store
item (@i{via} a @code{.narinfo} URL) returns 404 and triggers a
background process to @dfn{bake} the archive---computing its
@code{.narinfo} and compressing the archive, if needed.  Once the
archive is cached in @var{directory}, subsequent requests succeed and
are served directly from the cache, which guarantees that clients get
the best possible bandwidth.

The ``baking'' process is performed by worker threads.  By default, one
thread per CPU core is created, but this can be customized.  See
@option{--workers} below.

When @option{--ttl} is used, cached entries are automatically deleted
when they have expired.

@item --workers=@var{N}
When @option{--cache} is used, request the allocation of @var{N} worker
threads to ``bake'' archives.

@item --ttl=@var{ttl}
Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
(TTL) of @var{ttl}.  @var{ttl} must denote a duration: @code{5d} means 5
days, @code{1m} means 1 month, and so on.

This allows the user's Guix to keep substitute information in cache for
@var{ttl}.  However, note that @code{guix publish} does not itself
guarantee that the store items it provides will indeed remain available
for as long as @var{ttl}.

Additionally, when @option{--cache} is used, cached entries that have
not been accessed for @var{ttl} and that no longer have a corresponding
item in the store, may be deleted.

@item --nar-path=@var{path}
Use @var{path} as the prefix for the URLs of ``nar'' files
(@pxref{Invoking guix archive, normalized archives}).

By default, nars are served at a URL such as
@code{/nar/gzip/@dots{}-coreutils-8.25}.  This option allows you to
change the @code{/nar} part to @var{path}.

@item --public-key=@var{file}
@itemx --private-key=@var{file}
Use the specific @var{file}s as the public/private key pair used to sign
the store items being published.

The files must correspond to the same key pair (the private key is used
for signing and the public key is merely advertised in the signature
metadata).  They must contain keys in the canonical s-expression format
as produced by @command{guix archive --generate-key} (@pxref{Invoking
guix archive}).  By default, @file{/etc/guix/signing-key.pub} and
@file{/etc/guix/signing-key.sec} are used.

@item --repl[=@var{port}]
@itemx -r [@var{port}]
Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
Reference Manual}) on @var{port} (37146 by default).  This is used
primarily for debugging a running @command{guix publish} server.
@end table

Enabling @command{guix publish} on a GuixSD system is a one-liner: just
instantiate a @code{guix-publish-service-type} service in the @code{services} field
of the @code{operating-system} declaration (@pxref{guix-publish-service-type,
@code{guix-publish-service-type}}).

If you are instead running Guix on a ``foreign distro'', follow these
instructions:”

@itemize
@item
If your host distro uses the systemd init system:

@example
# ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
        /etc/systemd/system/
# systemctl start guix-publish && systemctl enable guix-publish
@end example

@item
If your host distro uses the Upstart init system:

@example
# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
# start guix-publish
@end example

@item
Otherwise, proceed similarly with your distro's init system.
@end itemize

@node Invoking guix challenge
@section Invoking @command{guix challenge}

@cindex reproducible builds
@cindex verifiable builds
@cindex @command{guix challenge}
@cindex challenge
Do the binaries provided by this server really correspond to the source
code it claims to build?  Is a package build process deterministic?
These are the questions the @command{guix challenge} command attempts to
answer.

The former is obviously an important question: Before using a substitute
server (@pxref{Substitutes}), one had better @emph{verify} that it
provides the right binaries, and thus @emph{challenge} it.  The latter
is what enables the former: If package builds are deterministic, then
independent builds of the package should yield the exact same result,
bit for bit; if a server provides a binary different from the one
obtained locally, it may be either corrupt or malicious.

We know that the hash that shows up in @file{/gnu/store} file names is
the hash of all the inputs of the process that built the file or
directory---compilers, libraries, build scripts,
etc. (@pxref{Introduction}).  Assuming deterministic build processes,
one store file name should map to exactly one build output.
@command{guix challenge} checks whether there is, indeed, a single
mapping by comparing the build outputs of several independent builds of
any given store item.

The command output looks like this:

@smallexample
$ guix challenge --substitute-urls="https://hydra.gnu.org https://guix.example.org"
updating list of substitutes from 'https://hydra.gnu.org'... 100.0%
updating list of substitutes from 'https://guix.example.org'... 100.0%
/gnu/store/@dots{}-openssl-1.0.2d contents differ:
  local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
  https://hydra.gnu.org/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
  https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
/gnu/store/@dots{}-git-2.5.0 contents differ:
  local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
  https://hydra.gnu.org/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
  https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
/gnu/store/@dots{}-pius-2.1.1 contents differ:
  local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
  https://hydra.gnu.org/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
  https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs

@dots{}

6,406 store items were analyzed:
  - 4,749 (74.1%) were identical
  - 525 (8.2%) differed
  - 1,132 (17.7%) were inconclusive
@end smallexample

@noindent
In this example, @command{guix challenge} first scans the store to
determine the set of locally-built derivations---as opposed to store
items that were downloaded from a substitute server---and then queries
all the substitute servers.  It then reports those store items for which
the servers obtained a result different from the local build.

@cindex non-determinism, in package builds
As an example, @code{guix.example.org} always gets a different answer.
Conversely, @code{hydra.gnu.org} agrees with local builds, except in the
case of Git.  This might indicate that the build process of Git is
non-deterministic, meaning that its output varies as a function of
various things that Guix does not fully control, in spite of building
packages in isolated environments (@pxref{Features}).  Most common
sources of non-determinism include the addition of timestamps in build
results, the inclusion of random numbers, and directory listings sorted
by inode number.  See @uref{https://reproducible-builds.org/docs/}, for
more information.

To find out what is wrong with this Git binary, we can do something along
these lines (@pxref{Invoking guix archive}):

@example
$ wget -q -O - https://hydra.gnu.org/nar/@dots{}-git-2.5.0 \
   | guix archive -x /tmp/git
$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
@end example

This command shows the difference between the files resulting from the
local build, and the files resulting from the build on
@code{hydra.gnu.org} (@pxref{Overview, Comparing and Merging Files,,
diffutils, Comparing and Merging Files}).  The @command{diff} command
works great for text files.  When binary files differ, a better option
is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
visualize differences for all kinds of files.

Once you have done that work, you can tell whether the differences are due
to a non-deterministic build process or to a malicious server.  We try
hard to remove sources of non-determinism in packages to make it easier
to verify substitutes, but of course, this is a process that
involves not just Guix, but a large part of the free software community.
In the meantime, @command{guix challenge} is one tool to help address
the problem.

If you are writing packages for Guix, you are encouraged to check
whether @code{hydra.gnu.org} and other substitute servers obtain the
same build result as you did with:

@example
$ guix challenge @var{package}
@end example

@noindent
where @var{package} is a package specification such as
@code{guile@@2.0} or @code{glibc:debug}.

The general syntax is:

@example
guix challenge @var{options} [@var{packages}@dots{}]
@end example

When a difference is found between the hash of a locally-built item and
that of a server-provided substitute, or among substitutes provided by
different servers, the command displays it as in the example above and
its exit code is 2 (other non-zero exit codes denote other kinds of
errors.)

The one option that matters is:

@table @code

@item --substitute-urls=@var{urls}
Consider @var{urls} the whitespace-separated list of substitute source
URLs to compare to.

@item --verbose
@itemx -v
Show details about matches (identical contents) in addition to
information about mismatches.

@end table

@node Invoking guix copy
@section Invoking @command{guix copy}

@cindex copy, of store items, over SSH
@cindex SSH, copy of store items
@cindex sharing store items across machines
@cindex transferring store items across machines
The @command{guix copy} command copies items from the store of one
machine to that of another machine over a secure shell (SSH)
connection@footnote{This command is available only when Guile-SSH was
found.  @xref{Requirements}, for details.}.  For example, the following
command copies the @code{coreutils} package, the user's profile, and all
their dependencies over to @var{host}, logged in as @var{user}:

@example
guix copy --to=@var{user}@@@var{host} \
          coreutils `readlink -f ~/.guix-profile`
@end example

If some of the items to be copied are already present on @var{host},
they are not actually sent.

The command below retrieves @code{libreoffice} and @code{gimp} from
@var{host}, assuming they are available there:

@example
guix copy --from=@var{host} libreoffice gimp
@end example

The SSH connection is established using the Guile-SSH client, which is
compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
@file{~/.ssh/config}, and uses the SSH agent for authentication.

The key used to sign items that are sent must be accepted by the remote
machine.  Likewise, the key used by the remote machine to sign items you
are retrieving must be in @file{/etc/guix/acl} so it is accepted by your
own daemon.  @xref{Invoking guix archive}, for more information about
store item authentication.

The general syntax is:

@example
guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
@end example

You must always specify one of the following options:

@table @code
@item --to=@var{spec}
@itemx --from=@var{spec}
Specify the host to send to or receive from.  @var{spec} must be an SSH
spec such as @code{example.org}, @code{charlie@@example.org}, or
@code{charlie@@example.org:2222}.
@end table

The @var{items} can be either package names, such as @code{gimp}, or
store items, such as @file{/gnu/store/@dots{}-idutils-4.6}.

When specifying the name of a package to send, it is first built if
needed, unless @option{--dry-run} was specified.  Common build options
are supported (@pxref{Common Build Options}).


@node Invoking guix container
@section Invoking @command{guix container}
@cindex container
@cindex @command{guix container}
@quotation Note
As of version @value{VERSION}, this tool is experimental.  The interface
is subject to radical change in the future.
@end quotation

The purpose of @command{guix container} is to manipulate processes
running within an isolated environment, commonly known as a
``container'', typically created by the @command{guix environment}
(@pxref{Invoking guix environment}) and @command{guix system container}
(@pxref{Invoking guix system}) commands.

The general syntax is:

@example
guix container @var{action} @var{options}@dots{}
@end example

@var{action} specifies the operation to perform with a container, and
@var{options} specifies the context-specific arguments for the action.

The following actions are available:

@table @code
@item exec
Execute a command within the context of a running container.

The syntax is:

@example
guix container exec @var{pid} @var{program} @var{arguments}@dots{}
@end example

@var{pid} specifies the process ID of the running container.
@var{program} specifies an executable file name within the root file
system of the container.  @var{arguments} are the additional options that
will be passed to @var{program}.

The following command launches an interactive login shell inside a
GuixSD container, started by @command{guix system container}, and whose
process ID is 9001:

@example
guix container exec 9001 /run/current-system/profile/bin/bash --login
@end example

Note that the @var{pid} cannot be the parent process of a container.  It
must be PID 1 of the container or one of its child processes.

@end table

@node Invoking guix weather
@section Invoking @command{guix weather}

Occasionally you're grumpy because substitutes are lacking and you end
up building packages by yourself (@pxref{Substitutes}).  The
@command{guix weather} command reports on substitute availability on the
specified servers so you can have an idea of whether you'll be grumpy
today.  It can sometimes be useful info as a user, but it is primarily
useful to people running @command{guix publish} (@pxref{Invoking guix
publish}).

@cindex statistics, for substitutes
@cindex availability of substitutes
@cindex substitute availability
@cindex weather, substitute availability
Here's a sample run:

@example
$ guix weather --substitute-urls=https://guix.example.org
computing 5,872 package derivations for x86_64-linux...
looking for 6,128 store items on https://guix.example.org..
updating list of substitutes from 'https://guix.example.org'... 100.0%
https://guix.example.org
  43.4% substitutes available (2,658 out of 6,128)
  7,032.5 MiB of nars (compressed)
  19,824.2 MiB on disk (uncompressed)
  0.030 seconds per request (182.9 seconds in total)
  33.5 requests per second
@end example

As you can see, it reports the fraction of all the packages for which
substitutes are available on the server---regardless of whether
substitutes are enabled, and regardless of whether this server's signing
key is authorized.  It also reports the size of the compressed archives
(``nars'') provided by the server, the size the corresponding store
items occupy in the store (assuming deduplication is turned off), and
the server's throughput.

To achieve that, @command{guix weather} queries over HTTP(S) meta-data
(@dfn{narinfos}) for all the relevant store items.  Like @command{guix
challenge}, it ignores signatures on those substitutes, which is
innocuous since the command only gathers statistics and cannot install
those substitutes.

Among other things, it is possible to query specific system types and
specific package sets.  The available options are listed below.

@table @code
@item --substitute-urls=@var{urls}
@var{urls} is the space-separated list of substitute server URLs to
query.  When this option is omitted, the default set of substitute
servers is queried.

@item --system=@var{system}
@itemx -s @var{system}
Query substitutes for @var{system}---e.g., @code{aarch64-linux}.  This
option can be repeated, in which case @command{guix weather} will query
substitutes for several system types.

@item --manifest=@var{file}
Instead of querying substitutes for all the packages, only ask for those
specified in @var{file}.  @var{file} must contain a @dfn{manifest}, as
with the @code{-m} option of @command{guix package} (@pxref{Invoking
guix package}).
@end table


@c *********************************************************************
@node GNU Distribution
@chapter GNU Distribution

@cindex Guix System Distribution
@cindex GuixSD
Guix comes with a distribution of the GNU system consisting entirely of
free software@footnote{The term ``free'' here refers to the
@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
users of that software}.}.  The
distribution can be installed on its own (@pxref{System Installation}),
but it is also possible to install Guix as a package manager on top of
an installed GNU/Linux system (@pxref{Installation}).  To distinguish
between the two, we refer to the standalone distribution as the Guix
System Distribution, or GuixSD.

The distribution provides core GNU packages such as GNU libc, GCC, and
Binutils, as well as many GNU and non-GNU applications.  The complete
list of available packages can be browsed
@url{http://www.gnu.org/software/guix/packages,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):

@example
guix package --list-available
@end example

Our goal is to provide a practical 100% free software distribution of
Linux-based and other variants of GNU, with a focus on the promotion and
tight integration of GNU components, and an emphasis on programs and
tools that help users exert that freedom.

Packages are currently available on the following platforms:

@table @code

@item x86_64-linux
Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;

@item i686-linux
Intel 32-bit architecture (IA32), Linux-Libre kernel;

@item armhf-linux
ARMv7-A architecture with hard float, Thumb-2 and NEON,
using the EABI hard-float application binary interface (ABI),
and Linux-Libre kernel.

@item aarch64-linux
little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.  This is
currently in an experimental stage, with limited support.
@xref{Contributing}, for how to help!

@item mips64el-linux
little-endian 64-bit MIPS processors, specifically the Loongson series,
n32 ABI, and Linux-Libre kernel.

@end table

GuixSD itself is currently only available on @code{i686} and @code{x86_64}.

@noindent
For information on porting to other architectures or kernels,
@pxref{Porting}.

@menu
* System Installation::         Installing the whole operating system.
* System Configuration::        Configuring the operating system.
* Documentation::                Browsing software user manuals.
* Installing Debugging Files::  Feeding the debugger.
* Security Updates::            Deploying security fixes quickly.
* Package Modules::             Packages from the programmer's viewpoint.
* Packaging Guidelines::        Growing the distribution.
* Bootstrapping::               GNU/Linux built from scratch.
* Porting::                     Targeting another platform or kernel.
@end menu

Building this distribution is a cooperative effort, and you are invited
to join!  @xref{Contributing}, for information about how you can help.

@node System Installation
@section System Installation

@cindex installing GuixSD
@cindex Guix System Distribution
This section explains how to install the Guix System Distribution (GuixSD)
on a machine.  The Guix 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 Installation::      Preparing the installation medium.
* DVD Installation::            Preparing the installation medium.
* Preparing for Installation::  Networking, partitioning, etc.
* Proceeding with the Installation::  The real thing.
* Installing GuixSD in a VM::   GuixSD playground.
* Building the Installation Image::  How this comes to be.
@end menu

@node Limitations
@subsection Limitations

As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
not production-ready.  It may contain bugs and lack important
features.  Thus, if you are looking for a stable production system that
respects your freedom as a computer user, a good solution at this point
is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
the more established GNU/Linux distributions}.  We hope you can soon switch
to the GuixSD without fear, of course.  In the meantime, you can
also keep using your distribution and try out the package manager on top
of it (@pxref{Installation}).

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

@itemize
@item
The installation process does not include a graphical user interface and
requires familiarity with GNU/Linux (see the following subsections to
get a feel of what that means.)

@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
More than 5,300 packages are available, but you may
occasionally find that a useful package is missing.

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

You have been warned!  But 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
@subsection Hardware Considerations

@cindex hardware support on GuixSD
GNU@tie{}GuixSD 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 GuixSD.

@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 GuixSD, as part of @var{%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 Installation
@subsection USB Stick Installation

An installation image for USB sticks can be downloaded from
@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.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 ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.xz.sig
$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.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
$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example

@noindent
and rerun the @code{gpg --verify} command.
@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.

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

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

@example
xz -d guixsd-install-@value{VERSION}.@var{system}.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=guixsd-install-@value{VERSION}.x86_64 of=/dev/sdX
sync
@end example

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

Once this is done, you should be able to reboot the system and boot from
the USB stick.  The latter usually requires you to get in the BIOS or
UEFI boot menu, where you can choose to boot from the USB stick.

@xref{Installing GuixSD in a VM}, if, instead, you would like to install
GuixSD in a virtual machine (VM).

@node DVD Installation
@subsection DVD Installation

An installation image for DVDs can be downloaded from
@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.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 ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.xz.sig
$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.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
$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example

@noindent
and rerun the @code{gpg --verify} command.
@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.

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

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

@example
xz -d guixsd-install-@value{VERSION}.@var{system}.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=guixsd-install-@value{VERSION}.x86_64
@end example

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

Once this is done, you should be able to reboot the system and boot from
the DVD.  The latter usually requires you to get in the BIOS or
UEFI boot menu, where you can choose to boot from the DVD.

@xref{Installing GuixSD in a VM}, if, instead, you would like to install
GuixSD in a virtual machine (VM).

@node Preparing for Installation
@subsection Preparing for Installation

Once you have successfully booted your computer using the installation medium,
you should end up with a root prompt.  Several console TTYs are configured
and can be used to run commands as root.  TTY2 shows this documentation,
browsable using the Info reader commands (@pxref{Top,,, info-stnd,
Stand-alone GNU Info}).  The installation system runs the GPM mouse
daemon, which allows you to select text with the left mouse button and
to paste it with the middle button.

@quotation Note
Installation requires access to the Internet so that any missing
dependencies of your system configuration can be downloaded.  See the
``Networking'' section below.
@end quotation

The installation system includes many common tools needed for this task.
But it is also a full-blown GuixSD system, which means that you can
install additional packages, should you need it, using @command{guix
package} (@pxref{Invoking guix package}).

@subsubsection Keyboard Layout

@cindex keyboard layout
The installation image uses the US qwerty keyboard layout.  If you want
to change it, you can use the @command{loadkeys} command.  For example,
the following command selects the Dvorak keyboard layout:

@example
loadkeys dvorak
@end example

See the files under @file{/run/current-system/profile/share/keymaps} for
a list of available keyboard layouts.  Run @command{man loadkeys} for
more information.

@subsubsection Networking

Run the following command see what your network interfaces are called:

@example
ifconfig -a
@end example

@noindent
@dots{} or, using the GNU/Linux-specific @command{ip} command:

@example
ip a
@end example

@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
Wired interfaces have a name starting with @samp{e}; for example, the
interface corresponding to the first on-board Ethernet controller is
called @samp{eno1}.  Wireless interfaces have a name starting with
@samp{w}, like @samp{w1p2s0}.

@table @asis
@item Wired connection
To configure a wired network run the following command, substituting
@var{interface} with the name of the wired interface you want to use.

@example
ifconfig @var{interface} up
@end example

@item Wireless connection
@cindex wireless
@cindex WiFi
To configure wireless networking, you can create a configuration file
for the @command{wpa_supplicant} configuration tool (its location is not
important) using one of the available text editors such as
@command{zile}:

@example
zile wpa_supplicant.conf
@end example

As an example, the following stanza can go to this file and will work
for many wireless networks, provided you give the actual SSID and
passphrase for the network you are connecting to:

@example
network=@{
  ssid="@var{my-ssid}"
  key_mgmt=WPA-PSK
  psk="the network's secret passphrase"
@}
@end example

Start the wireless service and run it in the background with the
following command (substitute @var{interface} with the name of the
network interface you want to use):

@example
wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
@end example

Run @command{man wpa_supplicant} for more information.
@end table

@cindex DHCP
At this point, you need to acquire an IP address.  On a network where IP
addresses are automatically assigned @i{via} DHCP, you can run:

@example
dhclient -v @var{interface}
@end example

Try to ping a server to see if networking is up and running:

@example
ping -c 3 gnu.org