This is guix.info, produced by makeinfo version 6.7 from guix.texi.

Copyright © 2012-2022 Ludovic Courtès
Copyright © 2013, 2014, 2016 Andreas Enge
Copyright © 2013 Nikita Karetnikov
Copyright © 2014, 2015, 2016 Alex Kost
Copyright © 2015, 2016 Mathieu Lirzin
Copyright © 2014 Pierre-Antoine Rault
Copyright © 2015 Taylan Ulrich Bayırlı/Kammer
Copyright © 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari
Copyright © 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 Ricardo
Wurmus
Copyright © 2016 Ben Woodcroft
Copyright © 2016, 2017, 2018, 2021 Chris Marusich
Copyright © 2016, 2017, 2018, 2019, 2020, 2021, 2022 Efraim Flashner
Copyright © 2016 John Darrington
Copyright © 2016, 2017 Nikita Gillmann
Copyright © 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen
Copyright © 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller
Copyright © 2016 Alex ter Weele
Copyright © 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines
Copyright © 2017, 2018, 2019 Clément Lassieur
Copyright © 2017, 2018, 2020, 2021, 2022 Mathieu Othacehe
Copyright © 2017 Federico Beffa
Copyright © 2017, 2018 Carlo Zancanaro
Copyright © 2017 Thomas Danckaert
Copyright © 2017 humanitiesNerd
Copyright © 2017, 2021 Christine Lemmer-Webber
Copyright © 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke
Copyright © 2017, 2019, 2020, 2022 Hartmut Goebel
Copyright © 2017, 2019, 2020, 2021, 2022 Maxim Cournoyer
Copyright © 2017–2022 Tobias Geerinckx-Rice
Copyright © 2017 George Clemmer
Copyright © 2017 Andy Wingo
Copyright © 2017, 2018, 2019, 2020 Arun Isaac
Copyright © 2017 nee
Copyright © 2018 Rutger Helling
Copyright © 2018, 2021 Oleg Pykhalov
Copyright © 2018 Mike Gerwitz
Copyright © 2018 Pierre-Antoine Rouby
Copyright © 2018, 2019 Gábor Boskovits
Copyright © 2018, 2019, 2020, 2022 Florian Pelz
Copyright © 2018 Laura Lazzati
Copyright © 2018 Alex Vong
Copyright © 2019 Josh Holland
Copyright © 2019, 2020 Diego Nicola Barbato
Copyright © 2019 Ivan Petkov
Copyright © 2019 Jakob L. Kreuze
Copyright © 2019 Kyle Andrews
Copyright © 2019 Alex Griffin
Copyright © 2019, 2020, 2021, 2022 Guillaume Le Vaillant
Copyright © 2020 Liliana Marie Prikler
Copyright © 2019, 2020, 2021, 2022 Simon Tournier
Copyright © 2020 Wiktor Żelazny
Copyright © 2020 Damien Cassou
Copyright © 2020 Jakub Kądziołka
Copyright © 2020 Jack Hill
Copyright © 2020 Naga Malleswari
Copyright © 2020, 2021 Brice Waegeneire
Copyright © 2020 R Veera Kumar
Copyright © 2020, 2021 Pierre Langlois
Copyright © 2020 pinoaffe
Copyright © 2020 André Batista
Copyright © 2020, 2021 Alexandru-Sergiu Marton
Copyright © 2020 raingloom
Copyright © 2020 Daniel Brooks
Copyright © 2020 John Soo
Copyright © 2020 Jonathan Brielmaier
Copyright © 2020 Edgar Vincent
Copyright © 2021, 2022 Maxime Devos
Copyright © 2021 B. Wilson
Copyright © 2021 Xinglu Chen
Copyright © 2021 Raghav Gururajan
Copyright © 2021 Domagoj Stolfa
Copyright © 2021 Hui Lu
Copyright © 2021 pukkamustard
Copyright © 2021 Alice Brenon
Copyright © 2021, 2022 Josselin Poiret
Copyright © 2021 muradm
Copyright © 2021, 2022 Andrew Tropin
Copyright © 2021 Sarah Morgensen
Copyright © 2022 Remco van ’t Veer
Copyright © 2022 Aleksandr Vityazev
Copyright © 2022 Philip M^{c}Grath
Copyright © 2022 Karl Hallsby
Copyright © 2022 Justin Veilleux
Copyright © 2022 Reily Siegel
Copyright © 2022 Simon Streit
Copyright © 2022 (
Copyright © 2022 John Kehayias

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled “GNU Free
Documentation License”.
INFO-DIR-SECTION System administration
START-INFO-DIR-ENTRY
* Guix: (guix).       Manage installed software and system configuration.
* guix package: (guix)Invoking guix package.  Installing, removing, and upgrading packages.
* guix gc: (guix)Invoking guix gc.            Reclaiming unused disk space.
* guix pull: (guix)Invoking guix pull.        Update the list of available packages.
* guix system: (guix)Invoking guix system.    Manage the operating system configuration.
* guix deploy: (guix)Invoking guix deploy.    Manage operating system configurations for remote hosts.
END-INFO-DIR-ENTRY

INFO-DIR-SECTION Software development
START-INFO-DIR-ENTRY
* guix shell: (guix)Invoking guix shell.      Creating software environments.
* guix environment: (guix)Invoking guix environment.  Building development environments with Guix.
* guix build: (guix)Invoking guix build.      Building packages.
* guix pack: (guix)Invoking guix pack.        Creating binary bundles.
END-INFO-DIR-ENTRY


File: guix.info,  Node: Invoking guix challenge,  Next: Invoking guix copy,  Prev: Invoking guix publish,  Up: Utilities

10.12 Invoking ‘guix challenge’
===============================

Do the binaries provided by this server really correspond to the source
code it claims to build?  Is a package build process deterministic?
These are the questions the ‘guix challenge’ command attempts to answer.

   The former is obviously an important question: Before using a
substitute server (*note Substitutes::), one had better _verify_ that it
provides the right binaries, and thus _challenge_ it.  The latter is
what enables the former: If package builds are deterministic, then
independent builds of the package should yield the exact same result,
bit for bit; if a server provides a binary different from the one
obtained locally, it may be either corrupt or malicious.

   We know that the hash that shows up in ‘/gnu/store’ file names is the
hash of all the inputs of the process that built the file or
directory—compilers, libraries, build scripts, etc.  (*note
Introduction::).  Assuming deterministic build processes, one store file
name should map to exactly one build output.  ‘guix challenge’ checks
whether there is, indeed, a single mapping by comparing the build
outputs of several independent builds of any given store item.

   The command output looks like this:

     $ guix challenge \
       --substitute-urls="https://ci.guix.gnu.org https://guix.example.org" \
       openssl git pius coreutils grep
     updating substitutes from 'https://ci.guix.gnu.org'... 100.0%
     updating substitutes from 'https://guix.example.org'... 100.0%
     /gnu/store/...-openssl-1.0.2d contents differ:
       local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
       https://ci.guix.gnu.org/nar/...-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
       https://guix.example.org/nar/...-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
       differing files:
         /lib/libcrypto.so.1.1
         /lib/libssl.so.1.1

     /gnu/store/...-git-2.5.0 contents differ:
       local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
       https://ci.guix.gnu.org/nar/...-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
       https://guix.example.org/nar/...-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
       differing file:
         /libexec/git-core/git-fsck

     /gnu/store/...-pius-2.1.1 contents differ:
       local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
       https://ci.guix.gnu.org/nar/...-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
       https://guix.example.org/nar/...-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
       differing file:
         /share/man/man1/pius.1.gz

     ...

     5 store items were analyzed:
       - 2 (40.0%) were identical
       - 3 (60.0%) differed
       - 0 (0.0%) were inconclusive

In this example, ‘guix challenge’ queries all the substitute servers for
each of the fives packages specified on the command line.  It then
reports those store items for which the servers obtained a result
different from the local build (if it exists) and/or different from one
another; here, the ‘local hash’ lines indicate that a local build result
was available for each of these packages and shows its hash.

   As an example, ‘guix.example.org’ always gets a different answer.
Conversely, ‘ci.guix.gnu.org’ agrees with local builds, except in the
case of Git.  This might indicate that the build process of Git is
non-deterministic, meaning that its output varies as a function of
various things that Guix does not fully control, in spite of building
packages in isolated environments (*note Features::).  Most common
sources of non-determinism include the addition of timestamps in build
results, the inclusion of random numbers, and directory listings sorted
by inode number.  See <https://reproducible-builds.org/docs/>, for more
information.

   To find out what is wrong with this Git binary, the easiest approach
is to run:

     guix challenge git \
       --diff=diffoscope \
       --substitute-urls="https://ci.guix.gnu.org https://guix.example.org"

   This automatically invokes ‘diffoscope’, which displays detailed
information about files that differ.

   Alternatively, we can do something along these lines (*note Invoking
guix archive::):

     $ wget -q -O - https://ci.guix.gnu.org/nar/lzip/...-git-2.5.0 \
        | lzip -d | guix archive -x /tmp/git
     $ diff -ur --no-dereference /gnu/store/...-git.2.5.0 /tmp/git

   This command shows the difference between the files resulting from
the local build, and the files resulting from the build on
‘ci.guix.gnu.org’ (*note Comparing and Merging Files:
(diffutils)Overview.).  The ‘diff’ command works great for text files.
When binary files differ, a better option is Diffoscope
(https://diffoscope.org/), a tool that helps visualize differences for
all kinds of files.

   Once you have done that work, you can tell whether the differences
are due to a non-deterministic build process or to a malicious server.
We try hard to remove sources of non-determinism in packages to make it
easier to verify substitutes, but of course, this is a process that
involves not just Guix, but a large part of the free software community.
In the meantime, ‘guix challenge’ is one tool to help address the
problem.

   If you are writing packages for Guix, you are encouraged to check
whether ‘ci.guix.gnu.org’ and other substitute servers obtain the same
build result as you did with:

     guix challenge PACKAGE

   The general syntax is:

     guix challenge OPTIONS ARGUMENT...

where ARGUMENT is a package specification such as ‘guile@2.0’ or
‘glibc:debug’ or, alternatively, a store file name as returned, for
example, by ‘guix build’ or ‘guix gc --list-live’.

   When a difference is found between the hash of a locally-built item
and that of a server-provided substitute, or among substitutes provided
by different servers, the command displays it as in the example above
and its exit code is 2 (other non-zero exit codes denote other kinds of
errors).

   The one option that matters is:

‘--substitute-urls=URLS’
     Consider URLS the whitespace-separated list of substitute source
     URLs to compare to.

‘--diff=MODE’
     Upon mismatches, show differences according to MODE, one of:

     ‘simple’ (the default)
          Show the list of files that differ.

     ‘diffoscope’
     COMMAND
          Invoke Diffoscope (https://diffoscope.org/), passing it two
          directories whose contents do not match.

          When COMMAND is an absolute file name, run COMMAND instead of
          Diffoscope.

     ‘none’
          Do not show further details about the differences.

     Thus, unless ‘--diff=none’ is passed, ‘guix challenge’ downloads
     the store items from the given substitute servers so that it can
     compare them.

‘--verbose’
‘-v’
     Show details about matches (identical contents) in addition to
     information about mismatches.


File: guix.info,  Node: Invoking guix copy,  Next: Invoking guix container,  Prev: Invoking guix challenge,  Up: Utilities

10.13 Invoking ‘guix copy’
==========================

The ‘guix copy’ command copies items from the store of one machine to
that of another machine over a secure shell (SSH) connection(1).  For
example, the following command copies the ‘coreutils’ package, the
user’s profile, and all their dependencies over to HOST, logged in as
USER:

     guix copy --to=USER@HOST \
               coreutils $(readlink -f ~/.guix-profile)

   If some of the items to be copied are already present on HOST, they
are not actually sent.

   The command below retrieves ‘libreoffice’ and ‘gimp’ from HOST,
assuming they are available there:

     guix copy --from=HOST libreoffice gimp

   The SSH connection is established using the Guile-SSH client, which
is compatible with OpenSSH: it honors ‘~/.ssh/known_hosts’ and
‘~/.ssh/config’, and uses the SSH agent for authentication.

   The key used to sign items that are sent must be accepted by the
remote machine.  Likewise, the key used by the remote machine to sign
items you are retrieving must be in ‘/etc/guix/acl’ so it is accepted by
your own daemon.  *Note Invoking guix archive::, for more information
about store item authentication.

   The general syntax is:

     guix copy [--to=SPEC|--from=SPEC] ITEMS...

   You must always specify one of the following options:

‘--to=SPEC’
‘--from=SPEC’
     Specify the host to send to or receive from.  SPEC must be an SSH
     spec such as ‘example.org’, ‘charlie@example.org’, or
     ‘charlie@example.org:2222’.

   The ITEMS can be either package names, such as ‘gimp’, or store
items, such as ‘/gnu/store/...-idutils-4.6’.

   When specifying the name of a package to send, it is first built if
needed, unless ‘--dry-run’ was specified.  Common build options are
supported (*note Common Build Options::).

   ---------- Footnotes ----------

   (1) This command is available only when Guile-SSH was found.  *Note
Requirements::, for details.


File: guix.info,  Node: Invoking guix container,  Next: Invoking guix weather,  Prev: Invoking guix copy,  Up: Utilities

10.14 Invoking ‘guix container’
===============================

     Note: As of version 1.4.0, this tool is experimental.  The
     interface is subject to radical change in the future.

   The purpose of ‘guix container’ is to manipulate processes running
within an isolated environment, commonly known as a “container”,
typically created by the ‘guix shell’ (*note Invoking guix shell::) and
‘guix system container’ (*note Invoking guix system::) commands.

   The general syntax is:

     guix container ACTION OPTIONS...

   ACTION specifies the operation to perform with a container, and
OPTIONS specifies the context-specific arguments for the action.

   The following actions are available:

‘exec’
     Execute a command within the context of a running container.

     The syntax is:

          guix container exec PID PROGRAM ARGUMENTS...

     PID specifies the process ID of the running container.  PROGRAM
     specifies an executable file name within the root file system of
     the container.  ARGUMENTS are the additional options that will be
     passed to PROGRAM.

     The following command launches an interactive login shell inside a
     Guix system container, started by ‘guix system container’, and
     whose process ID is 9001:

          guix container exec 9001 /run/current-system/profile/bin/bash --login

     Note that the PID cannot be the parent process of a container.  It
     must be PID 1 of the container or one of its child processes.


File: guix.info,  Node: Invoking guix weather,  Next: Invoking guix processes,  Prev: Invoking guix container,  Up: Utilities

10.15 Invoking ‘guix weather’
=============================

Occasionally you’re grumpy because substitutes are lacking and you end
up building packages by yourself (*note Substitutes::).  The ‘guix
weather’ command reports on substitute availability on the specified
servers so you can have an idea of whether you’ll be grumpy today.  It
can sometimes be useful info as a user, but it is primarily useful to
people running ‘guix publish’ (*note Invoking guix publish::).

   Here’s a sample run:

     $ guix weather --substitute-urls=https://guix.example.org
     computing 5,872 package derivations for x86_64-linux...
     looking for 6,128 store items on https://guix.example.org..
     updating substitutes from 'https://guix.example.org'... 100.0%
     https://guix.example.org
       43.4% substitutes available (2,658 out of 6,128)
       7,032.5 MiB of nars (compressed)
       19,824.2 MiB on disk (uncompressed)
       0.030 seconds per request (182.9 seconds in total)
       33.5 requests per second

       9.8% (342 out of 3,470) of the missing items are queued
       867 queued builds
           x86_64-linux: 518 (59.7%)
           i686-linux: 221 (25.5%)
           aarch64-linux: 128 (14.8%)
       build rate: 23.41 builds per hour
           x86_64-linux: 11.16 builds per hour
           i686-linux: 6.03 builds per hour
           aarch64-linux: 6.41 builds per hour

   As you can see, it reports the fraction of all the packages for which
substitutes are available on the server—regardless of whether
substitutes are enabled, and regardless of whether this server’s signing
key is authorized.  It also reports the size of the compressed archives
(“nars”) provided by the server, the size the corresponding store items
occupy in the store (assuming deduplication is turned off), and the
server’s throughput.  The second part gives continuous integration (CI)
statistics, if the server supports it.  In addition, using the
‘--coverage’ option, ‘guix weather’ can list “important” package
substitutes missing on the server (see below).

   To achieve that, ‘guix weather’ queries over HTTP(S) meta-data
(“narinfos”) for all the relevant store items.  Like ‘guix challenge’,
it ignores signatures on those substitutes, which is innocuous since the
command only gathers statistics and cannot install those substitutes.

   The general syntax is:

     guix weather OPTIONS... [PACKAGES...]

   When PACKAGES is omitted, ‘guix weather’ checks the availability of
substitutes for _all_ the packages, or for those specified with
‘--manifest’; otherwise it only considers the specified packages.  It is
also possible to query specific system types with ‘--system’.  ‘guix
weather’ exits with a non-zero code when the fraction of available
substitutes is below 100%.

   The available options are listed below.

‘--substitute-urls=URLS’
     URLS is the space-separated list of substitute server URLs to
     query.  When this option is omitted, the default set of substitute
     servers is queried.

‘--system=SYSTEM’
‘-s SYSTEM’
     Query substitutes for SYSTEM—e.g., ‘aarch64-linux’.  This option
     can be repeated, in which case ‘guix weather’ will query
     substitutes for several system types.

‘--manifest=FILE’
     Instead of querying substitutes for all the packages, only ask for
     those specified in FILE.  FILE must contain a “manifest”, as with
     the ‘-m’ option of ‘guix package’ (*note Invoking guix package::).

     This option can be repeated several times, in which case the
     manifests are concatenated.

‘--coverage[=COUNT]’
‘-c [COUNT]’
     Report on substitute coverage for packages: list packages with at
     least COUNT dependents (zero by default) for which substitutes are
     unavailable.  Dependent packages themselves are not listed: if B
     depends on A and A has no substitutes, only A is listed, even
     though B usually lacks substitutes as well.  The result looks like
     this:

          $ guix weather --substitute-urls=https://ci.guix.gnu.org https://bordeaux.guix.gnu.org -c 10
          computing 8,983 package derivations for x86_64-linux...
          looking for 9,343 store items on https://ci.guix.gnu.org https://bordeaux.guix.gnu.org...
          updating substitutes from 'https://ci.guix.gnu.org https://bordeaux.guix.gnu.org'... 100.0%
          https://ci.guix.gnu.org https://bordeaux.guix.gnu.org
            64.7% substitutes available (6,047 out of 9,343)
          ...
          2502 packages are missing from 'https://ci.guix.gnu.org https://bordeaux.guix.gnu.org' for 'x86_64-linux', among which:
              58  kcoreaddons@5.49.0      /gnu/store/...-kcoreaddons-5.49.0
              46  qgpgme@1.11.1           /gnu/store/...-qgpgme-1.11.1
              37  perl-http-cookiejar@0.008  /gnu/store/...-perl-http-cookiejar-0.008
              ...

     What this example shows is that ‘kcoreaddons’ and presumably the 58
     packages that depend on it have no substitutes at
     ‘ci.guix.gnu.org’; likewise for ‘qgpgme’ and the 46 packages that
     depend on it.

     If you are a Guix developer, or if you are taking care of this
     build farm, you’ll probably want to have a closer look at these
     packages: they may simply fail to build.

‘--display-missing’
     Display the list of store items for which substitutes are missing.


File: guix.info,  Node: Invoking guix processes,  Prev: Invoking guix weather,  Up: Utilities

10.16 Invoking ‘guix processes’
===============================

The ‘guix processes’ command can be useful to developers and system
administrators, especially on multi-user machines and on build farms: it
lists the current sessions (connections to the daemon), as well as
information about the processes involved(1).  Here’s an example of the
information it returns:

     $ sudo guix processes
     SessionPID: 19002
     ClientPID: 19090
     ClientCommand: guix shell python

     SessionPID: 19402
     ClientPID: 19367
     ClientCommand: guix publish -u guix-publish -p 3000 -C 9 ...

     SessionPID: 19444
     ClientPID: 19419
     ClientCommand: cuirass --cache-directory /var/cache/cuirass ...
     LockHeld: /gnu/store/...-perl-ipc-cmd-0.96.lock
     LockHeld: /gnu/store/...-python-six-bootstrap-1.11.0.lock
     LockHeld: /gnu/store/...-libjpeg-turbo-2.0.0.lock
     ChildPID: 20495
     ChildCommand: guix offload x86_64-linux 7200 1 28800
     ChildPID: 27733
     ChildCommand: guix offload x86_64-linux 7200 1 28800
     ChildPID: 27793
     ChildCommand: guix offload x86_64-linux 7200 1 28800

   In this example we see that ‘guix-daemon’ has three clients: ‘guix
environment’, ‘guix publish’, and the Cuirass continuous integration
tool; their process identifier (PID) is given by the ‘ClientPID’ field.
The ‘SessionPID’ field gives the PID of the ‘guix-daemon’ sub-process of
this particular session.

   The ‘LockHeld’ fields show which store items are currently locked by
this session, which corresponds to store items being built or
substituted (the ‘LockHeld’ field is not displayed when ‘guix processes’
is not running as root).  Last, by looking at the ‘ChildPID’ and
‘ChildCommand’ fields, we understand that these three builds are being
offloaded (*note Daemon Offload Setup::).

   The output is in Recutils format so we can use the handy ‘recsel’
command to select sessions of interest (*note (recutils)Selection
Expressions::).  As an example, the command shows the command line and
PID of the client that triggered the build of a Perl package:

     $ sudo guix processes | \
         recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
     ClientPID: 19419
     ClientCommand: cuirass --cache-directory /var/cache/cuirass ...

   Additional options are listed below.

‘--format=FORMAT’
‘-f FORMAT’
     Produce output in the specified FORMAT, one of:

     ‘recutils’
          The default option.  It outputs a set of Session recutils
          records that include each ‘ChildProcess’ as a field.

     ‘normalized’
          Normalize the output records into record sets (*note
          (recutils)Record Sets::).  Normalizing into record sets allows
          joins across record types.  The example below lists the PID of
          each ‘ChildProcess’ and the associated PID for ‘Session’ that
          spawned the ‘ChildProcess’ where the ‘Session’ was started
          using ‘guix build’.

               $ guix processes --format=normalized | \
                   recsel \
                   -j Session \
                   -t ChildProcess \
                   -p Session.PID,PID \
                   -e 'Session.ClientCommand ~ "guix build"'
               PID: 4435
               Session_PID: 4278

               PID: 4554
               Session_PID: 4278

               PID: 4646
               Session_PID: 4278

   ---------- Footnotes ----------

   (1) Remote sessions, when ‘guix-daemon’ is started with ‘--listen’
specifying a TCP endpoint, are _not_ listed.


File: guix.info,  Node: Foreign Architectures,  Next: System Configuration,  Prev: Utilities,  Up: Top

11 Foreign Architectures
************************

You can target computers of different CPU architectures when producing
packages (*note Invoking guix package::), packs (*note Invoking guix
pack::) or full systems (*note Invoking guix system::).

   GNU Guix supports two distinct mechanisms to target foreign
architectures:

  1. The traditional cross-compilation
     (https://en.wikipedia.org/wiki/Cross_compiler) mechanism.
  2. The native building mechanism which consists in building using the
     CPU instruction set of the foreign system you are targeting.  It
     often requires emulation, using the QEMU program for instance.

* Menu:

* Cross-Compilation::   Cross-compiling for another architecture.
* Native Builds::       Targeting another architecture through native builds.


File: guix.info,  Node: Cross-Compilation,  Next: Native Builds,  Up: Foreign Architectures

11.1 Cross-Compilation
======================

The commands supporting cross-compilation are proposing the
‘--list-targets’ and ‘--target’ options.

   The ‘--list-targets’ option lists all the supported targets that can
be passed as an argument to ‘--target’.

     $ guix build --list-targets
     The available targets are:

        - aarch64-linux-gnu
        - arm-linux-gnueabihf
        - i586-pc-gnu
        - i686-linux-gnu
        - i686-w64-mingw32
        - mips64el-linux-gnu
        - powerpc-linux-gnu
        - powerpc64le-linux-gnu
        - riscv64-linux-gnu
        - x86_64-linux-gnu
        - x86_64-w64-mingw32

   Targets are specified as GNU triplets (*note GNU configuration
triplets: (autoconf)Specifying Target Triplets.).

   Those triplets are passed to GCC and the other underlying compilers
possibly involved when building a package, a system image or any other
GNU Guix output.

     $ guix build --target=aarch64-linux-gnu hello
     /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12

     $ file /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello
     /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello: ELF
     64-bit LSB executable, ARM aarch64 ...

   The major benefit of cross-compilation is that there are no
performance penaly compared to emulation using QEMU. There are however
higher risks that some packages fail to cross-compile because few users
are using this mechanism extensively.


File: guix.info,  Node: Native Builds,  Prev: Cross-Compilation,  Up: Foreign Architectures

11.2 Native Builds
==================

The commands that support impersonating a specific system have the
‘--list-systems’ and ‘--system’ options.

   The ‘--list-systems’ option lists all the supported systems that can
be passed as an argument to ‘--system’.

     $ guix build --list-systems
     The available systems are:

        - x86_64-linux [current]
        - aarch64-linux
        - armhf-linux
        - i586-gnu
        - i686-linux
        - mips64el-linux
        - powerpc-linux
        - powerpc64le-linux
        - riscv64-linux

     $ guix build --system=i686-linux hello
     /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12

     $ file /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello
     /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello: ELF
     32-bit LSB executable, Intel 80386 ...

   In the above example, the current system is X86_64-LINUX.  The HELLO
package is however built for the I686-LINUX system.

   This is possible because the I686 CPU instruction set is a subset of
the X86_64, hence I686 targeting binaries can be run on X86_64.

   Still in the context of the previous example, if picking the
AARCH64-LINUX system and the ‘guix build --system=aarch64-linux hello’
has to build some derivations, an extra step might be needed.

   The AARCH64-LINUX targeting binaries cannot directly be run on a
X86_64-LINUX system.  An emulation layer is requested.  The GNU Guix
daemon can take advantage of the Linux kernel binfmt_misc
(https://en.wikipedia.org/wiki/Binfmt_misc) mechanism for that.  In
short, the Linux kernel can defer the execution of a binary targeting a
foreign platform, here AARCH64-LINUX, to a userspace program, usually an
emulator.

   There is a service that registers QEMU as a backend for the
‘binfmt_misc’ mechanism (*note ‘qemu-binfmt-service-type’:
Virtualization Services.).  On Debian based foreign distributions, the
alternative would be the ‘qemu-user-static’ package.

   If the ‘binfmt_misc’ mechanism is not setup correctly, the building
will fail this way:

     $ guix build --system=armhf-linux hello --check
     ...
      unsupported-platform /gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv aarch64-linux
     while setting up the build environment: a `aarch64-linux' is required to
     build `/gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv', but
     I am a `x86_64-linux'...

   whereas, with the ‘binfmt_misc’ mechanism correctly linked with QEMU,
one can expect to see:

     $ guix build --system=armhf-linux hello --check
     /gnu/store/13xz4nghg39wpymivlwghy08yzj97hlj-hello-2.12

   The main advantage of native building compared to cross-compiling, is
that more packages are likely to build correctly.  However it comes at a
price: compilation backed by QEMU is _way slower_ than
cross-compilation, because every instruction needs to be emulated.

   The availability of substitutes for the architecture targeted by the
‘--system’ option can mitigate this problem.  An other way to work
around it is to install GNU Guix on a machine whose CPU supports the
targeted instruction set, and set it up as an offload machine (*note
Daemon Offload Setup::).


File: guix.info,  Node: System Configuration,  Next: Home Configuration,  Prev: Foreign Architectures,  Up: Top

12 System Configuration
***********************

Guix System supports a consistent whole-system configuration mechanism.
By that we mean that all aspects of the global system configuration—such
as the available system services, timezone and locale settings, user
accounts—are declared in a single place.  Such a “system configuration”
can be “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 (*note Features::).  Another
advantage 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 own tools of the system.

   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.
* Swap Space::                  Backing RAM with disk space.
* User Accounts::               Specifying user accounts.
* Keyboard Layout::             How the system interprets key strokes.
* Locales::                     Language and cultural convention settings.
* Services::                    Specifying system services.
* Setuid Programs::             Programs running with elevated privileges.
* X.509 Certificates::          Authenticating HTTPS servers.
* Name Service Switch::         Configuring libc’s name service switch.
* Initial RAM Disk::            Linux-Libre bootstrapping.
* Bootloader Configuration::    Configuring the boot loader.
* Invoking guix system::        Instantiating a system configuration.
* Invoking guix deploy::        Deploying a system configuration to a remote host.
* Running Guix in a VM::        How to run Guix System in a virtual machine.
* Defining Services::           Adding new service definitions.


File: guix.info,  Node: Using the Configuration System,  Next: operating-system Reference,  Up: System Configuration

12.1 Using the Configuration System
===================================

The operating system is configured by providing an ‘operating-system’
declaration in a file that can then be passed to the ‘guix system’
command (*note 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:

     ;; This is an operating system configuration template
     ;; for a "bare bones" setup, with no X11 display server.

     (use-modules (gnu))
     (use-service-modules networking ssh)
     (use-package-modules screen ssh)

     (operating-system
       (host-name "komputilo")
       (timezone "Europe/Berlin")
       (locale "en_US.utf8")

       ;; Boot in "legacy" BIOS mode, assuming /dev/sdX is the
       ;; target hard disk, and "my-root" is the label of the target
       ;; root file system.
       (bootloader (bootloader-configuration
                     (bootloader grub-bootloader)
                     (targets '("/dev/sdX"))))
       ;; It's fitting to support the equally bare bones ‘-nographic’
       ;; QEMU option, which also nicely sidesteps forcing QWERTY.
       (kernel-arguments (list "console=ttyS0,115200"))
       (file-systems (cons (file-system
                             (device (file-system-label "my-root"))
                             (mount-point "/")
                             (type "ext4"))
                           %base-file-systems))

       ;; This is where user accounts are specified.  The "root"
       ;; account is implicit, and is initially created with the
       ;; empty password.
       (users (cons (user-account
                     (name "alice")
                     (comment "Bob's sister")
                     (group "users")

                     ;; Adding the account to the "wheel" group
                     ;; makes it a sudoer.  Adding it to "audio"
                     ;; and "video" allows the user to play sound
                     ;; and access the webcam.
                     (supplementary-groups '("wheel"
                                             "audio" "video")))
                    %base-user-accounts))

       ;; Globally-installed packages.
       (packages (cons screen %base-packages))

       ;; Add services to the baseline: a DHCP client and
       ;; an SSH server.
       (services (append (list (service dhcp-client-service-type)
                               (service openssh-service-type
                                        (openssh-configuration
                                         (openssh openssh-sans-x)
                                         (port-number 2222))))
                         %base-services)))

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

   Below we discuss the effect of some of the most important fields
(*note operating-system Reference::, for details about all the available
fields), and how to “instantiate” the operating system using ‘guix
system’.

Bootloader
----------

The ‘bootloader’ field describes the method that will be used to boot
your system.  Machines based on Intel processors can boot in “legacy”
BIOS mode, as in the example above.  However, more recent machines rely
instead on the “Unified Extensible Firmware Interface” (UEFI) to boot.
In that case, the ‘bootloader’ field should contain something along
these lines:

     (bootloader-configuration
       (bootloader grub-efi-bootloader)
       (targets '("/boot/efi")))

   *Note Bootloader Configuration::, for more information on the
available configuration options.

Globally-Visible Packages
-------------------------

The ‘packages’ field lists packages that will be globally visible on the
system, for all user accounts—i.e., in every user’s ‘PATH’ environment
variable—in addition to the per-user profiles (*note Invoking guix
package::).  The ‘%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 ‘mg’ lightweight text
editor, ‘find’, ‘grep’, etc.  The example above adds GNU Screen to
those, taken from the ‘(gnu packages screen)’ module (*note Package
Modules::).  The ‘(list package output)’ syntax can be used to add a
specific output of a package:

     (use-modules (gnu packages))
     (use-modules (gnu packages dns))

     (operating-system
       ;; ...
       (packages (cons (list isc-bind "utils")
                       %base-packages)))

   Referring to packages by variable name, like ‘isc-bind’ above, has
the advantage of being unambiguous; it also allows typos and such to be
diagnosed right away as “unbound variables”.  The downside is that one
needs to know which module defines which package, and to augment the
‘use-package-modules’ line accordingly.  To avoid that, one can use the
‘specification->package’ procedure of the ‘(gnu packages)’ module, which
returns the best package for a given name or name and version:

     (use-modules (gnu packages))

     (operating-system
       ;; ...
       (packages (append (map specification->package
                              '("tcpdump" "htop" "gnupg@2.0"))
                         %base-packages)))

System Services
---------------

The ‘services’ field lists “system services” to be made available when
the system starts (*note Services::).  The ‘operating-system’
declaration above specifies that, in addition to the basic services, we
want the OpenSSH secure shell daemon listening on port 2222 (*note
‘openssh-service-type’: Networking Services.).  Under the hood,
‘openssh-service-type’ arranges so that ‘sshd’ is started with the right
command-line options, possibly with supporting configuration files
generated as needed (*note Defining Services::).

   Occasionally, instead of using the base services as is, you will want
to customize them.  To do this, use ‘modify-services’ (*note
‘modify-services’: Service Reference.) to modify the list.

   For example, suppose you want to modify ‘guix-daemon’ and Mingetty
(the console log-in) in the ‘%base-services’ list (*note
‘%base-services’: Base Services.).  To do that, you can write the
following in your operating system declaration:

     (define %my-services
       ;; My very own list of services.
       (modify-services %base-services
         (guix-service-type config =>
                            (guix-configuration
                             (inherit config)
                             ;; Fetch substitutes from example.org.
                             (substitute-urls
                               (list "https://example.org/guix"
                                     "https://ci.guix.gnu.org"))))
         (mingetty-service-type config =>
                                (mingetty-configuration
                                 (inherit config)
                                 ;; Automatically log in as "guest".
                                 (auto-login "guest")))))

     (operating-system
       ;; ...
       (services %my-services))

   This changes the configuration—i.e., the service parameters—of the
‘guix-service-type’ instance, and that of all the
‘mingetty-service-type’ instances in the ‘%base-services’ list (*note
see the cookbook for how to auto-login one user to a specific TTY:
(guix-cookbook)Auto-Login to a Specific TTY.)). Observe how this is
accomplished: first, we arrange for the original configuration to be
bound to the identifier ‘config’ in the BODY, and then we write the BODY
so that it evaluates to the desired configuration.  In particular,
notice how we use ‘inherit’ to create a new configuration which has the
same values as the old configuration, but with a few modifications.

   The configuration for a typical “desktop” usage, with an encrypted
root partition, a swap file on the root partition, the X11 display
server, GNOME and Xfce (users can choose which of these desktop
environments to use at the log-in screen by pressing ‘F1’), network
management, power management, and more, would look like this:

     ;; This is an operating system configuration template
     ;; for a "desktop" setup with GNOME and Xfce where the
     ;; root partition is encrypted with LUKS, and a swap file.

     (use-modules (gnu) (gnu system nss) (guix utils))
     (use-service-modules desktop sddm xorg)
     (use-package-modules certs gnome)

     (operating-system
       (host-name "antelope")
       (timezone "Europe/Paris")
       (locale "en_US.utf8")

       ;; Choose US English keyboard layout.  The "altgr-intl"
       ;; variant provides dead keys for accented characters.
       (keyboard-layout (keyboard-layout "us" "altgr-intl"))

       ;; Use the UEFI variant of GRUB with the EFI System
       ;; Partition mounted on /boot/efi.
       (bootloader (bootloader-configuration
                     (bootloader grub-efi-bootloader)
                     (targets '("/boot/efi"))
                     (keyboard-layout keyboard-layout)))

       ;; Specify a mapped device for the encrypted root partition.
       ;; The UUID is that returned by 'cryptsetup luksUUID'.
       (mapped-devices
        (list (mapped-device
               (source (uuid "12345678-1234-1234-1234-123456789abc"))
               (target "my-root")
               (type luks-device-mapping))))

       (file-systems (append
                      (list (file-system
                              (device (file-system-label "my-root"))
                              (mount-point "/")
                              (type "ext4")
                              (dependencies mapped-devices))
                            (file-system
                              (device (uuid "1234-ABCD" 'fat))
                              (mount-point "/boot/efi")
                              (type "vfat")))
                      %base-file-systems))

       ;; Specify a swap file for the system, which resides on the
       ;; root file system.
       (swap-devices (list (swap-space
                            (target "/swapfile"))))

       ;; Create user `bob' with `alice' as its initial password.
       (users (cons (user-account
                     (name "bob")
                     (comment "Alice's brother")
                     (password (crypt "alice" "$6$abc"))
                     (group "students")
                     (supplementary-groups '("wheel" "netdev"
                                             "audio" "video")))
                    %base-user-accounts))

       ;; Add the `students' group
       (groups (cons* (user-group
                       (name "students"))
                      %base-groups))

       ;; This is where we specify system-wide packages.
       (packages (append (list
                          ;; for HTTPS access
                          nss-certs
                          ;; for user mounts
                          gvfs)
                         %base-packages))

       ;; Add GNOME and Xfce---we can choose at the log-in screen
       ;; by clicking the gear.  Use the "desktop" services, which
       ;; include the X11 log-in service, networking with
       ;; NetworkManager, and more.
       (services (if (target-x86-64?)
                     (append (list (service gnome-desktop-service-type)
                                   (service xfce-desktop-service-type)
                                   (set-xorg-configuration
                                    (xorg-configuration
                                     (keyboard-layout keyboard-layout))))
                             %desktop-services)

                     ;; FIXME: Since GDM depends on Rust (gdm -> gnome-shell -> gjs
                     ;; -> mozjs -> rust) and Rust is currently unavailable on
                     ;; non-x86_64 platforms, we use SDDM and Mate here instead of
                     ;; GNOME and GDM.
                     (append (list (service mate-desktop-service-type)
                                   (service xfce-desktop-service-type)
                                   (set-xorg-configuration
                                    (xorg-configuration
                                     (keyboard-layout keyboard-layout))
                                    sddm-service-type))
                             %desktop-services)))

       ;; Allow resolution of '.local' host names with mDNS.
       (name-service-switch %mdns-host-lookup-nss))

   A graphical system with a choice of lightweight window managers
instead of full-blown desktop environments would look like this:

     ;; This is an operating system configuration template
     ;; for a "desktop" setup without full-blown desktop
     ;; environments.

     (use-modules (gnu) (gnu system nss))
     (use-service-modules desktop)
     (use-package-modules bootloaders certs emacs emacs-xyz ratpoison suckless wm
                          xorg)

     (operating-system
       (host-name "antelope")
       (timezone "Europe/Paris")
       (locale "en_US.utf8")

       ;; Use the UEFI variant of GRUB with the EFI System
       ;; Partition mounted on /boot/efi.
       (bootloader (bootloader-configuration
                     (bootloader grub-efi-bootloader)
                     (targets '("/boot/efi"))))

       ;; Assume the target root file system is labelled "my-root",
       ;; and the EFI System Partition has UUID 1234-ABCD.
       (file-systems (append
                      (list (file-system
                              (device (file-system-label "my-root"))
                              (mount-point "/")
                              (type "ext4"))
                            (file-system
                              (device (uuid "1234-ABCD" 'fat))
                              (mount-point "/boot/efi")
                              (type "vfat")))
                      %base-file-systems))

       (users (cons (user-account
                     (name "alice")
                     (comment "Bob's sister")
                     (group "users")
                     (supplementary-groups '("wheel" "netdev"
                                             "audio" "video")))
                    %base-user-accounts))

       ;; Add a bunch of window managers; we can choose one at
       ;; the log-in screen with F1.
       (packages (append (list
                          ;; window managers
                          ratpoison i3-wm i3status dmenu
                          emacs emacs-exwm emacs-desktop-environment
                          ;; terminal emulator
                          xterm
                          ;; for HTTPS access
                          nss-certs)
                         %base-packages))

       ;; Use the "desktop" services, which include the X11
       ;; log-in service, networking with NetworkManager, and more.
       (services %desktop-services)

       ;; Allow resolution of '.local' host names with mDNS.
       (name-service-switch %mdns-host-lookup-nss))

   This example refers to the ‘/boot/efi’ file system by its UUID,
‘1234-ABCD’.  Replace this UUID with the right UUID on your system, as
returned by the ‘blkid’ command.

   *Note Desktop Services::, for the exact list of services provided by
‘%desktop-services’.  *Note X.509 Certificates::, for background
information about the ‘nss-certs’ package that is used here.

   Again, ‘%desktop-services’ is just a list of service objects.  If you
want to remove services from there, you can do so using the procedures
for list filtering (*note (guile)SRFI-1 Filtering and Partitioning::).
For instance, the following expression returns a list that contains all
the services in ‘%desktop-services’ minus the Avahi service:

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

   Alternatively, the ‘modify-services’ macro can be used:

     (modify-services %desktop-services
       (delete avahi-service-type))

Instantiating the System
------------------------

Assuming the ‘operating-system’ declaration is stored in the
‘my-system-config.scm’ file, the ‘guix system reconfigure
my-system-config.scm’ command instantiates that configuration, and makes
it the default GRUB boot entry (*note Invoking guix system::).

     Note: We recommend that you keep this ‘my-system-config.scm’ file
     safe and under version control to easily track changes to your
     configuration.

   The normal way to change the system configuration is by updating this
file and re-running ‘guix system reconfigure’.  One should never have to
touch files in ‘/etc’ or to run commands that modify the system state
such as ‘useradd’ or ‘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.

   Speaking of roll-back, each time you run ‘guix system reconfigure’, a
new “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 ‘guix system
list-generations’ command lists the system generations available on
disk.  It is also possible to roll back the system via the commands
‘guix system roll-back’ and ‘guix system switch-generation’.

   Although the ‘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 ‘guix system roll-back’), since the
operation might overwrite a later generation (*note Invoking guix
system::).

The Programming Interface
-------------------------

At the Scheme level, the bulk of an ‘operating-system’ declaration is
instantiated with the following monadic procedure (*note The Store
Monad::):

 -- Monadic Procedure: operating-system-derivation os
     Return a derivation that builds OS, an ‘operating-system’ object
     (*note 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 OS.

   This procedure is provided by the ‘(gnu system)’ module.  Along with
‘(gnu services)’ (*note Services::), this module contains the guts of
Guix System.  Make sure to visit it!


File: guix.info,  Node: operating-system Reference,  Next: File Systems,  Prev: Using the Configuration System,  Up: System Configuration

12.2 ‘operating-system’ Reference
=================================

This section summarizes all the options available in ‘operating-system’
declarations (*note Using the Configuration System::).

 -- 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 (*note Using the
     Configuration System::).

     ‘kernel’ (default: ‘linux-libre’)
          The package object of the operating system kernel to use(1).

     ‘hurd’ (default: ‘#f’)
          The package object of the Hurd to be started by the kernel.
          When this field is set, produce a GNU/Hurd operating system.
          In that case, ‘kernel’ must also be set to the ‘gnumach’
          package—the microkernel the Hurd runs on.

               Warning: This feature is experimental and only supported
               for disk images.

     ‘kernel-loadable-modules’ (default: ’())
          A list of objects (usually packages) to collect loadable
          kernel modules from–e.g.  ‘(list ddcci-driver-linux)’.

     ‘kernel-arguments’ (default: ‘%default-kernel-arguments’)
          List of strings or gexps representing additional arguments to
          pass on the command-line of the kernel—e.g.,
          ‘("console=ttyS0")’.

     ‘bootloader’
          The system bootloader configuration object.  *Note Bootloader
          Configuration::.

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

     ‘keyboard-layout’ (default: ‘#f’)
          This field specifies the keyboard layout to use in the
          console.  It can be either ‘#f’, in which case the default
          keyboard layout is used (usually US English), or a
          ‘<keyboard-layout>’ record.  *Note Keyboard Layout::, for more
          information.

          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
          ‘luks-device-mapping’ mapped device (*note Mapped Devices::).

               Note: This does _not_ specify the keyboard layout used by
               the bootloader, nor that used by the graphical display
               server.  *Note Bootloader Configuration::, for
               information on how to specify the bootloader’s keyboard
               layout.  *Note X Window::, for information on how to
               specify the keyboard layout used by the X Window System.

     ‘initrd-modules’ (default: ‘%base-initrd-modules’)
          The list of Linux kernel modules that need to be available in
          the initial RAM disk.  *Note Initial RAM Disk::.

     ‘initrd’ (default: ‘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.
          *Note Initial RAM Disk::.

     ‘firmware’ (default: ‘%base-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 ‘ath9k’ and
          ‘b43-open’, respectively).  *Note Hardware Considerations::,
          for more info on supported hardware.

     ‘host-name’
          The host name.

     ‘hosts-file’
          A file-like object (*note file-like objects: G-Expressions.)
          for use as ‘/etc/hosts’ (*note (libc)Host Names::).  The
          default is a file with entries for ‘localhost’ and HOST-NAME.

     ‘mapped-devices’ (default: ‘'()’)
          A list of mapped devices.  *Note Mapped Devices::.

     ‘file-systems’
          A list of file systems.  *Note File Systems::.

     ‘swap-devices’ (default: ‘'()’)
          A list of swap spaces.  *Note Swap Space::.

     ‘users’ (default: ‘%base-user-accounts’)
     ‘groups’ (default: ‘%base-groups’)
          List of user accounts and groups.  *Note User Accounts::.

          If the ‘users’ list lacks a user account with UID 0, a “root”
          account with UID 0 is automatically added.

     ‘skeletons’ (default: ‘(default-skeletons)’)
          A list of target file name/file-like object tuples (*note
          file-like objects: G-Expressions.).  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:

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

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

     ‘packages’ (default: ‘%base-packages’)
          A list of packages to be installed in the global profile,
          which is accessible at ‘/run/current-system/profile’.  Each
          element is either a package variable or a package/output
          tuple.  Here’s a simple example of both:

               (cons* git                     ; the default "out" output
                      (list git "send-email") ; another output of git
                      %base-packages)         ; the default set

          The default set includes core utilities and it is good
          practice to install non-core utilities in user profiles (*note
          Invoking guix package::).

     ‘timezone’ (default: ‘"Etc/UTC"’)
          A timezone identifying string—e.g., ‘"Europe/Paris"’.

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

     ‘locale’ (default: ‘"en_US.utf8"’)
          The name of the default locale (*note (libc)Locale Names::).
          *Note Locales::, for more information.

     ‘locale-definitions’ (default: ‘%default-locale-definitions’)
          The list of locale definitions to be compiled and that may be
          used at run time.  *Note Locales::.

     ‘locale-libcs’ (default: ‘(list GLIBC)’)
          The list of GNU libc packages whose locale data and tools are
          used to build the locale definitions.  *Note Locales::, for
          compatibility considerations that justify this option.

     ‘name-service-switch’ (default: ‘%default-nss’)
          Configuration of the libc name service switch (NSS)—a
          ‘<name-service-switch>’ object.  *Note Name Service Switch::,
          for details.

     ‘services’ (default: ‘%base-services’)
          A list of service objects denoting system services.  *Note
          Services::.

     ‘essential-services’ (default: ...)
          The list of “essential services”—i.e., things like instances
          of ‘system-service-type’ and ‘host-name-service-type’ (*note
          Service Reference::), which are derived from the operating
          system definition itself.  As a user you should _never_ need
          to touch this field.

     ‘pam-services’ (default: ‘(base-pam-services)’)
          Linux “pluggable authentication module” (PAM) services.

     ‘setuid-programs’ (default: ‘%setuid-programs’)
          List of ‘<setuid-program>’.  *Note Setuid Programs::, for more
          information.

     ‘sudoers-file’ (default: ‘%sudoers-specification’)
          The contents of the ‘/etc/sudoers’ file as a file-like object
          (*note ‘local-file’ and ‘plain-file’: G-Expressions.).

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

      -- Scheme Syntax: this-operating-system
          When used in the _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 ‘label’ field:

               (use-modules (gnu) (guix))

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

          It is an error to refer to ‘this-operating-system’ outside an
          operating system definition.

   ---------- Footnotes ----------

   (1) Currently only the Linux-libre kernel is fully supported.  Using
GNU mach with the GNU Hurd is experimental and only available when
building a virtual machine disk image.


File: guix.info,  Node: File Systems,  Next: Mapped Devices,  Prev: operating-system Reference,  Up: System Configuration

12.3 File Systems
=================

The list of file systems to be mounted is specified in the
‘file-systems’ field of the operating system declaration (*note Using
the Configuration System::).  Each file system is declared using the
‘file-system’ form, like this:

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

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

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

     ‘type’
          This is a string specifying the type of the file system—e.g.,
          ‘"ext4"’.

     ‘mount-point’
          This designates the place where the file system is to be
          mounted.

     ‘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 ‘/dev’ node.  Labels and UUIDs offer a way to refer
          to file systems without having to hard-code their actual
          device name(1).

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

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

          UUIDs are converted from their string representation (as shown
          by the ‘tune2fs -l’ command) using the ‘uuid’ form(2), like
          this:

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

          When the source of a file system is a mapped device (*note
          Mapped Devices::), its ‘device’ field _must_ refer to the
          mapped device name—e.g., ‘"/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.

     ‘flags’ (default: ‘'()’)
          This is a list of symbols denoting mount flags.  Recognized
          flags include ‘read-only’, ‘bind-mount’, ‘no-dev’ (disallow
          access to special files), ‘no-suid’ (ignore setuid and setgid
          bits), ‘no-atime’ (do not update file access times),
          ‘no-diratime’ (likewise for directories only), ‘strict-atime’
          (update file access time), ‘lazy-time’ (only update time on
          the in-memory version of the file inode), ‘no-exec’ (disallow
          program execution), and ‘shared’ (make the mount shared).
          *Note (libc)Mount-Unmount-Remount::, for more information on
          these flags.

     ‘options’ (default: ‘#f’)
          This is either ‘#f’, or a string denoting mount options passed
          to the file system driver.  *Note
          (libc)Mount-Unmount-Remount::, for details.

          Run ‘man 8 mount’ for options for various file systems, but
          beware that what it lists as file-system-independent “mount
          options” are in fact flags, and belong in the ‘flags’ field
          described above.

          The ‘file-system-options->alist’ and
          ‘alist->file-system-options’ procedures from ‘(gnu system
          file-systems)’ can be used to convert file system options
          given as an association list to the string representation, and
          vice-versa.

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

     ‘needed-for-boot?’ (default: ‘#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.

     ‘check?’ (default: ‘#t’)
          This Boolean indicates whether the file system should be
          checked for errors before being mounted.  How and when this
          happens can be further adjusted with the following options.

     ‘skip-check-if-clean?’ (default: ‘#t’)
          When true, this Boolean indicates that a file system check
          triggered by ‘check?’ may exit early if the file system is
          marked as “clean”, meaning that it was previously correctly
          unmounted and should not contain errors.

          Setting this to false will always force a full consistency
          check when ‘check?’ is true.  This may take a very long time
          and is not recommended on healthy systems—in fact, it may
          reduce reliability!

          Conversely, some primitive file systems like ‘fat’ do not keep
          track of clean shutdowns and will perform a full scan
          regardless of the value of this option.

     ‘repair’ (default: ‘'preen’)
          When ‘check?’ finds errors, it can (try to) repair them and
          continue booting.  This option controls when and how to do so.

          If false, try not to modify the file system at all.  Checking
          certain file systems like ‘jfs’ may still write to the device
          to replay the journal.  No repairs will be attempted.

          If ‘#t’, try to repair any errors found and assume “yes” to
          all questions.  This will fix the most errors, but may be
          risky.

          If ‘'preen’, repair only errors that are safe to fix without
          human interaction.  What that means is left up to the
          developers of each file system and may be equivalent to “none”
          or “all”.

     ‘create-mount-point?’ (default: ‘#f’)
          When true, the mount point is created if it does not exist
          yet.

     ‘mount-may-fail?’ (default: ‘#f’)
          When true, this indicates that mounting this file system can
          fail but that should not be considered an error.  This is
          useful in unusual cases; an example of this is ‘efivarfs’, a
          file system that can only be mounted on EFI/UEFI systems.

     ‘dependencies’ (default: ‘'()’)
          This is a list of ‘<file-system>’ or ‘<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:
          ‘/sys/fs/cgroup’ is a dependency of ‘/sys/fs/cgroup/cpu’ and
          ‘/sys/fs/cgroup/memory’.

          Another example is a file system that depends on a mapped
          device, for example for an encrypted partition (*note Mapped
          Devices::).

 -- Scheme Procedure: file-system-label STR
     This procedure returns an opaque file system label from STR, a
     string:

          (file-system-label "home")
          ⇒ #<file-system-label "home">

     File system labels are used to refer to file systems by label
     rather than by device name.  See above for examples.

   The ‘(gnu system file-systems)’ exports the following useful
variables.

 -- Scheme Variable: %base-file-systems
     These are essential file systems that are required on normal
     systems, such as ‘%pseudo-terminal-file-system’ and
     ‘%immutable-store’ (see below).  Operating system declarations
     should always contain at least these.

 -- Scheme Variable: %pseudo-terminal-file-system
     This is the file system to be mounted as ‘/dev/pts’.  It supports
     “pseudo-terminals” created via ‘openpty’ and similar functions
     (*note (libc)Pseudo-Terminals::).  Pseudo-terminals are used by
     terminal emulators such as ‘xterm’.

 -- Scheme Variable: %shared-memory-file-system
     This file system is mounted as ‘/dev/shm’ and is used to support
     memory sharing across processes (*note ‘shm_open’:
     (libc)Memory-mapped I/O.).

 -- Scheme Variable: %immutable-store
     This file system performs a read-only “bind mount” of ‘/gnu/store’,
     making it read-only for all the users including ‘root’.  This
     prevents against accidental modification by software running as
     ‘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.”

 -- Scheme Variable: %binary-format-file-system
     The ‘binfmt_misc’ file system, which allows handling of arbitrary
     executable file types to be delegated to user space.  This requires
     the ‘binfmt.ko’ kernel module to be loaded.

 -- Scheme Variable: %fuse-control-file-system
     The ‘fusectl’ file system, which allows unprivileged users to mount
     and unmount user-space FUSE file systems.  This requires the
     ‘fuse.ko’ kernel module to be loaded.

   The ‘(gnu system uuid)’ module provides tools to deal with file
system “unique identifiers” (UUIDs).

 -- Scheme Procedure: uuid STR [TYPE]
     Return an opaque UUID (unique identifier) object of the given TYPE
     (a symbol) by parsing STR (a string):

          (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")
          ⇒ #<<uuid> type: dce bv: ...>

          (uuid "1234-ABCD" 'fat)
          ⇒ #<<uuid> type: fat bv: ...>

     TYPE may be one of ‘dce’, ‘iso9660’, ‘fat’, ‘ntfs’, or one of the
     commonly found synonyms for these.

     UUIDs are another way to unambiguously refer to file systems in
     operating system configuration.  See the examples above.

* Menu:

* Btrfs file system::

   ---------- Footnotes ----------

   (1) Note that, while it is tempting to use ‘/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.

   (2) The ‘uuid’ form expects 16-byte UUIDs as defined in RFC 4122
(https://tools.ietf.org/html/rfc4122).  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.


File: guix.info,  Node: Btrfs file system,  Up: File Systems

12.3.1 Btrfs file system
------------------------

The Btrfs has special features, such as subvolumes, that merit being
explained in more details.  The following section attempts to cover
basic as well as complex uses of a Btrfs file system with the Guix
System.

   In its simplest usage, a Btrfs file system can be described, for
example, by:

     (file-system
       (mount-point "/home")
       (type "btrfs")
       (device (file-system-label "my-home")))

   The example below is more complex, as it makes use of a Btrfs
subvolume, named ‘rootfs’.  The parent Btrfs file system is labeled
‘my-btrfs-pool’, and is located on an encrypted device (hence the
dependency on ‘mapped-devices’):

     (file-system
       (device (file-system-label "my-btrfs-pool"))
       (mount-point "/")
       (type "btrfs")
       (options "subvol=rootfs")
       (dependencies mapped-devices))

   Some bootloaders, for example GRUB, only mount a Btrfs partition at
its top level during the early boot, and rely on their configuration to
refer to the correct subvolume path within that top level.  The
bootloaders operating in this way typically produce their configuration
on a running system where the Btrfs partitions are already mounted and
where the subvolume information is readily available.  As an example,
‘grub-mkconfig’, the configuration generator command shipped with GRUB,
reads ‘/proc/self/mountinfo’ to determine the top-level path of a
subvolume.

   The Guix System produces a bootloader configuration using the
operating system configuration as its sole input; it is therefore
necessary to extract the subvolume name on which ‘/gnu/store’ lives (if
any) from that operating system configuration.  To better illustrate,
consider a subvolume named ’rootfs’ which contains the root file system
data.  In such situation, the GRUB bootloader would only see the top
level of the root Btrfs partition, e.g.:

     /                   (top level)
     ├── rootfs          (subvolume directory)
         ├── gnu         (normal directory)
             ├── store   (normal directory)
     [...]

   Thus, the subvolume name must be prepended to the ‘/gnu/store’ path
of the kernel, initrd binaries and any other files referred to in the
GRUB configuration that must be found during the early boot.

   The next example shows a nested hierarchy of subvolumes and
directories:

     /                   (top level)
     ├── rootfs          (subvolume)
         ├── gnu         (normal directory)
             ├── store   (subvolume)
     [...]

   This scenario would work without mounting the ’store’ subvolume.
Mounting ’rootfs’ is sufficient, since the subvolume name matches its
intended mount point in the file system hierarchy.  Alternatively, the
’store’ subvolume could be referred to by setting the ‘subvol’ option to
either ‘/rootfs/gnu/store’ or ‘rootfs/gnu/store’.

   Finally, a more contrived example of nested subvolumes:

     /                           (top level)
     ├── root-snapshots          (subvolume)
         ├── root-current        (subvolume)
             ├── guix-store      (subvolume)
     [...]

   Here, the ’guix-store’ subvolume doesn’t match its intended mount
point, so it is necessary to mount it.  The subvolume must be fully
specified, by passing its file name to the ‘subvol’ option.  To
illustrate, the ’guix-store’ subvolume could be mounted on ‘/gnu/store’
by using a file system declaration such as:

     (file-system
       (device (file-system-label "btrfs-pool-1"))
       (mount-point "/gnu/store")
       (type "btrfs")
       (options "subvol=root-snapshots/root-current/guix-store,\
     compress-force=zstd,space_cache=v2"))


File: guix.info,  Node: Mapped Devices,  Next: Swap Space,  Prev: File Systems,  Up: System Configuration

12.4 Mapped Devices
===================

The Linux kernel has a notion of “device mapping”: a block device, such
as a hard disk partition, can be “mapped” into another device, usually
in ‘/dev/mapper/’, with additional processing over the data that flows
through it(1).  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 “transformed” in some way to create a new
device; for instance, RAID devices are obtained by “assembling” several
other devices, such as hard disks or partitions, into a new one that
behaves as one partition.

   Mapped devices are declared using the ‘mapped-device’ form, defined
as follows; for examples, see below.

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

     ‘source’
          This is either a string specifying the name of the block
          device to be mapped, such as ‘"/dev/sda3"’, or a list of such
          strings when several devices need to be assembled for creating
          a new one.  In case of LVM this is a string specifying name of
          the volume group to be mapped.

     ‘target’
          This string specifies the name of the resulting mapped device.
          For kernel mappers such as encrypted devices of type
          ‘luks-device-mapping’, specifying ‘"my-partition"’ leads to
          the creation of the ‘"/dev/mapper/my-partition"’ device.  For
          RAID devices of type ‘raid-device-mapping’, the full device
          name such as ‘"/dev/md0"’ needs to be given.  LVM logical
          volumes of type ‘lvm-device-mapping’ need to be specified as
          ‘"VGNAME-LVNAME"’.

     ‘targets’
          This list of strings specifies names of the resulting mapped
          devices in case there are several.  The format is identical to
          TARGET.

     ‘type’
          This must be a ‘mapped-device-kind’ object, which specifies
          how SOURCE is mapped to TARGET.

 -- Scheme Variable: luks-device-mapping
     This defines LUKS block device encryption using the ‘cryptsetup’
     command from the package with the same name.  It relies on the
     ‘dm-crypt’ Linux kernel module.

 -- Scheme Variable: raid-device-mapping
     This defines a RAID device, which is assembled using the ‘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
     ‘raid456’ for RAID-4, RAID-5 or RAID-6, or ‘raid10’ for RAID-10.

 -- Scheme Variable: lvm-device-mapping
     This defines one or more logical volumes for the Linux Logical
     Volume Manager (LVM) (https://www.sourceware.org/lvm2/).  The
     volume group is activated by the ‘vgchange’ command from the ‘lvm2’
     package.

   The following example specifies a mapping from ‘/dev/sda3’ to
‘/dev/mapper/home’ using LUKS—the Linux Unified Key Setup
(https://gitlab.com/cryptsetup/cryptsetup), a standard mechanism for
disk encryption.  The ‘/dev/mapper/home’ device can then be used as the
‘device’ of a ‘file-system’ declaration (*note File Systems::).

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

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

     cryptsetup luksUUID /dev/sda3

   and use it as follows:

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

   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.
*Note Swap Space::, or *Note Disk Partitioning: Preparing for
Installation, for an example.

   A RAID device formed of the partitions ‘/dev/sda1’ and ‘/dev/sdb1’
may be declared as follows:

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

   The ‘/dev/md0’ device can then be used as the ‘device’ of a
‘file-system’ declaration (*note 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.

   LVM logical volumes “alpha” and “beta” from volume group “vg0” can be
declared as follows:

     (mapped-device
       (source "vg0")
       (targets (list "vg0-alpha" "vg0-beta"))
       (type lvm-device-mapping))

   Devices ‘/dev/mapper/vg0-alpha’ and ‘/dev/mapper/vg0-beta’ can then
be used as the ‘device’ of a ‘file-system’ declaration (*note File
Systems::).

   ---------- Footnotes ----------

   (1) Note that the GNU Hurd makes no difference between the concept of
a “mapped device” and that of a file system: both boil down to
_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 “translator” mechanism (*note
(hurd)Translators::).


File: guix.info,  Node: Swap Space,  Next: User Accounts,  Prev: Mapped Devices,  Up: System Configuration

12.5 Swap Space
===============

Swap space, as it is commonly called, is a disk area specifically
designated for paging: the process in charge of memory management (the
Linux kernel or Hurd’s default pager) can decide that some memory pages
stored in RAM which belong to a running program but are unused should be
stored on disk instead.  It unloads those from the RAM, freeing up
precious fast memory, and writes them to the swap space.  If the program
tries to access that very page, the memory management process loads it
back into memory for the program to use.

   A common misconception about swap is that it is only useful when
small amounts of RAM are available to the system.  However, it should be
noted that kernels often use all available RAM for disk access caching
to make I/O faster, and thus paging out unused portions of program
memory will expand the RAM available for such caching.

   For a more detailed description of how memory is managed from the
viewpoint of a monolithic kernel, *Note (libc)Memory Concepts::.

   The Linux kernel has support for swap partitions and swap files: the
former uses a whole disk partition for paging, whereas the second uses a
file on a file system for that (the file system driver needs to support
it).  On a comparable setup, both have the same performance, so one
should consider ease of use when deciding between them.  Partitions are
“simpler” and do not need file system support, but need to be allocated
at disk formatting time (logical volumes notwithstanding), whereas files
can be allocated and deallocated at any time.

   Note that swap space is not zeroed on shutdown, so sensitive data
(such as passwords) may linger on it if it was paged out.  As such, you
should consider having your swap reside on an encrypted device (*note
Mapped Devices::).

 -- Data Type: swap-space
     Objects of this type represent swap spaces.  They contain the
     following members:

     ‘target’
          The device or file to use, either a UUID, a
          ‘file-system-label’ or a string, as in the definition of a
          ‘file-system’ (*note File Systems::).

     ‘dependencies’ (default: ‘'()’)
          A list of ‘file-system’ or ‘mapped-device’ objects, upon which
          the availability of the space depends.  Note that just like
          for ‘file-system’ objects, dependencies which are needed for
          boot and mounted in early userspace are not managed by the
          Shepherd, and so automatically filtered out for you.

     ‘priority’ (default: ‘#f’)
          Only supported by the Linux kernel.  Either ‘#f’ to disable
          swap priority, or an integer between 0 and 32767.  The kernel
          will first use swap spaces of higher priority when paging, and
          use same priority spaces on a round-robin basis.  The kernel
          will use swap spaces without a set priority after prioritized
          spaces, and in the order that they appeared in (not
          round-robin).

     ‘discard?’ (default: ‘#f’)
          Only supported by the Linux kernel.  When true, the kernel
          will notify the disk controller of discarded pages, for
          example with the TRIM operation on Solid State Drives.

   Here are some examples:

     (swap-space (target (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))

   Use the swap partition with the given UUID.  You can learn the UUID
of a Linux swap partition by running ‘swaplabel DEVICE’, where DEVICE is
the ‘/dev’ file name of that partition.

     (swap-space
       (target (file-system-label "swap"))
       (dependencies mapped-devices))

   Use the partition with label ‘swap’, which can be found after all the
MAPPED-DEVICES mapped devices have been opened.  Again, the ‘swaplabel’
command allows you to view and change the label of a Linux swap
partition.

   Here’s a more involved example with the corresponding ‘file-systems’
part of an ‘operating-system’ declaration.

     (file-systems
       (list (file-system
               (device (file-system-label "root"))
               (mount-point "/")
               (type "ext4"))
             (file-system
               (device (file-system-label "btrfs"))
               (mount-point "/btrfs")
               (type "btrfs"))))

     (swap-devices
       (list
         (swap-space
           (target "/btrfs/swapfile")
           (dependencies (filter (file-system-mount-point-predicate "/btrfs")
                                 file-systems)))))

   Use the file ‘/btrfs/swapfile’ as swap space, which depends on the
file system mounted at ‘/btrfs’.  Note how we use Guile’s filter to
select the file system in an elegant fashion!


File: guix.info,  Node: User Accounts,  Next: Keyboard Layout,  Prev: Swap Space,  Up: System Configuration

12.6 User Accounts
==================

User accounts and groups are entirely managed through the
‘operating-system’ declaration.  They are specified with the
‘user-account’ and ‘user-group’ forms:

     (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"))

   Here’s a user account that uses a different shell and a custom home
directory (the default would be ‘"/home/bob"’):

     (user-account
       (name "bob")
       (group "users")
       (comment "Alice's bro")
       (shell (file-append zsh "/bin/zsh"))
       (home-directory "/home/robert"))

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

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

     ‘name’
          The name of the user account.

     ‘group’
          This is the name (a string) or identifier (a number) of the
          user group this account belongs to.

     ‘supplementary-groups’ (default: ‘'()’)
          Optionally, this can be defined as a list of group names that
          this account belongs to.

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

     ‘comment’ (default: ‘""’)
          A comment about the account, such as the account owner’s full
          name.

          Note that, for non-system accounts, users are free to change
          their real name as it appears in ‘/etc/passwd’ using the
          ‘chfn’ command.  When they do, their choice prevails over the
          system administrator’s choice; reconfiguring does _not_ change
          their name.

     ‘home-directory’
          This is the name of the home directory for the account.

     ‘create-home-directory?’ (default: ‘#t’)
          Indicates whether the home directory of this account should be
          created if it does not exist yet.

     ‘shell’ (default: Bash)
          This is a G-expression denoting the file name of a program to
          be used as the shell (*note G-Expressions::).  For example,
          you would refer to the Bash executable like this:

               (file-append bash "/bin/bash")

          ...  and to the Zsh executable like that:

               (file-append zsh "/bin/zsh")

     ‘system?’ (default: ‘#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.

     ‘password’ (default: ‘#f’)
          You would normally leave this field to ‘#f’, initialize user
          passwords as ‘root’ with the ‘passwd’ command, and then let
          users change it with ‘passwd’.  Passwords set with ‘passwd’
          are of course preserved across reboot and reconfiguration.

          If you _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 ‘crypt’ procedure for this purpose:

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

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

               Note: The hash of this initial password will be available
               in a file in ‘/gnu/store’, readable by all the users, so
               this method must be used with care.

          *Note (libc)Passphrase Storage::, for more information on
          password encryption, and *note (guile)Encryption::, for
          information on Guile’s ‘crypt’ procedure.

   User group declarations are even simpler:

     (user-group (name "students"))

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

     ‘name’
          The name of the group.

     ‘id’ (default: ‘#f’)
          The group identifier (a number).  If ‘#f’, a new number is
          automatically allocated when the group is created.

     ‘system?’ (default: ‘#f’)
          This Boolean value indicates whether the group is a “system”
          group.  System groups have low numerical IDs.

     ‘password’ (default: ‘#f’)
          What, user groups can have a password?  Well, apparently yes.
          Unless ‘#f’, this field specifies the password of the group.

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

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

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


File: guix.info,  Node: Keyboard Layout,  Next: Locales,  Prev: User Accounts,  Up: System Configuration

12.7 Keyboard Layout
====================

To specify what each key of your keyboard does, you need to tell the
operating system what “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.

   There are three components that will want to know about your keyboard
layout:

   • The _bootloader_ may want to know what keyboard layout you want to
     use (*note ‘keyboard-layout’: Bootloader Configuration.).  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.

   • The _operating system kernel_, Linux, will need that so that the
     console is properly configured (*note ‘keyboard-layout’:
     operating-system Reference.).

   • The _graphical display server_, usually Xorg, also has its own idea
     of the keyboard layout (*note ‘keyboard-layout’: X Window.).

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

   Keyboard layouts are represented by records created by the
‘keyboard-layout’ procedure of ‘(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.

 -- Scheme Procedure: keyboard-layout NAME [VARIANT] [#:model]
          [#:options '()]
     Return a new keyboard layout with the given NAME and VARIANT.

     NAME must be a string such as ‘"fr"’; VARIANT must be a string such
     as ‘"bepo"’ or ‘"nodeadkeys"’.  See the ‘xkeyboard-config’ package
     for valid options.

   Here are a few examples:

     ;; 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")

     ;; Arabic layout with "Alt-Shift" to switch to US layout.
     (keyboard-layout "ar,us" #:options '("grp:alt_shift_toggle"))

     ;; 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")

   See the ‘share/X11/xkb’ directory of the ‘xkeyboard-config’ package
for a complete list of supported layouts, variants, and models.

   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:

     ;; 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)
                     (targets '("/boot/efi"))
                     (keyboard-layout keyboard-layout))) ;for GRUB
       (services (cons (set-xorg-configuration
                         (xorg-configuration             ;for Xorg
                           (keyboard-layout keyboard-layout)))
                       %desktop-services)))

   In the example above, for GRUB and for Xorg, we just refer to the
‘keyboard-layout’ field defined above, but we could just as well refer
to a different layout.  The ‘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 _default_ keyboard layout of your
system when it starts, but you can also adjust it at run time:

   • If you’re using GNOME, its settings panel has a “Region & Language”
     entry where you can select one or more keyboard layouts.

   • Under Xorg, the ‘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:

          setxkbmap us dvorak

   • The ‘loadkeys’ command changes the keyboard layout in effect in the
     Linux console.  However, note that ‘loadkeys’ does _not_ use the
     XKB keyboard layout categorization described above.  The command
     below loads the French bépo layout:

          loadkeys fr-bepo


File: guix.info,  Node: Locales,  Next: Services,  Prev: Keyboard Layout,  Up: System Configuration

12.8 Locales
============

A “locale” defines cultural conventions for a particular language and
region of the world (*note (libc)Locales::).  Each locale has a name
that typically has the form ‘LANGUAGE_TERRITORY.CODESET’—e.g.,
‘fr_LU.utf8’ designates the locale for the French language, with
cultural conventions from Luxembourg, and using the UTF-8 encoding.

   Usually, you will want to specify the default locale for the machine
using the ‘locale’ field of the ‘operating-system’ declaration (*note
‘locale’: operating-system Reference.).

   The selected locale is automatically added to the “locale
definitions” known to the system if needed, with its codeset inferred
from its name—e.g., ‘bo_CN.utf8’ will be assumed to use the ‘UTF-8’
codeset.  Additional locale definitions can be specified in the
‘locale-definitions’ slot of ‘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:

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

   Likewise, to save space, one might want ‘locale-definitions’ to list
only the locales that are actually used, as in:

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

   The compiled locale definitions are available at
‘/run/current-system/locale/X.Y’, where ‘X.Y’ is the libc version, which
is the default location where the GNU libc provided by Guix looks for
locale data.  This can be overridden using the ‘LOCPATH’ environment
variable (*note ‘LOCPATH’ and locale packages: locales-and-locpath.).

   The ‘locale-definition’ form is provided by the ‘(gnu system locale)’
module.  Details are given below.

 -- Data Type: locale-definition
     This is the data type of a locale definition.

     ‘name’
          The name of the locale.  *Note (libc)Locale Names::, for more
          information on locale names.

     ‘source’
          The name of the source for that locale.  This is typically the
          ‘LANGUAGE_TERRITORY’ part of the locale name.

     ‘charset’ (default: ‘"UTF-8"’)
          The “character set” or “code set” for that locale, as defined
          by IANA (https://www.iana.org/assignments/character-sets).

 -- Scheme Variable: %default-locale-definitions
     A list of commonly used UTF-8 locales, used as the default value of
     the ‘locale-definitions’ field of ‘operating-system’ declarations.

     These locale definitions use the “normalized codeset” for the part
     that follows the dot in the name (*note normalized codeset:
     (libc)Using gettextized software.).  So for instance it has
     ‘uk_UA.utf8’ but _not_, say, ‘uk_UA.UTF-8’.

12.8.1 Locale Data Compatibility Considerations
-----------------------------------------------

‘operating-system’ declarations provide a ‘locale-libcs’ field to
specify the GNU libc packages that are used to compile locale
declarations (*note 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.

   For instance, a program linked against libc version 2.21 is unable to
read locale data produced with libc 2.22; worse, that program _aborts_
instead of simply ignoring the incompatible locale data(1).  Similarly,
a program linked against libc 2.22 can read most, but not all, of the
locale data from libc 2.21 (specifically, ‘LC_COLLATE’ data is
incompatible); thus calls to ‘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 ‘GUIX_LOCPATH’ accordingly (*note ‘GUIX_LOCPATH’ and
locale packages: locales-and-locpath.).

   Still, it is best if the system-wide locale data at
‘/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 ‘locale-libcs’
field of ‘operating-system’:

     (use-package-modules base)

     (operating-system
       ;; ...
       (locale-libcs (list glibc-2.21 (canonical-package glibc))))

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

   ---------- Footnotes ----------

   (1) Versions 2.23 and later of GNU libc will simply skip the
incompatible locale data, which is already an improvement.


File: guix.info,  Node: Services,  Next: Setuid Programs,  Prev: Locales,  Up: System Configuration

12.9 Services
=============

An important part of preparing an ‘operating-system’ declaration is
listing “system services” and their configuration (*note 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” (*note Service
Composition::), but many services are managed by the GNU Shepherd (*note
Shepherd Services::).  On a running system, the ‘herd’ command allows
you to list the available services, show their status, start and stop
them, or do other specific operations (*note (shepherd)Jump Start::).
For example:

     # herd status

   The above command, run as ‘root’, lists the currently defined
services.  The ‘herd doc’ command shows a synopsis of the given service
and its associated actions:

     # herd doc nscd
     Run libc's name service cache daemon (nscd).

     # herd doc nscd action invalidate
     invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.

   The ‘start’, ‘stop’, and ‘restart’ sub-commands have the effect you
would expect.  For instance, the commands below stop the nscd service
and restart the Xorg display server:

     # herd stop nscd
     Service nscd has been stopped.
     # herd restart xorg-server
     Service xorg-server has been stopped.
     Service xorg-server has been started.

   For some services, ‘herd configuration’ returns the name of the
service’s configuration file, which can be handy to inspect its
configuration:

     # herd configuration sshd
     /gnu/store/...-sshd_config

   The following sections document the available services, starting with
the core services, that may be used in an ‘operating-system’
declaration.

* Menu:

* Base Services::               Essential system services.
* Scheduled Job Execution::     The mcron service.
* Log Rotation::                The rottlog service.
* Networking Setup::            Setting up network interfaces.
* Networking Services::         Firewall, SSH daemon, etc.
* Unattended Upgrades::         Automated system upgrades.
* X Window::                    Graphical display.
* Printing Services::           Local and remote printer support.
* Desktop Services::            D-Bus and desktop services.
* Sound Services::              ALSA and Pulseaudio services.
* Database Services::           SQL databases, key-value stores, etc.
* Mail Services::               IMAP, POP3, SMTP, and all that.
* Messaging Services::          Messaging services.
* Telephony Services::          Telephony services.
* File-Sharing Services::       File-sharing services.
* Monitoring Services::         Monitoring services.
* Kerberos Services::           Kerberos services.
* LDAP Services::               LDAP services.
* Web Services::                Web servers.
* Certificate Services::        TLS certificates via Let’s Encrypt.
* DNS Services::                DNS daemons.
* VNC Services::                VNC daemons.
* VPN Services::                VPN daemons.
* Network File System::         NFS related services.
* Samba Services::              Samba services.
* Continuous Integration::      Cuirass and Laminar services.
* Power Management Services::   Extending battery life.
* Audio Services::              The MPD.
* Virtualization Services::     Virtualization services.
* Version Control Services::    Providing remote access to Git repositories.
* Game Services::               Game servers.
* PAM Mount Service::           Service to mount volumes when logging in.
* Guix Services::               Services relating specifically to Guix.
* Linux Services::              Services tied to the Linux kernel.
* Hurd Services::               Services specific for a Hurd System.
* Miscellaneous Services::      Other services.


File: guix.info,  Node: Base Services,  Next: Scheduled Job Execution,  Up: Services

12.9.1 Base Services
--------------------

The ‘(gnu services base)’ module provides definitions for the basic
services that one expects from the system.  The services exported by
this module are listed below.

 -- Scheme Variable: %base-services
     This variable contains a list of basic services (*note Service
     Types and Services::, for more information on service objects) one
     would expect from the system: a login service (mingetty) on each
     tty, syslogd, the libc name service cache daemon (nscd), the udev
     device manager, and more.

     This is the default value of the ‘services’ field of
     ‘operating-system’ declarations.  Usually, when customizing a
     system, you will want to append services to ‘%base-services’, like
     this:

          (append (list (service avahi-service-type)
                        (service openssh-service-type))
                  %base-services)

 -- Scheme Variable: special-files-service-type
     This is the service that sets up “special files” such as ‘/bin/sh’;
     an instance of it is part of ‘%base-services’.

     The value associated with ‘special-files-service-type’ services
     must be a list of tuples where the first element is the “special
     file” and the second element is its target.  By default it is:

          `(("/bin/sh" ,(file-append bash "/bin/sh"))
            ("/usr/bin/env" ,(file-append coreutils "/bin/env")))

     If you want to add, say, ‘/bin/bash’ to your system, you can change
     it to:

          `(("/bin/sh" ,(file-append bash "/bin/sh"))
            ("/usr/bin/env" ,(file-append coreutils "/bin/env"))
            ("/bin/bash" ,(file-append bash "/bin/bash")))

     Since this is part of ‘%base-services’, you can use
     ‘modify-services’ to customize the set of special files (*note
     ‘modify-services’: Service Reference.).  But the simple way to add
     a special file is via the ‘extra-special-file’ procedure (see
     below).

 -- Scheme Procedure: extra-special-file FILE TARGET
     Use TARGET as the “special file” FILE.

     For example, adding the following lines to the ‘services’ field of
     your operating system declaration leads to a ‘/usr/bin/env’
     symlink:

          (extra-special-file "/usr/bin/env"
                              (file-append coreutils "/bin/env"))

 -- Scheme Procedure: host-name-service NAME
     Return a service that sets the host name to NAME.

 -- Scheme Variable: console-font-service-type
     Install the given fonts on the specified ttys (fonts are per
     virtual console on the kernel Linux).  The value of this service is
     a list of tty/font pairs.  The font can be the name of a font
     provided by the ‘kbd’ package or any valid argument to ‘setfont’,
     as in this example:

          `(("tty1" . "LatGrkCyr-8x16")
            ("tty2" . ,(file-append
                          font-tamzen
                          "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
            ("tty3" . ,(file-append
                          font-terminus
                          "/share/consolefonts/ter-132n"))) ; for HDPI

 -- Scheme Procedure: login-service CONFIG
     Return a service to run login according to CONFIG, a
     ‘<login-configuration>’ object, which specifies the message of the
     day, among other things.

 -- Data Type: login-configuration
     This is the data type representing the configuration of login.

     ‘motd’
          A file-like object containing the “message of the day”.

     ‘allow-empty-passwords?’ (default: ‘#t’)
          Allow empty passwords by default so that first-time users can
          log in when the ’root’ account has just been created.

 -- Scheme Procedure: mingetty-service CONFIG
     Return a service to run mingetty according to CONFIG, a
     ‘<mingetty-configuration>’ object, which specifies the tty to run,
     among other things.

 -- Data Type: mingetty-configuration
     This is the data type representing the configuration of Mingetty,
     which provides the default implementation of virtual console
     log-in.

     ‘tty’
          The name of the console this Mingetty runs on—e.g., ‘"tty1"’.

     ‘auto-login’ (default: ‘#f’)
          When true, this field must be a string denoting the user name
          under which the system automatically logs in.  When it is
          ‘#f’, a user name and password must be entered to log in.

     ‘login-program’ (default: ‘#f’)
          This must be either ‘#f’, in which case the default log-in
          program is used (‘login’ from the Shadow tool suite), or a
          gexp denoting the name of the log-in program.

     ‘login-pause?’ (default: ‘#f’)
          When set to ‘#t’ in conjunction with AUTO-LOGIN, the user will
          have to press a key before the log-in shell is launched.

     ‘clear-on-logout?’ (default: ‘#t’)
          When set to ‘#t’, the screen will be cleared after logout.

     ‘mingetty’ (default: MINGETTY)
          The Mingetty package to use.

 -- Scheme Procedure: agetty-service CONFIG
     Return a service to run agetty according to CONFIG, an
     ‘<agetty-configuration>’ object, which specifies the tty to run,
     among other things.

 -- Data Type: agetty-configuration
     This is the data type representing the configuration of agetty,
     which implements virtual and serial console log-in.  See the
     ‘agetty(8)’ man page for more information.

     ‘tty’
          The name of the console this agetty runs on, as a string—e.g.,
          ‘"ttyS0"’.  This argument is optional, it will default to a
          reasonable default serial port used by the kernel Linux.

          For this, if there is a value for an option ‘agetty.tty’ in
          the kernel command line, agetty will extract the device name
          of the serial port from it and use that.

          If not and if there is a value for an option ‘console’ with a
          tty in the Linux command line, agetty will extract the device
          name of the serial port from it and use that.

          In both cases, agetty will leave the other serial device
          settings (baud rate etc.) alone—in the hope that Linux pinned
          them to the correct values.

     ‘baud-rate’ (default: ‘#f’)
          A string containing a comma-separated list of one or more baud
          rates, in descending order.

     ‘term’ (default: ‘#f’)
          A string containing the value used for the ‘TERM’ environment
          variable.

     ‘eight-bits?’ (default: ‘#f’)
          When ‘#t’, the tty is assumed to be 8-bit clean, and parity
          detection is disabled.

     ‘auto-login’ (default: ‘#f’)
          When passed a login name, as a string, the specified user will
          be logged in automatically without prompting for their login
          name or password.

     ‘no-reset?’ (default: ‘#f’)
          When ‘#t’, don’t reset terminal cflags (control modes).

     ‘host’ (default: ‘#f’)
          This accepts a string containing the “login_host”, which will
          be written into the ‘/var/run/utmpx’ file.

     ‘remote?’ (default: ‘#f’)
          When set to ‘#t’ in conjunction with HOST, this will add an
          ‘-r’ fakehost option to the command line of the login program
          specified in LOGIN-PROGRAM.

     ‘flow-control?’ (default: ‘#f’)
          When set to ‘#t’, enable hardware (RTS/CTS) flow control.

     ‘no-issue?’ (default: ‘#f’)
          When set to ‘#t’, the contents of the ‘/etc/issue’ file will
          not be displayed before presenting the login prompt.

     ‘init-string’ (default: ‘#f’)
          This accepts a string that will be sent to the tty or modem
          before sending anything else.  It can be used to initialize a
          modem.

     ‘no-clear?’ (default: ‘#f’)
          When set to ‘#t’, agetty will not clear the screen before
          showing the login prompt.

     ‘login-program’ (default: (file-append shadow "/bin/login"))
          This must be either a gexp denoting the name of a log-in
          program, or unset, in which case the default value is the
          ‘login’ from the Shadow tool suite.

     ‘local-line’ (default: ‘#f’)
          Control the CLOCAL line flag.  This accepts one of three
          symbols as arguments, ‘'auto’, ‘'always’, or ‘'never’.  If
          ‘#f’, the default value chosen by agetty is ‘'auto’.

     ‘extract-baud?’ (default: ‘#f’)
          When set to ‘#t’, instruct agetty to try to extract the baud
          rate from the status messages produced by certain types of
          modems.

     ‘skip-login?’ (default: ‘#f’)
          When set to ‘#t’, do not prompt the user for a login name.
          This can be used with LOGIN-PROGRAM field to use non-standard
          login systems.

     ‘no-newline?’ (default: ‘#f’)
          When set to ‘#t’, do not print a newline before printing the
          ‘/etc/issue’ file.

     ‘login-options’ (default: ‘#f’)
          This option accepts a string containing options that are
          passed to the login program.  When used with the
          LOGIN-PROGRAM, be aware that a malicious user could try to
          enter a login name containing embedded options that could be
          parsed by the login program.

     ‘login-pause’ (default: ‘#f’)
          When set to ‘#t’, wait for any key before showing the login
          prompt.  This can be used in conjunction with AUTO-LOGIN to
          save memory by lazily spawning shells.

     ‘chroot’ (default: ‘#f’)
          Change root to the specified directory.  This option accepts a
          directory path as a string.

     ‘hangup?’ (default: ‘#f’)
          Use the Linux system call ‘vhangup’ to do a virtual hangup of
          the specified terminal.

     ‘keep-baud?’ (default: ‘#f’)
          When set to ‘#t’, try to keep the existing baud rate.  The
          baud rates from BAUD-RATE are used when agetty receives a
          <BREAK> character.

     ‘timeout’ (default: ‘#f’)
          When set to an integer value, terminate if no user name could
          be read within TIMEOUT seconds.

     ‘detect-case?’ (default: ‘#f’)
          When set to ‘#t’, turn on support for detecting an
          uppercase-only terminal.  This setting will detect a login
          name containing only uppercase letters as indicating an
          uppercase-only terminal and turn on some upper-to-lower case
          conversions.  Note that this will not support Unicode
          characters.

     ‘wait-cr?’ (default: ‘#f’)
          When set to ‘#t’, wait for the user or modem to send a
          carriage-return or linefeed character before displaying
          ‘/etc/issue’ or login prompt.  This is typically used with the
          INIT-STRING option.

     ‘no-hints?’ (default: ‘#f’)
          When set to ‘#t’, do not print hints about Num, Caps, and
          Scroll locks.

     ‘no-hostname?’ (default: ‘#f’)
          By default, the hostname is printed.  When this option is set
          to ‘#t’, no hostname will be shown at all.

     ‘long-hostname?’ (default: ‘#f’)
          By default, the hostname is only printed until the first dot.
          When this option is set to ‘#t’, the fully qualified hostname
          by ‘gethostname’ or ‘getaddrinfo’ is shown.

     ‘erase-characters’ (default: ‘#f’)
          This option accepts a string of additional characters that
          should be interpreted as backspace when the user types their
          login name.

     ‘kill-characters’ (default: ‘#f’)
          This option accepts a string that should be interpreted to
          mean “ignore all previous characters” (also called a “kill”
          character) when the user types their login name.

     ‘chdir’ (default: ‘#f’)
          This option accepts, as a string, a directory path that will
          be changed to before login.

     ‘delay’ (default: ‘#f’)
          This options accepts, as an integer, the number of seconds to
          sleep before opening the tty and displaying the login prompt.

     ‘nice’ (default: ‘#f’)
          This option accepts, as an integer, the nice value with which
          to run the ‘login’ program.

     ‘extra-options’ (default: ‘'()’)
          This option provides an “escape hatch” for the user to provide
          arbitrary command-line arguments to ‘agetty’ as a list of
          strings.

     ‘shepherd-requirement’ (default: ‘'()’)
          The option can be used to provides extra shepherd requirements
          (for example ‘'syslogd’) to the respective ‘'term-’* shepherd
          service.

 -- Scheme Procedure: kmscon-service-type CONFIG
     Return a service to run kmscon
     (https://www.freedesktop.org/wiki/Software/kmscon) according to
     CONFIG, a ‘<kmscon-configuration>’ object, which specifies the tty
     to run, among other things.

 -- Data Type: kmscon-configuration
     This is the data type representing the configuration of Kmscon,
     which implements virtual console log-in.

     ‘virtual-terminal’
          The name of the console this Kmscon runs on—e.g., ‘"tty1"’.

     ‘login-program’ (default: ‘#~(string-append #$shadow "/bin/login")’)
          A gexp denoting the name of the log-in program.  The default
          log-in program is ‘login’ from the Shadow tool suite.

     ‘login-arguments’ (default: ‘'("-p")’)
          A list of arguments to pass to ‘login’.

     ‘auto-login’ (default: ‘#f’)
          When passed a login name, as a string, the specified user will
          be logged in automatically without prompting for their login
          name or password.

     ‘hardware-acceleration?’ (default: #f)
          Whether to use hardware acceleration.

     ‘font-engine’ (default: ‘"pango"’)
          Font engine used in Kmscon.

     ‘font-size’ (default: ‘12’)
          Font size used in Kmscon.

     ‘keyboard-layout’ (default: ‘#f’)
          If this is ‘#f’, Kmscon uses the default keyboard
          layout—usually US English (“qwerty”) for a 105-key PC
          keyboard.

          Otherwise this must be a ‘keyboard-layout’ object specifying
          the keyboard layout.  *Note Keyboard Layout::, for more
          information on how to specify the keyboard layout.

     ‘kmscon’ (default: KMSCON)
          The Kmscon package to use.

 -- Scheme Procedure: nscd-service [CONFIG] [#:glibc glibc]
          [#:name-services '()]
     Return a service that runs the libc name service cache daemon
     (nscd) with the given CONFIG—an ‘<nscd-configuration>’ object.
     *Note Name Service Switch::, for an example.

     For convenience, the Shepherd service for nscd provides the
     following actions:

     ‘invalidate’
          This invalidate the given cache.  For instance, running:

               herd invalidate nscd hosts

          invalidates the host name lookup cache of nscd.

     ‘statistics’
          Running ‘herd statistics nscd’ displays information about nscd
          usage and caches.

 -- Scheme Variable: %nscd-default-configuration
     This is the default ‘<nscd-configuration>’ value (see below) used
     by ‘nscd-service’.  It uses the caches defined by
     ‘%nscd-default-caches’; see below.

 -- Data Type: nscd-configuration
     This is the data type representing the name service cache daemon
     (nscd) configuration.

     ‘name-services’ (default: ‘'()’)
          List of packages denoting “name services” that must be visible
          to the nscd—e.g., ‘(list NSS-MDNS)’.

     ‘glibc’ (default: GLIBC)
          Package object denoting the GNU C Library providing the ‘nscd’
          command.

     ‘log-file’ (default: ‘"/var/log/nscd.log"’)
          Name of the nscd log file.  This is where debugging output
          goes when ‘debug-level’ is strictly positive.

     ‘debug-level’ (default: ‘0’)
          Integer denoting the debugging levels.  Higher numbers mean
          that more debugging output is logged.

     ‘caches’ (default: ‘%nscd-default-caches’)
          List of ‘<nscd-cache>’ objects denoting things to be cached;
          see below.

 -- Data Type: nscd-cache
     Data type representing a cache database of nscd and its parameters.

     ‘database’
          This is a symbol representing the name of the database to be
          cached.  Valid values are ‘passwd’, ‘group’, ‘hosts’, and
          ‘services’, which designate the corresponding NSS database
          (*note (libc)NSS Basics::).

     ‘positive-time-to-live’
     ‘negative-time-to-live’ (default: ‘20’)
          A number representing the number of seconds during which a
          positive or negative lookup result remains in cache.

     ‘check-files?’ (default: ‘#t’)
          Whether to check for updates of the files corresponding to
          DATABASE.

          For instance, when DATABASE is ‘hosts’, setting this flag
          instructs nscd to check for updates in ‘/etc/hosts’ and to
          take them into account.

     ‘persistent?’ (default: ‘#t’)
          Whether the cache should be stored persistently on disk.

     ‘shared?’ (default: ‘#t’)
          Whether the cache should be shared among users.

     ‘max-database-size’ (default: 32 MiB)
          Maximum size in bytes of the database cache.

 -- Scheme Variable: %nscd-default-caches
     List of ‘<nscd-cache>’ objects used by default by
     ‘nscd-configuration’ (see above).

     It enables persistent and aggressive caching of service and host
     name lookups.  The latter provides better host name lookup
     performance, resilience in the face of unreliable name servers, and
     also better privacy—often the result of host name lookups is in
     local cache, so external name servers do not even need to be
     queried.

 -- Data Type: syslog-configuration
     This data type represents the configuration of the syslog daemon.

     ‘syslogd’ (default: ‘#~(string-append #$inetutils "/libexec/syslogd")’)
          The syslog daemon to use.

     ‘config-file’ (default: ‘%default-syslog.conf’)
          The syslog configuration file to use.

 -- Scheme Procedure: syslog-service CONFIG
     Return a service that runs a syslog daemon according to CONFIG.

     *Note (inetutils)syslogd invocation::, for more information on the
     configuration file syntax.

 -- Scheme Variable: guix-service-type
     This is the type of the service that runs the build daemon,
     ‘guix-daemon’ (*note Invoking guix-daemon::).  Its value must be a
     ‘guix-configuration’ record as described below.

 -- Data Type: guix-configuration
     This data type represents the configuration of the Guix build
     daemon.  *Note Invoking guix-daemon::, for more information.

     ‘guix’ (default: GUIX)
          The Guix package to use.

     ‘build-group’ (default: ‘"guixbuild"’)
          Name of the group for build user accounts.

     ‘build-accounts’ (default: ‘10’)
          Number of build user accounts to create.

     ‘authorize-key?’ (default: ‘#t’)
          Whether to authorize the substitute keys listed in
          ‘authorized-keys’—by default that of ‘ci.guix.gnu.org’ and
          ‘bordeaux.guix.gnu.org’ (*note Substitutes::).

          When ‘authorize-key?’ is true, ‘/etc/guix/acl’ cannot be
          changed by invoking ‘guix archive --authorize’.  You must
          instead adjust ‘guix-configuration’ as you wish and
          reconfigure the system.  This ensures that your operating
          system configuration file is self-contained.

               Note: When booting or reconfiguring to a system where
               ‘authorize-key?’ is true, the existing ‘/etc/guix/acl’
               file is backed up as ‘/etc/guix/acl.bak’ if it was
               determined to be a manually modified file.  This is to
               facilitate migration from earlier versions, which allowed
               for in-place modifications to ‘/etc/guix/acl’.

     ‘authorized-keys’ (default: ‘%default-authorized-guix-keys’)
          The list of authorized key files for archive imports, as a
          list of string-valued gexps (*note Invoking guix archive::).
          By default, it contains that of ‘ci.guix.gnu.org’ and
          ‘bordeaux.guix.gnu.org’ (*note Substitutes::).  See
          ‘substitute-urls’ below for an example on how to change it.

     ‘use-substitutes?’ (default: ‘#t’)
          Whether to use substitutes.

     ‘substitute-urls’ (default: ‘%default-substitute-urls’)
          The list of URLs where to look for substitutes by default.

          Suppose you would like to fetch substitutes from
          ‘guix.example.org’ in addition to ‘ci.guix.gnu.org’.  You will
          need to do two things: (1) add ‘guix.example.org’ to
          ‘substitute-urls’, and (2) authorize its signing key, having
          done appropriate checks (*note Substitute Server
          Authorization::).  The configuration below does exactly that:

               (guix-configuration
                 (substitute-urls
                  (append (list "https://guix.example.org")
                          %default-substitute-urls))
                 (authorized-keys
                  (append (list (local-file "./guix.example.org-key.pub"))
                          %default-authorized-guix-keys)))

          This example assumes that the file
          ‘./guix.example.org-key.pub’ contains the public key that
          ‘guix.example.org’ uses to sign substitutes.

     ‘generate-substitute-key?’ (default: ‘#t’)
          Whether to generate a “substitute key pair” under
          ‘/etc/guix/signing-key.pub’ and ‘/etc/guix/signing-key.sec’ if
          there is not already one.

          This key pair is used when exporting store items, for instance
          with ‘guix publish’ (*note Invoking guix publish::) or ‘guix
          archive’ (*note Invoking guix archive::).  Generating a key
          pair takes a few seconds when enough entropy is available and
          is only done once; you might want to turn it off for instance
          in a virtual machine that does not need it and where the extra
          boot time is a problem.

     ‘max-silent-time’ (default: ‘0’)
     ‘timeout’ (default: ‘0’)
          The number of seconds of silence and the number of seconds of
          activity, respectively, after which a build process times out.
          A value of zero disables the timeout.

     ‘log-compression’ (default: ‘'gzip’)
          The type of compression used for build logs—one of ‘gzip’,
          ‘bzip2’, or ‘none’.

     ‘discover?’ (default: ‘#f’)
          Whether to discover substitute servers on the local network
          using mDNS and DNS-SD.

     ‘extra-options’ (default: ‘'()’)
          List of extra command-line options for ‘guix-daemon’.

     ‘log-file’ (default: ‘"/var/log/guix-daemon.log"’)
          File where ‘guix-daemon’’s standard output and standard error
          are written.

     ‘http-proxy’ (default: ‘#f’)
          The URL of the HTTP and HTTPS proxy used for downloading
          fixed-output derivations and substitutes.

          It is also possible to change the daemon’s proxy at run time
          through the ‘set-http-proxy’ action, which restarts it:

               herd set-http-proxy guix-daemon http://localhost:8118

          To clear the proxy settings, run:

               herd set-http-proxy guix-daemon

     ‘tmpdir’ (default: ‘#f’)
          A directory path where the ‘guix-daemon’ will perform builds.

 -- Data Type: guix-extension

     This data type represents the parameters of the Guix build daemon
     that are extendable.  This is the type of the object that must be
     used within a guix service extension.  *Note Service Composition::,
     for more information.

     ‘authorized-keys’ (default: ‘'()’)
          A list of file-like objects where each element contains a
          public key.

     ‘substitute-urls’ (default: ‘'()’)
          A list of strings where each element is a substitute URL.

     ‘chroot-directories’ (default: ‘'()’)
          A list of file-like objects or strings pointing to additional
          directories the build daemon can use.

 -- Scheme Procedure: udev-service [#:udev EUDEV #:rules ‘'()’]
     Run UDEV, which populates the ‘/dev’ directory dynamically.  udev
     rules can be provided as a list of files through the RULES
     variable.  The procedures ‘udev-rule’, ‘udev-rules-service’ and
     ‘file->udev-rule’ from ‘(gnu services base)’ simplify the creation
     of such rule files.

     The ‘herd rules udev’ command, as root, returns the name of the
     directory containing all the active udev rules.

 -- Scheme Procedure: udev-rule [FILE-NAME CONTENTS]
     Return a udev-rule file named FILE-NAME containing the rules
     defined by the CONTENTS literal.

     In the following example, a rule for a USB device is defined to be
     stored in the file ‘90-usb-thing.rules’.  The rule runs a script
     upon detecting a USB device with a given product identifier.

          (define %example-udev-rule
            (udev-rule
              "90-usb-thing.rules"
              (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
                             "ATTR{product}==\"Example\", "
                             "RUN+=\"/path/to/script\"")))

 -- Scheme Procedure: udev-rules-service [NAME RULES] [#:groups GROUPS]
     Return a service that extends ‘udev-service-type ’ with RULES and
     ‘account-service-type’ with GROUPS as system groups.  This works by
     creating a singleton service type ‘NAME-udev-rules’, of which the
     returned service is an instance.

     Here we show how it can be used to extend ‘udev-service-type’ with
     the previously defined rule ‘%example-udev-rule’.

          (operating-system
           ;; ...
           (services
             (cons (udev-rules-service 'usb-thing %example-udev-rule)
                   %desktop-services)))

 -- Scheme Procedure: file->udev-rule [FILE-NAME FILE]
     Return a udev file named FILE-NAME containing the rules defined
     within FILE, a file-like object.

     The following example showcases how we can use an existing rule
     file.

          (use-modules (guix download)     ;for url-fetch
                       (guix packages)     ;for origin
                       ...)

          (define %android-udev-rules
            (file->udev-rule
              "51-android-udev.rules"
              (let ((version "20170910"))
                (origin
                 (method url-fetch)
                 (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
                                     "android-udev-rules/" version "/51-android.rules"))
                 (sha256
                  (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))

   Additionally, Guix package definitions can be included in RULES in
order to extend the udev rules with the definitions found under their
‘lib/udev/rules.d’ sub-directory.  In lieu of the previous
FILE->UDEV-RULE example, we could have used the ANDROID-UDEV-RULES
package which exists in Guix in the ‘(gnu packages android)’ module.

   The following example shows how to use the ANDROID-UDEV-RULES package
so that the Android tool ‘adb’ can detect devices without root
privileges.  It also details how to create the ‘adbusers’ group, which
is required for the proper functioning of the rules defined within the
‘android-udev-rules’ package.  To create such a group, we must define it
both as part of the ‘supplementary-groups’ of our ‘user-account’
declaration, as well as in the GROUPS of the ‘udev-rules-service’
procedure.

     (use-modules (gnu packages android)  ;for android-udev-rules
                  (gnu system shadow)     ;for user-group
                  ...)

     (operating-system
       ;; ...
       (users (cons (user-account
                     ;; ...
                     (supplementary-groups
                      '("adbusers"   ;for adb
                        "wheel" "netdev" "audio" "video")))))
       ;; ...
       (services
         (cons (udev-rules-service 'android android-udev-rules
                                   #:groups '("adbusers"))
               %desktop-services)))

 -- Scheme Variable: urandom-seed-service-type
     Save some entropy in ‘%random-seed-file’ to seed ‘/dev/urandom’
     when rebooting.  It also tries to seed ‘/dev/urandom’ from
     ‘/dev/hwrng’ while booting, if ‘/dev/hwrng’ exists and is readable.

 -- Scheme Variable: %random-seed-file
     This is the name of the file where some random bytes are saved by
     URANDOM-SEED-SERVICE to seed ‘/dev/urandom’ when rebooting.  It
     defaults to ‘/var/lib/random-seed’.

 -- Scheme Variable: gpm-service-type
     This is the type of the service that runs GPM, the “general-purpose
     mouse daemon”, which provides mouse support to the Linux console.
     GPM allows users to use the mouse in the console, notably to
     select, copy, and paste text.

     The value for services of this type must be a ‘gpm-configuration’
     (see below).  This service is not part of ‘%base-services’.

 -- Data Type: gpm-configuration
     Data type representing the configuration of GPM.

     ‘options’ (default: ‘%default-gpm-options’)
          Command-line options passed to ‘gpm’.  The default set of
          options instruct ‘gpm’ to listen to mouse events on
          ‘/dev/input/mice’.  *Note (gpm)Command Line::, for more
          information.

     ‘gpm’ (default: ‘gpm’)
          The GPM package to use.

 -- Scheme Variable: guix-publish-service-type
     This is the service type for ‘guix publish’ (*note Invoking guix
     publish::).  Its value must be a ‘guix-publish-configuration’
     object, as described below.

     This assumes that ‘/etc/guix’ already contains a signing key pair
     as created by ‘guix archive --generate-key’ (*note Invoking guix
     archive::).  If that is not the case, the service will fail to
     start.

 -- Data Type: guix-publish-configuration
     Data type representing the configuration of the ‘guix publish’
     service.

     ‘guix’ (default: ‘guix’)
          The Guix package to use.

     ‘port’ (default: ‘80’)
          The TCP port to listen for connections.

     ‘host’ (default: ‘"localhost"’)
          The host (and thus, network interface) to listen to.  Use
          ‘"0.0.0.0"’ to listen on all the network interfaces.

     ‘advertise?’ (default: ‘#f’)
          When true, advertise the service on the local network via the
          DNS-SD protocol, using Avahi.

          This allows neighboring Guix devices with discovery on (see
          ‘guix-configuration’ above) to discover this ‘guix publish’
          instance and to automatically download substitutes from it.

     ‘compression’ (default: ‘'(("gzip" 3) ("zstd" 3))’)
          This is a list of compression method/level tuple used when
          compressing substitutes.  For example, to compress all
          substitutes with _both_ lzip at level 7 and gzip at level 9,
          write:

               '(("lzip" 7) ("gzip" 9))

          Level 9 achieves the best compression ratio at the expense of
          increased CPU usage, whereas level 1 achieves fast
          compression.  *Note Invoking guix publish::, for more
          information on the available compression methods and the
          tradeoffs involved.

          An empty list disables compression altogether.

     ‘nar-path’ (default: ‘"nar"’)
          The URL path at which “nars” can be fetched.  *Note
          ‘--nar-path’: Invoking guix publish, for details.

     ‘cache’ (default: ‘#f’)
          When it is ‘#f’, disable caching and instead generate archives
          on demand.  Otherwise, this should be the name of a
          directory—e.g., ‘"/var/cache/guix/publish"’—where ‘guix
          publish’ caches archives and meta-data ready to be sent.
          *Note ‘--cache’: Invoking guix publish, for more information
          on the tradeoffs involved.

     ‘workers’ (default: ‘#f’)
          When it is an integer, this is the number of worker threads
          used for caching; when ‘#f’, the number of processors is used.
          *Note ‘--workers’: Invoking guix publish, for more
          information.

     ‘cache-bypass-threshold’ (default: 10 MiB)
          When ‘cache’ is true, this is the maximum size in bytes of a
          store item for which ‘guix publish’ may bypass its cache in
          case of a cache miss.  *Note ‘--cache-bypass-threshold’:
          Invoking guix publish, for more information.

     ‘ttl’ (default: ‘#f’)
          When it is an integer, this denotes the “time-to-live” in
          seconds of the published archives.  *Note ‘--ttl’: Invoking
          guix publish, for more information.

     ‘negative-ttl’ (default: ‘#f’)
          When it is an integer, this denotes the “time-to-live” in
          seconds for the negative lookups.  *Note ‘--negative-ttl’:
          Invoking guix publish, for more information.

 -- Scheme Procedure: rngd-service [#:rng-tools RNG-TOOLS] [#:device
          "/dev/hwrng"]
     Return a service that runs the ‘rngd’ program from RNG-TOOLS to add
     DEVICE to the kernel’s entropy pool.  The service will fail if
     DEVICE does not exist.

 -- Scheme Procedure: pam-limits-service [#:limits ‘'()’]

     Return a service that installs a configuration file for the
     ‘pam_limits’ module
     (http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html).  The
     procedure optionally takes a list of ‘pam-limits-entry’ values,
     which can be used to specify ‘ulimit’ limits and ‘nice’ priority
     limits to user sessions.

     The following limits definition sets two hard and soft limits for
     all login sessions of users in the ‘realtime’ group:

          (pam-limits-service
           (list
            (pam-limits-entry "@realtime" 'both 'rtprio 99)
            (pam-limits-entry "@realtime" 'both 'memlock 'unlimited)))

     The first entry increases the maximum realtime priority for
     non-privileged processes; the second entry lifts any restriction of
     the maximum address space that can be locked in memory.  These
     settings are commonly used for real-time audio systems.

     Another useful example is raising the maximum number of open file
     descriptors that can be used:

          (pam-limits-service
           (list
            (pam-limits-entry "*" 'both 'nofile 100000)))

     In the above example, the asterisk means the limit should apply to
     any user.  It is important to ensure the chosen value doesn’t
     exceed the maximum system value visible in the
     ‘/proc/sys/fs/file-max’ file, else the users would be prevented
     from login in.  For more information about the Pluggable
     Authentication Module (PAM) limits, refer to the ‘pam_limits’ man
     page from the ‘linux-pam’ package.

 -- Scheme Variable: greetd-service-type
     ‘greetd’ (https://git.sr.ht/~kennylevinsen/greetd) is a minimal and
     flexible login manager daemon, that makes no assumptions about what
     you want to launch.

     If you can run it from your shell in a TTY, greetd can start it.
     If it can be taught to speak a simple JSON-based IPC protocol, then
     it can be a geeter.

     ‘greetd-service-type’ provides necessary infrastructure for logging
     in users, including:

        • ‘greetd’ PAM service

        • Special variation of ‘pam-mount’ to mount ‘XDG_RUNTIME_DIR’

     Here is example of switching from ‘mingetty-service-type’ to
     ‘greetd-service-type’, and how different terminals could be:

            (append
             (modify-services %base-services
               ;; greetd-service-type provides "greetd" PAM service
               (delete login-service-type)
               ;; and can be used in place of mingetty-service-type
               (delete mingetty-service-type))
             (list
              (service greetd-service-type
                       (greetd-configuration
                        (terminals
                         (list
                          ;; we can make any terminal active by default
                          (greetd-terminal-configuration (terminal-vt "1") (terminal-switch #t))
                          ;; we can make environment without XDG_RUNTIME_DIR set
                          ;; even provide our own environment variables
                          (greetd-terminal-configuration
                           (terminal-vt "2")
                           (default-session-command
                             (greetd-agreety-session
                              (extra-env '(("MY_VAR" . "1")))
                              (xdg-env? #f))))
                          ;; we can use different shell instead of default bash
                          (greetd-terminal-configuration
                           (terminal-vt "3")
                           (default-session-command
                             (greetd-agreety-session (command (file-append zsh "/bin/zsh")))))
                          ;; we can use any other executable command as greeter
                          (greetd-terminal-configuration
                           (terminal-vt "4")
                           (default-session-command (program-file "my-noop-greeter" #~(exit))))
                          (greetd-terminal-configuration (terminal-vt "5"))
                          (greetd-terminal-configuration (terminal-vt "6"))))))
              ;; mingetty-service-type can be used in parallel
              ;; if needed to do so, do not (delete login-service-type)
              ;; as illustrated above
              #| (service mingetty-service-type (mingetty-configuration (tty "tty8"))) |#))

 -- Data Type: greetd-configuration
     Configuration record for the ‘greetd-service-type’.

     ‘motd’
          A file-like object containing the “message of the day”.

     ‘allow-empty-passwords?’ (default: ‘#t’)
          Allow empty passwords by default so that first-time users can
          log in when the ’root’ account has just been created.

     ‘terminals’ (default: ‘'()’)
          List of ‘greetd-terminal-configuration’ per terminal for which
          ‘greetd’ should be started.

     ‘greeter-supplementary-groups’ (default: ‘'()’)
          List of groups which should be added to ‘greeter’ user.  For
          instance:
               (greeter-supplementary-groups '("seat" "video"))
          Note that this example will fail if ‘seat’ group does not
          exist.

 -- Data Type: greetd-terminal-configuration
     Configuration record for per terminal greetd daemon service.

     ‘greetd’ (default: ‘greetd’)
          The greetd package to use.

     ‘config-file-name’
          Configuration file name to use for greetd daemon.  Generally,
          autogenerated derivation based on ‘terminal-vt’ value.

     ‘log-file-name’
          Log file name to use for greetd daemon.  Generally,
          autogenerated name based on ‘terminal-vt’ value.

     ‘terminal-vt’ (default: ‘"7"’)
          The VT to run on.  Use of a specific VT with appropriate
          conflict avoidance is recommended.

     ‘terminal-switch’ (default: ‘#f’)
          Make this terminal active on start of ‘greetd’.

     ‘default-session-user’ (default: ‘"greeter"’)
          The user to use for running the greeter.

     ‘default-session-command’ (default: ‘(greetd-agreety-session)’)
          Can be either instance of ‘greetd-agreety-session’
          configuration or ‘gexp->script’ like object to use as greeter.

 -- Data Type: greetd-agreety-session
     Configuration record for the agreety greetd greeter.

     ‘agreety’ (default: ‘greetd’)
          The package with ‘/bin/agreety’ command.

     ‘command’ (default: ‘(file-append bash "/bin/bash")’)
          Command to be started by ‘/bin/agreety’ on successful login.

     ‘command-args’ (default: ‘'("-l")’)
          Command arguments to pass to command.

     ‘extra-env’ (default: ‘'()’)
          Extra environment variables to set on login.

     ‘xdg-env?’ (default: ‘#t’)
          If true ‘XDG_RUNTIME_DIR’ and ‘XDG_SESSION_TYPE’ will be set
          before starting command.  One should note that, ‘extra-env’
          variables are set right after mentioned variables, so that
          they can be overriden.

 -- Data Type: greetd-wlgreet-session
     Generic configuration record for the wlgreet greetd greeter.

     ‘wlgreet’ (default: ‘wlgreet’)
          The package with the ‘/bin/wlgreet’ command.

     ‘command’ (default: ‘(file-append sway "/bin/sway")’)
          Command to be started by ‘/bin/wlgreet’ on successful login.

     ‘command-args’ (default: ‘'()’)
          Command arguments to pass to command.

     ‘output-mode’ (default: ‘"all"’)
          Option to use for ‘outputMode’ in the TOML configuration file.

     ‘scale’ (default: ‘1’)
          Option to use for ‘scale’ in the TOML configuration file.

     ‘background’ (default: ‘'(0 0 0 0.9)’)
          RGBA list to use as the background colour of the login prompt.

     ‘headline’ (default: ‘'(1 1 1 1)’)
          RGBA list to use as the headline colour of the UI popup.

     ‘prompt’ (default: ‘'(1 1 1 1)’)
          RGBA list to use as the prompt colour of the UI popup.

     ‘prompt-error’ (default: ‘'(1 1 1 1)’)
          RGBA list to use as the error colour of the UI popup.

     ‘border’ (default: ‘'(1 1 1 1)’)
          RGBA list to use as the border colour of the UI popup.

     ‘extra-env’ (default: ‘'()’)
          Extra environment variables to set on login.

 -- Data Type: greetd-wlgreet-sway-session
     Sway-specific configuration record for the wlgreet greetd greeter.

     ‘wlgreet-session’ (default: ‘(greetd-wlgreet-session)’)
          A ‘greetd-wlgreet-session’ record for generic wlgreet
          configuration, on top of the Sway-specific
          ‘greetd-wlgreet-sway-session’.

     ‘sway’ (default: ‘sway’)
          The package providing the ‘/bin/sway’ command.

     ‘sway-configuration’ (default: #f)
          File-like object providing an additional Sway configuration
          file to be prepended to the mandatory part of the
          configuration.

     Here is an example of a greetd configuration that uses wlgreet and
     Sway:

            (greetd-configuration
             ;; We need to give the greeter user these permissions, otherwise
             ;; Sway will crash on launch.
             (greeter-supplementary-groups (list "video" "input" "seat"))
             (terminals
              (list (greetd-terminal-configuration
                     (terminal-vt "1")
                     (terminal-switch #t)
                     (default-session-command
                      (greetd-wlgreet-sway-session
                       (sway-configuration
                        (local-file "sway-greetd.conf"))))))))


File: guix.info,  Node: Scheduled Job Execution,  Next: Log Rotation,  Prev: Base Services,  Up: Services

12.9.2 Scheduled Job Execution
------------------------------

The ‘(gnu services mcron)’ module provides an interface to GNU mcron, a
daemon to run jobs at scheduled times (*note (mcron)Top::).  GNU mcron
is similar to the traditional Unix ‘cron’ daemon; the main difference is
that it is implemented in Guile Scheme, which provides a lot of
flexibility when specifying the scheduling of jobs and their actions.

   The example below defines an operating system that runs the
‘updatedb’ (*note (find)Invoking updatedb::) and the ‘guix gc’ commands
(*note Invoking guix gc::) daily, as well as the ‘mkid’ command on
behalf of an unprivileged user (*note (idutils)mkid invocation::).  It
uses gexps to introduce job definitions that are passed to mcron (*note
G-Expressions::).

     (use-modules (guix) (gnu) (gnu services mcron))
     (use-package-modules base idutils)

     (define updatedb-job
       ;; Run 'updatedb' at 3AM every day.  Here we write the
       ;; job's action as a Scheme procedure.
       #~(job '(next-hour '(3))
              (lambda ()
                (execl (string-append #$findutils "/bin/updatedb")
                       "updatedb"
                       "--prunepaths=/tmp /var/tmp /gnu/store"))
              "updatedb"))

     (define garbage-collector-job
       ;; Collect garbage 5 minutes after midnight every day.
       ;; The job's action is a shell command.
       #~(job "5 0 * * *"            ;Vixie cron syntax
              "guix gc -F 1G"))

     (define idutils-job
       ;; Update the index database as user "charlie" at 12:15PM
       ;; and 19:15PM.  This runs from the user's home directory.
       #~(job '(next-minute-from (next-hour '(12 19)) '(15))
              (string-append #$idutils "/bin/mkid src")
              #:user "charlie"))

     (operating-system
       ;; ...

       ;; %BASE-SERVICES already includes an instance of
       ;; 'mcron-service-type', which we extend with additional
       ;; jobs using 'simple-service'.
       (services (cons (simple-service 'my-cron-jobs
                                        mcron-service-type
                                        (list garbage-collector-job
                                              updatedb-job
                                              idutils-job))
                       %base-services)))

     Tip: When providing the action of a job specification as a
     procedure, you should provide an explicit name for the job via the
     optional 3rd argument as done in the ‘updatedb-job’ example above.
     Otherwise, the job would appear as “Lambda function” in the output
     of ‘herd schedule mcron’, which is not nearly descriptive enough!

   For more complex jobs defined in Scheme where you need control over
the top level, for instance to introduce a ‘use-modules’ form, you can
move your code to a separate program using the ‘program-file’ procedure
of the ‘(guix gexp)’ module (*note G-Expressions::).  The example below
illustrates that.

     (define %battery-alert-job
       ;; Beep when the battery percentage falls below %MIN-LEVEL.
       #~(job
          '(next-minute (range 0 60 1))
          #$(program-file
             "battery-alert.scm"
             (with-imported-modules (source-module-closure
                                     '((guix build utils)))
               #~(begin
                   (use-modules (guix build utils)
                                (ice-9 popen)
                                (ice-9 regex)
                                (ice-9 textual-ports)
                                (srfi srfi-2))

                   (define %min-level 20)

                   (setenv "LC_ALL" "C")     ;ensure English output
                   (and-let* ((input-pipe (open-pipe*
                                           OPEN_READ
                                           #$(file-append acpi "/bin/acpi")))
                              (output (get-string-all input-pipe))
                              (m (string-match "Discharging, ([0-9]+)%" output))
                              (level (string->number (match:substring m 1)))
                              ((< level %min-level)))
                     (format #t "warning: Battery level is low (~a%)~%" level)
                     (invoke #$(file-append beep "/bin/beep") "-r5")))))))

   *Note mcron job specifications: (mcron)Guile Syntax, for more
information on mcron job specifications.  Below is the reference of the
mcron service.

   On a running system, you can use the ‘schedule’ action of the service
to visualize the mcron jobs that will be executed next:

     # herd schedule mcron

The example above lists the next five tasks that will be executed, but
you can also specify the number of tasks to display:

     # herd schedule mcron 10

 -- Scheme Variable: mcron-service-type
     This is the type of the ‘mcron’ service, whose value is an
     ‘mcron-configuration’ object.

     This service type can be the target of a service extension that
     provides additional job specifications (*note Service
     Composition::).  In other words, it is possible to define services
     that provide additional mcron jobs to run.

 -- Data Type: mcron-configuration
     Available ‘mcron-configuration’ fields are:

     ‘mcron’ (default: ‘mcron’) (type: file-like)
          The mcron package to use.

     ‘jobs’ (default: ‘()’) (type: list-of-gexps)
          This is a list of gexps (*note G-Expressions::), where each
          gexp corresponds to an mcron job specification (*note mcron
          job specifications: (mcron)Syntax.).

     ‘log?’ (default: ‘#t’) (type: boolean)
          Log messages to standard output.

     ‘log-format’ (default: ‘"~1@*~a ~a: ~a~%"’) (type: string)
          ‘(ice-9 format)’ format string for log messages.  The default
          value produces messages like "‘PID NAME: MESSAGE"’ (*note
          Invoking: (mcron)Invoking mcron.).  Each message is also
          prefixed by a timestamp by GNU Shepherd.


File: guix.info,  Node: Log Rotation,  Next: Networking Setup,  Prev: Scheduled Job Execution,  Up: Services

12.9.3 Log Rotation
-------------------

Log files such as those found in ‘/var/log’ tend to grow endlessly, so
it’s a good idea to “rotate” them once in a while—i.e., archive their
contents in separate files, possibly compressed.  The ‘(gnu services
admin)’ module provides an interface to GNU Rot[t]log, a log rotation
tool (*note (rottlog)Top::).

   This service is part of ‘%base-services’, and thus enabled by
default, with the default settings, for commonly encountered log files.
The example below shows how to extend it with an additional “rotation”,
should you need to do that (usually, services that produce log files
already take care of that):

     (use-modules (guix) (gnu))
     (use-service-modules admin)

     (define my-log-files
       ;; Log files that I want to rotate.
       '("/var/log/something.log" "/var/log/another.log"))

     (operating-system
       ;; ...
       (services (cons (simple-service 'rotate-my-stuff
                                       rottlog-service-type
                                       (list (log-rotation
                                              (frequency 'daily)
                                              (files my-log-files))))
                       %base-services)))

 -- Scheme Variable: rottlog-service-type
     This is the type of the Rottlog service, whose value is a
     ‘rottlog-configuration’ object.

     Other services can extend this one with new ‘log-rotation’ objects
     (see below), thereby augmenting the set of files to be rotated.

     This service type can define mcron jobs (*note Scheduled Job
     Execution::) to run the rottlog service.

 -- Data Type: rottlog-configuration
     Data type representing the configuration of rottlog.

     ‘rottlog’ (default: ‘rottlog’)
          The Rottlog package to use.

     ‘rc-file’ (default: ‘(file-append rottlog "/etc/rc")’)
          The Rottlog configuration file to use (*note
          (rottlog)Mandatory RC Variables::).

     ‘rotations’ (default: ‘%default-rotations’)
          A list of ‘log-rotation’ objects as defined below.

     ‘jobs’
          This is a list of gexps where each gexp corresponds to an
          mcron job specification (*note Scheduled Job Execution::).

 -- Data Type: log-rotation
     Data type representing the rotation of a group of log files.

     Taking an example from the Rottlog manual (*note (rottlog)Period
     Related File Examples::), a log rotation might be defined like
     this:

          (log-rotation
            (frequency 'daily)
            (files '("/var/log/apache/*"))
            (options '("storedir apache-archives"
                       "rotate 6"
                       "notifempty"
                       "nocompress")))

     The list of fields is as follows:

     ‘frequency’ (default: ‘'weekly’)
          The log rotation frequency, a symbol.

     ‘files’
          The list of files or file glob patterns to rotate.

     ‘options’ (default: ‘%default-log-rotation-options’)
          The list of rottlog options for this rotation (*note
          (rottlog)Configuration parameters::).

     ‘post-rotate’ (default: ‘#f’)
          Either ‘#f’ or a gexp to execute once the rotation has
          completed.

 -- Scheme Variable: %default-rotations
     Specifies weekly rotation of ‘%rotated-files’ and of
     ‘/var/log/guix-daemon.log’.

 -- Scheme Variable: %rotated-files
     The list of syslog-controlled files to be rotated.  By default it
     is: ‘'("/var/log/messages" "/var/log/secure" "/var/log/debug" \
     "/var/log/maillog")’.

   Some log files just need to be deleted periodically once they are
old, without any other criterion and without any archival step.  This is
the case of build logs stored by ‘guix-daemon’ under
‘/var/log/guix/drvs’ (*note Invoking guix-daemon::).  The ‘log-cleanup’
service addresses this use case.  For example, ‘%base-services’ (*note
Base Services::) includes the following:

     ;; Periodically delete old build logs.
     (service log-cleanup-service-type
              (log-cleanup-configuration
               (directory "/var/log/guix/drvs")))

   That ensures build logs do not accumulate endlessly.

 -- Scheme Variable: log-cleanup-service-type
     This is the type of the service to delete old logs.  Its value must
     be a ‘log-cleanup-configuration’ record as described below.

 -- Data Type: log-cleanup-configuration
     Data type representing the log cleanup configuration

     ‘directory’
          Name of the directory containing log files.

     ‘expiry’ (default: ‘(* 6 30 24 3600)’)
          Age in seconds after which a file is subject to deletion (six
          months by default).

     ‘schedule’ (default: ‘"30 12 01,08,15,22 * *"’)
          String or gexp denoting the corresponding mcron job schedule
          (*note Scheduled Job Execution::).

Anonip Service
--------------

Anonip is a privacy filter that removes IP address from web server logs.
This service creates a FIFO and filters any written lines with anonip
before writing the filtered log to a target file.

   The following example sets up the FIFO
‘/var/run/anonip/https.access.log’ and writes the filtered log file
‘/var/log/anonip/https.access.log’.

     (service anonip-service-type
              (anonip-configuration
                (input  "/var/run/anonip/https.access.log")
                (output "/var/log/anonip/https.access.log")))

   Configure your web server to write its logs to the FIFO at
‘/var/run/anonip/https.access.log’ and collect the anonymized log file
at ‘/var/web-logs/https.access.log’.

 -- Data Type: anonip-configuration
     This data type represents the configuration of anonip.  It has the
     following parameters:

     ‘anonip’ (default: ‘anonip’)
          The anonip package to use.

     ‘input’
          The file name of the input log file to process.  The service
          creates a FIFO of this name.  The web server should write its
          logs to this FIFO.

     ‘output’
          The file name of the processed log file.

     The following optional settings may be provided:

     ‘skip-private?’
          When ‘#true’ do not mask addresses in private ranges.

     ‘column’
          A 1-based indexed column number.  Assume IP address is in the
          specified column (default is 1).

     ‘replacement’
          Replacement string in case address parsing fails, e.g.
          ‘"0.0.0.0"’.

     ‘ipv4mask’
          Number of bits to mask in IPv4 addresses.

     ‘ipv6mask’
          Number of bits to mask in IPv6 addresses.

     ‘increment’
          Increment the IP address by the given number.  By default this
          is zero.

     ‘delimiter’
          Log delimiter string.

     ‘regex’
          Regular expression for detecting IP addresses.  Use this
          instead of ‘column’.


File: guix.info,  Node: Networking Setup,  Next: Networking Services,  Prev: Log Rotation,  Up: Services

12.9.4 Networking Setup
-----------------------

The ‘(gnu services networking)’ module provides services to configure
network interfaces and set up networking on your machine.  Those
services provide different ways for you to set up your machine: by
declaring a static network configuration, by running a Dynamic Host
Configuration Protocol (DHCP) client, or by running daemons such as
NetworkManager and Connman that automate the whole process,
automatically adapt to connectivity changes, and provide a high-level
user interface.

   On a laptop, NetworkManager and Connman are by far the most
convenient options, which is why the default desktop services include
NetworkManager (*note ‘%desktop-services’: Desktop Services.).  For a
server, or for a virtual machine or a container, static network
configuration or a simple DHCP client are often more appropriate.

   This section describes the various network setup services available,
starting with static network configuration.

 -- Scheme Variable: static-networking-service-type
     This is the type for statically-configured network interfaces.  Its
     value must be a list of ‘static-networking’ records.  Each of them
     declares a set of “addresses”, “routes”, and “links”, as shown
     below.

     Here is the simplest configuration, with only one network interface
     controller (NIC) and only IPv4 connectivity:

          ;; Static networking for one NIC, IPv4-only.
          (service static-networking-service-type
                   (list (static-networking
                          (addresses
                           (list (network-address
                                  (device "eno1")
                                  (value "10.0.2.15/24"))))
                          (routes
                           (list (network-route
                                  (destination "default")
                                  (gateway "10.0.2.2"))))
                          (name-servers '("10.0.2.3")))))

     The snippet above can be added to the ‘services’ field of your
     operating system configuration (*note Using the Configuration
     System::).  It will configure your machine to have 10.0.2.15 as its
     IP address, with a 24-bit netmask for the local network—meaning
     that any 10.0.2.X address is on the local area network (LAN).
     Traffic to addresses outside the local network is routed via
     10.0.2.2.  Host names are resolved by sending domain name system
     (DNS) queries to 10.0.2.3.

 -- Data Type: static-networking
     This is the data type representing a static network configuration.

     As an example, here is how you would declare the configuration of a
     machine with a single network interface controller (NIC) available
     as ‘eno1’, and with one IPv4 and one IPv6 address:

          ;; Network configuration for one NIC, IPv4 + IPv6.
          (static-networking
           (addresses (list (network-address
                             (device "eno1")
                             (value "10.0.2.15/24"))
                            (network-address
                             (device "eno1")
                             (value "2001:123:4567:101::1/64"))))
           (routes (list (network-route
                          (destination "default")
                          (gateway "10.0.2.2"))
                         (network-route
                          (destination "default")
                          (gateway "2020:321:4567:42::1"))))
           (name-servers '("10.0.2.3")))

     If you are familiar with the ‘ip’ command of the ‘iproute2’ package
     (https://wiki.linuxfoundation.org/networking/iproute2) found on
     Linux-based systems, the declaration above is equivalent to typing:

          ip address add 10.0.2.15/24 dev eno1
          ip address add 2001:123:4567:101::1/64 dev eno1
          ip route add default via inet 10.0.2.2
          ip route add default via inet6 2020:321:4567:42::1

     Run ‘man 8 ip’ for more info.  Venerable GNU/Linux users will
     certainly know how to do it with ‘ifconfig’ and ‘route’, but we’ll
     spare you that.

     The available fields of this data type are as follows:

     ‘addresses’
     ‘links’ (default: ‘'()’)
     ‘routes’ (default: ‘'()’)
          The list of ‘network-address’, ‘network-link’, and
          ‘network-route’ records for this network (see below).

     ‘name-servers’ (default: ‘'()’)
          The list of IP addresses (strings) of domain name servers.
          These IP addresses go to ‘/etc/resolv.conf’.

     ‘provision’ (default: ‘'(networking)’)
          If true, this should be a list of symbols for the Shepherd
          service corresponding to this network configuration.

     ‘requirement’ (default ‘'()’)
          The list of Shepherd services depended on.

 -- Data Type: network-address
     This is the data type representing the IP address of a network
     interface.

     ‘device’
          The name of the network interface for this address—e.g.,
          ‘"eno1"’.

     ‘value’
          The actual IP address and network mask, in CIDR (Classless
          Inter-Domain Routing) notation
          (https://en.wikipedia.org/wiki/CIDR#CIDR_notation), as a
          string.

          For example, ‘"10.0.2.15/24"’ denotes IPv4 address 10.0.2.15
          on a 24-bit sub-network—all 10.0.2.X addresses are on the same
          local network.

     ‘ipv6?’
          Whether ‘value’ denotes an IPv6 address.  By default this is
          automatically determined.

 -- Data Type: network-route
     This is the data type representing a network route.

     ‘destination’
          The route destination (a string), either an IP address and
          network mask or ‘"default"’ to denote the default route.

     ‘source’ (default: ‘#f’)
          The route source.

     ‘device’ (default: ‘#f’)
          The device used for this route—e.g., ‘"eno2"’.

     ‘ipv6?’ (default: auto)
          Whether this is an IPv6 route.  By default this is
          automatically determined based on ‘destination’ or ‘gateway’.

     ‘gateway’ (default: ‘#f’)
          IP address (a string) through which traffic is routed.

 -- Data Type: network-link
     Data type for a network link (*note (guile-netlink)Link::).

     ‘name’
          The name of the link—e.g., ‘"v0p0"’.

     ‘type’
          A symbol denoting the type of the link—e.g., ‘'veth’.

     ‘arguments’
          List of arguments for this type of link.

 -- Scheme Variable: %loopback-static-networking
     This is the ‘static-networking’ record representing the “loopback
     device”, ‘lo’, for IP addresses 127.0.0.1 and ::1, and providing
     the ‘loopback’ Shepherd service.

 -- Scheme Variable: %qemu-static-networking
     This is the ‘static-networking’ record representing network setup
     when using QEMU’s user-mode network stack on ‘eth0’ (*note
     (QEMU)Using the user mode network stack::).

 -- Scheme Variable: dhcp-client-service-type
     This is the type of services that run DHCP, a Dynamic Host
     Configuration Protocol (DHCP) client.

 -- Data Type: dhcp-client-configuration
     Data type representing the configuration of the DHCP client
     service.

     ‘package’ (default: ‘isc-dhcp’)
          DHCP client package to use.

     ‘interfaces’ (default: ‘'all’)
          Either ‘'all’ or the list of interface names that the DHCP
          client should listen on—e.g., ‘'("eno1")’.

          When set to ‘'all’, the DHCP client listens on all the
          available non-loopback interfaces that can be activated.
          Otherwise the DHCP client listens only on the specified
          interfaces.

 -- Scheme Variable: network-manager-service-type
     This is the service type for the NetworkManager
     (https://wiki.gnome.org/Projects/NetworkManager) service.  The
     value for this service type is a ‘network-manager-configuration’
     record.

     This service is part of ‘%desktop-services’ (*note Desktop
     Services::).

 -- Data Type: network-manager-configuration
     Data type representing the configuration of NetworkManager.

     ‘network-manager’ (default: ‘network-manager’)
          The NetworkManager package to use.

     ‘dns’ (default: ‘"default"’)
          Processing mode for DNS, which affects how NetworkManager uses
          the ‘resolv.conf’ configuration file.

          ‘default’
               NetworkManager will update ‘resolv.conf’ to reflect the
               nameservers provided by currently active connections.

          ‘dnsmasq’
               NetworkManager will run ‘dnsmasq’ as a local caching
               nameserver, using a “conditional forwarding”
               configuration if you are connected to a VPN, and then
               update ‘resolv.conf’ to point to the local nameserver.

               With this setting, you can share your network connection.
               For example when you want to share your network
               connection to another laptop via an Ethernet cable, you
               can open ‘nm-connection-editor’ and configure the Wired
               connection’s method for IPv4 and IPv6 to be “Shared to
               other computers” and reestablish the connection (or
               reboot).

               You can also set up a “host-to-guest connection” to QEMU
               VMs (*note Installing Guix in a VM::).  With a
               host-to-guest connection, you can e.g. access a Web
               server running on the VM (*note Web Services::) from a
               Web browser on your host system, or connect to the VM via
               SSH (*note ‘openssh-service-type’: Networking Services.).
               To set up a host-to-guest connection, run this command
               once:

                    nmcli connection add type tun \
                     connection.interface-name tap0 \
                     tun.mode tap tun.owner $(id -u) \
                     ipv4.method shared \
                     ipv4.addresses 172.28.112.1/24

               Then each time you launch your QEMU VM (*note Running
               Guix in a VM::), pass ‘-nic
               tap,ifname=tap0,script=no,downscript=no’ to
               ‘qemu-system-...’.

          ‘none’
               NetworkManager will not modify ‘resolv.conf’.

     ‘vpn-plugins’ (default: ‘'()’)
          This is the list of available plugins for virtual private
          networks (VPNs).  An example of this is the
          ‘network-manager-openvpn’ package, which allows NetworkManager
          to manage VPNs via OpenVPN.

 -- Scheme Variable: connman-service-type
     This is the service type to run Connman (https://01.org/connman), a
     network connection manager.

     Its value must be an ‘connman-configuration’ record as in this
     example:

          (service connman-service-type
                   (connman-configuration
                     (disable-vpn? #t)))

     See below for details about ‘connman-configuration’.

 -- Data Type: connman-configuration
     Data Type representing the configuration of connman.

     ‘connman’ (default: CONNMAN)
          The connman package to use.

     ‘disable-vpn?’ (default: ‘#f’)
          When true, disable connman’s vpn plugin.

 -- Scheme Variable: wpa-supplicant-service-type
     This is the service type to run WPA supplicant
     (https://w1.fi/wpa_supplicant/), an authentication daemon required
     to authenticate against encrypted WiFi or ethernet networks.

 -- Data Type: wpa-supplicant-configuration
     Data type representing the configuration of WPA Supplicant.

     It takes the following parameters:

     ‘wpa-supplicant’ (default: ‘wpa-supplicant’)
          The WPA Supplicant package to use.

     ‘requirement’ (default: ‘'(user-processes loopback syslogd)’
          List of services that should be started before WPA Supplicant
          starts.

     ‘dbus?’ (default: ‘#t’)
          Whether to listen for requests on D-Bus.

     ‘pid-file’ (default: ‘"/var/run/wpa_supplicant.pid"’)
          Where to store the PID file.

     ‘interface’ (default: ‘#f’)
          If this is set, it must specify the name of a network
          interface that WPA supplicant will control.

     ‘config-file’ (default: ‘#f’)
          Optional configuration file to use.

     ‘extra-options’ (default: ‘'()’)
          List of additional command-line arguments to pass to the
          daemon.

   Some networking devices such as modems require special care, and this
is what the services below focus on.

 -- Scheme Variable: modem-manager-service-type
     This is the service type for the ModemManager
     (https://wiki.gnome.org/Projects/ModemManager) service.  The value
     for this service type is a ‘modem-manager-configuration’ record.

     This service is part of ‘%desktop-services’ (*note Desktop
     Services::).

 -- Data Type: modem-manager-configuration
     Data type representing the configuration of ModemManager.

     ‘modem-manager’ (default: ‘modem-manager’)
          The ModemManager package to use.

 -- Scheme Variable: usb-modeswitch-service-type
     This is the service type for the USB_ModeSwitch
     (https://www.draisberghof.de/usb_modeswitch/) service.  The value
     for this service type is a ‘usb-modeswitch-configuration’ record.

     When plugged in, some USB modems (and other USB devices) initially
     present themselves as a read-only storage medium and not as a
     modem.  They need to be “modeswitched” before they are usable.  The
     USB_ModeSwitch service type installs udev rules to automatically
     modeswitch these devices when they are plugged in.

     This service is part of ‘%desktop-services’ (*note Desktop
     Services::).

 -- Data Type: usb-modeswitch-configuration
     Data type representing the configuration of USB_ModeSwitch.

     ‘usb-modeswitch’ (default: ‘usb-modeswitch’)
          The USB_ModeSwitch package providing the binaries for
          modeswitching.

     ‘usb-modeswitch-data’ (default: ‘usb-modeswitch-data’)
          The package providing the device data and udev rules file used
          by USB_ModeSwitch.

     ‘config-file’ (default: ‘#~(string-append #$usb-modeswitch:dispatcher "/etc/usb_modeswitch.conf")’)
          Which config file to use for the USB_ModeSwitch dispatcher.
          By default the config file shipped with USB_ModeSwitch is used
          which disables logging to ‘/var/log’ among other default
          settings.  If set to ‘#f’, no config file is used.


File: guix.info,  Node: Networking Services,  Next: Unattended Upgrades,  Prev: Networking Setup,  Up: Services

12.9.5 Networking Services
--------------------------

The ‘(gnu services networking)’ module discussed in the previous section
provides services for more advanced setups: providing a DHCP service for
others to use, filtering packets with iptables or nftables, running a
WiFi access point with ‘hostapd’, running the ‘inetd’ “superdaemon”, and
more.  This section describes those.

 -- Scheme Procedure: dhcpd-service-type
     This type defines a service that runs a DHCP daemon.  To create a
     service of this type, you must supply a ‘<dhcpd-configuration>’.
     For example:

          (service dhcpd-service-type
                   (dhcpd-configuration
                    (config-file (local-file "my-dhcpd.conf"))
                    (interfaces '("enp0s25"))))

 -- Data Type: dhcpd-configuration
     ‘package’ (default: ‘isc-dhcp’)
          The package that provides the DHCP daemon.  This package is
          expected to provide the daemon at ‘sbin/dhcpd’ relative to its
          output directory.  The default package is the ISC’s DHCP
          server (https://www.isc.org/dhcp/).
     ‘config-file’ (default: ‘#f’)
          The configuration file to use.  This is required.  It will be
          passed to ‘dhcpd’ via its ‘-cf’ option.  This may be any
          “file-like” object (*note file-like objects: G-Expressions.).
          See ‘man dhcpd.conf’ for details on the configuration file
          syntax.
     ‘version’ (default: ‘"4"’)
          The DHCP version to use.  The ISC DHCP server supports the
          values “4”, “6”, and “4o6”.  These correspond to the ‘dhcpd’
          program options ‘-4’, ‘-6’, and ‘-4o6’.  See ‘man dhcpd’ for
          details.
     ‘run-directory’ (default: ‘"/run/dhcpd"’)
          The run directory to use.  At service activation time, this
          directory will be created if it does not exist.
     ‘pid-file’ (default: ‘"/run/dhcpd/dhcpd.pid"’)
          The PID file to use.  This corresponds to the ‘-pf’ option of
          ‘dhcpd’.  See ‘man dhcpd’ for details.
     ‘interfaces’ (default: ‘'()’)
          The names of the network interfaces on which dhcpd should
          listen for broadcasts.  If this list is not empty, then its
          elements (which must be strings) will be appended to the
          ‘dhcpd’ invocation when starting the daemon.  It may not be
          necessary to explicitly specify any interfaces here; see ‘man
          dhcpd’ for details.

 -- Scheme Variable: hostapd-service-type
     This is the service type to run the hostapd
     (https://w1.fi/hostapd/) daemon to set up WiFi (IEEE 802.11) access
     points and authentication servers.  Its associated value must be a
     ‘hostapd-configuration’ as shown below:

          ;; Use wlan1 to run the access point for "My Network".
          (service hostapd-service-type
                   (hostapd-configuration
                    (interface "wlan1")
                    (ssid "My Network")
                    (channel 12)))

 -- Data Type: hostapd-configuration
     This data type represents the configuration of the hostapd service,
     with the following fields:

     ‘package’ (default: ‘hostapd’)
          The hostapd package to use.

     ‘interface’ (default: ‘"wlan0"’)
          The network interface to run the WiFi access point.

     ‘ssid’
          The SSID (“service set identifier”), a string that identifies
          this network.

     ‘broadcast-ssid?’ (default: ‘#t’)
          Whether to broadcast this SSID.

     ‘channel’ (default: ‘1’)
          The WiFi channel to use.

     ‘driver’ (default: ‘"nl80211"’)
          The driver interface type.  ‘"nl80211"’ is used with all Linux
          mac80211 drivers.  Use ‘"none"’ if building hostapd as a
          standalone RADIUS server that does # not control any
          wireless/wired driver.

     ‘extra-settings’ (default: ‘""’)
          Extra settings to append as-is to the hostapd configuration
          file.  See
          <https://w1.fi/cgit/hostap/plain/hostapd/hostapd.conf> for the
          configuration file reference.

 -- Scheme Variable: simulated-wifi-service-type
     This is the type of a service to simulate WiFi networking, which
     can be useful in virtual machines for testing purposes.  The
     service loads the Linux kernel ‘mac80211_hwsim’ module
     (https://www.kernel.org/doc/html/latest/networking/mac80211_hwsim/mac80211_hwsim.html)
     and starts hostapd to create a pseudo WiFi network that can be seen
     on ‘wlan0’, by default.

     The service’s value is a ‘hostapd-configuration’ record.

 -- Scheme Variable: iptables-service-type
     This is the service type to set up an iptables configuration.
     iptables is a packet filtering framework supported by the Linux
     kernel.  This service supports configuring iptables for both IPv4
     and IPv6.  A simple example configuration rejecting all incoming
     connections except those to the ssh port 22 is shown below.

          (service iptables-service-type
                   (iptables-configuration
                    (ipv4-rules (plain-file "iptables.rules" "*filter
          :INPUT ACCEPT
          :FORWARD ACCEPT
          :OUTPUT ACCEPT
          -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
          -A INPUT -p tcp --dport 22 -j ACCEPT
          -A INPUT -j REJECT --reject-with icmp-port-unreachable
          COMMIT
          "))
                    (ipv6-rules (plain-file "ip6tables.rules" "*filter
          :INPUT ACCEPT
          :FORWARD ACCEPT
          :OUTPUT ACCEPT
          -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
          -A INPUT -p tcp --dport 22 -j ACCEPT
          -A INPUT -j REJECT --reject-with icmp6-port-unreachable
          COMMIT
          "))))

 -- Data Type: iptables-configuration
     The data type representing the configuration of iptables.

     ‘iptables’ (default: ‘iptables’)
          The iptables package that provides ‘iptables-restore’ and
          ‘ip6tables-restore’.
     ‘ipv4-rules’ (default: ‘%iptables-accept-all-rules’)
          The iptables rules to use.  It will be passed to
          ‘iptables-restore’.  This may be any “file-like” object (*note
          file-like objects: G-Expressions.).
     ‘ipv6-rules’ (default: ‘%iptables-accept-all-rules’)
          The ip6tables rules to use.  It will be passed to
          ‘ip6tables-restore’.  This may be any “file-like” object
          (*note file-like objects: G-Expressions.).

 -- Scheme Variable: nftables-service-type
     This is the service type to set up a nftables configuration.
     nftables is a netfilter project that aims to replace the existing
     iptables, ip6tables, arptables and ebtables framework.  It provides
     a new packet filtering framework, a new user-space utility ‘nft’,
     and a compatibility layer for iptables.  This service comes with a
     default ruleset ‘%default-nftables-ruleset’ that rejecting all
     incoming connections except those to the ssh port 22.  To use it,
     simply write:

          (service nftables-service-type)

 -- Data Type: nftables-configuration
     The data type representing the configuration of nftables.

     ‘package’ (default: ‘nftables’)
          The nftables package that provides ‘nft’.
     ‘ruleset’ (default: ‘%default-nftables-ruleset’)
          The nftables ruleset to use.  This may be any “file-like”
          object (*note file-like objects: G-Expressions.).

 -- Scheme Variable: ntp-service-type
     This is the type of the service running the Network Time Protocol
     (NTP) (https://www.ntp.org) daemon, ‘ntpd’.  The daemon will keep
     the system clock synchronized with that of the specified NTP
     servers.

     The value of this service is an ‘ntpd-configuration’ object, as
     described below.

 -- Data Type: ntp-configuration
     This is the data type for the NTP service configuration.

     ‘servers’ (default: ‘%ntp-servers’)
          This is the list of servers (‘<ntp-server>’ records) with
          which ‘ntpd’ will be synchronized.  See the ‘ntp-server’ data
          type definition below.

     ‘allow-large-adjustment?’ (default: ‘#t’)
          This determines whether ‘ntpd’ is allowed to make an initial
          adjustment of more than 1,000 seconds.

     ‘ntp’ (default: ‘ntp’)
          The NTP package to use.

 -- Scheme Variable: %ntp-servers
     List of host names used as the default NTP servers.  These are
     servers of the NTP Pool Project (https://www.ntppool.org/en/).

 -- Data Type: ntp-server
     The data type representing the configuration of a NTP server.

     ‘type’ (default: ‘'server’)
          The type of the NTP server, given as a symbol.  One of
          ‘'pool’, ‘'server’, ‘'peer’, ‘'broadcast’ or
          ‘'manycastclient’.

     ‘address’
          The address of the server, as a string.

     ‘options’
          NTPD options to use with that specific server, given as a list
          of option names and/or of option names and values tuples.  The
          following example define a server to use with the options
          ‘iburst’ and ‘prefer’, as well as ‘version’ 3 and a ‘maxpoll’
          time of 16 seconds.

               (ntp-server
                (type 'server)
                (address "some.ntp.server.org")
                (options `(iburst (version 3) (maxpoll 16) prefer))))

 -- Scheme Procedure: openntpd-service-type
     Run the ‘ntpd’, the Network Time Protocol (NTP) daemon, as
     implemented by OpenNTPD (http://www.openntpd.org).  The daemon will
     keep the system clock synchronized with that of the given servers.

          (service
           openntpd-service-type
           (openntpd-configuration
            (listen-on '("127.0.0.1" "::1"))
            (sensor '("udcf0 correction 70000"))
            (constraint-from '("www.gnu.org"))
            (constraints-from '("https://www.google.com/"))))


 -- Scheme Variable: %openntpd-servers
     This variable is a list of the server addresses defined in
     ‘%ntp-servers’.

 -- Data Type: openntpd-configuration
     ‘openntpd’ (default: ‘(file-append openntpd "/sbin/ntpd")’)
          The openntpd executable to use.
     ‘listen-on’ (default: ‘'("127.0.0.1" "::1")’)
          A list of local IP addresses or hostnames the ntpd daemon
          should listen on.
     ‘query-from’ (default: ‘'()’)
          A list of local IP address the ntpd daemon should use for
          outgoing queries.
     ‘sensor’ (default: ‘'()’)
          Specify a list of timedelta sensor devices ntpd should use.
          ‘ntpd’ will listen to each sensor that actually exists and
          ignore non-existent ones.  See upstream documentation
          (https://man.openbsd.org/ntpd.conf) for more information.
     ‘server’ (default: ‘'()’)
          Specify a list of IP addresses or hostnames of NTP servers to
          synchronize to.
     ‘servers’ (default: ‘%openntp-servers’)
          Specify a list of IP addresses or hostnames of NTP pools to
          synchronize to.
     ‘constraint-from’ (default: ‘'()’)
          ‘ntpd’ can be configured to query the ‘Date’ from trusted
          HTTPS servers via TLS. This time information is not used for
          precision but acts as an authenticated constraint, thereby
          reducing the impact of unauthenticated NTP man-in-the-middle
          attacks.  Specify a list of URLs, IP addresses or hostnames of
          HTTPS servers to provide a constraint.
     ‘constraints-from’ (default: ‘'()’)
          As with constraint from, specify a list of URLs, IP addresses
          or hostnames of HTTPS servers to provide a constraint.  Should
          the hostname resolve to multiple IP addresses, ‘ntpd’ will
          calculate a median constraint from all of them.

 -- Scheme variable: inetd-service-type
     This service runs the ‘inetd’ (*note (inetutils)inetd invocation::)
     daemon.  ‘inetd’ listens for connections on internet sockets, and
     lazily starts the specified server program when a connection is
     made on one of these sockets.

     The value of this service is an ‘inetd-configuration’ object.  The
     following example configures the ‘inetd’ daemon to provide the
     built-in ‘echo’ service, as well as an smtp service which forwards
     smtp traffic over ssh to a server ‘smtp-server’ behind a gateway
     ‘hostname’:

          (service
           inetd-service-type
           (inetd-configuration
            (entries (list
                      (inetd-entry
                       (name "echo")
                       (socket-type 'stream)
                       (protocol "tcp")
                       (wait? #f)
                       (user "root"))
                      (inetd-entry
                       (node "127.0.0.1")
                       (name "smtp")
                       (socket-type 'stream)
                       (protocol "tcp")
                       (wait? #f)
                       (user "root")
                       (program (file-append openssh "/bin/ssh"))
                       (arguments
                        '("ssh" "-qT" "-i" "/path/to/ssh_key"
                          "-W" "smtp-server:25" "user@hostname")))))))

     See below for more details about ‘inetd-configuration’.

 -- Data Type: inetd-configuration
     Data type representing the configuration of ‘inetd’.

     ‘program’ (default: ‘(file-append inetutils "/libexec/inetd")’)
          The ‘inetd’ executable to use.

     ‘entries’ (default: ‘'()’)
          A list of ‘inetd’ service entries.  Each entry should be
          created by the ‘inetd-entry’ constructor.

 -- Data Type: inetd-entry
     Data type representing an entry in the ‘inetd’ configuration.  Each
     entry corresponds to a socket where ‘inetd’ will listen for
     requests.

     ‘node’ (default: ‘#f’)
          Optional string, a comma-separated list of local addresses
          ‘inetd’ should use when listening for this service.  *Note
          (inetutils)Configuration file:: for a complete description of
          all options.
     ‘name’
          A string, the name must correspond to an entry in
          ‘/etc/services’.
     ‘socket-type’
          One of ‘'stream’, ‘'dgram’, ‘'raw’, ‘'rdm’ or ‘'seqpacket’.
     ‘protocol’
          A string, must correspond to an entry in ‘/etc/protocols’.
     ‘wait?’ (default: ‘#t’)
          Whether ‘inetd’ should wait for the server to exit before
          listening to new service requests.
     ‘user’
          A string containing the user (and, optionally, group) name of
          the user as whom the server should run.  The group name can be
          specified in a suffix, separated by a colon or period, i.e.
          ‘"user"’, ‘"user:group"’ or ‘"user.group"’.
     ‘program’ (default: ‘"internal"’)
          The server program which will serve the requests, or
          ‘"internal"’ if ‘inetd’ should use a built-in service.
     ‘arguments’ (default: ‘'()’)
          A list strings or file-like objects, which are the server
          program’s arguments, starting with the zeroth argument, i.e.
          the name of the program itself.  For ‘inetd’’s internal
          services, this entry must be ‘'()’ or ‘'("internal")’.

     *Note (inetutils)Configuration file:: for a more detailed
     discussion of each configuration field.

 -- Scheme Variable: opendht-service-type
     This is the type of the service running a OpenDHT
     (https://opendht.net) node, ‘dhtnode’.  The daemon can be used to
     host your own proxy service to the distributed hash table (DHT),
     for example to connect to with Jami, among other applications.

          Important: When using the OpenDHT proxy server, the IP
          addresses it “sees” from the clients should be addresses
          reachable from other peers.  In practice this means that a
          publicly reachable address is best suited for a proxy server,
          outside of your private network.  For example, hosting the
          proxy server on a IPv4 private local network and exposing it
          via port forwarding could work for external peers, but peers
          local to the proxy would have their private addresses shared
          with the external peers, leading to connectivity problems.

     The value of this service is a ‘opendht-configuration’ object, as
     described below.

 -- Data Type: opendht-configuration
     Available ‘opendht-configuration’ fields are:

     ‘opendht’ (default: ‘opendht’) (type: file-like)
          The ‘opendht’ package to use.

     ‘peer-discovery?’ (default: ‘#f’) (type: boolean)
          Whether to enable the multicast local peer discovery
          mechanism.

     ‘enable-logging?’ (default: ‘#f’) (type: boolean)
          Whether to enable logging messages to syslog.  It is disabled
          by default as it is rather verbose.

     ‘debug?’ (default: ‘#f’) (type: boolean)
          Whether to enable debug-level logging messages.  This has no
          effect if logging is disabled.

     ‘bootstrap-host’ (default: ‘"bootstrap.jami.net:4222"’) (type: maybe-string)
          The node host name that is used to make the first connection
          to the network.  A specific port value can be provided by
          appending the ‘:PORT’ suffix.  By default, it uses the Jami
          bootstrap nodes, but any host can be specified here.  It’s
          also possible to disable bootstrapping by explicitly setting
          this field to the ‘%unset-value’ value.

     ‘port’ (default: ‘4222’) (type: maybe-number)
          The UDP port to bind to.  When left unspecified, an available
          port is automatically selected.

     ‘proxy-server-port’ (type: maybe-number)
          Spawn a proxy server listening on the specified port.

     ‘proxy-server-port-tls’ (type: maybe-number)
          Spawn a proxy server listening to TLS connections on the
          specified port.

 -- Scheme Variable: tor-service-type
     This is the type for a service that runs the Tor
     (https://torproject.org) anonymous networking daemon.  The service
     is configured using a ‘<tor-configuration>’ record.  By default,
     the Tor daemon runs as the ‘tor’ unprivileged user, which is a
     member of the ‘tor’ group.

 -- Data Type: tor-configuration
     ‘tor’ (default: ‘tor’)
          The package that provides the Tor daemon.  This package is
          expected to provide the daemon at ‘bin/tor’ relative to its
          output directory.  The default package is the Tor Project’s
          (https://www.torproject.org) implementation.

     ‘config-file’ (default: ‘(plain-file "empty" "")’)
          The configuration file to use.  It will be appended to a
          default configuration file, and the final configuration file
          will be passed to ‘tor’ via its ‘-f’ option.  This may be any
          “file-like” object (*note file-like objects: G-Expressions.).
          See ‘man tor’ for details on the configuration file syntax.

     ‘hidden-services’ (default: ‘'()’)
          The list of ‘<hidden-service>’ records to use.  For any hidden
          service you include in this list, appropriate configuration to
          enable the hidden service will be automatically added to the
          default configuration file.  You may conveniently create
          ‘<hidden-service>’ records using the ‘tor-hidden-service’
          procedure described below.

     ‘socks-socket-type’ (default: ‘'tcp’)
          The default socket type that Tor should use for its SOCKS
          socket.  This must be either ‘'tcp’ or ‘'unix’.  If it is
          ‘'tcp’, then by default Tor will listen on TCP port 9050 on
          the loopback interface (i.e., localhost).  If it is ‘'unix’,
          then Tor will listen on the UNIX domain socket
          ‘/var/run/tor/socks-sock’, which will be made writable by
          members of the ‘tor’ group.

          If you want to customize the SOCKS socket in more detail,
          leave ‘socks-socket-type’ at its default value of ‘'tcp’ and
          use ‘config-file’ to override the default by providing your
          own ‘SocksPort’ option.

     ‘control-socket?’ (default: ‘#f’)
          Whether or not to provide a “control socket” by which Tor can
          be controlled to, for instance, dynamically instantiate tor
          onion services.  If ‘#t’, Tor will listen for control commands
          on the UNIX domain socket ‘/var/run/tor/control-sock’, which
          will be made writable by members of the ‘tor’ group.

 -- Scheme Procedure: tor-hidden-service NAME MAPPING
     Define a new Tor “hidden service” called NAME and implementing
     MAPPING.  MAPPING is a list of port/host tuples, such as:

           '((22 "127.0.0.1:22")
             (80 "127.0.0.1:8080"))

     In this example, port 22 of the hidden service is mapped to local
     port 22, and port 80 is mapped to local port 8080.

     This creates a ‘/var/lib/tor/hidden-services/NAME’ directory, where
     the ‘hostname’ file contains the ‘.onion’ host name for the hidden
     service.

     See the Tor project’s documentation
     (https://www.torproject.org/docs/tor-hidden-service.html.en) for
     more information.

   The ‘(gnu services rsync)’ module provides the following services:

   You might want an rsync daemon if you have files that you want
available so anyone (or just yourself) can download existing files or
upload new files.

 -- Scheme Variable: rsync-service-type
     This is the service type for the rsync (https://rsync.samba.org)
     daemon, The value for this service type is a ‘rsync-configuration’
     record as in this example:

          ;; Export two directories over rsync.  By default rsync listens on
          ;; all the network interfaces.
          (service rsync-service-type
                   (rsync-configuration
                     (modules (list (rsync-module
                                      (name "music")
                                      (file-name "/srv/zik")
                                      (read-only? #f))
                                    (rsync-module
                                      (name "movies")
                                      (file-name "/home/charlie/movies"))))))

     See below for details about ‘rsync-configuration’.

 -- Data Type: rsync-configuration
     Data type representing the configuration for ‘rsync-service’.

     ‘package’ (default: RSYNC)
          ‘rsync’ package to use.

     ‘address’ (default: ‘#f’)
          IP address on which ‘rsync’ listens for incoming connections.
          If unspecified, it defaults to listening on all available
          addresses.

     ‘port-number’ (default: ‘873’)
          TCP port on which ‘rsync’ listens for incoming connections.
          If port is less than ‘1024’ ‘rsync’ needs to be started as the
          ‘root’ user and group.

     ‘pid-file’ (default: ‘"/var/run/rsyncd/rsyncd.pid"’)
          Name of the file where ‘rsync’ writes its PID.

     ‘lock-file’ (default: ‘"/var/run/rsyncd/rsyncd.lock"’)
          Name of the file where ‘rsync’ writes its lock file.

     ‘log-file’ (default: ‘"/var/log/rsyncd.log"’)
          Name of the file where ‘rsync’ writes its log file.

     ‘user’ (default: ‘"root"’)
          Owner of the ‘rsync’ process.

     ‘group’ (default: ‘"root"’)
          Group of the ‘rsync’ process.

     ‘uid’ (default: ‘"rsyncd"’)
          User name or user ID that file transfers to and from that
          module should take place as when the daemon was run as ‘root’.

     ‘gid’ (default: ‘"rsyncd"’)
          Group name or group ID that will be used when accessing the
          module.

     ‘modules’ (default: ‘%default-modules’)
          List of “modules”—i.e., directories exported over rsync.  Each
          element must be a ‘rsync-module’ record, as described below.

 -- Data Type: rsync-module
     This is the data type for rsync “modules”.  A module is a directory
     exported over the rsync protocol.  The available fields are as
     follows:

     ‘name’
          The module name.  This is the name that shows up in URLs.  For
          example, if the module is called ‘music’, the corresponding
          URL will be ‘rsync://host.example.org/music’.

     ‘file-name’
          Name of the directory being exported.

     ‘comment’ (default: ‘""’)
          Comment associated with the module.  Client user interfaces
          may display it when they obtain the list of available modules.

     ‘read-only?’ (default: ‘#t’)
          Whether or not client will be able to upload files.  If this
          is false, the uploads will be authorized if permissions on the
          daemon side permit it.

     ‘chroot?’ (default: ‘#t’)
          When this is true, the rsync daemon changes root to the
          module’s directory before starting file transfers with the
          client.  This improves security, but requires rsync to run as
          root.

     ‘timeout’ (default: ‘300’)
          Idle time in seconds after which the daemon closes a
          connection with the client.

   The ‘(gnu services syncthing)’ module provides the following
services:

   You might want a syncthing daemon if you have files between two or
more computers and want to sync them in real time, safely protected from
prying eyes.

 -- Scheme Variable: syncthing-service-type
     This is the service type for the syncthing (https://syncthing.net/)
     daemon, The value for this service type is a
     ‘syncthing-configuration’ record as in this example:

          (service syncthing-service-type
                   (syncthing-configuration (user "alice")))

     See below for details about ‘syncthing-configuration’.

      -- Data Type: syncthing-configuration
          Data type representing the configuration for
          ‘syncthing-service-type’.

          ‘syncthing’ (default: SYNCTHING)
               ‘syncthing’ package to use.

          ‘arguments’ (default: ’())
               List of command-line arguments passing to ‘syncthing’
               binary.

          ‘logflags’ (default: 0)
               Sum of logging flags, see Syncthing documentation
               logflags
               (https://docs.syncthing.net/users/syncthing.html#cmdoption-logflags).

          ‘user’ (default: #F)
               The user as which the Syncthing service is to be run.
               This assumes that the specified user exists.

          ‘group’ (default: "USERS")
               The group as which the Syncthing service is to be run.
               This assumes that the specified group exists.

          ‘home’ (default: #F)
               Common configuration and data directory.  The default
               configuration directory is ‘$HOME’ of the specified
               Syncthing ‘user’.

   Furthermore, ‘(gnu services ssh)’ provides the following services.

 -- Scheme Procedure: lsh-service [#:host-key "/etc/lsh/host-key"]
          [#:daemonic? #t] [#:interfaces '()] [#:port-number 22]
          [#:allow-empty-passwords? #f] [#:root-login? #f]
          [#:syslog-output? #t] [#:x11-forwarding? #t]
          [#:tcp/ip-forwarding? #t] [#:password-authentication? #t]
          [#:public-key-authentication? #t] [#:initialize? #t]
     Run the ‘lshd’ program from LSH to listen on port PORT-NUMBER.
     HOST-KEY must designate a file containing the host key, and
     readable only by root.

     When DAEMONIC? is true, ‘lshd’ will detach from the controlling
     terminal and log its output to syslogd, unless one sets
     SYSLOG-OUTPUT? to false.  Obviously, it also makes lsh-service
     depend on existence of syslogd service.  When PID-FILE? is true,
     ‘lshd’ writes its PID to the file called PID-FILE.

     When INITIALIZE? is true, automatically create the seed and host
     key upon service activation if they do not exist yet.  This may
     take long and require interaction.

     When INITIALIZE? is false, it is up to the user to initialize the
     randomness generator (*note (lsh)lsh-make-seed::), and to create a
     key pair with the private key stored in file HOST-KEY (*note
     (lsh)lshd basics::).

     When INTERFACES is empty, lshd listens for connections on all the
     network interfaces; otherwise, INTERFACES must be a list of host
     names or addresses.

     ALLOW-EMPTY-PASSWORDS? specifies whether to accept log-ins with
     empty passwords, and ROOT-LOGIN? specifies whether to accept
     log-ins as root.

     The other options should be self-descriptive.

 -- Scheme Variable: openssh-service-type
     This is the type for the OpenSSH (http://www.openssh.org) secure
     shell daemon, ‘sshd’.  Its value must be an ‘openssh-configuration’
     record as in this example:

          (service openssh-service-type
                   (openssh-configuration
                     (x11-forwarding? #t)
                     (permit-root-login 'prohibit-password)
                     (authorized-keys
                       `(("alice" ,(local-file "alice.pub"))
                         ("bob" ,(local-file "bob.pub"))))))

     See below for details about ‘openssh-configuration’.

     This service can be extended with extra authorized keys, as in this
     example:

          (service-extension openssh-service-type
                             (const `(("charlie"
                                       ,(local-file "charlie.pub")))))

 -- Data Type: openssh-configuration
     This is the configuration record for OpenSSH’s ‘sshd’.

     ‘openssh’ (default OPENSSH)
          The OpenSSH package to use.

     ‘pid-file’ (default: ‘"/var/run/sshd.pid"’)
          Name of the file where ‘sshd’ writes its PID.

     ‘port-number’ (default: ‘22’)
          TCP port on which ‘sshd’ listens for incoming connections.

     ‘max-connections’ (default: ‘200’)
          Hard limit on the maximum number of simultaneous client
          connections, enforced by the inetd-style Shepherd service
          (*note ‘make-inetd-constructor’: (shepherd)Service De- and
          Constructors.).

     ‘permit-root-login’ (default: ‘#f’)
          This field determines whether and when to allow logins as
          root.  If ‘#f’, root logins are disallowed; if ‘#t’, they are
          allowed.  If it’s the symbol ‘'prohibit-password’, then root
          logins are permitted but not with password-based
          authentication.

     ‘allow-empty-passwords?’ (default: ‘#f’)
          When true, users with empty passwords may log in.  When false,
          they may not.

     ‘password-authentication?’ (default: ‘#t’)
          When true, users may log in with their password.  When false,
          they have other authentication methods.

     ‘public-key-authentication?’ (default: ‘#t’)
          When true, users may log in using public key authentication.
          When false, users have to use other authentication method.

          Authorized public keys are stored in ‘~/.ssh/authorized_keys’.
          This is used only by protocol version 2.

     ‘x11-forwarding?’ (default: ‘#f’)
          When true, forwarding of X11 graphical client connections is
          enabled—in other words, ‘ssh’ options ‘-X’ and ‘-Y’ will work.

     ‘allow-agent-forwarding?’ (default: ‘#t’)
          Whether to allow agent forwarding.

     ‘allow-tcp-forwarding?’ (default: ‘#t’)
          Whether to allow TCP forwarding.

     ‘gateway-ports?’ (default: ‘#f’)
          Whether to allow gateway ports.

     ‘challenge-response-authentication?’ (default: ‘#f’)
          Specifies whether challenge response authentication is allowed
          (e.g. via PAM).

     ‘use-pam?’ (default: ‘#t’)
          Enables the Pluggable Authentication Module interface.  If set
          to ‘#t’, this will enable PAM authentication using
          ‘challenge-response-authentication?’ and
          ‘password-authentication?’, in addition to PAM account and
          session module processing for all authentication types.

          Because PAM challenge response authentication usually serves
          an equivalent role to password authentication, you should
          disable either ‘challenge-response-authentication?’ or
          ‘password-authentication?’.

     ‘print-last-log?’ (default: ‘#t’)
          Specifies whether ‘sshd’ should print the date and time of the
          last user login when a user logs in interactively.

     ‘subsystems’ (default: ‘'(("sftp" "internal-sftp"))’)
          Configures external subsystems (e.g. file transfer daemon).

          This is a list of two-element lists, each of which containing
          the subsystem name and a command (with optional arguments) to
          execute upon subsystem request.

          The command ‘internal-sftp’ implements an in-process SFTP
          server.  Alternatively, one can specify the ‘sftp-server’
          command:
               (service openssh-service-type
                        (openssh-configuration
                         (subsystems
                          `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))

     ‘accepted-environment’ (default: ‘'()’)
          List of strings describing which environment variables may be
          exported.

          Each string gets on its own line.  See the ‘AcceptEnv’ option
          in ‘man sshd_config’.

          This example allows ssh-clients to export the ‘COLORTERM’
          variable.  It is set by terminal emulators, which support
          colors.  You can use it in your shell’s resource file to
          enable colors for the prompt and commands if this variable is
          set.

               (service openssh-service-type
                        (openssh-configuration
                          (accepted-environment '("COLORTERM"))))

     ‘authorized-keys’ (default: ‘'()’)
          This is the list of authorized keys.  Each element of the list
          is a user name followed by one or more file-like objects that
          represent SSH public keys.  For example:

               (openssh-configuration
                 (authorized-keys
                   `(("rekado" ,(local-file "rekado.pub"))
                     ("chris" ,(local-file "chris.pub"))
                     ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))

          registers the specified public keys for user accounts
          ‘rekado’, ‘chris’, and ‘root’.

          Additional authorized keys can be specified via
          ‘service-extension’.

          Note that this does _not_ interfere with the use of
          ‘~/.ssh/authorized_keys’.

     ‘generate-host-keys?’ (default: ‘#t’)
          Whether to generate host key pairs with ‘ssh-keygen -A’ under
          ‘/etc/ssh’ if there are none.

          Generating key pairs takes a few seconds when enough entropy
          is available and is only done once.  You might want to turn it
          off for instance in a virtual machine that does not need it
          because host keys are provided in some other way, and where
          the extra boot time is a problem.

     ‘log-level’ (default: ‘'info’)
          This is a symbol specifying the logging level: ‘quiet’,
          ‘fatal’, ‘error’, ‘info’, ‘verbose’, ‘debug’, etc.  See the
          man page for ‘sshd_config’ for the full list of level names.

     ‘extra-content’ (default: ‘""’)
          This field can be used to append arbitrary text to the
          configuration file.  It is especially useful for elaborate
          configurations that cannot be expressed otherwise.  This
          configuration, for example, would generally disable root
          logins, but permit them from one specific IP address:

               (openssh-configuration
                 (extra-content "\
               Match Address 192.168.0.1
                 PermitRootLogin yes"))

 -- Scheme Procedure: dropbear-service [CONFIG]
     Run the Dropbear SSH daemon
     (https://matt.ucc.asn.au/dropbear/dropbear.html) with the given
     CONFIG, a ‘<dropbear-configuration>’ object.

     For example, to specify a Dropbear service listening on port 1234,
     add this call to the operating system’s ‘services’ field:

          (dropbear-service (dropbear-configuration
                              (port-number 1234)))

 -- Data Type: dropbear-configuration
     This data type represents the configuration of a Dropbear SSH
     daemon.

     ‘dropbear’ (default: DROPBEAR)
          The Dropbear package to use.

     ‘port-number’ (default: 22)
          The TCP port where the daemon waits for incoming connections.

     ‘syslog-output?’ (default: ‘#t’)
          Whether to enable syslog output.

     ‘pid-file’ (default: ‘"/var/run/dropbear.pid"’)
          File name of the daemon’s PID file.

     ‘root-login?’ (default: ‘#f’)
          Whether to allow ‘root’ logins.

     ‘allow-empty-passwords?’ (default: ‘#f’)
          Whether to allow empty passwords.

     ‘password-authentication?’ (default: ‘#t’)
          Whether to enable password-based authentication.

 -- Scheme Variable: autossh-service-type
     This is the type for the AutoSSH
     (https://www.harding.motd.ca/autossh) program that runs a copy of
     ‘ssh’ and monitors it, restarting it as necessary should it die or
     stop passing traffic.  AutoSSH can be run manually from the
     command-line by passing arguments to the binary ‘autossh’ from the
     package ‘autossh’, but it can also be run as a Guix service.  This
     latter use case is documented here.

     AutoSSH can be used to forward local traffic to a remote machine
     using an SSH tunnel, and it respects the ‘~/.ssh/config’ of the
     user it is run as.

     For example, to specify a service running autossh as the user
     ‘pino’ and forwarding all local connections to port ‘8081’ to
     ‘remote:8081’ using an SSH tunnel, add this call to the operating
     system’s ‘services’ field:

          (service autossh-service-type
                   (autossh-configuration
                    (user "pino")
                    (ssh-options (list "-T" "-N" "-L" "8081:localhost:8081" "remote.net"))))

 -- Data Type: autossh-configuration
     This data type represents the configuration of an AutoSSH service.

     ‘user’ (default ‘"autossh"’)
          The user as which the AutoSSH service is to be run.  This
          assumes that the specified user exists.

     ‘poll’ (default ‘600’)
          Specifies the connection poll time in seconds.

     ‘first-poll’ (default ‘#f’)
          Specifies how many seconds AutoSSH waits before the first
          connection test.  After this first test, polling is resumed at
          the pace defined in ‘poll’.  When set to ‘#f’, the first poll
          is not treated specially and will also use the connection poll
          specified in ‘poll’.

     ‘gate-time’ (default ‘30’)
          Specifies how many seconds an SSH connection must be active
          before it is considered successful.

     ‘log-level’ (default ‘1’)
          The log level, corresponding to the levels used by syslog—so
          ‘0’ is the most silent while ‘7’ is the chattiest.

     ‘max-start’ (default ‘#f’)
          The maximum number of times SSH may be (re)started before
          AutoSSH exits.  When set to ‘#f’, no maximum is configured and
          AutoSSH may restart indefinitely.

     ‘message’ (default ‘""’)
          The message to append to the echo message sent when testing
          connections.

     ‘port’ (default ‘"0"’)
          The ports used for monitoring the connection.  When set to
          ‘"0"’, monitoring is disabled.  When set to ‘"N"’ where N is a
          positive integer, ports N and N+1 are used for monitoring the
          connection, such that port N is the base monitoring port and
          ‘n+1’ is the echo port.  When set to ‘"N:M"’ where N and M are
          positive integers, the ports N and M are used for monitoring
          the connection, such that port N is the base monitoring port
          and M is the echo port.

     ‘ssh-options’ (default ‘'()’)
          The list of command-line arguments to pass to ‘ssh’ when it is
          run.  Options ‘-f’ and ‘-M’ are reserved for AutoSSH and may
          cause undefined behaviour.

 -- Scheme Variable: webssh-service-type
     This is the type for the WebSSH (https://webssh.huashengdun.org/)
     program that runs a web SSH client.  WebSSH can be run manually
     from the command-line by passing arguments to the binary ‘wssh’
     from the package ‘webssh’, but it can also be run as a Guix
     service.  This latter use case is documented here.

     For example, to specify a service running WebSSH on loopback
     interface on port ‘8888’ with reject policy with a list of allowed
     to connection hosts, and NGINX as a reverse-proxy to this service
     listening for HTTPS connection, add this call to the operating
     system’s ‘services’ field:

          (service webssh-service-type
            (webssh-configuration (address "127.0.0.1")
                                  (port 8888)
                                  (policy 'reject)
                                  (known-hosts '("localhost ecdsa-sha2-nistp256 AAAA…"
                                                 "127.0.0.1 ecdsa-sha2-nistp256 AAAA…"))))

          (service nginx-service-type
                   (nginx-configuration
                    (server-blocks
                     (list
                      (nginx-server-configuration
                       (inherit %webssh-configuration-nginx)
                       (server-name '("webssh.example.com"))
                       (listen '("443 ssl"))
                       (ssl-certificate (letsencrypt-certificate "webssh.example.com"))
                       (ssl-certificate-key (letsencrypt-key "webssh.example.com"))
                       (locations
                        (cons (nginx-location-configuration
                               (uri "/.well-known")
                               (body '("root /var/www;")))
                              (nginx-server-configuration-locations %webssh-configuration-nginx))))))))

 -- Data Type: webssh-configuration
     Data type representing the configuration for ‘webssh-service’.

     ‘package’ (default: WEBSSH)
          ‘webssh’ package to use.

     ‘user-name’ (default: "WEBSSH")
          User name or user ID that file transfers to and from that
          module should take place.

     ‘group-name’ (default: "WEBSSH")
          Group name or group ID that will be used when accessing the
          module.

     ‘address’ (default: #F)
          IP address on which ‘webssh’ listens for incoming connections.

     ‘port’ (default: 8888)
          TCP port on which ‘webssh’ listens for incoming connections.

     ‘policy’ (default: #F)
          Connection policy.  REJECT policy requires to specify
          KNOWN-HOSTS.

     ‘known-hosts’ (default: ’())
          List of hosts which allowed for SSH connection from ‘webssh’.

     ‘log-file’ (default: ‘"/var/log/webssh.log"’)
          Name of the file where ‘webssh’ writes its log file.

     ‘log-level’ (default: #F)
          Logging level.

 -- Scheme Variable: %facebook-host-aliases
     This variable contains a string for use in ‘/etc/hosts’ (*note
     (libc)Host Names::).  Each line contains a entry that maps a known
     server name of the Facebook on-line service—e.g.,
     ‘www.facebook.com’—to the local host—‘127.0.0.1’ or its IPv6
     equivalent, ‘::1’.

     This variable is typically used in the ‘hosts-file’ field of an
     ‘operating-system’ declaration (*note ‘/etc/hosts’:
     operating-system Reference.):

          (use-modules (gnu) (guix))

          (operating-system
            (host-name "mymachine")
            ;; ...
            (hosts-file
              ;; Create a /etc/hosts file with aliases for "localhost"
              ;; and "mymachine", as well as for Facebook servers.
              (plain-file "hosts"
                          (string-append (local-host-aliases host-name)
                                         %facebook-host-aliases))))

     This mechanism can prevent programs running locally, such as Web
     browsers, from accessing Facebook.

   The ‘(gnu services avahi)’ provides the following definition.

 -- Scheme Variable: avahi-service-type
     This is the service that runs ‘avahi-daemon’, a system-wide
     mDNS/DNS-SD responder that allows for service discovery and
     “zero-configuration” host name lookups (see <https://avahi.org/>).
     Its value must be an ‘avahi-configuration’ record—see below.

     This service extends the name service cache daemon (nscd) so that
     it can resolve ‘.local’ host names using nss-mdns
     (https://0pointer.de/lennart/projects/nss-mdns/).  *Note Name
     Service Switch::, for information on host name resolution.

     Additionally, add the AVAHI package to the system profile so that
     commands such as ‘avahi-browse’ are directly usable.

 -- Data Type: avahi-configuration
     Data type representation the configuration for Avahi.

     ‘host-name’ (default: ‘#f’)
          If different from ‘#f’, use that as the host name to publish
          for this machine; otherwise, use the machine’s actual host
          name.

     ‘publish?’ (default: ‘#t’)
          When true, allow host names and services to be published
          (broadcast) over the network.

     ‘publish-workstation?’ (default: ‘#t’)
          When true, ‘avahi-daemon’ publishes the machine’s host name
          and IP address via mDNS on the local network.  To view the
          host names published on your local network, you can run:

               avahi-browse _workstation._tcp

     ‘wide-area?’ (default: ‘#f’)
          When true, DNS-SD over unicast DNS is enabled.

     ‘ipv4?’ (default: ‘#t’)
     ‘ipv6?’ (default: ‘#t’)
          These fields determine whether to use IPv4/IPv6 sockets.

     ‘domains-to-browse’ (default: ‘'()’)
          This is a list of domains to browse.

 -- Scheme Variable: openvswitch-service-type
     This is the type of the Open vSwitch (https://www.openvswitch.org)
     service, whose value should be an ‘openvswitch-configuration’
     object.

 -- Data Type: openvswitch-configuration
     Data type representing the configuration of Open vSwitch, a
     multilayer virtual switch which is designed to enable massive
     network automation through programmatic extension.

     ‘package’ (default: OPENVSWITCH)
          Package object of the Open vSwitch.

 -- Scheme Variable: pagekite-service-type
     This is the service type for the PageKite (https://pagekite.net)
     service, a tunneling solution for making localhost servers publicly
     visible, even from behind restrictive firewalls or NAT without
     forwarded ports.  The value for this service type is a
     ‘pagekite-configuration’ record.

     Here’s an example exposing the local HTTP and SSH daemons:

          (service pagekite-service-type
                   (pagekite-configuration
                     (kites '("http:@kitename:localhost:80:@kitesecret"
                              "raw/22:@kitename:localhost:22:@kitesecret"))
                     (extra-file "/etc/pagekite.rc")))

 -- Data Type: pagekite-configuration
     Data type representing the configuration of PageKite.

     ‘package’ (default: PAGEKITE)
          Package object of PageKite.

     ‘kitename’ (default: ‘#f’)
          PageKite name for authenticating to the frontend server.

     ‘kitesecret’ (default: ‘#f’)
          Shared secret for authenticating to the frontend server.  You
          should probably put this inside ‘extra-file’ instead.

     ‘frontend’ (default: ‘#f’)
          Connect to the named PageKite frontend server instead of the
          pagekite.net service.

     ‘kites’ (default: ‘'("http:@kitename:localhost:80:@kitesecret")’)
          List of service kites to use.  Exposes HTTP on port 80 by
          default.  The format is ‘proto:kitename:host:port:secret’.

     ‘extra-file’ (default: ‘#f’)
          Extra configuration file to read, which you are expected to
          create manually.  Use this to add additional options and
          manage shared secrets out-of-band.

 -- Scheme Variable: yggdrasil-service-type
     The service type for connecting to the Yggdrasil network
     (https://yggdrasil-network.github.io/), an early-stage
     implementation of a fully end-to-end encrypted IPv6 network.

          Yggdrasil provides name-independent routing with
          cryptographically generated addresses.  Static addressing
          means you can keep the same address as long as you want, even
          if you move to a new location, or generate a new address (by
          generating new keys) whenever you want.
          <https://yggdrasil-network.github.io/2018/07/28/addressing.html>

     Pass it a value of ‘yggdrasil-configuration’ to connect it to
     public peers and/or local peers.

     Here is an example using public peers and a static address.  The
     static signing and encryption keys are defined in
     ‘/etc/yggdrasil-private.conf’ (the default value for
     ‘config-file’).

          ;; part of the operating-system declaration
          (service yggdrasil-service-type
                        (yggdrasil-configuration
                         (autoconf? #f) ;; use only the public peers
                         (json-config
                         ;; choose one from
                         ;; https://github.com/yggdrasil-network/public-peers
                          '((peers . #("tcp://1.2.3.4:1337"))))
                         ;; /etc/yggdrasil-private.conf is the default value for config-file
                         ))
          # sample content for /etc/yggdrasil-private.conf
          {
            # Your public key. Your peers may ask you for this to put
            # into their AllowedPublicKeys configuration.
            PublicKey: 64277...

            # Your private key. DO NOT share this with anyone!
            PrivateKey: 5c750...
          }

 -- Data Type: yggdrasil-configuration
     Data type representing the configuration of Yggdrasil.

     ‘package’ (default: ‘yggdrasil’)
          Package object of Yggdrasil.

     ‘json-config’ (default: ‘'()’)
          Contents of ‘/etc/yggdrasil.conf’.  Will be merged with
          ‘/etc/yggdrasil-private.conf’.  Note that these settings are
          stored in the Guix store, which is readable to all users.  *Do
          not store your private keys in it*.  See the output of
          ‘yggdrasil -genconf’ for a quick overview of valid keys and
          their default values.

     ‘autoconf?’ (default: ‘#f’)
          Whether to use automatic mode.  Enabling it makes Yggdrasil
          use adynamic IP and peer with IPv6 neighbors.

     ‘log-level’ (default: ‘'info’)
          How much detail to include in logs.  Use ‘'debug’ for more
          detail.

     ‘log-to’ (default: ‘'stdout’)
          Where to send logs.  By default, the service logs standard
          output to ‘/var/log/yggdrasil.log’.  The alternative is
          ‘'syslog’, which sends output to the running syslog service.

     ‘config-file’ (default: ‘"/etc/yggdrasil-private.conf"’)
          What HJSON file to load sensitive data from.  This is where
          private keys should be stored, which are necessary to specify
          if you don’t want a randomized address after each restart.
          Use ‘#f’ to disable.  Options defined in this file take
          precedence over ‘json-config’.  Use the output of ‘yggdrasil
          -genconf’ as a starting point.  To configure a static address,
          delete everything except these options:

             • ‘EncryptionPublicKey’
             • ‘EncryptionPrivateKey’
             • ‘SigningPublicKey’
             • ‘SigningPrivateKey’

 -- Scheme Variable: ipfs-service-type
     The service type for connecting to the IPFS network
     (https://ipfs.io), a global, versioned, peer-to-peer file system.
     Pass it a ‘ipfs-configuration’ to change the ports used for the
     gateway and API.

     Here’s an example configuration, using some non-standard ports:

          (service ipfs-service-type
                   (ipfs-configuration
                    (gateway "/ip4/127.0.0.1/tcp/8880")
                    (api "/ip4/127.0.0.1/tcp/8881")))

 -- Data Type: ipfs-configuration
     Data type representing the configuration of IPFS.

     ‘package’ (default: ‘go-ipfs’)
          Package object of IPFS.

     ‘gateway’ (default: ‘"/ip4/127.0.0.1/tcp/8082"’)
          Address of the gateway, in ‘multiaddress’ format.

     ‘api’ (default: ‘"/ip4/127.0.0.1/tcp/5001"’)
          Address of the API endpoint, in ‘multiaddress’ format.

 -- Scheme Variable: keepalived-service-type
     This is the type for the Keepalived (https://www.keepalived.org/)
     routing software, ‘keepalived’.  Its value must be an
     ‘keepalived-configuration’ record as in this example for master
     machine:

          (service keepalived-service-type
                   (keepalived-configuration
                     (config-file (local-file "keepalived-master.conf"))))

     where ‘keepalived-master.conf’:

          vrrp_instance my-group {
            state MASTER
            interface enp9s0
            virtual_router_id 100
            priority 100
            unicast_peer { 10.0.0.2 }
            virtual_ipaddress {
              10.0.0.4/24
            }
          }

     and for backup machine:

          (service keepalived-service-type
                   (keepalived-configuration
                    (config-file (local-file "keepalived-backup.conf"))))

     where ‘keepalived-backup.conf’:

          vrrp_instance my-group {
            state BACKUP
            interface enp9s0
            virtual_router_id 100
            priority 99
            unicast_peer { 10.0.0.3 }
            virtual_ipaddress {
              10.0.0.4/24
            }
          }


File: guix.info,  Node: Unattended Upgrades,  Next: X Window,  Prev: Networking Services,  Up: Services

12.9.6 Unattended Upgrades
--------------------------

Guix provides a service to perform _unattended upgrades_: periodically,
the system automatically reconfigures itself from the latest Guix.  Guix
System has several properties that make unattended upgrades safe:

   • upgrades are transactional (either the upgrade succeeds or it
     fails, but you cannot end up with an “in-between” system state);
   • the upgrade log is kept—you can view it with ‘guix system
     list-generations’—and you can roll back to any previous generation,
     should the upgraded system fail to behave as intended;
   • channel code is authenticated so you know you can only run genuine
     code (*note Channels::);
   • ‘guix system reconfigure’ prevents downgrades, which makes it
     immune to “downgrade attacks”.

   To set up unattended upgrades, add an instance of
‘unattended-upgrade-service-type’ like the one below to the list of your
operating system services:

     (service unattended-upgrade-service-type)

   The defaults above set up weekly upgrades: every Sunday at midnight.
You do not need to provide the operating system configuration file: it
uses ‘/run/current-system/configuration.scm’, which ensures it always
uses your latest configuration—*note provenance-service-type::, for more
information about this file.

   There are several things that can be configured, in particular the
periodicity and services (daemons) to be restarted upon completion.
When the upgrade is successful, the service takes care of deleting
system generations older that some threshold, as per ‘guix system
delete-generations’.  See the reference below for details.

   To ensure that upgrades are actually happening, you can run ‘guix
system describe’.  To investigate upgrade failures, visit the unattended
upgrade log file (see below).

 -- Scheme Variable: unattended-upgrade-service-type
     This is the service type for unattended upgrades.  It sets up an
     mcron job (*note Scheduled Job Execution::) that runs ‘guix system
     reconfigure’ from the latest version of the specified channels.

     Its value must be a ‘unattended-upgrade-configuration’ record (see
     below).

 -- Data Type: unattended-upgrade-configuration
     This data type represents the configuration of the unattended
     upgrade service.  The following fields are available:

     ‘schedule’ (default: ‘"30 01 * * 0"’)
          This is the schedule of upgrades, expressed as a gexp
          containing an mcron job schedule (*note mcron job
          specifications: (mcron)Guile Syntax.).

     ‘channels’ (default: ‘#~%default-channels’)
          This gexp specifies the channels to use for the upgrade (*note
          Channels::).  By default, the tip of the official ‘guix’
          channel is used.

     ‘operating-system-file’ (default: ‘"/run/current-system/configuration.scm"’)
          This field specifies the operating system configuration file
          to use.  The default is to reuse the config file of the
          current configuration.

          There are cases, though, where referring to
          ‘/run/current-system/configuration.scm’ is not enough, for
          instance because that file refers to extra files (SSH public
          keys, extra configuration files, etc.)  via ‘local-file’ and
          similar constructs.  For those cases, we recommend something
          along these lines:

               (unattended-upgrade-configuration
                 (operating-system-file
                   (file-append (local-file "." "config-dir" #:recursive? #t)
                                "/config.scm")))

          The effect here is to import all of the current directory into
          the store, and to refer to ‘config.scm’ within that directory.
          Therefore, uses of ‘local-file’ within ‘config.scm’ will work
          as expected.  *Note G-Expressions::, for information about
          ‘local-file’ and ‘file-append’.

     ‘services-to-restart’ (default: ‘'(mcron)’)
          This field specifies the Shepherd services to restart when the
          upgrade completes.

          Those services are restarted right away upon completion, as
          with ‘herd restart’, which ensures that the latest version is
          running—remember that by default ‘guix system reconfigure’
          only restarts services that are not currently running, which
          is conservative: it minimizes disruption but leaves outdated
          services running.

          Use ‘herd status’ to find out candidates for restarting.
          *Note Services::, for general information about services.
          Common services to restart would include ‘ntpd’ and
          ‘ssh-daemon’.

          By default, the ‘mcron’ service is restarted.  This ensures
          that the latest version of the unattended upgrade job will be
          used next time.

     ‘system-expiration’ (default: ‘(* 3 30 24 3600)’)
          This is the expiration time in seconds for system generations.
          System generations older that this amount of time are deleted
          with ‘guix system delete-generations’ when an upgrade
          completes.

               Note: The unattended upgrade service does not run the
               garbage collector.  You will probably want to set up your
               own mcron job to run ‘guix gc’ periodically.

     ‘maximum-duration’ (default: ‘3600’)
          Maximum duration in seconds for the upgrade; past that time,
          the upgrade aborts.

          This is primarily useful to ensure the upgrade does not end up
          rebuilding or re-downloading “the world”.

     ‘log-file’ (default: ‘"/var/log/unattended-upgrade.log"’)
          File where unattended upgrades are logged.


File: guix.info,  Node: X Window,  Next: Printing Services,  Prev: Unattended Upgrades,  Up: Services

12.9.7 X Window
---------------

Support for the X Window graphical display system—specifically Xorg—is
provided by the ‘(gnu services xorg)’ module.  Note that there is no
‘xorg-service’ procedure.  Instead, the X server is started by the
“login manager”, by default the GNOME Display Manager (GDM).

   GDM of course allows users to log in into window managers and desktop
environments other than GNOME; for those using GNOME, GDM is required
for features such as automatic screen locking.

   To use X11, you must install at least one “window manager”—for
example the ‘windowmaker’ or ‘openbox’ packages—preferably by adding it
to the ‘packages’ field of your operating system definition (*note
system-wide packages: operating-system Reference.).

   GDM also supports Wayland: it can itself use Wayland instead of X11
for its user interface, and it can also start Wayland sessions.  The
former is required for the latter, to enable, set ‘wayland?’ to ‘#t’ in
‘gdm-configuration’.

 -- Scheme Variable: gdm-service-type
     This is the type for the GNOME Desktop Manager
     (https://wiki.gnome.org/Projects/GDM/) (GDM), a program that
     manages graphical display servers and handles graphical user
     logins.  Its value must be a ‘gdm-configuration’ (see below).

     GDM looks for “session types” described by the ‘.desktop’ files in
     ‘/run/current-system/profile/share/xsessions’ (for X11 sessions)
     and ‘/run/current-system/profile/share/wayland-sessions’ (for
     Wayland sessions) and allows users to choose a session from the
     log-in screen.  Packages such as ‘gnome’, ‘xfce’, ‘i3’ and ‘sway’
     provide ‘.desktop’ files; adding them to the system-wide set of
     packages automatically makes them available at the log-in screen.

     In addition, ‘~/.xsession’ files are honored.  When available,
     ‘~/.xsession’ must be an executable that starts a window manager
     and/or other X clients.

 -- Data Type: gdm-configuration
     ‘auto-login?’ (default: ‘#f’)
     ‘default-user’ (default: ‘#f’)
          When ‘auto-login?’ is false, GDM presents a log-in screen.

          When ‘auto-login?’ is true, GDM logs in directly as
          ‘default-user’.

     ‘auto-suspend?’ (default ‘#t’)
          When true, GDM will automatically suspend to RAM when nobody
          is physically connected.  When a machine is used via remote
          desktop or SSH, this should be set to false to avoid GDM
          interrupting remote sessions or rendering the machine
          unavailable.

     ‘debug?’ (default: ‘#f’)
          When true, GDM writes debug messages to its log.

     ‘gnome-shell-assets’ (default: ...)
          List of GNOME Shell assets needed by GDM: icon theme, fonts,
          etc.

     ‘xorg-configuration’ (default: ‘(xorg-configuration)’)
          Configuration of the Xorg graphical server.

     ‘x-session’ (default: ‘(xinitrc)’)
          Script to run before starting a X session.

     ‘xdmcp?’ (default: ‘#f’)
          When true, enable the X Display Manager Control Protocol
          (XDMCP). This should only be enabled in trusted environments,
          as the protocol is not secure.  When enabled, GDM listens for
          XDMCP queries on the UDP port 177.

     ‘dbus-daemon’ (default: ‘dbus-daemon-wrapper’)
          File name of the ‘dbus-daemon’ executable.

     ‘gdm’ (default: ‘gdm’)
          The GDM package to use.

     ‘wayland?’ (default: ‘#f’)
          When true, enables Wayland in GDM, necessary to use Wayland
          sessions.

     ‘wayland-session’ (default: ‘gdm-wayland-session-wrapper’)
          The Wayland session wrapper to use, needed to setup the
          environment.

 -- Scheme Variable: slim-service-type
     This is the type for the SLiM graphical login manager for X11.

     Like GDM, SLiM looks for session types described by ‘.desktop’
     files and allows users to choose a session from the log-in screen
     using ‘F1’.  It also honors ‘~/.xsession’ files.

     Unlike GDM, SLiM does not spawn the user session on a different VT
     after logging in, which means that you can only start one graphical
     session.  If you want to be able to run multiple graphical sessions
     at the same time you have to add multiple SLiM services to your
     system services.  The following example shows how to replace the
     default GDM service with two SLiM services on tty7 and tty8.

          (use-modules (gnu services)
                       (gnu services desktop)
                       (gnu services xorg))

          (operating-system
            ;; ...
            (services (cons* (service slim-service-type (slim-configuration
                                                         (display ":0")
                                                         (vt "vt7")))
                             (service slim-service-type (slim-configuration
                                                         (display ":1")
                                                         (vt "vt8")))
                             (modify-services %desktop-services
                               (delete gdm-service-type)))))

 -- Data Type: slim-configuration
     Data type representing the configuration of ‘slim-service-type’.

     ‘allow-empty-passwords?’ (default: ‘#t’)
          Whether to allow logins with empty passwords.

     ‘gnupg?’ (default: ‘#f’)
          If enabled, ‘pam-gnupg’ will attempt to automatically unlock
          the user’s GPG keys with the login password via ‘gpg-agent’.
          The keygrips of all keys to be unlocked should be written to
          ‘~/.pam-gnupg’, and can be queried with ‘gpg -K
          --with-keygrip’.  Presetting passphrases must be enabled by
          adding ‘allow-preset-passphrase’ in ‘~/.gnupg/gpg-agent.conf’.

     ‘auto-login?’ (default: ‘#f’)
     ‘default-user’ (default: ‘""’)
          When ‘auto-login?’ is false, SLiM presents a log-in screen.

          When ‘auto-login?’ is true, SLiM logs in directly as
          ‘default-user’.

     ‘theme’ (default: ‘%default-slim-theme’)
     ‘theme-name’ (default: ‘%default-slim-theme-name’)
          The graphical theme to use and its name.

     ‘auto-login-session’ (default: ‘#f’)
          If true, this must be the name of the executable to start as
          the default session—e.g., ‘(file-append windowmaker
          "/bin/windowmaker")’.

          If false, a session described by one of the available
          ‘.desktop’ files in ‘/run/current-system/profile’ and
          ‘~/.guix-profile’ will be used.

               Note: You must install at least one window manager in the
               system profile or in your user profile.  Failing to do
               that, if ‘auto-login-session’ is false, you will be
               unable to log in.

     ‘xorg-configuration’ (default ‘(xorg-configuration)’)
          Configuration of the Xorg graphical server.

     ‘display’ (default ‘":0"’)
          The display on which to start the Xorg graphical server.

     ‘vt’ (default ‘"vt7"’)
          The VT on which to start the Xorg graphical server.

     ‘xauth’ (default: ‘xauth’)
          The XAuth package to use.

     ‘shepherd’ (default: ‘shepherd’)
          The Shepherd package used when invoking ‘halt’ and ‘reboot’.

     ‘sessreg’ (default: ‘sessreg’)
          The sessreg package used in order to register the session.

     ‘slim’ (default: ‘slim’)
          The SLiM package to use.

 -- Scheme Variable: %default-theme
 -- Scheme Variable: %default-theme-name
     The default SLiM theme and its name.

 -- Scheme Variable: sddm-service-type
     This is the type of the service to run the SDDM display manager
     (https://github.com/sddm/sddm).  Its value must be a
     ‘sddm-configuration’ record (see below).

     Here’s an example use:

          (service sddm-service-type
                   (sddm-configuration
                     (auto-login-user "alice")
                     (auto-login-session "xfce.desktop")))

 -- Data Type: sddm-configuration
     This data type represents the configuration of the SDDM login
     manager.  The available fields are:

     ‘sddm’ (default: ‘sddm’)
          The SDDM package to use.

     ‘display-server’ (default: "x11")
          Select display server to use for the greeter.  Valid values
          are ‘"x11"’ or ‘"wayland"’.

     ‘numlock’ (default: "on")
          Valid values are ‘"on"’, ‘"off"’ or ‘"none"’.

     ‘halt-command’ (default ‘#~(string-append #$shepherd "/sbin/halt")’)
          Command to run when halting.

     ‘reboot-command’ (default ‘#~(string-append #$shepherd "/sbin/reboot")’)
          Command to run when rebooting.

     ‘theme’ (default "maldives")
          Theme to use.  Default themes provided by SDDM are ‘"elarun"’,
          ‘"maldives"’ or ‘"maya"’.

     ‘themes-directory’ (default "/run/current-system/profile/share/sddm/themes")
          Directory to look for themes.

     ‘faces-directory’ (default "/run/current-system/profile/share/sddm/faces")
          Directory to look for faces.

     ‘default-path’ (default "/run/current-system/profile/bin")
          Default PATH to use.

     ‘minimum-uid’ (default: 1000)
          Minimum UID displayed in SDDM and allowed for log-in.

     ‘maximum-uid’ (default: 2000)
          Maximum UID to display in SDDM.

     ‘remember-last-user?’ (default #t)
          Remember last user.

     ‘remember-last-session?’ (default #t)
          Remember last session.

     ‘hide-users’ (default "")
          Usernames to hide from SDDM greeter.

     ‘hide-shells’ (default ‘#~(string-append #$shadow "/sbin/nologin")’)
          Users with shells listed will be hidden from the SDDM greeter.

     ‘session-command’ (default ‘#~(string-append #$sddm "/share/sddm/scripts/wayland-session")’)
          Script to run before starting a wayland session.

     ‘sessions-directory’ (default "/run/current-system/profile/share/wayland-sessions")
          Directory to look for desktop files starting wayland sessions.

     ‘xorg-configuration’ (default ‘(xorg-configuration)’)
          Configuration of the Xorg graphical server.

     ‘xauth-path’ (default ‘#~(string-append #$xauth "/bin/xauth")’)
          Path to xauth.

     ‘xephyr-path’ (default ‘#~(string-append #$xorg-server "/bin/Xephyr")’)
          Path to Xephyr.

     ‘xdisplay-start’ (default ‘#~(string-append #$sddm "/share/sddm/scripts/Xsetup")’)
          Script to run after starting xorg-server.

     ‘xdisplay-stop’ (default ‘#~(string-append #$sddm "/share/sddm/scripts/Xstop")’)
          Script to run before stopping xorg-server.

     ‘xsession-command’ (default: ‘xinitrc’)
          Script to run before starting a X session.

     ‘xsessions-directory’ (default: "/run/current-system/profile/share/xsessions")
          Directory to look for desktop files starting X sessions.

     ‘minimum-vt’ (default: 7)
          Minimum VT to use.

     ‘auto-login-user’ (default "")
          User account that will be automatically logged in.  Setting
          this to the empty string disables auto-login.

     ‘auto-login-session’ (default "")
          The ‘.desktop’ file name to use as the auto-login session, or
          the empty string.

     ‘relogin?’ (default #f)
          Relogin after logout.

 -- Scheme Variable: lightdm-service-type
     This is the type of the service to run the LightDM display manager
     (https://github.com/canonical/lightdm).  Its value must be a
     ‘lightdm-configuration’ record, which is documented below.  Among
     its distinguishing features are TigerVNC integration for easily
     remoting your desktop as well as support for the XDMCP protocol,
     which can be used by remote clients to start a session from the
     login manager.

     In its most basic form, it can be used simply as:

          (service lightdm-service-type)

     A more elaborate example making use of the VNC capabilities and
     enabling more features and verbose logs could look like:

          (service lightdm-service-type
                   (lightdm-configuration
                    (allow-empty-passwords? #t)
                    (xdmcp? #t)
                    (vnc-server? #t)
                    (vnc-server-command
                     (file-append tigervnc-server "/bin/Xvnc"
                                  "  -SecurityTypes None"))
                    (seats
                     (list (lightdm-seat-configuration
                            (name "*")
                            (user-session "ratpoison"))))))

 -- Data Type: lightdm-configuration
     Available ‘lightdm-configuration’ fields are:

     ‘lightdm’ (default: ‘lightdm’) (type: file-like)
          The lightdm package to use.

     ‘allow-empty-passwords?’ (default: ‘#f’) (type: boolean)
          Whether users not having a password set can login.

     ‘debug?’ (default: ‘#f’) (type: boolean)
          Enable verbose output.

     ‘xorg-configuration’ (type: xorg-configuration)
          The default Xorg server configuration to use to generate the
          Xorg server start script.  It can be refined per seat via the
          ‘xserver-command’ of the ‘<lightdm-seat-configuration>’
          record, if desired.

     ‘greeters’ (type: list-of-greeter-configurations)
          The LightDM greeter configurations specifying the greeters to
          use.

     ‘seats’ (type: list-of-seat-configurations)
          The seat configurations to use.  A LightDM seat is akin to a
          user.

     ‘xdmcp?’ (default: ‘#f’) (type: boolean)
          Whether a XDMCP server should listen on port UDP 177.

     ‘xdmcp-listen-address’ (type: maybe-string)
          The host or IP address the XDMCP server listens for incoming
          connections.  When unspecified, listen on for any hosts/IP
          addresses.

     ‘vnc-server?’ (default: ‘#f’) (type: boolean)
          Whether a VNC server is started.

     ‘vnc-server-command’ (type: file-like)
          The Xvnc command to use for the VNC server, it’s possible to
          provide extra options not otherwise exposed along the command,
          for example to disable security:

               (vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
                                                " -SecurityTypes None" ))

          Or to set a PasswordFile for the classic (unsecure) VncAuth
          mecanism:

               (vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
                                                " -PasswordFile /var/lib/lightdm/.vnc/passwd"))

          The password file should be manually created using the
          ‘vncpasswd’ command.  Note that LightDM will create new
          sessions for VNC users, which means they need to authenticate
          in the same way as local users would.

     ‘vnc-server-listen-address’ (type: maybe-string)
          The host or IP address the VNC server listens for incoming
          connections.  When unspecified, listen for any hosts/IP
          addresses.

     ‘vnc-server-port’ (default: ‘5900’) (type: number)
          The TCP port the VNC server should listen to.

     ‘extra-config’ (default: ‘()’) (type: list-of-strings)
          Extra configuration values to append to the LightDM
          configuration file.

 -- Data Type: lightdm-gtk-greeter-configuration
     Available ‘lightdm-gtk-greeter-configuration’ fields are:

     ‘lightdm-gtk-greeter’ (default: ‘lightdm-gtk-greeter’) (type: file-like)
          The lightdm-gtk-greeter package to use.

     ‘assets’  
          (default: ‘(adwaita-icon-theme
          gnome-themes-extrahicolor-icon-theme)’)  (type:
          list-of-file-likes) The list of packages complementing the
          greeter, such as package providing icon themes.

     ‘theme-name’ (default: ‘"Adwaita"’) (type: string)
          The name of the theme to use.

     ‘icon-theme-name’ (default: ‘"Adwaita"’) (type: string)
          The name of the icon theme to use.

     ‘cursor-theme-name’ (default: ‘"Adwaita"’) (type: string)
          The name of the cursor theme to use.

     ‘cursor-theme-size’ (default: ‘16’) (type: number)
          The size to use for the cursor theme.

     ‘allow-debugging?’ (type: maybe-boolean)
          Set to #t to enable debug log level.

     ‘background’ (type: file-like)
          The background image to use.

     ‘at-spi-enabled?’ (default: ‘#f’) (type: boolean)
          Enable accessibility support through the Assistive Technology
          Service Provider Interface (AT-SPI).

     ‘a11y-states’  
          (default: ‘(contrast font keyboard reader)’) (type:
          list-of-a11y-states) The accessibility features to enable,
          given as list of symbols.

     ‘reader’ (type: maybe-file-like)
          The command to use to launch a screen reader.

     ‘extra-config’ (default: ‘()’) (type: list-of-strings)
          Extra configuration values to append to the LightDM GTK
          Greeter configuration file.

 -- Data Type: lightdm-seat-configuration
     Available ‘lightdm-seat-configuration’ fields are:

     ‘name’ (type: seat-name)
          The name of the seat.  An asterisk (*) can be used in the name
          to apply the seat configuration to all the seat names it
          matches.

     ‘user-session’ (type: maybe-string)
          The session to use by default.  The session name must be
          provided as a lowercase string, such as ‘"gnome"’,
          ‘"ratpoison"’, etc.

     ‘type’ (default: ‘local’) (type: seat-type)
          The type of the seat, either the ‘local’ or ‘xremote’ symbol.

     ‘autologin-user’ (type: maybe-string)
          The username to automatically log in with by default.

     ‘greeter-session’  
          (default: ‘lightdm-gtk-greeter’) (type: greeter-session) The
          greeter session to use, specified as a symbol.  Currently,
          only ‘lightdm-gtk-greeter’ is supported.

     ‘xserver-command’ (type: maybe-file-like)
          The Xorg server command to run.

     ‘session-wrapper’ (type: file-like)
          The xinitrc session wrapper to use.

     ‘extra-config’ (default: ‘()’) (type: list-of-strings)
          Extra configuration values to append to the seat configuration
          section.

 -- Data Type: xorg-configuration
     This data type represents the configuration of the Xorg graphical
     display server.  Note that there is no Xorg service; instead, the X
     server is started by a “display manager” such as GDM, SDDM, LightDM
     or SLiM.  Thus, the configuration of these display managers
     aggregates an ‘xorg-configuration’ record.

     ‘modules’ (default: ‘%default-xorg-modules’)
          This is a list of “module packages” loaded by the Xorg
          server—e.g., ‘xf86-video-vesa’, ‘xf86-input-keyboard’, and so
          on.

     ‘fonts’ (default: ‘%default-xorg-fonts’)
          This is a list of font directories to add to the server’s
          “font path”.

     ‘drivers’ (default: ‘'()’)
          This must be either the empty list, in which case Xorg chooses
          a graphics driver automatically, or a list of driver names
          that will be tried in this order—e.g., ‘("modesetting"
          "vesa")’.

     ‘resolutions’ (default: ‘'()’)
          When ‘resolutions’ is the empty list, Xorg chooses an
          appropriate screen resolution.  Otherwise, it must be a list
          of resolutions—e.g., ‘((1024 768) (640 480))’.

     ‘keyboard-layout’ (default: ‘#f’)
          If this is ‘#f’, Xorg uses the default keyboard layout—usually
          US English (“qwerty”) for a 105-key PC keyboard.

          Otherwise this must be a ‘keyboard-layout’ object specifying
          the keyboard layout in use when Xorg is running.  *Note
          Keyboard Layout::, for more information on how to specify the
          keyboard layout.

     ‘extra-config’ (default: ‘'()’)
          This is a list of strings or objects appended to the
          configuration file.  It is used to pass extra text to be added
          verbatim to the configuration file.

     ‘server’ (default: ‘xorg-server’)
          This is the package providing the Xorg server.

     ‘server-arguments’ (default: ‘%default-xorg-server-arguments’)
          This is the list of command-line arguments to pass to the X
          server.  The default is ‘-nolisten tcp’.

 -- Scheme Procedure: set-xorg-configuration CONFIG
          [LOGIN-MANAGER-SERVICE-TYPE]
     Tell the log-in manager (of type LOGIN-MANAGER-SERVICE-TYPE) to use
     CONFIG, an ‘<xorg-configuration>’ record.

     Since the Xorg configuration is embedded in the log-in manager’s
     configuration—e.g., ‘gdm-configuration’—this procedure provides a
     shorthand to set the Xorg configuration.

 -- Scheme Procedure: xorg-start-command [CONFIG]
     Return a ‘startx’ script in which the modules, fonts, etc.
     specified in CONFIG, are available.  The result should be used in
     place of ‘startx’.

     Usually the X server is started by a login manager.

 -- Scheme Procedure: screen-locker-service PACKAGE [PROGRAM]
     Add PACKAGE, a package for a screen locker or screen saver whose
     command is PROGRAM, to the set of setuid programs and add a PAM
     entry for it.  For example:

          (screen-locker-service xlockmore "xlock")

     makes the good ol’ XlockMore usable.


File: guix.info,  Node: Printing Services,  Next: Desktop Services,  Prev: X Window,  Up: Services

12.9.8 Printing Services
------------------------

The ‘(gnu services cups)’ module provides a Guix service definition for
the CUPS printing service.  To add printer support to a Guix system, add
a ‘cups-service’ to the operating system definition:

 -- Scheme Variable: cups-service-type
     The service type for the CUPS print server.  Its value should be a
     valid CUPS configuration (see below).  To use the default settings,
     simply write:
          (service cups-service-type)

   The CUPS configuration controls the basic things about your CUPS
installation: what interfaces it listens on, what to do if a print job
fails, how much logging to do, and so on.  To actually add a printer,
you have to visit the <http://localhost:631> URL, or use a tool such as
GNOME’s printer configuration services.  By default, configuring a CUPS
service will generate a self-signed certificate if needed, for secure
connections to the print server.

   Suppose you want to enable the Web interface of CUPS and also add
support for Epson printers via the ‘epson-inkjet-printer-escpr’ package
and for HP printers via the ‘hplip-minimal’ package.  You can do that
directly, like this (you need to use the ‘(gnu packages cups)’ module):

     (service cups-service-type
              (cups-configuration
                (web-interface? #t)
                (extensions
                  (list cups-filters epson-inkjet-printer-escpr hplip-minimal))))

     Note: If you wish to use the Qt5 based GUI which comes with the
     hplip package then it is suggested that you install the ‘hplip’
     package, either in your OS configuration file or as your user.

   The available configuration parameters follow.  Each parameter
definition is preceded by its type; for example, ‘string-list foo’
indicates that the ‘foo’ parameter should be specified as a list of
strings.  There is also a way to specify the configuration as a string,
if you have an old ‘cupsd.conf’ file that you want to port over from
some other system; see the end for more details.

   Available ‘cups-configuration’ fields are:

 -- ‘cups-configuration’ parameter: package cups
     The CUPS package.

 -- ‘cups-configuration’ parameter: package-list extensions (default:
          ‘(list brlaser cups-filters epson-inkjet-printer-escpr
          foomatic-filters hplip-minimal splix)’)
     Drivers and other extensions to the CUPS package.

 -- ‘cups-configuration’ parameter: files-configuration
          files-configuration
     Configuration of where to write logs, what directories to use for
     print spools, and related privileged configuration parameters.

     Available ‘files-configuration’ fields are:

      -- ‘files-configuration’ parameter: log-location access-log
          Defines the access log filename.  Specifying a blank filename
          disables access log generation.  The value ‘stderr’ causes log
          entries to be sent to the standard error file when the
          scheduler is running in the foreground, or to the system log
          daemon when run in the background.  The value ‘syslog’ causes
          log entries to be sent to the system log daemon.  The server
          name may be included in filenames using the string ‘%s’, as in
          ‘/var/log/cups/%s-access_log’.

          Defaults to ‘"/var/log/cups/access_log"’.

      -- ‘files-configuration’ parameter: file-name cache-dir
          Where CUPS should cache data.

          Defaults to ‘"/var/cache/cups"’.

      -- ‘files-configuration’ parameter: string config-file-perm
          Specifies the permissions for all configuration files that the
          scheduler writes.

          Note that the permissions for the printers.conf file are
          currently masked to only allow access from the scheduler user
          (typically root).  This is done because printer device URIs
          sometimes contain sensitive authentication information that
          should not be generally known on the system.  There is no way
          to disable this security feature.

          Defaults to ‘"0640"’.

      -- ‘files-configuration’ parameter: log-location error-log
          Defines the error log filename.  Specifying a blank filename
          disables error log generation.  The value ‘stderr’ causes log
          entries to be sent to the standard error file when the
          scheduler is running in the foreground, or to the system log
          daemon when run in the background.  The value ‘syslog’ causes
          log entries to be sent to the system log daemon.  The server
          name may be included in filenames using the string ‘%s’, as in
          ‘/var/log/cups/%s-error_log’.

          Defaults to ‘"/var/log/cups/error_log"’.

      -- ‘files-configuration’ parameter: string fatal-errors
          Specifies which errors are fatal, causing the scheduler to
          exit.  The kind strings are:

          ‘none’
               No errors are fatal.

          ‘all’
               All of the errors below are fatal.

          ‘browse’
               Browsing initialization errors are fatal, for example
               failed connections to the DNS-SD daemon.

          ‘config’
               Configuration file syntax errors are fatal.

          ‘listen’
               Listen or Port errors are fatal, except for IPv6 failures
               on the loopback or ‘any’ addresses.

          ‘log’
               Log file creation or write errors are fatal.

          ‘permissions’
               Bad startup file permissions are fatal, for example
               shared TLS certificate and key files with world-read
               permissions.

          Defaults to ‘"all -browse"’.

      -- ‘files-configuration’ parameter: boolean file-device?
          Specifies whether the file pseudo-device can be used for new
          printer queues.  The URI <file:///dev/null> is always allowed.

          Defaults to ‘#f’.

      -- ‘files-configuration’ parameter: string group
          Specifies the group name or ID that will be used when
          executing external programs.

          Defaults to ‘"lp"’.

      -- ‘files-configuration’ parameter: string log-file-group
          Specifies the group name or ID that will be used for log
          files.

          Defaults to ‘"lpadmin"’.

      -- ‘files-configuration’ parameter: string log-file-perm
          Specifies the permissions for all log files that the scheduler
          writes.

          Defaults to ‘"0644"’.

      -- ‘files-configuration’ parameter: log-location page-log
          Defines the page log filename.  Specifying a blank filename
          disables page log generation.  The value ‘stderr’ causes log
          entries to be sent to the standard error file when the
          scheduler is running in the foreground, or to the system log
          daemon when run in the background.  The value ‘syslog’ causes
          log entries to be sent to the system log daemon.  The server
          name may be included in filenames using the string ‘%s’, as in
          ‘/var/log/cups/%s-page_log’.

          Defaults to ‘"/var/log/cups/page_log"’.

      -- ‘files-configuration’ parameter: string remote-root
          Specifies the username that is associated with unauthenticated
          accesses by clients claiming to be the root user.  The default
          is ‘remroot’.

          Defaults to ‘"remroot"’.

      -- ‘files-configuration’ parameter: file-name request-root
          Specifies the directory that contains print jobs and other
          HTTP request data.

          Defaults to ‘"/var/spool/cups"’.

      -- ‘files-configuration’ parameter: sandboxing sandboxing
          Specifies the level of security sandboxing that is applied to
          print filters, backends, and other child processes of the
          scheduler; either ‘relaxed’ or ‘strict’.  This directive is
          currently only used/supported on macOS.

          Defaults to ‘strict’.

      -- ‘files-configuration’ parameter: file-name server-keychain
          Specifies the location of TLS certificates and private keys.
          CUPS will look for public and private keys in this directory:
          ‘.crt’ files for PEM-encoded certificates and corresponding
          ‘.key’ files for PEM-encoded private keys.

          Defaults to ‘"/etc/cups/ssl"’.

      -- ‘files-configuration’ parameter: file-name server-root
          Specifies the directory containing the server configuration
          files.

          Defaults to ‘"/etc/cups"’.

      -- ‘files-configuration’ parameter: boolean sync-on-close?
          Specifies whether the scheduler calls fsync(2) after writing
          configuration or state files.

          Defaults to ‘#f’.

      -- ‘files-configuration’ parameter: space-separated-string-list
               system-group
          Specifies the group(s) to use for ‘@SYSTEM’ group
          authentication.

      -- ‘files-configuration’ parameter: file-name temp-dir
          Specifies the directory where temporary files are stored.

          Defaults to ‘"/var/spool/cups/tmp"’.

      -- ‘files-configuration’ parameter: string user
          Specifies the user name or ID that is used when running
          external programs.

          Defaults to ‘"lp"’.

      -- ‘files-configuration’ parameter: string set-env
          Set the specified environment variable to be passed to child
          processes.

          Defaults to ‘"variable value"’.

 -- ‘cups-configuration’ parameter: access-log-level access-log-level
     Specifies the logging level for the AccessLog file.  The ‘config’
     level logs when printers and classes are added, deleted, or
     modified and when configuration files are accessed or updated.  The
     ‘actions’ level logs when print jobs are submitted, held, released,
     modified, or canceled, and any of the conditions for ‘config’.  The
     ‘all’ level logs all requests.

     Defaults to ‘actions’.

 -- ‘cups-configuration’ parameter: boolean auto-purge-jobs?
     Specifies whether to purge job history data automatically when it
     is no longer required for quotas.

     Defaults to ‘#f’.

 -- ‘cups-configuration’ parameter: comma-separated-string-list
          browse-dns-sd-sub-types
     Specifies a list of DNS-SD sub-types to advertise for each shared
     printer.  For example, ‘"_cups" "_print"’ will tell network clients
     that both CUPS sharing and IPP Everywhere are supported.

     Defaults to ‘"_cups"’.

 -- ‘cups-configuration’ parameter: browse-local-protocols
          browse-local-protocols
     Specifies which protocols to use for local printer sharing.

     Defaults to ‘dnssd’.

 -- ‘cups-configuration’ parameter: boolean browse-web-if?
     Specifies whether the CUPS web interface is advertised.

     Defaults to ‘#f’.

 -- ‘cups-configuration’ parameter: boolean browsing?
     Specifies whether shared printers are advertised.

     Defaults to ‘#f’.

 -- ‘cups-configuration’ parameter: string classification
     Specifies the security classification of the server.  Any valid
     banner name can be used, including ‘"classified"’,
     ‘"confidential"’, ‘"secret"’, ‘"topsecret"’, and ‘"unclassified"’,
     or the banner can be omitted to disable secure printing functions.

     Defaults to ‘""’.

 -- ‘cups-configuration’ parameter: boolean classify-override?
     Specifies whether users may override the classification (cover
     page) of individual print jobs using the ‘job-sheets’ option.

     Defaults to ‘#f’.

 -- ‘cups-configuration’ parameter: default-auth-type default-auth-type
     Specifies the default type of authentication to use.

     Defaults to ‘Basic’.

 -- ‘cups-configuration’ parameter: default-encryption
          default-encryption
     Specifies whether encryption will be used for authenticated
     requests.

     Defaults to ‘Required’.

 -- ‘cups-configuration’ parameter: string default-language
     Specifies the default language to use for text and web content.

     Defaults to ‘"en"’.

 -- ‘cups-configuration’ parameter: string default-paper-size
     Specifies the default paper size for new print queues.  ‘"Auto"’
     uses a locale-specific default, while ‘"None"’ specifies there is
     no default paper size.  Specific size names are typically
     ‘"Letter"’ or ‘"A4"’.

     Defaults to ‘"Auto"’.

 -- ‘cups-configuration’ parameter: string default-policy
     Specifies the default access policy to use.

     Defaults to ‘"default"’.

 -- ‘cups-configuration’ parameter: boolean default-shared?
     Specifies whether local printers are shared by default.

     Defaults to ‘#t’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          dirty-clean-interval
     Specifies the delay for updating of configuration and state files,
     in seconds.  A value of 0 causes the update to happen as soon as
     possible, typically within a few milliseconds.

     Defaults to ‘30’.

 -- ‘cups-configuration’ parameter: error-policy error-policy
     Specifies what to do when an error occurs.  Possible values are
     ‘abort-job’, which will discard the failed print job; ‘retry-job’,
     which will retry the job at a later time; ‘retry-current-job’,
     which retries the failed job immediately; and ‘stop-printer’, which
     stops the printer.

     Defaults to ‘stop-printer’.

 -- ‘cups-configuration’ parameter: non-negative-integer filter-limit
     Specifies the maximum cost of filters that are run concurrently,
     which can be used to minimize disk, memory, and CPU resource
     problems.  A limit of 0 disables filter limiting.  An average print
     to a non-PostScript printer needs a filter limit of about 200.  A
     PostScript printer needs about half that (100).  Setting the limit
     below these thresholds will effectively limit the scheduler to
     printing a single job at any time.

     Defaults to ‘0’.

 -- ‘cups-configuration’ parameter: non-negative-integer filter-nice
     Specifies the scheduling priority of filters that are run to print
     a job.  The nice value ranges from 0, the highest priority, to 19,
     the lowest priority.

     Defaults to ‘0’.

 -- ‘cups-configuration’ parameter: host-name-lookups host-name-lookups
     Specifies whether to do reverse lookups on connecting clients.  The
     ‘double’ setting causes ‘cupsd’ to verify that the hostname
     resolved from the address matches one of the addresses returned for
     that hostname.  Double lookups also prevent clients with
     unregistered addresses from connecting to your server.  Only set
     this option to ‘#t’ or ‘double’ if absolutely required.

     Defaults to ‘#f’.

 -- ‘cups-configuration’ parameter: non-negative-integer job-kill-delay
     Specifies the number of seconds to wait before killing the filters
     and backend associated with a canceled or held job.

     Defaults to ‘30’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          job-retry-interval
     Specifies the interval between retries of jobs in seconds.  This is
     typically used for fax queues but can also be used with normal
     print queues whose error policy is ‘retry-job’ or
     ‘retry-current-job’.

     Defaults to ‘30’.

 -- ‘cups-configuration’ parameter: non-negative-integer job-retry-limit
     Specifies the number of retries that are done for jobs.  This is
     typically used for fax queues but can also be used with normal
     print queues whose error policy is ‘retry-job’ or
     ‘retry-current-job’.

     Defaults to ‘5’.

 -- ‘cups-configuration’ parameter: boolean keep-alive?
     Specifies whether to support HTTP keep-alive connections.

     Defaults to ‘#t’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          limit-request-body
     Specifies the maximum size of print files, IPP requests, and HTML
     form data.  A limit of 0 disables the limit check.

     Defaults to ‘0’.

 -- ‘cups-configuration’ parameter: multiline-string-list listen
     Listens on the specified interfaces for connections.  Valid values
     are of the form ADDRESS:PORT, where ADDRESS is either an IPv6
     address enclosed in brackets, an IPv4 address, or ‘*’ to indicate
     all addresses.  Values can also be file names of local UNIX domain
     sockets.  The Listen directive is similar to the Port directive but
     allows you to restrict access to specific interfaces or networks.

 -- ‘cups-configuration’ parameter: non-negative-integer listen-back-log
     Specifies the number of pending connections that will be allowed.
     This normally only affects very busy servers that have reached the
     MaxClients limit, but can also be triggered by large numbers of
     simultaneous connections.  When the limit is reached, the operating
     system will refuse additional connections until the scheduler can
     accept the pending ones.

     Defaults to ‘128’.

 -- ‘cups-configuration’ parameter: location-access-control-list
          location-access-controls
     Specifies a set of additional access controls.

     Available ‘location-access-controls’ fields are:

      -- ‘location-access-controls’ parameter: file-name path
          Specifies the URI path to which the access control applies.

      -- ‘location-access-controls’ parameter: access-control-list
               access-controls
          Access controls for all access to this path, in the same
          format as the ‘access-controls’ of ‘operation-access-control’.

          Defaults to ‘()’.

      -- ‘location-access-controls’ parameter:
               method-access-control-list method-access-controls
          Access controls for method-specific access to this path.

          Defaults to ‘()’.

          Available ‘method-access-controls’ fields are:

           -- ‘method-access-controls’ parameter: boolean reverse?
               If ‘#t’, apply access controls to all methods except the
               listed methods.  Otherwise apply to only the listed
               methods.

               Defaults to ‘#f’.

           -- ‘method-access-controls’ parameter: method-list methods
               Methods to which this access control applies.

               Defaults to ‘()’.

           -- ‘method-access-controls’ parameter: access-control-list
                    access-controls
               Access control directives, as a list of strings.  Each
               string should be one directive, such as ‘"Order
               allow,deny"’.

               Defaults to ‘()’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          log-debug-history
     Specifies the number of debugging messages that are retained for
     logging if an error occurs in a print job.  Debug messages are
     logged regardless of the LogLevel setting.

     Defaults to ‘100’.

 -- ‘cups-configuration’ parameter: log-level log-level
     Specifies the level of logging for the ErrorLog file.  The value
     ‘none’ stops all logging while ‘debug2’ logs everything.

     Defaults to ‘info’.

 -- ‘cups-configuration’ parameter: log-time-format log-time-format
     Specifies the format of the date and time in the log files.  The
     value ‘standard’ logs whole seconds while ‘usecs’ logs
     microseconds.

     Defaults to ‘standard’.

 -- ‘cups-configuration’ parameter: non-negative-integer max-clients
     Specifies the maximum number of simultaneous clients that are
     allowed by the scheduler.

     Defaults to ‘100’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          max-clients-per-host
     Specifies the maximum number of simultaneous clients that are
     allowed from a single address.

     Defaults to ‘100’.

 -- ‘cups-configuration’ parameter: non-negative-integer max-copies
     Specifies the maximum number of copies that a user can print of
     each job.

     Defaults to ‘9999’.

 -- ‘cups-configuration’ parameter: non-negative-integer max-hold-time
     Specifies the maximum time a job may remain in the ‘indefinite’
     hold state before it is canceled.  A value of 0 disables
     cancellation of held jobs.

     Defaults to ‘0’.

 -- ‘cups-configuration’ parameter: non-negative-integer max-jobs
     Specifies the maximum number of simultaneous jobs that are allowed.
     Set to 0 to allow an unlimited number of jobs.

     Defaults to ‘500’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          max-jobs-per-printer
     Specifies the maximum number of simultaneous jobs that are allowed
     per printer.  A value of 0 allows up to MaxJobs jobs per printer.

     Defaults to ‘0’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          max-jobs-per-user
     Specifies the maximum number of simultaneous jobs that are allowed
     per user.  A value of 0 allows up to MaxJobs jobs per user.

     Defaults to ‘0’.

 -- ‘cups-configuration’ parameter: non-negative-integer max-job-time
     Specifies the maximum time a job may take to print before it is
     canceled, in seconds.  Set to 0 to disable cancellation of “stuck”
     jobs.

     Defaults to ‘10800’.

 -- ‘cups-configuration’ parameter: non-negative-integer max-log-size
     Specifies the maximum size of the log files before they are
     rotated, in bytes.  The value 0 disables log rotation.

     Defaults to ‘1048576’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          multiple-operation-timeout
     Specifies the maximum amount of time to allow between files in a
     multiple file print job, in seconds.

     Defaults to ‘900’.

 -- ‘cups-configuration’ parameter: string page-log-format
     Specifies the format of PageLog lines.  Sequences beginning with
     percent (‘%’) characters are replaced with the corresponding
     information, while all other characters are copied literally.  The
     following percent sequences are recognized:

     ‘%%’
          insert a single percent character

     ‘%{name}’
          insert the value of the specified IPP attribute

     ‘%C’
          insert the number of copies for the current page

     ‘%P’
          insert the current page number

     ‘%T’
          insert the current date and time in common log format

     ‘%j’
          insert the job ID

     ‘%p’
          insert the printer name

     ‘%u’
          insert the username

     A value of the empty string disables page logging.  The string ‘%p
     %u %j %T %P %C %{job-billing} %{job-originating-host-name}
     %{job-name} %{media} %{sides}’ creates a page log with the standard
     items.

     Defaults to ‘""’.

 -- ‘cups-configuration’ parameter: environment-variables
          environment-variables
     Passes the specified environment variable(s) to child processes; a
     list of strings.

     Defaults to ‘()’.

 -- ‘cups-configuration’ parameter: policy-configuration-list policies
     Specifies named access control policies.

     Available ‘policy-configuration’ fields are:

      -- ‘policy-configuration’ parameter: string name
          Name of the policy.

      -- ‘policy-configuration’ parameter: string job-private-access
          Specifies an access list for a job’s private values.  ‘@ACL’
          maps to the printer’s requesting-user-name-allowed or
          requesting-user-name-denied values.  ‘@OWNER’ maps to the
          job’s owner.  ‘@SYSTEM’ maps to the groups listed for the
          ‘system-group’ field of the ‘files-configuration’, which is
          reified into the ‘cups-files.conf(5)’ file.  Other possible
          elements of the access list include specific user names, and
          ‘@GROUP’ to indicate members of a specific group.  The access
          list may also be simply ‘all’ or ‘default’.

          Defaults to ‘"@OWNER @SYSTEM"’.

      -- ‘policy-configuration’ parameter: string job-private-values
          Specifies the list of job values to make private, or ‘all’,
          ‘default’, or ‘none’.

          Defaults to ‘"job-name job-originating-host-name
          job-originating-user-name phone"’.

      -- ‘policy-configuration’ parameter: string
               subscription-private-access
          Specifies an access list for a subscription’s private values.
          ‘@ACL’ maps to the printer’s requesting-user-name-allowed or
          requesting-user-name-denied values.  ‘@OWNER’ maps to the
          job’s owner.  ‘@SYSTEM’ maps to the groups listed for the
          ‘system-group’ field of the ‘files-configuration’, which is
          reified into the ‘cups-files.conf(5)’ file.  Other possible
          elements of the access list include specific user names, and
          ‘@GROUP’ to indicate members of a specific group.  The access
          list may also be simply ‘all’ or ‘default’.

          Defaults to ‘"@OWNER @SYSTEM"’.

      -- ‘policy-configuration’ parameter: string
               subscription-private-values
          Specifies the list of job values to make private, or ‘all’,
          ‘default’, or ‘none’.

          Defaults to ‘"notify-events notify-pull-method
          notify-recipient-uri notify-subscriber-user-name
          notify-user-data"’.

      -- ‘policy-configuration’ parameter: operation-access-control-list
               access-controls
          Access control by IPP operation.

          Defaults to ‘()’.

 -- ‘cups-configuration’ parameter: boolean-or-non-negative-integer
          preserve-job-files
     Specifies whether job files (documents) are preserved after a job
     is printed.  If a numeric value is specified, job files are
     preserved for the indicated number of seconds after printing.
     Otherwise a boolean value applies indefinitely.

     Defaults to ‘86400’.

 -- ‘cups-configuration’ parameter: boolean-or-non-negative-integer
          preserve-job-history
     Specifies whether the job history is preserved after a job is
     printed.  If a numeric value is specified, the job history is
     preserved for the indicated number of seconds after printing.  If
     ‘#t’, the job history is preserved until the MaxJobs limit is
     reached.

     Defaults to ‘#t’.

 -- ‘cups-configuration’ parameter: non-negative-integer reload-timeout
     Specifies the amount of time to wait for job completion before
     restarting the scheduler.

     Defaults to ‘30’.

 -- ‘cups-configuration’ parameter: string rip-cache
     Specifies the maximum amount of memory to use when converting
     documents into bitmaps for a printer.

     Defaults to ‘"128m"’.

 -- ‘cups-configuration’ parameter: string server-admin
     Specifies the email address of the server administrator.

     Defaults to ‘"root@localhost.localdomain"’.

 -- ‘cups-configuration’ parameter: host-name-list-or-* server-alias
     The ServerAlias directive is used for HTTP Host header validation
     when clients connect to the scheduler from external interfaces.
     Using the special name ‘*’ can expose your system to known
     browser-based DNS rebinding attacks, even when accessing sites
     through a firewall.  If the auto-discovery of alternate names does
     not work, we recommend listing each alternate name with a
     ServerAlias directive instead of using ‘*’.

     Defaults to ‘*’.

 -- ‘cups-configuration’ parameter: string server-name
     Specifies the fully-qualified host name of the server.

     Defaults to ‘"localhost"’.

 -- ‘cups-configuration’ parameter: server-tokens server-tokens
     Specifies what information is included in the Server header of HTTP
     responses.  ‘None’ disables the Server header.  ‘ProductOnly’
     reports ‘CUPS’.  ‘Major’ reports ‘CUPS 2’.  ‘Minor’ reports ‘CUPS
     2.0’.  ‘Minimal’ reports ‘CUPS 2.0.0’.  ‘OS’ reports ‘CUPS 2.0.0
     (UNAME)’ where UNAME is the output of the ‘uname’ command.  ‘Full’
     reports ‘CUPS 2.0.0 (UNAME) IPP/2.0’.

     Defaults to ‘Minimal’.

 -- ‘cups-configuration’ parameter: multiline-string-list ssl-listen
     Listens on the specified interfaces for encrypted connections.
     Valid values are of the form ADDRESS:PORT, where ADDRESS is either
     an IPv6 address enclosed in brackets, an IPv4 address, or ‘*’ to
     indicate all addresses.

     Defaults to ‘()’.

 -- ‘cups-configuration’ parameter: ssl-options ssl-options
     Sets encryption options.  By default, CUPS only supports encryption
     using TLS v1.0 or higher using known secure cipher suites.
     Security is reduced when ‘Allow’ options are used, and enhanced
     when ‘Deny’ options are used.  The ‘AllowRC4’ option enables the
     128-bit RC4 cipher suites, which are required for some older
     clients.  The ‘AllowSSL3’ option enables SSL v3.0, which is
     required for some older clients that do not support TLS v1.0.  The
     ‘DenyCBC’ option disables all CBC cipher suites.  The ‘DenyTLS1.0’
     option disables TLS v1.0 support - this sets the minimum protocol
     version to TLS v1.1.

     Defaults to ‘()’.

 -- ‘cups-configuration’ parameter: boolean strict-conformance?
     Specifies whether the scheduler requires clients to strictly adhere
     to the IPP specifications.

     Defaults to ‘#f’.

 -- ‘cups-configuration’ parameter: non-negative-integer timeout
     Specifies the HTTP request timeout, in seconds.

     Defaults to ‘900’.

 -- ‘cups-configuration’ parameter: boolean web-interface?
     Specifies whether the web interface is enabled.

     Defaults to ‘#f’.

   At this point you’re probably thinking “oh dear, Guix manual, I like
you but you can stop already with the configuration options”.  Indeed.
However, one more point: it could be that you have an existing
‘cupsd.conf’ that you want to use.  In that case, you can pass an
‘opaque-cups-configuration’ as the configuration of a
‘cups-service-type’.

   Available ‘opaque-cups-configuration’ fields are:

 -- ‘opaque-cups-configuration’ parameter: package cups
     The CUPS package.

 -- ‘opaque-cups-configuration’ parameter: string cupsd.conf
     The contents of the ‘cupsd.conf’, as a string.

 -- ‘opaque-cups-configuration’ parameter: string cups-files.conf
     The contents of the ‘cups-files.conf’ file, as a string.

   For example, if your ‘cupsd.conf’ and ‘cups-files.conf’ are in
strings of the same name, you could instantiate a CUPS service like
this:

     (service cups-service-type
              (opaque-cups-configuration
                (cupsd.conf cupsd.conf)
                (cups-files.conf cups-files.conf)))

