guix.texi

For instance, the command:

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

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

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

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

The purpose of @command{guix publish} is to enable users to easily share
their store with others, which 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 system's signing key, 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 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

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

@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/package-list.html,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):

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

Our goal has been 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 VFP3D16 coprocessor,
using the EABI hard-float ABI, and 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

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

@noindent
For information on porting to other architectures or kernels,
@xref{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 Guix System Distribution
This section explains how to install the Guix System Distribution
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}, 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
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
The system does not yet provide GNOME and KDE; it provides Xfce, though,
if graphical desktop environments are your thing.

@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,900 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
@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

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

@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{ifconfig eno1 up && dhclient
eno1} (to get an automatically assigned IP address from the wired
network interface controller@footnote{
@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
The name @code{eno1} is for the first on-board Ethernet controller.  The
interface name for an Ethernet controller that is in the first slot of
the first PCI bus, for instance, would be @code{enp1s0}.  Use
@command{ifconfig -a} to list all the available network interfaces.}),
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}.

@xref{Using the Configuration System}, for examples of operating system
configurations.  These examples are available under
@file{/etc/configuration} in the installation image, so you can copy
them and use them as a starting point for your own configuration.

Once you are done preparing the configuration file, 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=850MiB 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 Guix System Distribution 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.
* X.509 Certificates::          Authenticating HTTPS servers.
* Name Service Switch::         Configuring libc's name service switch.
* 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
@include os-config-bare-bones.texi
@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.

The configuration for a typical ``desktop'' usage, with the X11 display
server, a desktop environment, network management, an SSH server, and
more, would look like this:

@lisp
@include os-config-desktop.texi
@end lisp

@xref{Desktop Services}, for the exact list of services provided by
@var{%desktop-services}.  @xref{X.509 Certificates}, for background
information about the @code{nss-certs} package that is used here.

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 kernel 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 file-like object (@pxref{G-Expressions, file-like objects}) for use as
@file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
Reference Manual}).  The default is 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{%base-user-accounts})
@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{name-service-switch} (default: @var{%default-nss})
Configuration of libc's name service switch (NSS)---a
@code{<name-service-switch>} object.  @xref{Name Service Switch}, for
details.

@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 file-like object
(@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).

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} and @var{%immutable-store} (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} %immutable-store
This file system performs a read-only ``bind mount'' of
@file{/gnu/store}, making it read-only for all the users including
@code{root}.  This prevents against accidental modification by software
running as @code{root} or by system administrators.

The daemon itself is still able to write to the store: it remounts it
read-write in its own ``name space.''
@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 and groups are entirely managed through the
@code{operating-system} declaration.  They are specified with the
@code{user-account} and @code{user-group} forms:

@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

When booting or upon completion of @command{guix system reconfigure},
the system ensures that only the user accounts and groups specified in
the @code{operating-system} declaration exist, and with the specified
properties.  Thus, account or group creations or modifications made by
directly invoking commands such as @command{useradd} are lost upon
reconfiguration or reboot.  This ensures that the system remains exactly
as declared.

@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}.  Passwords set with
@command{passwd} are of course preserved across reboot and
reconfiguration.

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

@defvr {Scheme Variable} %base-user-accounts
This is the list of basic system accounts that programs may expect to
find on a GNU/Linux system, such as the ``nobody'' account.

Note that the ``root'' account is not included here.  It is a
special-case and is automatically added whether or not it is specified.
@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:

@example
(cons (locale-definition
        (name "fy_DE.utf8") (source "fy_DE"))
      %default-locale-definitions)
@end example

Likewise, to save space, one might want @code{locale-definitions} to
list only the locales that are actually used, as in:

@example
(list (locale-definition
        (name "ja_JP.eucjp") (source "ja_JP")
        (charset "EUC-JP")))
@end example

The @code{locale-definition} form is provided by the @code{(gnu system
locale)} module.  Details are given below.

@deftp {Data Type} locale-definition
This is the data type of a locale definition.

@table @asis

@item @code{name}
The name of the locale.  @xref{Locale Names,,, libc, The GNU C Library
Reference Manual}, for more information on locale names.

@item @code{source}
The name of the source for that locale.  This is typically the
@code{@var{language}_@var{territory}} part of the locale name.

@item @code{charset} (default: @code{"UTF-8"})
The ``character set'' or ``code set'' for that locale,
@uref{http://www.iana.org/assignments/character-sets, as defined by
IANA}.

@end table
@end deftp

@defvr {Scheme Variable} %default-locale-definitions
An arbitrary list of commonly used locales, used as the default value of
the @code{locale-definitions} field of @code{operating-system}
declarations.
@end defvr

@node Services
@subsection Services

@cindex system services
An important part of preparing an @code{operating-system} declaration is
listing @dfn{system services} and their configuration (@pxref{Using the