guix.texi

(remove (lambda (service)
          (eq? (service-kind service) avahi-service-type))
        %desktop-services)
@end lisp

@unnumberedsubsec Instantiating the System

Assuming the @code{operating-system} declaration
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 configuration is by updating this
file and re-running @command{guix system reconfigure}.  One should never
have to touch files in @file{/etc} or to run commands that modify the
system state such as @command{useradd} or @command{grub-install}.  In
fact, you must avoid that since that would not only void your warranty
but also prevent you from rolling back to previous versions of your
system, should you ever need to.

@cindex roll-back, of the operating system
Speaking of roll-back, each time you run @command{guix system
reconfigure}, a new @dfn{generation} of the system is created---without
modifying or deleting previous generations.  Old system generations get
an entry in the bootloader boot menu, allowing you to boot them in case
something went wrong with the latest generation.  Reassuring, no?  The
@command{guix system list-generations} command lists the system
generations available on disk.  It is also possible to roll back the
system via the commands @command{guix system roll-back} and
@command{guix system switch-generation}.

Although the @command{guix system reconfigure} command will not modify
previous generations, you must take care when the current generation is not
the latest (e.g., after invoking @command{guix system roll-back}), since
the operation might overwrite a later generation (@pxref{Invoking guix
system}).

@unnumberedsubsec The Programming Interface

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

This procedure is provided by the @code{(gnu system)} module.  Along
with @code{(gnu services)} (@pxref{Services}), this module contains the
guts of Guix System.  Make sure to visit it!


