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

Copyright © 2012–2025 Ludovic Courtès
Copyright © 2013, 2014, 2016, 2024 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, 2023, 2025 Leo Famulari
Copyright © 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 Ricardo
Wurmus
Copyright © 2016 Ben Woodcroft
Copyright © 2016, 2017, 2018, 2021 Chris Marusich
Copyright © 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2025 Efraim
Flashner
Copyright © 2016 John Darrington
Copyright © 2016, 2017 Nikita Gillmann
Copyright © 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024, 2025
Janneke 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, 2024, 2025 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–2025 Maxim Cournoyer
Copyright © 2017–2022 Tobias Geerinckx-Rice
Copyright © 2017 George Clemmer
Copyright © 2017 Andy Wingo
Copyright © 2017, 2018, 2019, 2020, 2023, 2024, 2025 Arun Isaac
Copyright © 2017 nee
Copyright © 2018 Rutger Helling
Copyright © 2018, 2021, 2023, 2025 Oleg Pykhalov
Copyright © 2018 Mike Gerwitz
Copyright © 2018 Pierre-Antoine Rouby
Copyright © 2018, 2019 Gábor Boskovits
Copyright © 2018, 2019, 2020, 2022, 2023, 2024 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, 2023 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, 2022 Pierre Langlois
Copyright © 2020 pinoaffe
Copyright © 2020, 2023 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-2023 Josselin Poiret
Copyright © 2021, 2023 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
Copyright © 2022⁠–⁠2023 Bruno Victal
Copyright © 2022 Ivan Vilata-i-Balaguer
Copyright © 2023-2025 Giacomo Leidi
Copyright © 2022 Antero Mejr
Copyright © 2023 Karl Hallsby
Copyright © 2023 Nathaniel Nicandro
Copyright © 2023 Tanguy Le Carrour
Copyright © 2023-2024 Zheng Junjie
Copyright © 2023 Brian Cully
Copyright © 2023 Felix Lechner
Copyright © 2023 Foundation Devices, Inc.
Copyright © 2023 Thomas Ieong
Copyright © 2023 Saku Laesvuori
Copyright © 2023 Graham James Addis
Copyright © 2023-2025 Tomas Volf
Copyright © 2024, 2025 Herman Rimm
Copyright © 2024 Matthew Trzcinski
Copyright © 2024 Richard Sent
Copyright © 2024 Dariqq
Copyright © 2024 Denis ’GNUtoo’ Carikli
Copyright © 2024 Fabio Natali
Copyright © 2024 Arnaud Daby-Seesaram
Copyright © 2024-2025 Nigko Yerden
Copyright © 2024 Troy Figiel
Copyright © 2024 Sharlatan Hellseher
Copyright © 2024 45mg
Copyright © 2024 Greg Hogan
Copyright © 2025 Sören Tempel
Copyright © 2025 Rostislav Svoboda
Copyright © 2025 Zacchaeus
Copyright © 2025 Sergio Pastor Pérez
Copyright © 2024 Evgeny Pisemsky
Copyright © 2025 jgart
Copyright © 2025 Artur Wroblewski
Copyright © 2025 Edouard Klein
Copyright © 2025 Rodion Goritskov
Copyright © 2025 dan
Copyright © 2025 Noé Lopez

   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: Samba Services,  Next: Continuous Integration,  Prev: Network File System,  Up: Services

11.10.27 Samba Services
-----------------------

The ‘(gnu services samba)’ module provides service definitions for Samba
as well as additional helper services.  Currently it provides the
following services.

Samba
.....

