guix.texi

working directory are mounted:

@example
guix environment --ad-hoc --container guile -- guile
@end example

@quotation Note
The @code{--container} option requires Linux-libre 3.19 or newer.
@end quotation

The available options are summarized below.

@table @code
@item --root=@var{file}
@itemx -r @var{file}
@cindex persistent environment
@cindex garbage collector root, for environments
Make @var{file} a symlink to the profile for this environment, and
register it as a garbage collector root.

This is useful if you want to protect your environment from garbage
collection, to make it ``persistent''.

When this option is omitted, the environment is protected from garbage
collection only for the duration of the @command{guix environment}
session.  This means that next time you recreate the same environment,
you could have to rebuild or re-download packages.

@item --expression=@var{expr}
@itemx -e @var{expr}
Create an environment for the package or list of packages that
@var{expr} evaluates to.

For example, running:

@example
guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
@end example

starts a shell with the environment for this specific variant of the
PETSc package.

Running:

@example
guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
@end example

starts a shell with all the GuixSD base packages available.

The above commands only the use default output of the given packages.
To select other outputs, two element tuples can be specified:

@example
guix environment --ad-hoc -e '(list (@ (gnu packages bash) bash) "include")'
@end example

@item --load=@var{file}
@itemx -l @var{file}
Create an environment for the package or list of packages that the code
within @var{file} evaluates to.

As an example, @var{file} might contain a definition like this
(@pxref{Defining Packages}):

@example
@verbatiminclude environment-gdb.scm
@end example

@item --ad-hoc
Include all specified packages in the resulting environment, as if an
@i{ad hoc} package were defined with them as inputs.  This option is
useful for quickly creating an environment without having to write a
package expression to contain the desired inputs.

For instance, the command:

@example
guix environment --ad-hoc guile guile-sdl -- guile
@end example

runs @command{guile} in an environment where Guile and Guile-SDL are
available.

Note that this example implicitly asks for the default output of
@code{guile} and @code{guile-sdl}, but it is possible to ask for a
specific output---e.g., @code{glib:bin} asks for the @code{bin} output
of @code{glib} (@pxref{Packages with Multiple Outputs}).

This option may be composed with the default behavior of @command{guix
environment}.  Packages appearing before @code{--ad-hoc} are interpreted
as packages whose dependencies will be added to the environment, the
default behavior.  Packages appearing after are interpreted as packages
that will be added to the environment directly.

@item --pure
Unset existing environment variables when building the new environment.
This has the effect of creating an environment in which search paths
only contain package inputs.

@item --search-paths
Display the environment variable definitions that make up the
environment.

@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}.

@item --container
@itemx -C
@cindex container
Run @var{command} within an isolated container.  The current working
directory outside the container is mapped inside the container.
Additionally, a dummy home directory is created that matches the current
user's home directory, and @file{/etc/passwd} is configured accordingly.
The spawned process runs as the current user outside the container, but
has root privileges in the context of the container.

@item --network
@itemx -N
For containers, share the network namespace with the host system.
Containers created without this flag only have access to the loopback
device.

@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 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 guile -- guile
@end example
@end table

It 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

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.

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, or to
run @command{guix publish} behind a caching proxy.

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

@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
add a call to @code{guix-publish-service} in the @code{services} field
of the @code{operating-system} declaration (@pxref{guix-publish-service,
@code{guix-publish-service}}).

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

@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

@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 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.
* 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.
* 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
Few system services are currently supported out-of-the-box
(@pxref{Services}).

@item
More than 4,000 packages are available, but you may
occasionally find that a useful package is missing.

@item
GNOME, Xfce, 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-usb-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-usb-install-@value{VERSION}.@var{system}.xz.sig
$ gpg --verify guixsd-usb-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 a single partition with the tools necessary for an
installation.  It is meant to be copied @emph{as is} to a large-enough
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 guixsd-usb-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-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
@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' 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 Preparing for Installation
@subsection Preparing for Installation

Once you have successfully booted the image on the USB stick, 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
@end example

Setting up network access is almost always a requirement because the
image does not contain all the software and tools that may be needed.

@subsubsection Disk Partitioning

Unless this has already been done, the next step is to partition, and
then format the target partition(s).

The installation image includes several partitioning tools, including
Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
@command{fdisk}, and @command{cfdisk}.  Run it and set up your disk with
the partition layout you want:

@example
cfdisk
@end example

Once you are done partitioning the target hard disk drive, you have to
create a file system on the relevant partition(s)@footnote{Currently
GuixSD only supports ext4 and btrfs file systems.  In particular, code
that reads partition UUIDs and labels only works for these file system
types.}.

Preferably, assign partitions a label so that you can easily and
reliably refer to them in @code{file-system} declarations (@pxref{File
Systems}).  This is typically done using the @code{-L} option of
@command{mkfs.ext4} and related commands.  So, assuming the target root
partition lives at @file{/dev/sda1}, a file system with the label
@code{my-root} can be created with:

@example
mkfs.ext4 -L my-root /dev/sda1
@end example

@cindex encrypted disk
If you are instead planning to encrypt the root partition, you can use
the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
@code{man cryptsetup}} for more information.)  Assuming you want to
store the root partition on @file{/dev/sda1}, the command sequence would
be along these lines:

@example
cryptsetup luksFormat /dev/sda1
cryptsetup open --type luks /dev/sda1 my-partition
mkfs.ext4 -L my-root /dev/mapper/my-partition
@end example

Once that is done, mount the target root partition under @file{/mnt}
with a command like (again, assuming @code{my-root} is the label of the
root partition):

@example
mount LABEL=my-root /mnt
@end example

Finally, if you plan to use one or more swap partitions (@pxref{Memory
Concepts, swap space,, libc, The GNU C Library Reference Manual}), make
sure to initialize them with @command{mkswap}.  Assuming you have one
swap partition on @file{/dev/sda2}, you would run:

@example
mkswap /dev/sda2
swapon /dev/sda2
@end example

@node Proceeding with the Installation
@subsection Proceeding with the Installation

With the target partitions ready and the target root mounted on
@file{/mnt}, we're ready to go.  First, run:

@example
herd start cow-store /mnt
@end example

This makes @file{/gnu/store} copy-on-write, such that packages added to it
during the installation phase are written to the target disk on @file{/mnt}
rather than kept in memory.  This is necessary because the first phase of
the @command{guix system init} command (see below) entails downloads or
builds to @file{/gnu/store} which, initially, is an in-memory file system.

Next, you have to edit a file and
provide the declaration of the operating system to be installed.  To
that end, the installation system comes with three text editors: GNU nano
(@pxref{Top,,, nano, GNU nano Manual}), GNU Zile (an Emacs clone), and
nvi (a clone of the original BSD @command{vi} editor).
We strongly recommend storing that file on the target root file system, say,
as @file{/mnt/etc/config.scm}.  Failing to do that, you will have lost your
configuration file once you have rebooted into the newly-installed system.

@xref{Using the Configuration System}, for an overview of the
configuration file.  The example configurations discussed in that
section are available under @file{/etc/configuration} in the
installation image.  Thus, to get started with a system configuration
providing a graphical display server (a ``desktop'' system), you can run
something along these lines: