guix.texi

The @code{non-core} subset refers to the remaining packages.  It is
typically useful in cases where an update of the core packages would be
inconvenient.

@end table

In addition, @command{guix refresh} can be passed one or more package
names, as in this example:

@example
guix refresh -u emacs idutils
@end example

@noindent
The command above specifically updates the @code{emacs} and
@code{idutils} packages.  The @code{--select} option would have no
effect in this case.

When considering whether to upgrade a package, it is sometimes
convenient to know which packages would be affected by the upgrade and
should be checked for compatibility.  For this the following option may
be used when passing @command{guix refresh} one or more package names:

@table @code

@item --list-dependent
@itemx -l
List top-level dependent packages that would need to be rebuilt as a
result of upgrading one or more packages.

@end table

Be aware that the @code{--list-dependent} option only
@emph{approximates} the rebuilds that would be required as a result of
an upgrade.  More rebuilds might be required under some circumstances.

@example
$ guix refresh --list-dependent flex
Building the following 120 packages would ensure 213 dependent packages are rebuilt:
hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{}
@end example

The command above lists a set of packages that could be built to check
for compatibility with an upgraded @code{flex} package.

The following options can be used to customize GnuPG operation:

@table @code

@item --gpg=@var{command}
Use @var{command} as the GnuPG 2.x command.  @var{command} is searched
for in @code{$PATH}.

@item --key-download=@var{policy}
Handle missing OpenPGP keys according to @var{policy}, which may be one
of:

@table @code
@item always
Always download missing OpenPGP keys from the key server, and add them
to the user's GnuPG keyring.

@item never
Never try to download missing OpenPGP keys.  Instead just bail out.

@item interactive
When a package signed with an unknown OpenPGP key is encountered, ask
the user whether to download it or not.  This is the default behavior.
@end table

@item --key-server=@var{host}
Use @var{host} as the OpenPGP key server when importing a public key.

@end table

@node Invoking guix lint
@section Invoking @command{guix lint}
The @command{guix lint} is meant to help package developers avoid common
errors and use a consistent style.  It runs a few checks on a given set of
packages in order to find common mistakes in their definitions.

The general syntax is:

@example
guix lint @var{options} @var{package}@dots{}
@end example

If no package is given on the command line, then all packages are checked.
The @var{options} may be zero or more of the following:

@table @code

@item --checkers
@itemx -c
Only enable the checkers specified in a comma-separated list using the
names returned by @code{--list-checkers}.

@item --list-checkers
@itemx -l
List and describe all the available checkers that will be run on packages
and exit.

@end table

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

@cindex reproducible build environments
The purpose of @command{guix environment} is to assist hackers in
creating reproducible development environments without polluting their
package profile.  The @command{guix environment} tool takes one or more
packages, builds all of the necessary inputs, and creates a shell
environment to use them.

The general syntax is:

@example
guix environment @var{options} @var{package}@dots{}
@end example

The following examples spawns a new shell that is capable of building
the GNU Guile source code:

@example
guix environment guile
@end example

If the specified packages are not built yet, @command{guix environment}
automatically builds them.  The new shell's environment is an augmented
version of the environment that @command{guix environment} was run in.
It contains the necessary search paths for building the given package
added to the existing environment variables.  To create a ``pure''
environment in which the original environment variables have been unset,
use the @code{--pure} option.

Additionally, more than one package may be specified, in which case the
union of the inputs for the given packages are used.  For example, the
command below spawns a shell where all of the dependencies of both Guile
and Emacs are available:

@example
guix environment guile emacs
@end example

Sometimes an interactive shell session is not desired.  The
@code{--exec} option can be used to specify the command to run instead.

@example
guix environment guile --exec=make
@end example

The following options are available:

@table @code
@item --expression=@var{expr}
@itemx -e @var{expr}
Create an environment for the package that @var{expr} evaluates to.

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

@item --exec=@var{command}
@item -E @var{command}
Execute @var{command} in the new environment.

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

It also supports all of the common build options that @command{guix
build} supports (@pxref{Invoking guix build, common build options}).

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

Guix comes with a distribution 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}.} that forms the basis of the GNU system.  This
includes 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/package-list.html,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):

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

Our goal is to build 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.

The GNU distribution is 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 mips64el-linux
little-endian 64-bit MIPS processors, specifically the Loongson series,
n32 application binary interface (ABI), and Linux-Libre kernel.

@end table

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

@menu
* System Installation::         Installing the whole operating system.
* System Configuration::        Configuring a GNU 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