Samba (https://www.samba.org) provides network shares for folders and
printers using the SMB/CIFS protocol commonly used on Windows.  It can
also act as an Active Directory Domain Controller (AD DC) for other
hosts in an heterougenious network with different types of Computer
systems.

 -- Variable: samba-service-type

     The service type to enable the samba services ‘samba’, ‘nmbd’,
     ‘smbd’ and ‘winbindd’.  By default this service type does not run
     any of the Samba daemons; they must be enabled individually.

     Below is a basic example that configures a simple, anonymous
     (unauthenticated) Samba file share exposing the ‘/public’
     directory.

          Tip: The ‘/public’ directory and its contents must be world
          readable/writable, so you’ll want to run ‘chmod -R 777
          /public’ on it.

          Caution: Such a Samba configuration should only be used in
          controlled environments, and you should not share any private
          files using it, as anyone connecting to your network would be
          able to access them.

          (service samba-service-type (samba-configuration
                                       (enable-smbd? #t)
                                       (config-file (plain-file "smb.conf" "\
          [global]
          map to guest = Bad User
          logging = syslog@1

          [public]
          browsable = yes
          path = /public
          read only = no
          guest ok = yes
          guest only = yes\n"))))

 -- Data Type: samba-service-configuration
     Configuration record for the Samba suite.

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

     ‘config-file’ (default: ‘#f’)
          The config file to use.  To learn about its syntax, run ‘man
          smb.conf’.

     ‘enable-samba?’ (default: ‘#f’)
          Enable the ‘samba’ daemon.

     ‘enable-smbd?’ (default: ‘#f’)
          Enable the ‘smbd’ daemon.

     ‘enable-nmbd?’ (default: ‘#f’)
          Enable the ‘nmbd’ daemon.

     ‘enable-winbindd?’ (default: ‘#f’)
          Enable the ‘winbindd’ daemon.

Web Service Discovery Daemon
............................

The WSDD (Web Service Discovery daemon) implements the Web Services
Dynamic Discovery
(http://docs.oasis-open.org/ws-dd/discovery/1.1/os/wsdd-discovery-1.1-spec-os.html)
protocol that enables host discovery over Multicast DNS, similar to what
Avahi does.  It is a drop-in replacement for SMB hosts that have had
SMBv1 disabled for security reasons.

 -- Variable: wsdd-service-type
     Service type for the WSD host daemon.  The value for this service
     type is a ‘wsdd-configuration’ record.  The details for the
     ‘wsdd-configuration’ record type are given below.

 -- Data Type: wsdd-configuration
     This data type represents the configuration for the wsdd service.

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

     ‘ipv4only?’ (default: ‘#f’)
          Only listen to IPv4 addresses.

     ‘ipv6only’ (default: ‘#f’)
          Only listen to IPv6 addresses.  Please note: Activating both
          options is not possible, since there would be no IP versions
          to listen to.

     ‘chroot’ (default: ‘#f’)
          Chroot into a separate directory to prevent access to other
          directories.  This is to increase security in case there is a
          vulnerability in ‘wsdd’.

     ‘hop-limit’ (default: ‘1’)
          Limit to the level of hops for multicast packets.  The default
          is 1 which should prevent packets from leaving the local
          network.

     ‘interface’ (default: ‘'()’)
          Limit to the given list of interfaces to listen to.  By
          default wsdd will listen to all interfaces.  Except the
          loopback interface is never used.

     ‘uuid-device’ (default: ‘#f’)
          The WSD protocol requires a device to have a UUID. Set this to
          manually assign the service a UUID.

     ‘domain’ (default: ‘#f’)
          Notify this host is a member of an Active Directory.

     ‘host-name’ (default: ‘#f’)
          Manually set the hostname rather than letting ‘wsdd’ inherit
          this host’s hostname.  Only the host name part of a possible
          FQDN will be used in the default case.

     ‘preserve-case?’ (default: ‘#f’)
          By default ‘wsdd’ will convert the hostname in workgroup to
          all uppercase.  The opposite is true for hostnames in domains.
          Setting this parameter will preserve case.

     ‘workgroup’ (default: "WORKGROUP")
          Change the name of the workgroup.  By default ‘wsdd’ reports
          this host being member of a workgroup.


File: guix.info,  Node: Continuous Integration,  Next: Power Management Services,  Prev: Samba Services,  Up: Services

11.10.28 Continuous Integration
-------------------------------

Cuirass (https://guix.gnu.org/cuirass/) is a continuous integration tool
for Guix.  It can be used both for development and for providing
substitutes to others (*note Substitutes::).

   The ‘(gnu services cuirass)’ module provides the following service.

 -- Procedure: cuirass-service-type
     The type of the Cuirass service.  Its value must be a
     ‘cuirass-configuration’ object, as described below.

   To add build jobs, you have to set the ‘specifications’ field of the
configuration.  For instance, the following example will build all the
packages provided by the ‘my-channel’ channel.

     (define %cuirass-specs
       #~(list (specification
                (name 'my-channel)
                (build '(channels my-channel))
                (channels
                 (cons (channel
                        (name 'my-channel)
                        (url "https://my-channel.git"))
                       %default-channels)))))

     (service cuirass-service-type
              (cuirass-configuration
               (specifications %cuirass-specs)))

   To build the ‘linux-libre’ package defined by the default Guix
channel, one can use the following configuration.

     (define %cuirass-specs
       #~(list (specification
                (name 'my-linux)
                (build '(packages "linux-libre")))))

     (service cuirass-service-type
              (cuirass-configuration
               (specifications %cuirass-specs)))

   The other configuration possibilities, as well as the specification
record itself are described in the Cuirass manual (*note
(cuirass)Specifications::).

   While information related to build jobs is located directly in the
specifications, global settings for the ‘cuirass’ process are accessible
in other ‘cuirass-configuration’ fields.

 -- Data Type: cuirass-configuration
     Data type representing the configuration of Cuirass.

     ‘cuirass’ (default: ‘cuirass’)
          The Cuirass package to use.

     ‘log-file’ (default: ‘"/var/log/cuirass.log"’)
          Location of the log file.

     ‘web-log-file’ (default: ‘"/var/log/cuirass-web.log"’)
          Location of the log file used by the web interface.

     ‘cache-directory’ (default: ‘"/var/cache/cuirass"’)
          Location of the repository cache.

     ‘user’ (default: ‘"cuirass"’)
          Owner of the ‘cuirass’ process.

     ‘group’ (default: ‘"cuirass"’)
          Owner’s group of the ‘cuirass’ process.

     ‘interval’ (default: ‘300’)
          Number of seconds between the poll of the repositories
          followed by the Cuirass jobs, by default.

          Note that individual jobset specifications may override this
          in their ‘period’ field; the value specified here is only used
          for specifications that use the default ‘period’ value, which
          is zero.

     ‘parallel-evaluations’ (default: ‘#f’)
          Maximum number of jobset evaluations that may run
          concurrently.  If ‘#f’, that number is determined based on a
          number of CPU cores, with an upper bound of 8.

     ‘ttl’ (default: ‘2592000’)
          Duration to keep build results’ GC roots alive, in seconds.

     ‘evaluation-ttl’ (default: 24 months)
          Number of seconds after which an evaluation may be deleted
          from the database.

     ‘build-expiry’ (default: 4 months)
          Duration in seconds after which pending builds are canceled.
          This helps ensure that the backlog does not grow indefinitely.

     ‘threads’ (default: ‘#f’)
     ‘web-threads’ (default: ‘#f’)
          Number of kernel threads to use for Cuirass (main process) and
          for the web interface (the ‘cuirass web’ program).  The
          default value should be appropriate for most cases.

     ‘parameters’ (default: ‘#f’)
          Read parameters from the given PARAMETERS file.  The supported
          parameters are described here (*note (cuirass)Parameters::).

     ‘remote-server’ (default: ‘#f’)
          A ‘cuirass-remote-server-configuration’ record to use the
          build remote mechanism or ‘#f’ to use the default build
          mechanism.

     ‘database’ (default: ‘"dbname=cuirass host=/var/run/postgresql"’)
          Use DATABASE as the database containing the jobs and the past
          build results.  Since Cuirass uses PostgreSQL as a database
          engine, DATABASE must be a string such as ‘"dbname=cuirass
          host=localhost"’.

     ‘port’ (default: ‘8081’)
          Port number used by the HTTP server.

     ‘host’ (default: ‘"localhost"’)
          Listen on the network interface for HOST.  The default is to
          accept connections from localhost.

     ‘specifications’ (default: ‘#~'()’)
          A gexp (*note G-Expressions::) that evaluates to a list of
          specifications records.  The specification record is described
          in the Cuirass manual (*note (cuirass)Specifications::).

     ‘one-shot?’ (default: ‘#f’)
          Only evaluate specifications and build derivations once.

     ‘fallback?’ (default: ‘#f’)
          When substituting a pre-built binary fails, fall back to
          building packages locally.

     ‘extra-options’ (default: ‘'()’)
          Extra options to pass when running the ‘cuirass register’
          process.

     ‘web-extra-options’ (default: ‘'()’)
          Extra options to pass when running the ‘cuirass web’ process.

Cuirass remote building
.......................

Cuirass supports two mechanisms to build derivations.

   • Using the local Guix daemon.  This is the default build mechanism.
     Once the build jobs are evaluated, they are sent to the local Guix
     daemon.  Cuirass then listens to the Guix daemon output to detect
     the various build events.

   • Using the remote build mechanism.  The build jobs are not submitted
     to the local Guix daemon.  Instead, a remote server dispatches
     build requests to the connect remote workers, according to the
     build priorities.

   To enable this build mode a ‘cuirass-remote-server-configuration’
record must be passed as ‘remote-server’ argument of the
‘cuirass-configuration’ record.  The
‘cuirass-remote-server-configuration’ record is described below.

   This build mode scales way better than the default build mode.  This
is the build mode that is used on the GNU Guix build farm at
<https://ci.guix.gnu.org>.  It should be preferred when using Cuirass to
build large amount of packages.

 -- Data Type: cuirass-remote-server-configuration
     Data type representing the configuration of the Cuirass
     remote-server.

     ‘backend-port’ (default: ‘5555’)
          The TCP port for communicating with ‘remote-worker’ processes
          using ZMQ. It defaults to ‘5555’.

     ‘log-port’ (default: ‘5556’)
          The TCP port of the log server.  It defaults to ‘5556’.

     ‘publish-port’ (default: ‘5557’)
          The TCP port of the publish server.  It defaults to ‘5557’.

     ‘log-file’ (default: ‘"/var/log/cuirass-remote-server.log"’)
          Location of the log file.

     ‘cache’ (default: ‘"/var/cache/cuirass/remote"’)
          Use CACHE directory to cache build log files.

     ‘log-expiry’ (default: 6 months)
          The duration in seconds after which build logs collected by
          ‘cuirass remote-worker’ may be deleted.

     ‘trigger-url’ (default: ‘#f’)
          Once a substitute is successfully fetched, trigger substitute
          baking at TRIGGER-URL.

     ‘publish?’ (default: ‘#t’)
          If set to false, do not start a publish server and ignore the
          ‘publish-port’ argument.  This can be useful if there is
          already a standalone publish server standing next to the
          remote server.

     ‘public-key’
     ‘private-key’
          Use the specific FILEs as the public/private key pair used to
          sign the store items being published.

   At least one remote worker must also be started on any machine of the
local network to actually perform the builds and report their status.

 -- Data Type: cuirass-remote-worker-configuration
     Data type representing the configuration of the Cuirass
     remote-worker.

     ‘cuirass’ (default: ‘cuirass’)
          The Cuirass package to use.

     ‘workers’ (default: ‘1’)
          Start WORKERS parallel workers.

     ‘server’ (default: ‘#f’)
          Do not use Avahi discovery and connect to the given ‘server’
          IP address instead.

     ‘systems’ (default: ‘(list (%current-system))’)
          Only request builds for the given SYSTEMS.

     ‘log-file’ (default: ‘"/var/log/cuirass-remote-worker.log"’)
          Location of the log file.

     ‘publish-port’ (default: ‘5558’)
          The TCP port of the publish server.  It defaults to ‘5558’.

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

     ‘public-key’
     ‘private-key’
          Use the specific FILEs as the public/private key pair used to
          sign the store items being published.

Laminar
.......

Laminar (https://laminar.ohwg.net/) is a lightweight and modular
Continuous Integration service.  It doesn’t have a configuration web UI
instead uses version-controllable configuration files and scripts.

   Laminar encourages the use of existing tools such as bash and cron
instead of reinventing them.

 -- Variable: laminar-service-type
     The type of the Laminar service.  Its value must be a
     ‘laminar-configuration’ object, as described below.

     All configuration values have defaults, a minimal configuration to
     get Laminar running is shown below.  By default, the web interface
     is available on port 8080.

          (service laminar-service-type)

 -- Data Type: laminar-configuration
     Data type representing the configuration of Laminar.

     ‘laminar’ (default: ‘laminar’)
          The Laminar package to use.

     ‘home-directory’ (default: ‘"/var/lib/laminar"’)
          The directory for job configurations and run directories.

     ‘supplementary-groups’ (default: ‘()’)
          Supplementary groups for the Laminar user account.

     ‘bind-http’ (default: ‘"*:8080"’)
          The interface/port or unix socket on which laminard should
          listen for incoming connections to the web frontend.

     ‘bind-rpc’ (default: ‘"unix-abstract:laminar"’)
          The interface/port or unix socket on which laminard should
          listen for incoming commands such as build triggers.

     ‘title’ (default: ‘"Laminar"’)
          The page title to show in the web frontend.

     ‘keep-rundirs’ (default: ‘0’)
          Set to an integer defining how many rundirs to keep per job.
          The lowest-numbered ones will be deleted.  The default is 0,
          meaning all run dirs will be immediately deleted.

     ‘archive-url’ (default: ‘#f’)
          The web frontend served by laminard will use this URL to form
          links to artefacts archived jobs.

     ‘base-url’ (default: ‘#f’)
          Base URL to use for links to laminar itself.

Forgejo Runner
..............

The ‘(gnu services ci)’ also provides a service for Forgejo Runner
(https://code.forgejo.org/forgejo/runner), a daemon that connects to an
instance of the Forgejo code collaboration tool (https://forgejo.org)
and runs jobs for continuous integration.

   A minimal configuration mostly with default values that can be added
to the ‘services’ field of your operating system looks like this:

     (service forgejo-runner-service-type
              (forgejo-runner-configuration
               (name "my-runner")
               (labels '("guix" "linux"))))

   This provides a ‘forgejo-runner’ Shepherd service.  That service will
initially fail to start; you will have to manually “register” the runner
against the Forgejo server by running a command like:

     herd register forgejo-runner URL TOKEN

...  where the arguments are as follows:

URL
     the URL of the Forgejo server—e.g., ‘https://codeberg.org’;
TOKEN
     an access token provided by the Forgejo server
     (https://forgejo.org/docs/latest/admin/runner-installation/#standard-registration).

   Once registration has succeeded, you can start the runner:

     herd enable forgejo-runner
     herd start forgejo-runner

   The runner then receives orders from the Forgejo server to execute
“actions”.  Actions are commands and workflows specified by YAML files
in the ‘.forgejo/workflows’ directory of source code repositories—see
the Forgejo Action documentation
(https://forgejo.org/docs/v7.0/user/actions/) for more info.

   Note that at the moment ‘forgejo-runner-service-type’ lets you run
only one runner.  Details about the configuration of this service
follow.

 -- Variable: forgejo-runner-service-type
     This is the service type for Forgejo Runner.  Its value must be a
     ‘forgejo-runner-configuration’ record, documented below.

 -- Data Type: forgejo-runner-configuration
     This data type represents the configuration of an instance of
     ‘forgejo-runner-service-type’.  It contains the following fields:

     ‘package’ (default: ‘forgejo-runner’)
          The Forgejo Runner package to use.

     ‘name’ (default: ‘#~(gethostname)’)
          Name of the runner as will be shown in the runner management
          interface of Forgejo.

     ‘labels’ (default: ‘'("guix")’)
          List of labels
          (https://forgejo.org/docs/latest/admin/actions/#choosing-labels)
          representing the type of environment the runner provides and
          that actions may refer to.

     ‘capacity’ (default: ‘1’)
          Number of tasks to be executed concurrently.

     ‘timeout’ (default: ‘(* 3 3600)’)
          Maximum duration of a job, in seconds.

     ‘fetch-timeout’ (default: ‘5’)
          Maximum duration for fetching the job from the Forgejo server,
          in seconds.

     ‘fetch-interval’ (default: ‘2’)
          Interval (in seconds) for fetching the job from the Forgejo
          server.

     ‘report-interval’ (default: ‘1’)
          Interval (in seconds) for reporting the job status and log to
          the Forgejo server.

     ‘data-directory’ (default: ‘"/var/lib/forgejo-runner"’)
          Directory where ‘forgejo-runner’ will store persistent data
          such as its configuration and access token.

     ‘run-directory’ (default: ‘"/var/run/forgejo-runner"’)
          Directory where ‘forgejo-runner’ stores cached data.

     ‘log-file’ (default: ‘"/var/log/forgejo-runner.log"’)
          Name of the ‘forgejo-runner’ log file.


File: guix.info,  Node: Power Management Services,  Next: Audio Services,  Prev: Continuous Integration,  Up: Services

11.10.29 Power Management Services
----------------------------------

Power Profiles Daemon
.....................

The ‘(gnu services pm)’ module provides a Guix service definition for
the Linux Power Profiles Daemon, which makes power profiles handling
available over D-Bus.

   The available profiles consist of the default ‘balanced’ mode, a
‘power-saver’ mode and on supported systems a ‘performance’ mode.

     Important: The ‘power-profiles-daemon’ conflicts with other power
     management tools like ‘tlp’.  Using both together is not
     recommended.

 -- Variable: power-profiles-daemon-service-type
     This is the service type for the Power Profiles Daemon
     (https://gitlab.freedesktop.org/upower/power-profiles-daemon/).
     The value for this service is a
     ‘power-profiles-daemon-configuration’.

     To enable the Power Profiles Daemon with default configuration add
     this line to your services:

          (service power-profiles-daemon-service-type)

 -- Data Type: power-profiles-daemon-configuration
     Data type representing the configuration of
     ‘power-profiles-daemon-service-type’.

     ‘power-profiles-daemon’ (default: ‘power-profiles-daemon’) (type: file-like)
          Package object of power-profiles-daemon.

TLP daemon
..........

The ‘(gnu services pm)’ module provides a Guix service definition for
the Linux power management tool TLP.

   TLP enables various powersaving modes in userspace and kernel.
Contrary to ‘upower-service’, it is not a passive, monitoring tool, as
it will apply custom settings each time a new power source is detected.
More information can be found at TLP home page
(https://linrunner.de/en/tlp/tlp.html).

 -- Variable: tlp-service-type
     The service type for the TLP tool.  The default settings are
     optimised for battery life on most systems, but you can tweak them
     to your heart’s content by adding a valid ‘tlp-configuration’:
          (service tlp-service-type
                   (tlp-configuration
                    (cpu-scaling-governor-on-ac (list "performance"))
                    (sched-powersave-on-bat? #t)))

   Each parameter definition is preceded by its type; for example,
‘boolean foo’ indicates that the ‘foo’ parameter should be specified as
a boolean.  Types starting with ‘maybe-’ denote parameters that won’t
show up in TLP config file when their value is left unset, or is
explicitly set to the ‘%unset-value’ value.

   Available ‘tlp-configuration’ fields are:

 -- tlp-configuration parameter: package tlp
     The TLP package.

 -- tlp-configuration parameter: boolean tlp-enable?
     Set to true if you wish to enable TLP.

     Defaults to ‘#t’.

 -- tlp-configuration parameter: string tlp-default-mode
     Default mode when no power supply can be detected.  Alternatives
     are AC and BAT.

     Defaults to ‘"AC"’.

 -- tlp-configuration parameter: non-negative-integer
          disk-idle-secs-on-ac
     Number of seconds Linux kernel has to wait after the disk goes
     idle, before syncing on AC.

     Defaults to ‘0’.

 -- tlp-configuration parameter: non-negative-integer
          disk-idle-secs-on-bat
     Same as ‘disk-idle-ac’ but on BAT mode.

     Defaults to ‘2’.

 -- tlp-configuration parameter: non-negative-integer
          max-lost-work-secs-on-ac
     Dirty pages flushing periodicity, expressed in seconds.

     Defaults to ‘15’.

 -- tlp-configuration parameter: non-negative-integer
          max-lost-work-secs-on-bat
     Same as ‘max-lost-work-secs-on-ac’ but on BAT mode.

     Defaults to ‘60’.

 -- tlp-configuration parameter: maybe-space-separated-string-list
          cpu-scaling-governor-on-ac
     CPU frequency scaling governor on AC mode.  With intel_pstate
     driver, alternatives are powersave and performance.  With
     acpi-cpufreq driver, alternatives are ondemand, powersave,
     performance and conservative.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-space-separated-string-list
          cpu-scaling-governor-on-bat
     Same as ‘cpu-scaling-governor-on-ac’ but on BAT mode.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-non-negative-integer
          cpu-scaling-min-freq-on-ac
     Set the min available frequency for the scaling governor on AC.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-non-negative-integer
          cpu-scaling-max-freq-on-ac
     Set the max available frequency for the scaling governor on AC.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-non-negative-integer
          cpu-scaling-min-freq-on-bat
     Set the min available frequency for the scaling governor on BAT.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-non-negative-integer
          cpu-scaling-max-freq-on-bat
     Set the max available frequency for the scaling governor on BAT.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-non-negative-integer
          cpu-min-perf-on-ac
     Limit the min P-state to control the power dissipation of the CPU,
     in AC mode.  Values are stated as a percentage of the available
     performance.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-non-negative-integer
          cpu-max-perf-on-ac
     Limit the max P-state to control the power dissipation of the CPU,
     in AC mode.  Values are stated as a percentage of the available
     performance.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-non-negative-integer
          cpu-min-perf-on-bat
     Same as ‘cpu-min-perf-on-ac’ on BAT mode.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-non-negative-integer
          cpu-max-perf-on-bat
     Same as ‘cpu-max-perf-on-ac’ on BAT mode.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-boolean cpu-boost-on-ac?
     Enable CPU turbo boost feature on AC mode.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-boolean cpu-boost-on-bat?
     Same as ‘cpu-boost-on-ac?’ on BAT mode.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: boolean sched-powersave-on-ac?
     Allow Linux kernel to minimize the number of CPU
     cores/hyper-threads used under light load conditions.

     Defaults to ‘#f’.

 -- tlp-configuration parameter: boolean sched-powersave-on-bat?
     Same as ‘sched-powersave-on-ac?’ but on BAT mode.

     Defaults to ‘#t’.

 -- tlp-configuration parameter: boolean nmi-watchdog?
     Enable Linux kernel NMI watchdog.

     Defaults to ‘#f’.

 -- tlp-configuration parameter: maybe-string phc-controls
     For Linux kernels with PHC patch applied, change CPU voltages.  An
     example value would be ‘"F:V F:V F:V F:V"’.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: string energy-perf-policy-on-ac
     Set CPU performance versus energy saving policy on AC.
     Alternatives are performance, normal, powersave.

     Defaults to ‘"performance"’.

 -- tlp-configuration parameter: string energy-perf-policy-on-bat
     Same as ‘energy-perf-policy-ac’ but on BAT mode.

     Defaults to ‘"powersave"’.

 -- tlp-configuration parameter: space-separated-string-list
          disks-devices
     Hard disk devices.

 -- tlp-configuration parameter: space-separated-string-list
          disk-apm-level-on-ac
     Hard disk advanced power management level.

 -- tlp-configuration parameter: space-separated-string-list
          disk-apm-level-on-bat
     Same as ‘disk-apm-bat’ but on BAT mode.

 -- tlp-configuration parameter: maybe-space-separated-string-list
          disk-spindown-timeout-on-ac
     Hard disk spin down timeout.  One value has to be specified for
     each declared hard disk.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-space-separated-string-list
          disk-spindown-timeout-on-bat
     Same as ‘disk-spindown-timeout-on-ac’ but on BAT mode.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-space-separated-string-list
          disk-iosched
     Select IO scheduler for disk devices.  One value has to be
     specified for each declared hard disk.  Example alternatives are
     cfq, deadline and noop.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: string sata-linkpwr-on-ac
     SATA aggressive link power management (ALPM) level.  Alternatives
     are min_power, medium_power, max_performance.

     Defaults to ‘"max_performance"’.

 -- tlp-configuration parameter: string sata-linkpwr-on-bat
     Same as ‘sata-linkpwr-ac’ but on BAT mode.

     Defaults to ‘"min_power"’.

 -- tlp-configuration parameter: maybe-string sata-linkpwr-blacklist
     Exclude specified SATA host devices for link power management.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-on-off-boolean
          ahci-runtime-pm-on-ac?
     Enable Runtime Power Management for AHCI controller and disks on AC
     mode.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-on-off-boolean
          ahci-runtime-pm-on-bat?
     Same as ‘ahci-runtime-pm-on-ac’ on BAT mode.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: non-negative-integer
          ahci-runtime-pm-timeout
     Seconds of inactivity before disk is suspended.

     Defaults to ‘15’.

 -- tlp-configuration parameter: string pcie-aspm-on-ac
     PCI Express Active State Power Management level.  Alternatives are
     default, performance, powersave.

     Defaults to ‘"performance"’.

 -- tlp-configuration parameter: string pcie-aspm-on-bat
     Same as ‘pcie-aspm-ac’ but on BAT mode.

     Defaults to ‘"powersave"’.

 -- tlp-configuration parameter: maybe-non-negative-integer
          start-charge-thresh-bat0
     Percentage when battery 0 should begin charging.  Only supported on
     some laptops.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-non-negative-integer
          stop-charge-thresh-bat0
     Percentage when battery 0 should stop charging.  Only supported on
     some laptops.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-non-negative-integer
          start-charge-thresh-bat1
     Percentage when battery 1 should begin charging.  Only supported on
     some laptops.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-non-negative-integer
          stop-charge-thresh-bat1
     Percentage when battery 1 should stop charging.  Only supported on
     some laptops.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: string radeon-power-profile-on-ac
     Radeon graphics clock speed level.  Alternatives are low, mid,
     high, auto, default.

     Defaults to ‘"high"’.

 -- tlp-configuration parameter: string radeon-power-profile-on-bat
     Same as ‘radeon-power-ac’ but on BAT mode.

     Defaults to ‘"low"’.

 -- tlp-configuration parameter: string radeon-dpm-state-on-ac
     Radeon dynamic power management method (DPM). Alternatives are
     battery, performance.

     Defaults to ‘"performance"’.

 -- tlp-configuration parameter: string radeon-dpm-state-on-bat
     Same as ‘radeon-dpm-state-ac’ but on BAT mode.

     Defaults to ‘"battery"’.

 -- tlp-configuration parameter: string radeon-dpm-perf-level-on-ac
     Radeon DPM performance level.  Alternatives are auto, low, high.

     Defaults to ‘"auto"’.

 -- tlp-configuration parameter: string radeon-dpm-perf-level-on-bat
     Same as ‘radeon-dpm-perf-ac’ but on BAT mode.

     Defaults to ‘"auto"’.

 -- tlp-configuration parameter: on-off-boolean wifi-pwr-on-ac?
     Wifi power saving mode.

     Defaults to ‘#f’.

 -- tlp-configuration parameter: on-off-boolean wifi-pwr-on-bat?
     Same as ‘wifi-power-ac?’ but on BAT mode.

     Defaults to ‘#t’.

 -- tlp-configuration parameter: y-n-boolean wol-disable?
     Disable wake on LAN.

     Defaults to ‘#t’.

 -- tlp-configuration parameter: non-negative-integer
          sound-power-save-on-ac
     Timeout duration in seconds before activating audio power saving on
     Intel HDA and AC97 devices.  A value of 0 disables power saving.

     Defaults to ‘0’.

 -- tlp-configuration parameter: non-negative-integer
          sound-power-save-on-bat
     Same as ‘sound-powersave-ac’ but on BAT mode.

     Defaults to ‘1’.

 -- tlp-configuration parameter: y-n-boolean
          sound-power-save-controller?
     Disable controller in powersaving mode on Intel HDA devices.

     Defaults to ‘#t’.

 -- tlp-configuration parameter: boolean bay-poweroff-on-bat?
     Enable optical drive in UltraBay/MediaBay on BAT mode.  Drive can
     be powered on again by releasing (and reinserting) the eject lever
     or by pressing the disc eject button on newer models.

     Defaults to ‘#f’.

 -- tlp-configuration parameter: string bay-device
     Name of the optical drive device to power off.

     Defaults to ‘"sr0"’.

 -- tlp-configuration parameter: string runtime-pm-on-ac
     Runtime Power Management for PCI(e) bus devices.  Alternatives are
     on and auto.

     Defaults to ‘"on"’.

 -- tlp-configuration parameter: string runtime-pm-on-bat
     Same as ‘runtime-pm-ac’ but on BAT mode.

     Defaults to ‘"auto"’.

 -- tlp-configuration parameter: boolean runtime-pm-all?
     Runtime Power Management for all PCI(e) bus devices, except
     blacklisted ones.

     Defaults to ‘#t’.

 -- tlp-configuration parameter: maybe-space-separated-string-list
          runtime-pm-blacklist
     Exclude specified PCI(e) device addresses from Runtime Power
     Management.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: space-separated-string-list
          runtime-pm-driver-blacklist
     Exclude PCI(e) devices assigned to the specified drivers from
     Runtime Power Management.

 -- tlp-configuration parameter: boolean usb-autosuspend?
     Enable USB autosuspend feature.

     Defaults to ‘#t’.

 -- tlp-configuration parameter: maybe-string usb-blacklist
     Exclude specified devices from USB autosuspend.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: boolean usb-blacklist-wwan?
     Exclude WWAN devices from USB autosuspend.

     Defaults to ‘#t’.

 -- tlp-configuration parameter: maybe-string usb-whitelist
     Include specified devices into USB autosuspend, even if they are
     already excluded by the driver or via ‘usb-blacklist-wwan?’.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: maybe-boolean
          usb-autosuspend-disable-on-shutdown?
     Enable USB autosuspend before shutdown.

     Defaults to ‘disabled’.

 -- tlp-configuration parameter: boolean
          restore-device-state-on-startup?
     Restore radio device state (bluetooth, wifi, wwan) from previous
     shutdown on system startup.

     Defaults to ‘#f’.

 -- tlp-configuration parameter: string cpu-energy-perf-policy-on-ac
     Set CPU energy/performance policy when on AC mode.  Possible
     values, in order of increasing power saving, are performance,
     balance_performance, default, balance_power and power.

 -- tlp-configuration parameter: string cpu-energy-perf-policy-on-bat
     Set CPU energy/performance policy when on BAT mode.  Possible
     values, in order of increasing power saving, are performance,
     balance_performance, default, balance_power and power.

Thermald daemon
...............

The ‘(gnu services pm)’ module provides an interface to thermald, a CPU
frequency scaling service which helps prevent overheating.

 -- Variable: thermald-service-type
     This is the service type for thermald
     (https://01.org/linux-thermal-daemon/), the Linux Thermal Daemon,
     which is responsible for controlling the thermal state of
     processors and preventing overheating.

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

     ‘adaptive?’ (default: ‘#f’)
          Use DPTF (Dynamic Power and Thermal Framework) adaptive tables
          when present.

     ‘ignore-cpuid-check?’ (default: ‘#f’)
          Ignore cpuid check for supported CPU models.

     ‘thermald’ (default: THERMALD)
          Package object of thermald.

          PowerTOP
          ........

          The ‘(gnu services pm)’ module also provides a service
          definition for PowerTOP (https://01.org/powertop/), a power
          consumption analysis and tuning tool.  When started, it tunes
          Linux kernel settings to reduce power consumption.

           -- Variable: powertop-service-type
               The service type for PowerTOP. No configuration is
               necessary.  When the service starts, it executes
               ‘powertop --auto-tune’.

                    (service powertop-service-type)

          Available ‘powertop-configuration’ fields are:

           -- powertop-configuration parameter: package powertop
               The PowerTOP package.  Defaults to ‘powertop’ in the
               ‘(gnu packages linux)’ module

   The ‘(gnu services power)’ module provides a service definition for
apcupsd (http://www.apcupsd.org/), a utility to interact with APC (APC
by Schneider Electric or formerly American Power Conversion Corporation)
UPS (Uninterruptible Power Supply) devices.  Apcupsd also works with
some OEM (Original Equipment Manufacturer)-branded products manufactured
by APC.

 -- Variable: apcupsd-service-type
     The service type for apcupsd.  For USB UPSes no configuration is
     necessary, however tweaking some fields to better suit your needs
     might be desirable.  The defaults are taken from the upstream
     configuration and they are not very conservative (for example, the
     default ‘battery-level’ of 5% may be considered too low by some).

     The default event handlers do send emails, read more in *note
     apcupsd-event-handlers::.

          (service apcupsd-service-type)

 -- Data Type: apcupsd-configuration

     Available ‘apcupsd-configuration’ fields are:

     ‘apcupsd’ (default: ‘apcupsd’) (type: package)
          The ‘apcupsd’ package to use.

     ‘shepherd-service-name’ (default: ‘apcupsd’) (type: symbol)
          The name of the shepherd service.  You can add the service
          multiple times with different names to manage multiple UPSes.

     ‘auto-start?’ (default: ‘#t’) (type: boolean)
          Should the shepherd service auto-start?

     ‘pid-file’ (default: ‘"/var/run/apcupsd.pid"’) (type: string)
          The file name of the pid file.

     ‘debug-level’ (default: ‘0’) (type: integer)
          The logging verbosity.  Bigger number means more logs.  The
          source code uses up to ‘300’ as debug level value, so a value
          of ‘999’ seems reasonable to enable all the logs.

     ‘run-dir’ (default: ‘"/var/run/apcupsd"’) (type: string)
          The directory containing runtime information.  You need to
          change this if you desire to run multiple instances of the
          daemon.

     ‘name’ (type: maybe-string)
          Use this to give your UPS a name in log files and such.  This
          is particularly useful if you have multiple UPSes.  This does
          not set the EEPROM. It should be 8 characters or less.

     ‘cable’ (default: ‘usb’) (type: enum-cable)
          The type of a cable connecting the UPS to your computer.
          Possible generic choices are ‘'simple’, ‘'smart’, ‘'ether’ and
          ‘'usb’.

          Alternatively, a specific cable model number may be used:
          ‘'940-0119A’, ‘'940-0127A’, ‘'940-0128A’, ‘'940-0020B’,
          ‘'940-0020C’, ‘'940-0023A’, ‘'940-0024B’, ‘'940-0024C’,
          ‘'940-1524C’, ‘'940-0024G’, ‘'940-0095A’, ‘'940-0095B’,
          ‘'940-0095C’, ‘'940-0625A’, ‘'M-04-02-2000’.

     ‘type’ (default: ‘usb’) (type: enum-type)
          The type of the UPS you have.

          ‘apcsmart’
               Newer serial character device, appropriate for SmartUPS
               models using a serial cable (not an USB).

          ‘usb’
               Most new UPSes are an USB.

          ‘net’
               Network link to a master apcupsd through apcupsd’s
               Network Information Server.  This is used if the UPS
               powering your computer is connected to a different
               computer for monitoring.

          ‘snmp’
               SNMP network link to an SNMP-enabled UPS device.

          ‘netsnmp’
               Same as the SNMP above but requires use of the net-snmp
               library.  Unless you have a specific need for this old
               driver, you should use the ‘'snmp’ instead.

          ‘dumb’
               An old serial character device for use with
               simple-signaling UPSes.

          ‘pcnet’
               A PowerChute Network Shutdown protocol which can be used
               as an alternative to an SNMP with the AP9617 family of
               smart slot cards.

          ‘modbus’
               A serial device for use with newest SmartUPS models
               supporting the MODBUS protocol.

     ‘device’ (default: ‘""’) (type: string)
          For USB UPSes, usually you want to set this to an empty string
          (the default).  For other UPS types, you must specify an
          appropriate port or address.

          ‘apcsmart’
               Set to the appropriate ‘/dev/tty**’ device.

          ‘usb’
               A null string setting enables auto-detection, which is
               the best choice for most installations.

          ‘net’
               Set to ‘HOSTNAME:PORT’.

          ‘snmp’
               Set to ‘HOSTNAME:PORT:VENDOR:COMMUNITY’.  The HOSTNAME is
               the ip address or hostname of the UPS on the network.
               The VENDOR can be can be "APC" or "APC_NOTRAP".
               "APC_NOTRAP" will disable SNMP trap catching; you usually
               want "APC". The PORT is usually 161.  The COMMUNITY is
               usually "private".

          ‘netsnmp’
               Same as the ‘'snmp’.

          ‘dumb’
               Set to the appropriate ‘/dev/tty**’ device.

          ‘pcnet’
               Set to ‘IPADDR:USERNAME:PASSPHRASE:PORT’.  The IPADDR is
               the IP address of the UPS management card.  The USERNAME
               and the PASSPHRASE are the credentials for which the card
               has been configured.  The PORT is the port number on
               which to listen for messages from the UPS, normally 3052.
               If this parameter is empty or missing, the default of
               3052 will be used.

          ‘modbus’
               Set to the appropriate ‘/dev/tty**’ device.  You can also
               leave it empty for MODBUS over USB or set to the serial
               number of the UPS.

     ‘poll-time’ (default: ‘60’) (type: integer)
          The interval (in seconds) at which apcupsd polls the UPS for
          status.  This setting applies both to directly-attached UPSes
          (apcsmart, usb, dumb) and networked UPSes (net, snmp).
          Lowering this setting will improve the apcupsd’s
          responsiveness to certain events at the cost of higher CPU
          utilization.

     ‘on-batery-delay’ (default: ‘6’) (type: integer)
          The time in seconds from when a power failure is detected
          until we react to it with an onbattery event.  The ‘'powerout’
          event will be triggered immediately when a power failure is
          detected.  However, the ‘'onbattery’ event will be trigger
          only after this delay.

     ‘battery-level’ (default: ‘5’) (type: integer)
          If during a power failure, the remaining battery percentage
          (as reported by the UPS) is below or equal to this value, the
          apcupsd will initiate a system shutdown.

               Note: ‘battery-level’, ‘remaining-minutes’, and ‘timeout’
               work in a conjunction, so the first that occurs will
               cause the initiation of a shutdown.

     ‘remaining-minutes’ (default: ‘3’) (type: integer)
          If during a power failure, the remaining runtime in minutes
          (as calculated internally by the UPS) is below or equal to
          this value, apcupsd will initiate a system shutdown.

               Note: ‘battery-level’, ‘remaining-minutes’, and ‘timeout’
               work in a conjunction, so the first that occurs will
               cause the initiation of a shutdown.

     ‘timeout’ (default: ‘0’) (type: integer)
          If during a power failure, the UPS has run on batteries for
          this many seconds or longer, apcupsd will initiate a system
          shutdown.  The value of 0 disables this timer.

               Note: ‘battery-level’, ‘remaining-minutes’, and ‘timeout’
               work in a conjunction, so the first that occurs will
               cause the initiation of a shutdown.

     ‘annoy-interval’ (default: ‘300’) (type: integer)
          The time in seconds between annoying users (via the ‘'annoyme’
          event) to sign off prior to system shutdown.  0 disables.

     ‘annoy-delay’ (default: ‘60’) (type: integer)
          The initial delay in seconds after a power failure before
          warning users to get off the system.

     ‘no-logon’ (default: ‘disable’) (type: enum-no-logon)
          The condition which determines when users are prevented from
          logging in during a power failure.

     ‘kill-delay’ (default: ‘0’) (type: integer)
          If this is non-zero, the apcupsd will continue running after a
          shutdown has been requested, and after the specified time in
          seconds attempt to kill the power.  This is for use on systems
          where apcupsd cannot regain control after a shutdown.

     ‘net-server’ (default: ‘#f’) (type: boolean)
          If enabled, a network information server process will be
          started.

     ‘net-server-ip’ (default: ‘"127.0.0.1"’) (type: string)
          An IP address on which the NIS server will listen for incoming
          connections.

     ‘net-server-port’ (default: ‘3551’) (type: integer)
          An IP port on which the NIS server will listen for incoming
          connections.

     ‘net-server-events-file’ (type: maybe-string)
          If you want the last few EVENTS to be available over the
          network by the network information server, you must set this
          to a file name.

     ‘net-server-events-file-max-size’ (default: ‘10’) (type: integer)
          The maximum size of the events file in kilobytes.

     ‘class’ (default: ‘standalone’) (type: enum-class)
          Normally standalone unless you share an UPS using an APC
          ShareUPS card.

     ‘mode’ (default: ‘disable’) (type: enum-mode)
          Normally disable unless you share an UPS using an APC ShareUPS
          card.

     ‘stat-time’ (default: ‘0’) (type: integer)
          The time interval in seconds between writing the status file,
          0 disables.

     ‘log-stats’ (default: ‘#f’) (type: boolean)
          Also write the stats as a logs.  This generates a lot of
          output.

     ‘data-time’ (default: ‘0’) (type: integer)
          The time interval in seconds between writing the data records
          to the log file, 0 disables.

     ‘facility’ (type: maybe-string)
          The logging facility for the syslog.

     ‘event-handlers’ (type: apcupsd-event-handlers)
          Handlers for events produced by apcupsd.

 -- Data Type: apcupsd-event-handlers

     For a description of the events please refer to ‘man 8 apccontrol’.

     Each handler shall be a gexp.  It is spliced into the control
     script for the daemon.  In addition to the standard Guile
     programming environment, the following procedures and variables are
     also available:

     ‘conf’
          Variable containing the file name of the configuration file.

     ‘powerfail-file’
          Variable containing the file name of the powerfail file.

     ‘cmd’
          The event currently being handled.

     ‘name’
          The name of the UPS as specified in the configuration file.

     ‘connected?’
          Is ‘#t’ if ‘apcupsd’ is connected to the UPS via a serial port
          (or a USB port).  In most configurations, this will be the
          case.  In the case of a Slave machine where apcupsd is not
          directly connected to the UPS, this value will be ‘#f’.

     ‘powered?’
          Is ‘#t’ if the computer on which ‘apcupsd’ is running is
          powered by the UPS and ‘#f’ if not.  At the moment, this value
          is unimplemented and always ‘#f’.

     ‘(err FMT ARGS...)’
          Wrapper around ‘format’ outputting to ‘(current-error-port)’.

     ‘(wall FMT ARGS...)’
          Wrapper around ‘format’ outputting via ‘wall’.

     ‘(apcupsd ARGS...)’
          Call ‘apcupsd’ while passing the correct configuration file
          and all the arguments.

     ‘(mail-to-root SUBJECT BODY)’
          Send an email to the local administrator.  This procedure
          assumes the ‘sendmail’ is located at
          ‘/run/privileged/bin/sendmail’ (as would be the case with
          ‘opensmtpd-service-type’).

     Available ‘apcupsd-event-handlers’ fields are:

     ‘modules’ (type: gexp)
          Additional modules to import into the generated handler
          script.

     ‘killpower’ (type: gexp)
          The handler for the killpower event.

     ‘commfailure’ (type: gexp)
          The handler for the commfailure event.

     ‘commok’ (type: gexp)
          The handler for the commfailure event.

     ‘powerout’ (type: gexp)
          The handler for the powerout event.

     ‘onbattery’ (type: gexp)
          The handler for the onbattery event.

     ‘offbattery’ (type: gexp)
          The handler for the offbattery event.

     ‘mainsback’ (type: gexp)
          The handler for the mainsback event.

     ‘failing’ (type: gexp)
          The handler for the failing event.

     ‘timeout’ (type: gexp)
          The handler for the timeout event.

     ‘loadlimit’ (type: gexp)
          The handler for the loadlimit event.

     ‘runlimit’ (type: gexp)
          The handler for the runlimit event.

     ‘doreboot’ (type: gexp)
          The handler for the doreboot event.

     ‘doshutdown’ (type: gexp)
          The handler for the doshutdown event.

     ‘annoyme’ (type: gexp)
          The handler for the annoyme event.

     ‘emergency’ (type: gexp)
          The handler for the emergency event.

     ‘changeme’ (type: gexp)
          The handler for the changeme event.

     ‘remotedown’ (type: gexp)
          The handler for the remotedown event.

     ‘startselftest’ (type: gexp)
          The handler for the startselftest event.

     ‘endselftest’ (type: gexp)
          The handler for the endselftest event.

     ‘battdetach’ (type: gexp)
          The handler for the battdetach event.

     ‘battattach’ (type: gexp)
          The handler for the battattach event.


File: guix.info,  Node: Audio Services,  Next: Virtualization Services,  Prev: Power Management Services,  Up: Services

11.10.30 Audio Services
-----------------------

The ‘(gnu services audio)’ module provides a service to start MPD (the
Music Player Daemon).

Music Player Daemon
...................

The Music Player Daemon (MPD) is a service that can play music while
being controlled from the local machine or over the network by a variety
of clients.

   The following example shows the simplest configuration to locally
expose, via PulseAudio, a music collection kept at ‘/srv/music’, with
‘mpd’ running as the default ‘mpd’ user.  This user will spawn its own
PulseAudio daemon, which may compete for the sound card access with that
of your own user.  In this configuration, you may have to stop the
playback of your user audio applications to hear MPD’s output and
vice-versa.

     (service mpd-service-type
              (mpd-configuration
               (music-directory "/srv/music")))

     Important: The music directory must be readable to the MPD user, by
     default, ‘mpd’.  Permission problems will be reported via
     ‘Permission denied’ errors in the MPD logs, which appear in
     ‘/var/log/messages’ by default.

   Most MPD clients will trigger a database update upon connecting, but
you can also use the ‘update’ action do to so:

     herd update mpd

   All the MPD configuration fields are documented below, and a more
complex example follows.

 -- Variable: mpd-service-type
     The service type for ‘mpd’

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

     ‘package’ (default: ‘mpd’) (type: file-like)
          The MPD package.

     ‘user’ (type: user-account)
          The user to run mpd as.

     ‘group’ (type: user-group)
          The group to run mpd as.

          The default ‘%mpd-group’ is a system group with name “mpd”.

     ‘shepherd-requirement’ (default: ‘'()’) (type: list-of-symbols)
          A list of symbols naming Shepherd services that this service
          will depend on.

     ‘environment-variables’ (default: ‘'("PULSE_CLIENTCONFIG=/etc/pulse/client.conf" "PULSE_CONFIG=/etc/pulse/daemon.conf")’) (type: list-of-strings)
          A list of strings specifying environment variables.

     ‘log-file’ (type: maybe-string)
          The location of the log file.  Unless specified, logs are sent
          to the local syslog daemon.  Alternatively, a log file name
          can be specified, for example ‘/var/log/mpd.log’.

     ‘log-level’ (type: maybe-string)
          Suppress any messages below this threshold.  The available
          values, in decreasing order of verbosity, are: ‘verbose’,
          ‘info’, ‘notice’, ‘warning’ and ‘error’.

     ‘music-directory’ (type: maybe-string)
          The directory to scan for music files.

     ‘music-dir’ (type: maybe-string)
          The directory to scan for music files.

     ‘playlist-directory’ (type: maybe-string)
          The directory to store playlists.

     ‘playlist-dir’ (type: maybe-string)
          The directory to store playlists.

     ‘db-file’ (type: maybe-string)
          The location of the music database.  When left unspecified,
          ‘~/.cache/db’ is used.

     ‘state-file’ (type: maybe-string)
          The location of the file that stores current MPD’s state.

     ‘sticker-file’ (type: maybe-string)
          The location of the sticker database.

     ‘default-port’ (default: ‘6600’) (type: maybe-port)
          The default port to run mpd on.

     ‘endpoints’ (type: maybe-list-of-strings)
          The addresses that mpd will bind to.  A port different from
          DEFAULT-PORT may be specified, e.g.  ‘localhost:6602’ and IPv6
          addresses must be enclosed in square brackets when a different
          port is used.  To use a Unix domain socket, an absolute path
          or a path starting with ‘~’ can be specified here.

     ‘address’ (type: maybe-string)
          The address that mpd will bind to.  To use a Unix domain
          socket, an absolute path can be specified here.

     ‘database’ (type: maybe-mpd-plugin)
          MPD database plugin configuration.

     ‘partitions’ (default: ‘'()’) (type: list-of-mpd-partition)
          List of MPD "partitions".

     ‘neighbors’ (default: ‘'()’) (type: list-of-mpd-plugin)
          List of MPD neighbor plugin configurations.

     ‘inputs’ (default: ‘'()’) (type: list-of-mpd-plugin)
          List of MPD input plugin configurations.

     ‘archive-plugins’ (default: ‘'()’) (type: list-of-mpd-plugin)
          List of MPD archive plugin configurations.

     ‘auto-update?’ (type: maybe-boolean)
          Whether to automatically update the music database when files
          are changed in the MUSIC-DIRECTORY.

     ‘input-cache-size’ (type: maybe-string)
          MPD input cache size.

     ‘decoders’ (default: ‘'()’) (type: list-of-mpd-plugin)
          List of MPD decoder plugin configurations.

     ‘resampler’ (type: maybe-mpd-plugin)
          MPD resampler plugin configuration.

     ‘filters’ (default: ‘'()’) (type: list-of-mpd-plugin)
          List of MPD filter plugin configurations.

     ‘outputs’ (type: list-of-mpd-plugin-or-output)
          The audio outputs that MPD can use.  By default this is a
          single output using pulseaudio.

     ‘playlist-plugins’ (default: ‘'()’) (type: list-of-mpd-plugin)
          List of MPD playlist plugin configurations.

     ‘extra-options’ (default: ‘'()’) (type: alist)
          An association list of option symbols/strings to string values
          to be appended to the configuration.

 -- Data Type: mpd-plugin
     Data type representing a ‘mpd’ plugin.

     ‘plugin’ (type: maybe-string)
          Plugin name.

     ‘name’ (type: maybe-string)
          Name.

     ‘enabled?’ (type: maybe-boolean)
          Whether the plugin is enabled/disabled.

     ‘extra-options’ (default: ‘'()’) (type: alist)
          An association list of option symbols/strings to string values
          to be appended to the plugin configuration.  See MPD plugin
          reference (https://mpd.readthedocs.io/en/latest/plugins.html)
          for available options.

 -- Data Type: mpd-partition
     Data type representing a ‘mpd’ partition.

     ‘name’ (type: string)
          Partition name.

     ‘extra-options’ (default: ‘'()’) (type: alist)
          An association list of option symbols/strings to string values
          to be appended to the partition configuration.  See
          Configuring Partitions
          (https://mpd.readthedocs.io/en/latest/user.html#configuring-partitions)
          for available options.

 -- Data Type: mpd-output
     Available ‘mpd-output’ fields are:

     ‘name’ (default: ‘"MPD"’) (type: string)
          The name of the audio output.

     ‘type’ (default: ‘"pulse"’) (type: string)
          The type of audio output.

     ‘enabled?’ (default: ‘#t’) (type: boolean)
          Specifies whether this audio output is enabled when MPD is
          started.  By default, all audio outputs are enabled.  This is
          just the default setting when there is no state file; with a
          state file, the previous state is restored.

     ‘format’ (type: maybe-string)
          Force a specific audio format on output.  See Global Audio
          Format
          (https://mpd.readthedocs.io/en/latest/user.html#audio-output-format)
          for a more detailed description.

     ‘tags?’ (default: ‘#t’) (type: boolean)
          If set to ‘#f’, then MPD will not send tags to this output.
          This is only useful for output plugins that can receive tags,
          for example the ‘httpd’ output plugin.

     ‘always-on?’ (default: ‘#f’) (type: boolean)
          If set to ‘#t’, then MPD attempts to keep this audio output
          always open.  This may be useful for streaming servers, when
          you don’t want to disconnect all listeners even when playback
          is accidentally stopped.

     ‘mixer-type’ (type: maybe-string)
          This field accepts a string that specifies which mixer should
          be used for this audio output: the ‘hardware’ mixer, the
          ‘software’ mixer, the ‘null’ mixer (allows setting the volume,
          but with no effect; this can be used as a trick to implement
          an external mixer External Mixer) or no mixer (‘none’).  When
          left unspecified, a ‘hardware’ mixer is used for devices that
          support it.

     ‘replay-gain-handler’ (type: maybe-string)
          This field accepts a string that specifies how Replay Gain
          (https://mpd.readthedocs.io/en/latest/user.html#replay-gain)
          is to be applied.  ‘software’ uses an internal software volume
          control, ‘mixer’ uses the configured (hardware) mixer control
          and ‘none’ disables replay gain on this audio output.

     ‘extra-options’ (default: ‘'()’) (type: alist)
          An association list of option symbols/strings to string values
          to be appended to the audio output configuration.

   The following example shows a configuration of ‘mpd’ that configures
some of its plugins and provides a HTTP audio streaming output.

     (service mpd-service-type
              (mpd-configuration
                (outputs
                  (list (mpd-output
                          (name "streaming")
                          (type "httpd")
                          (mixer-type 'null)
                          (extra-options
                           `((encoder . "vorbis")
                             (port    . "8080"))))))
                (decoders
                  (list (mpd-plugin
                          (plugin "mikmod")
                          (enabled? #f))
                        (mpd-plugin
                          (plugin "openmpt")
                          (enabled? #t)
                          (extra-options `((repeat-count . -1)
                                           (interpolation-filter . 1))))))
                (resampler (mpd-plugin
                             (plugin "libsamplerate")
                             (extra-options `((type . 0)))))))

myMPD
.....

myMPD (https://jcorporation.github.io/myMPD/) is a web server frontend
for MPD that provides a mobile friendly web client for MPD.

   The following example shows a myMPD instance listening on port 80,
with album cover caching disabled.

     (service mympd-service-type
              (mympd-configuration
               (port 80)
               (covercache-ttl 0)))

 -- Variable: mympd-service-type
     The service type for ‘mympd’.

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

     ‘package’ (default: ‘mympd’) (type: file-like)
          The package object of the myMPD server.

     ‘shepherd-requirement’ (default: ‘'()’) (type: list-of-symbols)
          This is a list of symbols naming Shepherd services that this
          service will depend on.

     ‘user’ (default: ‘%mympd-user’) (type: user-account)
          Owner of the ‘mympd’ process.

          The default ‘%mympd-user’ is a system user with the name
          “mympd”, who is a part of the group GROUP (see below).

     ‘group’ (default: ‘%mympd-group’) (type: user-group)
          Owner group of the ‘mympd’ process.

          The default ‘%mympd-group’ is a system group with name
          “mympd”.
     ‘work-directory’ (default: ‘"/var/lib/mympd"’) (type: string)
          Where myMPD will store its data.

     ‘cache-directory’ (default: ‘"/var/cache/mympd"’) (type: string)
          Where myMPD will store its cache.

     ‘acl’ (type: maybe-mympd-ip-acl)
          ACL to access the myMPD webserver.

     ‘covercache-ttl’ (default: ‘31’) (type: maybe-integer)
          How long to keep cached covers, ‘0’ disables cover caching.

     ‘http?’ (default: ‘#t’) (type: boolean)
          HTTP support.

     ‘host’ (default: ‘"[::]"’) (type: string)
          Host name to listen on.

     ‘port’ (default: ‘80’) (type: maybe-port)
          HTTP port to listen on.

     ‘log-level’ (default: ‘5’) (type: integer)
          How much detail to include in logs, possible values: ‘0’ to
          ‘7’.

     ‘log-to’ (type: maybe-string)
          Where to send logs.  Unless specified, the service logs to the
          local syslog service under the ‘daemon’ facility.
          Alternatively, a log file name can be specified, for example
          ‘/var/log/mympd.log’.

     ‘lualibs’ (default: ‘"all"’) (type: maybe-string)
          See
          <https://jcorporation.github.io/myMPD/scripting/#lua-standard-libraries>.

     ‘uri’ (type: maybe-string)
          Override URI to myMPD. See
          <https://github.com/jcorporation/myMPD/issues/950>.

     ‘script-acl’ (default: ‘(mympd-ip-acl (allow '("127.0.0.1")))’) (type: maybe-mympd-ip-acl)
          ACL to access the myMPD script backend.

     ‘ssl?’ (default: ‘#f’) (type: boolean)
          SSL/TLS support.

     ‘ssl-port’ (default: ‘443’) (type: maybe-port)
          Port to listen for HTTPS.

     ‘ssl-cert’ (type: maybe-string)
          Path to PEM encoded X.509 SSL/TLS certificate (public key).

     ‘ssl-key’ (type: maybe-string)
          Path to PEM encoded SSL/TLS private key.

     ‘pin-hash’ (type: maybe-string)
          SHA-256 hashed pin used by myMPD to control settings access by
          prompting a pin from the user.

     ‘save-caches?’ (type: maybe-boolean)
          Whether to preserve caches between service restarts.

 -- Data Type: mympd-ip-acl
     Available ‘mympd-ip-acl’ fields are:

     ‘allow’ (default: ‘'()’) (type: list-of-strings)
          Allowed IP addresses.

     ‘deny’ (default: ‘'()’) (type: list-of-strings)
          Disallowed IP addresses.


File: guix.info,  Node: Virtualization Services,  Next: Version Control Services,  Prev: Audio Services,  Up: Services

11.10.31 Virtualization Services
--------------------------------

The ‘(gnu services virtualization)’ module provides services for the
libvirt and virtlog daemons, as well as other virtualization-related
services.

Libvirt daemon
..............

‘libvirtd’ is the server side daemon component of the libvirt
virtualization management system.  This daemon runs on host servers and
performs required management tasks for virtualized guests.  To connect
to the libvirt daemon as an unprivileged user, it must be added to the
‘libvirt’ group, as shown in the example below.

 -- Variable: libvirt-service-type
     This is the type of the libvirt daemon (https://libvirt.org).  Its
     value must be a ‘libvirt-configuration’.

          (users (cons (user-account
                        (name "user")
                        (group "users")
                        (supplementary-groups '("libvirt"
                                                "audio" "video" "wheel")))
                       %base-user-accounts))
          (service libvirt-service-type
                   (libvirt-configuration
                    (tls-port "16555")))

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

     ‘libvirt’ (default: ‘libvirt’) (type: file-like)
          Libvirt package.

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

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

     ‘requirement’ (default: ‘'()’) (type: list-of-symbols)
          Shepherd services dependencies to the provisioned Shepherd
          service.

     ‘firmwares’ (default: ‘(ovmf-x86-64)’) (type: list-of-file-likes)
          List of UEFI/BIOS firmware packages to make available.  Each
          firmware package should contain a
          ‘share/qemu/firmware/NAME.json’ QEMU firmware metadata file.

     ‘listen-tls?’ (default: ‘#t’) (type: boolean)
          Flag listening for secure TLS connections on the public TCP/IP
          port.  must set ‘listen’ for this to have any effect.  It is
          necessary to setup a CA and issue server certificates before
          using this capability.

     ‘listen-tcp?’ (default: ‘#f’) (type: boolean)
          Listen for unencrypted TCP connections on the public TCP/IP
          port.  must set ‘listen’ for this to have any effect.  Using
          the TCP socket requires SASL authentication by default.  Only
          SASL mechanisms which support data encryption are allowed.
          This is DIGEST_MD5 and GSSAPI (Kerberos5).

     ‘tls-port’ (default: ‘"16514"’) (type: string)
          Port for accepting secure TLS connections This can be a port
          number, or service name.

     ‘tcp-port’ (default: ‘"16509"’) (type: string)
          Port for accepting insecure TCP connections This can be a port
          number, or service name.

     ‘listen-addr’ (default: ‘"0.0.0.0"’) (type: string)
          IP address or hostname used for client connections.

     ‘mdns-adv?’ (default: ‘#f’) (type: boolean)
          Flag toggling mDNS advertisement of the libvirt service.

     ‘mdns-name’ (default: ‘"Virtualization Host terra"’) (type: string)
          Default mDNS advertisement name.  This must be unique on the
          immediate broadcast network.

     ‘unix-sock-group’ (default: ‘"libvirt"’) (type: string)
          UNIX domain socket group ownership.  This can be used to allow
          a trusted set of users access to management capabilities
          without becoming root.

     ‘unix-sock-ro-perms’ (default: ‘"0777"’) (type: string)
          UNIX socket permissions for the R/O socket.  This is used for
          monitoring VM status only.

     ‘unix-sock-rw-perms’ (default: ‘"0770"’) (type: string)
          UNIX socket permissions for the R/W socket.  Default allows
          only root.  If PolicyKit is enabled on the socket, the default
          will change to allow everyone (e.g., ‘"0777"’).

     ‘unix-sock-admin-perms’ (default: ‘"0777"’) (type: string)
          UNIX socket permissions for the admin socket.  Default allows
          only owner (root), do not change it unless you are sure to
          whom you are exposing the access to.

     ‘unix-sock-dir’ (default: ‘"/var/run/libvirt"’) (type: string)
          The directory in which sockets will be found/created.

     ‘auth-unix-ro’ (default: ‘"polkit"’) (type: string)
          Authentication scheme for UNIX read-only sockets.  By default
          socket permissions allow anyone to connect.

     ‘auth-unix-rw’ (default: ‘"polkit"’) (type: string)
          Authentication scheme for UNIX read-write sockets.  By default
          socket permissions only allow root.  If PolicyKit support was
          compiled into libvirt, the default will be to use ’polkit’
          auth.

     ‘auth-tcp’ (default: ‘"sasl"’) (type: string)
          Authentication scheme for TCP sockets.  If you don’t enable
          SASL, then all TCP traffic is cleartext.  Don’t do this
          outside of a development/test scenario.

     ‘auth-tls’ (default: ‘"none"’) (type: string)
          Authentication scheme for TLS sockets.  TLS sockets already
          have encryption provided by the TLS layer, and limited
          authentication is done by certificates.  It is possible to
          make use of any SASL authentication mechanism as well, by
          using ‘"sasl"’ for this option

     ‘access-drivers’ (default: ‘()’) (type: optional-list)
          API access control scheme.  By default an authenticated user
          is allowed access to all APIs.  Access drivers can place
          restrictions on this.

     ‘key-file’ (default: ‘""’) (type: string)
          Server key file path.  If set to an empty string, then no
          private key is loaded.

     ‘cert-file’ (default: ‘""’) (type: string)
          Server key file path.  If set to an empty string, then no
          certificate is loaded.

     ‘ca-file’ (default: ‘""’) (type: string)
          Server key file path.  If set to an empty string, then no CA
          certificate is loaded.

     ‘crl-file’ (default: ‘""’) (type: string)
          Certificate revocation list path.  If set to an empty string,
          then no CRL is loaded.

     ‘tls-no-sanity-cert’ (default: ‘#f’) (type: boolean)
          Disable verification of our own server certificates.  When
          ‘libvirtd’ starts it performs some sanity checks against its
          own certificates.

     ‘tls-no-verify-cert’ (default: ‘#f’) (type: boolean)
          Disable verification of client certificates.  Client
          certificate verification is the primary authentication
          mechanism.  Any client which does not present a certificate
          signed by the CA will be rejected.

     ‘tls-allowed-dn-list’ (default: ‘()’) (type: optional-list)
          Whitelist of allowed x509 Distinguished Name.

     ‘sasl-allowed-usernames’ (default: ‘()’) (type: optional-list)
          Whitelist of allowed SASL usernames.  The format for username
          depends on the SASL authentication mechanism.

     ‘tls-priority’ (default: ‘"NORMAL"’) (type: string)
          Override the compile time default TLS priority string.  The
          default is usually "NORMAL" unless overridden at build time.
          Only set this if it is desired for libvirt to deviate from the
          global default settings.

     ‘max-clients’ (default: ‘5000’) (type: integer)
          Maximum number of concurrent client connections to allow over
          all sockets combined.

     ‘max-queued-clients’ (default: ‘1000’) (type: integer)
          Maximum length of queue of connections waiting to be accepted
          by the daemon.  Note, that some protocols supporting
          re-transmission may obey this so that a later reattempt at
          connection succeeds.

     ‘max-anonymous-clients’ (default: ‘20’) (type: integer)
          Maximum length of queue of accepted but not yet authenticated
          clients.  Set this to zero to turn this feature off.

     ‘min-workers’ (default: ‘5’) (type: integer)
          Number of workers to start up initially.

     ‘max-workers’ (default: ‘20’) (type: integer)
          Maximum number of worker threads.  If the number of active
          clients exceeds ‘min-workers’, then more threads are spawned,
          up to ‘max_workers’ limit.  Typically you’d want ‘max_workers’
          to equal maximum number of clients allowed.

     ‘prio-workers’ (default: ‘5’) (type: integer)
          Number of priority workers.  If all workers from above pool
          are stuck, some calls marked as high priority (notably
          domainDestroy) can be executed in this pool.

     ‘max-requests’ (default: ‘20’) (type: integer)
          Total global limit on concurrent RPC calls.

     ‘max-client-requests’ (default: ‘5’) (type: integer)
          Limit on concurrent requests from a single client connection.
          To avoid one client monopolizing the server this should be a
          small fraction of the global max_requests and max_workers
          parameter.

     ‘admin-min-workers’ (default: ‘1’) (type: integer)
          Same as ‘min-workers’ but for the admin interface.

     ‘admin-max-workers’ (default: ‘5’) (type: integer)
          Same as ‘max-workers’ but for the admin interface.

     ‘admin-max-clients’ (default: ‘5’) (type: integer)
          Same as ‘max-clients’ but for the admin interface.

     ‘admin-max-queued-clients’ (default: ‘5’) (type: integer)
          Same as ‘max-queued-clients’ but for the admin interface.

     ‘admin-max-client-requests’ (default: ‘5’) (type: integer)
          Same as ‘max-client-requests’ but for the admin interface.

     ‘log-level’ (default: ‘3’) (type: integer)
          Semi-deprecated option for the logging level: using the
          ‘log-filters’ option instead is recommend, as it provides
          finer control.  The log level can be set to ‘4’ for errors,
          ‘3’ for warnings, ‘2’ for information or ‘1’ for debug.  Note
          that since ‘log-filters’ and ‘log-outputs’ take precedence
          over this option, you will need to also adjust their logging
          levels to avoid filtering out messages.

     ‘log-filters’ (default: ‘"3:remote 4:event"’) (type: string)
          Logging filters.  A filter allows selecting a different
          logging level for a given category of logs.  The format for a
          filter is either ‘X:NAME’ or ‘X:+NAME’, where name is a string
          which is matched against the category given in the
          ‘VIR_LOG_INIT()’ at the top of each libvirt source file, e.g.,
          ‘"remote"’, ‘"qemu"’, or ‘"util.json"’.  NAME can be a
          substring of the full category name, in order to match
          multiple similar categories.  The optional ‘+’ prefix tells
          libvirt to log stack traces for each message matching NAME.  X
          is the log level value used to filter the associated message
          category.  X can be set to ‘4’ for errors, ‘3’ for warnings,
          ‘2’ for information, or ‘1’ for debug.  Multiple filters can
          be defined in a single filters statement, as space-separated
          values.  Since ‘log-outputs’ also include a level filter, you
          may need to also adjust its value to see all the filtered
          messages.

     ‘log-outputs’ (default: ‘"3:syslog:libvirtd"’) (type: string)
          Logging outputs.  An output is one of the places to save
          logging information.  The format for an output has the form
          ‘"X:var{output}"’, where OUTPUT can be ‘stderr’,
          ‘syslog:NAME’, where NAME is the syslog ‘ident’ value to use,
          or ‘file:FILE_NAME’, where FILE_NAME is the file name of the
          file to output to.  X is the minimal level, which acts as a
          filter.  X can be set to X can be set to ‘4’ for errors, ‘3’
          for warnings, ‘2’ for information, or ‘1’ for debug.  Multiple
          filters can be defined in a single filters statement, as
          space-separated values.

     ‘audit-level’ (default: ‘1’) (type: integer)
          Modify the behavior of the auditing subsystem.  ‘0’ disables
          all auditing, samp{1} enables auditing only if enabled on
          thehost and ‘2’ enables auditing but exits if it is disabled
          on the host.

     ‘audit-logging’ (default: ‘#f’) (type: boolean)
          Send audit messages via libvirt logging infrastructure.

     ‘host-uuid’ (default: ‘""’) (type: optional-string)
          Host UUID. UUID must not have all digits be the same.

     ‘host-uuid-source’ (default: ‘"smbios"’) (type: string)
          Source to read host UUID. Use ‘"smbios"’ to fetch the UUID via
          ‘dmidecode -s system-uuid’, or ‘"machine-id"’ to fetch the
          UUID from ‘/etc/machine-id’.  If ‘dmidecode’ does not provide
          a valid UUID a temporary UUID will be generated.

     ‘keepalive-interval’ (default: ‘5’) (type: integer)
          A keepalive message is sent to a client after
          ‘keepalive_interval’ seconds of inactivity to check if the
          client is still responding.  If set to ‘-1’, libvirtd won’t
          send keepalive requests; however clients can still send them
          and the daemon will send responses.

     ‘keepalive-count’ (default: ‘5’) (type: integer)
          Maximum number of keepalive messages that are allowed to be
          sent to the client without getting any response before the
          connection is considered broken.  In other words, the
          connection is automatically closed approximately after
          ‘keepalive_interval * (keepalive_count + 1)’ seconds since the
          last message received from the client.  When ‘keepalive-count’
          is set to ‘0’, connections will be automatically closed after
          ‘keepalive-interval’ seconds of inactivity without sending any
          keepalive messages.

     ‘admin-keepalive-interval’ (default: ‘5’) (type: integer)
          Same as above but for admin interface.

     ‘admin-keepalive-count’ (default: ‘5’) (type: integer)
          Same as above but for admin interface.

     ‘ovs-timeout’ (default: ‘5’) (type: integer)
          Timeout for Open vSwitch calls.  The ‘ovs-vsctl’ utility is
          used for the configuration and its timeout option is set by
          default to 5 seconds to avoid potential infinite waits
          blocking libvirt.

Virtlog daemon
..............

The virtlogd service is a server side daemon component of libvirt that
is used to manage logs from virtual machine consoles.

   This daemon is not used directly by libvirt client applications,
rather it is called on their behalf by ‘libvirtd’.  By maintaining the
logs in a standalone daemon, the main ‘libvirtd’ daemon can be restarted
without risk of losing logs.  The ‘virtlogd’ daemon has the ability to
re-exec() itself upon receiving ‘SIGUSR1’, to allow live upgrades
without downtime.

 -- Variable: virtlog-service-type
     This is the type of the virtlog daemon.  Its value must be a
     ‘virtlog-configuration’.

          (service virtlog-service-type
                   (virtlog-configuration
                    (max-clients 1000)))

 -- libvirt parameter: package libvirt
     Libvirt package.

 -- virtlog-configuration parameter: integer log-level
     Logging level.  4 errors, 3 warnings, 2 information, 1 debug.

     Defaults to ‘3’.

 -- virtlog-configuration parameter: string log-filters
     Logging filters.

     A filter allows to select a different logging level for a given
     category of logs The format for a filter is one of:

        • x:name

        • x:+name

     where ‘name’ is a string which is matched against the category
     given in the ‘VIR_LOG_INIT()’ at the top of each libvirt source
     file, e.g., "remote", "qemu", or "util.json" (the name in the
     filter can be a substring of the full category name, in order to
     match multiple similar categories), the optional "+" prefix tells
     libvirt to log stack trace for each message matching name, and ‘x’
     is the minimal level where matching messages should be logged:

        • 1: DEBUG

        • 2: INFO

        • 3: WARNING

        • 4: ERROR

     Multiple filters can be defined in a single filters statement, they
     just need to be separated by spaces.

     Defaults to ‘"3:remote 4:event"’.

 -- virtlog-configuration parameter: string log-outputs
     Logging outputs.

     An output is one of the places to save logging information The
     format for an output can be:

     ‘x:stderr’
          output goes to stderr

     ‘x:syslog:name’
          use syslog for the output and use the given name as the ident

     ‘x:file:file_path’
          output to a file, with the given filepath

     ‘x:journald’
          output to journald logging system

     In all case the x prefix is the minimal level, acting as a filter

        • 1: DEBUG

        • 2: INFO

        • 3: WARNING

        • 4: ERROR

     Multiple outputs can be defined, they just need to be separated by
     spaces.

     Defaults to ‘"3:stderr"’.

 -- virtlog-configuration parameter: integer max-clients
     Maximum number of concurrent client connections to allow over all
     sockets combined.

     Defaults to ‘1024’.

 -- virtlog-configuration parameter: integer max-size
     Maximum file size before rolling over.

     Defaults to ‘2MB’

 -- virtlog-configuration parameter: integer max-backups
     Maximum number of backup files to keep.

     Defaults to ‘3’

Transparent Emulation with QEMU
...............................

‘qemu-binfmt-service-type’ provides support for transparent emulation of
program binaries built for different architectures—e.g., it allows you
to transparently execute an ARMv7 program on an x86_64 machine.  It
achieves this by combining the QEMU (https://www.qemu.org) emulator and
the ‘binfmt_misc’ feature of the kernel Linux.  This feature only allows
you to emulate GNU/Linux on a different architecture, but see below for
GNU/Hurd support.

 -- Variable: qemu-binfmt-service-type
     This is the type of the QEMU/binfmt service for transparent
     emulation.  Its value must be a ‘qemu-binfmt-configuration’ object,
     which specifies the QEMU package to use as well as the architecture
     we want to emulated:

          (service qemu-binfmt-service-type
                   (qemu-binfmt-configuration
                     (platforms (lookup-qemu-platforms "arm" "aarch64"))))

     In this example, we enable transparent emulation for the ARM and
     aarch64 platforms.  Running ‘herd stop qemu-binfmt’ turns it off,
     and running ‘herd start qemu-binfmt’ turns it back on (*note the
     ‘herd’ command: (shepherd)Invoking herd.).

 -- Data Type: qemu-binfmt-configuration
     This is the configuration for the ‘qemu-binfmt’ service.

     ‘platforms’ (default: ‘'()’)
          The list of emulated QEMU platforms.  Each item must be a
          “platform object” as returned by ‘lookup-qemu-platforms’ (see
          below).

          For example, let’s suppose you’re on an x86_64 machine and you
          have this service:

               (service qemu-binfmt-service-type
                        (qemu-binfmt-configuration
                          (platforms (lookup-qemu-platforms "arm"))))

          You can run:

               guix build -s armhf-linux inkscape

          and it will build Inkscape for ARMv7 _as if it were a native
          build_, transparently using QEMU to emulate the ARMv7 CPU.
          Pretty handy if you’d like to test a package build for an
          architecture you don’t have access to!

     ‘qemu’ (default: ‘qemu’)
          The QEMU package to use.

 -- Procedure: lookup-qemu-platforms platforms...
     Return the list of QEMU platform objects corresponding to
     PLATFORMS....  PLATFORMS must be a list of strings corresponding to
     platform names, such as ‘"arm"’, ‘"sparc"’, ‘"mips64el"’, and so
     on.

 -- Procedure: qemu-platform? obj
     Return true if OBJ is a platform object.

 -- Procedure: qemu-platform-name platform
     Return the name of PLATFORM—a string such as ‘"arm"’.

QEMU Guest Agent
................

The QEMU guest agent provides control over the emulated system to the
host.  The ‘qemu-guest-agent’ service runs the agent on Guix guests.  To
control the agent from the host, open a socket by invoking QEMU with the
following arguments:

     qemu-system-x86_64 \
     	-chardev socket,path=/tmp/qga.sock,server=on,wait=off,id=qga0 \
     	-device virtio-serial \
     	-device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0 \
     	...

   This creates a socket at ‘/tmp/qga.sock’ on the host.  Once the guest
agent is running, you can issue commands with ‘socat’:

     $ guix shell socat -- socat unix-connect:/tmp/qga.sock stdio
     {"execute": "guest-get-host-name"}
     {"return": {"host-name": "guix"}}

   See QEMU guest agent documentation
(https://wiki.qemu.org/Features/GuestAgent) for more options and
commands.

 -- Variable: qemu-guest-agent-service-type
     Service type for the QEMU guest agent service.

 -- Data Type: qemu-guest-agent-configuration
     Configuration for the ‘qemu-guest-agent’ service.

     ‘qemu’ (default: ‘qemu-minimal’)
          The QEMU package to use.

     ‘device’ (default: ‘""’)
          File name of the device or socket the agent uses to
          communicate with the host.  If empty, QEMU uses a default file
          name.

Xen Guest Agent
...............

The Xen guest agent allows a Xen host to control the emulated system.
The ‘xe-guest-utilities’ service runs the agent on Guix guests.

   xe-guest-utilities (https://github.com/xenserver/xe-guest-utilities)
collects information about the running virtualized guest.  This
includes:
   • static information
        • The operating system running
        • The Linux kernel version

   • dynamic information
        • Network interfaces (devices) being added/removed
        • Network connections being unplugged/plugged-in
        • CPUs being added or removed
        • The guest migrating, being paused/resumed, etc.

   • ephemeral information
        • The amount of memory currently in-use and free
        • The amount of disk-space used

     Note: The default Linux-libre kernel that Guix ships already
     enables the necessary paravirtualization features for a guest.
     There is nothing you need to do for the guest to support Xen’s
     paravirtualization features.

     The guest utilities are used to have the guest report information
     _back_ to the virtualizing host and support tasks that require
     cooperation between host and guest, like CPU hotplugging.

 -- Variable: xe-guest-utilities-service-type
     Service type for the Xen guest utilities service.

 -- Data Type: xe-guest-utilities-configuration
     Configuration for the ‘xe-guest-utilities’ service.

     ‘package’ (default: ‘xe-guest-utilities’)
          The Xen guest utilities package to use.

     ‘pid-file’ (default: ‘"/var/run/xe-daemon.pid"’)
          Name of the file holding the PID of ‘xe-deamon’.

     ‘log-file’ (default: ‘"/var/log/xe-guest-utilities.log"’)
          Name of the ‘xe-guest-utilities’ log file.

   ‘xe-guest-utilities’ is the standard guest utilities used for Xen
guests.  More recently the Xen Project has been working to develop
‘xen-guest-agent’, a modern drop-in replacement for
‘xe-guest-utilities’.  While they nearly have feature-parity,
‘xen-guest-agent’ currently lacks some of the features of its
predecessor, namely disk metrics and “PV drivers version”.

 -- Variable: xen-guest-agent-service-type
     Service type for the Xen guest agent service.

 -- Data Type: xen-guest-agent-configuration
     Configuration for the ‘xen-guest-agent’ service.

     ‘package’ (default: ‘xen-guest-agent’)
          The Xen guest agent package to use.

     Warning: ‘xe-guest-utilities’ and ‘xen-guest-agent’ are mutually
     exclusive.

Virtual Build Machines
......................

“Virtual build machines” or “build VMs” let you offload builds to a
fully controlled environment.  “How can it be more controlled than
regular builds?  And why would it be useful?”, you ask.  Good questions.

   Builds spawned by ‘guix-daemon’ indeed run in a controlled
environment; specifically the daemon spawns build processes in separate
namespaces and in a chroot, such as that build processes only see their
declared dependencies and a well-defined subset of the file system tree
(*note Build Environment Setup::, for details).  A few aspects of the
environments are not controlled though: the operating system kernel, the
CPU model, and the date.  Most of the time, these aspects have no impact
on the build process: the level of isolation ‘guix-daemon’ provides is
“good enough”.

   However, there are occasionally cases where those aspects _do_
influence the build process.  A typical example is “time traps”: build
processes that stop working after a certain date(1).  Another one is
software that optimizes for the CPU microarchitecture it is built on or,
worse, bugs that manifest only on specific CPUs.

   To address that, ‘virtual-build-machine-service-type’ lets you add a
virtual build machine on your system, as in this example:

     (use-modules (gnu services virtualization))

     (operating-system
       ;; ...
       (services (append (list (service virtual-build-machine-service-type))
                         %base-services)))

   By default, you have to explicitly start the build machine when you
need it, at which point builds may be offloaded to it (*note Daemon
Offload Setup::):

     herd start build-vm

   With the default setting shown above, the build VM runs with its
clock set to a date several years in the past, and on a CPU model that
corresponds to that date—a model possibly older than that of your
machine.  This lets you rebuild today software from the past that would
otherwise fail to build due to a time trap or other issues in its build
process.  You can view the VM’s config like this:

     herd configuration build-vm

   You can configure the build VM, as in this example:

     (service virtual-build-machine-service-type
              (virtual-build-machine
               (cpu "Westmere")
               (cpu-count 8)
               (memory-size (* 1 1024))
               (auto-start? #t)))

   The available options are shown below.

 -- Variable: virtual-build-machine-service-type
     This is the service type to run “virtual build machines”.  Virtual
     build machines are configured so that builds are offloaded to them
     when they are running.

 -- Data Type: virtual-build-machine
     This is the data type specifying the configuration of a build
     machine.  It contains the fields below:

     ‘name’ (default: ‘'build-vm’)
          The name of this build VM. It is used to construct the name of
          its Shepherd service.

     ‘image’
          The image of the virtual machine (*note System Images::).
          This notably specifies the virtual disk size and the operating
          system running into it (*note operating-system Reference::).
          The default value is a minimal operating system image.

     ‘qemu’ (default: ‘qemu-minimal’)
          The QEMU package to run the image.

     ‘cpu’
          The CPU model being emulated as a string denoting a model
          known to QEMU.

          The default value is a model that matches ‘date’ (see below).
          To see what CPU models are available, run, for example:

               qemu-system-x86_64 -cpu help

     ‘cpu-count’ (default: ‘4’)
          The number of CPUs emulated by the virtual machine.

     ‘memory-size’ (default: ‘2048’)
          Size in mebibytes (MiB) of the virtual machine’s main memory
          (RAM).

     ‘date’ (default: a few years ago)
          Date inside the virtual machine when it starts; this must be a
          SRFI-19 date object (*note (guile)SRFI-19 Date::).

     ‘port-forwardings’ (default: 11022 and 11004)
          TCP ports of the virtual machine forwarded to the host.  By
          default, the SSH and secrets ports are forwarded into the
          host.

     ‘systems’ (default: ‘(list (%current-system))’)
          List of system types supported by the build VM—e.g.,
          ‘"x86_64-linux"’.

     ‘auto-start?’ (default: ‘#f’)
          Whether to start the virtual machine when the system boots.

   In the next section, you’ll find a variant on this theme: GNU/Hurd
virtual machines!

The Hurd in a Virtual Machine
.............................

Service ‘hurd-vm’ provides support for running GNU/Hurd in a virtual
machine (VM), a so-called “childhurd”.  This service is meant to be used
on GNU/Linux and the given GNU/Hurd operating system configuration is
cross-compiled.  The virtual machine is a Shepherd service that can be
referred to by the names ‘hurd-vm’ and ‘childhurd’ and be controlled
with commands such as:

     herd start hurd-vm
     herd stop childhurd

   When the service is running, you can view its console by connecting
to it with a VNC client, for example with:

     guix shell tigervnc-client -- vncviewer localhost:5900

   The default configuration (see ‘hurd-vm-configuration’ below) spawns
a secure shell (SSH) server in your GNU/Hurd system, which QEMU (the
virtual machine emulator) redirects to port 10022 on the host.  By
default, the service enables “offloading” such that the host
‘guix-daemon’ automatically offloads GNU/Hurd builds to the childhurd
(*note Daemon Offload Setup::).  This is what happens when running a
command like the following one, where ‘i586-gnu’ is the system type of
32-bit GNU/Hurd:

     guix build emacs-minimal -s i586-gnu

   The childhurd is volatile and stateless: it starts with a fresh root
file system every time you restart it.  By default though, all the files
under ‘/etc/childhurd’ on the host are copied as is to the root file
system of the childhurd when it boots.  This allows you to initialize
“secrets” inside the VM: SSH host keys, authorized substitute keys, and
so on—see the explanation of ‘secret-root’ below.

   You will probably find it useful to create an account for you in the
GNU/Hurd virtual machine and to authorize logins with your SSH key.  To
do that, you can define the GNU/Hurd system in the usual way (*note
Using the Configuration System::), and then pass that operating system
as the ‘os’ field of ‘hurd-vm-configuration’, as in this example:

     (define childhurd-os
       ;; Definition of my GNU/Hurd system, derived from the default one.
       (operating-system
         (inherit %hurd-vm-operating-system)

         ;; Add a user account.
         (users (cons (user-account
                       (name "charlie")
                       (comment "This is me!")
                       (group "users")
                       (supplementary-groups '("wheel"))) ;for 'sudo'
                      %base-user-accounts))

         (services
          ;; Modify the SSH configuration to allow login as "root"
          ;; and as "charlie" using public key authentication.
          (modify-services (operating-system-user-services
                            %hurd-vm-operating-system)
            (openssh-service-type
             config => (openssh-configuration
                        (inherit config)
                        (authorized-keys
                         `(("root"
                            ,(local-file
                              "/home/charlie/.ssh/id_rsa.pub"))
                           ("charlie"
                            ,(local-file
                              "/home/charlie/.ssh/id_rsa.pub"))))))))))

     (operating-system
       ;; ...
       (services
         ;; Add the 'hurd-vm' service, configured to use the
         ;; operating system configuration above.
         (append (list (service hurd-vm-service-type
                                (hurd-vm-configuration
                                  (os %childhurd-os))))
                 %base-services)))

   That’s it!  The remainder of this section provides the reference of
the service configuration.

 -- Variable: hurd-vm-service-type
     This is the type of the Hurd in a Virtual Machine service.  Its
     value must be a ‘hurd-vm-configuration’ object, which specifies the
     operating system (*note operating-system Reference::) and the disk
     size for the Hurd Virtual Machine, the QEMU package to use as well
     as the options for running it.

     For example:

          (service hurd-vm-service-type
                   (hurd-vm-configuration
                    (disk-size (* 5000 (expt 2 20))) ;5G
                    (memory-size 1024)))             ;1024MiB

     would create a disk image big enough to build GNU Hello, with some
     extra memory.

 -- Data Type: hurd-vm-configuration
     The data type representing the configuration for
     ‘hurd-vm-service-type’.

     ‘os’ (default: %HURD-VM-OPERATING-SYSTEM)
          The operating system to instantiate.  This default is
          bare-bones with a permissive OpenSSH secure shell daemon
          listening on port 2222 (*note ‘openssh-service-type’:
          Networking Services.).

     ‘qemu’ (default: ‘qemu-minimal’)
          The QEMU package to use.

     ‘type’ (default: ‘'hurd-qcow2’)
          The image type name.  Use ‘'hurd-qcow2’ for a 32-bit image or
          ‘'hurd64-qcow2’ for a 64-bit image.

     ‘image’ (default: HURD-VM-DISK-IMAGE)
          The image object representing the disk image of this virtual
          machine (*note System Images::).

          Alternatively, this can be the file name (a string) of an
          image, which is useful if you want the image to persist across
          service restarts—see example below.

     ‘disk-size’ (default: ‘'guess’)
          The size of the disk image.

     ‘memory-size’ (default: ‘512’)
          The memory size of the Virtual Machine in mebibytes.

     ‘options’ (default: ‘'("--snapshot")’)
          The extra options for running QEMU.

     ‘id’ (default: ‘#f’)
          If set, a non-zero positive integer used to parameterize
          Childhurd instances.  It is appended to the service’s name,
          e.g.  ‘childhurd1’.

     ‘net-options’ (default: HURD-VM-NET-OPTIONS)
          The procedure used to produce the list of QEMU networking
          options.

          By default, it produces

               '("--device" "rtl8139,netdev=net0"
                 "--netdev" (string-append
                             "user,id=net0,"
                             "hostfwd=tcp:127.0.0.1:SECRETS-PORT-:1004,"
                             "hostfwd=tcp:127.0.0.1:SSH-PORT-:2222,"
                             "hostfwd=tcp:127.0.0.1:VNC-PORT-:5900"))

          with forwarded ports:

               SECRETS-PORT: (+ 11004 (* 1000 ID))
               SSH-PORT: (+ 10022 (* 1000 ID))
               VNC-PORT: (+ 15900 (* 1000 ID))

     ‘offloading?’ (default: ‘#t’)
          Whether to automatically set up offloading of builds to the
          childhurd.

          When enabled, this lets you run GNU/Hurd builds on the host
          and have them transparently offloaded to the VM, for instance
          when running a command like this:

               guix build coreutils -s i586-gnu

          This option automatically sets up offloading like so:

            1. Authorizing the childhurd’s key on the host so that the
               host accepts build results coming from the childhurd,
               which can be done like so (*note ‘guix archive
               --authorize’: Invoking guix archive, for more on that).

            2. Creating a user account called ‘offloading’ dedicated to
               offloading in the childhurd.

            3. Creating an SSH key pair on the host and making it an
               authorized key of the ‘offloading’ account in the
               childhurd.

            4. Adding the childhurd to ‘/etc/guix/machines.scm’ (*note
               Daemon Offload Setup::).

     ‘secret-root’ (default: ‘/etc/childhurd’)
          The root directory with out-of-band secrets to be installed
          into the childhurd once it runs.  Childhurds are volatile
          which means that on every startup, secrets such as the SSH
          host keys and Guix signing key are recreated.

          If the ‘/etc/childhurd’ directory does not exist, the
          ‘secret-service’ running in the Childhurd will be sent an
          empty list of secrets.

          By default, the service automatically populates
          ‘/etc/childhurd’ with the following non-volatile secrets,
          unless they already exist:

               /etc/childhurd/etc/guix/acl
               /etc/childhurd/etc/guix/signing-key.pub
               /etc/childhurd/etc/guix/signing-key.sec
               /etc/childhurd/etc/ssh/authorized_keys.d/offloading
               /etc/childhurd/etc/ssh/ssh_host_ed25519_key
               /etc/childhurd/etc/ssh/ssh_host_ecdsa_key
               /etc/childhurd/etc/ssh/ssh_host_ed25519_key.pub
               /etc/childhurd/etc/ssh/ssh_host_ecdsa_key.pub

   Note that by default the VM image is volatile—i.e., once the service
is stopped, the contents are lost.  If you want a persistent image
instead, override the configuration’s ‘image’ and ‘options’ without the
‘--snapshot’ flag using something along these lines:

     (service hurd-vm-service-type
              (hurd-vm-configuration
               ;; Specify an out-of-store, persistent image.
               (image "/out/of/store/writable/hurd.img")
               (options '())))

Ganeti
......

     Note: This service is considered experimental.  Configuration
     options may be changed in a backwards-incompatible manner, and not
     all features have been thorougly tested.  Users of this service are
     encouraged to share their experience at <guix-devel@gnu.org>.

   Ganeti is a virtual machine management system.  It is designed to
keep virtual machines running on a cluster of servers even in the event
of hardware failures, and to make maintenance and recovery tasks easy.
It consists of multiple services which are described later in this
section.  In addition to the Ganeti service, you will need the OpenSSH
service (*note ‘openssh-service-type’: Networking Services.), and update
the ‘/etc/hosts’ file (*note ‘hosts-service-type’: Service Reference.)
with the cluster name and address (or use a DNS server).

   All nodes participating in a Ganeti cluster should have the same
Ganeti and ‘/etc/hosts’ configuration.  Here is an example configuration
for a Ganeti cluster node that supports multiple storage backends, and
installs the ‘debootstrap’ and ‘guix’ “OS providers”:

     (use-package-modules virtualization)
     (use-service-modules base ganeti networking ssh)
     (operating-system
       ;; ...
       (host-name "node1")

       ;; Install QEMU so we can use KVM-based instances, and LVM, DRBD and Ceph
       ;; in order to use the "plain", "drbd" and "rbd" storage backends.
       (packages (append (map specification->package
                              '("qemu" "lvm2" "drbd-utils" "ceph"
                                ;; Add the debootstrap and guix OS providers.
                                "ganeti-instance-guix" "ganeti-instance-debootstrap"))
                         %base-packages))
       (services
        (append (list (service static-networking-service-type
                               (list (static-networking
                                      (addresses
                                       (list (network-address
                                              (device "eth0")
                                              (value "192.168.1.201/24"))))
                                      (routes
                                       (list (network-route
                                              (destination "default")
                                              (gateway "192.168.1.254"))))
                                      (name-servers '("192.168.1.252"
                                                      "192.168.1.253")))))

                      ;; Ganeti uses SSH to communicate between nodes.
                      (service openssh-service-type
                               (openssh-configuration
                                (permit-root-login 'prohibit-password)))

                      (simple-service 'ganeti-hosts-entries hosts-service-type
                                      (list
                                        (host "192.168.1.200" "ganeti.example.com")
                                        (host "192.168.1.201" "node1.example.com"
                                              '("node1"))
                                        (host "192.168.1.202" "node2.example.com"
                                              '("node2"))))

                      (service ganeti-service-type
                               (ganeti-configuration
                                ;; This list specifies allowed file system paths
                                ;; for storing virtual machine images.
                                (file-storage-paths '("/srv/ganeti/file-storage"))
                                ;; This variable configures a single "variant" for
                                ;; both Debootstrap and Guix that works with KVM.
                                (os %default-ganeti-os))))
                %base-services)))

   Users are advised to read the Ganeti administrators guide
(https://docs.ganeti.org/docs/ganeti/3.0/html/admin.html) to learn about
the various cluster options and day-to-day operations.  There is also a
blog post
(https://guix.gnu.org/blog/2020/running-a-ganeti-cluster-on-guix/)
describing how to configure and initialize a small cluster.

 -- Variable: ganeti-service-type
     This is a service type that includes all the various services that
     Ganeti nodes should run.

     Its value is a ‘ganeti-configuration’ object that defines the
     package to use for CLI operations, as well as configuration for the
     various daemons.  Allowed file storage paths and available guest
     operating systems are also configured through this data type.

 -- Data Type: ganeti-configuration
     The ‘ganeti’ service takes the following configuration options:

     ‘ganeti’ (default: ‘ganeti’)
          The ‘ganeti’ package to use.  It will be installed to the
          system profile and make ‘gnt-cluster’, ‘gnt-instance’, etc
          available.  Note that the value specified here does not affect
          the other services as each refer to a specific ‘ganeti’
          package (see below).

     ‘noded-configuration’ (default: ‘(ganeti-noded-configuration)’)
     ‘confd-configuration’ (default: ‘(ganeti-confd-configuration)’)
     ‘wconfd-configuration’ (default: ‘(ganeti-wconfd-configuration)’)
     ‘luxid-configuration’ (default: ‘(ganeti-luxid-configuration)’)
     ‘rapi-configuration’ (default: ‘(ganeti-rapi-configuration)’)
     ‘kvmd-configuration’ (default: ‘(ganeti-kvmd-configuration)’)
     ‘mond-configuration’ (default: ‘(ganeti-mond-configuration)’)
     ‘metad-configuration’ (default: ‘(ganeti-metad-configuration)’)
     ‘watcher-configuration’ (default: ‘(ganeti-watcher-configuration)’)
     ‘cleaner-configuration’ (default: ‘(ganeti-cleaner-configuration)’)

          These options control the various daemons and cron jobs that
          are distributed with Ganeti.  The possible values for these
          are described in detail below.  To override a setting, you
          must use the configuration type for that service:

               (service ganeti-service-type
                        (ganeti-configuration
                         (rapi-configuration
                          (ganeti-rapi-configuration
                           (interface "eth1"))))
                         (watcher-configuration
                          (ganeti-watcher-configuration
                           (rapi-ip "10.0.0.1"))))

     ‘file-storage-paths’ (default: ‘'()’)
          List of allowed directories for file storage backend.

     ‘hooks’ (default: ‘#f’)
          When set, this should be a file-like object containing a
          directory with cluster execution hooks
          (https://docs.ganeti.org/docs/ganeti/3.0/html/hooks.html).

     ‘os’ (default: ‘%default-ganeti-os’)
          List of ‘<ganeti-os>’ records.

     In essence ‘ganeti-service-type’ is shorthand for declaring each
     service individually:

          (service ganeti-noded-service-type)
          (service ganeti-confd-service-type)
          (service ganeti-wconfd-service-type)
          (service ganeti-luxid-service-type)
          (service ganeti-kvmd-service-type)
          (service ganeti-mond-service-type)
          (service ganeti-metad-service-type)
          (service ganeti-watcher-service-type)
          (service ganeti-cleaner-service-type)

     Plus a service extension for ‘etc-service-type’ that configures the
     file storage backend and OS variants.

 -- Data Type: ganeti-os
     This data type is suitable for passing to the ‘os’ parameter of
     ‘ganeti-configuration’.  It takes the following parameters:

     ‘name’
          The name for this OS provider.  It is only used to specify
          where the configuration ends up.  Setting it to “debootstrap”
          will create ‘/etc/ganeti/instance-debootstrap’.

     ‘extension’ (default: ‘#f’)
          The file extension for variants of this OS type.  For example
          ‘.conf’ or ‘.scm’.  It will be appended to the variant file
          name if set.

     ‘variants’ (default: ‘'()’)
          This must be either a list of ‘ganeti-os-variant’ objects for
          this OS, or a “file-like” object (*note file-like objects:
          G-Expressions.) representing the variants directory.

          To use the Guix OS provider with variant definitions residing
          in a local directory instead of declaring individual variants
          (see GUIX-VARIANTS below), you can do:

               (ganeti-os
                (name "guix")
                (variants (local-file "ganeti-guix-variants"
                                      #:recursive? #true)))

          Note that you will need to maintain the ‘variants.list’ file
          (see ‘ganeti-os-interface(7)
          (https://docs.ganeti.org/docs/ganeti/3.0/man/ganeti-os-interface.html)’)
          manually in this case.

 -- Data Type: ganeti-os-variant
     This is the data type for a Ganeti OS variant.  It takes the
     following parameters:

     ‘name’
          The name of this variant.

     ‘configuration’
          A configuration file for this variant.

 -- Variable: %default-debootstrap-hooks
     This variable contains hooks to configure networking and the GRUB
     bootloader.

 -- Variable: %default-debootstrap-extra-pkgs
     This variable contains a list of packages suitable for a
     fully-virtualized guest.

 -- Data Type: debootstrap-configuration

     This data type creates configuration files suitable for the
     debootstrap OS provider.

     ‘hooks’ (default: ‘%default-debootstrap-hooks’)
          When not ‘#f’, this must be a G-expression that specifies a
          directory with scripts that will run when the OS is installed.
          It can also be a list of ‘(name . file-like)’ pairs.  For
          example:

               `((99-hello-world . ,(plain-file "#!/bin/sh\necho Hello, World")))

          That will create a directory with one executable named
          ‘99-hello-world’ and run it every time this variant is
          installed.  If set to ‘#f’, hooks in
          ‘/etc/ganeti/instance-debootstrap/hooks’ will be used, if any.
     ‘proxy’ (default: ‘#f’)
          Optional HTTP proxy to use.
     ‘mirror’ (default: ‘#f’)
          The Debian mirror.  Typically something like
          ‘http://ftp.no.debian.org/debian’.  The default varies
          depending on the distribution.
     ‘arch’ (default: ‘#f’)
          The dpkg architecture.  Set to ‘armhf’ to debootstrap an ARMv7
          instance on an AArch64 host.  Default is to use the current
          system architecture.
     ‘suite’ (default: ‘"stable"’)
          When set, this must be a Debian distribution “suite” such as
          ‘buster’ or ‘focal’.  If set to ‘#f’, the default for the OS
          provider is used.
     ‘extra-pkgs’ (default: ‘%default-debootstrap-extra-pkgs’)
          List of extra packages that will get installed by dpkg in
          addition to the minimal system.
     ‘components’ (default: ‘#f’)
          When set, must be a list of Debian repository “components”.
          For example ‘'("main" "contrib")’.
     ‘generate-cache?’ (default: ‘#t’)
          Whether to automatically cache the generated debootstrap
          archive.
     ‘clean-cache’ (default: ‘14’)
          Discard the cache after this amount of days.  Use ‘#f’ to
          never clear the cache.
     ‘partition-style’ (default: ‘'msdos’)
          The type of partition to create.  When set, it must be one of
          ‘'msdos’, ‘'none’ or a string.
     ‘partition-alignment’ (default: ‘2048’)
          Alignment of the partition in sectors.

 -- Procedure: debootstrap-variant name configuration
     This is a helper procedure that creates a ‘ganeti-os-variant’
     record.  It takes two parameters: a name and a
     ‘debootstrap-configuration’ object.

 -- Procedure: debootstrap-os variants...
     This is a helper procedure that creates a ‘ganeti-os’ record.  It
     takes a list of variants created with ‘debootstrap-variant’.

 -- Procedure: guix-variant name configuration
     This is a helper procedure that creates a ‘ganeti-os-variant’
     record for use with the Guix OS provider.  It takes a name and a
     G-expression that returns a “file-like” (*note file-like objects:
     G-Expressions.) object containing a Guix System configuration.

 -- Procedure: guix-os variants...
     This is a helper procedure that creates a ‘ganeti-os’ record.  It
     takes a list of variants produced by ‘guix-variant’.

 -- Variable: %default-debootstrap-variants
     This is a convenience variable to make the debootstrap provider
     work “out of the box” without users having to declare variants
     manually.  It contains a single debootstrap variant with the
     default configuration:

          (list (debootstrap-variant
                 "default"
                 (debootstrap-configuration)))

 -- Variable: %default-guix-variants
     This is a convenience variable to make the Guix OS provider work
     without additional configuration.  It creates a virtual machine
     that has an SSH server, a serial console, and authorizes the Ganeti
     hosts SSH keys.

          (list (guix-variant
                 "default"
                 (file-append ganeti-instance-guix
                              "/share/doc/ganeti-instance-guix/examples/dynamic.scm")))

   Users can implement support for OS providers unbeknownst to Guix by
extending the ‘ganeti-os’ and ‘ganeti-os-variant’ records appropriately.
For example:

     (ganeti-os
      (name "custom")
      (extension ".conf")
      (variants
       (list (ganeti-os-variant
              (name "foo")
              (configuration (plain-file "bar" "this is fine"))))))

   That creates ‘/etc/ganeti/instance-custom/variants/foo.conf’ which
points to a file in the store with contents ‘this is fine’.  It also
creates ‘/etc/ganeti/instance-custom/variants/variants.list’ with
contents ‘foo’.

   Obviously this may not work for all OS providers out there.  If you
find the interface limiting, please reach out to <guix-devel@gnu.org>.

   The rest of this section documents the various services that are
included by ‘ganeti-service-type’.

 -- Variable: ganeti-noded-service-type
     ‘ganeti-noded’ is the daemon responsible for node-specific
     functions within the Ganeti system.  The value of this service must
     be a ‘ganeti-noded-configuration’ object.

 -- Data Type: ganeti-noded-configuration
     This is the configuration for the ‘ganeti-noded’ service.

     ‘ganeti’ (default: ‘ganeti’)
          The ‘ganeti’ package to use for this service.

     ‘port’ (default: ‘1811’)
          The TCP port on which the node daemon listens for network
          requests.

     ‘address’ (default: ‘"0.0.0.0"’)
          The network address that the daemon will bind to.  The default
          address means bind to all available addresses.

     ‘interface’ (default: ‘#f’)
          When this is set, it must be a specific network interface
          (e.g. ‘eth0’) that the daemon will bind to.

     ‘max-clients’ (default: ‘20’)
          This sets a limit on the maximum number of simultaneous client
          connections that the daemon will handle.  Connections above
          this count are accepted, but no responses will be sent until
          enough connections have closed.

     ‘ssl?’ (default: ‘#t’)
          Whether to use SSL/TLS to encrypt network communications.  The
          certificate is automatically provisioned by the cluster and
          can be rotated with ‘gnt-cluster renew-crypto’.

     ‘ssl-key’ (default: ‘"/var/lib/ganeti/server.pem"’)
          This can be used to provide a specific encryption key for TLS
          communications.

     ‘ssl-cert’ (default: ‘"/var/lib/ganeti/server.pem"’)
          This can be used to provide a specific certificate for TLS
          communications.

     ‘debug?’ (default: ‘#f’)
          When true, the daemon performs additional logging for
          debugging purposes.  Note that this will leak encryption
          details to the log files, use with caution.

 -- Variable: ganeti-confd-service-type
     ‘ganeti-confd’ answers queries related to the configuration of a
     Ganeti cluster.  The purpose of this daemon is to have a highly
     available and fast way to query cluster configuration values.  It
     is automatically active on all “master candidates”.  The value of
     this service must be a ‘ganeti-confd-configuration’ object.

 -- Data Type: ganeti-confd-configuration
     This is the configuration for the ‘ganeti-confd’ service.

     ‘ganeti’ (default: ‘ganeti’)
          The ‘ganeti’ package to use for this service.

     ‘port’ (default: ‘1814’)
          The UDP port on which to listen for network requests.

     ‘address’ (default: ‘"0.0.0.0"’)
          Network address that the daemon will bind to.

     ‘debug?’ (default: ‘#f’)
          When true, the daemon performs additional logging for
          debugging purposes.

 -- Variable: ganeti-wconfd-service-type
     ‘ganeti-wconfd’ is the daemon that has authoritative knowledge
     about the cluster configuration and is the only entity that can
     accept changes to it.  All jobs that need to modify the
     configuration will do so by sending appropriate requests to this
     daemon.  It only runs on the “master node” and will automatically
     disable itself on other nodes.

     The value of this service must be a ‘ganeti-wconfd-configuration’
     object.

 -- Data Type: ganeti-wconfd-configuration
     This is the configuration for the ‘ganeti-wconfd’ service.

     ‘ganeti’ (default: ‘ganeti’)
          The ‘ganeti’ package to use for this service.

     ‘no-voting?’ (default: ‘#f’)
          The daemon will refuse to start if the majority of cluster
          nodes does not agree that it is running on the master node.
          Set to ‘#t’ to start even if a quorum can not be reached
          (dangerous, use with caution).

     ‘debug?’ (default: ‘#f’)
          When true, the daemon performs additional logging for
          debugging purposes.

 -- Variable: ganeti-luxid-service-type
     ‘ganeti-luxid’ is a daemon used to answer queries related to the
     configuration and the current live state of a Ganeti cluster.
     Additionally, it is the authoritative daemon for the Ganeti job
     queue.  Jobs can be submitted via this daemon and it schedules and
     starts them.

     It takes a ‘ganeti-luxid-configuration’ object.

 -- Data Type: ganeti-luxid-configuration
     This is the configuration for the ‘ganeti-luxid’ service.

     ‘ganeti’ (default: ‘ganeti’)
          The ‘ganeti’ package to use for this service.

     ‘no-voting?’ (default: ‘#f’)
          The daemon will refuse to start if it cannot verify that the
          majority of cluster nodes believes that it is running on the
          master node.  Set to ‘#t’ to ignore such checks and start
          anyway (this can be dangerous).

     ‘debug?’ (default: ‘#f’)
          When true, the daemon performs additional logging for
          debugging purposes.

 -- Variable: ganeti-rapi-service-type
     ‘ganeti-rapi’ provides a remote API for Ganeti clusters.  It runs
     on the master node and can be used to perform cluster actions
     programmatically via a JSON-based RPC protocol.

     Most query operations are allowed without authentication (unless
     REQUIRE-AUTHENTICATION? is set), whereas write operations require
     explicit authorization via the ‘/var/lib/ganeti/rapi/users’ file.
     See the Ganeti Remote API documentation
     (https://docs.ganeti.org/docs/ganeti/3.0/html/rapi.html) for more
     information.

     The value of this service must be a ‘ganeti-rapi-configuration’
     object.

 -- Data Type: ganeti-rapi-configuration
     This is the configuration for the ‘ganeti-rapi’ service.

     ‘ganeti’ (default: ‘ganeti’)
          The ‘ganeti’ package to use for this service.

     ‘require-authentication?’ (default: ‘#f’)
          Whether to require authentication even for read-only
          operations.

     ‘port’ (default: ‘5080’)
          The TCP port on which to listen to API requests.

     ‘address’ (default: ‘"0.0.0.0"’)
          The network address that the service will bind to.  By default
          it listens on all configured addresses.

     ‘interface’ (default: ‘#f’)
          When set, it must specify a specific network interface such as
          ‘eth0’ that the daemon will bind to.

     ‘max-clients’ (default: ‘20’)
          The maximum number of simultaneous client requests to handle.
          Further connections are allowed, but no responses are sent
          until enough connections have closed.

     ‘ssl?’ (default: ‘#t’)
          Whether to use SSL/TLS encryption on the RAPI port.

     ‘ssl-key’ (default: ‘"/var/lib/ganeti/server.pem"’)
          This can be used to provide a specific encryption key for TLS
          communications.

     ‘ssl-cert’ (default: ‘"/var/lib/ganeti/server.pem"’)
          This can be used to provide a specific certificate for TLS
          communications.

     ‘debug?’ (default: ‘#f’)
          When true, the daemon performs additional logging for
          debugging purposes.  Note that this will leak encryption
          details to the log files, use with caution.

 -- Variable: ganeti-kvmd-service-type
     ‘ganeti-kvmd’ is responsible for determining whether a given KVM
     instance was shut down by an administrator or a user.  Normally
     Ganeti will restart an instance that was not stopped through Ganeti
     itself.  If the cluster option ‘user_shutdown’ is true, this daemon
     monitors the ‘QMP’ socket provided by QEMU and listens for shutdown
     events, and marks the instance as “USER_down” instead of
     “ERROR_down” when it shuts down gracefully by itself.

     It takes a ‘ganeti-kvmd-configuration’ object.

 -- Data Type: ganeti-kvmd-configuration

     ‘ganeti’ (default: ‘ganeti’)
          The ‘ganeti’ package to use for this service.

     ‘debug?’ (default: ‘#f’)
          When true, the daemon performs additional logging for
          debugging purposes.

 -- Variable: ganeti-mond-service-type
     ‘ganeti-mond’ is an optional daemon that provides Ganeti monitoring
     functionality.  It is responsible for running data collectors and
     publish the collected information through a HTTP interface.

     It takes a ‘ganeti-mond-configuration’ object.

 -- Data Type: ganeti-mond-configuration

     ‘ganeti’ (default: ‘ganeti’)
          The ‘ganeti’ package to use for this service.

     ‘port’ (default: ‘1815’)
          The port on which the daemon will listen.

     ‘address’ (default: ‘"0.0.0.0"’)
          The network address that the daemon will bind to.  By default
          it binds to all available interfaces.

     ‘debug?’ (default: ‘#f’)
          When true, the daemon performs additional logging for
          debugging purposes.

 -- Variable: ganeti-metad-service-type
     ‘ganeti-metad’ is an optional daemon that can be used to provide
     information about the cluster to instances or OS install scripts.

     It takes a ‘ganeti-metad-configuration’ object.

 -- Data Type: ganeti-metad-configuration

     ‘ganeti’ (default: ‘ganeti’)
          The ‘ganeti’ package to use for this service.

     ‘port’ (default: ‘80’)
          The port on which the daemon will listen.

     ‘address’ (default: ‘#f’)
          If set, the daemon will bind to this address only.  If left
          unset, the behavior depends on the cluster configuration.

     ‘debug?’ (default: ‘#f’)
          When true, the daemon performs additional logging for
          debugging purposes.

 -- Variable: ganeti-watcher-service-type
     ‘ganeti-watcher’ is a script designed to run periodically and
     ensure the health of a cluster.  It will automatically restart
     instances that have stopped without Ganeti’s consent, and repairs
     DRBD links in case a node has rebooted.  It also archives old
     cluster jobs and restarts Ganeti daemons that are not running.  If
     the cluster parameter ‘ensure_node_health’ is set, the watcher will
     also shutdown instances and DRBD devices if the node it is running
     on is declared offline by known master candidates.

     It can be paused on all nodes with ‘gnt-cluster watcher pause’.

     The service takes a ‘ganeti-watcher-configuration’ object.

 -- Data Type: ganeti-watcher-configuration

     ‘ganeti’ (default: ‘ganeti’)
          The ‘ganeti’ package to use for this service.

     ‘schedule’ (default: ‘"*/5 * * * *"’)
          When to run the script, expressed either as a string in
          traditional cron syntax or as a gexp representing a Shepherd
          calendar event (*note (shepherd)Timers::).  The default is
          every five minutes.

     ‘rapi-ip’ (default: ‘#f’)
          This option needs to be specified only if the RAPI daemon is
          configured to use a particular interface or address.  By
          default the cluster address is used.

     ‘job-age’ (default: ‘(* 6 3600)’)
          Archive cluster jobs older than this age, specified in
          seconds.  The default is 6 hours.  This keeps ‘gnt-job list’
          manageable.

     ‘verify-disks?’ (default: ‘#t’)
          If this is ‘#f’, the watcher will not try to repair broken
          DRBD links automatically.  Administrators will need to use
          ‘gnt-cluster verify-disks’ manually instead.

     ‘debug?’ (default: ‘#f’)
          When ‘#t’, the script performs additional logging for
          debugging purposes.

 -- Variable: ganeti-cleaner-service-type
     ‘ganeti-cleaner’ is a script designed to run periodically and
     remove old files from the cluster.  This service type controls two
     “cron jobs”: one intended for the master node that permanently
     purges old cluster jobs, and one intended for every node that
     removes expired X509 certificates, keys, and outdated
     ‘ganeti-watcher’ information.  Like all Ganeti services, it is safe
     to include even on non-master nodes as it will disable itself as
     necessary.

     It takes a ‘ganeti-cleaner-configuration’ object.

 -- Data Type: ganeti-cleaner-configuration

     ‘ganeti’ (default: ‘ganeti’)
          The ‘ganeti’ package to use for the ‘gnt-cleaner’ command.

     ‘master-schedule’ (default: ‘"45 1 * * *"’)
          How often to run the master cleaning job.  The default is once
          per day, at 01:45:00.

     ‘node-schedule’ (default: ‘"45 2 * * *"’)
          How often to run the node cleaning job.  The default is once
          per day, at 02:45:00.

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

   (1) The most widespread example of time traps is test suites that
involve checking the expiration date of a certificate.  Such tests
exists in TLS implementations such as OpenSSL and GnuTLS, but also in
high-level software such as Python.


File: guix.info,  Node: Version Control Services,  Next: Game Services,  Prev: Virtualization Services,  Up: Services

11.10.32 Version Control Services
---------------------------------

The ‘(gnu services version-control)’ module provides a service to allow
remote access to local Git repositories.  There are three options: the
‘git-daemon-service-type’, which provides access to repositories via the
‘git://’ unsecured TCP-based protocol, extending the ‘nginx’ web server
to proxy some requests to ‘git-http-backend’, or providing a web
interface with ‘cgit-service-type’.

 -- Variable: git-daemon-service-type
     Type for a service that runs ‘git daemon’, a simple TCP server to
     expose repositories over the Git protocol for anonymous access.

     The value for this service type is a ‘<git-daemon-configuration>’
     record, by default it allows read-only access to exported(1)
     repositories under ‘/srv/git’.

 -- Data Type: git-daemon-configuration
     Data type representing the configuration for
     ‘git-daemon-service-type’.

     ‘package’ (default: ‘git’)
          Package object of the Git distributed version control system.

     ‘export-all?’ (default: ‘#f’)
          Whether to allow access for all Git repositories, even if they
          do not have the ‘git-daemon-export-ok’ file.

     ‘base-path’ (default: ‘/srv/git’)
          Whether to remap all the path requests as relative to the
          given path.  If you run ‘git daemon’ with ‘(base-path
          "/srv/git")’ on ‘example.com’, then if you later try to pull
          ‘git://example.com/hello.git’, git daemon will interpret the
          path as ‘/srv/git/hello.git’.

     ‘user-path’ (default: ‘#f’)
          Whether to allow ‘~user’ notation to be used in requests.
          When specified with empty string, requests to
          ‘git://host/~alice/foo’ is taken as a request to access ‘foo’
          repository in the home directory of user ‘alice’.  If
          ‘(user-path "PATH")’ is specified, the same request is taken
          as a request to access ‘PATH/foo’ repository in the home
          directory of user ‘alice’.

     ‘listen’ (default: ‘'()’)
          Whether to listen on specific IP addresses or hostnames,
          defaults to all.

     ‘port’ (default: ‘#f’)
          Whether to listen on an alternative port, which defaults to
          9418.

     ‘whitelist’ (default: ‘'()’)
          If not empty, only allow access to this list of directories.

     ‘extra-options’ (default: ‘'()’)
          Extra options that will be passed to ‘git daemon’.(2)

   The ‘git://’ protocol lacks authentication.  When you pull from a
repository fetched via ‘git://’, you don’t know whether the data you
receive was modified or is even coming from the specified host, and your
connection is subject to eavesdropping.  It’s better to use an
authenticated and encrypted transport, such as ‘https’.  Although Git
allows you to serve repositories using unsophisticated file-based web
servers, there is a faster protocol implemented by the
‘git-http-backend’ program.  This program is the back-end of a proper
Git web service.  It is designed to sit behind a FastCGI proxy.  *Note
Web Services::, for more on running the necessary ‘fcgiwrap’ daemon.

   Guix has a separate configuration data type for serving Git
repositories over HTTP.

 -- Data Type: git-http-configuration
     Data type representing the configuration for a future
     ‘git-http-service-type’; can currently be used to configure Nginx
     through ‘git-http-nginx-location-configuration’.

     ‘package’ (default: GIT)
          Package object of the Git distributed version control system.

     ‘git-root’ (default: ‘/srv/git’)
          Directory containing the Git repositories to expose to the
          world.

     ‘export-all?’ (default: ‘#f’)
          Whether to expose access for all Git repositories in GIT-ROOT,
          even if they do not have the ‘git-daemon-export-ok’ file.

     ‘uri-path’ (default: ‘/git/’)
          Path prefix for Git access.  With the default ‘/git/’ prefix,
          this will map ‘http://SERVER/git/REPO.git’ to
          ‘/srv/git/REPO.git’.  Requests whose URI paths do not begin
          with this prefix are not passed on to this Git instance.

     ‘fcgiwrap-socket’ (default: ‘127.0.0.1:9000’)
          The socket on which the ‘fcgiwrap’ daemon is listening.  *Note
          Web Services::.

   There is no ‘git-http-service-type’, currently; instead you can
create an ‘nginx-location-configuration’ from a ‘git-http-configuration’
and then add that location to a web server.

 -- Procedure: git-http-nginx-location-configuration
          [config=(git-http-configuration)]
     Compute an ‘nginx-location-configuration’ that corresponds to the
     given Git http configuration.  An example nginx service definition
     to serve the default ‘/srv/git’ over HTTPS might be:

          (service nginx-service-type
                   (nginx-configuration
                    (server-blocks
                     (list
                      (nginx-server-configuration
                       (listen '("443 ssl"))
                       (server-name "git.my-host.org")
                       (ssl-certificate
                        "/etc/certs/git.my-host.org/fullchain.pem")
                       (ssl-certificate-key
                        "/etc/certs/git.my-host.org/privkey.pem")
                       (locations
                        (list
                         (git-http-nginx-location-configuration
                          (git-http-configuration (uri-path "/"))))))))))

     This example assumes that you are using Let’s Encrypt to get your
     TLS certificate.  *Note Certificate Services::.  The default
     ‘certbot’ service will redirect all HTTP traffic on
     ‘git.my-host.org’ to HTTPS.  You will also need to add an
     ‘fcgiwrap’ proxy to your system services.  *Note Web Services::.

Cgit Service
............

Cgit (https://git.zx2c4.com/cgit/) is a web frontend for Git
repositories written in C.

   The following example will configure the service with default values.
By default, Cgit can be accessed on port 80 (‘http://localhost:80’).

     (service cgit-service-type)

   The ‘file-object’ type designates either a file-like object (*note
file-like objects: G-Expressions.) or a string.

   Available ‘cgit-configuration’ fields are:

 -- cgit-configuration parameter: package package
     The CGIT package.

 -- cgit-configuration parameter: nginx-server-configuration-list nginx
     NGINX configuration.

 -- cgit-configuration parameter: file-object about-filter
     Specifies a command which will be invoked to format the content of
     about pages (both top-level and for each repository).

     Defaults to ‘""’.

 -- cgit-configuration parameter: string agefile
     Specifies a path, relative to each repository path, which can be
     used to specify the date and time of the youngest commit in the
     repository.

     Defaults to ‘""’.

 -- cgit-configuration parameter: file-object auth-filter
     Specifies a command that will be invoked for authenticating
     repository access.

     Defaults to ‘""’.

 -- cgit-configuration parameter: string branch-sort
     Flag which, when set to ‘age’, enables date ordering in the branch
     ref list, and when set ‘name’ enables ordering by branch name.

     Defaults to ‘"name"’.

 -- cgit-configuration parameter: string cache-root
     Path used to store the cgit cache entries.

     Defaults to ‘"/var/cache/cgit"’.

 -- cgit-configuration parameter: integer cache-static-ttl
     Number which specifies the time-to-live, in minutes, for the cached
     version of repository pages accessed with a fixed SHA1.

     Defaults to ‘-1’.

 -- cgit-configuration parameter: integer cache-dynamic-ttl
     Number which specifies the time-to-live, in minutes, for the cached
     version of repository pages accessed without a fixed SHA1.

     Defaults to ‘5’.

 -- cgit-configuration parameter: integer cache-repo-ttl
     Number which specifies the time-to-live, in minutes, for the cached
     version of the repository summary page.

     Defaults to ‘5’.

 -- cgit-configuration parameter: integer cache-root-ttl
     Number which specifies the time-to-live, in minutes, for the cached
     version of the repository index page.

     Defaults to ‘5’.

 -- cgit-configuration parameter: integer cache-scanrc-ttl
     Number which specifies the time-to-live, in minutes, for the result
     of scanning a path for Git repositories.

     Defaults to ‘15’.

 -- cgit-configuration parameter: integer cache-about-ttl
     Number which specifies the time-to-live, in minutes, for the cached
     version of the repository about page.

     Defaults to ‘15’.

 -- cgit-configuration parameter: integer cache-snapshot-ttl
     Number which specifies the time-to-live, in minutes, for the cached
     version of snapshots.

     Defaults to ‘5’.

 -- cgit-configuration parameter: integer cache-size
     The maximum number of entries in the cgit cache.  When set to ‘0’,
     caching is disabled.

     Defaults to ‘0’.

 -- cgit-configuration parameter: boolean case-sensitive-sort?
     Sort items in the repo list case sensitively.

     Defaults to ‘#t’.

 -- cgit-configuration parameter: list clone-prefix
     List of common prefixes which, when combined with a repository URL,
     generates valid clone URLs for the repository.

     Defaults to ‘'()’.

 -- cgit-configuration parameter: list clone-url
     List of ‘clone-url’ templates.

     Defaults to ‘'()’.

 -- cgit-configuration parameter: file-object commit-filter
     Command which will be invoked to format commit messages.

     Defaults to ‘""’.

 -- cgit-configuration parameter: string commit-sort
     Flag which, when set to ‘date’, enables strict date ordering in the
     commit log, and when set to ‘topo’ enables strict topological
     ordering.

     Defaults to ‘"git log"’.

 -- cgit-configuration parameter: file-object css
     URL which specifies the css document to include in all cgit pages.

     Defaults to ‘"/share/cgit/cgit.css"’.

 -- cgit-configuration parameter: file-object email-filter
     Specifies a command which will be invoked to format names and email
     address of committers, authors, and taggers, as represented in
     various places throughout the cgit interface.

     Defaults to ‘""’.

 -- cgit-configuration parameter: boolean embedded?
     Flag which, when set to ‘#t’, will make cgit generate a HTML
     fragment suitable for embedding in other HTML pages.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: boolean enable-commit-graph?
     Flag which, when set to ‘#t’, will make cgit print an ASCII-art
     commit history graph to the left of the commit messages in the
     repository log page.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: boolean enable-filter-overrides?
     Flag which, when set to ‘#t’, allows all filter settings to be
     overridden in repository-specific cgitrc files.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: boolean enable-follow-links?
     Flag which, when set to ‘#t’, allows users to follow a file in the
     log view.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: boolean enable-http-clone?
     If set to ‘#t’, cgit will act as an dumb HTTP endpoint for Git
     clones.

     Defaults to ‘#t’.

 -- cgit-configuration parameter: boolean enable-index-links?
     Flag which, when set to ‘#t’, will make cgit generate extra links
     "summary", "commit", "tree" for each repo in the repository index.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: boolean enable-index-owner?
     Flag which, when set to ‘#t’, will make cgit display the owner of
     each repo in the repository index.

     Defaults to ‘#t’.

 -- cgit-configuration parameter: boolean enable-log-filecount?
     Flag which, when set to ‘#t’, will make cgit print the number of
     modified files for each commit on the repository log page.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: boolean enable-log-linecount?
     Flag which, when set to ‘#t’, will make cgit print the number of
     added and removed lines for each commit on the repository log page.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: boolean enable-remote-branches?
     Flag which, when set to ‘#t’, will make cgit display remote
     branches in the summary and refs views.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: boolean enable-subject-links?
     Flag which, when set to ‘1’, will make cgit use the subject of the
     parent commit as link text when generating links to parent commits
     in commit view.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: boolean enable-html-serving?
     Flag which, when set to ‘#t’, will make cgit use the subject of the
     parent commit as link text when generating links to parent commits
     in commit view.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: boolean enable-tree-linenumbers?
     Flag which, when set to ‘#t’, will make cgit generate linenumber
     links for plaintext blobs printed in the tree view.

     Defaults to ‘#t’.

 -- cgit-configuration parameter: boolean enable-git-config?
     Flag which, when set to ‘#f’, will allow cgit to use Git config to
     set any repo specific settings.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: file-object favicon
     URL used as link to a shortcut icon for cgit.

     Defaults to ‘"/favicon.ico"’.

 -- cgit-configuration parameter: string footer
     The content of the file specified with this option will be included
     verbatim at the bottom of all pages (i.e. it replaces the standard
     "generated by..." message).

     Defaults to ‘""’.

 -- cgit-configuration parameter: string head-include
     The content of the file specified with this option will be included
     verbatim in the HTML HEAD section on all pages.

     Defaults to ‘""’.

 -- cgit-configuration parameter: string header
     The content of the file specified with this option will be included
     verbatim at the top of all pages.

     Defaults to ‘""’.

 -- cgit-configuration parameter: file-object include
     Name of a configfile to include before the rest of the current
     config- file is parsed.

     Defaults to ‘""’.

 -- cgit-configuration parameter: string index-header
     The content of the file specified with this option will be included
     verbatim above the repository index.

     Defaults to ‘""’.

 -- cgit-configuration parameter: string index-info
     The content of the file specified with this option will be included
     verbatim below the heading on the repository index page.

     Defaults to ‘""’.

 -- cgit-configuration parameter: boolean local-time?
     Flag which, if set to ‘#t’, makes cgit print commit and tag times
     in the servers timezone.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: file-object logo
     URL which specifies the source of an image which will be used as a
     logo on all cgit pages.

     Defaults to ‘"/share/cgit/cgit.png"’.

 -- cgit-configuration parameter: string logo-link
     URL loaded when clicking on the cgit logo image.

     Defaults to ‘""’.

 -- cgit-configuration parameter: file-object owner-filter
     Command which will be invoked to format the Owner column of the
     main page.

     Defaults to ‘""’.

 -- cgit-configuration parameter: integer max-atom-items
     Number of items to display in atom feeds view.

     Defaults to ‘10’.

 -- cgit-configuration parameter: integer max-commit-count
     Number of entries to list per page in "log" view.

     Defaults to ‘50’.

 -- cgit-configuration parameter: integer max-message-length
     Number of commit message characters to display in "log" view.

     Defaults to ‘80’.

 -- cgit-configuration parameter: integer max-repo-count
     Specifies the number of entries to list per page on the repository
     index page.

     Defaults to ‘50’.

 -- cgit-configuration parameter: integer max-repodesc-length
     Specifies the maximum number of repo description characters to
     display on the repository index page.

     Defaults to ‘80’.

 -- cgit-configuration parameter: integer max-blob-size
     Specifies the maximum size of a blob to display HTML for in KBytes.

     Defaults to ‘0’.

 -- cgit-configuration parameter: string max-stats
     Maximum statistics period.  Valid values are ‘week’,‘month’,
     ‘quarter’ and ‘year’.

     Defaults to ‘""’.

 -- cgit-configuration parameter: mimetype-alist mimetype
     Mimetype for the specified filename extension.

     Defaults to ‘'((gif "image/gif") (html "text/html") (jpg
     "image/jpeg") (jpeg "image/jpeg") (pdf "application/pdf") (png
     "image/png") (svg "image/svg+xml"))’.

 -- cgit-configuration parameter: file-object mimetype-file
     Specifies the file to use for automatic mimetype lookup.

     Defaults to ‘""’.

 -- cgit-configuration parameter: string module-link
     Text which will be used as the formatstring for a hyperlink when a
     submodule is printed in a directory listing.

     Defaults to ‘""’.

 -- cgit-configuration parameter: boolean nocache?
     If set to the value ‘#t’ caching will be disabled.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: boolean noplainemail?
     If set to ‘#t’ showing full author email addresses will be
     disabled.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: boolean noheader?
     Flag which, when set to ‘#t’, will make cgit omit the standard
     header on all pages.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: project-list project-list
     A list of subdirectories inside of ‘repository-directory’, relative
     to it, that should loaded as Git repositories.  An empty list means
     that all subdirectories will be loaded.

     Defaults to ‘'()’.

 -- cgit-configuration parameter: file-object readme
     Text which will be used as default ‘repository-cgit-configuration’
     ‘readme’.

     Defaults to ‘""’.

 -- cgit-configuration parameter: boolean remove-suffix?
     If set to ‘#t’ and ‘repository-directory’ is enabled, if any
     repositories are found with a suffix of ‘.git’, this suffix will be
     removed for the URL and name.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: integer renamelimit
     Maximum number of files to consider when detecting renames.

     Defaults to ‘-1’.

 -- cgit-configuration parameter: string repository-sort
     The way in which repositories in each section are sorted.

     Defaults to ‘""’.

 -- cgit-configuration parameter: robots-list robots
     Text used as content for the ‘robots’ meta-tag.

     Defaults to ‘'("noindex" "nofollow")’.

 -- cgit-configuration parameter: string root-desc
     Text printed below the heading on the repository index page.

     Defaults to ‘"a fast webinterface for the git dscm"’.

 -- cgit-configuration parameter: string root-readme
     The content of the file specified with this option will be included
     verbatim below the “about” link on the repository index page.

     Defaults to ‘""’.

 -- cgit-configuration parameter: string root-title
     Text printed as heading on the repository index page.

     Defaults to ‘""’.

 -- cgit-configuration parameter: boolean scan-hidden-path
     If set to ‘#t’ and repository-directory is enabled,
     repository-directory will recurse into directories whose name
     starts with a period.  Otherwise, repository-directory will stay
     away from such directories, considered as “hidden”.  Note that this
     does not apply to the ‘.git’ directory in non-bare repos.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: list snapshots
     Text which specifies the default set of snapshot formats that cgit
     generates links for.

     Defaults to ‘'()’.

 -- cgit-configuration parameter: repository-directory
          repository-directory
     Name of the directory to scan for repositories (represents
     ‘scan-path’).

     Defaults to ‘"/srv/git"’.

 -- cgit-configuration parameter: string section
     The name of the current repository section - all repositories
     defined after this option will inherit the current section name.

     Defaults to ‘""’.

 -- cgit-configuration parameter: string section-sort
     Flag which, when set to ‘1’, will sort the sections on the
     repository listing by name.

     Defaults to ‘""’.

 -- cgit-configuration parameter: integer section-from-path
     A number which, if defined prior to repository-directory, specifies
     how many path elements from each repo path to use as a default
     section name.

     Defaults to ‘0’.

 -- cgit-configuration parameter: boolean side-by-side-diffs?
     If set to ‘#t’ shows side-by-side diffs instead of unidiffs per
     default.

     Defaults to ‘#f’.

 -- cgit-configuration parameter: file-object source-filter
     Specifies a command which will be invoked to format plaintext blobs
     in the tree view.

     Defaults to ‘""’.

 -- cgit-configuration parameter: integer summary-branches
     Specifies the number of branches to display in the repository
     “summary” view.

     Defaults to ‘10’.

 -- cgit-configuration parameter: integer summary-log
     Specifies the number of log entries to display in the repository
     “summary” view.

     Defaults to ‘10’.

 -- cgit-configuration parameter: integer summary-tags
     Specifies the number of tags to display in the repository “summary”
     view.

     Defaults to ‘10’.

 -- cgit-configuration parameter: string strict-export
     Filename which, if specified, needs to be present within the
     repository for cgit to allow access to that repository.

     Defaults to ‘""’.

 -- cgit-configuration parameter: string virtual-root
     URL which, if specified, will be used as root for all cgit links.

     Defaults to ‘"/"’.

 -- cgit-configuration parameter: repository-cgit-configuration-list
          repositories
     A list of ‘repository-cgit-configuration’ records.

     Defaults to ‘'()’.

     Available ‘repository-cgit-configuration’ fields are:

      -- repository-cgit-configuration parameter: repo-list snapshots
          A mask of snapshot formats for this repo that cgit generates
          links for, restricted by the global ‘snapshots’ setting.

          Defaults to ‘'()’.

      -- repository-cgit-configuration parameter: repo-file-object
               source-filter
          Override the default ‘source-filter’.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string url
          The relative URL used to access the repository.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-file-object
               about-filter
          Override the default ‘about-filter’.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string
               branch-sort
          Flag which, when set to ‘age’, enables date ordering in the
          branch ref list, and when set to ‘name’ enables ordering by
          branch name.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-list clone-url
          A list of URLs which can be used to clone repo.

          Defaults to ‘'()’.

      -- repository-cgit-configuration parameter: repo-file-object
               commit-filter
          Override the default ‘commit-filter’.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string
               commit-sort
          Flag which, when set to ‘date’, enables strict date ordering
          in the commit log, and when set to ‘topo’ enables strict
          topological ordering.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string defbranch
          The name of the default branch for this repository.  If no
          such branch exists in the repository, the first branch name
          (when sorted) is used as default instead.  By default branch
          pointed to by HEAD, or “master” if there is no suitable HEAD.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string desc
          The value to show as repository description.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string homepage
          The value to show as repository homepage.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-file-object
               email-filter
          Override the default ‘email-filter’.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: maybe-repo-boolean
               enable-commit-graph?
          A flag which can be used to disable the global setting
          ‘enable-commit-graph?’.

          Defaults to ‘disabled’.

      -- repository-cgit-configuration parameter: maybe-repo-boolean
               enable-log-filecount?
          A flag which can be used to disable the global setting
          ‘enable-log-filecount?’.

          Defaults to ‘disabled’.

      -- repository-cgit-configuration parameter: maybe-repo-boolean
               enable-log-linecount?
          A flag which can be used to disable the global setting
          ‘enable-log-linecount?’.

          Defaults to ‘disabled’.

      -- repository-cgit-configuration parameter: maybe-repo-boolean
               enable-remote-branches?
          Flag which, when set to ‘#t’, will make cgit display remote
          branches in the summary and refs views.

          Defaults to ‘disabled’.

      -- repository-cgit-configuration parameter: maybe-repo-boolean
               enable-subject-links?
          A flag which can be used to override the global setting
          ‘enable-subject-links?’.

          Defaults to ‘disabled’.

      -- repository-cgit-configuration parameter: maybe-repo-boolean
               enable-html-serving?
          A flag which can be used to override the global setting
          ‘enable-html-serving?’.

          Defaults to ‘disabled’.

      -- repository-cgit-configuration parameter: repo-boolean hide?
          Flag which, when set to ‘#t’, hides the repository from the
          repository index.

          Defaults to ‘#f’.

      -- repository-cgit-configuration parameter: repo-boolean ignore?
          Flag which, when set to ‘#t’, ignores the repository.

          Defaults to ‘#f’.

      -- repository-cgit-configuration parameter: repo-file-object logo
          URL which specifies the source of an image which will be used
          as a logo on this repo’s pages.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string logo-link
          URL loaded when clicking on the cgit logo image.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-file-object
               owner-filter
          Override the default ‘owner-filter’.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string
               module-link
          Text which will be used as the formatstring for a hyperlink
          when a submodule is printed in a directory listing.  The
          arguments for the formatstring are the path and SHA1 of the
          submodule commit.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: module-link-path
               module-link-path
          Text which will be used as the formatstring for a hyperlink
          when a submodule with the specified subdirectory path is
          printed in a directory listing.

          Defaults to ‘'()’.

      -- repository-cgit-configuration parameter: repo-string max-stats
          Override the default maximum statistics period.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string name
          The value to show as repository name.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string owner
          A value used to identify the owner of the repository.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string path
          An absolute path to the repository directory.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string readme
          A path (relative to repo) which specifies a file to include
          verbatim as the “About” page for this repo.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-string section
          The name of the current repository section - all repositories
          defined after this option will inherit the current section
          name.

          Defaults to ‘""’.

      -- repository-cgit-configuration parameter: repo-list
               extra-options
          Extra options will be appended to cgitrc file.

          Defaults to ‘'()’.

 -- cgit-configuration parameter: list extra-options
     Extra options will be appended to cgitrc file.

     Defaults to ‘'()’.

   However, it could be that you just want to get a ‘cgitrc’ up and
running.  In that case, you can pass an ‘opaque-cgit-configuration’ as a
record to ‘cgit-service-type’.  As its name indicates, an opaque
configuration does not have easy reflective capabilities.

   Available ‘opaque-cgit-configuration’ fields are:

 -- opaque-cgit-configuration parameter: package cgit
     The cgit package.

 -- opaque-cgit-configuration parameter: string string
     The contents of the ‘cgitrc’, as a string.

   For example, if your ‘cgitrc’ is just the empty string, you could
instantiate a cgit service like this:

     (service cgit-service-type
              (opaque-cgit-configuration
               (cgitrc "")))

Gitolite Service
................

Gitolite (https://gitolite.com/gitolite/) is a tool for hosting Git
repositories on a central server.

   Gitolite can handle multiple repositories and users, and supports
flexible configuration of the permissions for the users on the
repositories.

   The following example will configure Gitolite using the default ‘git’
user, and the provided SSH public key.

     (service gitolite-service-type
              (gitolite-configuration
                (admin-pubkey (plain-file
                                "yourname.pub"
                                "ssh-rsa AAAA... guix@example.com"))))

   Gitolite is configured through a special admin repository which you
can clone, for example, if you setup Gitolite on ‘example.com’, you
would run the following command to clone the admin repository.

     git clone git@example.com:gitolite-admin

   When the Gitolite service is activated, the provided ‘admin-pubkey’
will be inserted in to the ‘keydir’ directory in the gitolite-admin
repository.  If this results in a change in the repository, it will be
committed using the message “gitolite setup by GNU Guix”.

 -- Data Type: gitolite-configuration
     Data type representing the configuration for
     ‘gitolite-service-type’.

     ‘package’ (default: ‘gitolite’)
          Gitolite package to use.  There are optional Gitolite
          dependencies that are not included in the default package,
          such as Redis and git-annex.  These features can be made
          available by using the ‘make-gitolite’ procedure in the ‘(gnu
          packages version-control’) module to produce a variant of
          Gitolite with the desired additional dependencies.

          The following code returns a package in which the Redis and
          git-annex programs can be invoked by Gitolite’s scripts:

               (use-modules (gnu packages databases)
                            (gnu packages haskell-apps)
                            (gnu packages version-control))
               (make-gitolite (list redis git-annex))

     ‘user’ (default: ‘"git"’)
          User to use for Gitolite.  This will be user that you use when
          accessing Gitolite over SSH.

     ‘group’ (default: ‘"git"’)
          Group to use for Gitolite.

     ‘home-directory’ (default: ‘"/var/lib/gitolite"’)
          Directory in which to store the Gitolite configuration and
          repositories.

     ‘rc-file’ (default: ‘(gitolite-rc-file)’)
          A “file-like” object (*note file-like objects:
          G-Expressions.), representing the configuration for Gitolite.

     ‘git-config’ (default: ‘(gitolite-git-configuration)’)
          A “file-like” object (*note file-like objects:
          G-Expressions.), representing the git configuration for
          Gitolite.

     ‘admin-pubkey’
          A “file-like” object (*note file-like objects: G-Expressions.)
          used to setup Gitolite.  This will be inserted in to the
          ‘keydir’ directory within the gitolite-admin repository.

          To specify the SSH key as a string, use the ‘plain-file’
          function.

               (plain-file "yourname.pub" "ssh-rsa AAAA... guix@example.com")

          The file has to have ‘.pub’ extension.

     ‘admin-name’ (default: ‘#f’)
          Usually the key name is derived by taking a base name of the
          ‘admin-pubkey’.  The resulting file name is the name of the
          gitolite user.  You can use this field to override the
          automatic name.

 -- Data Type: gitolite-rc-file
     Data type representing the Gitolite RC file.

     ‘umask’ (default: ‘#o0077’)
          This controls the permissions Gitolite sets on the
          repositories and their contents.

          A value like ‘#o0027’ will give read access to the group used
          by Gitolite (by default: ‘git’).  This is necessary when using
          Gitolite with software like cgit or gitweb.

     ‘local-code’ (default: ‘"$rc{GL_ADMIN_BASE}/local"’)
          Allows you to add your own non-core programs, or even override
          the shipped ones with your own.

          Please supply the FULL path to this variable.  By default,
          directory called "local" in your gitolite clone is used,
          providing the benefits of versioning them as well as making
          changes to them without having to log on to the server.

     ‘unsafe-pattern’ (default: ‘#f’)
          An optional Perl regular expression for catching unsafe
          configurations in the configuration file.  See Gitolite’s
          documentation
          (https://gitolite.com/gitolite/git-config.html#compensating-for-unsafe_patt)
          for more information.

          When the value is not ‘#f’, it should be a string containing a
          Perl regular expression, such as ‘"[`~#\$\&()|;<>]"’, which is
          the default value used by gitolite.  It rejects any special
          character in configuration that might be interpreted by a
          shell, which is useful when sharing the administration burden
          with other people that do not otherwise have shell access on
          the server.

     ‘git-config-keys’ (default: ‘""’)
          Gitolite allows you to set git config values using the
          ‘config’ keyword.  This setting allows control over the config
          keys to accept.

     ‘log-extra’ (default: ‘#f’)
          Whether gitolite should log extra details.

          For historical reasons, this field defaults to ‘#f’.  The
          default value from gitolite however is ‘1’ (written as ‘#t’ in
          this configuration).

     ‘host-name’ (default: ‘#f’)
          The host name of this gitolite instance.  It is used by the
          mirroring feature.

     ‘roles’ (default: ‘'(("READERS" . 1) ("WRITERS" . ))’)
          Set the role names allowed to be used by users running the
          perms command.

     ‘enable’ (default: ‘'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")’)
          This setting controls the commands and features to enable
          within Gitolite.

     ‘extra-content’ (default: ‘""’)
          Extra content to add verbatim into the ‘%RC’ hash.

 -- Data Type: gitolite-git-configuration
     Data type representing the git configuration file for gitolite.

     ‘name’ (default: ‘"GNU GNU"’)
          User name used for commits (e.g.  during setting up the admin
          repository).

     ‘email’ (default: ‘"guix@localhost"’)
          Email used for commits (e.g.  during setting up the admin
          repository).

     ‘default-branch’ (default: ‘#f’)
          If true, set the ‘init.defaultBranch’ option to that value.
          Common values are ‘"master"’ and ‘"main"’.

     ‘receive-fsck-objects’ (default: ‘#f’)
          If it is set to true, git-receive-pack will check all received
          objects.

     ‘extra-content’ (default: ‘""’)
          Extra content to add verbatim into the git configuration file.

Gitile Service
..............

Gitile (https://git.lepiller.eu/gitile) is a Git forge for viewing
public git repository contents from a web browser.

   Gitile works best in collaboration with Gitolite, and will serve the
public repositories from Gitolite by default.  The service should listen
only on a local port, and a webserver should be configured to serve
static resources.  The gitile service provides an easy way to extend the
Nginx service for that purpose (*note NGINX::).

   The following example will configure Gitile to serve repositories
from a custom location, with some default messages for the home page and
the footers.

     (service gitile-service-type
              (gitile-configuration
                (repositories "/srv/git")
                (base-git-url "https://myweb.site/git")
                (index-title "My git repositories")
                (intro '((p "This is all my public work!")))
                (footer '((p "This is the end")))
                (nginx
                  (nginx-server-configuration
                    (ssl-certificate
                      "/etc/certs/myweb.site/fullchain.pem")
                    (ssl-certificate-key
                      "/etc/certs/myweb.site/privkey.pem")
                    (listen '("443 ssl http2" "[::]:443 ssl http2"))
                    (locations
                      (list
                        ;; Allow for https anonymous fetch on /git/ urls.
                        (git-http-nginx-location-configuration
                          (git-http-configuration
                            (uri-path "/git/")
                            (git-root "/var/lib/gitolite/repositories")))))))))

   In addition to the configuration record, you should configure your
git repositories to contain some optional information.  First, your
public repositories need to contain the ‘git-daemon-export-ok’ magic
file that allows Git to export the repository.  Gitile uses the presence
of this file to detect public repositories it should make accessible.
To do so with Gitolite for instance, modify your ‘conf/gitolite.conf’ to
include this in the repositories you want to make public:

     repo foo
         R = daemon

   In addition, Gitile can read the repository configuration to display
more information on the repository.  Gitile uses the gitweb namespace
for its configuration.  As an example, you can use the following in your
‘conf/gitolite.conf’:

     repo foo
         R = daemon
         desc = A long description, optionally with <i>HTML</i>, shown on the index page
         config gitweb.name = The Foo Project
         config gitweb.synopsis = A short description, shown on the main page of the project

   Do not forget to commit and push these changes once you are
satisfied.  You may need to change your gitolite configuration to allow
the previous configuration options to be set.  One way to do that is to
add the following service definition:

     (service gitolite-service-type
               (gitolite-configuration
                 (admin-pubkey (local-file "key.pub"))
                 (rc-file
                   (gitolite-rc-file
                     (umask #o0027)
                     ;; Allow to set any configuration key
                     (git-config-keys ".*")
                     ;; Allow any text as a valid configuration value
                     (unsafe-patt "^$")))))

 -- Data Type: gitile-configuration
     Data type representing the configuration for ‘gitile-service-type’.

     ‘package’ (default: GITILE)
          Gitile package to use.

     ‘host’ (default: ‘"localhost"’)
          The host on which gitile is listening.

     ‘port’ (default: ‘8080’)
          The port on which gitile is listening.

     ‘database’ (default: ‘"/var/lib/gitile/gitile-db.sql"’)
          The location of the database.

     ‘repositories’ (default: ‘"/var/lib/gitolite/repositories"’)
          The location of the repositories.  Note that only public
          repositories will be shown by Gitile.  To make a repository
          public, add an empty ‘git-daemon-export-ok’ file at the root
          of that repository.

     ‘git-owner-validation?’ (default: ‘#t’)
          Whether to check for the service user’s ownership of
          repositories.  By default, Git will refuse to process a
          repository owned by another user.

     ‘base-git-url’
          The base git url that will be used to show clone commands.

     ‘index-title’ (default: ‘"Index"’)
          The page title for the index page that lists all the available
          repositories.

     ‘intro’ (default: ‘'()’)
          The intro content, as a list of sxml expressions.  This is
          shown above the list of repositories, on the index page.

     ‘footer’ (default: ‘'()’)
          The footer content, as a list of sxml expressions.  This is
          shown on every page served by Gitile.

     ‘nginx’
          An nginx server block that will be extended and used as a
          reverse proxy by Gitile to serve its pages, and as a normal
          web server to serve its assets.

          You can use this block to add more custom URLs to your domain,
          such as a ‘/git/’ URL for anonymous clones, or serving any
          other files you would like to serve.

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

   (1) By creating the magic file ‘git-daemon-export-ok’ in the
repository directory.

   (2) Run ‘man git-daemon’ for more information.


File: guix.info,  Node: Game Services,  Next: PAM Mount Service,  Prev: Version Control Services,  Up: Services

11.10.33 Game Services
----------------------

Joycond service
...............

The joycond service allows the pairing of Nintendo joycon game
controllers over Bluetooth.  (*note Desktop Services:: for setting up
Bluetooth.)

 -- Data Type: joycond-configuration
     Data type representing the configuration of ‘joycond’.

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

 -- Variable: joycond-service-type
     Service type for the joycond service.  It also extends the
     ‘udev-service-type’ with the ‘joycond’ package (provided via the
     ‘joycond-configuration’ configuration), so that joycond controllers
     can be detected and used by an unprivileged user.

The Battle for Wesnoth Service
..............................

The Battle for Wesnoth (https://wesnoth.org) is a fantasy, turn based
tactical strategy game, with several single player campaigns, and
multiplayer games (both networked and local).

 -- Variable: wesnothd-service-type
     Service type for the wesnothd service.  Its value must be a
     ‘wesnothd-configuration’ object.  To run wesnothd in the default
     configuration, instantiate it as:

          (service wesnothd-service-type)

 -- Data Type: wesnothd-configuration
     Data type representing the configuration of ‘wesnothd’.

     ‘package’ (default: ‘wesnoth-server’)
          The wesnoth server package to use.

     ‘port’ (default: ‘15000’)
          The port to bind the server to.


File: guix.info,  Node: PAM Mount Service,  Next: Guix Services,  Prev: Game Services,  Up: Services

11.10.34 PAM Mount Service
--------------------------

The ‘(gnu services pam-mount)’ module provides a service allowing users
to mount volumes when they log in.  It should be able to mount any
volume format supported by the system.

 -- Variable: pam-mount-service-type
     Service type for PAM Mount support.

 -- Data Type: pam-mount-configuration
     Data type representing the configuration of PAM Mount.

     It takes the following parameters:

     ‘rules’
          The configuration rules that will be used to generate
          ‘/etc/security/pam_mount.conf.xml’.

          The configuration rules are SXML elements (*note
          (guile)SXML::), and the default ones don’t mount anything for
          anyone at login:

               `((debug (@ (enable "0")))
                 (mntoptions (@ (allow ,(string-join
                                         '("nosuid" "nodev" "loop"
                                           "encryption" "fsck" "nonempty"
                                           "allow_root" "allow_other")
                                         ","))))
                 (mntoptions (@ (require "nosuid,nodev")))
                 (logout (@ (wait "0")
                            (hup "0")
                            (term "no")
                            (kill "no")))
                 (mkmountpoint (@ (enable "1")
                                  (remove "true"))))

          Some ‘volume’ elements must be added to automatically mount
          volumes at login.  Here’s an example allowing the user ‘alice’
          to mount her encrypted ‘HOME’ directory and allowing the user
          ‘bob’ to mount the partition where he stores his data:

               (define pam-mount-rules
               `((debug (@ (enable "0")))
                           (volume (@ (user "alice")
                                      (fstype "crypt")
                                      (path "/dev/sda2")
                                      (mountpoint "/home/alice")))
                           (volume (@ (user "bob")
                                      (fstype "auto")
                                      (path "/dev/sdb3")
                                      (mountpoint "/home/bob/data")
                                      (options "defaults,autodefrag,compress")))
                           (mntoptions (@ (allow ,(string-join
                                                   '("nosuid" "nodev" "loop"
                                                     "encryption" "fsck" "nonempty"
                                                     "allow_root" "allow_other")
                                                   ","))))
                           (mntoptions (@ (require "nosuid,nodev")))
                           (logout (@ (wait "0")
                                      (hup "0")
                                      (term "no")
                                      (kill "no")))
                           (mkmountpoint (@ (enable "1")
                                            (remove "true")))))

               (service pam-mount-service-type
                        (pam-mount-configuration
                          (rules pam-mount-rules)))

          The complete list of possible options can be found in the man
          page for pam_mount.conf
          (http://pam-mount.sourceforge.net/pam_mount.conf.5.html).

PAM Mount Volume Service
------------------------

PAM mount volumes are automatically mounted at login by the PAM login
service according to a set of per-volume rules.  Because they are
mounted by PAM the password entered during login may be used directly to
mount authenticated volumes, such as ‘cifs’, using the same credentials.

   These volumes will be added in addition to any volumes directly
specified in ‘pam-mount-rules’.

   Here is an example of a rule which will mount a remote CIFS share
from ‘//remote-server/share’ into a sub-directory of ‘/shares’ named
after the user logging in:

     (simple-service 'pam-mount-remote-share pam-mount-volume-service-type
                     (list (pam-mount-volume
                            (secondary-group "users")
                            (file-system-type "cifs")
                            (server "remote-server")
                            (file-name "share")
                            (mount-point "/shares/%(USER)")
                            (options "nosuid,nodev,seal,cifsacl"))))

 -- Data Type: pam-mount-volume-service-type
     Configuration for a single volume to be mounted.  Any fields not
     specified will be omitted from the run-time PAM configuration.  See
     the man page
     (http://pam-mount.sourceforge.net/pam_mount.conf.5.html) for the
     default values when unspecified.

     ‘user-name’ (type: maybe-string)
          Mount the volume for the given user.

     ‘user-id’ (type: maybe-integer-or-range)
          Mount the volume for the user with this ID. This field may
          also be specified as a pair of ‘(start . end)’ indicating a
          range of user IDs for whom to mount the volume.

     ‘primary-group’ (type: maybe-string)
          Mount the volume for users with this primary group name.

     ‘group-id’ (type: maybe-integer-or-range)
          Mount the volume for the users with this primary group ID.
          This field may also be specified as a cons cell of ‘(start .
          end)’ indicating a range of group ids for whom to mount the
          volume.

     ‘secondary-group’ (type: maybe-string)
          Mount the volume for users who are members of this group as
          either a primary or secondary group.

     ‘file-system-type’ (type: maybe-string)
          The file system type for the volume being mounted (e.g.,
          ‘cifs’)

     ‘no-mount-as-root?’ (type: maybe-boolean)
          Whether or not to mount the volume with root privileges.  This
          is normally disabled, but may be enabled for mounts of type
          ‘fuse’, or other user-level mounts.

     ‘server’ (type: maybe-string)
          The name of the remote server to mount the volume from, when
          necessary.

     ‘file-name’ (type: maybe-string)
          The location of the volume, either local or remote, depending
          on the ‘file-system-type’.

     ‘mount-point’ (type: maybe-string)
          Where to mount the volume in the local file-system.  This may
          be set to ‘~’ to indicate the home directory of the user
          logging in.  If this field is omitted then ‘/etc/fstab’ is
          consulted for the mount destination.

     ‘options’ (type: maybe-string)
          The options to be passed as-is to the underlying mount
          program.

     ‘ssh?’ (type: maybe-boolean)
          Enable this option to pass the login password to SSH for use
          with mounts involving SSH (e.g., ‘sshfs’).

     ‘cipher’ (type: maybe-string)
          Cryptsetup cipher name for the volume.  To be used with the
          ‘crypt’ ‘file-system-type’.

     ‘file-system-key-cipher’ (type: maybe-string)
          Cipher name used by the target volume.

     ‘file-system-key-hash’ (type: maybe-string)
          SSL hash name used by the target volume.

     ‘file-system-key-file-name’ (type: maybe-string)
          File name of the file system key for the target volume.


File: guix.info,  Node: Guix Services,  Next: Linux Services,  Prev: PAM Mount Service,  Up: Services

11.10.35 Guix Services
----------------------

Shared Cache Service
....................

Running ‘guix pull’, ‘guix time-machine’, ‘guix system reconfigure’, and
‘guix home reconfigure’ pulls the complete Git version control history
of your channels in ‘$HOME/.cache/guix/checkouts’.  If you have multiple
user accounts (typically ‘root’ and a main user account for your
personal computer), or if multiple users are using the system (typically
on a shared server), then this can quickly waste a lot of space.

   The ‘shared-cache’ service lets you prevent this waste by either
sharing or exposing a specific user’s cache to the other users.

   In the context of this service, _sharing_ and _exposing_ have the
same meaning as with ‘guix shell’: making the shared cache directory
read-only if you use mode ‘'expose’ (the default), and writable if you
use mode ‘'share’, (*note ‘--expose’ and ‘--share’: Invoking guix
shell.).

   Whatever mode you choose, from the point of view of the user, the
cache appears writable.  With ‘'expose’, any write will be stored in a
user-owned overlay directory next to mountpoint, whereas with ‘'share’,
writes will be propagated back to the sharing user’s cache.

     Warning: Use the ‘'share’ option _if and only if_ users on the
     machine trust each other.  This is a hard requirement since, with
     this option, any user could “poison” the shared cache to indirectly
     gain access to other user’s data and privileges.

     Warning: Using ‘'share’ is meant for a single-seat computer where
     the single user has unprivileged user accounts—e.g.  one for work
     and one for gaming.  Even then, channels from one will leak into
     the other’s cache.  Use with caution.

     Warning: ‘'share’ will not work for multiple concurrent invocation
     of ‘guix’, e.g.  if two user accounts run ‘guix time machine’ at
     the same time, the results will be fun but not useful.

   Here is an example configuration that exposes ‘root’’s guix checkout
cache to ‘alice’ and ‘bob’:

     (operating-system
       ;; ...
          (services
           (cons*
            (service shared-cache-service-type
                  (shared-cache-configuration
                    (users (list (user-cache (user "alice"))
                                 (user-cache (user "bob"))))))
                         %desktop-services)))

   The service can also be extended by providing a list of ‘user-cache’,
allowing for easier splitting of configuration.

     (operating-system
       ;; ...
       (services
        (cons*
         (simple-service 'bob-shared-guix-cache shared-cache-service-type
                         (list (user-cache (user "bob"))))
         %desktop-services)))

 -- Variable: shared-cache-service-type
     Service type for sharing a subdirectory of ‘~/.cache/’ between
     multiple users.

     This service allows different system users to share the contents of
     the user cache, avoiding duplication and saving disk space.  It can
     be configured in either “share” mode, where all users write to the
     same cache, or “expose” mode, where users get a read-only view with
     a writable overlay.  Its value must be a
     ‘shared-cache-configuration’ object.

 -- Data Type: shared-cache-configuration
     Data type representing the configuration of the shared cache.

     ‘mode’ (default: ‘'expose’)
          Either ‘'share’ (read-write, dangerous) or ‘'expose’
          (read-only with per-user overlay, the default).  In share
          mode, all writes go to the shared directory.  In expose mode,
          only reads use the shared directory; writes go to a user-owned
          overlay.

     ‘shared-directory’ (default: ‘"/root/.cache"’)
          The source cache directory that is shared between users.  Each
          user will see some or all of its subdirectories mounted into
          their own ‘~/.cache’.

     ‘users’ (default: ‘'()’)
          The list of users that will benefit from the shared directory.
          This must be a list of ‘user-info’ records.

 -- Data Type: user-info
     Data type representing the configuration for a single user
     benefitting from a shared cache.

     ‘user’
          The username of the user.

     ‘location’ (default: ‘"/home/USER/.cache"’)
          The cache directory of the user.

     ‘group’ (default: ‘"users"’)
          The primary group of the user.

     ‘directories’ (default: ‘'("guix/checkouts")’)
          List of subdirectories of the ‘shared-cache-configuration’’s
          ‘shared-directory’ (whose default is ‘/root/.cache’) to mount
          under LOCATION (whose default is ‘~/.cache/’) for the user.

Build Farm Front-End (BFFE)
...........................

The Build Farm Front-End (https://git.cbaines.net/guix/bffe/) assists
with building Guix packages in bulk.  It’s responsible for submitting
builds and displaying the status of the build farm.

 -- Variable: bffe-service-type
     Service type for the Build Farm Front-End.  Its value must be a
     ‘bffe-configuration’ object.

 -- Data Type: bffe-configuration
     Data type representing the configuration of the Build Farm
     Front-End.

     ‘package’ (default: ‘bffe’)
          The Build Farm Front-End package to use.

     ‘user’ (default: ‘"bffe"’)
          The system user to run the service as.

     ‘group’ (default: ‘"bffe"’)
          The system group to run the service as.

     ‘arguments’
          A list of arguments to the Build Farm Front-End.  These are
          passed to the ‘run-bffe-service’ procedure when starting the
          service.

          For example, the following value directs the Build Farm
          Front-End to submit builds for derivations available from
          ‘data.guix.gnu.org’ to the Build Coordinator instance assumed
          to be running on the same machine.

               (list
                #:build
                (list
                 (build-from-guix-data-service
                  (data-service-url "https://data.guix.gnu.org")
                  (build-coordinator-url "http://127.0.0.1:8746")
                  (branches '("master"))
                  (systems '("x86_64-linux" "i686-linux"))
                  (systems-and-targets
                   (map (lambda (target)
                          (cons "x86_64-linux" target))
                        '("aarch64-linux-gnu"
                          "i586-pc-gnu")))))
                #:web-server-args
                '(#:event-source "https://example.com"
                  #:controller-args
                  (#:title "example.com build farm")))

     ‘extra-environment-variables’ (default: ’())
          Extra environment variables to set via the shepherd service.

Guix Build Coordinator
......................

The Guix Build Coordinator
(https://git.cbaines.net/guix/build-coordinator/) aids in distributing
derivation builds among machines running an “agent”.  The build daemon
is still used to build the derivations, but the Guix Build Coordinator
manages allocating builds and working with the results.

   The Guix Build Coordinator consists of one “coordinator”, and one or
more connected “agent” processes.  The coordinator process handles
clients submitting builds, and allocating builds to agents.  The agent
processes talk to a build daemon to actually perform the builds, then
send the results back to the coordinator.

   There is a script to run the coordinator component of the Guix Build
Coordinator, but the Guix service uses a custom Guile script instead, to
provide better integration with G-expressions used in the configuration.

 -- Variable: guix-build-coordinator-service-type
     Service type for the Guix Build Coordinator.  Its value must be a
     ‘guix-build-coordinator-configuration’ object.

 -- Data Type: guix-build-coordinator-configuration
     Data type representing the configuration of the Guix Build
     Coordinator.

     ‘package’ (default: ‘guix-build-coordinator’)
          The Guix Build Coordinator package to use.

     ‘user’ (default: ‘"guix-build-coordinator"’)
          The system user to run the service as.

     ‘group’ (default: ‘"guix-build-coordinator"’)
          The system group to run the service as.

     ‘database-uri-string’ (default: ‘"sqlite:///var/lib/guix-build-coordinator/guix_build_coordinator.db"’)
          The URI to use for the database.

     ‘agent-communication-uri’ (default: ‘"http://0.0.0.0:8745"’)
          The URI describing how to listen to requests from agent
          processes.

     ‘client-communication-uri’ (default: ‘"http://127.0.0.1:8746"’)
          The URI describing how to listen to requests from clients.
          The client API allows submitting builds and currently isn’t
          authenticated, so take care when configuring this value.

     ‘allocation-strategy’ (default: ‘#~basic-build-allocation-strategy’)
          A G-expression for the allocation strategy to be used.  This
          is a procedure that takes the datastore as an argument and
          populates the allocation plan in the database.

     ‘hooks’ (default: ’())
          An association list of hooks.  These provide a way to execute
          arbitrary code upon certain events, like a build result being
          processed.

     ‘parallel-hooks’ (default: ’())
          Hooks can be configured to run in parallel.  This parameter is
          an association list of hooks to do in parallel, where the key
          is the symbol for the hook and the value is the number of
          threads to run.

     ‘listen-repl’ (default: #F)
          Port or filename to spawn a REPL listening on, pass ‘#t’ to
          listen on the default port or ‘#f’ to disable.

     ‘guile’ (default: ‘guile-3.0-latest’)
          The Guile package with which to run the Guix Build
          Coordinator.

     ‘extra-environment-variables’ (default: ’())
          Extra environment variables to set via the shepherd service.

 -- Variable: guix-build-coordinator-agent-service-type
     Service type for a Guix Build Coordinator agent.  Its value must be
     a ‘guix-build-coordinator-agent-configuration’ object.

 -- Data Type: guix-build-coordinator-agent-configuration
     Data type representing the configuration a Guix Build Coordinator
     agent.

     ‘package’ (default: ‘guix-build-coordinator/agent-only’)
          The Guix Build Coordinator package to use.

     ‘user’ (default: ‘"guix-build-coordinator-agent"’)
          The system user to run the service as.

     ‘coordinator’ (default: ‘"http://localhost:8745"’)
          The URI to use when connecting to the coordinator.

     ‘authentication’
          Record describing how this agent should authenticate with the
          coordinator.  Possible record types are described below.

     ‘systems’ (default: ‘#f’)
          The systems for which this agent should fetch builds.  The
          agent process will use the current system it’s running on as
          the default.

     ‘max-parallel-builds’ (default: ‘#f’)
          The number of builds to perform in parallel.

     ‘max-parallel-uploads’ (default: ‘#f’)
          The number of uploads to perform in parallel.

     ‘max-allocated-builds’ (default: ‘#f’)
          The maximum number of builds this agent can be allocated.

     ‘max-1min-load-average’ (default: ‘#f’)
          Load average value to look at when considering starting new
          builds, if the 1 minute load average exceeds this value, the
          agent will wait before starting new builds.

          This will be unspecified if the value is ‘#f’, and the agent
          will use the number of cores reported by the system as the max
          1 minute load average.

     ‘derivation-substitute-urls’ (default: ‘#f’)
          URLs from which to attempt to fetch substitutes for
          derivations, if the derivations aren’t already available.

     ‘non-derivation-substitute-urls’ (default: ‘#f’)
          URLs from which to attempt to fetch substitutes for build
          inputs, if the input store items aren’t already available.

     ‘extra-options’ (default: ’())
          Extra command line options for ‘guix-build-coordinator-agent’.

 -- Data Type: guix-build-coordinator-agent-password-auth
     Data type representing an agent authenticating with a coordinator
     via a UUID and password.

     ‘uuid’
          The UUID of the agent.  This should be generated by the
          coordinator process, stored in the coordinator database, and
          used by the intended agent.

     ‘password’
          The password to use when connecting to the coordinator.

 -- Data Type: guix-build-coordinator-agent-password-file-auth
     Data type representing an agent authenticating with a coordinator
     via a UUID and password read from a file.

     ‘uuid’
          The UUID of the agent.  This should be generated by the
          coordinator process, stored in the coordinator database, and
          used by the intended agent.

     ‘password-file’
          A file containing the password to use when connecting to the
          coordinator.

 -- Data Type: guix-build-coordinator-agent-dynamic-auth
     Data type representing an agent authenticating with a coordinator
     via a dynamic auth token and agent name.

     ‘agent-name’
          Name of an agent, this is used to match up to an existing
          entry in the database if there is one.  When no existing entry
          is found, a new entry is automatically added.

     ‘token’
          Dynamic auth token, this is created and stored in the
          coordinator database, and is used by the agent to
          authenticate.

 -- Data Type: guix-build-coordinator-agent-dynamic-auth-with-file
     Data type representing an agent authenticating with a coordinator
     via a dynamic auth token read from a file and agent name.

     ‘agent-name’
          Name of an agent, this is used to match up to an existing
          entry in the database if there is one.  When no existing entry
          is found, a new entry is automatically added.

     ‘token-file’
          File containing the dynamic auth token, this is created and
          stored in the coordinator database, and is used by the agent
          to authenticate.

Guix Data Service
.................

The Guix Data Service (http://data.guix.gnu.org) processes, stores and
provides data about GNU Guix.  This includes information about packages,
derivations and lint warnings.

   The data is stored in a PostgreSQL database, and available through a
web interface.

 -- Variable: guix-data-service-type
     Service type for the Guix Data Service.  Its value must be a
     ‘guix-data-service-configuration’ object.  The service optionally
     extends the getmail service, as the guix-commits mailing list is
     used to find out about changes in the Guix git repository.

 -- Data Type: guix-data-service-configuration
     Data type representing the configuration of the Guix Data Service.

     ‘package’ (default: ‘guix-data-service’)
          The Guix Data Service package to use.

     ‘user’ (default: ‘"guix-data-service"’)
          The system user to run the service as.

     ‘group’ (default: ‘"guix-data-service"’)
          The system group to run the service as.

     ‘port’ (default: ‘8765’)
          The port to bind the web service to.

     ‘host’ (default: ‘"127.0.0.1"’)
          The host to bind the web service to.

     ‘getmail-idle-mailboxes’ (default: ‘#f’)
          If set, this is the list of mailboxes that the getmail service
          will be configured to listen to.

     ‘commits-getmail-retriever-configuration’ (default: ‘#f’)
          If set, this is the ‘getmail-retriever-configuration’ object
          with which to configure getmail to fetch mail from the
          guix-commits mailing list.

     ‘extra-options’ (default: ’())
          Extra command line options for ‘guix-data-service’.

     ‘extra-process-jobs-options’ (default: ’())
          Extra command line options for
          ‘guix-data-service-process-jobs’.

     ‘git-repositories’ (default: #F)
          List of git-repository information to insert into the
          database.

     ‘build-servers’ (default: #F)
          List of build-server information to insert into the database.

Guix Home Service
.................

The Guix Home service is a way to let Guix System deploy the home
environment of one or more users (*note Home Configuration::, for more
on Guix Home).  That way, the system configuration embeds declarations
of the home environment of those users and can be used to deploy
everything consistently at once, saving users the need to run ‘guix home
reconfigure’ independently.

   ‘guix home’ can operate on the home environment configured for
current user via this service, but its effect won’t last beyond the next
system activation.  This can be used for quick testing and may avoid the
need of keeping a separate home configuration.

 -- Variable: guix-home-service-type
     Service type for the Guix Home service.  Its value must be a list
     of lists containing user and home environment pairs.  The key of
     each pair is a string representing the user to deploy the
     configuration under and the value is a home-environment
     configuration.

          (use-modules (gnu services guix))

          (define my-home
            (home-environment
              ...))

          (operating-system
            (services (append (list (service guix-home-service-type
                                             `(("alice" ,my-home))))
                              %base-services)))

     This service can be extended by other services to add additional
     home environments, as in this example:

          (simple-service 'my-extra-home guix-home-service-type
                          `(("bob" ,my-extra-home)))

Nar Herder
..........

The Nar Herder (https://git.cbaines.net/guix/nar-herder/about/) is a
utility for managing a collection of nars.

 -- Variable: nar-herder-type
     Service type for the Guix Data Service.  Its value must be a
     ‘nar-herder-configuration’ object.  The service optionally extends
     the getmail service, as the guix-commits mailing list is used to
     find out about changes in the Guix git repository.

 -- Data Type: nar-herder-configuration
     Data type representing the configuration of the Guix Data Service.

     ‘package’ (default: ‘nar-herder’)
          The Nar Herder package to use.

     ‘user’ (default: ‘"nar-herder"’)
          The system user to run the service as.

     ‘group’ (default: ‘"nar-herder"’)
          The system group to run the service as.

     ‘port’ (default: ‘8734’)
          The port to bind the server to.

     ‘host’ (default: ‘"127.0.0.1"’)
          The host to bind the server to.

     ‘control-port’ (default: ‘8734’)
          The port to bind the control server to.

     ‘control-host’ (default: ‘"127.0.0.1"’)
          The host to bind the control server to.

     ‘mirror’ (default: ‘#f’)
          Optional URL of the other Nar Herder instance which should be
          mirrored.  This means that this Nar Herder instance will
          download it’s database, and keep it up to date.

     ‘database’ (default: ‘"/var/lib/nar-herder/nar_herder.db"’)
          Location for the database.  If this Nar Herder instance is
          mirroring another, the database will be downloaded if it
          doesn’t exist.  If this Nar Herder instance isn’t mirroring
          another, an empty database will be created.

     ‘database-dump’ (default: ‘"/var/lib/nar-herder/nar_herder_dump.db"’)
          Location of the database dump.  This is created and regularly
          updated by taking a copy of the database.  This is the version
          of the database that is available to download.

     ‘storage’ (default: ‘#f’)
          Optional location in which to store nars.

     ‘storage-limit’ (default: ‘"none"’)
          Limit in bytes for the nars stored in the storage location.
          This can also be set to “none” so that there is no limit.

          When the storage location exceeds this size, nars are removed
          according to the nar removal criteria.

     ‘storage-nar-removal-criteria’ (default: ‘'()’)
          Criteria used to remove nars from the storage location.  These
          are used in conjunction with the storage limit.

          When the storage location exceeds the storage limit size, nars
          will be checked against the nar removal criteria and if any of
          the criteria match, they will be removed.  This will continue
          until the storage location is below the storage limit size.

          Each criteria is specified by a string, then an equals sign,
          then another string.  Currently, only one criteria is
          supported, checking if a nar is stored on another Nar Herder
          instance.

     ‘ttl’ (default: ‘#f’)
          Produce ‘Cache-Control’ HTTP headers that advertise a
          time-to-live (TTL) of TTL.  TTL must denote a duration: ‘5d’
          means 5 days, ‘1m’ means 1 month, and so on.

          This allows the user’s Guix to keep substitute information in
          cache for TTL.

     ‘new-ttl’ (default: ‘#f’)
          If specified, this will override the ‘ttl’ setting when used
          for the ‘Cache-Control’ headers, but this value will be used
          when scheduling the removal of nars.

          Use this setting when the TTL is being reduced to avoid
          removing nars while clients still have cached narinfos.

     ‘negative-ttl’ (default: ‘#f’)
          Similarly produce ‘Cache-Control’ HTTP headers to advertise
          the time-to-live (TTL) of _negative_ lookups—missing store
          items, for which the HTTP 404 code is returned.  By default,
          no negative TTL is advertised.

     ‘log-level’ (default: ‘'DEBUG’)
          Log level to use, specify a log level like ‘'INFO’ to stop
          logging individual requests.

     ‘cached-compressions’ (default: ‘'()’)
          Activate generating cached nars with different compression
          details from the stored nars.  This is a list of
          nar-herder-cached-compression-configuration records.

     ‘min-uses’ (default: ‘3’)
          When cached-compressions are enabled, generate cached nars
          when at least this number of requests are made for a nar.

     ‘workers’ (default: ‘2’)
          Number of cached nars to generate at a time.

     ‘nar-source’ (default: ‘#f’)
          Location to fetch nars from when computing cached
          compressions.  By default, the storage location will be used.

     ‘extra-environment-variables’ (default: ‘'()’)
          Extra environment variables to set via the shepherd service.

 -- Data Type: nar-herder-cached-compression-configuration
     Data type representing the cached compression configuration.

     ‘type’
          Type of compression to use, e.g.  ‘'zstd’.

     ‘workers’ (default: ‘#f’)
          Level of the compression to use.

     ‘directory’ (default: ‘#f’)
          Location to store the cached nars.  If unspecified, they will
          be stored in /var/cache/nar-herder/nar/TYPE.

     ‘directory-max-size’ (default: ‘#f’)
          Maximum size in bytes of the directory.

     ‘unused-removal-duration’ (default: ‘#f’)
          If a cached nar isn’t used for ‘unused-removal-duration’, it
          will be scheduled for removal.

          UNUSED-REMOVAL-DURATION must denote a duration: ‘5d’ means 5
          days, ‘1m’ means 1 month, and so on.

     ‘ttl’ (default: ‘#f’)
          If specified this overrides the ‘ttl’ used for narinfos when
          this cached compression is available.

     ‘new-ttl’ (default: ‘#f’)
          As with the ‘new-ttl’ option for ‘nar-herder-configuration’,
          this value will override the ‘ttl’ when used for narinfo
          requests.


File: guix.info,  Node: Linux Services,  Next: Hurd Services,  Prev: Guix Services,  Up: Services

11.10.36 Linux Services
-----------------------

VFS Mapping Service
...................

The VFS (Virtual File System) Mapping service allows you to bind a file
name under a different name in the global namespace.  For example, this
is used by the Shared Cache Service (*note Guix Services::) to bind the
‘root’ user’s cache over another user’s cache.  Another use case may be
to expose game data from the store over your home directory, and apply
modifications there.

   The service has three _policies_ to choose from with respect to
access rights on the bound over path:

‘'bind’
     Use a bind mount; the ownership and file permissions of the
     destination are the same as the source.

‘'translate’
     Use bindfs to make the destination appear as owned by the target
     user and group.  Writes will be propagated back to the source as if
     made by the original owner.

‘'overlay’
     Use an overlay to make the destination appear as owned by the
     target user and group.  Writes will not appear in the source, but
     will be stored in a target-user-owned ‘-overlay’ suffixed directory
     near the destination.

   Here is an example configuration that exposes the default data
directory of ‘tuxpaint’ under the home directory of ‘alice’.  Any
modification made by Alice to the brushes or stamps will not propagate
back to the store (which is read-only anyway).

     (operating-system
       ;; ...
       (services
        (cons*
         (service vfs-mapping-service-type
                  (vfs-mapping-configuration
                   (bindings (list (vfs-mapping
                                    (source      #~(string-append #$tuxpaint
                                                                  "/share/tuxpaint"))
                                    (destination "/home/alice/.tuxpaint")
                                    (user        "alice")
                                    (policy      'overlay)
                                    (name        "alice-tuxpaint-overlay"))))))
         %desktop-services)))

   The service can also be extended by providing a list of
‘vfs-mapping’, allowing for easier splitting of configuration.

     (operating-system
       ;; ...
       (services
        (cons*
         (simple-service 'bob-too-wants-to-hack-on-tuxpaint
                         vfs-mapping-service-type
                         (list (vfs-mapping
                                (source      #~(string-append #$tuxpaint "/share/tuxpaint"))
                                (destination "/home/bob/.tuxpaint")
                                (user        "bob")
                                (policy      'overlay)
                                (name        "bob-tuxpaint-overlay"))))
         %desktop-services)))

   The ‘source’ file name must exist for the service to start.  The
‘destination’ directory will be created if it does not exist.

 -- Variable: vfs-mapping-service-type
     Service type for binding a directory in multiple places on the file
     system.

     The access rights are either the same in source and destination
     (‘'bind’), or writes are translated back to the source as if made
     by the source’s owner (‘'translate’), or kept in an overlay
     directory near the destination (‘'overlay’).  The service’s value
     must be a ‘vfs-mapping-configuration’ object.

 -- Data Type: vfs-mapping-configuration
     Data type representing the configuration of the vfs-mapping
     service.

     ‘bindfs’ (default: ‘#~(string-append #$bindfs "/bin/bindfs")’)
          The ‘bindfs’ command to use for mounting.

     ‘fusermount’ (default: ‘#~(string-append #$fuse-2 "/bin/fusermount")’)
          The ‘fusermount’ command to use.

     ‘umount’ (default: ‘#~(string-append #$util-linux+udev "/bin/umount")’)
          The ‘umount’ command to use.

     ‘bindings’ (default: ‘'()’)
          A list of ‘vfs-mapping’ records.

 -- Data Type: vfs-mapping
     Data type representing the configuration for a single shared
     directory.

     ‘source’
          The source file name to be shared.

     ‘destination’
          The destination at which the contents of ‘source’ will be
          exposed.

     ‘policy’ (default: ‘'translate’)
          Either ‘'bind’ (same ownership and access rights for ‘source’
          and ‘destination’), ‘'translate’ (read-write, with writes
          translated as if made by ‘source’’s owner), or ‘'overlay’
          (read-only with ‘user’-owned writable overlay).

     ‘user’ (default: ‘#f’)
          The user that will own the ‘destination’ directory, and appear
          to own its content.  It must be kept at its default ‘#f’ value
          when using the ‘'bind’ policy.

     ‘group’ (default: ‘"users"’)
          The group that will own the ‘destination’ directory, and
          appear to own its content.

     ‘name’ (default: ‘"<src>-[<policy>]-><dst>"’)
          The name of the shepherd service to mount and unmount the
          binding.

     ‘requirement’ (default: ‘'(file-systems user-homes)’)
          The list of services that Shepherd ought to provision before
          trying to mount.

Early OOM Service
.................

Early OOM (https://github.com/rfjakob/earlyoom), also known as Earlyoom,
is a minimalist out of memory (OOM) daemon that runs in user space and
provides a more responsive and configurable alternative to the in-kernel
OOM killer.  It is useful to prevent the system from becoming
unresponsive when it runs out of memory.

 -- Variable: earlyoom-service-type
     The service type for running ‘earlyoom’, the Early OOM daemon.  Its
     value must be a ‘earlyoom-configuration’ object, described below.
     The service can be instantiated in its default configuration with:

          (service earlyoom-service-type)

 -- Data Type: earlyoom-configuration
     This is the configuration record for the ‘earlyoom-service-type’.

     ‘earlyoom’ (default: EARLYOOM)
          The Earlyoom package to use.

     ‘minimum-available-memory’ (default: ‘10’)
          The threshold for the minimum _available_ memory, in
          percentages.

     ‘minimum-free-swap’ (default: ‘10’)
          The threshold for the minimum free swap memory, in
          percentages.

     ‘prefer-regexp’ (default: ‘#f’)
          A regular expression (as a string) to match the names of the
          processes that should be preferably killed.

     ‘avoid-regexp’ (default: ‘#f’)
          A regular expression (as a string) to match the names of the
          processes that should _not_ be killed.

     ‘memory-report-interval’ (default: ‘0’)
          The interval in seconds at which a memory report is printed.
          It is disabled by default.

     ‘ignore-positive-oom-score-adj?’ (default: ‘#f’)
          A boolean indicating whether the positive adjustments set in
          ‘/proc/*/oom_score_adj’ should be ignored.

     ‘show-debug-messages?’ (default: ‘#f’)
          A boolean indicating whether debug messages should be printed.
          The logs are saved at ‘/var/log/earlyoom.log’.

     ‘send-notification-command’ (default: ‘#f’)
          This can be used to provide a custom command used for sending
          notifications.

fstrim Service
..............

The command ‘fstrim’ can be used to discard (or “trim”) unused blocks on
a mounted file system.

     Warning: Running ‘fstrim’ frequently, or even using ‘mount -o
     discard’, might negatively affect the lifetime of poor-quality SSD
     devices.  For most desktop and server systems a sufficient trimming
     frequency is once a week.  Note that not all devices support a
     queued trim, so each trim command incurs a performance penalty on
     whatever else might be trying to use the disk at the time.

 -- Variable: fstrim-service-type
     Type for a service that periodically runs ‘fstrim’, whose value
     must be an ‘<fstrim-configuration>’ object.  The service can be
     instantiated in its default configuration with:

          (service fstrim-service-type)

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

     ‘package’ (default: ‘util-linux’) (type: file-like)
          The package providing the ‘fstrim’ command.

     ‘schedule’ (default: ‘"0 0 * * 0"’) (type: Shepherd calendar event)
          Schedule for launching ‘fstrim’, expressed as a string in
          traditional cron syntax or as a gexp evaluating to a Shepherd
          calendar event (*note (shepherd)Timers::).  By default this is
          set to run weekly on Sunday at 00:00.

     ‘listed-in’ (default: ‘'("/etc/fstab" "/proc/self/mountinfo")’) (type: maybe-list-of-strings)
          List of files in fstab or kernel mountinfo format.  All
          missing or empty files are silently ignored.  The evaluation
          of the list _stops_ after the first non-empty file.  File
          systems with ‘X-fstrim.notrim’ mount option in fstab are
          skipped.

     ‘verbose?’ (default: ‘#t’) (type: boolean)
          Verbose execution.

     ‘quiet-unsupported?’ (default: ‘#t’) (type: boolean)
          Suppress error messages if trim operation (ioctl) is
          unsupported.

     ‘extra-arguments’ (type: maybe-list-of-strings)
          Extra options to append to ‘fstrim’ (run ‘man fstrim’ for more
          information).

Kernel Module Loader Service
............................

The kernel module loader service allows one to load loadable kernel
modules at boot.  This is especially useful for modules that don’t
autoload and need to be manually loaded, as is the case with ‘ddcci’.

 -- Variable: kernel-module-loader-service-type
     The service type for loading loadable kernel modules at boot with
     ‘modprobe’.  Its value must be a list of strings representing
     module names.  For example loading the drivers provided by
     ‘ddcci-driver-linux’, in debugging mode by passing some module
     parameters, can be done as follow:

          (use-modules (gnu) (gnu services))
          (use-package-modules linux)
          (use-service-modules linux)

          (define ddcci-config
            (plain-file "ddcci.conf"
                        "options ddcci dyndbg delay=120"))

          (operating-system
            ...
            (services (cons* (service kernel-module-loader-service-type
                                      '("ddcci" "ddcci_backlight"))
                             (simple-service 'ddcci-config etc-service-type
                                             (list `("modprobe.d/ddcci.conf"
                                                     ,ddcci-config)))
                             %base-services))
            (kernel-loadable-modules (list ddcci-driver-linux)))

Cachefilesd Service
...................

The Cachefilesd service starts a daemon that caches network file system
data locally.  It is especially useful for NFS and AFS shares, where it
reduces latencies for repeated access when reading files.

   The daemon can be configured as follows:

     (service cachefilesd-service-type
              (cachefilesd-configuration
                (cache-directory "/var/cache/fscache")))

 -- Variable: cachefilesd-service-type
     The service type for starting ‘cachefilesd’.  The value for this
     service type is a ‘cachefilesd-configuration’, whose only required
     field is CACHE-DIRECTORY.

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

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

     ‘debug-output?’ (default: ‘#f’) (type: boolean)
          Print debugging output to stderr.

     ‘use-syslog?’ (default: ‘#t’) (type: boolean)
          Log to syslog facility instead of stdout.

     ‘scan?’ (default: ‘#t’) (type: boolean)
          Scan for cacheable objects.

     ‘cache-directory’ (type: maybe-string)
          Location of the cache directory.

     ‘cache-name’ (default: ‘"CacheFiles"’) (type: maybe-string)
          Name of cache (keep unique).

     ‘security-context’ (type: maybe-string)
          SELinux security context.

     ‘pause-culling-for-block-percentage’ (default: ‘7’) (type: maybe-non-negative-integer)
          Pause culling when available blocks exceed this percentage.

     ‘pause-culling-for-file-percentage’ (default: ‘7’) (type: maybe-non-negative-integer)
          Pause culling when available files exceed this percentage.

     ‘resume-culling-for-block-percentage’ (default: ‘5’) (type: maybe-non-negative-integer)
          Start culling when available blocks drop below this
          percentage.

     ‘resume-culling-for-file-percentage’ (default: ‘5’) (type: maybe-non-negative-integer)
          Start culling when available files drop below this percentage.

     ‘pause-caching-for-block-percentage’ (default: ‘1’) (type: maybe-non-negative-integer)
          Pause further allocations when available blocks drop below
          this percentage.

     ‘pause-caching-for-file-percentage’ (default: ‘1’) (type: maybe-non-negative-integer)
          Pause further allocations when available files drop below this
          percentage.

     ‘log2-table-size’ (default: ‘12’) (type: maybe-non-negative-integer)
          Size of tables holding cullable objects in logarithm of base
          2.

     ‘cull?’ (default: ‘#t’) (type: boolean)
          Create free space by culling (consumes system load).

     ‘trace-function-entry-in-kernel-module?’ (default: ‘#f’) (type: boolean)
          Trace function entry in the kernel module (for debugging).

     ‘trace-function-exit-in-kernel-module?’ (default: ‘#f’) (type: boolean)
          Trace function exit in the kernel module (for debugging).

     ‘trace-internal-checkpoints-in-kernel-module?’ (default: ‘#f’) (type: boolean)
          Trace internal checkpoints in the kernel module (for
          debugging).

Rasdaemon Service
.................

The Rasdaemon service provides a daemon which monitors platform RAS
(Reliability, Availability, and Serviceability) reports from Linux
kernel trace events, logging them to syslogd.

   Reliability, Availability and Serviceability is a concept used on
servers meant to measure their robustness.

   *Relability* is the probability that a system will produce correct
outputs:

   • Generally measured as Mean Time Between Failures (MTBF), and
   • Enhanced by features that help to avoid, detect and repair hardware
     faults

   *Availability* is the probability that a system is operational at a
given time:

   • Generally measured as a percentage of downtime per a period of
     time, and
   • Often uses mechanisms to detect and correct hardware faults in
     runtime.

   *Serviceability* is the simplicity and speed with which a system can
be repaired or maintained:

   • Generally measured on Mean Time Between Repair (MTBR).

   Among the monitoring measures, the most usual ones include:

   • CPU – detect errors at instruction execution and at L1/L2/L3
     caches;
   • Memory – add error correction logic (ECC) to detect and correct
     errors;
   • I/O – add CRC checksums for transferred data;
   • Storage – RAID, journal file systems, checksums, Self-Monitoring,
     Analysis and Reporting Technology (SMART).

   By monitoring the number of occurrences of error detections, it is
possible to identify if the probability of hardware errors is
increasing, and, on such case, do a preventive maintenance to replace a
degraded component while those errors are correctable.

   For detailed information about the types of error events gathered and
how to make sense of them, see the kernel administrator’s guide at
<https://www.kernel.org/doc/html/latest/admin-guide/ras.html>.

 -- Variable: rasdaemon-service-type
     Service type for the ‘rasdaemon’ service.  It accepts a
     ‘rasdaemon-configuration’ object.  Instantiating like

          (service rasdaemon-service-type)

     will load with a default configuration, which monitors all events
     and logs to syslogd.

 -- Data Type: rasdaemon-configuration
     The data type representing the configuration of ‘rasdaemon’.

     ‘record?’ (default: ‘#f’)

          A boolean indicating whether to record the events in an SQLite
          database.  This provides a more structured access to the
          information contained in the log file.  The database location
          is hard-coded to ‘/var/lib/rasdaemon/ras-mc_event.db’.

Zram Device Service
...................

The Zram device service provides a compressed swap device in system
memory.  The Linux Kernel documentation has more information about zram
(https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html)
devices.

 -- Variable: zram-device-service-type
     This service creates the zram block device, formats it as swap and
     enables it as a swap device.  The service’s value is a
     ‘zram-device-configuration’ record.

      -- Data Type: zram-device-configuration
          This is the data type representing the configuration for the
          zram-device service.

          ‘size’ (default ‘"1G"’)
               This is the amount of space you wish to provide for the
               zram device.  It accepts a string and can be a number of
               bytes or use a suffix, eg.: ‘"512M"’ or ‘1024000’.
          ‘compression-algorithm’ (default ‘'lzo’)
               This is the compression algorithm you wish to use.  It is
               difficult to list all the possible compression options,
               but common ones supported by Guix’s Linux Libre Kernel
               include ‘'lzo’, ‘'lz4’ and ‘'zstd’.
          ‘memory-limit’ (default ‘0’)
               This is the maximum amount of memory which the zram
               device can use.  Setting it to ’0’ disables the limit.
               While it is generally expected that compression will be
               2:1, it is possible that uncompressable data can be
               written to swap and this is a method to limit how much
               memory can be used.  It accepts a string and can be a
               number of bytes or use a suffix, eg.: ‘"2G"’.
          ‘priority’ (default ‘#f’)
               This is the priority of the swap device created from the
               zram device.  *Note Swap Space:: for a description of
               swap priorities.  You might want to set a specific
               priority for the zram device, otherwise it could end up
               not being used much for the reasons described there.


File: guix.info,  Node: Hurd Services,  Next: Miscellaneous Services,  Prev: Linux Services,  Up: Services

11.10.37 Hurd Services
----------------------

 -- Variable: hurd-console-service-type
     This service starts the fancy ‘VGA’ console client on the Hurd.

     The service’s value is a ‘hurd-console-configuration’ record.

 -- Data Type: hurd-console-configuration
     This is the data type representing the configuration for the
     hurd-console-service.

     ‘hurd’ (default: HURD)
          The Hurd package to use.

 -- Variable: hurd-getty-service-type
     This service starts a tty using the Hurd ‘getty’ program.

     The service’s value is a ‘hurd-getty-configuration’ record.

 -- Data Type: hurd-getty-configuration
     This is the data type representing the configuration for the
     hurd-getty-service.

     ‘hurd’ (default: HURD)
          The Hurd package to use.

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

     ‘baud-rate’ (default: ‘38400’)
          An integer specifying the baud rate of the tty.


File: guix.info,  Node: Miscellaneous Services,  Prev: Hurd Services,  Up: Services

11.10.38 Miscellaneous Services
-------------------------------

Fingerprint Service
...................

The ‘(gnu services authentication)’ module provides a DBus service to
read and identify fingerprints via a fingerprint sensor.

 -- Variable: fprintd-service-type
     The service type for ‘fprintd’, which provides the fingerprint
     reading capability.

          (service fprintd-service-type)

System Control Service
......................

The ‘(gnu services sysctl)’ provides a service to configure kernel
parameters at boot.

 -- Variable: sysctl-service-type
     The service type for ‘sysctl’, which modifies kernel parameters
     under ‘/proc/sys/’.  To enable IPv4 forwarding, it can be
     instantiated as:

          (service sysctl-service-type
                   (sysctl-configuration
                     (settings '(("net.ipv4.ip_forward" . "1")))))

     Since ‘sysctl-service-type’ is used in the default lists of
     services, ‘%base-services’ and ‘%desktop-services’, you can use
     ‘modify-services’ to change its configuration and add the kernel
     parameters that you want (*note ‘modify-services’: Service
     Reference.).

          (modify-services %base-services
            (sysctl-service-type config =>
                                 (sysctl-configuration
                                   (settings (append '(("net.ipv4.ip_forward" . "1"))
                                                     %default-sysctl-settings)))))

 -- Data Type: sysctl-configuration
     The data type representing the configuration of ‘sysctl’.

     ‘sysctl’ (default: ‘(file-append procps "/sbin/sysctl"’)
          The ‘sysctl’ executable to use.

     ‘settings’ (default: ‘%default-sysctl-settings’)
          An association list specifies kernel parameters and their
          values.

 -- Variable: %default-sysctl-settings
     An association list specifying the default ‘sysctl’ parameters on
     Guix System.

PC/SC Smart Card Daemon Service
...............................

The ‘(gnu services security-token)’ module provides the following
service to run ‘pcscd’, the PC/SC Smart Card Daemon.  ‘pcscd’ is the
daemon program for pcsc-lite and the MuscleCard framework.  It is a
resource manager that coordinates communications with smart card
readers, smart cards and cryptographic tokens that are connected to the
system.

 -- Variable: pcscd-service-type
     Service type for the ‘pcscd’ service.  Its value must be a
     ‘pcscd-configuration’ object.  To run pcscd in the default
     configuration, instantiate it as:

          (service pcscd-service-type)

 -- Data Type: pcscd-configuration
     The data type representing the configuration of ‘pcscd’.

     ‘pcsc-lite’ (default: ‘pcsc-lite’)
          The pcsc-lite package that provides pcscd.
     ‘usb-drivers’ (default: ‘(list ccid)’)
          List of packages that provide USB drivers to pcscd.  Drivers
          are expected to be under ‘pcsc/drivers’ in the store directory
          of the package.

LIRC Service
............

The ‘(gnu services lirc)’ module provides the following service.

 -- Variable: lirc-service-type
     Type for a service that runs LIRC (http://www.lirc.org), a daemon
     that decodes infrared signals from remote controls.

     The value for this service is a ‘<lirc-configuration>’ object.

 -- Data Type: lirc-configuration
     Data type representing the configuration of ‘lircd’.

     ‘lirc’ (default: ‘lirc’) (type: file-like)
          Package object for ‘lirc’.

     ‘device’ (default: ‘#f’) (type: string)
     ‘driver’ (default: ‘#f’) (type: string)
     ‘config-file’ (default: ‘#f’) (type: string-or-file-like)
          TODO. See ‘lircd’ manual for details.

     ‘extra-options’ (default: ‘'()’) (type: list-of-string)
          Additional command-line options to pass to ‘lircd’.

SPICE Service
.............

The ‘(gnu services spice)’ module provides the following service.

 -- Variable: spice-vdagent-service-type
     Type of the service that runs VDAGENT
     (https://www.spice-space.org), a daemon that enables sharing the
     clipboard with a vm and setting the guest display resolution when
     the graphical console window resizes.

 -- Data Type: spice-vdagent-configuration
     Data type representing the configuration of
     ‘spice-vdagent-service-type’.

     ‘spice-vdagent’ (default: ‘spice-vdagent’) (type: file-like)
          Package object for VDAGENT.

inputattach Service
...................

The inputattach (https://linuxwacom.github.io/) service allows you to
use input devices such as Wacom tablets, touchscreens, or joysticks with
the Xorg display server.

 -- Variable: inputattach-service-type
     Type of a service that runs ‘inputattach’ on a device and
     dispatches events from it.

 -- Data Type: inputattach-configuration
     ‘device-type’ (default: ‘"wacom"’)
          The type of device to connect to.  Run ‘inputattach --help’,
          from the ‘inputattach’ package, to see the list of supported
          device types.

     ‘device’ (default: ‘"/dev/ttyS0"’)
          The device file to connect to the device.

     ‘baud-rate’ (default: ‘#f’)
          Baud rate to use for the serial connection.  Should be a
          number or ‘#f’.

     ‘log-file’ (default: ‘#f’)
          If true, this must be the name of a file to log messages to.

Dictionary Service
..................

The ‘(gnu services dict)’ module provides the following service:

 -- Variable: dicod-service-type
     This is the type of the service that runs the ‘dicod’ daemon, an
     implementation of DICT server (*note (dico)Dicod::).

     You can add ‘open localhost’ to your ‘~/.dico’ file to make
     ‘localhost’ the default server for ‘dico’ client (*note
     (dico)Initialization File::).

          Note: This service is also available for Guix Home, where it
          runs directly with your user privileges (*note
          ‘home-dicod-service-type’: Miscellaneous Home Services.).

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

     ‘dico’ (default: DICO)
          Package object of the GNU Dico dictionary server.

     ‘interfaces’ (default: ’("LOCALHOST"))
          This is the list of IP addresses and ports and possibly socket
          file names to listen to (*note ‘listen’ directive:
          (dico)Server Settings.).

     ‘handlers’ (default: ’())
          List of ‘<dicod-handler>’ objects denoting handlers (module
          instances).

     ‘databases’ (default: (LIST %DICOD-DATABASE:GCIDE))
          List of ‘<dicod-database>’ objects denoting dictionaries to be
          served.

 -- Data Type: dicod-handler
     Data type representing a dictionary handler (module instance).

     ‘name’
          Name of the handler (module instance).

     ‘module’ (default: #F)
          Name of the dicod module of the handler (instance).  If it is
          ‘#f’, the module has the same name as the handler.  (*note
          (dico)Modules::).

     ‘options’
          List of strings or gexps representing the arguments for the
          module handler

 -- Data Type: dicod-database
     Data type representing a dictionary database.

     ‘name’
          Name of the database, will be used in DICT commands.

     ‘handler’
          Name of the dicod handler (module instance) used by this
          database (*note (dico)Handlers::).

     ‘complex?’ (default: #F)
          Whether the database configuration complex.  The complex
          configuration will need a corresponding ‘<dicod-handler>’
          object, otherwise not.

     ‘options’
          List of strings or gexps representing the arguments for the
          database (*note (dico)Databases::).

 -- Variable: %dicod-database:gcide
     A ‘<dicod-database>’ object serving the GNU Collaborative
     International Dictionary of English using the ‘gcide’ package.

 -- Procedure: dicod-freedict-database dictionary-name
     Returns a record of type ‘dicod-database’ for purpose of
     configuring a database for the FreeDict multilingual dictionary
     named by DICTIONARY-NAME, a string such as ‘"kur-eng"’ for the
     Kurdish-to-English dictionary, into a service of type
     ‘dicod-service-type’.

 -- Variable: %dicod-databases:freedict
     A relatively large list of records of type ‘dicod-database’, made
     available for users who wish to configure all the FreeDict
     multilingual dictionaries provided by the ‘freedict-dictionaries’
     package into a service of type ‘dicod-service-type’.

   The following is an example ‘dicod-service-type’ configuration,
extending a ‘dicod’ daemon serving databases for the wordnet and gcide
dictionaries, as well as a selection of FreeDict multilingual
dictionaries.

     (service dicod-service-type
              (dicod-configuration
               (handlers (list
                          (dicod-handler
                           (name "wordnet")
                           (module "wordnet")
                           (options
                            (list #~(string-append "wnhome=" #$wordnet))))))
               (databases (cons*
                           (dicod-database
                            (name "wordnet")
                            (complex? #t)
                            (handler "wordnet"))
                           %dicod-database:gcide
                           (map
                            dicod-freedict-database
                            '("fra-eng" "eng-fra" "eng-spa" "spa-eng"))))))

Docker Service
..............

The ‘(gnu services docker)’ module provides the following services.

 -- Variable: containerd-service-type

     This service type operates containerd containerd
     (https://containerd.io), a daemon responsible for overseeing the
     entire container lifecycle on its host system.  This includes image
     handling, storage management, container execution, supervision,
     low-level storage operations, network connections, and more.

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

     ‘containerd’ (default: ‘containerd’)
          The containerd daemon package to use.

     ‘debug?’ (default ‘#f’)
          Enable or disable debug output.

     ‘environment-variables’ (default: ‘'()’)
          List of environment variables to set for ‘containerd’.

          This must be a list of strings where each string has the form
          ‘KEY=VALUE’ as in this example:

               (list "HTTP_PROXY=socks5://127.0.0.1:9150"
                     "HTTPS_PROXY=socks5://127.0.0.1:9150")

 -- Variable: docker-service-type

     This is the type of the service that runs Docker
     (https://www.docker.com), a daemon that can execute application
     bundles (sometimes referred to as “containers”) in isolated
     environments.

     The ‘containerd-service-type’ service need to be added to a system
     configuration, otherwise a message about not any service provides
     ‘containerd’ will be displayed during ‘guix system reconfigure’.

 -- Data Type: docker-configuration
     This is the data type representing the configuration of Docker and
     Containerd.

     ‘docker’ (default: ‘docker’)
          The Docker daemon package to use.

     ‘docker-cli’ (default: ‘docker-cli’)
          The Docker client package to use.

     ‘containerd’ (default: CONTAINERD)
          This field is deprecated in favor of ‘containerd-service-type’
          service.

     ‘proxy’ (default DOCKER-LIBNETWORK-CMD-PROXY)
          The Docker user-land networking proxy package to use.

     ‘enable-proxy?’ (default ‘#t’)
          Enable or disable the use of the Docker user-land networking
          proxy.

     ‘debug?’ (default ‘#f’)
          Enable or disable debug output.

     ‘enable-iptables?’ (default ‘#t’)
          Enable or disable the addition of iptables rules.

     ‘environment-variables’ (default: ‘'()’)
          List of environment variables to set for ‘dockerd’.

          This must be a list of strings where each string has the form
          ‘KEY=VALUE’ as in this example:

               (list "LANGUAGE=eo:ca:eu"
                     "TMPDIR=/tmp/dockerd")

     ‘config-file’ (type: maybe-file-like)
          JSON configuration file pass to ‘dockerd’.

 -- Variable: singularity-service-type
     This is the type of the service that allows you to run Singularity
     (https://www.sylabs.io/singularity/), a Docker-style tool to create
     and run application bundles (aka.  “containers”).  The value for
     this service is the Singularity package to use.

     The service does not install a daemon; instead, it installs helper
     programs as setuid-root (*note Privileged Programs::) such that
     unprivileged users can invoke ‘singularity run’ and similar
     commands.

Rootless Podman Service
.......................

The ‘(gnu services containers)’ module provides the following service.

 -- Variable: rootless-podman-service-type
     This is the service type for Podman (https://podman.io) is a
     container management tool.

     In addition to providing a drop-in replacement for Docker, Podman
     offers the ability to run containers in “root-less” mode, meaning
     that regular users can deploy containers without elevated
     privileges.  It does so mainly by leveraging two Linux kernel
     features: unprivileged user namespaces, and subordinate user and
     group IDs (*note the subordinate user and group ID service:
     subordinate-user-group-ids.).

     The ‘rootless-podman-service-type’ sets up the system to allow
     unprivileged users to run ‘podman’ commands:

          (use-service-modules containers dbus desktop networking ...)
          (use-modules (gnu system accounts))  ;for 'subid-range'

          (operating-system
            ;; ...
            (users (cons (user-account
                          (name "alice")
                          (comment "Bob's sister")
                          (group "users")

                          ;; Adding the account to the "cgroup" group
                          ;; makes it possible to run podman commands.
                          (supplementary-groups '("cgroup" "wheel"
                                                  "audio" "video")))
                         %base-user-accounts))
            (services
              (cons* (service dbus-root-service-type)
                     (service dhcpcd-service-type)
                     (service elogind-service-type)
                     (service iptables-service-type)
                     (service rootless-podman-service-type
                              (rootless-podman-configuration
                                (subgids
                                 (list (subid-range (name "alice"))))
                                (subuids
                                 (list (subid-range (name "alice"))))))
                     %base-services)))

     The ‘iptables-service-type’ is required for Podman to be able to
     setup its own networks.  Due to the change in user groups and file
     systems it is recommended to reboot (or at least logout), before
     trying to run Podman commands.

     To test your installation you can run:

          $ podman run -it --rm docker.io/alpine cat /etc/*release*
          NAME="Alpine Linux"
          ID=alpine
          VERSION_ID=3.20.2
          PRETTY_NAME="Alpine Linux v3.20"
          HOME_URL="https://alpinelinux.org/"
          BUG_REPORT_URL="https://gitlab.alpinelinux.org/alpine/aports/-/issues"

 -- Data Type: rootless-podman-configuration
     Available ‘rootless-podman-configuration’ fields are:

     ‘podman’ (default: ‘podman’) (type: package-or-#f)
          The Podman package that will be installed in the system
          profile.  Pass ‘#f’ to not install Podman.

     ‘group-name’ (default: ‘"cgroup"’) (type: string)
          The name of the group that will own /sys/fs/cgroup resources.
          Users that want to use rootless Podman have to be in this
          group.

     ‘containers-registries’ (type: lowerable)
          A string or a gexp evaluating to the path of Podman’s
          ‘containers/registries.conf’ configuration file.

     ‘containers-storage’ (type: lowerable)
          A string or a gexp evaluating to the path of Podman’s
          ‘containers/storage.conf’ configuration file.

     ‘containers-policy’ (type: lowerable)
          A string or a gexp evaluating to the path of Podman’s
          ‘containers/policy.json’ configuration file.

     ‘pam-limits’ (type: list-of-pam-limits-entries)
          The PAM limits to be set for rootless Podman.

     ‘subgids’ (default: ‘()’) (type: list-of-subid-ranges)
          A list of subid ranges representing the subgids that will be
          available for each configured user.

     ‘subuids’ (default: ‘()’) (type: list-of-subid-ranges)
          A list of subid ranges representing the subuids that will be
          available for each configured user.

OCI backed services
...................

Should you wish to manage your Open Container Initiative (OCI)
containers with the same consistent interface you use for your other
Shepherd services, OCI-SERVICE-TYPE is the tool to use: given an OCI
container image, it will run it in a Shepherd service.  One example
where this is useful: it lets you run services that are available as OCI
images but not yet packaged for Guix.

 -- Variable: oci-service-type

     This is a thin wrapper around Docker’s or Podman’s CLI that
     executes OCI images backed processes as Shepherd Services.

          (simple-service 'oci-provisioning
                          oci-service-type
                          (oci-extension
                            (networks
                              (list
                                (oci-network-configuration (name "monitoring"))))
                            (containers
                             (list
                              (oci-container-configuration
                               (network "monitoring")
                               (image
                                (oci-image
                                  (repository "guile")
                                  (tag "3")
                                  (value (specifications->manifest '("guile")))
                                  (pack-options '(#:symlinks (("/bin/guile" -> "bin/guile"))
                                                  #:max-layers 2))))
                               (entrypoint "/bin/guile")
                               (command
                                '("-c" "(display \"hello!\n\")")))
                              (oci-container-configuration
                                (image "prom/prometheus")
                                (network "host")
                                (ports
                                 '(("9000" . "9000")
                                   ("9090" . "9090"))))
                              (oci-container-configuration
                                (image "grafana/grafana:10.0.1")
                                (network "host")
                                (volumes
                                 '("/var/lib/grafana:/var/lib/grafana")))))))

     In this example three different Shepherd services are going to be
     added to the system.  Each ‘oci-container-configuration’ record
     translates to a ‘docker run’ or ‘podman run’ invocation and its
     fields directly map to options.  You can refer to the Docker
     (https://docs.docker.com/engine/reference/commandline/run) or
     Podman
     (https://docs.podman.io/en/stable/markdown/podman-run.1.html)
     upstream documentation for semantics of each value.  If the images
     are not found, they will be pulled.  You can refer to the Docker
     (https://docs.docker.com/engine/reference/commandline/pull/) or
     Podman
     (https://docs.podman.io/en/stable/markdown/podman-pull.1.html)
     upstream documentation for semantics.  The services with ‘(network
     "host")’ are going to be attached to the host network and are
     supposed to behave like native processes with regard to networking.

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

     ‘runtime’ (default: ‘'docker’) (type: symbol)
          The OCI runtime to use to run commands.  It can be either
          ‘'docker’ or ‘'podman’.

     ‘runtime-cli’ (type: maybe-package-or-string)
          The OCI runtime command line to be installed in the system
          profile and used to provision OCI resources, it can be either
          a package or a string representing an absolute file name to
          the runtime binary entrypoint.  When unset it will default to
          ‘docker-cli’ package for the ‘'docker’ runtime or to ‘podman’
          package for the ‘'podman’ runtime.

     ‘runtime-extra-arguments’ (default: ‘'()’) (type: list)
          A list of strings, gexps or file-like objects that will be
          placed after each ‘docker’ or ‘podman’ invokation.

     ‘user’ (type: maybe-string)
          The user name under whose authority OCI commands will be run.
          This field will override the ‘user’ field of
          ‘oci-configuration’.

     ‘group’ (type: maybe-string)
          The group name under whose authority OCI commands will be run.
          When using the ‘'podman’ OCI runtime, this field will be
          ignored and the default group of the user configured in the
          ‘user’ field will be used.  This field will override the
          ‘group’ field of ‘oci-configuration’.

     ‘subuids-range’ (type: maybe-subid-range)
          An optional ‘subid-range’ record allocating subuids for the
          user from the ‘user’ field.  When unset, with the rootless
          Podman OCI runtime, it defaults to ‘(subid-range (name
          "oci-container"))’.

     ‘subgids-range’ (type: maybe-subid-range)
          An optional ‘subid-range’ record allocating subgids for the
          user from the ‘user’ field.  When unset, with the rootless
          Podman OCI runtime, it defaults to ‘(subid-range (name
          "oci-container"))’.

     ‘containers’ (default: ‘'()’) (type: list-of-oci-containers)
          The list of ‘oci-container-configuration’ records representing
          the containers to provision.  The use of the ‘oci-extension’
          record should be preferred for most cases.

     ‘networks’ (default: ‘'()’) (type: list-of-oci-networks)
          The list of ‘oci-network-configuration’ records representing
          the containers to provision.  The use of the ‘oci-extension’
          record should be preferred for most cases.

     ‘volumes’ (default: ‘'()’) (type: list-of-oci-volumes)
          The list of ‘oci-volumes-configuration’ records representing
          the containers to provision.  The use of the ‘oci-extension’
          record should be preferred for most cases.

     ‘verbose?’ (default: ‘#f’) (type: boolean)
          When true, additional output will be printed, allowing to
          better follow the flow of execution.

 -- Data Type: oci-extension
     Available ‘oci-extension’ fields are:

     ‘containers’ (default: ‘'()’) (type: list-of-oci-containers)
          The list of ‘oci-container-configuration’ records representing
          the containers to provision.

     ‘networks’ (default: ‘'()’) (type: list-of-oci-networks)
          The list of ‘oci-network-configuration’ records representing
          the containers to provision.

     ‘volumes’ (default: ‘'()’) (type: list-of-oci-volumes)
          The list of ‘oci-volumes-configuration’ records representing
          the containers to provision.

 -- Data Type: oci-container-configuration
     Available ‘oci-container-configuration’ fields are:

     ‘user’ (default: ‘"oci-container"’) (type: string)
          The user under whose authority docker commands will be run.

     ‘group’ (default: ‘"docker"’) (type: string)
          The group under whose authority docker commands will be run.

     ‘command’ (default: ‘'()’) (type: list-of-strings)
          Overwrite the default command (‘CMD’) of the image.

     ‘entrypoint’ (default: ‘""’) (type: string)
          Overwrite the default entrypoint (‘ENTRYPOINT’) of the image.

     ‘host-environment’ (default: ‘'()’) (type: list)
          Set environment variables in the host environment where
          ‘docker run’ or ‘podman run’ are invoked.  This is especially
          useful to pass secrets from the host to the container without
          having them on the OCI runtime command line, for example: by
          setting the ‘MYSQL_PASSWORD’ on the host and by passing ‘--env
          MYSQL_PASSWORD’ through the ‘extra-arguments’ field, it is
          possible to securely set values in the container environment.
          This field’s value can be a list of pairs or strings, even
          mixed:

               (list '("LANGUAGE" . "eo:ca:eu")
                     "JAVA_HOME=/opt/java")

          Pair members can be strings, gexps or file-like objects.
          Strings are passed directly to ‘make-forkexec-constructor’.

     ‘environment’ (default: ‘'()’) (type: list)
          Set environment variables inside the container.  This can be a
          list of pairs or strings, even mixed:

               (list '("LANGUAGE" . "eo:ca:eu")
                     "JAVA_HOME=/opt/java")

          Pair members can be strings, gexps or file-like objects.
          Strings are passed directly to the OCI runtime CLI. You can
          refer to the Docker
          (https://docs.docker.com/engine/reference/commandline/run/#env)
          or Podman
          (https://docs.podman.io/en/stable/markdown/podman-run.1.html#env-e-env)
          upstream documentation for semantics.

     ‘image’ (type: string-or-oci-image)
          The image used to build the container.  It can be a string or
          an ‘oci-image’ record.  Strings are resolved by the OCI
          runtime, and follow the usual format
          ‘myregistry.local:5000/testing/test-image:tag’.

     ‘provision’ (default: ‘""’) (type: string)
          Set the name of the provisioned Shepherd service.

     ‘requirement’ (default: ‘'()’) (type: list-of-symbols)
          Set additional Shepherd services dependencies to the
          provisioned Shepherd service.

     ‘log-file’ (type: maybe-string)
          When ‘log-file’ is set, it names the file to which the
          service’s standard output and standard error are redirected.
          ‘log-file’ is created if it does not exist, otherwise it is
          appended to.

     ‘auto-start?’ (default: ‘#t’) (type: boolean)
          Whether this service should be started automatically by the
          Shepherd.  If it is ‘#f’, the service has to be started
          manually with ‘herd start’.

     ‘respawn?’ (default: ‘#f’) (type: boolean)
          Whether to have Shepherd restart the service when it stops,
          for instance when the underlying process dies.

     ‘shepherd-actions’ (default: ‘'()’) (type: list-of-shepherd-actions)
          This is a list of ‘shepherd-action’ records defining actions
          supported by the service.

     ‘network’ (default: ‘""’) (type: string)
          Set an OCI network for the spawned container.

     ‘ports’ (default: ‘'()’) (type: list)
          Set the port or port ranges to expose from the spawned
          container.  This can be a list of pairs or strings, even
          mixed:

               (list '("8080" . "80")
                     "10443:443")

          Pair members can be strings, gexps or file-like objects.
          Strings are passed directly to the OCI runtime CLI. You can
          refer to the Docker
          (https://docs.docker.com/engine/reference/commandline/run/#publish)
          or Podman
          (https://docs.podman.io/en/stable/markdown/podman-run.1.html#publish-p-ip-hostport-containerport-protocol)
          upstream documentation for semantics.

     ‘volumes’ (default: ‘'()’) (type: list)
          Set volume mappings for the spawned container.  This can be a
          list of pairs or strings, even mixed:

               (list '("/root/data/grafana" . "/var/lib/grafana")
                     "/gnu/store:/gnu/store")

          Pair members can be strings, gexps or file-like objects.
          Strings are passed directly to the OCI runtime CLI. You can
          refer to the Docker
          (https://docs.docker.com/engine/reference/commandline/run/#volume)
          or Podman
          (https://docs.podman.io/en/stable/markdown/podman-run.1.html#volume-v-source-volume-host-dir-container-dir-options)
          upstream documentation for semantics.

     ‘container-user’ (default: ‘""’) (type: string)
          Set the current user inside the spawned container.  You can
          refer to the Docker
          (https://docs.docker.com/engine/reference/run/#user) or Podman
          (https://docs.podman.io/en/stable/markdown/podman-run.1.html#user-u-user-group)
          upstream documentation for semantics.

     ‘workdir’ (default: ‘""’) (type: string)
          Set the current working directory for the spawned Shepherd
          service.  You can refer to the Docker
          (https://docs.docker.com/engine/reference/run/#workdir) or
          Podman
          (https://docs.podman.io/en/stable/markdown/podman-run.1.html#workdir-w-dir)
          upstream documentation for semantics.

     ‘extra-arguments’ (default: ‘'()’) (type: list)
          A list of strings, gexps or file-like objects that will be
          directly passed to the ‘docker run’ or ‘podman run’
          invokation.

 -- Data Type: oci-network-configuration
     Available ‘oci-network-configuration’ fields are:

     ‘name’ (type: string)
          The name of the OCI network to provision.

     ‘driver’ (type: maybe-string)
          The driver to manage the network.

     ‘gateway’ (type: maybe-string)
          IPv4 or IPv6 gateway for the subnet.

     ‘internal?’ (default: ‘#f’) (type: boolean)
          Restrict external access to the network

     ‘ip-range’ (type: maybe-string)
          Allocate container ip from a sub-range in CIDR format.

     ‘ipam-driver’ (type: maybe-string)
          IP Address Management Driver.

     ‘ipv6?’ (default: ‘#f’) (type: boolean)
          Enable IPv6 networking.

     ‘subnet’ (type: maybe-string)
          Subnet in CIDR format that represents a network segment.

     ‘labels’ (default: ‘'()’) (type: list)
          The list of labels that will be used to tag the current
          volume.

     ‘extra-arguments’ (default: ‘'()’) (type: list)
          A list of strings, gexps or file-like objects that will be
          directly passed to the ‘docker network create’ or ‘podman
          network create’ invokation.

 -- Data Type: oci-volume-configuration
     Available ‘oci-volume-configuration’ fields are:

     ‘name’ (type: string)
          The name of the OCI volume to provision.

     ‘labels’ (default: ‘'()’) (type: list)
          The list of labels that will be used to tag the current
          volume.

     ‘extra-arguments’ (default: ‘'()’) (type: list)
          A list of strings, gexps or file-like objects that will be
          directly passed to the ‘docker volume create’ or ‘podman
          volume create’ invokation.

 -- Data Type: oci-image
     Available ‘oci-image’ fields are:

     ‘repository’ (type: string)
          A string like ‘myregistry.local:5000/testing/test-image’ that
          names the OCI image.

     ‘tag’ (default: ‘"latest"’) (type: string)
          A string representing the OCI image tag.  Defaults to
          ‘latest’.

     ‘value’ (type: oci-lowerable-image)
          A ‘manifest’ or ‘operating-system’ record that will be lowered
          into an OCI compatible tarball.  Otherwise this field’s value
          can be a file-like object that evaluates to an OCI compatible
          tarball.

     ‘pack-options’ (default: ‘'()’) (type: list)
          An optional set of keyword arguments that will be passed to
          the ‘docker-image’ procedure from ‘guix scripts pack’.  They
          can be used to replicate ‘guix pack’ behavior:

               (oci-image
                 (repository "guile")
                 (tag "3")
                 (value
                   (specifications->manifest '("guile")))
                 (pack-options '(#:symlinks (("/bin/guile" -> "bin/guile"))
                                 #:max-layers 2)))

          If the ‘value’ field is an ‘operating-system’ record, this
          field’s value will be ignored.

     ‘system’ (default: ‘""’) (type: string)
          Attempt to build for a given system, e.g. "i686-linux"

     ‘target’ (default: ‘""’) (type: string)
          Attempt to cross-build for a given triple, e.g.
          "aarch64-linux-gnu"

     ‘grafts?’ (default: ‘#f’) (type: boolean)
          Whether to allow grafting or not in the pack build.

Subordinate User and Group ID Service
.....................................

Among the virtualization facilities implemented by the Linux kernel is
the concept of “subordinate IDs”.  Subordinate IDs allow for mapping
user and group IDs inside process namespaces to user and group IDs of
the host system.  Subordinate user ID ranges (subuids) allow users to
map virtual user IDs inside containers to the user ID of an unprivileged
user of the host system.  Subordinate group ID ranges (subgids), instead
map virtual group IDs to the group ID of an unprivileged user on the
host system.  You can access ‘subuid(5)’ and ‘subgid(5)’ Linux man pages
for more details.

   The ‘(gnu system shadow)’ module exposes the ‘subids-service-type’,
its configuration record ‘subids-configuration’ and its extension record
‘subids-extension’.

   With ‘subids-service-type’, subuids and subgids ranges can be
reserved for users that desire so:

     (use-modules (gnu system shadow)     ;for 'subids-service-type'
                  (gnu system accounts)   ;for 'subid-range'
                  ...)

     (operating-system
       ;; ...
       (services
         (list
           (simple-service 'alice-bob-subids
                           subids-service-type
                           (subids-extension
                             (subgids
                              (list
                               (subid-range (name "alice"))))
                             (subuids
                              (list
                               (subid-range (name "alice"))
                               (subid-range (name "bob")
                                            (start 100700)))))))))

   Users (definitely other services), usually, are supposed to extend
the service instead of adding subids directly to ‘subids-configuration’,
unless the want to change the default behavior for root.  With default
settings the ‘subids-service-type’ adds, if it’s not already there, a
configuration for the root account to both ‘/etc/subuid’ and
‘/etc/subgid’, possibly starting at the minimum possible subid.
Otherwise the root subuids and subgids ranges are fitted wherever
possible.

   The above configuration will yield the following:

     # cat /etc/subgid
     root:100000:65536
     alice:165536:65536
     # cat /etc/subuid
     root:100000:700
     bob:100700:65536
     alice:166236:65536

 -- Data Type: subids-configuration

     With default settings the ‘subids-service-type’ adds, if it’s not
     already there, a configuration for the root account to both
     ‘/etc/subuid’ and ‘/etc/subgid’, possibly starting at the minimum
     possible subid.  To disable the default behavior and provide your
     own definition for the root subid ranges you can set to ‘#f’ the
     ‘add-root?’ field:

          (use-modules (gnu system shadow)     ;for 'subids-service-type'
                       (gnu system accounts)   ;for 'subid-range'
                       ...)

          (operating-system
            ;; ...
            (services
              (list
                (service subids-service-type
                         (subids-configuration
                          (add-root? #f)
                          (subgids
                            (subid-range (name "root")
                                         (start 120000)
                                         (count 100)))
                          (subuids
                            (subid-range (name "root")
                                         (start 120000)
                                         (count 100)))))
                (simple-service 'alice-bob-subids
                                subids-service-type
                                (subids-extension
                                  (subgids
                                   (list
                                    (subid-range (name "alice"))))
                                  (subuids
                                   (list
                                    (subid-range (name "alice"))
                                    (subid-range (name "bob")
                                                 (start 100700)))))))))

     Available ‘subids-configuration’ fields are:

     ‘add-root?’ (default: ‘#t’) (type: boolean)
          Whether to automatically configure subuids and subgids for
          root.

     ‘subgids’ (default: ‘'()’) (type: list-of-subid-ranges)
          The list of ‘subid-range’s that will be serialized to
          ‘/etc/subgid’.  If a range doesn’t specify a start it will be
          fitted based on its number of requested subids.  If a range
          doesn’t specify a count the default size of 65536 will be
          assumed.

     ‘subuids’ (default: ‘'()’) (type: list-of-subid-ranges)
          The list of ‘subid-range’s that will be serialized to
          ‘/etc/subuid’.  If a range doesn’t specify a start it will be
          fitted based on its number of requested subids.  If a range
          doesn’t specify a count the default size of 65536 will be
          assumed.

 -- Data Type: subids-extension

     Available ‘subids-extension’ fields are:

     ‘subgids’ (default: ‘'()’) (type: list-of-subid-ranges)
          The list of ‘subid-range’s that will be appended to
          ‘subids-configuration-subgids’.  Entries with the same name
          are deduplicated upon merging.

     ‘subuids’ (default: ‘'()’) (type: list-of-subid-ranges)
          The list of ‘subid-range’s that will be appended to
          ‘subids-configuration-subuids’.  Entries with the same name
          are deduplicated upon merging.

 -- Data Type: subid-range

     The ‘subid-range’ record is defined at ‘(gnu system accounts)’.
     Available fields are:

     ‘name’ (type: string)
          The name of the user or group that will own this range.

     ‘start’ (default: ‘#f’) (type: integer)
          The first requested subid.  When false the first available
          subid with enough contiguous subids will be assigned.

     ‘count’ (default: ‘#f’) (type: integer)
          The number of total allocated subids.  When #f the default of
          65536 will be assumed .

Auditd Service
..............

The ‘(gnu services auditd)’ module provides the following service.

 -- Variable: auditd-service-type

     This is the type of the service that runs auditd
     (https://people.redhat.com/sgrubb/audit/), a daemon that tracks
     security-relevant information on your system.

     Examples of things that can be tracked:

       1. File accesses
       2. System calls
       3. Invoked commands
       4. Failed login attempts
       5. Firewall filtering
       6. Network access

     ‘auditctl’ from the ‘audit’ package can be used in order to add or
     remove events to be tracked (until the next reboot).  In order to
     permanently track events, put the command line arguments of
     auditctl into a file called ‘audit.rules’ in the configuration
     directory (see below).  ‘aureport’ from the ‘audit’ package can be
     used in order to view a report of all recorded events.  The audit
     daemon by default logs into the file ‘/var/log/audit.log’.

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

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

     ‘configuration-directory’ (default: ‘%default-auditd-configuration-directory’)
          The directory containing the configuration file for the audit
          package, which must be named ‘auditd.conf’, and optionally
          some audit rules to instantiate on startup.

R-Shiny service
...............

The ‘(gnu services science)’ module provides the following service.

 -- Variable: rshiny-service-type

     This is a type of service which is used to run a webapp created
     with ‘r-shiny’.  This service sets the ‘R_LIBS_USER’ environment
     variable and runs the provided script to call ‘runApp’.

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

          ‘package’ (default: ‘r-shiny’)
               The package to use.

          ‘binary’ (default ‘"rshiny"’)
               The name of the binary or shell script located at
               ‘package/bin/’ to run when the service is run.

               The common way to create this file is as follows:

                    ...
                    (let* ((out       (assoc-ref %outputs "out"))
                           (targetdir (string-append out "/share/" ,name))
                           (app       (string-append out "/bin/" ,name))
                           (Rbin      (search-input-file %build-inputs "/bin/Rscript")))
                      ;; ...
                      (mkdir-p (string-append out "/bin"))
                      (call-with-output-file app
                        (lambda (port)
                          (format port
                    "#!~a
                    library(shiny)
                    setwd(\"~a\")
                    runApp(launch.browser=0, port=4202)~%\n"
                          Rbin targetdir))))

Nix service
...........

The ‘(gnu services nix)’ module provides the following service.

 -- Variable: nix-service-type

     This is the type of the service that runs build daemon of the Nix
     (https://nixos.org/nix/) package manager.  Here is an example
     showing how to use it:

          (use-modules (gnu))
          (use-service-modules nix)
          (use-package-modules package-management)

          (operating-system
            ;; ...
            (packages (append (list nix)
                              %base-packages))

            (services (append (list (service nix-service-type))
                              %base-services)))

     After ‘guix system reconfigure’ configure Nix for your user:

        • Add a Nix channel and update it.  See Nix channels
          (https://wiki.nixos.org/wiki/Nix_channels) for more
          information about the available channels.  If you would like
          to use the unstable Nix channel you can do this by running:

               $ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
               $ nix-channel --update

        • Create your Nix profile directory:

               $ sudo mkdir -p /nix/var/nix/profiles/per-user/$USER
               $ sudo chown $USER:root /nix/var/nix/profiles/per-user/$USER

        • Create a symlink to your profile and activate Nix profile:

               $ ln -s "/nix/var/nix/profiles/per-user/$USER/profile" ~/.nix-profile
               $ source /run/current-system/profile/etc/profile.d/nix.sh

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

     ‘nix’ (default: ‘nix’)
          The Nix package to use.

     ‘sandbox’ (default: ‘#t’)
          Specifies whether builds are sandboxed by default.

     ‘build-directory’ (default: ‘"/tmp"’)
          The directory where build directory are stored during builds.
          This is useful to change if, for example, the default location
          does not have enough space to hold build trees for big
          packages.

          This is similar to setting the ‘TMPDIR’ environment variable
          for ‘guix-daemon’.  *note ‘TMPDIR’: Build Environment Setup,
          for more info.

     ‘build-sandbox-items’ (default: ‘'()’)
          This is a list of strings or objects appended to the
          ‘build-sandbox-items’ field of the configuration file.

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

     ‘extra-options’ (default: ‘'()’)
          Extra command line options for ‘nix-service-type’.

Fail2Ban service
................

‘fail2ban’ (http://www.fail2ban.org/) scans log files (e.g.
‘/var/log/apache/error_log’) and bans IP addresses that show malicious
signs – repeated password failures, attempts to make use of exploits,
etc.

   ‘fail2ban-service-type’ service type is provided by the ‘(gnu
services security)’ module.

   This service type runs the ‘fail2ban’ daemon.  It can be configured
in various ways, which are:

Basic configuration
     The basic parameters of the Fail2Ban service can be configured via
     its ‘fail2ban’ configuration, which is documented below.

User-specified jail extensions
     The ‘fail2ban-jail-service’ function can be used to add new
     Fail2Ban jails.

Shepherd extension mechanism
     Service developers can extend the ‘fail2ban-service-type’ service
     type itself via the usual service extension mechanism.

 -- Variable: fail2ban-service-type

     This is the type of the service that runs ‘fail2ban’ daemon.  Below
     is an example of a basic, explicit configuration:

          (append
           (list
            (service fail2ban-service-type
                     (fail2ban-configuration
                      (extra-jails
                       (list
                        (fail2ban-jail-configuration
                         (name "sshd")
                         (enabled? #t))))))
            ;; There is no implicit dependency on an actual SSH
            ;; service, so you need to provide one.
            (service openssh-service-type))
           %base-services)

 -- Procedure: fail2ban-jail-service svc-type jail
     Extend SVC-TYPE, a ‘<service-type>’ object with JAIL, a
     ‘fail2ban-jail-configuration’ object.

     For example:

          (append
           (list
            (service
             ;; The 'fail2ban-jail-service' procedure can extend any service type
             ;; with a fail2ban jail.  This removes the requirement to explicitly
             ;; extend services with fail2ban-service-type.
             (fail2ban-jail-service
              openssh-service-type
              (fail2ban-jail-configuration
               (name "sshd")
               (enabled? #t)))
             (openssh-configuration ...))))

   Below is the reference for the different ‘jail-service-type’
configuration records.

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

     ‘fail2ban’ (default: ‘fail2ban’) (type: package)
          The ‘fail2ban’ package to use.  It is used for both binaries
          and as base default configuration that is to be extended with
          ‘<fail2ban-jail-configuration>’ objects.

     ‘run-directory’ (default: ‘"/var/run/fail2ban"’) (type: string)
          The state directory for the ‘fail2ban’ daemon.

     ‘jails’ (default: ‘'()’) (type: list-of-fail2ban-jail-configurations)
          Instances of ‘<fail2ban-jail-configuration>’ collected from
          extensions.

     ‘extra-jails’ (default: ‘'()’) (type: list-of-fail2ban-jail-configurations)
          Instances of ‘<fail2ban-jail-configuration>’ explicitly
          provided.

     ‘extra-content’ (default: ‘'()’) (type: text-config)
          Extra raw content to add to the end of the ‘jail.local’ file,
          provided as a list of file-like objects.

 -- Data Type: fail2ban-ignore-cache-configuration
     Available ‘fail2ban-ignore-cache-configuration’ fields are:

     ‘key’ (type: string)
          Cache key.

     ‘max-count’ (type: integer)
          Cache size.

     ‘max-time’ (type: integer)
          Cache time.

 -- Data Type: fail2ban-jail-action-configuration
     Available ‘fail2ban-jail-action-configuration’ fields are:

     ‘name’ (type: string)
          Action name.

     ‘arguments’ (default: ‘'()’) (type: list-of-arguments)
          Action arguments.

 -- Data Type: fail2ban-jail-configuration
     Available ‘fail2ban-jail-configuration’ fields are:

     ‘name’ (type: string)
          Required name of this jail configuration.

     ‘enabled?’ (default: ‘#t’) (type: boolean)
          Whether this jail is enabled.

     ‘backend’ (type: maybe-symbol)
          Backend to use to detect changes in the ‘log-path’.  The
          default is ’auto.  To consult the defaults of the jail
          configuration, refer to the ‘/etc/fail2ban/jail.conf’ file of
          the ‘fail2ban’ package.

     ‘max-retry’ (type: maybe-integer)
          The number of failures before a host gets banned (e.g.
          ‘(max-retry 5)’).

     ‘max-matches’ (type: maybe-integer)
          The number of matches stored in ticket (resolvable via tag
          ‘<matches>’) in action.

     ‘find-time’ (type: maybe-string)
          The time window during which the maximum retry count must be
          reached for an IP address to be banned.  A host is banned if
          it has generated ‘max-retry’ during the last ‘find-time’
          seconds (e.g.  ‘(find-time "10m")’).  It can be provided in
          seconds or using Fail2Ban’s "time abbreviation format", as
          described in ‘man 5 jail.conf’.

     ‘ban-time’ (type: maybe-string)
          The duration, in seconds or time abbreviated format, that a
          ban should last.  (e.g.  ‘(ban-time "10m")’).

     ‘ban-time-increment?’ (type: maybe-boolean)
          Whether to consider past bans to compute increases to the
          default ban time of a specific IP address.

     ‘ban-time-factor’ (type: maybe-string)
          The coefficient to use to compute an exponentially growing ban
          time.

     ‘ban-time-formula’ (type: maybe-string)
          This is the formula used to calculate the next value of a ban
          time.

     ‘ban-time-multipliers’ (type: maybe-string)
          Used to calculate next value of ban time instead of formula.

     ‘ban-time-max-time’ (type: maybe-string)
          The maximum number of seconds a ban should last.

     ‘ban-time-rnd-time’ (type: maybe-string)
          The maximum number of seconds a randomized ban time should
          last.  This can be useful to stop “clever” botnets calculating
          the exact time an IP address can be unbanned again.

     ‘ban-time-overall-jails?’ (type: maybe-boolean)
          When true, it specifies the search of an IP address in the
          database should be made across all jails.  Otherwise, only the
          current jail of the ban IP address is considered.

     ‘ignore-self?’ (type: maybe-boolean)
          Never ban the local machine’s own IP address.

     ‘ignore-ip’ (default: ‘'()’) (type: list-of-strings)
          A list of IP addresses, CIDR masks or DNS hosts to ignore.
          ‘fail2ban’ will not ban a host which matches an address in
          this list.

     ‘ignore-cache’ (type: maybe-fail2ban-ignore-cache-configuration)
          Provide cache parameters for the ignore failure check.

     ‘filter’ (type: maybe-fail2ban-jail-filter-configuration)
          The filter to use by the jail, specified via a
          ‘<fail2ban-jail-filter-configuration>’ object.  By default,
          jails have names matching their filter name.

     ‘log-time-zone’ (type: maybe-string)
          The default time zone for log lines that do not have one.

     ‘log-encoding’ (type: maybe-symbol)
          The encoding of the log files handled by the jail.  Possible
          values are: ‘'ascii’, ‘'utf-8’ and ‘'auto’.

     ‘log-path’ (default: ‘'()’) (type: list-of-strings)
          The file names of the log files to be monitored.

     ‘action’ (default: ‘'()’) (type: list-of-fail2ban-jail-actions)
          A list of ‘<fail2ban-jail-action-configuration>’.

     ‘extra-content’ (default: ‘'()’) (type: text-config)
          Extra content for the jail configuration, provided as a list
          of file-like objects.

 -- Data Type: fail2ban-jail-filter-configuration
     Available ‘fail2ban-jail-filter-configuration’ fields are:

     ‘name’ (type: string)
          Filter to use.

     ‘mode’ (type: maybe-string)
          Mode for filter.

Resize File System Service
..........................

This service type lets you resize a live file system during boot, which
can be convenient if a Guix image is flashed on an SD Card (e.g.  for an
embedded device) or uploaded to a VPS. In both cases the medium the
image will reside upon may be larger than the image you want to produce.

   For an embedded device booting from an SD card you may use something
like:
     (service resize-file-system-service-type
              (resize-file-system-configuration
               (file-system
                (file-system (device (file-system-label "root"))
                             (type "ext4")))))

     Warning: Be extra cautious to use the correct device and type.  The
     service has little error handling of its own and relies on the
     underlying tools.  Wrong use could end in loss of data or the
     corruption of the operating system.

   Partitions and file systems are grown to the maximum size available.
File systems can only grow when they are on the last partition on a
device and have empty space available.

   This service supports the ext2, ext3, ext4, btrfs, and bcachefs file
systems.

‘file-system’ (type: file-system)
     The file-system object to resize (*note File Systems::).  This
     object must have the ‘device’ and ‘type’ fields set.  Other fields
     are ignored.

‘cloud-utils’ (default: ‘cloud-utils’) (type: file-like)
     The cloud-utils package to use.  This package is used for the
     ‘growpart’ command.

‘e2fsprogs’ (default: ‘e2fsprogs’) (type: file-like)
     The e2fsprogs package to use, used for resizing ext2, ext3, and
     ext4 file systems.

‘btrfs-progs’ (default: ‘btrfs-progs’) (type: file-like)
     The btrfs-progs package to use, used for resizing the btrfs file
     system.

‘bcachefs-tools’ (default: ‘bcachefs-tools’) (type: file-like)
     The bcachefs-tools package to use, used for resizing the bcachefs
     file system.

Backup Services
...............

The ‘(gnu services backup)’ module offers services for backing up file
system trees.  For now, it provides the ‘restic-backup-service-type’.

   With ‘restic-backup-service-type’, you can periodically back up
directories and files with Restic (https://restic.net/), which supports
end-to-end encryption and deduplication.  Consider the following
configuration:

     (use-service-modules backup ...) ;for 'restic-backup-service-type'
     (use-package-modules sync ...)   ;for 'rclone'

     (operating-system
       ;; ...
       (packages (append (list rclone)    ;for use by restic
                         %base-packages))
       (services
         (list
           (service restic-backup-service-type
                    (restic-backup-configuration
                      (jobs
                        (list (restic-backup-job
                                (name "remote-ftp")
                                (repository "rclone:remote-ftp:backup/restic")
                                (password-file "/root/.restic")
                                ;; Every day at 23.
                                (schedule "0 23 * * *")
                                (files '("/root/.restic"
                                         "/root/.config/rclone"
                                         "/etc/ssh/ssh_host_rsa_key"
                                         "/etc/ssh/ssh_host_rsa_key.pub"
                                         "/etc/guix/signing-key.pub"
                                         "/etc/guix/signing-key.sec"))))))))))

   Each ‘restic-backup-job’ translates to a Shepherd timer which sets
the ‘RESTIC_PASSWORD’ environment variable by reading the first line of
‘password-file’ and runs ‘restic backup’, creating backups using rclone
of all the files listed in the ‘files’ field.

   The ‘restic-backup-service-type’ provides the ability to
instantaneously trigger a backup with the ‘trigger’ Shepherd action:

     sudo herd trigger remote-ftp

 -- Data Type: restic-backup-configuration
     Available ‘restic-backup-configuration’ fields are:

     ‘jobs’ (default: ‘'()’) (type: list-of-restic-backup-jobs)
          The list of backup jobs for the current system.

 -- Data Type: restic-backup-job
     Available ‘restic-backup-job’ fields are:

     ‘restic’ (default: ‘restic’) (type: package)
          The restic package to be used for the current job.

     ‘user’ (default: ‘"root"’) (type: string)
          The user used for running the current job.

     ‘group’ (default: ‘"root"’) (type: string)
          The group used for running the current job.

     ‘log-file’ (type: maybe-string)
          The file system path to the log file for this job.  By default
          the file will have be ‘/var/log/restic-backup/JOB-NAME.log’,
          where JOB-NAME is the name defined in the ‘name’ field.  For
          Guix Home services it defaults to
          ‘$XDG_STATE_HOME/shepherd/restic-backup/JOB-NAME.log’.

     ‘max-duration’ (type: maybe-number)
          The maximum duration in seconds that a job may last.  Past
          ‘max-duration’ seconds, the job is forcefully terminated.

     ‘wait-for-termination?’ (default: ‘#f’) (type: boolean)
          Wait until the job has finished before considering executing
          it again; otherwise, perform it strictly on every occurrence
          of event, at the risk of having multiple instances running
          concurrently.

     ‘repository’ (type: string)
          The restic repository target of this job.

     ‘name’ (type: string)
          A string denoting a name for this job.

     ‘password-file’ (type: string)
          Name of the password file, readable by the configured ‘user’,
          that will be used to set the ‘RESTIC_PASSWORD’ environment
          variable for the current job.

     ‘schedule’ (type: gexp-or-string)
          A string or a gexp representing the frequency of the backup.
          Gexp must evaluate to ‘calendar-event’ records or to strings.
          Strings must contain Vixie cron date lines.

     ‘requirement’ (type: maybe-list-of-symbols)
          The list of Shepherd services that this backup job depends
          upon.  When unset it defaults to ‘'()’, for Guix Home.
          Otherwise to ‘'(user-processes file-systems)’.

     ‘files’ (default: ‘'()’) (type: list-of-lowerables)
          The list of files or directories to be backed up.  It must be
          a list of values that can be lowered to strings.

     ‘verbose?’ (default: ‘#f’) (type: boolean)
          Whether to enable verbose output for the current backup job.

     ‘extra-flags’ (default: ‘'()’) (type: list-of-lowerables)
          A list of values that are lowered to strings.  These will be
          passed as command-line arguments to the current job ‘restic
          backup’ invocation.

DLNA/UPnP Services
..................

The ‘(gnu services upnp)’ module offers services related to UPnP
(Universal Plug and Play) and DLNA (Digital Living Network Alliance),
networking protocols that can be used for media streaming and device
interoperability within a local network.  For now, this module provides
the ‘readymedia-service-type’.

   ReadyMedia (https://minidlna.sourceforge.net/) (formerly known as
MiniDLNA) is a DLNA/UPnP-AV media server.  The project’s daemon,
‘minidlnad’, can serve media files (audio, pictures, and video) to
DLNA/UPnP-AV clients available on the network.
‘readymedia-service-type’ is a Guix service that wraps around
ReadyMedia’s ‘minidlnad’.

   Consider the following configuration:
     (use-service-modules upnp ...)

     (operating-system
       ...
       (services
        (list (service readymedia-service-type
                       (readymedia-configuration
                        (media-directories
                         (list (readymedia-media-directory
                                (path "/media/audio")
                                (types '(A)))
                               (readymedia-media-directory
                                (path "/media/video")
                                (types '(V)))
                               (readymedia-media-directory
                                (path "/media/misc"))))
                        (extra-config '(("notify_interval" . "60")))))
              ...)))

   This sets up the ReadyMedia daemon to serve files from the media
folders specified in ‘media-directories’.  The ‘media-directories’ field
is mandatory.  All other fields (such as network ports and the server
name) come with a predefined default and can be omitted.

     Note: This service is also available for Guix Home, where it runs
     directly with your user privileges (*note
     ‘home-readymedia-service-type’: Miscellaneous Home Services.).

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

     ‘readymedia’ (default: ‘readymedia’) (type: package)
          The ReadyMedia package to be used for the service.

     ‘friendly-name’ (default: ‘#f’) (type: maybe-string)
          A custom name that will be displayed on connected clients.

     ‘media-directories’ (type: list)
          The list of media folders to serve content from.  Each item is
          a ‘readymedia-media-directory’.

     ‘cache-directory’ (default: ‘"/var/cache/readymedia"’) (type: string)
          A folder for ReadyMedia’s cache files.  If not existing
          already, the folder will be created as part of the service
          activation and the ReadyMedia user will be assigned ownership.

     ‘log-directory’ (default: ‘"/var/log/readymedia"’) (type: string)
          A folder for ReadyMedia’s log files.  If not existing already,
          the folder will be created as part of the service activation
          and the ReadyMedia user will be assigned ownership.

     ‘port’ (default: ‘#f’) (type: maybe-integer)
          A custom port that the service will be listening on.

     ‘extra-config’ (default: ‘'()’) (type: alist)
          An association list of further options, as accepted by
          ReadyMedia.

 -- Data Type: readymedia-media-directory
     A ‘media-directories’ entry includes a folder ‘path’ and,
     optionally, the ‘types’ of media files included within the folder.

     ‘path’ (type: string)
          The media folder location.

     ‘types’ (default: ‘'()’) (type: list)
          A list indicating the types of file included in the media
          folder.  Valid values are combinations of individual media
          types, i.e.  symbol ‘A’ for audio, ‘P’ for pictures, ‘V’ for
          video.  An empty list means that no type is specified.

