guix.texi

meta-data, and @var{options} specifies a package identifier and other
options specific to @var{importer}.  Currently, the available
``importers'' are:

@table @code
@item gnu
Import meta-data for the given GNU package.  This provides a template
for the latest version of that GNU package, including the hash of its
source tarball, and its canonical synopsis and description.

Additional information such as the package's dependencies and its
license needs to be figured out manually.

For example, the following command returns a package definition for
GNU@tie{}Hello:

@example
guix import gnu hello
@end example

Specific command-line options are:

@table @code
@item --key-download=@var{policy}
As for @code{guix refresh}, specify the policy to handle missing OpenPGP
keys when verifying the package's signature.  @xref{Invoking guix
refresh, @code{--key-download}}.
@end table

@item pypi
@cindex pypi
Import meta-data from the @uref{https://pypi.python.org/, Python Package
Index}@footnote{This functionality requires Guile-JSON to be installed.
@xref{Requirements}.}.  Information is taken from the JSON-formatted
description available at @code{pypi.python.org} and usually includes all
the relevant information, including package dependencies.

The command below imports meta-data for the @code{itsdangerous} Python
package:

@example
guix import pypi itsdangerous
@end example

@item cpan
@cindex CPAN
Import meta-data from @uref{https://www.metacpan.org/, MetaCPAN}.
Information is taken from the JSON-formatted meta-data provided through
@uref{https://api.metacpan.org/, MetaCPAN's API} and includes most
relevant information.  License information should be checked closely.
Package dependencies are included but may in some cases needlessly
include core Perl modules.

The command command below imports meta-data for the @code{Acme::Boolean}
Perl module:

@example
guix import cpan Acme::Boolean
@end example

@item nix
Import meta-data from a local copy of the source of the
@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
relies on the @command{nix-instantiate} command of
@uref{http://nixos.org/nix/, Nix}.}.  Package definitions in Nixpkgs are
typically written in a mixture of Nix-language and Bash code.  This
command only imports the high-level package structure that is written in
the Nix language.  It normally includes all the basic fields of a
package definition.

When importing a GNU package, the synopsis and descriptions are replaced
by their canonical upstream variant.

As an example, the command below imports the package definition of
LibreOffice (more precisely, it imports the definition of the package
bound to the @code{libreoffice} top-level attribute):

@example
guix import nix ~/path/to/nixpkgs libreoffice
@end example
@end table

The structure of the @command{guix import} code is modular.  It would be
useful to have more importers for other package formats, and your help
is welcome here (@pxref{Contributing}).

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

The primary audience of the @command{guix refresh} command is developers
of the GNU software distribution.  By default, it reports any packages
provided by the distribution that are outdated compared to the latest
upstream version, like this:

@example
$ guix refresh
gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
@end example

It does so by browsing each package's FTP directory and determining the
highest version number of the source tarballs
therein@footnote{Currently, this only works for GNU packages.}.

When passed @code{--update}, it modifies distribution source files to
update the version numbers and source tarball hashes of those packages'
recipes (@pxref{Defining Packages}).  This is achieved by downloading
each package's latest source tarball and its associated OpenPGP
signature, authenticating the downloaded tarball against its signature
using @command{gpg}, and finally computing its hash.  When the public
key used to sign the tarball is missing from the user's keyring, an
attempt is made to automatically retrieve it from a public key server;
when it's successful, the key is added to the user's keyring; otherwise,
@command{guix refresh} reports an error.

The following options are supported:

@table @code

@item --update
@itemx -u
Update distribution source files (package recipes) in place.
@xref{Defining Packages}, for more information on package definitions.

@item --select=[@var{subset}]
@itemx -s @var{subset}
Select all the packages in @var{subset}, one of @code{core} or
@code{non-core}.

The @code{core} subset refers to all the packages at the core of the
distribution---i.e., packages that are used to build ``everything
else''.  This includes GCC, libc, Binutils, Bash, etc.  Usually,
changing one of these packages in the distribution entails a rebuild of
all the others.  Thus, such updates are an inconvenience to users in
terms of build time or bandwidth used to achieve the upgrade.

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

@cindex Guix System Distribution
@cindex GSD
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 GNU@tie{}GSD.

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

GSD 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 (GSD) 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 GSD 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/guix-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 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.
* 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")
                (group "users")
                (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