This section explains how to install the complete GNU operating system
on a machine.  The Guix package manager can also be installed on top of
a running GNU/Linux system, @pxref{Installation}.

@ifinfo
@c This paragraph is for people reading this from tty2 of the
@c installation image.
You're 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{Help,,, info, Info: An Introduction}.  Hit
@kbd{l} afterwards to come back here.
@end ifinfo

@subsection Limitations

As of version @value{VERSION}, GNU@tie{}Guix and the GNU system
distribution are alpha software.  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
more established GNU/Linux distributions}.  We hope you can soon switch
to the GNU system 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
The system does not yet provide graphical desktop environments such as
GNOME and KDE.

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

@item
Few system services are currently supported out-of-the-box
(@pxref{Services}).

@item
On the order of 1,000 packages are available, which means that you may
occasionally find that a useful package is missing.
@end itemize

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

@subsection USB Stick Installation

An installation image for USB sticks can be downloaded from
@url{ftp://alpha.gnu.org/gnu/guix/gnu-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

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 gnu-usb-install-@value{VERSION}.@var{system}.xz
@end example

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

@example
dd if=gnu-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.

@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{Help,,, info, Info: An
Introduction}).

To install the system, you would:

@enumerate

@item
Configure the network, by running @command{dhclient eth0} (to get an
automatically assigned IP address from the wired network interface
controller), or using the @command{ifconfig} command.

The system automatically loads drivers for your network interface
controllers.

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

@item
Unless this has already been done, you must partition and format the
target partitions.

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.