@node operating-system Reference
@section @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{kernel-arguments} (default: @code{'("quiet")})
List of strings or gexps representing additional arguments to pass on
the command-line of the kernel---e.g., @code{("console=ttyS0")}.

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

@item @code{label}
This is the label (a string) as it appears in the bootloader's menu entry.
The default label includes the kernel name and version.

@item @code{keyboard-layout} (default: @code{#f})
This field specifies the keyboard layout to use in the console.  It can be
either @code{#f}, in which case the default keyboard layout is used (usually
US English), or a @code{<keyboard-layout>} record.

This keyboard layout is in effect as soon as the kernel has booted.  For
instance, it is the keyboard layout in effect when you type a passphrase if
your root file system is on a @code{luks-device-mapping} mapped device
(@pxref{Mapped Devices}).

@quotation Note
This does @emph{not} specify the keyboard layout used by the bootloader, nor
that used by the graphical display server.  @xref{Bootloader Configuration},
for information on how to specify the bootloader's keyboard layout.  @xref{X
Window}, for information on how to specify the keyboard layout used by the X
Window System.
@end quotation

@item @code{initrd-modules} (default: @code{%base-initrd-modules})
@cindex initrd
@cindex initial RAM disk
The list of Linux kernel modules that need to be available in the
initial RAM disk.  @xref{Initial RAM Disk}.

@item @code{initrd} (default: @code{base-initrd})
A procedure that returns an initial RAM disk for the Linux
kernel.  This field is provided to support low-level customization and
should rarely be needed for casual use.  @xref{Initial RAM Disk}.

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

The default includes firmware needed for Atheros- and Broadcom-based
WiFi devices (Linux-libre modules @code{ath9k} and @code{b43-open},
respectively).  @xref{Hardware Considerations}, for more info on
supported hardware.

@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 or files to be used for ``swap
space'' (@pxref{Memory Concepts,,, libc, The GNU C Library Reference
Manual}).  For example, @code{'("/dev/sda3")} or @code{'("/swapfile")}.
It is possible to specify a swap file in a file system on a mapped
device, provided that the necessary device mapping and file system are
also specified.  @xref{Mapped Devices} and @ref{File Systems}.

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

If the @code{users} list lacks a user account with UID@tie{}0, a
``root'' account with UID@tie{}0 is automatically added.

@item @code{skeletons} (default: @code{(default-skeletons)})
A list target file name/file-like object tuples (@pxref{G-Expressions,
file-like objects}).  These are the skeleton files that will be added to
the home directory of newly-created user accounts.

For instance, a valid value may look like this:

@lisp
`((".bashrc" ,(plain-file "bashrc" "echo Hello\n"))
  (".guile" ,(plain-file "guile"
                         "(use-modules (ice-9 readline))
                          (activate-readline)")))
@end lisp

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

@item @code{packages} (default: @code{%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 and 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"}.

You can run the @command{tzselect} command to find out which timezone
string corresponds to your region.  Choosing an invalid timezone name
causes @command{guix system} to fail.

@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: @code{%default-locale-definitions})
The list of locale definitions to be compiled and that may be used at
run time.  @xref{Locales}.

@item @code{locale-libcs} (default: @code{(list @var{glibc})})
The list of GNU@tie{}libc packages whose locale data and tools are used
to build the locale definitions.  @xref{Locales}, for compatibility
considerations that justify this option.

@item @code{name-service-switch} (default: @code{%default-nss})
Configuration of the libc name service switch (NSS)---a
@code{<name-service-switch>} object.  @xref{Name Service Switch}, for
details.

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

@cindex essential services
@item @code{essential-services} (default: ...)
The list of ``essential services''---i.e., things like instances of
@code{system-service-type} and @code{host-name-service-type} (@pxref{Service
Reference}), which are derived from the operating system definition itself.
As a user you should @emph{never} need to touch this field.

@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-file} (default: @var{%sudoers-specification})
@cindex sudoers file
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

@deffn {Scheme Syntax} this-operating-system
When used in the @emph{lexical scope} of an operating system field definition,
this identifier resolves to the operating system being defined.

The example below shows how to refer to the operating system being defined in
the definition of the @code{label} field:

@lisp
(use-modules (gnu) (guix))

(operating-system
  ;; ...
  (label (package-full-name
          (operating-system-kernel this-operating-system))))
@end lisp

It is an error to refer to @code{this-operating-system} outside an operating
system definition.
@end deffn

@end deftp

@node File Systems
@section File Systems

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

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

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.  It can be one of three
things: a file system label, a file system UUID, or the name of a
@file{/dev} node.  Labels and UUIDs offer a way to refer to file
systems without having to hard-code their actual device
name@footnote{Note that, while it is tempting to use
@file{/dev/disk/by-uuid} and similar device names to achieve the same
result, this is not recommended: These special device nodes are created
by the udev daemon and may be unavailable at the time the device is
mounted.}.

@findex file-system-label
File system labels are created using the @code{file-system-label}
procedure, UUIDs are created using @code{uuid}, and @file{/dev} node are
plain strings.  Here's an example of a file system referred to by its
label, as shown by the @command{e2label} command:

@lisp
(file-system
  (mount-point "/home")
  (type "ext4")
  (device (file-system-label "my-home")))
@end lisp

@findex uuid
UUIDs are converted from their string representation (as shown by the
@command{tune2fs -l} command) using the @code{uuid} form@footnote{The
@code{uuid} form expects 16-byte UUIDs as defined in
@uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}.  This is the
form of UUID used by the ext2 family of file systems and others, but it
is different from ``UUIDs'' found in FAT file systems, for instance.},
like this:

@lisp
(file-system
  (mount-point "/home")
  (type "ext4")
  (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
@end lisp

When the source of a file system 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"}.
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), @code{no-atime} (do not update file access times),
@code{strict-atime} (update file access time), @code{lazy-time} (only
update time on the in-memory version of the file inode), and
@code{no-exec} (disallow program execution).
@xref{Mount-Unmount-Remount,,, libc, The GNU C Library Reference
Manual}, for more information on these flags.

@item @code{options} (default: @code{#f})
This is either @code{#f}, or a string denoting mount options passed to the
file system driver.  @xref{Mount-Unmount-Remount,,, libc, The GNU C Library
Reference Manual}, for details and run @command{man 8 mount} for options for
various file systems.

@item @code{mount?} (default: @code{#t})
This value indicates whether to automatically mount the file system when
the system is brought up.  When set to @code{#f}, the file system gets
an entry in @file{/etc/fstab} (read by the @command{mount} command) but
is not automatically mounted.

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

@item @code{dependencies} (default: @code{'()})
This is a list of @code{<file-system>} or @code{<mapped-device>} objects
representing file systems that must be mounted or mapped devices that
must be opened before (and unmounted or closed after) this one.

As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is
a dependency of @file{/sys/fs/cgroup/cpu} and
@file{/sys/fs/cgroup/memory}.

Another example is a file system that depends on a mapped device, for
example for an encrypted partition (@pxref{Mapped Devices}).
@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{%pseudo-terminal-file-system} and @var{%immutable-store} (see
below.)  Operating system declarations should always contain at least
these.
@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
@section 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,
usually in @code{/dev/mapper/},
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.
Guix extends this notion by considering any device or set of devices that
are @dfn{transformed} in some way to create a new device; for instance,
RAID devices are obtained by @dfn{assembling} several other devices, such
as hard disks or partitions, into a new one that behaves as one partition.
Other examples, not yet implemented, are LVM logical volumes.

Mapped devices are declared using the @code{mapped-device} form,
defined as follows; for examples, see 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 is either a string specifying the name of the block device to be mapped,
such as @code{"/dev/sda3"}, or a list of such strings when several devices
need to be assembled for creating a new one.

@item target
This string specifies the name of the resulting mapped device.  For
kernel mappers such as encrypted devices of type @code{luks-device-mapping},
specifying @code{"my-partition"} leads to the creation of
the @code{"/dev/mapper/my-partition"} device.
For RAID devices of type @code{raid-device-mapping}, the full device name
such as @code{"/dev/md0"} needs to be given.

@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 package with the same name.  It relies on the
@code{dm-crypt} Linux kernel module.
@end defvr

@defvr {Scheme Variable} raid-device-mapping
This defines a RAID device, which is assembled using the @code{mdadm}
command from the package with the same name.  It requires a Linux kernel
module for the appropriate RAID level to be loaded, such as @code{raid456}
for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
@end defvr

@cindex disk encryption
@cindex LUKS
The following example specifies a mapping from @file{/dev/sda3} to
@file{/dev/mapper/home} using LUKS---the
@url{https://gitlab.com/cryptsetup/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}).

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

Alternatively, to become independent of device numbering, one may obtain
the LUKS UUID (@dfn{unique identifier}) of the source device by a
command like:

@example
cryptsetup luksUUID /dev/sda3
@end example

and use it as follows:

@lisp
(mapped-device
  (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
  (target "home")
  (type luks-device-mapping))
@end lisp

@cindex swap encryption
It is also desirable to encrypt swap space, since swap space may contain
sensitive data.  One way to accomplish that is to use a swap file in a
file system on a device mapped via LUKS encryption.  In this way, the
swap file is encrypted because the entire device is encrypted.
@xref{Preparing for Installation,,Disk Partitioning}, for an example.

A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
may be declared as follows:

@lisp
(mapped-device
  (source (list "/dev/sda1" "/dev/sdb1"))
  (target "/dev/md0")
  (type raid-device-mapping))
@end lisp

The @file{/dev/md0} device can then be used as the @code{device} of a
@code{file-system} declaration (@pxref{File Systems}).
Note that the RAID level need not be given; it is chosen during the
initial creation and formatting of the RAID device and is determined
automatically later.


@node User Accounts
@section User Accounts

@cindex users
@cindex accounts
@cindex 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:

@lisp
(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 lisp

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}
@cindex groups
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 owner's full name.

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

@item @code{create-home-directory?} (default: @code{#t})
Indicates whether the home directory of this account should be created
if it does not exist yet.

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

@anchor{user-account-password}
@cindex password, for user accounts
@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 set an initial password for an account, then
this field must contain the encrypted password, as a string.  You can use the
@code{crypt} procedure for this purpose:

@lisp
(user-account
  (name "charlie")
  (group "users")

  ;; Specify a SHA-512-hashed initial password.
  (password (crypt "InitialPassword!" "$6$abc")))
@end lisp

@quotation Note
The hash of this initial password will be available in a file in
@file{/gnu/store}, readable by all the users, so this method must be used with
care.
@end quotation

@xref{Passphrase Storage,,, 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

@cindex groups
User group declarations are even simpler:

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

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

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

@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 password of the group.

@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 Keyboard Layout
@section Keyboard Layout

@cindex keyboard layout
@cindex keymap
To specify what each key of your keyboard does, you need to tell the operating
system what @dfn{keyboard layout} you want to use.  The default, when nothing
is specified, is the US English QWERTY layout for 105-key PC keyboards.
However, German speakers will usually prefer the German QWERTZ layout, French
speakers will want the AZERTY layout, and so on; hackers might prefer Dvorak
or bépo, and they might even want to further customize the effect of some of
the keys.  This section explains how to get that done.

@cindex keyboard layout, definition
There are three components that will want to know about your keyboard layout:

@itemize
@item
The @emph{bootloader} may want to know what keyboard layout you want to use
(@pxref{Bootloader Configuration, @code{keyboard-layout}}).  This is useful if
you want, for instance, to make sure that you can type the passphrase of your
encrypted root partition using the right layout.

@item
The @emph{operating system kernel}, Linux, will need that so that the console
is properly configured (@pxref{operating-system Reference,
@code{keyboard-layout}}).

@item
The @emph{graphical display server}, usually Xorg, also has its own idea of
the keyboard layout (@pxref{X Window, @code{keyboard-layout}}).
@end itemize

Guix allows you to configure all three separately but, fortunately, it allows
you to share the same keyboard layout for all three components.

@cindex XKB, keyboard layouts
Keyboard layouts are represented by records created by the
@code{keyboard-layout} procedure of @code{(gnu system keyboard)}.  Following
the X Keyboard extension (XKB), each layout has four attributes: a name (often
a language code such as ``fi'' for Finnish or ``jp'' for Japanese), an
optional variant name, an optional keyboard model name, and a possibly empty
list of additional options.  In most cases the layout name is all you care
about.  Here are a few example:

@lisp
;; The German QWERTZ layout.  Here we assume a standard
;; "pc105" keyboard model.
(keyboard-layout "de")

;; The bépo variant of the French layout.
(keyboard-layout "fr" "bepo")

;; The Catalan layout.
(keyboard-layout "es" "cat")

;; The Latin American Spanish layout.  In addition, the
;; "Caps Lock" key is used as an additional "Ctrl" key,
;; and the "Menu" key is used as a "Compose" key to enter
;; accented letters.
(keyboard-layout "latam"
                 #:options '("ctrl:nocaps" "compose:menu"))

;; The Russian layout for a ThinkPad keyboard.
(keyboard-layout "ru" #:model "thinkpad")

;; The "US international" layout, which is the US layout plus
;; dead keys to enter accented characters.  This is for an
;; Apple MacBook keyboard.
(keyboard-layout "us" "intl" #:model "macbook78")
@end lisp

See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} package
for a complete list of supported layouts, variants, and models.

@cindex keyboard layout, configuration
Let's say you want your system to use the Turkish keyboard layout throughout
your system---bootloader, console, and Xorg.  Here's what your system
configuration would look like:

@findex set-xorg-configuration
@lisp
;; Using the Turkish layout for the bootloader, the console,
;; and for Xorg.

(operating-system
  ;; ...
  (keyboard-layout (keyboard-layout "tr"))  ;for the console
  (bootloader (bootloader-configuration
                (bootloader grub-efi-bootloader)
                (target "/boot/efi")
                (keyboard-layout keyboard-layout))) ;for GRUB
  (services (cons (set-xorg-configuration
                    (xorg-configuration             ;for Xorg
                      (keyboard-layout keyboard-layout)))
                  %desktop-services)))
@end lisp

In the example above, for GRUB and for Xorg, we just refer to the
@code{keyboard-layout} field defined above, but we could just as well refer to
a different layout.  The @code{set-xorg-configuration} procedure communicates
the desired Xorg configuration to the graphical log-in manager, by default
GDM.

We've discussed how to specify the @emph{default} keyboard layout of your
system when it starts, but you can also adjust it at run time:

@itemize
@item
If you're using GNOME, its settings panel has a ``Region & Language'' entry
where you can select one or more keyboard layouts.

@item
Under Xorg, the @command{setxkbmap} command (from the same-named package)
allows you to change the current layout.  For example, this is how you would
change the layout to US Dvorak:

@example
setxkbmap us dvorak
@end example

@item
The @code{loadkeys} command changes the keyboard layout in effect in the Linux
console.  However, note that @code{loadkeys} does @emph{not} use the XKB
keyboard layout categorization described above.  The command below loads the
French bépo layout:

@example
loadkeys fr-bepo
@end example
@end itemize

@node Locales
@section 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{codeset}}---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}}).

The selected locale is automatically added to the @dfn{locale
definitions} known to the system if needed, with its codeset inferred
from its name---e.g., @code{bo_CN.utf8} will be assumed to use the
@code{UTF-8} codeset.  Additional locale definitions can be specified in
the @code{locale-definitions} slot of @code{operating-system}---this is
useful, for instance, if the codeset could not be inferred from the
locale name.  The default set of locale definitions includes some widely
used locales, but not all the available locales, in order to save space.

For instance, to add the North Frisian locale for Germany, the value of
that field may be:

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

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

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

@vindex LOCPATH
The compiled locale definitions are available at
@file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
version, which is the default location where the GNU@tie{}libc provided
by Guix looks for locale data.  This can be overridden using the
@code{LOCPATH} environment variable (@pxref{locales-and-locpath,
@code{LOCPATH} and locale packages}).

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{https://www.iana.org/assignments/character-sets, as defined by
IANA}.

@end table
@end deftp

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

@cindex locale name
@cindex normalized codeset in locale names
These locale definitions use the @dfn{normalized codeset} for the part
that follows the dot in the name (@pxref{Using gettextized software,
normalized codeset,, libc, The GNU C Library Reference Manual}).  So for
instance it has @code{uk_UA.utf8} but @emph{not}, say,
@code{uk_UA.UTF-8}.
@end defvr

@subsection Locale Data Compatibility Considerations

@cindex incompatibility, of locale data
@code{operating-system} declarations provide a @code{locale-libcs} field
to specify the GNU@tie{}libc packages that are used to compile locale
declarations (@pxref{operating-system Reference}).  ``Why would I
care?'', you may ask.  Well, it turns out that the binary format of
locale data is occasionally incompatible from one libc version to
another.

@c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
For instance, a program linked against libc version 2.21 is unable to
read locale data produced with libc 2.22; worse, that program
@emph{aborts} instead of simply ignoring the incompatible locale
data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
the incompatible locale data, which is already an improvement.}.
Similarly, a program linked against libc 2.22 can read most, but not
all, of the locale data from libc 2.21 (specifically, @code{LC_COLLATE}
data is incompatible); thus calls to @code{setlocale} may fail, but
programs will not abort.

The ``problem'' with Guix is that users have a lot of freedom: They can
choose whether and when to upgrade software in their profiles, and might
be using a libc version different from the one the system administrator
used to build the system-wide locale data.

Fortunately, unprivileged users can also install their own locale data
and define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
@code{GUIX_LOCPATH} and locale packages}).

Still, it is best if the system-wide locale data at
@file{/run/current-system/locale} is built for all the libc versions
actually in use on the system, so that all the programs can access
it---this is especially crucial on a multi-user system.  To do that, the
administrator can specify several libc packages in the
@code{locale-libcs} field of @code{operating-system}:

@lisp
(use-package-modules base)

(operating-system
  ;; @dots{}
  (locale-libcs (list glibc-2.21 (canonical-package glibc))))
@end lisp

This example would lead to a system containing locale definitions for
both libc 2.21 and the current version of libc in
@file{/run/current-system/locale}.


@node Services
@section 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
Configuration System}).  System services are typically daemons launched
when the system boots, or other actions needed at that time---e.g.,
configuring network access.

Guix has a broad definition of ``service'' (@pxref{Service
Composition}), but many services are managed by the GNU@tie{}Shepherd
(@pxref{Shepherd Services}).  On a running system, the @command{herd}
command allows you to list the available services, show their status,
start and stop them, or do other specific operations (@pxref{Jump
Start,,, shepherd, The GNU Shepherd Manual}).  For example:

@example
# herd status