The installation image includes Parted (@pxref{Overview,,, parted, GNU
Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
encryption, and e2fsprogs, the suite of tools to manipulate
ext2/ext3/ext4 file systems.

@item
Once that is done, mount the target root partition under @file{/mnt}.

@item
Lastly, run @code{deco start cow-store /mnt}.

This will make @file{/gnu/store} copy-on-write, such that packages added
to it during the installation phase will be written to the target disk
rather than kept in memory.

@end enumerate


@subsection Proceeding with the Installation

With the target partitions ready, you now have to edit a file and
provide the declaration of the operating system to be installed.  To
that end, the installation system comes with two text editors: GNU nano
(@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
It is better to store that file on the target root file system, say, as
@file{/mnt/etc/config.scm}.

A minimal operating system configuration, with just the bare minimum and
only a root account would look like this (on the installation system,
this example is available as @file{/etc/configuration-template.scm}):

@example
@include os-config.texi
@end example

@noindent
For more information on @code{operating-system} declarations,
@pxref{Using the Configuration System}.

Once that is done, the new system must be initialized (remember that the
target root file system is mounted under @file{/mnt}):

@example
guix system init /mnt/etc/config.scm /mnt
@end example

@noindent
This will copy all the necessary files, and install GRUB on
@file{/dev/sdX}, unless you pass the @option{--no-grub} option.  For
more information, @pxref{Invoking guix system}.  This command may trigger
downloads or builds of missing packages, which can take some time.

Once that command has completed---and hopefully succeeded!---you can
run @command{reboot} and boot into the new system.  Cross fingers, and
join us on @code{#guix} on the Freenode IRC network or on
@file{guix-devel@@gnu.org} to share your experience---good or not so
good.

@subsection Building the Installation Image

The installation image described above was built using the @command{guix
system} command, specifically:

@example
guix system disk-image --image-size=800MiB gnu/system/install.scm
@end example

@xref{Invoking guix system}, for more information.  See
@file{gnu/system/install.scm} in the source tree for more information
about the installation image.

@node System Configuration
@section System Configuration

@cindex system configuration
The GNU system supports a consistent whole-system configuration
mechanism.  By that we mean that all aspects of the global system
configuration---such as the available system services, timezone and
locale settings, user accounts---are declared in a single place.  Such
a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.

One of the advantages of putting all the system configuration under the
control of Guix is that it supports transactional system upgrades, and
makes it possible to roll-back to a previous system instantiation,
should something go wrong with the new one (@pxref{Features}).  Another
one is that it makes it easy to replicate the exact same configuration
across different machines, or at different points in time, without
having to resort to additional administration tools layered on top of
the system's own tools.
@c Yes, we're talking of Puppet, Chef, & co. here.  ↑

This section describes this mechanism.  First we focus on the system
administrator's viewpoint---explaining how the system is configured and
instantiated.  Then we show how this mechanism can be extended, for
instance to support new system services.

@menu
* Using the Configuration System::  Customizing your GNU system.
* operating-system Reference::  Detail of operating-system declarations.
* File Systems::                Configuring file system mounts.
* Mapped Devices::              Block device extra processing.
* User Accounts::               Specifying user accounts.
* Locales::                     Language and cultural convention settings.
* Services::                    Specifying system services.
* Setuid Programs::             Programs running with root privileges.
* Initial RAM Disk::            Linux-Libre bootstrapping.
* GRUB Configuration::          Configuring the boot loader.
* Invoking guix system::        Instantiating a system configuration.
* Defining Services::           Adding new service definitions.
@end menu

@node Using the Configuration System
@subsection Using the Configuration System

The operating system is configured by providing an
@code{operating-system} declaration in a file that can then be passed to
the @command{guix system} command (@pxref{Invoking guix system}).  A
simple setup, with the default system services, the default Linux-Libre
kernel, initial RAM disk, and boot loader looks like this:

@findex operating-system
@lisp
(use-modules (gnu)   ; for 'user-account', '%base-services', etc.
             (gnu packages emacs)  ; for 'emacs'
             (gnu services ssh))   ; for 'lsh-service'

(operating-system
  (host-name "komputilo")
  (timezone "Europe/Paris")
  (locale "fr_FR.utf8")
  (bootloader (grub-configuration
                (device "/dev/sda")))
  (file-systems (cons (file-system
                        (device "/dev/sda1") ; or partition label
                        (mount-point "/")
                        (type "ext3"))
                      %base-file-systems))
  (users (list (user-account
                (name "alice")
                (uid 1000) (group 100)
                (comment "Bob's sister")
                (home-directory "/home/alice"))))
  (packages (cons emacs %base-packages))
  (services (cons (lsh-service #:port 2222 #:root-login? #t)
                  %base-services)))
@end lisp

This example should be self-describing.  Some of the fields defined
above, such as @code{host-name} and @code{bootloader}, are mandatory.
Others, such as @code{packages} and @code{services}, can be omitted, in
which case they get a default value.

@vindex %base-packages
The @code{packages} field lists
packages that will be globally visible on the system, for all user
accounts---i.e., in every user's @code{PATH} environment variable---in
addition to the per-user profiles (@pxref{Invoking guix package}).  The
@var{%base-packages} variable provides all the tools one would expect
for basic user and administrator tasks---including the GNU Core
Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
editor, @command{find}, @command{grep}, etc.  The example above adds
Emacs to those, taken from the @code{(gnu packages emacs)} module
(@pxref{Package Modules}).

@vindex %base-services
The @code{services} field lists @dfn{system services} to be made
available when the system starts (@pxref{Services}).
The @code{operating-system} declaration above specifies that, in
addition to the basic services, we want the @command{lshd} secure shell
daemon listening on port 2222, and allowing remote @code{root} logins
(@pxref{Invoking lshd,,, lsh, GNU lsh Manual}).  Under the hood,
@code{lsh-service} arranges so that @code{lshd} is started with the
right command-line options, possibly with supporting configuration files
generated as needed (@pxref{Defining Services}).  @xref{operating-system
Reference}, for details about the available @code{operating-system}
fields.

Assuming the above snippet is stored in the @file{my-system-config.scm}
file, the @command{guix system reconfigure my-system-config.scm} command
instantiates that configuration, and makes it the default GRUB boot
entry (@pxref{Invoking guix system}).  The normal way to change the
system's configuration is by updating this file and re-running the
@command{guix system} command.

At the Scheme level, the bulk of an @code{operating-system} declaration
is instantiated with the following monadic procedure (@pxref{The Store
Monad}):

@deffn {Monadic Procedure} operating-system-derivation os
Return a derivation that builds @var{os}, an @code{operating-system}
object (@pxref{Derivations}).

The output of the derivation is a single directory that refers to all
the packages, configuration files, and other supporting files needed to
instantiate @var{os}.
@end deffn

@node operating-system Reference
@subsection @code{operating-system} Reference

This section summarizes all the options available in
@code{operating-system} declarations (@pxref{Using the Configuration
System}).

@deftp {Data Type} operating-system
This is the data type representing an operating system configuration.
By that, we mean all the global system configuration, not per-user
configuration (@pxref{Using the Configuration System}).

@table @asis
@item @code{kernel} (default: @var{linux-libre})
The package object of the operating system to use@footnote{Currently
only the Linux-libre kernel is supported.  In the future, it will be
possible to use the GNU@tie{}Hurd.}.

@item @code{bootloader}
The system bootloader configuration object.  @xref{GRUB Configuration}.

@item @code{initrd} (default: @code{base-initrd})
A two-argument monadic procedure that returns an initial RAM disk for
the Linux kernel.  @xref{Initial RAM Disk}.

@item @code{firmware} (default: @var{%base-firmware})
@cindex firmware
List of firmware packages loadable by the operating system kernel.

The default includes firmware needed for Atheros-based WiFi devices
(Linux-libre module @code{ath9k}.)

@item @code{host-name}
The host name.

@item @code{hosts-file}
@cindex hosts file
A zero-argument monadic procedure that returns a text file for use as
@file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
Reference Manual}).  The default is to produce a file with entries for
@code{localhost} and @var{host-name}.

@item @code{mapped-devices} (default: @code{'()})
A list of mapped devices.  @xref{Mapped Devices}.

@item @code{file-systems}
A list of file systems.  @xref{File Systems}.

@item @code{swap-devices} (default: @code{'()})
@cindex swap devices
A list of strings identifying devices to be used for ``swap space''
(@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}).
For example, @code{'("/dev/sda3")}.

@item @code{users} (default: @code{'()})
@itemx @code{groups} (default: @var{%base-groups})
List of user accounts and groups.  @xref{User Accounts}.

@item @code{skeletons} (default: @code{(default-skeletons)})
A monadic list of pairs of target file name and files.  These are the
files that will be used as skeletons as new accounts are created.

For instance, a valid value may look like this:

@example
(mlet %store-monad ((bashrc (text-file "bashrc" "\
     export PATH=$HOME/.guix-profile/bin")))
  (return `((".bashrc" ,bashrc))))
@end example

@item @code{issue} (default: @var{%default-issue})
A string denoting the contents of the @file{/etc/issue} file, which is
what displayed when users log in on a text console.

@item @code{packages} (default: @var{%base-packages})
The set of packages installed in the global profile, which is accessible
at @file{/run/current-system/profile}.

The default set includes core utilities, but it is good practice to
install non-core utilities in user profiles (@pxref{Invoking guix
package}).

@item @code{timezone}
A timezone identifying string---e.g., @code{"Europe/Paris"}.

@item @code{locale} (default: @code{"en_US.utf8"})
The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
Library Reference Manual}).  @xref{Locales}, for more information.

@item @code{locale-definitions} (default: @var{%default-locale-definitions})
The list of locale definitions to be compiled and that may be used at
run time.  @xref{Locales}.

@item @code{services} (default: @var{%base-services})
A list of monadic values denoting system services.  @xref{Services}.

@item @code{pam-services} (default: @code{(base-pam-services)})
@cindex PAM
@cindex pluggable authentication modules
Linux @dfn{pluggable authentication module} (PAM) services.
@c FIXME: Add xref to PAM services section.

@item @code{setuid-programs} (default: @var{%setuid-programs})
List of string-valued G-expressions denoting setuid programs.
@xref{Setuid Programs}.

@item @code{sudoers} (default: @var{%sudoers-specification})
@cindex sudoers
The contents of the @file{/etc/sudoers} file as a string.

This file specifies which users can use the @command{sudo} command, what
they are allowed to do, and what privileges they may gain.  The default
is that only @code{root} and members of the @code{wheel} group may use
@code{sudo}.

@end table
@end deftp

@node File Systems
@subsection File Systems

The list of file systems to be mounted is specified in the
@code{file-systems} field of the operating system's declaration
(@pxref{Using the Configuration System}).  Each file system is declared
using the @code{file-system} form, like this:

@example
(file-system
  (mount-point "/home")
  (device "/dev/sda3")
  (type "ext4"))
@end example

As usual, some of the fields are mandatory---those shown in the example
above---while others can be omitted.  These are described below.

@deftp {Data Type} file-system
Objects of this type represent file systems to be mounted.  They
contain the following members:

@table @asis
@item @code{type}
This is a string specifying the type of the file system---e.g.,
@code{"ext4"}.

@item @code{mount-point}
This designates the place where the file system is to be mounted.

@item @code{device}
This names the ``source'' of the file system.  By default it is the name
of a node under @file{/dev}, but its meaning depends on the @code{title}
field described below.

@item @code{title} (default: @code{'device})
This is a symbol that specifies how the @code{device} field is to be
interpreted.

When it is the symbol @code{device}, then the @code{device} field is
interpreted as a file name; when it is @code{label}, then @code{device}
is interpreted as a partition label name; when it is @code{uuid},
@code{device} is interpreted as a partition unique identifier (UUID).

The @code{label} and @code{uuid} options offer a way to refer to disk
partitions without having to hard-code their actual device name.

However, when a file system's source is a mapped device (@pxref{Mapped
Devices}), its @code{device} field @emph{must} refer to the mapped
device name---e.g., @file{/dev/mapper/root-partition}---and consequently
@code{title} must be set to @code{'device}.  This is required so that
the system knows that mounting the file system depends on having the
corresponding device mapping established.

@item @code{flags} (default: @code{'()})
This is a list of symbols denoting mount flags.  Recognized flags
include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
access to special files), @code{no-suid} (ignore setuid and setgid
bits), and @code{no-exec} (disallow program execution.)

@item @code{options} (default: @code{#f})
This is either @code{#f}, or a string denoting mount options.

@item @code{needed-for-boot?} (default: @code{#f})
This Boolean value indicates whether the file system is needed when
booting.  If that is true, then the file system is mounted when the
initial RAM disk (initrd) is loaded.  This is always the case, for
instance, for the root file system.

@item @code{check?} (default: @code{#t})
This Boolean indicates whether the file system needs to be checked for
errors before being mounted.

@item @code{create-mount-point?} (default: @code{#f})
When true, the mount point is created if it does not exist yet.

@end table
@end deftp

The @code{(gnu system file-systems)} exports the following useful
variables.

@defvr {Scheme Variable} %base-file-systems
These are essential file systems that are required on normal systems,
such as @var{%devtmpfs-file-system} (see below.)  Operating system
declarations should always contain at least these.
@end defvr

@defvr {Scheme Variable} %devtmpfs-file-system
The @code{devtmpfs} file system to be mounted on @file{/dev}.  This is a
requirement for udev (@pxref{Base Services, @code{udev-service}}).
@end defvr

@defvr {Scheme Variable} %pseudo-terminal-file-system
This is the file system to be mounted as @file{/dev/pts}.  It supports
@dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
Manual}).  Pseudo-terminals are used by terminal emulators such as
@command{xterm}.
@end defvr

@defvr {Scheme Variable} %shared-memory-file-system
This file system is mounted as @file{/dev/shm} and is used to support
memory sharing across processes (@pxref{Memory-mapped I/O,
@code{shm_open},, libc, The GNU C Library Reference Manual}).
@end defvr

@defvr {Scheme Variable} %binary-format-file-system
The @code{binfmt_misc} file system, which allows handling of arbitrary
executable file types to be delegated to user space.  This requires the
@code{binfmt.ko} kernel module to be loaded.
@end defvr

@defvr {Scheme Variable} %fuse-control-file-system
The @code{fusectl} file system, which allows unprivileged users to mount
and unmount user-space FUSE file systems.  This requires the
@code{fuse.ko} kernel module to be loaded.
@end defvr

@node Mapped Devices
@subsection Mapped Devices

@cindex device mapping
@cindex mapped devices
The Linux kernel has a notion of @dfn{device mapping}: a block device,
such as a hard disk partition, can be @dfn{mapped} into another device,
with additional processing over the data that flows through
it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
concept of a ``mapped device'' and that of a file system: both boil down
to @emph{translating} input/output operations made on a file to
operations on its backing store.  Thus, the Hurd implements mapped
devices, like file systems, using the generic @dfn{translator} mechanism
(@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}.  A
typical example is encryption device mapping: all writes to the mapped
device are encrypted, and all reads are deciphered, transparently.

Mapped devices are declared using the @code{mapped-device} form:

@example
(mapped-device
  (source "/dev/sda3")
  (target "home")
  (type luks-device-mapping))
@end example

@noindent
@cindex disk encryption
@cindex LUKS
This example specifies a mapping from @file{/dev/sda3} to
@file{/dev/mapper/home} using LUKS---the
@url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a
standard mechanism for disk encryption.  The @file{/dev/mapper/home}
device can then be used as the @code{device} of a @code{file-system}
declaration (@pxref{File Systems}).  The @code{mapped-device} form is
detailed below.

@deftp {Data Type} mapped-device
Objects of this type represent device mappings that will be made when
the system boots up.

@table @code
@item source
This string specifies the name of the block device to be mapped, such as
@code{"/dev/sda3"}.

@item target
This string specifies the name of the mapping to be established.  For
example, specifying @code{"my-partition"} will lead to the creation of
the @code{"/dev/mapper/my-partition"} device.

@item type
This must be a @code{mapped-device-kind} object, which specifies how
@var{source} is mapped to @var{target}.
@end table
@end deftp

@defvr {Scheme Variable} luks-device-mapping
This defines LUKS block device encryption using the @command{cryptsetup}
command, from the same-named package.  This relies on the
@code{dm-crypt} Linux kernel module.
@end defvr

@node User Accounts
@subsection User Accounts

User accounts are specified with the @code{user-account} form:

@example
(user-account
  (name "alice")
  (group "users")
  (supplementary-groups '("wheel"   ;allow use of sudo, etc.
                          "audio"   ;sound card
                          "video"   ;video devices such as webcams
                          "cdrom")) ;the good ol' CD-ROM
  (comment "Bob's sister")
  (home-directory "/home/alice"))
@end example

@deftp {Data Type} user-account
Objects of this type represent user accounts.  The following members may
be specified:

@table @asis
@item @code{name}
The name of the user account.

@item @code{group}
This is the name (a string) or identifier (a number) of the user group
this account belongs to.

@item @code{supplementary-groups} (default: @code{'()})
Optionally, this can be defined as a list of group names that this
account belongs to.

@item @code{uid} (default: @code{#f})
This is the user ID for this account (a number), or @code{#f}.  In the
latter case, a number is automatically chosen by the system when the
account is created.

@item @code{comment} (default: @code{""})
A comment about the account, such as the account's owner full name.

@item @code{home-directory}
This is the name of the home directory for the account.

@item @code{shell} (default: Bash)
This is a G-expression denoting the file name of a program to be used as
the shell (@pxref{G-Expressions}).

@item @code{system?} (default: @code{#f})
This Boolean value indicates whether the account is a ``system''
account.  System accounts are sometimes treated specially; for instance,
graphical login managers do not list them.

@item @code{password} (default: @code{#f})
You would normally leave this field to @code{#f}, initialize user
passwords as @code{root} with the @command{passwd} command, and then let
users change it with @command{passwd}.

If you @emph{do} want to have a preset password for an account, then
this field must contain the encrypted password, as a string.
@xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
Manual}, for information on Guile's @code{crypt} procedure.

@end table
@end deftp

User group declarations are even simpler:

@example
(user-group (name "students"))
@end example

@deftp {Data Type} user-group
This type is for, well, user groups.  There are just a few fields:

@table @asis
@item @code{name}
The group's name.

@item @code{id} (default: @code{#f})
The group identifier (a number).  If @code{#f}, a new number is
automatically allocated when the group is created.

@item @code{system?} (default: @code{#f})
This Boolean value indicates whether the group is a ``system'' group.
System groups have low numerical IDs.

@item @code{password} (default: @code{#f})
What, user groups can have a password?  Well, apparently yes.  Unless
@code{#f}, this field specifies the group's password.

@end table
@end deftp

For convenience, a variable lists all the basic user groups one may
expect:

@defvr {Scheme Variable} %base-groups
This is the list of basic user groups that users and/or packages expect
to be present on the system.  This includes groups such as ``root'',
``wheel'', and ``users'', as well as groups used to control access to
specific devices such as ``audio'', ``disk'', and ``cdrom''.
@end defvr

@node Locales
@subsection Locales

@cindex locale
A @dfn{locale} defines cultural conventions for a particular language
and region of the world (@pxref{Locales,,, libc, The GNU C Library
Reference Manual}).  Each locale has a name that typically has the form
@code{@var{language}_@var{territory}.@var{charset}}---e.g.,
@code{fr_LU.utf8} designates the locale for the French language, with
cultural conventions from Luxembourg, and using the UTF-8 encoding.

@cindex locale definition
Usually, you will want to specify the default locale for the machine
using the @code{locale} field of the @code{operating-system} declaration
(@pxref{operating-system Reference, @code{locale}}).

That locale must be among the @dfn{locale definitions} that are known to
the system---and these are specified in the @code{locale-definitions}
slot of @code{operating-system}.  The default value includes locale
definition for some widely used locales, but not for all the available
locales, in order to save space.

If the locale specified in the @code{locale} field is not among the
definitions listed in @code{locale-definitions}, @command{guix system}
raises an error.  In that case, you should add the locale definition to
the @code{locale-definitions} field.  For instance, to add the North
Frisian locale for Germany, the value of that field may be: