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: Messaging Services,  Next: Telephony Services,  Prev: Mail Services,  Up: Services

11.10.14 Messaging Services
---------------------------

The ‘(gnu services messaging)’ module provides Guix service definitions
for messaging services.  Currently it provides the following services:

Prosody Service
...............

 -- Variable: prosody-service-type
     This is the type for the Prosody XMPP communication server
     (https://prosody.im).  Its value must be a ‘prosody-configuration’
     record as in this example:

          (service prosody-service-type
                   (prosody-configuration
                    (modules-enabled (cons* "groups" "mam" %default-modules-enabled))
                    (int-components
                     (list
                      (int-component-configuration
                       (hostname "conference.example.net")
                       (plugin "muc")
                       (mod-muc (mod-muc-configuration)))))
                    (virtualhosts
                     (list
                      (virtualhost-configuration
                       (domain "example.net"))))))

     See below for details about ‘prosody-configuration’.

   By default, Prosody does not need much configuration.  Only one
‘virtualhosts’ field is needed: it specifies the domain you wish Prosody
to serve.

   You can perform various sanity checks on the generated configuration
with the ‘prosodyctl check’ command.

   Prosodyctl will also help you to import certificates from the
‘letsencrypt’ directory so that the ‘prosody’ user can access them.  See
<https://prosody.im/doc/letsencrypt>.

     prosodyctl --root cert import /etc/certs

   The available configuration parameters follow.  Each parameter
definition is preceded by its type; for example, ‘string-list foo’
indicates that the ‘foo’ parameter should be specified as a list of
strings.  Types starting with ‘maybe-’ denote parameters that won’t show
up in ‘prosody.cfg.lua’ when their value is left unspecified.

   There is also a way to specify the configuration as a string, if you
have an old ‘prosody.cfg.lua’ file that you want to port over from some
other system; see the end for more details.

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

   Available ‘prosody-configuration’ fields are:

 -- prosody-configuration parameter: package prosody
     The Prosody package.

 -- prosody-configuration parameter: file-name data-path
     Location of the Prosody data storage directory.  See
     <https://prosody.im/doc/configure>.  Defaults to
     ‘"/var/lib/prosody"’.

 -- prosody-configuration parameter: file-object-list plugin-paths
     Additional plugin directories.  They are searched in all the
     specified paths in order.  See
     <https://prosody.im/doc/plugins_directory>.  Defaults to ‘'()’.

 -- prosody-configuration parameter: file-name certificates
     Every virtual host and component needs a certificate so that
     clients and servers can securely verify its identity.  Prosody will
     automatically load certificates/keys from the directory specified
     here.  Defaults to ‘"/etc/prosody/certs"’.

 -- prosody-configuration parameter: string-list admins
     This is a list of accounts that are admins for the server.  Note
     that you must create the accounts separately.  See
     <https://prosody.im/doc/admins> and
     <https://prosody.im/doc/creating_accounts>.  Example: ‘(admins
     '("user1@example.com" "user2@example.net"))’ Defaults to ‘'()’.

 -- prosody-configuration parameter: boolean use-libevent?
     Enable use of libevent for better performance under high load.  See
     <https://prosody.im/doc/libevent>.  Defaults to ‘#f’.

 -- prosody-configuration parameter: module-list modules-enabled
     This is the list of modules Prosody will load on startup.  It looks
     for ‘mod_modulename.lua’ in the plugins folder, so make sure that
     exists too.  Documentation on modules can be found at:
     <https://prosody.im/doc/modules>.  Defaults to ‘'("roster"
     "saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist"
     "vcard" "version" "uptime" "time" "ping" "pep" "register"
     "admin_adhoc")’.

 -- prosody-configuration parameter: string-list modules-disabled
     ‘"offline"’, ‘"c2s"’ and ‘"s2s"’ are auto-loaded, but should you
     want to disable them then add them to this list.  Defaults to
     ‘'()’.

 -- prosody-configuration parameter: file-object groups-file
     Path to a text file where the shared groups are defined.  If this
     path is empty then ‘mod_groups’ does nothing.  See
     <https://prosody.im/doc/modules/mod_groups>.  Defaults to
     ‘"/var/lib/prosody/sharedgroups.txt"’.

 -- prosody-configuration parameter: boolean allow-registration?
     Disable account creation by default, for security.  See
     <https://prosody.im/doc/creating_accounts>.  Defaults to ‘#f’.

 -- prosody-configuration parameter: maybe-ssl-configuration ssl
     These are the SSL/TLS-related settings.  Most of them are disabled
     so to use Prosody’s defaults.  If you do not completely understand
     these options, do not add them to your config, it is easy to lower
     the security of your server using them.  See
     <https://prosody.im/doc/advanced_ssl_config>.

     Available ‘ssl-configuration’ fields are:

      -- ssl-configuration parameter: maybe-string protocol
          This determines what handshake to use.

      -- ssl-configuration parameter: maybe-file-name key
          Path to your private key file.

      -- ssl-configuration parameter: maybe-file-name certificate
          Path to your certificate file.

      -- ssl-configuration parameter: file-object capath
          Path to directory containing root certificates that you wish
          Prosody to trust when verifying the certificates of remote
          servers.  Defaults to ‘"/etc/ssl/certs"’.

      -- ssl-configuration parameter: maybe-file-object cafile
          Path to a file containing root certificates that you wish
          Prosody to trust.  Similar to ‘capath’ but with all
          certificates concatenated together.

      -- ssl-configuration parameter: maybe-string-list verify
          A list of verification options (these mostly map to OpenSSL’s
          ‘set_verify()’ flags).

      -- ssl-configuration parameter: maybe-string-list options
          A list of general options relating to SSL/TLS.  These map to
          OpenSSL’s ‘set_options()’.  For a full list of options
          available in LuaSec, see the LuaSec source.

      -- ssl-configuration parameter: maybe-non-negative-integer depth
          How long a chain of certificate authorities to check when
          looking for a trusted root certificate.

      -- ssl-configuration parameter: maybe-string ciphers
          An OpenSSL cipher string.  This selects what ciphers Prosody
          will offer to clients, and in what order.

      -- ssl-configuration parameter: maybe-file-name dhparam
          A path to a file containing parameters for Diffie-Hellman key
          exchange.  You can create such a file with: ‘openssl dhparam
          -out /etc/prosody/certs/dh-2048.pem 2048’

      -- ssl-configuration parameter: maybe-string curve
          Curve for Elliptic curve Diffie-Hellman.  Prosody’s default is
          ‘"secp384r1"’.

      -- ssl-configuration parameter: maybe-string-list verifyext
          A list of “extra” verification options.

      -- ssl-configuration parameter: maybe-string password
          Password for encrypted private keys.

 -- prosody-configuration parameter: boolean c2s-require-encryption?
     Whether to force all client-to-server connections to be encrypted
     or not.  See <https://prosody.im/doc/modules/mod_tls>.  Defaults to
     ‘#f’.

 -- prosody-configuration parameter: string-list disable-sasl-mechanisms
     Set of mechanisms that will never be offered.  See
     <https://prosody.im/doc/modules/mod_saslauth>.  Defaults to
     ‘'("DIGEST-MD5")’.

 -- prosody-configuration parameter: string-list
          insecure-sasl-mechanisms
     Set of mechanisms that will not be offered on unencrypted
     connections.  See <https://prosody.im/doc/modules/mod_saslauth>.
     Defaults to ‘'("PLAIN" "LOGIN")’.

 -- prosody-configuration parameter: boolean s2s-require-encryption?
     Whether to force all server-to-server connections to be encrypted
     or not.  See <https://prosody.im/doc/modules/mod_tls>.  Defaults to
     ‘#f’.

 -- prosody-configuration parameter: boolean s2s-secure-auth?
     Whether to require encryption and certificate authentication.  This
     provides ideal security, but requires servers you communicate with
     to support encryption AND present valid, trusted certificates.  See
     <https://prosody.im/doc/s2s#security>.  Defaults to ‘#f’.

 -- prosody-configuration parameter: string-list s2s-insecure-domains
     Many servers don’t support encryption or have invalid or
     self-signed certificates.  You can list domains here that will not
     be required to authenticate using certificates.  They will be
     authenticated using DNS.  See
     <https://prosody.im/doc/s2s#security>.  Defaults to ‘'()’.

 -- prosody-configuration parameter: string-list s2s-secure-domains
     Even if you leave ‘s2s-secure-auth?’ disabled, you can still
     require valid certificates for some domains by specifying a list
     here.  See <https://prosody.im/doc/s2s#security>.  Defaults to
     ‘'()’.

 -- prosody-configuration parameter: string authentication
     Select the authentication backend to use.  The default provider
     stores passwords in plaintext and uses Prosody’s configured data
     storage to store the authentication data.  If you do not trust your
     server please see
     <https://prosody.im/doc/modules/mod_auth_internal_hashed> for
     information about using the hashed backend.  See also
     <https://prosody.im/doc/authentication> Defaults to
     ‘"internal_plain"’.

 -- prosody-configuration parameter: maybe-string log
     Set logging options.  Advanced logging configuration is not yet
     supported by the Prosody service.  See
     <https://prosody.im/doc/logging>.  Defaults to ‘"*syslog"’.

 -- prosody-configuration parameter: file-name pidfile
     File to write pid in.  See
     <https://prosody.im/doc/modules/mod_posix>.  Defaults to
     ‘"/var/run/prosody/prosody.pid"’.

 -- prosody-configuration parameter: maybe-non-negative-integer
          http-max-content-size
     Maximum allowed size of the HTTP body (in bytes).

 -- prosody-configuration parameter: maybe-string http-external-url
     Some modules expose their own URL in various ways.  This URL is
     built from the protocol, host and port used.  If Prosody sits
     behind a proxy, the public URL will be ‘http-external-url’ instead.
     See <https://prosody.im/doc/http#external_url>.

 -- prosody-configuration parameter: virtualhost-configuration-list
          virtualhosts
     A host in Prosody is a domain on which user accounts can be
     created.  For example if you want your users to have addresses like
     ‘"john.smith@example.com"’ then you need to add a host
     ‘"example.com"’.  All options in this list will apply only to this
     host.

          Note: The name _virtual_ host is used in configuration to
          avoid confusion with the actual physical host that Prosody is
          installed on.  A single Prosody instance can serve many
          domains, each one defined as a VirtualHost entry in Prosody’s
          configuration.  Conversely a server that hosts a single domain
          would have just one VirtualHost entry.

          See <https://prosody.im/doc/configure#virtual_host_settings>.

     Available ‘virtualhost-configuration’ fields are:

     all these ‘prosody-configuration’ fields: ‘admins’,
     ‘use-libevent?’, ‘modules-enabled’, ‘modules-disabled’,
     ‘groups-file’, ‘allow-registration?’, ‘ssl’,
     ‘c2s-require-encryption?’, ‘disable-sasl-mechanisms’,
     ‘insecure-sasl-mechanisms’, ‘s2s-require-encryption?’,
     ‘s2s-secure-auth?’, ‘s2s-insecure-domains’, ‘s2s-secure-domains’,
     ‘authentication’, ‘log’, ‘http-max-content-size’,
     ‘http-external-url’, ‘raw-content’, plus:
      -- virtualhost-configuration parameter: string domain
          Domain you wish Prosody to serve.

 -- prosody-configuration parameter: int-component-configuration-list
          int-components
     Components are extra services on a server which are available to
     clients, usually on a subdomain of the main server (such as
     ‘"mycomponent.example.com"’).  Example components might be chatroom
     servers, user directories, or gateways to other protocols.

     Internal components are implemented with Prosody-specific plugins.
     To add an internal component, you simply fill the hostname field,
     and the plugin you wish to use for the component.

     See <https://prosody.im/doc/components>.  Defaults to ‘'()’.

     Available ‘int-component-configuration’ fields are:

     all these ‘prosody-configuration’ fields: ‘admins’,
     ‘use-libevent?’, ‘modules-enabled’, ‘modules-disabled’,
     ‘groups-file’, ‘allow-registration?’, ‘ssl’,
     ‘c2s-require-encryption?’, ‘disable-sasl-mechanisms’,
     ‘insecure-sasl-mechanisms’, ‘s2s-require-encryption?’,
     ‘s2s-secure-auth?’, ‘s2s-insecure-domains’, ‘s2s-secure-domains’,
     ‘authentication’, ‘log’, ‘http-max-content-size’,
     ‘http-external-url’, ‘raw-content’, plus:
      -- int-component-configuration parameter: string hostname
          Hostname of the component.

      -- int-component-configuration parameter: string plugin
          Plugin you wish to use for the component.

      -- int-component-configuration parameter:
               maybe-mod-muc-configuration mod-muc
          Multi-user chat (MUC) is Prosody’s module for allowing you to
          create hosted chatrooms/conferences for XMPP users.

          General information on setting up and using multi-user
          chatrooms can be found in the “Chatrooms” documentation
          (<https://prosody.im/doc/chatrooms>), which you should read if
          you are new to XMPP chatrooms.

          See also <https://prosody.im/doc/modules/mod_muc>.

          Available ‘mod-muc-configuration’ fields are:

           -- mod-muc-configuration parameter: string name
               The name to return in service discovery responses.
               Defaults to ‘"Prosody Chatrooms"’.

           -- mod-muc-configuration parameter: string-or-boolean
                    restrict-room-creation
               If ‘#t’, this will only allow admins to create new
               chatrooms.  Otherwise anyone can create a room.  The
               value ‘"local"’ restricts room creation to users on the
               service’s parent domain.  E.g. ‘user@example.com’ can
               create rooms on ‘rooms.example.com’.  The value ‘"admin"’
               restricts to service administrators only.  Defaults to
               ‘#f’.

           -- mod-muc-configuration parameter: non-negative-integer
                    max-history-messages
               Maximum number of history messages that will be sent to
               the member that has just joined the room.  Defaults to
               ‘20’.

 -- prosody-configuration parameter: ext-component-configuration-list
          ext-components
     External components use XEP-0114, which most standalone components
     support.  To add an external component, you simply fill the
     hostname field.  See <https://prosody.im/doc/components>.  Defaults
     to ‘'()’.

     Available ‘ext-component-configuration’ fields are:

     all these ‘prosody-configuration’ fields: ‘admins’,
     ‘use-libevent?’, ‘modules-enabled’, ‘modules-disabled’,
     ‘groups-file’, ‘allow-registration?’, ‘ssl’,
     ‘c2s-require-encryption?’, ‘disable-sasl-mechanisms’,
     ‘insecure-sasl-mechanisms’, ‘s2s-require-encryption?’,
     ‘s2s-secure-auth?’, ‘s2s-insecure-domains’, ‘s2s-secure-domains’,
     ‘authentication’, ‘log’, ‘http-max-content-size’,
     ‘http-external-url’, ‘raw-content’, plus:
      -- ext-component-configuration parameter: string component-secret
          Password which the component will use to log in.

      -- ext-component-configuration parameter: string hostname
          Hostname of the component.

 -- prosody-configuration parameter: non-negative-integer-list
          component-ports
     Port(s) Prosody listens on for component connections.  Defaults to
     ‘'(5347)’.

 -- prosody-configuration parameter: string component-interface
     Interface Prosody listens on for component connections.  Defaults
     to ‘"127.0.0.1"’.

 -- prosody-configuration parameter: maybe-raw-content raw-content
     Raw content that will be added to the configuration file.

   It could be that you just want to get a ‘prosody.cfg.lua’ up and
running.  In that case, you can pass an ‘opaque-prosody-configuration’
record as the value of ‘prosody-service-type’.  As its name indicates,
an opaque configuration does not have easy reflective capabilities.
Available ‘opaque-prosody-configuration’ fields are:

 -- opaque-prosody-configuration parameter: package prosody
     The prosody package.

 -- opaque-prosody-configuration parameter: string prosody.cfg.lua
     The contents of the ‘prosody.cfg.lua’ to use.

   For example, if your ‘prosody.cfg.lua’ is just the empty string, you
could instantiate a prosody service like this:

     (service prosody-service-type
              (opaque-prosody-configuration
               (prosody.cfg.lua "")))

BitlBee Service
...............

BitlBee (https://bitlbee.org) is a gateway that provides an IRC
interface to a variety of messaging protocols such as XMPP.

 -- Variable: bitlbee-service-type
     This is the service type for the BitlBee (https://bitlbee.org) IRC
     gateway daemon.  Its value is a ‘bitlbee-configuration’ (see
     below).

     To have BitlBee listen on port 6667 on localhost, add this line to
     your services:

          (service bitlbee-service-type)

 -- Data Type: bitlbee-configuration
     This is the configuration for BitlBee, with the following fields:

     ‘interface’ (default: ‘"127.0.0.1"’)
     ‘port’ (default: ‘6667’)
          Listen on the network interface corresponding to the IP
          address specified in INTERFACE, on PORT.

          When INTERFACE is ‘127.0.0.1’, only local clients can connect;
          when it is ‘0.0.0.0’, connections can come from any networking
          interface.

     ‘bitlbee’ (default: ‘bitlbee’)
          The BitlBee package to use.

     ‘plugins’ (default: ‘'()’)
          List of plugin packages to use—e.g., ‘bitlbee-discord’.

     ‘extra-settings’ (default: ‘""’)
          Configuration snippet added as-is to the BitlBee configuration
          file.

ngIRCd service
..............

ngIRCd (https://ngircd.barton.de/), is a lightweight IRCd (Internet
Relay Chat daemon), which can be used to host your own IRC server.

 -- Variable: ngircd-service-type
     The service type for ngIRCd.  Its value is a ‘ngircd-configuration’
     object, documented below.

     In its most simple form, the service can be used with its default
     configuration, like this:

          (service ngircd-service-type)

     A slightly more complex example configuration could look like:

          (service ngircd-service-type
                   (ngircd-configuration
                    (channels
                     (list (ngircd-channel
                            (name "#fruits")
                            (topic "All things fruits -- veggies are off-topic"))))
                    (operators
                     (list (ngircd-operator
                            (name "mikan")
                            (password "tomatoes-are-fruits/carrots-are-not"))))))

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

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

     ‘debug?’ (default: ‘#f’) (type: boolean)
          Turn on debugging messages.

     ‘shepherd-requirement’ (default: ‘(user-processes networking)’) (type: list-of-symbols)
          Shepherd requirements the service should depend on.

     ‘global’ (type: ngircd-global)
          A ngircd-global record object used to specify global options.

     ‘limits’ (type: maybe-ngircd-limits)
          The ngircd-limits record object used to specify limits
          options.

     ‘options’ (type: ngircd-options)
          The ngircd-options record object used to specify optional
          features and configuration options.

     ‘ssl’ (type: maybe-ngircd-ssl)
          The ngircd-ssl record object used to specify the SSL-related
          options.

     ‘operators’ (type: maybe-list-of-ngircd-operators)
          A list of ngircd-operator record objects used to specify the
          operators.

     ‘servers’ (type: maybe-list-of-ngircd-servers)
          A list of ngircd-server record objects used to specify other
          remote servers to connect to.

     ‘channels’ (type: maybe-list-of-ngircd-channels)
          A list of ngircd-channels record objects specifying
          pre-defined channels to be created by the server when starting
          up.

 -- Data Type: ngircd-global
     Available ‘ngircd-global’ fields are:

     ‘name’ (type: maybe-string)
          Server name in the IRC network.  This is an individual name of
          the IRC server, it is not related to the DNS host name.  It
          must be unique in the IRC network and must contain at least
          one dot (‘.’) character.  When not set, ngIRCd tries to deduce
          a valid IRC server name from the local host name.

     ‘admin-info-1’ (type: maybe-string)
          First administrator information.

     ‘admin-info-2’ (type: maybe-string)
          Second administrator information.

     ‘admin-email’ (type: maybe-string)
          Email to reach administrators.

     ‘help-file’ (type: maybe-file-like)
          File-like containing the ngIRCd help text.

     ‘info’ (type: maybe-string)
          Info text of the server.  This will be shown by WHOIS and
          LINKS requests for example.

     ‘listen’ (default: ‘("::" "0.0.0.0")’) (type: list-of-strings)
          A list of IP address on which the server should listen.  By
          default it listens on all configured IP addresses and
          interfaces.

     ‘motd-file’ (type: file-like)
          Text file with the message of the day (MOTD). This message
          will be shown to all users connecting to the server.

     ‘motd-phrase’ (type: maybe-string)
          A simple phrase (<127 chars) to use if you don’t want to use a
          MOTD file.

     ‘network’ (type: maybe-string)
          The name of the IRC network to which this server belongs.
          This name is optional, should only contain ASCII characters,
          and can’t contain spaces.  It is only used to inform clients.

     ‘password’ (type: maybe-string)
          Global password or all users needed to connect to the server.
          By default, no password is required.  PAM must be disabled for
          this option to have an effect.

     ‘pid-file’ (default: ‘"/run/ngircd/ngircd.pid"’) (type: string)
          The file name where the PID of ngIRCd should be written after
          it starts.

     ‘ports’ (default: ‘(6667)’) (type: list-of-ports)
          Port number(s) on which the server should listen for
          _unencrypted_ connections.

     ‘server-uid’ (default: ‘"ngircd"’) (type: string-or-number)
          The user that the ‘ngircd’ command should run as.

     ‘server-gid’ (default: ‘"ngircd"’) (type: string-or-number)
          The group that the ‘ngircd’ command should run as.

 -- Data Type: ngircd-limits
     Available ‘ngircd-limits’ fields are:

     ‘connect-retry’ (default: ‘60’) (type: maybe-number)
          The number of seconds the server should wait before
          re-attempting to establish a link to not yet (or no longer)
          connected servers.

     ‘max-connections’ (default: ‘0’) (type: maybe-number)
          Maximum number of simultaneous in- and outbound connections
          the server is allowed to accept.  There is no limit by
          default.

     ‘max-connections-ip’ (default: ‘5’) (type: maybe-number)
          Maximum number of simultaneous connections from a single IP
          address that the server will accept.  This configuration
          options lowers the risk of denial of service attacks (DoS).
          Set to 0 to remove the limit.

     ‘max-joins’ (default: ‘10’) (type: maybe-number)
          Maximum number of channels a user can be member of.  Set to 0
          to remove the limit.

     ‘max-list-size’ (default: ‘100’) (type: maybe-number)
          Maximum number of channels returned in response to a LIST
          command.

     ‘ping-timeout’ (default: ‘120’) (type: maybe-number)
          Number of seconds of inactivity after which the server will
          send a PING to the peer to test whether it is alive or not.

     ‘pong-timeout’ (default: ‘20’) (type: maybe-number)
          If a client fails to answer a PING with a PONG within this
          amount of seconds, it will be disconnected by the server.

 -- Data Type: ngircd-options
     Available ‘ngircd-options’ fields are:

     ‘allowed-channel-types’ (default: ‘"#&+"’) (type: maybe-string)
          List of allowed channel types (channel prefixes) for newly
          created channels on the local server.  By default, all
          supported channel types are allowed.

     ‘allow-remote-oper?’ (default: ‘#f’) (type: maybe-boolean)
          If this option is active, IRC operators connected to remote
          servers are allowed to control this local server using
          administrative commands, for example like CONNECT, DIE, SQUIT,
          etc.

     ‘connect-ipv4?’ (default: ‘#t’) (type: maybe-boolean)
          Set to ‘#f’ to prevent ngIRCd from connecting to other IRC
          servers using the IPv4 protocol, allowed by default.

     ‘connect-ipv6?’ (default: ‘#t’) (type: maybe-boolean)
          Set to ‘#f’ to prevent ngIRCd from connecting to other IRC
          servers using the IPv6 protocol, allowed by default.

     ‘dns?’ (default: ‘#t’) (type: maybe-boolean)
          Set to ‘#f’ to disable DNS lookups when clients connect.  If
          you configure the daemon to connect to other servers, ngIRCd
          may still perform a DNS lookup if required.

     ‘more-privacy?’ (default: ‘#f’) (type: maybe-boolean)
          Set this to ‘#t’ to have ngIRCd censor user idle time, logon
          time as well as the PART/QUIT messages (that sometimes used to
          inform everyone about which client software is being used).
          WHOWAS requests are also silently ignored, and NAMES output
          doesn’t list any clients for non-members.  This option is most
          useful when ngIRCd is being used together with anonymizing
          software such as TOR or I2P and one does not wish to make it
          too easy to collect statistics on the users.

     ‘notice-before-registration?’ (default: ‘#f’) (type: maybe-boolean)
          Normally ngIRCd doesn’t send any messages to a client until it
          is registered.  Enable this option to let the daemon send
          ‘NOTICE *’ messages to clients while connecting.

     ‘oper-can-use-mode?’ (default: ‘#f’) (type: maybe-boolean)
          Should IRC Operators be allowed to use the MODE command even
          if they are not(!)  channel-operators?

     ‘oper-chan-p-auto-op?’ (default: ‘#t’) (type: maybe-boolean)
          Should IRC Operators get AutoOp (+o) in persistent (+P)
          channels?

     ‘oper-server-mode?’ (default: ‘#f’) (type: maybe-boolean)
          If ‘open-can-use-mode?’ is ‘#t’, this may lead the
          compatibility problems with servers that run the ircd-irc2
          software.  This option masks mode requests by non-chanops as
          if they were coming from the server.  Only enable this if you
          have ircd-irc2 servers in your IRC network.

     ‘pam?’ (default: ‘#f’) (type: boolean)
          Set to ‘#t’ to enable calls to the PAM library at runtime; all
          users connecting without password are allowed to connect, all
          passwords given will fail.  Users identified without PAM are
          registered with a tilde (‘~’) prepended to their user name.
          This defaults to ‘#f’ in Guix because the service runs as an
          unprivileged user and thus cannot authenticate other users via
          the ‘pam_unix’ PAM module.

     ‘pam-is-optional?’ (default: ‘#f’) (type: maybe-boolean)
          Set to ‘#t’ to make PAM authentication optional, causing
          clients not sending a password to still be able to connect,
          but won’t become identified and keep the tilder (‘~’)
          character prepended to their supplied user name.

     ‘require-auth-ping?’ (default: ‘#f’) (type: maybe-boolean)
          Set to ‘#t’ to have ngIRCd send an authentication PING when a
          new client connects, and register this client only after
          receiving the corresponding PONG reply.

 -- Data Type: ngircd-ssl
     Available ‘ngircd-ssl’ fields are:

     ‘cert-file’ (type: maybe-string)
          SSL certificate file of the private server key.

     ‘key-file’ (type: maybe-string)
          File name of the SSL Server Key to be used for SSL
          connections, which is required for SSL/TLS support.

     ‘ca-file’ (default: ‘"/etc/ssl/certs/ca-certificates.crt"’) (type: maybe-string)
          A file listing all the certificates of the trusted Certificate
          Authorities.

     ‘ports’ (type: maybe-list-of-ports)
          Like the global configuration’s ‘port’ option, except that
          ngIRCd will expect incoming connections to be SSL/TLS
          encrypted.  Common port numbers for SSL-encrypted IRC are 6669
          and 6697.

     ‘cipher-list’ (type: maybe-string)
          The GnuTLS cipher suites allowed for SSL/TLS connections, a
          value such as ‘"SECURE128:-VERS-SSL3.0"’.  Refer to ‘man 3
          gnutls_priority_init’ for details.

     ‘dh-file’ (type: maybe-file-like)
          A file-like containing the Diffie-Hellman parameters, which
          can be created with GnuTLS via ‘certtool
          --generate-dh-params’.  If this file is not present, the
          Diffie-Hellman parameters will be computed on startup, which
          may take some time.

 -- Data Type: ngircd-operator
     Available ‘ngircd-operator’ fields are:

     ‘name’ (type: string)
          ID of the operator (may be different of the nickname).

     ‘password’ (type: string)
          Password of the IRC operator.

     ‘mask’ (type: maybe-string)
          Mask that is to be checked before an /OPER for this account is
          accepted, for example: ‘"nick!ident@*.example.com"’.

 -- Data Type: ngircd-server
     Available ‘ngircd-server’ fields are:

     ‘name’ (type: string)
          IRC name of the remote server.

     ‘host’ (type: string)
          Internet host name (or IP address) of the peer.

     ‘my-password’ (type: string)
          Own password for this connection.  This password has to be
          configured as ‘peer-password’ on the other server and must not
          have ‘:’ as first character.

     ‘peer-password’ (type: string)
          Foreign password for this connection.  This password has to be
          configured as ‘my-password’ on the other server.

     ‘bind’ (type: maybe-string)
          IP address to use as source IP for the outgoing connection.
          The default is to let the operating system decide.

     ‘port’ (type: maybe-port)
          Port of the remote server to which ngIRCd should connect
          (active).  If no port is assigned to a configured server, the
          daemon only waits for incoming connections (passive, which is
          the default).

     ‘group’ (type: maybe-number)
          Group of this server.

     ‘passive?’ (default: ‘#f’) (type: maybe-boolean)
          Set to ‘#t’ to disable automatic connection even if the port
          value is specified.

     ‘ssl-connect?’ (default: ‘#f’) (type: maybe-boolean)
          Set to ‘#t’ to enforce the use of TLS to connect to the remote
          server.

     ‘ssl-verify?’ (default: ‘#t’) (type: maybe-boolean)
          Set to ‘#f’ to disable the verification of the TLS certificate
          presented by the remote server.  This can be useful if the
          remote server uses a self-signed certificate.  Beware that
          this degrades security by enabling man-in-the-middle attacks,
          as the _remote site is not verified at all_.

 -- Data Type: ngircd-channel
     Available ‘ngircd-channel’ fields are:

     ‘name’ (type: string)
          Name of the channel, including channel prefix ("#" or "&").

     ‘topic’ (type: maybe-string)
          Topic for this channel.

     ‘modes’ (type: maybe-list-of-strings)
          Initial channel modes, as used in MODE commands.  Modifying
          lists (ban list, invite list, exception list) is supported.
          If multiple MODE strings are specified, they are evaluated in
          the order listed (left to right).

     ‘key-file’ (type: maybe-file-like)
          Path and file name of a ngIRCd key file containing individual
          channel keys for different users.  Refer to ‘man 5
          ngircd.conf’ for more details.

Pounce Service
..............

pounce (https://git.causal.agency/pounce/about/) is a multi-client,
TLS-only IRC bouncer.  It maintains a persistent connection to an IRC
server, acting as a proxy and buffer for a number of clients.

 -- Variable: pounce-service-type
     This is the service type for the pounce IRC bouncer.  Its value is
     a ‘pounce-configuration’ configuration instance, which is
     documented below.

     The following example configures pounce to act as an IRC bouncer
     for the Libera.Chat (https://libera.chat) server, using CertFP
     (client certificate fingerprint) authentication to avoid leaking a
     sensitive password to the publicly readable store.  The equally
     sensitive TLS certificate file should be created in-place or
     transferred using a secure means such as SSH, prior to deploying
     the service.  The service activation will ensure the ownership and
     permissions of the certificate/key files are set correctly.  In the
     below example, it is placed at ‘/etc/pounce/libera.pem’ on the
     target machine.  Pounce itself can be used to generate a TLS
     certificate, using the ‘pounce -g libera.pem’ command, which
     concatenates both the private key and the public certificate in the
     specified file name.  For more information regarding CertFP
     authentication, refer to ‘man pounce’ or the Libera.Chat guide at
     <https://libera.chat/guides/certfp>.

          (service pounce-service-type
                   (pounce-configuration
                    (host "irc.libera.chat")
                    (client-cert "/etc/pounce/libera.pem")
                    (nick "hannah")
                    (join (list "#gnu" "#guix" "#guile" "#hurd"))))

     Once deployed on the target machine, pounce will act as an IRC
     server listening for TLS connections on the 6697 TCP port of the
     ‘localhost’ address of that machine.  By default, a self-signed
     certificate for pounce is created at
     ‘/var/lib/pounce/.config/pounce/localhost.cert’.  If you plan to
     expose the bouncer to the public Internet, it is advisable to use a
     CA (Certificate Authority)-signed certificate, as can be obtained
     using a certificate service (*note Certificate Services::), so that
     IRC clients can verify the certificate out of the box.  If you
     instead plan to connect to the bouncer strictly via a secure
     connection, for example using a VPN (Virtual Private Network) or
     SSH (Secure Shell), then it is acceptable to simply let your IRC
     client trust the auto-generated, self-signed pounce certificate or
     even disable TLS certificate verification in your client.

     To connect to a second server, a second pounce instance is needed,
     taking care to specify the ‘provision’ field of its
     ‘pounce-configuration’ to avoid a name clash with the previous
     service, along with a distinct ‘local-port’ and ‘log-file’.  The
     following example shows how to configure another bouncer, this time
     for the OFTC (https://www.oftc.net) IRC server.  Like in the
     previous example, CertFP authentication is used, which can be
     configured similarly.  For more details about using CertFP with the
     OFTC IRC server, refer to <https://www.oftc.net/NickServ/CertFP/>.

          (service pounce-service-type
                   (pounce-configuration
                    (shepherd-provision '(pounce-oftc))
                    (local-port 6698)
                    (log-file "/var/log/pounce-oftc.log")
                    (host "irc.oftc.net")
                    (client-cert "/etc/pounce/oftc.pem")
                    (nick "sena")
                    (join (list "#gcc" "#glibc"))))

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

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

     ‘shepherd-provision’ (default: ‘(pounce)’) (type: list-of-symbols)
          The name(s) of the service.

     ‘shepherd-requirement’ (default: ‘(user-processes networking)’) (type: list-of-symbols)
          Shepherd requirements the service should depend on.

     ‘log-file’ (default: ‘"/var/log/pounce.log"’) (type: string)
          The log file name to use.

     ‘verbose?’ (type: maybe-boolean)
          When true, log IRC messages to standard output.

     ‘local-host’ (default: ‘"localhost"’) (type: maybe-string)
          The host to bind to.

     ‘local-port’ (default: ‘6697’) (type: maybe-port)
          The port to bind to.

     ‘local-ca’ (type: maybe-string)
          Require clients to authenticate using a TLS client certificate
          either contained in or signed by a certificate in the file
          loaded from ‘local-ca’, a file name.  The file is reloaded
          when the SIGUSR1 signal is received.

     ‘local-cert’ (type: maybe-string)
          File name of the TLS certificate to load.  The file is
          reloaded when the SIGUSR1 signal is received.  Unless
          specified, a self-signed certificate is generated at
          ‘/var/lib/pounce/.config/pounce/HOST.pem’, where HOST
          corresponds to the value of the ‘local-host’ field.

     ‘local-priv’ (type: maybe-string)
          File name of the private TLS key to load.  Unless specified, a
          key is generated at ‘/var/lib/pounce/.config/pounce/HOST.key’,
          where HOST corresponds to the value of the ‘local-host’ field.

     ‘local-pass’ (type: maybe-string)
          Require the server password pass for clients to connect.  The
          pass string must be hashed using ‘pounce -x’.

     ‘size’ (default: ‘4096’) (type: maybe-power-of-two)
          Set the number of messages contained in the buffer to SIZE.
          This sets the maximum number of recent messages which can be
          relayed to a reconnecting client.  The size must be a power of
          two.

     ‘bind’ (type: maybe-string)
          Host to bind the _source_ address to when connecting to the
          server.  To connect from any address over IPv4 only, use
          ‘0.0.0.0’.  To connect from any address over IPv6 only, use
          ‘::’.

     ‘host’ (type: string)
          The host name to connect to.

     ‘port’ (type: maybe-port)
          The port number to connect to.

     ‘pass’ (type: maybe-string)
          Password to use to log in with the server.  The password must
          have been hashed via the ‘pounce -x’ command.

     ‘join’ (type: maybe-list-of-strings)
          The list of channels to join.

     ‘mode’ (type: maybe-string)
          The user mode.

     ‘user’ (type: maybe-string)
          To set the username.  The default username is the same as the
          nickname.

     ‘nick’ (default: ‘"pounce"’) (type: maybe-string)
          Set nickname to NICK.

     ‘real’ (type: maybe-string)
          Set the real name.  The default is ‘nick’.

     ‘away’ (type: maybe-string)
          The away status to use when no clients are connected and no
          other away status has been set.

     ‘quit’ (type: maybe-string)
          The message to use when quitting.

     ‘no-names?’ (type: maybe-boolean)
          Do not request ‘NAMES’ for each channel when a client
          connects.  This avoids already connected clients receiving
          unsolicited responses but prevents new clients from populating
          user lists.

     ‘queue-interval’ (default: ‘200’) (type: maybe-number)
          Set the server send queue interval in milliseconds.  The queue
          is used to send automated messages from pounce to the server.
          Messages from clients are sent to the server directly.

     ‘trust’ (type: maybe-string)
          File name of a certificate to trust.  When used, server name
          verification is disabled.

     ‘client-cert’ (type: maybe-string)
          The file name of the TLS client.  If the private key is in a
          separate file, it is loaded with ‘client-priv’.  With
          ‘sasl-external?’, authenticate using SASL EXTERNAL.
          Certificates can be generated with ‘pounce -g’.  For more
          details, refer to “Generating Client Certificates” in ‘man 1
          pounce’.

     ‘client-priv’ (type: maybe-string)
          The file name of the TLS client private key.

     ‘sasl-plain’ (type: maybe-pair)
          A pair of the username and password in plain text to
          authenticate using SASL PLAIN. Since this method requires the
          account password in plain text, it is recommended to use
          CertFP instead with ‘sasl-external’.

     ‘sasl-external?’ (type: maybe-boolean)
          Authenticate using SASL EXTERNAL, also known as CertFP. The
          TLS client certificate is loaded from ‘client-cert’.

Quassel Service
...............

Quassel (https://quassel-irc.org/) is a distributed IRC client, meaning
that one or more clients can attach to and detach from the central core.

 -- Variable: quassel-service-type
     This is the service type for the Quassel (https://quassel-irc.org/)
     IRC backend daemon.  Its value is a ‘quassel-configuration’ (see
     below).

 -- Data Type: quassel-configuration
     This is the configuration for Quassel, with the following fields:

     ‘quassel’ (default: ‘quassel’)
          The Quassel package to use.

     ‘interface’ (default: ‘"::,0.0.0.0"’)
     ‘port’ (default: ‘4242’)
          Listen on the network interface(s) corresponding to the IPv4
          or IPv6 interfaces specified in the comma delimited INTERFACE,
          on PORT.

     ‘loglevel’ (default: ‘"Info"’)
          The level of logging desired.  Accepted values are Debug,
          Info, Warning and Error.

Snuik Service
.............

The Snuik IRC bot (https://gitlab.com/janneke/snuik) can be run as a
daemon to aid talking to users that are currently offline.  With the
‘(gnu services messaging)’ service, you can configure it by adding a
‘snuik-service-type’ service to the ‘services’ field of your operating
system declaration.

 -- Variable: snuik-service-type
     This is the type of the Snuik service, whose value is a
     ‘snuik-configuration’ object.

   Here is an example of a service and its configuration:

     (service snuik-service-type
              (snuik-configuration
               (password-file "/var/run/snuik/.password.snuik")
               (channels '("#bootstrappable"
                           "#dezyne"
                           "#guix-risc-v"
                           "#lilypond"))))

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

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

     ‘server’ (default: ‘"irc.libera.chat"’)
          The IRC server to connect to.

     ‘port’ (default: ‘6665’) (type: integer)
          Port number used by the IRC server.

     ‘nick’ (default: ‘"snuik"’) (type: string)
          The nickname for snuik to use.

     ‘password’ (default: ‘#f’) (type: string)
          The password to use when logging in.

     ‘password-file’ (default: ‘".password.<nick>’)
          The file to read the password from to use when logging in.

     ‘channels’ (default: ‘'("##botchat")’)
          The channels for snuik to join, a list of strings.

     ‘extra-options’ (default: ‘'()’)
          Extra options will be passed to ‘snuik’, please run ‘snuik
          --help ’ for more information.

Mosquitto Service
.................

Mosquitto (https://mosquitto.org/) is a lightweight message broker that
implements the MQTT protocol versions 5.0, 3.1.1 and 3.1.  It is
suitable for use on all devices from low power single board computers to
full servers.

 -- Variable: mosquitto-service-type
     This is the service type for the Mosquitto (https://mosquitto.org/)
     MQTT broker.  Its value is a ‘mosquitto-configuration’ (see below).

 -- Data Type: mosquitto-configuration
     This is the configuration for Mosquitto, with the following fields:

     ‘package’ (default: ‘mosquitto’)
          The Mosquitto package to use.

     ‘config-file’ (default: ‘#f’)
          The Mosquitto configuration file as a file-like object or the
          value ‘#f’ to use the default configuration.

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

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

Mollysocket Service
...................

Mollysocket (https://github.com/mollyim/mollysocket) is a UnifiedPush
provider for the messaging app Molly (https://molly.im), a fork of
Signal.

 -- Variable: mollysocket-service-type
     The Mollysocket service.  Takes ‘mollysocket-configuration’ as its
     value.  By default, this service listens on port 8020 for any Molly
     client.

 -- Data Type: mollysocket-configuration
     The configuration for Mollysocket, with the following fields:

     ‘package’ (default: ‘mollysocket’)
          The Mollysocket package to use.

     ‘host’ (default: ‘"0.0.0.0"’)
          Address for the webserver to listen on.  It is recommended
          that this be set to localhost, and instead configure a
          TLS-supporting reverse proxy in front of it.

     ‘port’ (default: ‘8020’)
          Port for the webserver to listen on.

     ‘webserver’ (default: ‘#t’)
          Whether the webserver sould be enabled.  If disabled, the
          server is considered to be in airgapped mode, and clients must
          be configured likewise.

     ‘allowed-endpoints’ (default: ‘'("*")’)
          Allowlist of UnifiedPush distributor endpoints, represented as
          IP addresses or domain names.  Addresses on the local network
          must be specified explicitly.

     ‘allowed-uuids’ (default: ‘'("*")’)
          Allowlist of Signal account UUIDs.

     ‘db’ (default: ‘"/var/lib/mollysocket/db.sqlite"’)
          Path to the Mollysocket database.  Will be created if it
          doesn’t exist.

     ‘vapid-key-file’ (default: ‘"/var/lib/mollysocket/vapid.key"’)
          Path to the VAPID key used to authorize requests to the
          UnifiedPush distributor.  Will be created if it doesn’t exist.


File: guix.info,  Node: Telephony Services,  Next: File-Sharing Services,  Prev: Messaging Services,  Up: Services

11.10.15 Telephony Services
---------------------------

The ‘(gnu services telephony)’ module contains Guix service definitions
for telephony services.  Currently it provides the following services:

Jami
....

 -- Variable: jami-service-type
     The service type for running Jami as a service.  It takes a
     ‘jami-configuration’ object as a value, documented below.  This
     section describes how to configure a Jami server that can be used
     to host video (or audio) conferences, among other uses.  The
     following example demonstrates how to specify Jami account archives
     (backups) to be provisioned automatically:

          (service jami-service-type
                   (jami-configuration
                    (accounts
                     (list (jami-account
                            (archive "/etc/jami/unencrypted-account-1.gz"))
                           (jami-account
                            (archive "/etc/jami/unencrypted-account-2.gz"))))))

     When the accounts field is specified, the Jami account files of the
     service found under ‘/var/lib/jami’ are recreated every time the
     service starts.

     Jami accounts and their corresponding backup archives can be
     generated using the ‘jami’ or ‘jami-gnome’ Jami clients.  The
     accounts should not be password-protected, but it is wise to ensure
     their files are only readable by ‘root’.

     The next example shows how to declare that only some contacts
     should be allowed to communicate with a given account:

          (service jami-service-type
                   (jami-configuration
                    (accounts
                     (list (jami-account
                            (archive "/etc/jami/unencrypted-account-1.gz")
                            (peer-discovery? #t)
                            (rendezvous-point? #t)
                            (allowed-contacts
                             '("1dbcb0f5f37324228235564b79f2b9737e9a008f"
                               "2dbcb0f5f37324228235564b79f2b9737e9a008f")))))))

     In this mode, only the declared ‘allowed-contacts’ can initiate
     communication with the Jami account.  This can be used, for
     example, with rendezvous point accounts to create a private video
     conferencing space.

     To put the system administrator in full control of the conferences
     hosted on their system, the Jami service supports the following
     actions:

          # herd doc jami list-actions
          (list-accounts
           list-account-details
           list-banned-contacts
           list-contacts
           list-moderators
           add-moderator
           ban-contact
           enable-account
           disable-account)

     The above actions aim to provide the most valuable actions for
     moderation purposes, not to cover the whole Jami API. Users wanting
     to interact with the Jami daemon from Guile may be interested in
     experimenting with the ‘(gnu build jami-service)’ module, which
     powers the above Shepherd actions.

     The ‘add-moderator’ and ‘ban-contact’ actions accept a contact
     _fingerprint_ (40 characters long hash) as first argument and an
     account fingerprint or username as second argument:

          # herd add-moderator jami 1dbcb0f5f37324228235564b79f2b9737e9a008f \
            f3345f2775ddfe07a4b0d95daea111d15fbc1199

          # herd list-moderators jami
          Moderators for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
            - 1dbcb0f5f37324228235564b79f2b9737e9a008f


     In the case of ‘ban-contact’, the second username argument is
     optional; when omitted, the account is banned from all Jami
     accounts:

          # herd ban-contact jami 1dbcb0f5f37324228235564b79f2b9737e9a008f

          # herd list-banned-contacts jami
          Banned contacts for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
            - 1dbcb0f5f37324228235564b79f2b9737e9a008f


     Banned contacts are also stripped from their moderation privileges.

     The ‘disable-account’ action allows to completely disconnect an
     account from the network, making it unreachable, while
     ‘enable-account’ does the inverse.  They accept a single account
     username or fingerprint as first argument:

          # herd disable-account jami f3345f2775ddfe07a4b0d95daea111d15fbc1199

          # herd list-accounts jami
          The following Jami accounts are available:
            - f3345f2775ddfe07a4b0d95daea111d15fbc1199 (dummy) [disabled]


     The ‘list-account-details’ action prints the detailed parameters of
     each accounts in the Recutils format, which means the ‘recsel’
     command can be used to select accounts of interest (*note
     (recutils)Selection Expressions::).  Note that period characters
     (‘.’) found in the account parameter keys are mapped to underscores
     (‘_’) in the output, to meet the requirements of the Recutils
     format.  The following example shows how to print the account
     fingerprints for all accounts operating in the rendezvous point
     mode:

          # herd list-account-details jami | \
            recsel -p Account.username -e 'Account.rendezVous ~ "true"'
          Account_username: f3345f2775ddfe07a4b0d95daea111d15fbc1199

     The remaining actions should be self-explanatory.

     The complete set of available configuration options is detailed
     below.

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

     ‘libjami’ (default: ‘libjami’) (type: package)
          The Jami daemon package to use.

     ‘dbus’ (default: ‘dbus-for-jami’) (type: package)
          The D-Bus package to use to start the required D-Bus session.

     ‘nss-certs’ (default: ‘nss-certs’) (type: package)
          The nss-certs package to use to provide TLS certificates.

     ‘enable-logging?’ (default: ‘#t’) (type: boolean)
          Whether to enable logging to syslog.

     ‘debug?’ (default: ‘#f’) (type: boolean)
          Whether to enable debug level messages.

     ‘auto-answer?’ (default: ‘#f’) (type: boolean)
          Whether to force automatic answer to incoming calls.

     ‘accounts’ (type: maybe-jami-account-list)
          A list of Jami accounts to be (re-)provisioned every time the
          Jami daemon service starts.  When providing this field, the
          account directories under ‘/var/lib/jami/’ are recreated every
          time the service starts, ensuring a consistent state.

 -- Data Type: jami-account
     Available ‘jami-account’ fields are:

     ‘archive’ (type: string-or-computed-file)
          The account archive (backup) file name of the account.  This
          is used to provision the account when the service starts.  The
          account archive should _not_ be encrypted.  It is highly
          recommended to make it readable only to the ‘root’ user (i.e.,
          not in the store), to guard against leaking the secret key
          material of the Jami account it contains.

     ‘allowed-contacts’ (type: maybe-account-fingerprint-list)
          The list of allowed contacts for the account, entered as their
          40 characters long fingerprint.  Messages or calls from
          accounts not in that list will be rejected.  When left
          specified, the configuration of the account archive is used
          as-is with respect to contacts and public inbound
          calls/messaging allowance, which typically defaults to allow
          any contact to communicate with the account.

     ‘moderators’ (type: maybe-account-fingerprint-list)
          The list of contacts that should have moderation privileges
          (to ban, mute, etc.  other users) in rendezvous conferences,
          entered as their 40 characters long fingerprint.  When left
          unspecified, the configuration of the account archive is used
          as-is with respect to moderation, which typically defaults to
          allow anyone to moderate.

     ‘rendezvous-point?’ (type: maybe-boolean)
          Whether the account should operate in the rendezvous mode.  In
          this mode, all the incoming audio/video calls are mixed into a
          conference.  When left unspecified, the value from the account
          archive prevails.

     ‘peer-discovery?’ (type: maybe-boolean)
          Whether peer discovery should be enabled.  Peer discovery is
          used to discover other OpenDHT nodes on the local network,
          which can be useful to maintain communication between devices
          on such network even when the connection to the Internet has
          been lost.  When left unspecified, the value from the account
          archive prevails.

     ‘bootstrap-hostnames’ (type: maybe-list-of-strings)
          A list of hostnames or IPs pointing to OpenDHT nodes, that
          should be used to initially join the OpenDHT network.  When
          left unspecified, the value from the account archive prevails.

     ‘name-server-uri’ (type: maybe-string)
          The URI of the name server to use, that can be used to
          retrieve the account fingerprint for a registered username.

Mumble server
.............

This section describes how to set up and run a Mumble
(https://mumble.info) server (formerly known as Murmur).

 -- Variable: mumble-server-service-type

     This is the service to run a Mumble server.  It takes a
     ‘mumble-server-configuration’ object as its value, defined below.

 -- Data Type: mumble-server-configuration
     The service type for the Mumble server.  An example configuration
     can look like this:

          (service mumble-server-service-type
                   (mumble-server-configuration
                    (welcome-text
                      "Welcome to this Mumble server running on Guix!")
                    (cert-required? #t) ;disallow text password logins
                    (ssl-cert "/etc/certs/mumble.example.com/fullchain.pem")
                    (ssl-key "/etc/certs/mumble.example.com/privkey.pem")))

     After reconfiguring your system, you can manually set the
     mumble-server ‘SuperUser’ password with the command that is printed
     during the activation phase.

     It is recommended to register a normal Mumble user account and
     grant it admin or moderator rights.  You can use the ‘mumble’
     client to login as new normal user, register yourself, and log out.
     For the next step login with the name ‘SuperUser’ use the
     ‘SuperUser’ password that you set previously, and grant your newly
     registered mumble user administrator or moderator rights and create
     some channels.

     Available ‘mumble-server-configuration’ fields are:

     ‘package’ (default: ‘mumble’)
          Package that contains ‘bin/mumble-server’.

     ‘user’ (default: ‘"mumble-server"’)
          User who will run the Mumble-Server server.

     ‘group’ (default: ‘"mumble-server"’)
          Group of the user who will run the mumble-server server.

     ‘port’ (default: ‘64738’)
          Port on which the server will listen.

     ‘welcome-text’ (default: ‘""’)
          Welcome text sent to clients when they connect.

     ‘server-password’ (default: ‘""’)
          Password the clients have to enter in order to connect.

     ‘max-users’ (default: ‘100’)
          Maximum of users that can be connected to the server at once.

     ‘max-user-bandwidth’ (default: ‘#f’)
          Maximum voice traffic a user can send per second.

     ‘database-file’ (default: ‘"/var/lib/mumble-server/db.sqlite"’)
          File name of the sqlite database.  The service’s user will
          become the owner of the directory.

     ‘log-file’ (default: ‘"/var/log/mumble-server/mumble-server.log"’)
          File name of the log file.  The service’s user will become the
          owner of the directory.

     ‘autoban-attempts’ (default: ‘10’)
          Maximum number of logins a user can make in
          ‘autoban-timeframe’ without getting auto banned for
          ‘autoban-time’.

     ‘autoban-timeframe’ (default: ‘120’)
          Timeframe for autoban in seconds.

     ‘autoban-time’ (default: ‘300’)
          Amount of time in seconds for which a client gets banned when
          violating the autoban limits.

     ‘opus-threshold’ (default: ‘100’)
          Percentage of clients that need to support opus before
          switching over to opus audio codec.

     ‘channel-nesting-limit’ (default: ‘10’)
          How deep channels can be nested at maximum.

     ‘channelname-regex’ (default: ‘#f’)
          A string in form of a Qt regular expression that channel names
          must conform to.

     ‘username-regex’ (default: ‘#f’)
          A string in form of a Qt regular expression that user names
          must conform to.

     ‘text-message-length’ (default: ‘5000’)
          Maximum size in bytes that a user can send in one text chat
          message.

     ‘image-message-length’ (default: ‘(* 128 1024)’)
          Maximum size in bytes that a user can send in one image
          message.

     ‘cert-required?’ (default: ‘#f’)
          If it is set to ‘#t’ clients that use weak password
          authentication will not be accepted.  Users must have
          completed the certificate wizard to join.

     ‘remember-channel?’ (default: ‘#f’)
          Should mumble-server remember the last channel each user was
          in when they disconnected and put them into the remembered
          channel when they rejoin.

     ‘allow-html?’ (default: ‘#f’)
          Should html be allowed in text messages, user comments, and
          channel descriptions.

     ‘allow-ping?’ (default: ‘#f’)
          Setting to true exposes the current user count, the maximum
          user count, and the server’s maximum bandwidth per client to
          unauthenticated users.  In the Mumble client, this information
          is shown in the Connect dialog.

          Disabling this setting will prevent public listing of the
          server.

     ‘bonjour?’ (default: ‘#f’)
          Should the server advertise itself in the local network
          through the bonjour protocol.

     ‘send-version?’ (default: ‘#f’)
          Should the mumble-server server version be exposed in ping
          requests.

     ‘log-days’ (default: ‘31’)
          Mumble also stores logs in the database, which are accessible
          via RPC. The default is 31 days of months, but you can set
          this setting to 0 to keep logs forever, or -1 to disable
          logging to the database.

     ‘obfuscate-ips?’ (default: ‘#t’)
          Should logged ips be obfuscated to protect the privacy of
          users.

     ‘ssl-cert’ (default: ‘#f’)
          File name of the SSL/TLS certificate used for encrypted
          connections.

               (ssl-cert "/etc/certs/example.com/fullchain.pem")
     ‘ssl-key’ (default: ‘#f’)
          Filepath to the ssl private key used for encrypted
          connections.
               (ssl-key "/etc/certs/example.com/privkey.pem")

     ‘ssl-dh-params’ (default: ‘#f’)
          File name of a PEM-encoded file with Diffie-Hellman parameters
          for the SSL/TLS encryption.  Alternatively you set it to
          ‘"@ffdhe2048"’, ‘"@ffdhe3072"’, ‘"@ffdhe4096"’, ‘"@ffdhe6144"’
          or ‘"@ffdhe8192"’ to use bundled parameters from RFC 7919.

     ‘ssl-ciphers’ (default: ‘#f’)
          The ‘ssl-ciphers’ option chooses the cipher suites to make
          available for use in SSL/TLS.

          This option is specified using OpenSSL cipher list notation
          (https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT).

          It is recommended that you try your cipher string using
          ’openssl ciphers <string>’ before setting it here, to get a
          feel for which cipher suites you will get.  After setting this
          option, it is recommend that you inspect your Mumble server
          log to ensure that Mumble is using the cipher suites that you
          expected it to.

               Note: Changing this option may impact the backwards
               compatibility of your Mumble-Server server, and can
               remove the ability for older Mumble clients to be able to
               connect to it.

     ‘public-registration’ (default: ‘#f’)
          Must be a ‘<mumble-server-public-registration-configuration>’
          record or ‘#f’.

          You can optionally register your server in the public server
          list that the ‘mumble’ client shows on startup.  You cannot
          register your server if you have set a ‘server-password’, or
          set ‘allow-ping’ to ‘#f’.

          It might take a few hours until it shows up in the public
          list.

     ‘file’ (default: ‘#f’)
          Optional alternative override for this configuration.

 -- Data Type: mumble-server-public-registration-configuration
     Configuration for public registration of a mumble-server service.

     ‘name’
          This is a display name for your server.  Not to be confused
          with the hostname.

     ‘password’
          A password to identify your registration.  Subsequent updates
          will need the same password.  Don’t lose your password.

     ‘url’
          This should be a ‘http://’ or ‘https://’ link to your web
          site.

     ‘hostname’ (default: ‘#f’)
          By default your server will be listed by its IP address.  If
          it is set your server will be linked by this host name
          instead.

     Deprecation notice: Due to historical reasons, all of the above
     ‘mumble-server-’ procedures are also exported with the ‘murmur-’
     prefix.  It is recommended that you switch to using
     ‘mumble-server-’ going forward.


File: guix.info,  Node: File-Sharing Services,  Next: Monitoring Services,  Prev: Telephony Services,  Up: Services

11.10.16 File-Sharing Services
------------------------------

The ‘(gnu services file-sharing)’ module provides services that assist
with transferring files over peer-to-peer file-sharing networks.

Transmission Daemon Service
...........................

Transmission (https://transmissionbt.com/) is a flexible BitTorrent
client that offers a variety of graphical and command-line interfaces.
A ‘transmission-daemon-service-type’ service provides Transmission’s
headless variant, ‘transmission-daemon’, as a system service, allowing
users to share files via BitTorrent even when they are not logged in.

 -- Variable: transmission-daemon-service-type
     The service type for the Transmission Daemon BitTorrent client.
     Its value must be a ‘transmission-daemon-configuration’ object as
     in this example:

          (service transmission-daemon-service-type
                   (transmission-daemon-configuration
                    ;; Restrict access to the RPC ("control") interface
                    (rpc-authentication-required? #t)
                    (rpc-username "transmission")
                    (rpc-password
                     (transmission-password-hash
                      "transmission" ; desired password
                      "uKd1uMs9"))   ; arbitrary salt value

                    ;; Accept requests from this and other hosts on the
                    ;; local network
                    (rpc-whitelist-enabled? #t)
                    (rpc-whitelist '("::1" "127.0.0.1" "192.168.0.*"))

                    ;; Limit bandwidth use during work hours
                    (alt-speed-down (* 1024 2)) ;   2 MB/s
                    (alt-speed-up 512)          ; 512 kB/s

                    (alt-speed-time-enabled? #t)
                    (alt-speed-time-day 'weekdays)
                    (alt-speed-time-begin
                     (+ (* 60 8) 30))           ; 8:30 am
                    (alt-speed-time-end
                     (+ (* 60 (+ 12 5)) 30))))  ; 5:30 pm

   Once the service is started, users can interact with the daemon
through its Web interface (at ‘http://localhost:9091/’) or by using the
‘transmission-remote’ command-line tool, available in the ‘transmission’
package.  (Emacs users may want to also consider the
‘emacs-transmission’ package.)  Both communicate with the daemon through
its remote procedure call (RPC) interface, which by default is available
to all users on the system; you may wish to change this by assigning
values to the ‘rpc-authentication-required?’, ‘rpc-username’ and
‘rpc-password’ settings, as shown in the example above and documented
further below.

   The value for ‘rpc-password’ must be a password hash of the type
generated and used by Transmission clients.  This can be copied verbatim
from an existing ‘settings.json’ file, if another Transmission client is
already being used.  Otherwise, the ‘transmission-password-hash’ and
‘transmission-random-salt’ procedures provided by this module can be
used to obtain a suitable hash value.

 -- Procedure: transmission-password-hash password salt
     Returns a string containing the result of hashing PASSWORD together
     with SALT, in the format recognized by Transmission clients for
     their ‘rpc-password’ configuration setting.

     SALT must be an eight-character string.  The
     ‘transmission-random-salt’ procedure can be used to generate a
     suitable salt value at random.

 -- Procedure: transmission-random-salt
     Returns a string containing a random, eight-character salt value of
     the type generated and used by Transmission clients, suitable for
     passing to the ‘transmission-password-hash’ procedure.

   These procedures are accessible from within a Guile REPL started with
the ‘guix repl’ command (*note Invoking guix repl::).  This is useful
for obtaining a random salt value to provide as the second parameter to
‘transmission-password-hash‘, as in this example session:

     $ guix repl
     scheme@(guix-user)> ,use (gnu services file-sharing)
     scheme@(guix-user)> (transmission-random-salt)
     $1 = "uKd1uMs9"

   Alternatively, a complete password hash can generated in a single
step:

     scheme@(guix-user)> (transmission-password-hash "transmission"
     (transmission-random-salt))
     $2 = "{c8bbc6d1740cd8dc819a6e25563b67812c1c19c9VtFPfdsX"

   The resulting string can be used as-is for the value of
‘rpc-password’, allowing the password to be kept hidden even in the
operating-system configuration.

   Torrent files downloaded by the daemon are directly accessible only
to users in the “transmission” user group, who receive read-only access
to the directory specified by the ‘download-dir’ configuration setting
(and also the directory specified by ‘incomplete-dir’, if
‘incomplete-dir-enabled?’ is ‘#t’).  Downloaded files can be moved to
another directory or deleted altogether using ‘transmission-remote’ with
its ‘--move’ and ‘--remove-and-delete’ options.

   If the ‘watch-dir-enabled?’ setting is set to ‘#t’, users in the
“transmission” group are able also to place ‘.torrent’ files in the
directory specified by ‘watch-dir’ to have the corresponding torrents
added by the daemon.  (The ‘trash-original-torrent-files?’ setting
controls whether the daemon deletes these files after processing them.)

   Some of the daemon’s configuration settings can be changed
temporarily by ‘transmission-remote’ and similar tools.  To undo these
changes, use the service’s ‘reload’ action to have the daemon reload its
settings from disk:

     # herd reload transmission-daemon

   The full set of available configuration settings is defined by the
‘transmission-daemon-configuration’ data type.

 -- Data Type: transmission-daemon-configuration
     The data type representing configuration settings for Transmission
     Daemon.  These correspond directly to the settings recognized by
     Transmission clients in their ‘settings.json’ file.

   Available ‘transmission-daemon-configuration’ fields are:

 -- transmission-daemon-configuration parameter: package transmission
     The Transmission package to use.

 -- transmission-daemon-configuration parameter: non-negative-integer
          stop-wait-period
     The period, in seconds, to wait when stopping the service for
     ‘transmission-daemon’ to exit before killing its process.  This
     allows the daemon time to complete its housekeeping and send a
     final update to trackers as it shuts down.  On slow hosts, or hosts
     with a slow network connection, this value may need to be
     increased.

     Defaults to ‘10’.

 -- transmission-daemon-configuration parameter: string download-dir
     The directory to which torrent files are downloaded.

     Defaults to ‘"/var/lib/transmission-daemon/downloads"’.

 -- transmission-daemon-configuration parameter: boolean
          incomplete-dir-enabled?
     If ‘#t’, files will be held in ‘incomplete-dir’ while their torrent
     is being downloaded, then moved to ‘download-dir’ once the torrent
     is complete.  Otherwise, files for all torrents (including those
     still being downloaded) will be placed in ‘download-dir’.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: maybe-string
          incomplete-dir
     The directory in which files from incompletely downloaded torrents
     will be held when ‘incomplete-dir-enabled?’ is ‘#t’.

     Defaults to ‘disabled’.

 -- transmission-daemon-configuration parameter: umask umask
     The file mode creation mask used for downloaded files.  (See the
     ‘umask’ man page for more information.)

     Defaults to ‘18’.

 -- transmission-daemon-configuration parameter: boolean
          rename-partial-files?
     When ‘#t’, “.part” is appended to the name of partially downloaded
     files.

     Defaults to ‘#t’.

 -- transmission-daemon-configuration parameter: preallocation-mode
          preallocation
     The mode by which space should be preallocated for downloaded
     files, one of ‘none’, ‘fast’ (or ‘sparse’) and ‘full’.  Specifying
     ‘full’ will minimize disk fragmentation at a cost to file-creation
     speed.

     Defaults to ‘fast’.

 -- transmission-daemon-configuration parameter: boolean
          watch-dir-enabled?
     If ‘#t’, the directory specified by ‘watch-dir’ will be watched for
     new ‘.torrent’ files and the torrents they describe added
     automatically (and the original files removed, if
     ‘trash-original-torrent-files?’ is ‘#t’).

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: maybe-string watch-dir
     The directory to be watched for ‘.torrent’ files indicating new
     torrents to be added, when ‘watch-dir-enabled’ is ‘#t’.

     Defaults to ‘disabled’.

 -- transmission-daemon-configuration parameter: boolean
          trash-original-torrent-files?
     When ‘#t’, ‘.torrent’ files will be deleted from the watch
     directory once their torrent has been added (see
     ‘watch-directory-enabled?’).

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: boolean
          speed-limit-down-enabled?
     When ‘#t’, the daemon’s download speed will be limited to the rate
     specified by ‘speed-limit-down’.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          speed-limit-down
     The default global-maximum download speed, in kilobytes per second.

     Defaults to ‘100’.

 -- transmission-daemon-configuration parameter: boolean
          speed-limit-up-enabled?
     When ‘#t’, the daemon’s upload speed will be limited to the rate
     specified by ‘speed-limit-up’.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          speed-limit-up
     The default global-maximum upload speed, in kilobytes per second.

     Defaults to ‘100’.

 -- transmission-daemon-configuration parameter: boolean
          alt-speed-enabled?
     When ‘#t’, the alternate speed limits ‘alt-speed-down’ and
     ‘alt-speed-up’ are used (in place of ‘speed-limit-down’ and
     ‘speed-limit-up’, if they are enabled) to constrain the daemon’s
     bandwidth usage.  This can be scheduled to occur automatically at
     certain times during the week; see ‘alt-speed-time-enabled?’.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          alt-speed-down
     The alternate global-maximum download speed, in kilobytes per
     second.

     Defaults to ‘50’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          alt-speed-up
     The alternate global-maximum upload speed, in kilobytes per second.

     Defaults to ‘50’.

 -- transmission-daemon-configuration parameter: boolean
          alt-speed-time-enabled?
     When ‘#t’, the alternate speed limits ‘alt-speed-down’ and
     ‘alt-speed-up’ will be enabled automatically during the periods
     specified by ‘alt-speed-time-day’, ‘alt-speed-time-begin’ and
     ‘alt-time-speed-end’.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: day-list
          alt-speed-time-day
     The days of the week on which the alternate-speed schedule should
     be used, specified either as a list of days (‘sunday’, ‘monday’,
     and so on) or using one of the symbols ‘weekdays’, ‘weekends’ or
     ‘all’.

     Defaults to ‘all’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          alt-speed-time-begin
     The time of day at which to enable the alternate speed limits,
     expressed as a number of minutes since midnight.

     Defaults to ‘540’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          alt-speed-time-end
     The time of day at which to disable the alternate speed limits,
     expressed as a number of minutes since midnight.

     Defaults to ‘1020’.

 -- transmission-daemon-configuration parameter: string
          bind-address-ipv4
     The IP address at which to listen for peer connections, or
     “0.0.0.0” to listen at all available IP addresses.

     Defaults to ‘"0.0.0.0"’.

 -- transmission-daemon-configuration parameter: string
          bind-address-ipv6
     The IPv6 address at which to listen for peer connections, or “::”
     to listen at all available IPv6 addresses.

     Defaults to ‘"::"’.

 -- transmission-daemon-configuration parameter: boolean
          peer-port-random-on-start?
     If ‘#t’, when the daemon starts it will select a port at random on
     which to listen for peer connections, from the range specified
     (inclusively) by ‘peer-port-random-low’ and
     ‘peer-port-random-high’.  Otherwise, it listens on the port
     specified by ‘peer-port’.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: port-number
          peer-port-random-low
     The lowest selectable port number when ‘peer-port-random-on-start?’
     is ‘#t’.

     Defaults to ‘49152’.

 -- transmission-daemon-configuration parameter: port-number
          peer-port-random-high
     The highest selectable port number when ‘peer-port-random-on-start’
     is ‘#t’.

     Defaults to ‘65535’.

 -- transmission-daemon-configuration parameter: port-number peer-port
     The port on which to listen for peer connections when
     ‘peer-port-random-on-start?’ is ‘#f’.

     Defaults to ‘51413’.

 -- transmission-daemon-configuration parameter: boolean
          port-forwarding-enabled?
     If ‘#t’, the daemon will attempt to configure port-forwarding on an
     upstream gateway automatically using UPnP and NAT-PMP.

     Defaults to ‘#t’.

 -- transmission-daemon-configuration parameter: encryption-mode
          encryption
     The encryption preference for peer connections, one of
     ‘prefer-unencrypted-connections’, ‘prefer-encrypted-connections’ or
     ‘require-encrypted-connections’.

     Defaults to ‘prefer-encrypted-connections’.

 -- transmission-daemon-configuration parameter: maybe-string
          peer-congestion-algorithm
     The TCP congestion-control algorithm to use for peer connections,
     specified using a string recognized by the operating system in
     calls to ‘setsockopt’.  When left unspecified, the operating-system
     default is used.

     Note that on GNU/Linux systems, the kernel must be configured to
     allow processes to use a congestion-control algorithm not in the
     default set; otherwise, it will deny these requests with “Operation
     not permitted”.  To see which algorithms are available on your
     system and which are currently permitted for use, look at the
     contents of the files ‘tcp_available_congestion_control’ and
     ‘tcp_allowed_congestion_control’ in the ‘/proc/sys/net/ipv4’
     directory.

     As an example, to have Transmission Daemon use the TCP Low Priority
     congestion-control algorithm
     (http://www-ece.rice.edu/networks/TCP-LP/), you’ll need to modify
     your kernel configuration to build in support for the algorithm,
     then update your operating-system configuration to allow its use by
     adding a ‘sysctl-service-type’ service (or updating the existing
     one’s configuration) with lines like the following:

          (service sysctl-service-type
                   (sysctl-configuration
                    (settings
                     ("net.ipv4.tcp_allowed_congestion_control" .
                      "reno cubic lp"))))

     The Transmission Daemon configuration can then be updated with

          (peer-congestion-algorithm "lp")

     and the system reconfigured to have the changes take effect.

     Defaults to ‘disabled’.

 -- transmission-daemon-configuration parameter: tcp-type-of-service
          peer-socket-tos
     The type of service to request in outgoing TCP packets, one of
     ‘default’, ‘low-cost’, ‘throughput’, ‘low-delay’ and ‘reliability’.

     Defaults to ‘default’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          peer-limit-global
     The global limit on the number of connected peers.

     Defaults to ‘200’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          peer-limit-per-torrent
     The per-torrent limit on the number of connected peers.

     Defaults to ‘50’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          upload-slots-per-torrent
     The maximum number of peers to which the daemon will upload data
     simultaneously for each torrent.

     Defaults to ‘14’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          peer-id-ttl-hours
     The maximum lifespan, in hours, of the peer ID associated with each
     public torrent before it is regenerated.

     Defaults to ‘6’.

 -- transmission-daemon-configuration parameter: boolean
          blocklist-enabled?
     When ‘#t’, the daemon will ignore peers mentioned in the blocklist
     it has most recently downloaded from ‘blocklist-url’.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: maybe-string
          blocklist-url
     The URL of a peer blocklist (in P2P-plaintext or eMule ‘.dat’
     format) to be periodically downloaded and applied when
     ‘blocklist-enabled?’ is ‘#t’.

     Defaults to ‘disabled’.

 -- transmission-daemon-configuration parameter: boolean
          download-queue-enabled?
     If ‘#t’, the daemon will be limited to downloading at most
     ‘download-queue-size’ non-stalled torrents simultaneously.

     Defaults to ‘#t’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          download-queue-size
     The size of the daemon’s download queue, which limits the number of
     non-stalled torrents it will download at any one time when
     ‘download-queue-enabled?’ is ‘#t’.

     Defaults to ‘5’.

 -- transmission-daemon-configuration parameter: boolean
          seed-queue-enabled?
     If ‘#t’, the daemon will be limited to seeding at most
     ‘seed-queue-size’ non-stalled torrents simultaneously.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          seed-queue-size
     The size of the daemon’s seed queue, which limits the number of
     non-stalled torrents it will seed at any one time when
     ‘seed-queue-enabled?’ is ‘#t’.

     Defaults to ‘10’.

 -- transmission-daemon-configuration parameter: boolean
          queue-stalled-enabled?
     When ‘#t’, the daemon will consider torrents for which it has not
     shared data in the past ‘queue-stalled-minutes’ minutes to be
     stalled and not count them against its ‘download-queue-size’ and
     ‘seed-queue-size’ limits.

     Defaults to ‘#t’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          queue-stalled-minutes
     The maximum period, in minutes, a torrent may be idle before it is
     considered to be stalled, when ‘queue-stalled-enabled?’ is ‘#t’.

     Defaults to ‘30’.

 -- transmission-daemon-configuration parameter: boolean
          ratio-limit-enabled?
     When ‘#t’, a torrent being seeded will automatically be paused once
     it reaches the ratio specified by ‘ratio-limit’.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: non-negative-rational
          ratio-limit
     The ratio at which a torrent being seeded will be paused, when
     ‘ratio-limit-enabled?’ is ‘#t’.

     Defaults to ‘2.0’.

 -- transmission-daemon-configuration parameter: boolean
          idle-seeding-limit-enabled?
     When ‘#t’, a torrent being seeded will automatically be paused once
     it has been idle for ‘idle-seeding-limit’ minutes.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          idle-seeding-limit
     The maximum period, in minutes, a torrent being seeded may be idle
     before it is paused, when ‘idle-seeding-limit-enabled?’ is ‘#t’.

     Defaults to ‘30’.

 -- transmission-daemon-configuration parameter: boolean dht-enabled?
     Enable the distributed hash table (DHT) protocol
     (http://bittorrent.org/beps/bep_0005.html), which supports the use
     of trackerless torrents.

     Defaults to ‘#t’.

 -- transmission-daemon-configuration parameter: boolean lpd-enabled?
     Enable local peer discovery
     (https://en.wikipedia.org/wiki/Local_Peer_Discovery) (LPD), which
     allows the discovery of peers on the local network and may reduce
     the amount of data sent over the public Internet.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: boolean pex-enabled?
     Enable peer exchange (https://en.wikipedia.org/wiki/Peer_exchange)
     (PEX), which reduces the daemon’s reliance on external trackers and
     may improve its performance.

     Defaults to ‘#t’.

 -- transmission-daemon-configuration parameter: boolean utp-enabled?
     Enable the micro transport protocol
     (http://bittorrent.org/beps/bep_0029.html) (uTP), which aims to
     reduce the impact of BitTorrent traffic on other users of the local
     network while maintaining full utilization of the available
     bandwidth.

     Defaults to ‘#t’.

 -- transmission-daemon-configuration parameter: boolean rpc-enabled?
     If ‘#t’, enable the remote procedure call (RPC) interface, which
     allows remote control of the daemon via its Web interface, the
     ‘transmission-remote’ command-line client, and similar tools.

     Defaults to ‘#t’.

 -- transmission-daemon-configuration parameter: string rpc-bind-address
     The IP address at which to listen for RPC connections, or “0.0.0.0”
     to listen at all available IP addresses.

     Defaults to ‘"0.0.0.0"’.

 -- transmission-daemon-configuration parameter: port-number rpc-port
     The port on which to listen for RPC connections.

     Defaults to ‘9091’.

 -- transmission-daemon-configuration parameter: string rpc-url
     The path prefix to use in the RPC-endpoint URL.

     Defaults to ‘"/transmission/"’.

 -- transmission-daemon-configuration parameter: boolean
          rpc-authentication-required?
     When ‘#t’, clients must authenticate (see ‘rpc-username’ and
     ‘rpc-password’) when using the RPC interface.  Note this has the
     side effect of disabling host-name whitelisting (see
     ‘rpc-host-whitelist-enabled?’.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: maybe-string
          rpc-username
     The username required by clients to access the RPC interface when
     ‘rpc-authentication-required?’ is ‘#t’.

     Defaults to ‘disabled’.

 -- transmission-daemon-configuration parameter:
          maybe-transmission-password-hash rpc-password
     The password required by clients to access the RPC interface when
     ‘rpc-authentication-required?’ is ‘#t’.  This must be specified
     using a password hash in the format recognized by Transmission
     clients, either copied from an existing ‘settings.json’ file or
     generated using the ‘transmission-password-hash’ procedure.

     Defaults to ‘disabled’.

 -- transmission-daemon-configuration parameter: boolean
          rpc-whitelist-enabled?
     When ‘#t’, RPC requests will be accepted only when they originate
     from an address specified in ‘rpc-whitelist’.

     Defaults to ‘#t’.

 -- transmission-daemon-configuration parameter: string-list
          rpc-whitelist
     The list of IP and IPv6 addresses from which RPC requests will be
     accepted when ‘rpc-whitelist-enabled?’ is ‘#t’.  Wildcards may be
     specified using ‘*’.

     Defaults to ‘'("127.0.0.1" "::1")’.

 -- transmission-daemon-configuration parameter: boolean
          rpc-host-whitelist-enabled?
     When ‘#t’, RPC requests will be accepted only when they are
     addressed to a host named in ‘rpc-host-whitelist’.  Note that
     requests to “localhost” or “localhost.”, or to a numeric address,
     are always accepted regardless of these settings.

     Note also this functionality is disabled when
     ‘rpc-authentication-required?’ is ‘#t’.

     Defaults to ‘#t’.

 -- transmission-daemon-configuration parameter: string-list
          rpc-host-whitelist
     The list of host names recognized by the RPC server when
     ‘rpc-host-whitelist-enabled?’ is ‘#t’.

     Defaults to ‘'()’.

 -- transmission-daemon-configuration parameter: message-level
          message-level
     The minimum severity level of messages to be logged (to
     ‘/var/log/transmission.log’) by the daemon, one of ‘none’ (no
     logging), ‘error’, ‘info’ and ‘debug’.

     Defaults to ‘info’.

 -- transmission-daemon-configuration parameter: boolean
          start-added-torrents?
     When ‘#t’, torrents are started as soon as they are added;
     otherwise, they are added in “paused” state.

     Defaults to ‘#t’.

 -- transmission-daemon-configuration parameter: boolean
          script-torrent-done-enabled?
     When ‘#t’, the script specified by ‘script-torrent-done-filename’
     will be invoked each time a torrent completes.

     Defaults to ‘#f’.

 -- transmission-daemon-configuration parameter: maybe-file-object
          script-torrent-done-filename
     A file name or file-like object specifying a script to run each
     time a torrent completes, when ‘script-torrent-done-enabled?’ is
     ‘#t’.

     Defaults to ‘disabled’.

 -- transmission-daemon-configuration parameter: boolean
          scrape-paused-torrents-enabled?
     When ‘#t’, the daemon will scrape trackers for a torrent even when
     the torrent is paused.

     Defaults to ‘#t’.

 -- transmission-daemon-configuration parameter: non-negative-integer
          cache-size-mb
     The amount of memory, in megabytes, to allocate for the daemon’s
     in-memory cache.  A larger value may increase performance by
     reducing the frequency of disk I/O.

     Defaults to ‘4’.

 -- transmission-daemon-configuration parameter: boolean
          prefetch-enabled?
     When ‘#t’, the daemon will try to improve I/O performance by
     hinting to the operating system which data is likely to be read
     next from disk to satisfy requests from peers.

     Defaults to ‘#t’.


File: guix.info,  Node: Monitoring Services,  Next: Kerberos Services,  Prev: File-Sharing Services,  Up: Services

11.10.17 Monitoring Services
----------------------------

Darkstat Service
................

Darkstat is a packet sniffer that captures network traffic, calculates
statistics about usage, and serves reports over HTTP.

 -- Variable: darkstat-service-type
     This is the service type for the darkstat
     (https://unix4lyfe.org/darkstat/) service, its value must be a
     ‘darkstat-configuration’ record as in this example:

          (service darkstat-service-type
                   (darkstat-configuration
                     (interface "eno1")))

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

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

     ‘interface’
          Capture traffic on the specified network interface.

     ‘port’ (default: ‘"667"’)
          Bind the web interface to the specified port.

     ‘bind-address’ (default: ‘"127.0.0.1"’)
          Bind the web interface to the specified address.

     ‘base’ (default: ‘"/"’)
          Specify the path of the base URL.  This can be useful if
          ‘darkstat’ is accessed via a reverse proxy.

Prometheus Node Exporter Service
................................

The Prometheus “node exporter” makes hardware and operating system
statistics provided by the Linux kernel available for the Prometheus
monitoring system.  This service should be deployed on all physical
nodes and virtual machines, where monitoring these statistics is
desirable.

 -- Variable: prometheus-node-exporter-service-type
     This is the service type for the prometheus-node-exporter
     (https://github.com/prometheus/node_exporter/) service, its value
     must be a ‘prometheus-node-exporter-configuration’.

          (service prometheus-node-exporter-service-type)

 -- Data Type: prometheus-node-exporter-configuration
     Data type representing the configuration of ‘node_exporter’.

     ‘package’ (default: ‘go-github-com-prometheus-node-exporter’)
          The prometheus-node-exporter package to use.

     ‘web-listen-address’ (default: ‘":9100"’)
          Bind the web interface to the specified address.

     ‘textfile-directory’ (default: ‘"/var/lib/prometheus/node-exporter"’)
          This directory can be used to export metrics specific to this
          machine.  Files containing metrics in the text format, with
          the filename ending in ‘.prom’ should be placed in this
          directory.

     ‘extra-options’ (default: ‘'()’)
          Extra options to pass to the Prometheus node exporter.

vnStat Network Traffic Monitor
..............................

vnStat is a network traffic monitor that uses interface statistics
provided by the kernel rather than traffic sniffing.  This makes it a
light resource monitor, regardless of network traffic rate.

 -- Variable: vnstat-service-type
     This is the service type for the vnStat (https://humdi.net/vnstat/)
     daemon and accepts a ‘vnstat-configuration’ value.

     The following example will configure the service with default
     values:

          (service vnstat-service-type)

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

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

     ‘database-directory’ (default: ‘"/var/lib/vnstat"’) (type: string)
          Specifies the directory where the database is to be stored.  A
          full path must be given and a leading ’/’ isn’t required.

     ‘5-minute-hours’ (default: ‘48’) (type: maybe-integer)
          Data retention duration for the 5 minute resolution entries.
          The configuration defines for how many past hours entries will
          be stored.  Set to ‘-1’ for unlimited entries or to ‘0’ to
          disable the data collection of this resolution.

     ‘64bit-interface-counters’ (default: ‘-2’) (type: maybe-integer)
          Select interface counter handling.  Set to ‘1’ for defining
          that all interfaces use 64-bit counters on the kernel side and
          ‘0’ for defining 32-bit counter.  Set to ‘-1’ for using the
          old style logic used in earlier versions where counter values
          within 32-bits are assumed to be 32-bit and anything larger is
          assumed to be a 64-bit counter.  This may produce false
          results if a 64-bit counter is reset within the 32-bits.  Set
          to ‘-2’ for using automatic detection based on available
          kernel datastructures.

     ‘always-add-new-interfaces?’ (default: ‘#t’) (type: maybe-boolean)
          Enable or disable automatic creation of new database entries
          for interfaces not currently in the database even if the
          database file already exists when the daemon is started.  New
          database entries will also get created for new interfaces seen
          while the daemon is running.  Pseudo interfaces ‘lo’, ‘lo0’
          and ‘sit0’ are always excluded from getting added.

     ‘bandwidth-detection?’ (default: ‘#t’) (type: maybe-boolean)
          Try to automatically detect MAX-BANDWIDTH value for each
          monitored interface.  Mostly only ethernet interfaces support
          this feature.  MAX-BANDWIDTH will be used as fallback value if
          detection fails.  Any interface specific MAX-BW configuration
          will disable the detection for the specified interface.  In
          Linux, the detection is disabled for tun interfaces due to the
          Linux kernel always reporting 10 Mbit regardless of the used
          real interface.

     ‘bandwidth-detection-interval’ (default: ‘5’) (type: maybe-integer)
          How often in minutes interface specific detection of
          MAX-BANDWIDTH is done for detecting possible changes when
          BANDWIDTH-DETECTION is enabled.  Can be disabled by setting to
          ‘0’.  Value range: ‘0’..‘30’

     ‘boot-variation’ (default: ‘15’) (type: maybe-integer)
          Time in seconds how much the boot time reported by system
          kernel can variate between updates.  Value range: ‘0’..‘300’

     ‘check-disk-space?’ (default: ‘#t’) (type: maybe-boolean)
          Enable or disable the availability check of at least some free
          disk space before a database write.

     ‘create-directories?’ (default: ‘#t’) (type: maybe-boolean)
          Enable or disable the creation of directories when a
          configured path doesn’t exist.  This includes
          DATABASE-DIRECTORY.

     ‘daemon-group’ (type: maybe-user-group)
          Specify the group to which the daemon process should switch
          during startup.  Set to ‘%unset-value’ to disable group
          switching.

     ‘daemon-user’ (type: maybe-user-account)
          Specify the user to which the daemon process should switch
          during startup.  Set to ‘%unset-value’ to disable user
          switching.

     ‘daily-days’ (default: ‘62’) (type: maybe-integer)
          Data retention duration for the one day resolution entries.
          The configuration defines for how many past days entries will
          be stored.  Set to ‘-1’ for unlimited entries or to ‘0’ to
          disable the data collection of this resolution.

     ‘database-synchronous’ (default: ‘-1’) (type: maybe-integer)
          Change the setting of the SQLite "synchronous" flag which
          controls how much care is taken to ensure disk writes have
          fully completed when writing data to the database before
          continuing other actions.  Higher values take extra steps to
          ensure data safety at the cost of slower performance.  A value
          of ‘0’ will result in all handling being left to the
          filesystem itself.  Set to ‘-1’ to select the default value
          according to database mode controlled by
          DATABASE-WRITE-AHEAD-LOGGING setting.  See SQLite
          documentation for more details regarding values from ‘1’ to
          ‘3’.  Value range: ‘-1’..‘3’

     ‘database-write-ahead-logging?’ (default: ‘#f’) (type: maybe-boolean)
          Enable or disable SQLite Write-Ahead Logging mode for the
          database.  See SQLite documentation for more details and note
          that support for read-only operations isn’t available in older
          SQLite versions.

     ‘hourly-days’ (default: ‘4’) (type: maybe-integer)
          Data retention duration for the one hour resolution entries.
          The configuration defines for how many past days entries will
          be stored.  Set to ‘-1’ for unlimited entries or to ‘0’ to
          disable the data collection of this resolution.

     ‘log-file’ (type: maybe-string)
          Specify log file path and name to be used if USE-LOGGING is
          set to ‘1’.

     ‘max-bandwidth’ (type: maybe-integer)
          Maximum bandwidth for all interfaces.  If the interface
          specific traffic exceeds the given value then the data is
          assumed to be invalid and rejected.  Set to 0 in order to
          disable the feature.  Value range: ‘0’..‘50000’

     ‘max-bw’ (type: maybe-alist)
          Same as MAX-BANDWIDTH but can be used for setting individual
          limits for selected interfaces.  This is an association list
          of interfaces as strings to integer values.  For example,
               (max-bw `(("eth0" .  15000)
                         ("ppp0" .  10000)))
          BANDWIDTH-DETECTION is disabled on an interface specific level
          for each MAX-BW configuration.  Value range: ‘0’..‘50000’

     ‘monthly-months’ (default: ‘25’) (type: maybe-integer)
          Data retention duration for the one month resolution entries.
          The configuration defines for how many past months entries
          will be stored.  Set to ‘-1’ for unlimited entries or to ‘0’
          to disable the data collection of this resolution.

     ‘month-rotate’ (default: ‘1’) (type: maybe-integer)
          Day of month that months are expected to change.  Usually set
          to 1 but can be set to alternative values for example for
          tracking monthly billed traffic where the billing period
          doesn’t start on the first day.  For example, if set to 7,
          days of February up to and including the 6th will count for
          January.  Changing this option will not cause existing data to
          be recalculated.  Value range: ‘1’..‘28’

     ‘month-rotate-affects-years?’ (default: ‘#f’) (type: maybe-boolean)
          Enable or disable MONTH-ROTATE also affecting yearly data.
          Applicable only when MONTH-ROTATE has a value greater than
          one.

     ‘offline-save-interval’ (default: ‘30’) (type: maybe-integer)
          How often in minutes cached interface data is saved to file
          when all monitored interfaces are offline.  Value range:
          SAVE-INTERVAL..‘60’

     ‘pid-file’ (default: ‘"/var/run/vnstatd.pid"’) (type: maybe-string)
          Specify pid file path and name to be used.

     ‘poll-interval’ (default: ‘5’) (type: maybe-integer)
          How often in seconds interfaces are checked for status
          changes.  Value range: ‘2’..‘60’

     ‘rescan-database-on-save?’ (type: maybe-boolean)
          Automatically discover added interfaces from the database and
          start monitoring.  The rescan is done every SAVE-INTERVAL or
          OFFLINE-SAVE-INTERVAL minutes depending on the current
          activity state.

     ‘save-interval’ (default: ‘5’) (type: maybe-integer)
          How often in minutes cached interface data is saved to file.
          Value range: ( UPDATE-INTERVAL / 60 )..‘60’

     ‘save-on-status-change?’ (default: ‘#t’) (type: maybe-boolean)
          Enable or disable the additional saving to file of cached
          interface data when the availability of an interface changes,
          i.e., when an interface goes offline or comes online.

     ‘time-sync-wait’ (default: ‘5’) (type: maybe-integer)
          How many minutes to wait during daemon startup for system
          clock to sync if most recent database update appears to be in
          the future.  This may be needed in systems without a real-time
          clock (RTC) which require some time after boot to query and
          set the correct time.  ‘0’ = wait disabled.  Value range:
          ‘0’..‘60’

     ‘top-day-entries’ (default: ‘20’) (type: maybe-integer)
          Data retention duration for the top day entries.  The
          configuration defines how many of the past top day entries
          will be stored.  Set to ‘-1’ for unlimited entries or to ‘0’
          to disable the data collection of this resolution.

     ‘trafficless-entries?’ (default: ‘#t’) (type: maybe-boolean)
          Create database entries even when there is no traffic during
          the entry’s time period.

     ‘update-file-owner?’ (default: ‘#t’) (type: maybe-boolean)
          Enable or disable the update of file ownership during daemon
          process startup.  During daemon startup, only database, log
          and pid files will be modified if the user or group change
          feature ( DAEMON-USER or DAEMON-GROUP ) is enabled and the
          files don’t match the requested user or group.  During manual
          database creation, this option will cause file ownership to be
          inherited from the database directory if the directory already
          exists.  This option only has effect when the process is
          started as root or via sudo.

     ‘update-interval’ (default: ‘20’) (type: maybe-integer)
          How often in seconds the interface data is updated.  Value
          range: POLL-INTERVAL..‘300’

     ‘use-logging’ (default: ‘2’) (type: maybe-integer)
          Enable or disable logging.  Accepted values are: ‘0’ =
          disabled, ‘1’ = logfile and ‘2’ = syslog.

     ‘use-utc?’ (type: maybe-boolean)
          Enable or disable using UTC as timezone in the database for
          all entries.  When enabled, all entries added to the database
          will use UTC regardless of the configured system timezone.
          When disabled, the configured system timezone will be used.
          Changing this setting will not result in already existing data
          to be modified.

     ‘yearly-years’ (default: ‘-1’) (type: maybe-integer)
          Data retention duration for the one year resolution entries.
          The configuration defines for how many past years entries will
          be stored.  Set to ‘-1’ for unlimited entries or to ‘0’ to
          disable the data collection of this resolution.

Zabbix server
.............

Zabbix is a high performance monitoring system that can collect data
from a variety of sources and provide the results in a web-based
interface.  Alerting and reporting is built-in, as well as “templates”
for common operating system metrics such as network utilization, CPU
load, and disk space consumption.

   This service provides the central Zabbix monitoring service; you also
need *note ‘zabbix-front-end-service-type’: zabbix-front-end. to
configure Zabbix and display results, and optionally *note
‘zabbix-agent-service-type’: zabbix-agent. on machines that should be
monitored (other data sources are supported, such as *note Prometheus
Node Exporter: prometheus-node-exporter.).

 -- Variable: zabbix-server-service-type
     This is the service type for the Zabbix server service.  Its value
     must be a ‘zabbix-server-configuration’ record, shown below.

 -- Data Type: zabbix-server-configuration
     Available ‘zabbix-server-configuration’ fields are:

     ‘zabbix-server’ (default: ‘zabbix-server’) (type: file-like)
          The zabbix-server package.

     ‘user’ (default: ‘"zabbix"’) (type: string)
          User who will run the Zabbix server.

     ‘group’ (default: ‘"zabbix"’) (type: string)
          Group who will run the Zabbix server.

     ‘db-host’ (default: ‘"127.0.0.1"’) (type: string)
          Database host name.

     ‘db-name’ (default: ‘"zabbix"’) (type: string)
          Database name.

     ‘db-user’ (default: ‘"zabbix"’) (type: string)
          Database user.

     ‘db-password’ (default: ‘""’) (type: string)
          Database password.  Please, use ‘include-files’ with
          ‘DBPassword=SECRET’ inside a specified file instead.

     ‘db-port’ (default: ‘5432’) (type: number)
          Database port.

     ‘log-type’ (default: ‘""’) (type: string)
          Specifies where log messages are written to:

             • ‘system’ - syslog.

             • ‘file’ - file specified with ‘log-file’ parameter.

             • ‘console’ - standard output.

     ‘log-file’ (default: ‘"/var/log/zabbix/server.log"’) (type: string)
          Log file name for ‘log-type’ ‘file’ parameter.

     ‘pid-file’ (default: ‘"/var/run/zabbix/zabbix_server.pid"’) (type: string)
          Name of PID file.

     ‘ssl-ca-location’ (default: ‘"/etc/ssl/certs/ca-certificates.crt"’) (type: string)
          The location of certificate authority (CA) files for SSL
          server certificate verification.

     ‘ssl-cert-location’ (default: ‘"/etc/ssl/certs"’) (type: string)
          Location of SSL client certificates.

     ‘extra-options’ (default: ‘""’) (type: extra-options)
          Extra options will be appended to Zabbix server configuration
          file.

     ‘include-files’ (default: ‘'()’) (type: include-files)
          You may include individual files or all files in a directory
          in the configuration file.

Zabbix agent
............

The Zabbix agent gathers information about the running system for the
Zabbix monitoring server.  It has a variety of built-in checks, and can
be extended with custom “user parameters”
(https://www.zabbix.com/documentation/current/en/manual/config/items/userparameters).

 -- Variable: zabbix-agent-service-type
     This is the service type for the Zabbix agent service.  Its value
     must be a ‘zabbix-agent-configuration’ record, shown below.

 -- Data Type: zabbix-agent-configuration
     Available ‘zabbix-agent-configuration’ fields are:

     ‘zabbix-agent’ (default: ‘zabbix-agentd’) (type: file-like)
          The zabbix-agent package.

     ‘user’ (default: ‘"zabbix"’) (type: string)
          User who will run the Zabbix agent.

     ‘group’ (default: ‘"zabbix"’) (type: string)
          Group who will run the Zabbix agent.

     ‘hostname’ (default: ‘""’) (type: string)
          Unique, case sensitive hostname which is required for active
          checks and must match hostname as configured on the server.

     ‘log-type’ (default: ‘""’) (type: string)
          Specifies where log messages are written to:

             • ‘system’ - syslog.

             • ‘file’ - file specified with ‘log-file’ parameter.

             • ‘console’ - standard output.

     ‘log-file’ (default: ‘"/var/log/zabbix/agent.log"’) (type: string)
          Log file name for ‘log-type’ ‘file’ parameter.

     ‘pid-file’ (default: ‘"/var/run/zabbix/zabbix_agent.pid"’) (type: string)
          Name of PID file.

     ‘server’ (default: ‘'("127.0.0.1")’) (type: list)
          List of IP addresses, optionally in CIDR notation, or
          hostnames of Zabbix servers and Zabbix proxies.  Incoming
          connections will be accepted only from the hosts listed here.

     ‘server-active’ (default: ‘'("127.0.0.1")’) (type: list)
          List of IP:port (or hostname:port) pairs of Zabbix servers and
          Zabbix proxies for active checks.  If port is not specified,
          default port is used.  If this parameter is not specified,
          active checks are disabled.

     ‘extra-options’ (default: ‘""’) (type: extra-options)
          Extra options will be appended to Zabbix server configuration
          file.

     ‘include-files’ (default: ‘'()’) (type: include-files)
          You may include individual files or all files in a directory
          in the configuration file.

Zabbix front-end
................

The Zabbix front-end provides a web interface to Zabbix.  It does not
need to run on the same machine as the Zabbix server.  This service
works by extending the *note PHP-FPM:: and *note NGINX:: services with
the configuration necessary for loading the Zabbix user interface.

 -- Variable: zabbix-front-end-service-type
     This is the service type for the Zabbix web frontend.  Its value
     must be a ‘zabbix-front-end-configuration’ record, shown below.

 -- Data Type: zabbix-front-end-configuration
     Available ‘zabbix-front-end-configuration’ fields are:

     ‘zabbix-server’ (default: ‘zabbix-server’) (type: file-like)
          The Zabbix server package to use.

     ‘nginx’ (default: ‘'()’) (type: list)
          List of *note ‘nginx-server-configuration’:
          nginx-server-configuration. blocks for the Zabbix front-end.
          When empty, a default that listens on port 80 is used.

     ‘db-host’ (default: ‘"localhost"’) (type: string)
          Database host name.

     ‘db-port’ (default: ‘5432’) (type: number)
          Database port.

     ‘db-name’ (default: ‘"zabbix"’) (type: string)
          Database name.

     ‘db-user’ (default: ‘"zabbix"’) (type: string)
          Database user.

     ‘db-password’ (default: ‘""’) (type: string)
          Database password.  Please, use ‘db-secret-file’ instead.

     ‘db-secret-file’ (default: ‘""’) (type: string)
          Secret file which will be appended to ‘zabbix.conf.php’ file.
          This file contains credentials for use by Zabbix front-end.
          You are expected to create it manually.

     ‘zabbix-host’ (default: ‘"localhost"’) (type: string)
          Zabbix server hostname.

     ‘zabbix-port’ (default: ‘10051’) (type: number)
          Zabbix server port.


File: guix.info,  Node: Kerberos Services,  Next: LDAP Services,  Prev: Monitoring Services,  Up: Services

11.10.18 Kerberos Services
--------------------------

The ‘(gnu services kerberos)’ module provides services relating to the
authentication protocol “Kerberos”.

Krb5 Service
............

Programs using a Kerberos client library normally expect a configuration
file in ‘/etc/krb5.conf’.  This service generates such a file from a
definition provided in the operating system declaration.  It does not
cause any daemon to be started.

   No “keytab” files are provided by this service—you must explicitly
create them.  This service is known to work with the MIT client library,
‘mit-krb5’.  Other implementations have not been tested.

 -- Variable: krb5-service-type
     A service type for Kerberos 5 clients.

Here is an example of its use:
     (service krb5-service-type
              (krb5-configuration
               (default-realm "EXAMPLE.COM")
               (allow-weak-crypto? #t)
               (realms (list
                        (krb5-realm
                         (name "EXAMPLE.COM")
                         (admin-server "groucho.example.com")
                         (kdc "karl.example.com"))
                        (krb5-realm
                         (name "ARGRX.EDU")
                         (admin-server "kerb-admin.argrx.edu")
                         (kdc "keys.argrx.edu"))))))

This example provides a Kerberos 5 client configuration which:
   • Recognizes two realms, viz: “EXAMPLE.COM” and “ARGRX.EDU”, both of
     which have distinct administration servers and key distribution
     centers;
   • Will default to the realm “EXAMPLE.COM” if the realm is not
     explicitly specified by clients;
   • Accepts services which only support encryption types known to be
     weak.

   The ‘krb5-realm’ and ‘krb5-configuration’ types have many fields.
Only the most commonly used ones are described here.  For a full list,
and more detailed explanation of each, see the MIT krb5.conf
documentation.

 -- Data Type: krb5-realm
     ‘name’
          This field is a string identifying the name of the realm.  A
          common convention is to use the fully qualified DNS name of
          your organization, converted to upper case.

     ‘admin-server’
          This field is a string identifying the host where the
          administration server is running.

     ‘kdc’
          This field is a string identifying the key distribution center
          for the realm.

 -- Data Type: krb5-configuration

     ‘allow-weak-crypto?’ (default: ‘#f’)
          If this flag is ‘#t’ then services which only offer encryption
          algorithms known to be weak will be accepted.

     ‘default-realm’ (default: ‘#f’)
          This field should be a string identifying the default Kerberos
          realm for the client.  You should set this field to the name
          of your Kerberos realm.  If this value is ‘#f’ then a realm
          must be specified with every Kerberos principal when invoking
          programs such as ‘kinit’.

     ‘realms’
          This should be a non-empty list of ‘krb5-realm’ objects, which
          clients may access.  Normally, one of them will have a ‘name’
          field matching the ‘default-realm’ field.

PAM krb5 Service
................

The ‘pam-krb5’ service allows for login authentication and password
management via Kerberos.  You will need this service if you want PAM
enabled applications to authenticate users using Kerberos.

 -- Variable: pam-krb5-service-type
     A service type for the Kerberos 5 PAM module.

 -- Data Type: pam-krb5-configuration
     Data type representing the configuration of the Kerberos 5 PAM
     module.  This type has the following parameters:
     ‘pam-krb5’ (default: ‘pam-krb5’)
          The pam-krb5 package to use.

     ‘minimum-uid’ (default: ‘1000’)
          The smallest user ID for which Kerberos authentications should
          be attempted.  Local accounts with lower values will silently
          fail to authenticate.


File: guix.info,  Node: LDAP Services,  Next: Web Services,  Prev: Kerberos Services,  Up: Services

11.10.19 LDAP Services
----------------------

Authentication against LDAP with nslcd
......................................

The ‘(gnu services authentication)’ module provides the
‘nslcd-service-type’, which can be used to authenticate against an LDAP
server.  In addition to configuring the service itself, you may want to
add ‘ldap’ as a name service to the Name Service Switch.  *Note Name
Service Switch:: for detailed information.

   Here is a simple operating system declaration with a default
configuration of the ‘nslcd-service-type’ and a Name Service Switch
configuration that consults the ‘ldap’ name service last:

     (use-service-modules authentication)
     (use-modules (gnu system nss))
     ...
     (operating-system
       ...
       (services
         (cons*
           (service nslcd-service-type)
           (service dhcp-client-service-type)
           %base-services))
       (name-service-switch
        (let ((services (list (name-service (name "db"))
                              (name-service (name "files"))
                              (name-service (name "ldap")))))
          (name-service-switch
           (inherit %mdns-host-lookup-nss)
           (password services)
           (shadow   services)
           (group    services)
           (netgroup services)
           (gshadow  services)))))

   Available ‘nslcd-configuration’ fields are:

 -- nslcd-configuration parameter: package nss-pam-ldapd
     The ‘nss-pam-ldapd’ package to use.

 -- nslcd-configuration parameter: maybe-number threads
     The number of threads to start that can handle requests and perform
     LDAP queries.  Each thread opens a separate connection to the LDAP
     server.  The default is to start 5 threads.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: string uid
     This specifies the user id with which the daemon should be run.

     Defaults to ‘"nslcd"’.

 -- nslcd-configuration parameter: string gid
     This specifies the group id with which the daemon should be run.

     Defaults to ‘"nslcd"’.

 -- nslcd-configuration parameter: log-option log
     This option controls the way logging is done via a list containing
     SCHEME and LEVEL.  The SCHEME argument may either be the symbols
     ‘none’ or ‘syslog’, or an absolute file name.  The LEVEL argument
     is optional and specifies the log level.  The log level may be one
     of the following symbols: ‘crit’, ‘error’, ‘warning’, ‘notice’,
     ‘info’ or ‘debug’.  All messages with the specified log level or
     higher are logged.

     Defaults to ‘'("/var/log/nslcd" info)’.

 -- nslcd-configuration parameter: list uri
     The list of LDAP server URIs.  Normally, only the first server will
     be used with the following servers as fall-back.

     Defaults to ‘'("ldap://localhost:389/")’.

 -- nslcd-configuration parameter: maybe-string ldap-version
     The version of the LDAP protocol to use.  The default is to use the
     maximum version supported by the LDAP library.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string binddn
     Specifies the distinguished name with which to bind to the
     directory server for lookups.  The default is to bind anonymously.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string bindpw
     Specifies the credentials with which to bind.  This option is only
     applicable when used with binddn.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string rootpwmoddn
     Specifies the distinguished name to use when the root user tries to
     modify a user’s password using the PAM module.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string rootpwmodpw
     Specifies the credentials with which to bind if the root user tries
     to change a user’s password.  This option is only applicable when
     used with rootpwmoddn

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string sasl-mech
     Specifies the SASL mechanism to be used when performing SASL
     authentication.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string sasl-realm
     Specifies the SASL realm to be used when performing SASL
     authentication.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string sasl-authcid
     Specifies the authentication identity to be used when performing
     SASL authentication.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string sasl-authzid
     Specifies the authorization identity to be used when performing
     SASL authentication.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-boolean sasl-canonicalize?
     Determines whether the LDAP server host name should be
     canonicalised.  If this is enabled the LDAP library will do a
     reverse host name lookup.  By default, it is left up to the LDAP
     library whether this check is performed or not.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string krb5-ccname
     Set the name for the GSS-API Kerberos credentials cache.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: string base
     The directory search base.

     Defaults to ‘"dc=example,dc=com"’.

 -- nslcd-configuration parameter: scope-option scope
     Specifies the search scope (subtree, onelevel, base or children).
     The default scope is subtree; base scope is almost never useful for
     name service lookups; children scope is not supported on all
     servers.

     Defaults to ‘'(subtree)’.

 -- nslcd-configuration parameter: maybe-deref-option deref
     Specifies the policy for dereferencing aliases.  The default policy
     is to never dereference aliases.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-boolean referrals
     Specifies whether automatic referral chasing should be enabled.
     The default behaviour is to chase referrals.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: list-of-map-entries maps
     This option allows for custom attributes to be looked up instead of
     the default RFC 2307 attributes.  It is a list of maps, each
     consisting of the name of a map, the RFC 2307 attribute to match
     and the query expression for the attribute as it is available in
     the directory.

     Defaults to ‘'()’.

 -- nslcd-configuration parameter: list-of-filter-entries filters
     A list of filters consisting of the name of a map to which the
     filter applies and an LDAP search filter expression.

     Defaults to ‘'()’.

 -- nslcd-configuration parameter: maybe-number bind-timelimit
     Specifies the time limit in seconds to use when connecting to the
     directory server.  The default value is 10 seconds.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-number timelimit
     Specifies the time limit (in seconds) to wait for a response from
     the LDAP server.  A value of zero, which is the default, is to wait
     indefinitely for searches to be completed.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-number idle-timelimit
     Specifies the period if inactivity (in seconds) after which the
     con‐ nection to the LDAP server will be closed.  The default is not
     to time out connections.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-number reconnect-sleeptime
     Specifies the number of seconds to sleep when connecting to all
     LDAP servers fails.  By default one second is waited between the
     first failure and the first retry.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-number reconnect-retrytime
     Specifies the time after which the LDAP server is considered to be
     permanently unavailable.  Once this time is reached retries will be
     done only once per this time period.  The default value is 10
     seconds.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-ssl-option ssl
     Specifies whether to use SSL/TLS or not (the default is not to).
     If ’start-tls is specified then StartTLS is used rather than raw
     LDAP over SSL.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-tls-reqcert-option tls-reqcert
     Specifies what checks to perform on a server-supplied certificate.
     The meaning of the values is described in the ldap.conf(5) manual
     page.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string tls-cacertdir
     Specifies the directory containing X.509 certificates for peer
     authen‐ tication.  This parameter is ignored when using GnuTLS.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string tls-cacertfile
     Specifies the path to the X.509 certificate for peer
     authentication.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string tls-randfile
     Specifies the path to an entropy source.  This parameter is ignored
     when using GnuTLS.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string tls-ciphers
     Specifies the ciphers to use for TLS as a string.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string tls-cert
     Specifies the path to the file containing the local certificate for
     client TLS authentication.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string tls-key
     Specifies the path to the file containing the private key for
     client TLS authentication.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-number pagesize
     Set this to a number greater than 0 to request paged results from
     the LDAP server in accordance with RFC2696.  The default (0) is to
     not request paged results.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-ignore-users-option
          nss-initgroups-ignoreusers
     This option prevents group membership lookups through LDAP for the
     specified users.  Alternatively, the value ’all-local may be used.
     With that value nslcd builds a full list of non-LDAP users on
     startup.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-number nss-min-uid
     This option ensures that LDAP users with a numeric user id lower
     than the specified value are ignored.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-number nss-uid-offset
     This option specifies an offset that is added to all LDAP numeric
     user ids.  This can be used to avoid user id collisions with local
     users.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-number nss-gid-offset
     This option specifies an offset that is added to all LDAP numeric
     group ids.  This can be used to avoid user id collisions with local
     groups.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-boolean nss-nested-groups
     If this option is set, the member attribute of a group may point to
     another group.  Members of nested groups are also returned in the
     higher level group and parent groups are returned when finding
     groups for a specific user.  The default is not to perform extra
     searches for nested groups.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-boolean
          nss-getgrent-skipmembers
     If this option is set, the group member list is not retrieved when
     looking up groups.  Lookups for finding which groups a user belongs
     to will remain functional so the user will likely still get the
     correct groups assigned on login.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-boolean nss-disable-enumeration
     If this option is set, functions which cause all user/group entries
     to be loaded from the directory will not succeed in doing so.  This
     can dramatically reduce LDAP server load in situations where there
     are a great number of users and/or groups.  This option is not
     recommended for most configurations.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string validnames
     This option can be used to specify how user and group names are
     verified within the system.  This pattern is used to check all user
     and group names that are requested and returned from LDAP.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-boolean ignorecase
     This specifies whether or not to perform searches using
     case-insensitive matching.  Enabling this could open up the system
     to authorization bypass vulnerabilities and introduce nscd cache
     poisoning vulnerabilities which allow denial of service.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-boolean pam-authc-ppolicy
     This option specifies whether password policy controls are
     requested and handled from the LDAP server when performing user
     authentication.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string pam-authc-search
     By default nslcd performs an LDAP search with the user’s
     credentials after BIND (authentication) to ensure that the BIND
     operation was successful.  The default search is a simple check to
     see if the user’s DN exists.  A search filter can be specified that
     will be used instead.  It should return at least one entry.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string pam-authz-search
     This option allows flexible fine tuning of the authorisation check
     that should be performed.  The search filter specified is executed
     and if any entries match, access is granted, otherwise access is
     denied.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: maybe-string
          pam-password-prohibit-message
     If this option is set password modification using pam_ldap will be
     denied and the specified message will be presented to the user
     instead.  The message can be used to direct the user to an
     alternative means of changing their password.

     Defaults to ‘disabled’.

 -- nslcd-configuration parameter: list pam-services
     List of pam service names for which LDAP authentication should
     suffice.

     Defaults to ‘'()’.

LDAP Directory Server
.....................

The ‘(gnu services ldap)’ module provides the
‘directory-server-service-type’, which can be used to create and launch
an LDAP server instance.

   Here is an example configuration of the
‘directory-server-service-type’:

     (use-service-modules ldap)

     ...
     (operating-system
       ...
       (services
         (cons
           (service directory-server-service-type
                    (directory-server-instance-configuration
                     (slapd
                      (slapd-configuration
                       (root-password "{PBKDF2_SHA256}AAAgAG...ABSOLUTELYSECRET")))))
           %base-services)))

   The root password should be generated with the ‘pwdhash’ utility that
is provided by the ‘389-ds-base’ package.

   Note that changes to the directory server configuration will not be
applied to existing instances.  You will need to back up and restore
server data manually.  Only new directory server instances will be
created upon system reconfiguration.

 -- Data Type: directory-server-instance-configuration
     Available ‘directory-server-instance-configuration’ fields are:

     ‘package’ (default: ‘389-ds-base’) (type: file-like)
          The ‘389-ds-base’ package.

     ‘config-version’ (default: ‘2’) (type: number)
          Sets the format version of the configuration file.  To use the
          INF file with ‘dscreate’, this parameter must be 2.

     ‘full-machine-name’ (default: ‘"localhost"’) (type: string)
          Sets the fully qualified hostname (FQDN) of this system.

     ‘selinux’ (default: ‘#false’) (type: boolean)
          Enables SELinux detection and integration during the
          installation of this instance.  If set to ‘#true’, ‘dscreate’
          auto-detects whether SELinux is enabled.

     ‘strict-host-checking’ (default: ‘#true’) (type: boolean)
          Sets whether the server verifies the forward and reverse
          record set in the ‘full-machine-name’ parameter.  When
          installing this instance with GSSAPI authentication behind a
          load balancer, set this parameter to ‘#false’.

     ‘systemd’ (default: ‘#false’) (type: boolean)
          Enables systemd platform features.  If set to ‘#true’,
          ‘dscreate’ auto-detects whether systemd is installed.

     ‘slapd’ (type: slapd-configuration)
          Configuration of slapd.

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

               ‘instance-name’ (default: ‘"localhost"’) (type: string)
                    Sets the name of the instance.  You can refer to
                    this value in other parameters of this INF file
                    using the ‘{instance_name}’ variable.  Note that
                    this name cannot be changed after the installation!

               ‘user’ (default: ‘"dirsrv"’) (type: string)
                    Sets the user name the ns-slapd process will use
                    after the service started.

               ‘group’ (default: ‘"dirsrv"’) (type: string)
                    Sets the group name the ns-slapd process will use
                    after the service started.

               ‘port’ (default: ‘389’) (type: number)
                    Sets the TCP port the instance uses for LDAP
                    connections.

               ‘secure-port’ (default: ‘636’) (type: number)
                    Sets the TCP port the instance uses for TLS-secured
                    LDAP connections (LDAPS).

               ‘root-dn’ (default: ‘"cn=Directory Manager"’) (type: string)
                    Sets the “Distinquished Name” (DN) of the
                    administrator account for this instance.

               ‘root-password’ (default: ‘"{invalid}YOU-SHOULD-CHANGE-THIS"’) (type: string)
                    Sets the password of the account specified in the
                    ‘root-dn’ parameter.  You can either set this
                    parameter to a plain text password ‘dscreate’ hashes
                    during the installation or to a "{algorithm}hash"
                    string generated by the ‘pwdhash’ utility.  Note
                    that setting a plain text password can be a security
                    risk if unprivileged users can read this INF file!

               ‘self-sign-cert’ (default: ‘#true’) (type: boolean)
                    Sets whether the setup creates a self-signed
                    certificate and enables TLS encryption during the
                    installation.  This is not suitable for production,
                    but it enables administrators to use TLS right after
                    the installation.  You can replace the self-signed
                    certificate with a certificate issued by a
                    certificate authority.

               ‘self-sign-cert-valid-months’ (default: ‘24’) (type: number)
                    Set the number of months the issued self-signed
                    certificate will be valid.

               ‘backup-dir’ (default: ‘"/var/lib/dirsrv/slapd-{instance_name}/bak"’) (type: string)
                    Set the backup directory of the instance.

               ‘cert-dir’ (default: ‘"/etc/dirsrv/slapd-{instance_name}"’) (type: string)
                    Sets the directory of the instance’s Network
                    Security Services (NSS) database.

               ‘config-dir’ (default: ‘"/etc/dirsrv/slapd-{instance_name}"’) (type: string)
                    Sets the configuration directory of the instance.

               ‘db-dir’ (default: ‘"/var/lib/dirsrv/slapd-{instance_name}/db"’) (type: string)
                    Sets the database directory of the instance.

               ‘initconfig-dir’ (default: ‘"/etc/dirsrv/registry"’) (type: string)
                    Sets the directory of the operating system’s rc
                    configuration directory.

               ‘ldif-dir’ (default: ‘"/var/lib/dirsrv/slapd-{instance_name}/ldif"’) (type: string)
                    Sets the LDIF export and import directory of the
                    instance.

               ‘lock-dir’ (default: ‘"/var/lock/dirsrv/slapd-{instance_name}"’) (type: string)
                    Sets the lock directory of the instance.

               ‘log-dir’ (default: ‘"/var/log/dirsrv/slapd-{instance_name}"’) (type: string)
                    Sets the log directory of the instance.

               ‘run-dir’ (default: ‘"/run/dirsrv"’) (type: string)
                    Sets PID directory of the instance.

               ‘schema-dir’ (default: ‘"/etc/dirsrv/slapd-{instance_name}/schema"’) (type: string)
                    Sets schema directory of the instance.

               ‘tmp-dir’ (default: ‘"/tmp"’) (type: string)
                    Sets the temporary directory of the instance.

     ‘backend-userroot’ (type: backend-userroot-configuration)
          Configuration of the userroot backend.

           -- Data Type: backend-userroot-configuration
               Available ‘backend-userroot-configuration’ fields are:

               ‘create-suffix-entry?’ (default: ‘#false’) (type: boolean)
                    Set this parameter to ‘#true’ to create a generic
                    root node entry for the suffix in the database.

               ‘require-index?’ (default: ‘#false’) (type: boolean)
                    Set this parameter to ‘#true’ to refuse unindexed
                    searches in this database.

               ‘sample-entries’ (default: ‘"no"’) (type: string)
                    Set this parameter to ‘"yes"’ to add latest version
                    of sample entries to this database.  Or, use
                    ‘"001003006"’ to use the 1.3.6 version sample
                    entries.  Use this option, for example, to create a
                    database for testing purposes.

               ‘suffix’ (type: maybe-string)
                    Sets the root suffix stored in this database.  If
                    you do not set the suffix attribute the install
                    process will not create the backend/suffix.  You can
                    also create multiple backends/suffixes by
                    duplicating this section.


File: guix.info,  Node: Web Services,  Next: High Availability Services,  Prev: LDAP Services,  Up: Services

11.10.20 Web Services
---------------------

The ‘(gnu services web)’ module provides the Apache HTTP Server, the
nginx web server, and also a fastcgi wrapper daemon.

Apache HTTP Server
..................

 -- Variable: httpd-service-type
     Service type for the Apache HTTP (https://httpd.apache.org/) server
     (“httpd”).  The value for this service type is a
     ‘httpd-configuration’ record.

     A simple example configuration is given below.

          (service httpd-service-type
                   (httpd-configuration
                     (config
                       (httpd-config-file
                         (server-name "www.example.com")
                         (document-root "/srv/http/www.example.com")))))

     Other services can also extend the ‘httpd-service-type’ to add to
     the configuration.

          (simple-service 'www.example.com-server httpd-service-type
                          (list
                            (httpd-virtualhost
                              "*:80"
                              (list (string-join '("ServerName www.example.com"
                                                   "DocumentRoot /srv/http/www.example.com")
                                                 "\n")))))

   The details for the ‘httpd-configuration’, ‘httpd-module’,
‘httpd-config-file’ and ‘httpd-virtualhost’ record types are given
below.

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

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

     ‘pid-file’ (default: ‘"/var/run/httpd"’)
          The pid file used by the shepherd-service.

     ‘config’ (default: ‘(httpd-config-file)’)
          The configuration file to use with the httpd service.  The
          default value is a ‘httpd-config-file’ record, but this can
          also be a different G-expression that generates a file, for
          example a ‘plain-file’.  A file outside of the store can also
          be specified through a string.

 -- Data Type: httpd-module
     This data type represents a module for the httpd service.

     ‘name’
          The name of the module.

     ‘file’
          The file for the module.  This can be relative to the httpd
          package being used, the absolute location of a file, or a
          G-expression for a file within the store, for example
          ‘(file-append mod-wsgi "/modules/mod_wsgi.so")’.

 -- Variable: %default-httpd-modules
     A default list of ‘httpd-module’ objects.

 -- Data Type: httpd-config-file
     This data type represents a configuration file for the httpd
     service.

     ‘modules’ (default: ‘%default-httpd-modules’)
          The modules to load.  Additional modules can be added here, or
          loaded by additional configuration.

          For example, in order to handle requests for PHP files, you
          can use Apache’s ‘mod_proxy_fcgi’ module along with
          ‘php-fpm-service-type’:

               (service httpd-service-type
                        (httpd-configuration
                         (config
                          (httpd-config-file
                           (modules (cons*
                                     (httpd-module
                                      (name "proxy_module")
                                      (file "modules/mod_proxy.so"))
                                     (httpd-module
                                      (name "proxy_fcgi_module")
                                      (file "modules/mod_proxy_fcgi.so"))
                                     %default-httpd-modules))
                           (extra-config (list "\
               <FilesMatch \\.php$>
                   SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\"
               </FilesMatch>"))))))
               (service php-fpm-service-type
                        (php-fpm-configuration
                         (socket "/var/run/php-fpm.sock")
                         (socket-group "httpd")))

     ‘server-root’ (default: ‘httpd’)
          The ‘ServerRoot’ in the configuration file, defaults to the
          httpd package.  Directives including ‘Include’ and
          ‘LoadModule’ are taken as relative to the server root.

     ‘server-name’ (default: ‘#f’)
          The ‘ServerName’ in the configuration file, used to specify
          the request scheme, hostname and port that the server uses to
          identify itself.

          This doesn’t need to be set in the server config, and can be
          specified in virtual hosts.  The default is ‘#f’ to not
          specify a ‘ServerName’.

     ‘document-root’ (default: ‘"/srv/http"’)
          The ‘DocumentRoot’ from which files will be served.

     ‘listen’ (default: ‘'("80")’)
          The list of values for the ‘Listen’ directives in the config
          file.  The value should be a list of strings, when each string
          can specify the port number to listen on, and optionally the
          IP address and protocol to use.

     ‘pid-file’ (default: ‘"/var/run/httpd"’)
          The ‘PidFile’ to use.  This should match the ‘pid-file’ set in
          the ‘httpd-configuration’ so that the Shepherd service is
          configured correctly.

     ‘error-log’ (default: ‘"/var/log/httpd/error_log"’)
          The ‘ErrorLog’ to which the server will log errors.

     ‘user’ (default: ‘"httpd"’)
          The ‘User’ which the server will answer requests as.

     ‘group’ (default: ‘"httpd"’)
          The ‘Group’ which the server will answer requests as.

     ‘extra-config’ (default: ‘(list "TypesConfig etc/httpd/mime.types")’)
          A flat list of strings and G-expressions which will be added
          to the end of the configuration file.

          Any values which the service is extended with will be appended
          to this list.

 -- Data Type: httpd-virtualhost
     This data type represents a virtualhost configuration block for the
     httpd service.

     These should be added to the extra-config for the httpd-service.

          (simple-service 'www.example.com-server httpd-service-type
                          (list
                            (httpd-virtualhost
                              "*:80"
                              (list (string-join '("ServerName www.example.com"
                                                    "DocumentRoot /srv/http/www.example.com")
                                                 "\n")))))

     ‘addresses-and-ports’
          The addresses and ports for the ‘VirtualHost’ directive.

     ‘contents’
          The contents of the ‘VirtualHost’ directive, this should be a
          list of strings and G-expressions.

NGINX
.....

 -- Variable: nginx-service-type
     Service type for the NGinx (https://nginx.org/) web server.  The
     value for this service type is a ‘<nginx-configuration>’ record.

     A simple example configuration is given below.

          (service nginx-service-type
                   (nginx-configuration
                     (server-blocks
                       (list (nginx-server-configuration
                               (server-name '("www.example.com"))
                               (root "/srv/http/www.example.com"))))))

     In addition to adding server blocks to the service configuration
     directly, this service can be extended by other services to add
     server blocks, as in this example:

          (simple-service 'my-extra-server nginx-service-type
                          (list (nginx-server-configuration
                                  (root "/srv/http/extra-website")
                                  (try-files (list "$uri" "$uri/index.html")))))

   At startup, ‘nginx’ has not yet read its configuration file, so it
uses a default file to log error messages.  If it fails to load its
configuration file, that is where error messages are logged.  After the
configuration file is loaded, the default error log file changes as per
configuration.  In our case, startup error messages can be found in
‘/var/run/nginx/logs/error.log’, and after configuration in
‘/var/log/nginx/error.log’.  The second location can be changed with the
LOG-DIRECTORY configuration option.

 -- Data Type: nginx-configuration
     This data type represents the configuration for NGinx.  Some
     configuration can be done through this and the other provided
     record types, or alternatively, a config file can be provided.

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

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

          This is useful if you would like ‘nginx’ to be started after a
          back-end web server or a logging service such as Anonip has
          been started.

     ‘log-directory’ (default: ‘"/var/log/nginx"’)
          The directory to which NGinx will write log files.

     ‘log-format’ (default: ‘'combined’) (type: symbol)
          Logging format for the access log.  Nginx defaults to the
          httpd-like format named ‘'combined’.  Other formats can be
          defined using ‘log-formats’.

     ‘log-formats’ (default: ‘'()’)
          A list of additional “log formats” to define, the elements
          should be of type ‘<nginx-log-format-configuration>’.

     ‘log-level’ (default: ‘'error’) (type: symbol)
          Logging level for the error log, which can be any of the
          following values: ‘'debug’, ‘'info’, ‘'notice’, ‘'warn’,
          ‘'error’, ‘'crit’, ‘'alert’, or ‘'emerg’.

     ‘run-directory’ (default: ‘"/var/run/nginx"’)
          The directory in which NGinx will create a pid file, and write
          temporary files.

     ‘server-blocks’ (default: ‘'()’)
          A list of “server blocks” to create in the generated
          configuration file, the elements should be of type
          ‘<nginx-server-configuration>’.

          The following example would setup NGinx to serve
          ‘www.example.com’ from the ‘/srv/http/www.example.com’
          directory, without using HTTPS.
               (service nginx-service-type
                        (nginx-configuration
                          (server-blocks
                            (list (nginx-server-configuration
                                    (server-name '("www.example.com"))
                                    (root "/srv/http/www.example.com"))))))

     ‘upstream-blocks’ (default: ‘'()’)
          A list of “upstream blocks” to create in the generated
          configuration file, the elements should be of type
          ‘<nginx-upstream-configuration>’.

          Configuring upstreams through the ‘upstream-blocks’ can be
          useful when combined with ‘locations’ in the
          ‘<nginx-server-configuration>’ records.  The following example
          creates a server configuration with one location
          configuration, that will proxy requests to a upstream
          configuration, which will handle requests with two servers.

               (service
                 nginx-service-type
                 (nginx-configuration
                   (server-blocks
                     (list (nginx-server-configuration
                             (server-name '("www.example.com"))
                             (root "/srv/http/www.example.com")
                             (locations
                               (list
                                 (nginx-location-configuration
                                 (uri "/path1")
                                 (body '("proxy_pass http://server-proxy;"))))))))
                   (upstream-blocks
                     (list (nginx-upstream-configuration
                             (name "server-proxy")
                             (servers (list "server1.example.com"
                                            "server2.example.com")))))))

     ‘file’ (default: ‘#f’)
          If a configuration FILE is provided, this will be used, rather
          than generating a configuration file from the provided
          ‘log-directory’, ‘run-directory’, ‘server-blocks’ and
          ‘upstream-blocks’.  For proper operation, these arguments
          should match what is in FILE to ensure that the directories
          are created when the service is activated.

          This can be useful if you have an existing configuration file,
          or it’s not possible to do what is required through the other
          parts of the nginx-configuration record.

     ‘server-names-hash-bucket-size’ (default: ‘#f’)
          Bucket size for the server names hash tables, defaults to ‘#f’
          to use the size of the processors cache line.

     ‘server-names-hash-bucket-max-size’ (default: ‘#f’)
          Maximum bucket size for the server names hash tables.

     ‘stream’ (default: ‘#f’)
          ‘<nginx-stream-configuration>’ object describing stream server
          directives.

     ‘modules’ (default: ‘'()’)
          List of nginx dynamic modules to load.  This should be a list
          of file names of loadable modules, as in this example:

               (modules
                (list
                 (file-append nginx-accept-language-module "\
               /etc/nginx/modules/ngx_http_accept_language_module.so")
                 (file-append nginx-lua-module "\
               /etc/nginx/modules/ngx_http_lua_module.so")))

     ‘lua-package-path’ (default: ‘'()’)
          List of nginx lua packages to load.  This should be a list of
          package names of loadable lua modules, as in this example:

               (lua-package-path (list lua-resty-core
                                       lua-resty-lrucache
                                       lua-resty-signal
                                       lua-tablepool
                                       lua-resty-shell))

     ‘lua-package-cpath’ (default: ‘'()’)
          List of nginx lua C packages to load.  This should be a list
          of package names of loadable lua C modules, as in this
          example:

               (lua-package-cpath (list lua-resty-signal))

     ‘global-directives’ (default: ‘'((events . ()))’)
          Association list of global directives for the top level of the
          nginx configuration.  Values may themselves be association
          lists.

               (global-directives
                `((worker_processes . 16)
                  (pcre_jit . on)
                  (events . ((worker_connections . 1024)))))

     ‘extra-content’ (default: ‘""’)
          Additional content to be appended to the ‘http’ block.  Can
          either be a value that can be lowered into a string or a list
          of such values.  In the former case, it is inserted directly.
          In the latter, it is prefixed with indentation and suffixed
          with a newline.  Nested lists are flattened into one line.

               (extra-content "include /etc/nginx/custom-config.conf;")
               (extra-content `("include /etc/nginx/custom-config.conf;"
                                ("include " ,%custom-config.conf ";")))

 -- Data Type: nginx-log-format-configuration
     Data type representing the configuration of a custom Nginx log
     format.  This type has the following parameters:

     ‘name’ (type: symbol)
          The name of the log format as a symbol.

     ‘escape’ (default: ‘'default’) (type: symbol)
          The mode used to escape values of variables in the format.
          The supported values are:

             • ‘'default’, to escape all characters outside of the ASCII
               printable range.
             • ‘'json’, to escape all characters invalid in JSON
               strings.
             • ‘'none’, to disable escaping.

     ‘format’ (type: string)
          The format as accepted by the ‘log_format’ directive.

 -- Data Type: nginx-server-configuration
     Data type representing the configuration of an nginx server block.
     This type has the following parameters:

     ‘listen’ (default: ‘'("80" "443 ssl")’)
          Each ‘listen’ directive sets the address and port for IP, or
          the path for a UNIX-domain socket on which the server will
          accept requests.  Both address and port, or only address or
          only port can be specified.  An address may also be a
          hostname, for example:

               '("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000")

     ‘server-name’ (default: ‘(list 'default)’)
          A list of server names this server represents.  ‘'default’
          represents the default server for connections matching no
          other server.

     ‘root’ (default: ‘"/srv/http"’)
          Root of the website nginx will serve.

     ‘locations’ (default: ‘'()’)
          A list of “nginx-location-configuration” or
          “nginx-named-location-configuration” records to use within
          this server block.

     ‘index’ (default: ‘(list "index.html")’)
          Index files to look for when clients ask for a directory.  If
          it cannot be found, Nginx will send the list of files in the
          directory.

     ‘try-files’ (default: ‘'()’)
          A list of files whose existence is checked in the specified
          order.  ‘nginx’ will use the first file it finds to process
          the request.

     ‘ssl-certificate’ (default: ‘#f’)
          Where to find the certificate for secure connections.  Set it
          to ‘#f’ if you don’t have a certificate or you don’t want to
          use HTTPS.

     ‘ssl-certificate-key’ (default: ‘#f’)
          Where to find the private key for secure connections.  Set it
          to ‘#f’ if you don’t have a key or you don’t want to use
          HTTPS.

     ‘server-tokens?’ (default: ‘#f’)
          Whether the server should add its configuration to response.

     ‘raw-content’ (default: ‘'()’)
          A list of strings or file-like objects to be appended to the
          server block.  Each item is prefixed with indentation and
          suffixed with a new line.  Nested lists are flattened.

 -- Data Type: nginx-upstream-configuration
     Data type representing the configuration of an nginx ‘upstream’
     block.  This type has the following parameters:

     ‘name’
          Name for this group of servers.

     ‘servers’
          Specify the addresses of the servers in the group.  The
          address can be specified as a IP address (e.g. ‘127.0.0.1’),
          domain name (e.g. ‘backend1.example.com’) or a path to a UNIX
          socket using the prefix ‘unix:’.  For addresses using an IP
          address or domain name, the default port is 80, and a
          different port can be specified explicitly.

     ‘extra-content’
          Additional content to be appended to the upstream block.  Can
          be a string or file-like object or list of thereof.  In case
          of list, each item is prefixed with indentation and suffixed
          with a new line.  Nested lists are flattened.

               (extra-content "include /etc/nginx/custom-config.conf;")
               (extra-content `("include /etc/nginx/custom-config.conf;"
                                ("include " ,%custom-config.conf ";")))

 -- Data Type: nginx-location-configuration
     Data type representing the configuration of an nginx ‘location’
     block.  This type has the following parameters:

     ‘uri’
          URI which this location block matches.

     ‘body’
          Body of the location block, specified as a list of strings or
          file-like objects.  Each item is prefixed with indentation and
          suffixed with a new line.  Nested lists are flattened.

          For example, to pass requests to a upstream server group
          defined using an ‘nginx-upstream-configuration’ block, the
          following directive would be specified in the body ‘(list
          "proxy_pass http://upstream-name;")’.

 -- Data Type: nginx-named-location-configuration
     Data type representing the configuration of an nginx named location
     block.  Named location blocks are used for request redirection, and
     not used for regular request processing.  This type has the
     following parameters:

     ‘name’
          Name to identify this location block.

     ‘body’
          *Note nginx-location-configuration body::, as the body for
          named location blocks can be used in a similar way to the
          ‘nginx-location-configuration body’.  One restriction is that
          the body of a named location block cannot contain location
          blocks.

 -- Data Type: nginx-stream-configuration
     Data type representing the configuration file context in which
     stream directives are specified.  This type has the following
     parameters:

     ‘upstream-blocks’ (default: ‘'()’)
          A list of upstream blocks to create in the generated
          configuration file, the elements should be of type
          ‘<nginx-upstream-configuration>’.

     ‘server-blocks’ (default: ‘'()’)
          A list of server blocks to create in the generated
          configuration file, the elements should be of type
          ‘<nginx-server-configuration>’.

     ‘extra-content’ (default: ‘'()’)
          Additional content to be appended to the ‘stream’ block.  Can
          either be a value that can be lowered into a string or a list
          of such values.  In the former case, it is inserted directly.
          In the latter, it is prefixed with indentation and suffixed
          with a newline.  Nested lists are flattened into one line.

Varnish Cache
.............

Varnish is a fast cache server that sits in between web applications and
end users.  It proxies requests from clients and caches the accessed
URLs such that multiple requests for the same resource only creates one
request to the back-end.

 -- Variable: varnish-service-type
     Service type for the Varnish daemon.

 -- Data Type: varnish-configuration
     Data type representing the ‘varnish’ service configuration.  This
     type has the following parameters:

     ‘package’ (default: ‘varnish’)
          The Varnish package to use.

     ‘name’ (default: ‘"default"’)
          A name for this Varnish instance.  Varnish will create a
          directory in ‘/var/varnish/’ with this name and keep temporary
          files there.  If the name starts with a forward slash, it is
          interpreted as an absolute directory name.

          Pass the ‘-n’ argument to other Varnish programs to connect to
          the named instance, e.g. ‘varnishncsa -n default’.

     ‘backend’ (default: ‘"localhost:8080"’)
          The backend to use.  This option has no effect if ‘vcl’ is
          set.

     ‘vcl’ (default: #f)
          The “VCL” (Varnish Configuration Language) program to run.  If
          this is ‘#f’, Varnish will proxy ‘backend’ using the default
          configuration.  Otherwise this must be a file-like object with
          valid VCL syntax.

          For example, to mirror www.gnu.org (https://www.gnu.org) with
          VCL you can do something along these lines:

               (define %gnu-mirror
                 (plain-file "gnu.vcl"
                             "vcl 4.1;
               backend gnu { .host = \"www.gnu.org\"; }"))

               (operating-system
                 ;; ...
                 (services (cons (service varnish-service-type
                                          (varnish-configuration
                                           (listen '(":80"))
                                           (vcl %gnu-mirror)))
                                 %base-services)))

          The configuration of an already running Varnish instance can
          be inspected and changed using the ‘varnishadm’ program.

          Consult the Varnish User Guide
          (https://varnish-cache.org/docs/) and Varnish Book
          (https://book.varnish-software.com/4.0/) for comprehensive
          documentation on Varnish and its configuration language.

     ‘listen’ (default: ‘'("localhost:80")’)
          List of addresses Varnish will listen on.

     ‘storage’ (default: ‘'("malloc,128m")’)
          List of storage backends that will be available in VCL.

     ‘parameters’ (default: ‘'()’)
          List of run-time parameters in the form ‘'(("parameter" .
          "value"))’.

     ‘extra-options’ (default: ‘'()’)
          Additional arguments to pass to the ‘varnishd’ process.

Whoogle Search
--------------

Whoogle Search (https://github.com/benbusby/whoogle-search) is a
self-hosted, ad-free, privacy-respecting meta search engine that
collects and displays Google search results.  By default, you can
configure it by adding this line to the ‘services’ field of your
operating system declaration:

     (service whoogle-service-type)

   As a result, Whoogle Search runs as local Web server, which you can
access by opening ‘http://localhost:5000’ in your browser.  The
configuration reference is given below.

 -- Variable: whoogle-service-type
     Service type for Whoogle Search.  Its value must be a
     ‘whoogle-configuration’ record—see below.

 -- Data Type: whoogle-configuration
     Data type representing Whoogle Search service configuration.

     ‘package’ (default: ‘whoogle-search’)
          The Whoogle Search package to use.

     ‘host’ (default: ‘"127.0.0.1"’)
          The host address to run Whoogle on.

     ‘port’ (default: ‘5000’)
          The port where Whoogle will be exposed.

     ‘environment-variables’ (default: ‘'()’)
          A list of strings with the environment variables to configure
          Whoogle.  You can consult its environment variables template
          (https://github.com/benbusby/whoogle-search/blob/main/whoogle.template.env)
          for the list of available options.

Patchwork
.........

Patchwork is a patch tracking system.  It can collect patches sent to a
mailing list, and display them in a web interface.

 -- Variable: patchwork-service-type
     Service type for Patchwork.

   The following example is an example of a minimal service for
Patchwork, for the ‘patchwork.example.com’ domain.

     (service patchwork-service-type
              (patchwork-configuration
               (domain "patchwork.example.com")
               (settings-module
                (patchwork-settings-module
                 (allowed-hosts (list domain))
                 (default-from-email "patchwork@patchwork.example.com")))
               (getmail-retriever-config
                (getmail-retriever-configuration
                 (type "SimpleIMAPSSLRetriever")
                 (server "imap.example.com")
                 (port 993)
                 (username "patchwork")
                 (password-command
                  (list (file-append coreutils "/bin/cat")
                        "/etc/getmail-patchwork-imap-password"))
                 (extra-parameters
                 '((mailboxes . ("Patches"))))))))


   There are three records for configuring the Patchwork service.  The
‘<patchwork-configuration>’ relates to the configuration for Patchwork
within the HTTPD service.

   The ‘settings-module’ field within the ‘<patchwork-configuration>’
record can be populated with the ‘<patchwork-settings-module>’ record,
which describes a settings module that is generated within the Guix
store.

   For the ‘database-configuration’ field within the
‘<patchwork-settings-module>’, the ‘<patchwork-database-configuration>’
must be used.

 -- Data Type: patchwork-configuration
     Data type representing the Patchwork service configuration.  This
     type has the following parameters:

     ‘patchwork’ (default: ‘patchwork’)
          The Patchwork package to use.

     ‘domain’
          The domain to use for Patchwork, this is used in the HTTPD
          service virtual host.

     ‘settings-module’
          The settings module to use for Patchwork.  As a Django
          application, Patchwork is configured with a Python module
          containing the settings.  This can either be an instance of
          the ‘<patchwork-settings-module>’ record, any other record
          that represents the settings in the store, or a directory
          outside of the store.

     ‘static-path’ (default: ‘"/static/"’)
          The path under which the HTTPD service should serve the static
          files.

     ‘getmail-retriever-config’
          The getmail-retriever-configuration record value to use with
          Patchwork.  Getmail will be configured with this value, the
          messages will be delivered to Patchwork.

 -- Data Type: patchwork-settings-module
     Data type representing a settings module for Patchwork.  Some of
     these settings relate directly to Patchwork, but others relate to
     Django, the web framework used by Patchwork, or the Django Rest
     Framework library.  This type has the following parameters:

     ‘database-configuration’ (default: ‘(patchwork-database-configuration)’)
          The database connection settings used for Patchwork.  See the
          ‘<patchwork-database-configuration>’ record type for more
          information.

     ‘secret-key-file’ (default: ‘"/etc/patchwork/django-secret-key"’)
          Patchwork, as a Django web application uses a secret key for
          cryptographically signing values.  This file should contain a
          unique unpredictable value.

          If this file does not exist, it will be created and populated
          with a random value by the patchwork-setup shepherd service.

          This setting relates to Django.

     ‘allowed-hosts’
          A list of valid hosts for this Patchwork service.  This should
          at least include the domain specified in the
          ‘<patchwork-configuration>’ record.

          This is a Django setting.

     ‘default-from-email’
          The email address from which Patchwork should send email by
          default.

          This is a Patchwork setting.

     ‘static-url’ (default: ‘#f’)
          The URL to use when serving static assets.  It can be part of
          a URL, or a full URL, but must end in a ‘/’.

          If the default value is used, the ‘static-path’ value from the
          ‘<patchwork-configuration>’ record will be used.

          This is a Django setting.

     ‘admins’ (default: ‘'()’)
          Email addresses to send the details of errors that occur.
          Each value should be a list containing two elements, the name
          and then the email address.

          This is a Django setting.

     ‘debug?’ (default: ‘#f’)
          Whether to run Patchwork in debug mode.  If set to ‘#t’,
          detailed error messages will be shown.

          This is a Django setting.

     ‘enable-rest-api?’ (default: ‘#t’)
          Whether to enable the Patchwork REST API.

          This is a Patchwork setting.

     ‘enable-xmlrpc?’ (default: ‘#t’)
          Whether to enable the XML RPC API.

          This is a Patchwork setting.

     ‘force-https-links?’ (default: ‘#t’)
          Whether to use HTTPS links on Patchwork pages.

          This is a Patchwork setting.

     ‘extra-settings’ (default: ‘""’)
          Extra code to place at the end of the Patchwork settings
          module.

 -- Data Type: patchwork-database-configuration
     Data type representing the database configuration for Patchwork.

     ‘engine’ (default: ‘"django.db.backends.postgresql_psycopg2"’)
          The database engine to use.

     ‘name’ (default: ‘"patchwork"’)
          The name of the database to use.

     ‘user’ (default: ‘"httpd"’)
          The user to connect to the database as.

     ‘password’ (default: ‘""’)
          The password to use when connecting to the database.

     ‘host’ (default: ‘""’)
          The host to make the database connection to.

     ‘port’ (default: ‘""’)
          The port on which to connect to the database.

Mumi
....

Mumi (https://codeberg.org/guix/mumi) is a Web interface to the Debbugs
bug tracker, by default for the GNU instance (https://bugs.gnu.org).
Mumi is a Web server, but it also fetches and indexes mail retrieved
from Debbugs.

 -- Variable: mumi-service-type
     This is the service type for Mumi.

 -- Data Type: mumi-configuration
     Data type representing the Mumi service configuration.  This type
     has the following fields:

     ‘mumi’ (default: ‘mumi’)
          The Mumi package to use.

     ‘data-directory’ (default: ‘"/var/mumi/data"’)
          Data directory to store Debbugs data from upstream Debbugs
          instance.

     ‘rsync-remote’
          Remote rsync path from which to download Debbugs data.  The
          remote is polled every 5 minutes, unless a previous instance
          of rsync is already running.

     ‘rsync-flags’ (default: ‘'()’)
          Additional flags to pass to ‘rsync’.

     ‘mailer?’ (default: ‘#true’)
          Whether to enable or disable the mailer component.

     ‘sender’
          The email address used as the sender for comments.

     ‘smtp’
          A URI to configure the SMTP settings for Mailutils.  This
          could be something like ‘sendmail:///path/to/bin/msmtp’ or any
          other URI supported by Mailutils.  *Note SMTP Mailboxes:
          (mailutils)SMTP Mailboxes.

     ‘packages’
          List of ‘<mumi-package-configuration>’ objects representing
          packages configured on Mumi.

 -- Data Type: mumi-package-configuration
     Data type representing the configuration of a package on Mumi.
     This type has the following fields:

     ‘name’
          Name of the package.

     ‘display-name’
          Display name used for this package in the web interface.

     ‘debbugs-packages’
          List of Debbugs packages this package refers to.

     ‘bug-email-address’
          Email address to send bug reports to.

     ‘patch-email-address’
          Email address to send patches to, if that is different from
          ‘bug-email-address’.

     ‘file-tags’
          Association list mapping tags to filename regular expressions.
          Keys are tag names, and values are lists of regular
          expressions.  For each entry of the association list, the tag
          is applied if a filename referred to in a patch matches any of
          the regular expressions.

FastCGI
.......

FastCGI is an interface between the front-end and the back-end of a web
service.  It is a somewhat legacy facility; new web services should
generally just talk HTTP between the front-end and the back-end.
However there are a number of back-end services such as PHP or the
optimized HTTP Git repository access that use FastCGI, so we have
support for it in Guix.

   To use FastCGI, you configure the front-end web server (e.g., nginx)
to dispatch some subset of its requests to the fastcgi backend, which
listens on a local TCP or UNIX socket.  There is an intermediary
‘fcgiwrap’ program that sits between the actual backend process and the
web server.  The front-end indicates which backend program to run,
passing that information to the ‘fcgiwrap’ process.

 -- Variable: fcgiwrap-service-type
     A service type for the ‘fcgiwrap’ FastCGI proxy.

 -- Data Type: fcgiwrap-configuration
     Data type representing the configuration of the ‘fcgiwrap’ service.
     This type has the following parameters:
     ‘package’ (default: ‘fcgiwrap’)
          The fcgiwrap package to use.

     ‘socket’ (default: ‘tcp:127.0.0.1:9000’)
          The socket on which the ‘fcgiwrap’ process should listen, as a
          string.  Valid SOCKET values include
          ‘unix:/PATH/TO/UNIX/SOCKET’, ‘tcp:DOT.TED.QU.AD:PORT’ and
          ‘tcp6:[IPV6_ADDR]:port’.

     ‘user’ (default: ‘fcgiwrap’)
     ‘group’ (default: ‘fcgiwrap’)
          The user and group names, as strings, under which to run the
          ‘fcgiwrap’ process.  The ‘fastcgi’ service will ensure that if
          the user asks for the specific user or group names ‘fcgiwrap’
          that the corresponding user and/or group is present on the
          system.

          It is possible to configure a FastCGI-backed web service to
          pass HTTP authentication information from the front-end to the
          back-end, and to allow ‘fcgiwrap’ to run the back-end process
          as a corresponding local user.  To enable this capability on
          the back-end, run ‘fcgiwrap’ as the ‘root’ user and group.
          Note that this capability also has to be configured on the
          front-end as well.

PHP-FPM
.......

PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI
implementation with some additional features useful for sites of any
size.

   These features include:
   • Adaptive process spawning
   • Basic statistics (similar to Apache’s mod_status)
   • Advanced process management with graceful stop/start
   • Ability to start workers with different uid/gid/chroot/environment
     and different php.ini (replaces safe_mode)
   • Stdout & stderr logging
   • Emergency restart in case of accidental opcode cache destruction
   • Accelerated upload support
   • Support for a "slowlog"
   • Enhancements to FastCGI, such as fastcgi_finish_request() - a
     special function to finish request & flush all data while
     continuing to do something time-consuming (video converting, stats
     processing, etc.)
   ... and much more.

 -- Variable: php-fpm-service-type
     A Service type for ‘php-fpm’.

 -- Data Type: php-fpm-configuration
     Data Type for php-fpm service configuration.
     ‘php’ (default: ‘php’)
          The php package to use.
     ‘socket’ (default: ‘(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")’)
          The address on which to accept FastCGI requests.  Valid
          syntaxes are:
          ‘"ip.add.re.ss:port"’
               Listen on a TCP socket to a specific address on a
               specific port.
          ‘"port"’
               Listen on a TCP socket to all addresses on a specific
               port.
          ‘"/path/to/unix/socket"’
               Listen on a unix socket.

     ‘user’ (default: ‘php-fpm’)
          User who will own the php worker processes.
     ‘group’ (default: ‘php-fpm’)
          Group of the worker processes.
     ‘socket-user’ (default: ‘php-fpm’)
          User who can speak to the php-fpm socket.
     ‘socket-group’ (default: ‘nginx’)
          Group that can speak to the php-fpm socket.
     ‘pid-file’ (default: ‘(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")’)
          The process id of the php-fpm process is written to this file
          once the service has started.
     ‘log-file’ (default: ‘(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")’)
          Log for the php-fpm master process.
     ‘process-manager’ (default: ‘(php-fpm-dynamic-process-manager-configuration)’)
          Detailed settings for the php-fpm process manager.  Must be
          one of:
          ‘<php-fpm-dynamic-process-manager-configuration>’
          ‘<php-fpm-static-process-manager-configuration>’
          ‘<php-fpm-on-demand-process-manager-configuration>’
     ‘display-errors’ (default ‘#f’)
          Determines whether php errors and warning should be sent to
          clients and displayed in their browsers.  This is useful for
          local php development, but a security risk for public sites,
          as error messages can reveal passwords and personal data.
     ‘timezone’ (default ‘#f’)
          Specifies ‘php_admin_value[date.timezone]’ parameter.
     ‘workers-logfile’ (default ‘(string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log")’)
          This file will log the ‘stderr’ outputs of php worker
          processes.  Can be set to ‘#f’ to disable logging.
     ‘file’ (default ‘#f’)
          An optional override of the whole configuration.  You can use
          the ‘mixed-text-file’ function or an absolute filepath for it.
     ‘php-ini-file’ (default ‘#f’)
          An optional override of the default php settings.  It may be
          any “file-like” object (*note file-like objects:
          G-Expressions.).  You can use the ‘mixed-text-file’ function
          or an absolute filepath for it.

          For local development it is useful to set a higher timeout and
          memory limit for spawned php processes.  This be accomplished
          with the following operating system configuration snippet:
               (define %local-php-ini
                 (plain-file "php.ini"
                             "memory_limit = 2G
               max_execution_time = 1800"))

               (operating-system
                 ;; ...
                 (services (cons (service php-fpm-service-type
                                          (php-fpm-configuration
                                           (php-ini-file %local-php-ini)))
                                 %base-services)))

          Consult the core php.ini directives
          (https://www.php.net/manual/en/ini.core.php) for comprehensive
          documentation on the acceptable ‘php.ini’ directives.

 -- Data type: php-fpm-dynamic-process-manager-configuration
     Data Type for the ‘dynamic’ php-fpm process manager.  With the
     ‘dynamic’ process manager, spare worker processes are kept around
     based on its configured limits.
     ‘max-children’ (default: ‘5’)
          Maximum of worker processes.
     ‘start-servers’ (default: ‘2’)
          How many worker processes should be started on start-up.
     ‘min-spare-servers’ (default: ‘1’)
          How many spare worker processes should be kept around at
          minimum.
     ‘max-spare-servers’ (default: ‘3’)
          How many spare worker processes should be kept around at
          maximum.

 -- Data type: php-fpm-static-process-manager-configuration
     Data Type for the ‘static’ php-fpm process manager.  With the
     ‘static’ process manager, an unchanging number of worker processes
     are created.
     ‘max-children’ (default: ‘5’)
          Maximum of worker processes.

 -- Data type: php-fpm-on-demand-process-manager-configuration
     Data Type for the ‘on-demand’ php-fpm process manager.  With the
     ‘on-demand’ process manager, worker processes are only created as
     requests arrive.
     ‘max-children’ (default: ‘5’)
          Maximum of worker processes.
     ‘process-idle-timeout’ (default: ‘10’)
          The time in seconds after which a process with no requests is
          killed.

 -- Procedure: nginx-php-location [#:nginx-package nginx] [socket
          (string-append "/var/run/php" (version-major (package-version
          php)) "-fpm.sock")]
     A helper function to quickly add php to an
     ‘nginx-server-configuration’.

   A simple services setup for nginx with php can look like this:
     (services (cons* (service dhcp-client-service-type)
                      (service php-fpm-service-type)
                      (service nginx-service-type
                               (nginx-server-configuration
                                (server-name '("example.com"))
                                (root "/srv/http/")
                                (locations
                                 (list (nginx-php-location)))
                                (listen '("80"))
                                (ssl-certificate #f)
                                (ssl-certificate-key #f)))
                      %base-services))

   The cat avatar generator is a simple service to demonstrate the use
of php-fpm in ‘Nginx’.  It is used to generate cat avatar from a seed,
for instance the hash of a user’s email address.

 -- Procedure: cat-avatar-generator-service [#:cache-dir
          "/var/cache/cat-avatar-generator"] [#:package
          cat-avatar-generator] [#:configuration
          (nginx-server-configuration)]
     Returns an nginx-server-configuration that inherits
     ‘configuration’.  It extends the nginx configuration to add a
     server block that serves ‘package’, a version of
     cat-avatar-generator.  During execution, cat-avatar-generator will
     be able to use ‘cache-dir’ as its cache directory.

   A simple setup for cat-avatar-generator can look like this:
     (services (cons* (cat-avatar-generator-service
                       #:configuration
                       (nginx-server-configuration
                         (server-name '("example.com"))))
                      ...
                      %base-services))

Hpcguix-web
...........

The hpcguix-web (https://github.com/UMCUGenetics/hpcguix-web/) program
is a customizable web interface to browse Guix packages, initially
designed for users of high-performance computing (HPC) clusters.

 -- Variable: hpcguix-web-service-type
     The service type for ‘hpcguix-web’.

 -- Data Type: hpcguix-web-configuration
     Data type for the hpcguix-web service configuration.

     ‘specs’ (default: ‘#f’)
          Either ‘#f’ or a gexp (*note G-Expressions::) specifying the
          hpcguix-web service configuration as an
          ‘hpcguix-web-configuration’ record.  The main fields of that
          record type are:

          ‘title-prefix’ (default: ‘"hpcguix | "’)
               The page title prefix.

          ‘guix-command’ (default: ‘"guix"’)
               The ‘guix’ command to use in examples that appear on HTML
               pages.

          ‘package-filter-proc’ (default: ‘(const #t)’)
               A procedure specifying how to filter packages that are
               displayed.

          ‘package-page-extension-proc’ (default: ‘(const '())’)
               Extension package for ‘hpcguix-web’.

          ‘menu’ (default: ‘'()’)
               Additional entry in page ‘menu’.

          ‘channels’ (default: ‘%default-channels’)
               List of channels from which the package list is built
               (*note Channels::).

          ‘package-list-expiration’ (default: ‘(* 12 3600)’)
               The expiration time, in seconds, after which the package
               list is rebuilt from the latest instances of the given
               channels.

          See the hpcguix-web repository for a complete example
          (https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm).

     ‘package’ (default: ‘hpcguix-web’)
          The hpcguix-web package to use.

     ‘address’ (default: ‘"127.0.0.1"’)
          The IP address to listen to.

     ‘port’ (default: ‘5000’)
          The port number to listen to.

   A typical hpcguix-web service declaration looks like this:

     (service hpcguix-web-service-type
              (hpcguix-web-configuration
               (specs
                #~(hpcweb-configuration
                   (title-prefix "Guix-HPC - ")
                   (menu '(("/about" "ABOUT")))))))

     Note: The hpcguix-web service periodically updates the package list
     it publishes by pulling channels from Git.  To that end, it needs
     to access X.509 certificates so that it can authenticate Git
     servers when communicating over HTTPS, and it assumes that
     ‘/etc/ssl/certs’ contains those certificates.

     A certificate package, ‘nss-certs’, is provided by default as part
     of ‘%base-packages’.  *note X.509 Certificates::, for more
     information on X.509 certificates.

gmnisrv
.......

The gmnisrv (https://git.sr.ht/~sircmpwn/gmnisrv) program is a simple
Gemini (https://gemini.circumlunar.space/) protocol server.

 -- Variable: gmnisrv-service-type
     This is the type of the gmnisrv service, whose value should be a
     ‘gmnisrv-configuration’ object, as in this example:

          (service gmnisrv-service-type
                   (gmnisrv-configuration
                     (config-file (local-file "./my-gmnisrv.ini"))))

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

     ‘package’ (default: GMNISRV)
          Package object of the gmnisrv server.

     ‘config-file’ (default: ‘%default-gmnisrv-config-file’)
          File-like object of the gmnisrv configuration file to use.
          The default configuration listens on port 1965 and serves
          files from ‘/srv/gemini’.  Certificates are stored in
          ‘/var/lib/gemini/certs’.  For more information, run ‘man
          gmnisrv’ and ‘man gmnisrv.ini’.

Agate
.....

The Agate (gemini://qwertqwefsday.eu/agate.gmi) (GitHub page over HTTPS
(https://github.com/mbrubeck/agate)) program is a simple Gemini
(https://gemini.circumlunar.space/) protocol server written in Rust.

 -- Variable: agate-service-type
     This is the type of the agate service, whose value should be an
     ‘agate-service-type’ object, as in this example:

          (service agate-service-type
          	 (agate-configuration
          	   (content "/srv/gemini")
          	   (certificates "/srv/gemini-certs")))

     The example above represents the minimal tweaking necessary to get
     Agate up and running.  Specifying the path to the certificate and
     key directory is always necessary, as the Gemini protocol requires
     TLS by default.

     If the specified ‘certificates’ path is writable by Agate, and
     contains no valid pre-generated key and certificate, Agate will try
     to generate them on the first start.  In this case you should pass
     at least one hostname using the ‘hostnames’ option.  If the
     specified directory is read-only, key and certificate should be
     pre-generated by the user.

     To obtain a certificate and a key in DER format, you could, for
     example, use OpenSSL, running commands similar to the following
     example:

          openssl genpkey -out key.der -outform DER -algorithm RSA \
              -pkeyopt rsa_keygen_bits:4096
          openssl req -x509 -key key.der -outform DER -days 3650 -out cert.der \
              -subj "/CN=example.com"

     Of course, you’ll have to replace example.com with your own domain
     name, and then point the Agate configuration towards the path of
     the directory with the generated key and certificate using the
     ‘certificates’ option.

 -- Data Type: agate-configuration
     Data type representing the configuration of Agate.

     ‘package’ (default: ‘agate’)
          The package object of the Agate server.

     ‘content’ (default: ‘"/srv/gemini"’)
          The directory from which Agate will serve files.

     ‘certificates’ (default: ‘"/srv/gemini-certs"’)
          Root of the certificate directory.  Must be filled in with a
          value from the user.

     ‘addresses’ (default: ‘'("[::]:1965" "0.0.0.0:1965")’)
          A list of the addresses to listen on.

     ‘hostnames’ (default: ‘'()’)
          Virtual hosts for the Gemini server.  If multiple values are
          specified, corresponding directory names should be present in
          the ‘content’ directory.  Optional.

     ‘languages’ (default: ‘#f’)
          RFC 4646 language code(s) for text/gemini documents.
          Optional.

     ‘only-tls13?’ (default: ‘#f’)
          Set to ‘#t’ to disable support for TLSv1.2.

     ‘serve-secret?’ (default: ‘#f’)
          Set to ‘#t’ to serve secret files (files/directories starting
          with a dot).

     ‘central-configuration?’ (default: ‘#f’)
          Set to ‘#t’ to look for the .meta configuration file in the
          ‘content’ root directory and will ignore ‘.meta’ files in
          other directories

     ‘ed25519?’ (default: ‘#f’)
          Set to ‘#t’ to generate keys using the Ed25519 signature
          algorithm instead of the default ECDSA.

     ‘skip-port-check?’ (default: ‘#f’)
          Set to ‘#t’ to skip URL port check even when a ‘hostname’ is
          specified.

     ‘log-ip?’ (default: ‘#t’)
          Whether or not to output IP addresses when logging.

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

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

     ‘log-file’ (default: ‘"/var/log/agate.log"’)
          The file which should store the logging output of Agate.

Miniflux
........

The Miniflux (https://miniflux.app/) is a minimalist RSS feed reader
with a web interface.

   Depending on the configuration, an initial administrator user can be
pre-created on startup.  To enable this, ‘create-admin?’ should be set
to ‘#t’, and both ‘admin-username-file’ and ‘admin-password-file’ should
point to files containing the username and password, respectively.
However, it is recommended to manually change the password to a secure
one via the web UI after the initial service startup.

 -- Variable: miniflux-service-type
     This is the type of the Miniflux service.  Its value must be a
     ‘miniflux-configuration’ record as in this example:

          (service miniflux-service-type
                   (miniflux-configuration
                    (listen-address "0.0.0.0:8080")
                    (base-url "http://my-news-source.test")
                    (create-administrator-account? #t)
                    (administrator-account-name "/var/miniflux/initial-admin-username")
                    (administrator-account-password "/var/miniflux/initial-admin-password")))

     The details of the ‘miniflux-configuration’ record type are given
     below.

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

     ‘listen-address’ (default: ‘"127.0.0.1:8080"’) (type: string)
          Address to listen on.  Use absolute path like
          ‘"/var/run/miniflux/miniflux.sock"’ for a Unix socket.

     ‘base-url’ (default: ‘"http://127.0.0.1/"’) (type: string)
          Base URL to generate HTML links and base path for cookies.

     ‘create-administrator-account?’ (default: ‘#f’) (type: boolean)
          Create an initial administrator account.

     ‘administrator-account-name’ (type: maybe-string-or-file-path)
          Initial administrator account name as a string or an absolute
          path to a file with an account name inside.

     ‘administrator-account-password’ (type: maybe-string-or-file-path)
          Initial administrator account password as a string or an
          absolute path to a file with a password inside.

     ‘run-migrations?’ (default: ‘#t’) (type: boolean)
          Run database migrations during application startup.

     ‘database-url’ (default: ‘"host=/var/run/postgresql"’) (type: string)
          PostgreSQL connection string.

     ‘user’ (default: ‘"miniflux"’) (type: string)
          User name for Postgresql and system account.

     ‘group’ (default: ‘"miniflux"’) (type: string)
          Group for the system account.

     ‘log-file’ (default: ‘"/var/log/miniflux.log"’) (type: string)
          Path to the log file.

     ‘extra-settings’ (type: maybe-list)
          Extra configuration parameters as a list of strings.


File: guix.info,  Node: High Availability Services,  Next: Certificate Services,  Prev: Web Services,  Up: Services

11.10.21 High Availability Services
-----------------------------------

The ‘(gnu services high-availability)’ module provides RabbitMQ message
broker service.

RabbitMQ
........

 -- Variable: rabbitmq-service-type
     Service type for the RabbitMQ (https://www.rabbitmq.com/) web
     server.  The value for this service type is a
     ‘<rabbitmq-configuration>’ record.

     A simple example configuration is given below.

          (service rabbitmq-service-type
                   (rabbitmq-configuration
                     (rabbitmq-configuration
                       (plugins '("rabbitmq_stream"
                                  "rabbitmq_management"
                                  "rabbitmq_prometheus")))))

   At startup, RabbitMQ broker logs its initialization messages into
‘/var/log/messages’ file.  Once running, the logging messages can be
found in a logging file of a RabbitMQ node in ‘/var/log/rabbitmq’
directory.

     Note: The default configuration of the RabbitMQ service enables the
     RabbitMQ broker to accept connections only on loopback interfaces.
     However, enabling certain plugins may open ports on all network
     interfaces.  See also RabbitMQ Port Access
     (https://www.rabbitmq.com/docs/networking#ports).

 -- Data Type: rabbitmq-configuration
     This data type represents the configuration for RabbitMQ.

     ‘rabbitmq’ (default: ‘rabbitmq’)
          The RabbitMQ package to use.

     ‘config-file’ (default: ‘%default-rabbitmq-config-file’)
          Configuration file for the RabbitMQ broker.  See also RabbitMQ
          Configuration (https://www.rabbitmq.com/docs/configure).

     ‘data-directory’ (default: ‘"/var/lib/rabbitmq/data"’)
          Directory with RabbitMQ broker data - a schema database,
          message stores, cluster member information, and other
          persistent node state.

     ‘plugins’ (default: ‘'()’)
          A list of RabbitMQ plugins to enable.  View all available
          plugins using the ‘rabbitmq-plugins list’ command.


File: guix.info,  Node: Certificate Services,  Next: DNS Services,  Prev: High Availability Services,  Up: Services

11.10.22 Certificate Services
-----------------------------

The ‘(gnu services certbot)’ module provides a service to automatically
obtain a valid TLS certificate from the Let’s Encrypt certificate
authority.  These certificates can then be used to serve content
securely over HTTPS or other TLS-based protocols, with the knowledge
that the client will be able to verify the server’s authenticity.

   Let’s Encrypt (https://letsencrypt.org/) provides the ‘certbot’ tool
to automate the certification process.  This tool first securely
generates a key on the server.  It then makes a request to the Let’s
Encrypt certificate authority (CA) to sign the key.  The CA checks that
the request originates from the host in question by using a
challenge-response protocol, requiring the server to provide its
response over HTTP.  If that protocol completes successfully, the CA
signs the key, resulting in a certificate.  That certificate is valid
for a limited period of time, and therefore to continue to provide TLS
services, the server needs to periodically ask the CA to renew its
signature.

   The certbot service automates this process: the initial key
generation, the initial certification request to the Let’s Encrypt
service, the web server challenge/response integration, writing the
certificate to disk, the automated periodic renewals, and the deployment
tasks associated with the renewal (e.g. reloading services, copying keys
with different permissions).

   Certbot is run twice a day, at a random minute within the hour.  It
won’t do anything until your certificates are due for renewal or
revoked, but running it regularly would give your service a chance of
staying online in case a Let’s Encrypt-initiated revocation happened for
some reason.

   By using this service, you agree to the ACME Subscriber Agreement,
which can be found there:
<https://acme-v02.api.letsencrypt.org/directory>.

 -- Variable: certbot-service-type
     A service type for the ‘certbot’ Let’s Encrypt client.  Its value
     must be a ‘certbot-configuration’ record as in this example:

          (service certbot-service-type
                   (certbot-configuration
                    (email "foo@example.net")
                    (certificates
                     (list
                      (certificate-configuration
                       (domains '("example.net" "www.example.net")))
                      (certificate-configuration
                       (domains '("bar.example.net")))))))

     See below for details about ‘certbot-configuration’.

 -- Data Type: certbot-configuration
     Data type representing the configuration of the ‘certbot’ service.
     This type has the following parameters:

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

     ‘webroot’ (default: ‘/var/www’)
          The directory from which to serve the Let’s Encrypt
          challenge/response files.

     ‘certificates’ (default: ‘'()’)
          A list of ‘certificates-configuration’s for which to generate
          certificates and request signatures.  Each certificate has a
          ‘name’ and several ‘domains’.

     ‘email’ (default: ‘#f’)
          Optional email address used for registration and recovery
          contact.  Setting this is encouraged as it allows you to
          receive important notifications about the account and issued
          certificates.

     ‘server’ (default: ‘#f’)
          Optional URL of ACME server.  Setting this overrides certbot’s
          default, which is the Let’s Encrypt server.

     ‘rsa-key-size’ (default: ‘2048’)
          Size of the RSA key.

     ‘default-location’ (default: see below)
          The default ‘nginx-location-configuration’.  Because ‘certbot’
          needs to be able to serve challenges and responses, it needs
          to be able to run a web server.  It does so by extending the
          ‘nginx’ web service with an ‘nginx-server-configuration’
          listening on the DOMAINS on port 80, and which has a
          ‘nginx-location-configuration’ for the ‘/.well-known/’ URI
          path subspace used by Let’s Encrypt.  *Note Web Services::,
          for more on these nginx configuration data types.

          Requests to other URL paths will be matched by the
          ‘default-location’, which if present is added to all
          ‘nginx-server-configuration’s.

          By default, the ‘default-location’ will issue a redirect from
          ‘http://DOMAIN/...’ to ‘https://DOMAIN/...’, leaving you to
          define what to serve on your site via ‘https’.

          Pass ‘#f’ to not issue a default location.

 -- Data Type: certificate-configuration
     Data type representing the configuration of a certificate.  This
     type has the following parameters:

     ‘name’ (default: see below)
          This name is used by Certbot for housekeeping and in file
          paths; it doesn’t affect the content of the certificate
          itself.  To see certificate names, run ‘certbot certificates’.

          Its default is the first provided domain.

     ‘domains’ (default: ‘'()’)
          The first domain provided will be the subject CN of the
          certificate, and all domains will be Subject Alternative Names
          on the certificate.

     ‘challenge’ (default: ‘#f’)
          The challenge type that has to be run by certbot.  If ‘#f’ is
          specified, default to the HTTP challenge.  If a value is
          specified, defaults to the manual plugin (see
          ‘authentication-hook’, ‘cleanup-hook’ and the documentation at
          <https://certbot.eff.org/docs/using.html#hooks>), and gives
          Let’s Encrypt permission to log the public IP address of the
          requesting machine.

     ‘csr’ (default: ‘#f’)
          File name of Certificate Signing Request (CSR) in DER or PEM
          format.  If ‘#f’ is specified, this argument will not be
          passed to certbot.  If a value is specified, certbot will use
          it to obtain a certificate, instead of using a self-generated
          CSR. The domain-name(s) mentioned in ‘domains’, must be
          consistent with the domain-name(s) mentioned in CSR file.

     ‘authentication-hook’ (default: ‘#f’)
          Command to be run in a shell once for each certificate
          challenge to be answered.  For this command, the shell
          variable ‘$CERTBOT_DOMAIN’ will contain the domain being
          authenticated, ‘$CERTBOT_VALIDATION’ contains the validation
          string and ‘$CERTBOT_TOKEN’ contains the file name of the
          resource requested when performing an HTTP-01 challenge.

     ‘cleanup-hook’ (default: ‘#f’)
          Command to be run in a shell once for each certificate
          challenge that have been answered by the
          ‘authentication-hook’.  For this command, the shell variables
          available in the ‘authentication-hook’ script are still
          available, and additionally ‘$CERTBOT_AUTH_OUTPUT’ will
          contain the standard output of the ‘authentication-hook’
          script.

     ‘deploy-hook’ (default: ‘#f’)
          Command to be run in a shell once for each successfully issued
          certificate.  For this command, the shell variable
          ‘$RENEWED_LINEAGE’ will point to the config live subdirectory
          (for example, ‘"/etc/letsencrypt/live/example.com"’)
          containing the new certificates and keys; the shell variable
          ‘$RENEWED_DOMAINS’ will contain a space-delimited list of
          renewed certificate domains (for example, ‘"example.com
          www.example.com"’.

     ‘dry-run?’ (default: ‘#f’)
          Communicate with the ACME server but do not update
          certificates nor trigger ‘deploy-hook’.  This is useful as a
          temporary setting to test the challenge procedure, especially
          the ‘authentication-hook’ and ‘cleanup-hook’ while working on
          them.  It’s also a good idea to use the Let’s Encrypt staging
          server at
          <https://acme-staging-v02.api.letsencrypt.org/directory> while
          testing, which allows for higher rate limits, but with which
          ‘certbot’ will helpfully refuse to update certificates and
          recommend the ‘dry-run?’ option.  For example:

               (define %authentication-hook
                 (program-file "authentication-hook"
                   #~(let ((domain (getenv "CERTBOT_DOMAIN"))
                           (token (getenv "CERTBOT_TOKEN")))
                       (format #t "Hey, can you authenticate ~a with ~a for me?"
                               domain token))))

               (define %cleanup-hook
                 (program-file "authentication-hook"
                   #~(display "Bye")))

               (service certbot-service-type
                        (certbot-configuration
                         (server "https://acme-staging-v02.api.letsencrypt.org/directory")
                         (certificates
                          (list
                           (certificate-configuration
                             (dry-run? #t)
                             (authentication-hook %authentication-hook)
                             (cleanup-hook %cleanup-hook)
                             (domains '("example.net" "www.example.net")))))))

     ‘start-self-signed?’ (default: ‘#t’)
          Whether to generate an initial self-signed certificate during
          system activation.  This option is particularly useful to
          allow ‘nginx’ to start before ‘certbot’ has run, because
          ‘certbot’ relies on ‘nginx’ running to perform HTTP
          challenges.

   For each ‘certificate-configuration’, the certificate is saved to
‘/etc/certs/NAME/fullchain.pem’ and the key is saved to
‘/etc/certs/NAME/privkey.pem’.


File: guix.info,  Node: DNS Services,  Next: VNC Services,  Prev: Certificate Services,  Up: Services

11.10.23 DNS Services
---------------------

The ‘(gnu services dns)’ module provides services related to the “domain
name system” (DNS). It provides a server service for hosting an
_authoritative_ DNS server for multiple zones, slave or master.  This
service uses Knot DNS (https://www.knot-dns.cz/).  And also a caching
and forwarding DNS server for the LAN, which uses dnsmasq
(http://www.thekelleys.org.uk/dnsmasq/doc.html).

Knot Service
............

An example configuration of an authoritative server for two zones, one
master and one slave, is:

     (define-zone-entries example.org.zone
     ;; Name TTL Class Type Data
       ("@"  ""  "IN"  "A"  "127.0.0.1")
       ("@"  ""  "IN"  "NS" "ns")
       ("ns" ""  "IN"  "A"  "127.0.0.1"))

     (define master-zone
       (knot-zone-configuration
         (domain "example.org")
         (zone (zone-file
                 (origin "example.org")
                 (entries example.org.zone)))))

     (define slave-zone
       (knot-zone-configuration
         (domain "plop.org")
         (dnssec-policy "default")
         (master (list "plop-master"))))

     (define plop-master
       (knot-remote-configuration
         (id "plop-master")
         (address (list "208.76.58.171"))))

     (operating-system
       ;; ...
       (services (cons* (service knot-service-type
                          (knot-configuration
                            (remotes (list plop-master))
                            (zones (list master-zone slave-zone))))
                        ;; ...
                        %base-services)))

 -- Variable: knot-service-type
     This is the type for the Knot DNS server.

     Knot DNS is an authoritative DNS server, meaning that it can serve
     multiple zones, that is to say domain names you would buy from a
     registrar.  This server is not a resolver, meaning that it can only
     resolve names for which it is authoritative.  This server can be
     configured to serve zones as a master server or a slave server as a
     per-zone basis.  Slave zones will get their data from masters, and
     will serve it as an authoritative server.  From the point of view
     of a resolver, there is no difference between master and slave.

     The following data types are used to configure the Knot DNS server:

 -- Data Type: knot-key-configuration
     Data type representing a key.  This type has the following
     parameters:

     ‘id’ (default: ‘""’)
          An identifier for other configuration fields to refer to this
          key.  IDs must be unique and must not be empty.

     ‘algorithm’ (default: ‘#f’)
          The algorithm to use.  Choose between ‘#f’, ‘'hmac-md5’,
          ‘'hmac-sha1’, ‘'hmac-sha224’, ‘'hmac-sha256’, ‘'hmac-sha384’
          and ‘'hmac-sha512’.

     ‘secret’ (default: ‘""’)
          The secret key itself.

 -- Data Type: knot-acl-configuration
     Data type representing an Access Control List (ACL) configuration.
     This type has the following parameters:

     ‘id’ (default: ‘""’)
          An identifier for other configuration fields to refer to this
          key.  IDs must be unique and must not be empty.

     ‘address’ (default: ‘'()’)
          An ordered list of IP addresses, network subnets, or network
          ranges represented with strings.  The query must match one of
          them.  Empty value means that address match is not required.

     ‘key’ (default: ‘'()’)
          An ordered list of references to keys represented with
          strings.  The string must match a key ID defined in a
          ‘knot-key-configuration’.  No key means that a key is not
          require to match that ACL.

     ‘action’ (default: ‘'()’)
          An ordered list of actions that are permitted or forbidden by
          this ACL.  Possible values are lists of zero or more elements
          from ‘'transfer’, ‘'notify’ and ‘'update’.

     ‘deny?’ (default: ‘#f’)
          When true, the ACL defines restrictions.  Listed actions are
          forbidden.  When false, listed actions are allowed.

 -- Data Type: zone-entry
     Data type representing a record entry in a zone file.  This type
     has the following parameters:

     ‘name’ (default: ‘"@"’)
          The name of the record.  ‘"@"’ refers to the origin of the
          zone.  Names are relative to the origin of the zone.  For
          example, in the ‘example.org’ zone, ‘"ns.example.org"’
          actually refers to ‘ns.example.org.example.org’.  Names ending
          with a dot are absolute, which means that ‘"ns.example.org."’
          refers to ‘ns.example.org’.

     ‘ttl’ (default: ‘""’)
          The Time-To-Live (TTL) of this record.  If not set, the
          default TTL is used.

     ‘class’ (default: ‘"IN"’)
          The class of the record.  Knot currently supports only ‘"IN"’
          and partially ‘"CH"’.

     ‘type’ (default: ‘"A"’)
          The type of the record.  Common types include A (IPv4
          address), AAAA (IPv6 address), NS (Name Server) and MX (Mail
          eXchange).  Many other types are defined.

     ‘data’ (default: ‘""’)
          The data contained in the record.  For instance an IP address
          associated with an A record, or a domain name associated with
          an NS record.  Remember that domain names are relative to the
          origin unless they end with a dot.

 -- Data Type: zone-file
     Data type representing the content of a zone file.  This type has
     the following parameters:

     ‘entries’ (default: ‘'()’)
          The list of entries.  The SOA record is taken care of, so you
          don’t need to put it in the list of entries.  This list should
          probably contain an entry for your primary authoritative DNS
          server.  Other than using a list of entries directly, you can
          use ‘define-zone-entries’ to define a object containing the
          list of entries more easily, that you can later pass to the
          ‘entries’ field of the ‘zone-file’.

     ‘origin’ (default: ‘""’)
          The name of your zone.  This parameter cannot be empty.

     ‘ns’ (default: ‘"ns"’)
          The domain of your primary authoritative DNS server.  The name
          is relative to the origin, unless it ends with a dot.  It is
          mandatory that this primary DNS server corresponds to an NS
          record in the zone and that it is associated to an IP address
          in the list of entries.

     ‘mail’ (default: ‘"hostmaster"’)
          An email address people can contact you at, as the owner of
          the zone.  This is translated as ‘<mail>@<origin>’.

     ‘serial’ (default: ‘1’)
          The serial number of the zone.  As this is used to keep track
          of changes by both slaves and resolvers, it is mandatory that
          it _never_ decreases.  Always increment it when you make a
          change in your zone.

     ‘refresh’ (default: ‘(* 2 24 3600)’)
          The frequency at which slaves will do a zone transfer.  This
          value is a number of seconds.  It can be computed by
          multiplications or with ‘(string->duration)’.

     ‘retry’ (default: ‘(* 15 60)’)
          The period after which a slave will retry to contact its
          master when it fails to do so a first time.

     ‘expiry’ (default: ‘(* 14 24 3600)’)
          Default TTL of records.  Existing records are considered
          correct for at most this amount of time.  After this period,
          resolvers will invalidate their cache and check again that it
          still exists.

     ‘nx’ (default: ‘3600’)
          Default TTL of inexistent records.  This delay is usually
          short because you want your new domains to reach everyone
          quickly.

 -- Data Type: knot-remote-configuration
     Data type representing a remote configuration.  This type has the
     following parameters:

     ‘id’ (default: ‘""’)
          An identifier for other configuration fields to refer to this
          remote.  IDs must be unique and must not be empty.

     ‘address’ (default: ‘'()’)
          An ordered list of destination IP addresses.  Addresses are
          tried in sequence.  An optional port can be given with the @
          separator.  For instance: ‘(list "1.2.3.4" "2.3.4.5@53")’.
          Default port is 53.

     ‘via’ (default: ‘'()’)
          An ordered list of source IP addresses.  An empty list will
          have Knot choose an appropriate source IP.  An optional port
          can be given with the @ separator.  The default is to choose
          at random.

     ‘key’ (default: ‘#f’)
          A reference to a key, that is a string containing the
          identifier of a key defined in a ‘knot-key-configuration’
          field.

 -- Data Type: knot-keystore-configuration
     Data type representing a keystore to hold dnssec keys.  This type
     has the following parameters:

     ‘id’ (default: ‘""’)
          The id of the keystore.  It must not be empty.

     ‘backend’ (default: ‘'pem’)
          The backend to store the keys in.  Can be ‘'pem’ or ‘'pkcs11’.

     ‘config’ (default: ‘"/var/lib/knot/keys/keys"’)
          The configuration string of the backend.  An example for the
          PKCS#11 is: ‘"pkcs11:token=knot;pin-value=1234
          /gnu/store/.../lib/pkcs11/libsofthsm2.so"’.  For the pem
          backend, the string represents a path in the file system.

 -- Data Type: knot-policy-configuration
     Data type representing a dnssec policy.  Knot DNS is able to
     automatically sign your zones.  It can either generate and manage
     your keys automatically or use keys that you generate.

     Dnssec is usually implemented using two keys: a Key Signing Key
     (KSK) that is used to sign the second, and a Zone Signing Key (ZSK)
     that is used to sign the zone.  In order to be trusted, the KSK
     needs to be present in the parent zone (usually a top-level
     domain).  If your registrar supports dnssec, you will have to send
     them your KSK’s hash so they can add a DS record in their zone.
     This is not automated and need to be done each time you change your
     KSK.

     The policy also defines the lifetime of keys.  Usually, ZSK can be
     changed easily and use weaker cryptographic functions (they use
     lower parameters) in order to sign records quickly, so they are
     changed often.  The KSK however requires manual interaction with
     the registrar, so they are changed less often and use stronger
     parameters because they sign only one record.

     This type has the following parameters:

     ‘id’ (default: ‘""’)
          The id of the policy.  It must not be empty.

     ‘keystore’ (default: ‘"default"’)
          A reference to a keystore, that is a string containing the
          identifier of a keystore defined in a
          ‘knot-keystore-configuration’ field.  The ‘"default"’
          identifier means the default keystore (a kasp database that
          was setup by this service).

     ‘manual?’ (default: ‘#f’)
          Whether the key management is manual or automatic.

     ‘single-type-signing?’ (default: ‘#f’)
          When ‘#t’, use the Single-Type Signing Scheme.

     ‘algorithm’ (default: ‘"ecdsap256sha256"’)
          An algorithm of signing keys and issued signatures.

     ‘ksk-size’ (default: ‘256’)
          The length of the KSK.  Note that this value is correct for
          the default algorithm, but would be unsecure for other
          algorithms.

     ‘zsk-size’ (default: ‘256’)
          The length of the ZSK.  Note that this value is correct for
          the default algorithm, but would be unsecure for other
          algorithms.

     ‘dnskey-ttl’ (default: ‘'default’)
          The TTL value for DNSKEY records added into zone apex.  The
          special ‘'default’ value means same as the zone SOA TTL.

     ‘zsk-lifetime’ (default: ‘(* 30 24 3600)’)
          The period between ZSK publication and the next rollover
          initiation.

     ‘propagation-delay’ (default: ‘(* 24 3600)’)
          An extra delay added for each key rollover step.  This value
          should be high enough to cover propagation of data from the
          master server to all slaves.

     ‘rrsig-lifetime’ (default: ‘(* 14 24 3600)’)
          A validity period of newly issued signatures.

     ‘rrsig-refresh’ (default: ‘(* 7 24 3600)’)
          A period how long before a signature expiration the signature
          will be refreshed.

     ‘nsec3?’ (default: ‘#f’)
          When ‘#t’, NSEC3 will be used instead of NSEC.

     ‘nsec3-iterations’ (default: ‘5’)
          The number of additional times the hashing is performed.

     ‘nsec3-salt-length’ (default: ‘8’)
          The length of a salt field in octets, which is appended to the
          original owner name before hashing.

     ‘nsec3-salt-lifetime’ (default: ‘(* 30 24 3600)’)
          The validity period of newly issued salt field.

 -- Data Type: knot-zone-configuration
     Data type representing a zone served by Knot.  This type has the
     following parameters:

     ‘domain’ (default: ‘""’)
          The domain served by this configuration.  It must not be
          empty.

     ‘file’ (default: ‘""’)
          The file where this zone is saved.  This parameter is ignored
          by master zones.  Empty means default location that depends on
          the domain name.

     ‘zone’ (default: ‘(zone-file)’)
          The content of the zone file.  This parameter is ignored by
          slave zones.  It must contain a zone-file record.

     ‘master’ (default: ‘'()’)
          A list of master remotes.  When empty, this zone is a master.
          When set, this zone is a slave.  This is a list of remotes
          identifiers.

     ‘ddns-master’ (default: ‘#f’)
          The main master.  When empty, it defaults to the first master
          in the list of masters.

     ‘notify’ (default: ‘'()’)
          A list of slave remote identifiers.

     ‘acl’ (default: ‘'()’)
          A list of acl identifiers.

     ‘semantic-checks?’ (default: ‘#f’)
          When set, this adds more semantic checks to the zone.

     ‘zonefile-sync’ (default: ‘0’)
          The delay between a modification in memory and on disk.  0
          means immediate synchronization.

     ‘zonefile-load’ (default: ‘#f’)
          The way the zone file contents are applied during zone load.
          Possible values are:

             • ‘#f’ for using the default value from Knot,
             • ‘'none’ for not using the zone file at all,
             • ‘'difference’ for computing the difference between
               already available contents and zone contents and applying
               it to the current zone contents,
             • ‘'difference-no-serial’ for the same as ‘'difference’,
               but ignoring the SOA serial in the zone file, while the
               server takes care of it automatically.
             • ‘'whole’ for loading zone contents from the zone file.

     ‘journal-content’ (default: ‘#f’)
          The way the journal is used to store zone and its changes.
          Possible values are ‘'none’ to not use it at all, ‘'changes’
          to store changes and ‘'all’ to store contents.  ‘#f’ does not
          set this option, so the default value from Knot is used.

     ‘max-journal-usage’ (default: ‘#f’)
          The maximum size for the journal on disk.  ‘#f’ does not set
          this option, so the default value from Knot is used.

     ‘max-journal-depth’ (default: ‘#f’)
          The maximum size of the history.  ‘#f’ does not set this
          option, so the default value from Knot is used.

     ‘max-zone-size’ (default: ‘#f’)
          The maximum size of the zone file.  This limit is enforced for
          incoming transfer and updates.  ‘#f’ does not set this option,
          so the default value from Knot is used.

     ‘dnssec-policy’ (default: ‘#f’)
          A reference to a ‘knot-policy-configuration’ record, or the
          special name ‘"default"’.  If the value is ‘#f’, there is no
          dnssec signing on this zone.

     ‘serial-policy’ (default: ‘'increment’)
          A policy between ‘'increment’ and ‘'unixtime’.

 -- Data Type: knot-configuration
     Data type representing the Knot configuration.  This type has the
     following parameters:

     ‘knot’ (default: ‘knot’)
          The Knot package.

     ‘run-directory’ (default: ‘"/var/run/knot"’)
          The run directory.  This directory will be used for pid file
          and sockets.

     ‘includes’ (default: ‘'()’)
          A list of strings or file-like objects denoting other files
          that must be included at the top of the configuration file.

          This can be used to manage secrets out-of-band.  For example,
          secret keys may be stored in an out-of-band file not managed
          by Guix, and thus not visible in ‘/gnu/store’—e.g., you could
          store secret key configuration in ‘/etc/knot/secrets.conf’ and
          add this file to the ‘includes’ list.

          One can generate a secret tsig key (for nsupdate and zone
          transfers with the keymgr command from the knot package.  Note
          that the package is not automatically installed by the
          service.  The following example shows how to generate a new
          tsig key:

               keymgr -t mysecret > /etc/knot/secrets.conf
               chmod 600 /etc/knot/secrets.conf

          Also note that the generated key will be named MYSECRET, so it
          is the name that needs to be used in the KEY field of the
          ‘knot-acl-configuration’ record and in other places that need
          to refer to that key.

          It can also be used to add configuration not supported by this
          interface.

     ‘listen-v4’ (default: ‘"0.0.0.0"’)
          An ip address on which to listen.

     ‘listen-v6’ (default: ‘"::"’)
          An ip address on which to listen.

     ‘listen-port’ (default: ‘53’)
          A port on which to listen.

     ‘keys’ (default: ‘'()’)
          The list of knot-key-configuration used by this configuration.

     ‘acls’ (default: ‘'()’)
          The list of knot-acl-configuration used by this configuration.

     ‘remotes’ (default: ‘'()’)
          The list of knot-remote-configuration used by this
          configuration.

     ‘zones’ (default: ‘'()’)
          The list of knot-zone-configuration used by this
          configuration.

Knot Resolver Service
.....................

 -- Variable: knot-resolver-service-type
     This is the type of the knot resolver service, whose value should
     be a ‘knot-resolver-configuration’ object as in this example:

          (service knot-resolver-service-type
                   (knot-resolver-configuration
                     (kresd-config-file (plain-file "kresd.conf" "
          net.listen('192.168.0.1', 5353)
          user('knot-resolver', 'knot-resolver')
          modules = { 'hints > iterate', 'stats', 'predict' }
          cache.size = 100 * MB
          "))))

     For more information, refer its manual
     (https://knot-resolver.readthedocs.io/en/stable/config-overview.html).

 -- Data Type: knot-resolver-configuration
     Data type representing the configuration of knot-resolver.

     ‘package’ (default: KNOT-RESOLVER)
          Package object of the knot DNS resolver.

     ‘kresd-config-file’ (default: %kresd.conf)
          File-like object of the kresd configuration file to use, by
          default it will listen on ‘127.0.0.1’ and ‘::1’.

     ‘garbage-collection-interval’ (default: 1000)
          Number of milliseconds for ‘kres-cache-gc’ to periodically
          trim the cache.

Dnsmasq Service
...............

 -- Variable: dnsmasq-service-type
     This is the type of the dnsmasq service, whose value should be a
     ‘dnsmasq-configuration’ object as in this example:

          (service dnsmasq-service-type
                   (dnsmasq-configuration
                     (no-resolv? #t)
                     (servers '("192.168.1.1"))))

     ‘dnsmasq-service-type’ provides two actions:

     ‘reload’
          Send a ‘SIGHUP’ signal to ‘dnsmasq’ to clear cache and reload
          hosts files which triggers the following actions:

             • Clear the DNS cache
             • Reload ‘/etc/hosts’ and ‘/etc/ethers’
             • Reload files specified by ‘--dhcp-hostsfile’,
               ‘--dhcp-hostsdir’, ‘--dhcp-optsfile’, ‘--dhcp-optsdir’,
               ‘--addn-hosts’, or ‘--hostsdir’
             • Execute DHCP lease change scripts for all existing leases
             • Reread ‘/etc/resolv.conf’ (only if ‘--no-poll’ is
               configured).

               Note: The ‘SIGHUP’ signal does not trigger a reload of
               the main configuration file.

          Example usage:
               herd reload dnsmasq

     ‘stats’
          When ‘dnsmasq’ receives a ‘SIGUSR1’ signal, it writes
          statistics to the system log including:

             • Cache size and number of evicted entries
             • Cache hits, misses, and authoritative queries answered
             • For each upstream server: queries sent and errors
               received
             • TCP connection fork statistics.

          Example usage:
               herd stats dnsmasq

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

     ‘package’ (default: DNSMASQ)
          Package object of the dnsmasq server.

     ‘shepherd-provision’ (default: ‘'(dnsmasq)’)
     ‘shepherd-requirement’ (default: ‘'(user-processes networking)’)
          This option can be used to provide a list of Shepherd service
          names (symbols) provided by this service.  You might want to
          change the default value if you intend to run several
          ‘dnsmasq’ instances.

          Likewise, ‘shepherd-requirement’ is a list of Shepherd service
          names (symbols) that this service will depend on.

     ‘pid-file’ (default: ‘"/run/dnsmasq.pid"’)
          Specify an alternate path for dnsmasq to record its process-id
          in.

     ‘no-hosts?’ (default: ‘#f’)
          When true, don’t read the hostnames in /etc/hosts.

     ‘port’ (default: ‘53’)
          The port to listen on.  Setting this to zero completely
          disables DNS responses, leaving only DHCP and/or TFTP
          functions.

     ‘local-service?’ (default: ‘#t’)
          Accept DNS queries only from hosts whose address is on a local
          subnet, ie a subnet for which an interface exists on the
          server.

     ‘listen-addresses’ (default: ‘'()’)
          Listen on the given IP addresses.

     ‘resolv-file’ (default: ‘"/etc/resolv.conf"’)
          The file to read the IP address of the upstream nameservers
          from.

     ‘no-resolv?’ (default: ‘#f’)
          When true, don’t read RESOLV-FILE.

     ‘forward-private-reverse-lookup?’ (default: ‘#t’)
          When false, all reverse lookups for private IP ranges are
          answered with "no such domain" rather than being forwarded
          upstream.

     ‘query-servers-in-order?’ (default: ‘#f’)
          When true, dnsmasq queries the servers in the same order as
          they appear in SERVERS.

     ‘servers’ (default: ‘'()’)
          Specify IP address of upstream servers directly.

     ‘servers-file’ (default: ‘#f’)
          Specify file containing upstream servers.  This file is
          re-read when dnsmasq receives SIGHUP. Could be either a string
          or a file-like object.

     ‘addresses’ (default: ‘'()’)
          For each entry, specify an IP address to return for any host
          in the given domains.  Queries in the domains are never
          forwarded and always replied to with the specified IP address.

          This is useful for redirecting hosts locally, for example:

               (service dnsmasq-service-type
                        (dnsmasq-configuration
                          (addresses
                            '(; Redirect to a local web-server.
                              "/example.org/127.0.0.1"
                              ; Redirect subdomain to a specific IP.
                              "/subdomain.example.org/192.168.1.42"))))

          Note that rules in ‘/etc/hosts’ take precedence over this.

     ‘cache-size’ (default: ‘150’)
          Set the size of dnsmasq’s cache.  Setting the cache size to
          zero disables caching.

     ‘negative-cache?’ (default: ‘#t’)
          When false, disable negative caching.

     ‘cpe-id’ (default: ‘#f’)
          If set, add a CPE (Customer-Premises Equipment) identifier to
          DNS queries which are forwarded upstream.

     ‘tftp-enable?’ (default: ‘#f’)
          Whether to enable the built-in TFTP server.

     ‘tftp-no-fail?’ (default: ‘#f’)
          If true, does not fail dnsmasq if the TFTP server could not
          start up.

     ‘tftp-single-port?’ (default: ‘#f’)
          Whether to use only one single port for TFTP.

     ‘tftp-secure?’ (default: ‘#f’)
          If true, only files owned by the user running the dnsmasq
          process are accessible.

          If dnsmasq is being run as root, different rules apply:
          ‘tftp-secure?’ has no effect, but only files which have the
          world-readable bit set are accessible.

     ‘tftp-max’ (default: ‘#f’)
          If set, sets the maximal number of concurrent connections
          allowed.

     ‘tftp-mtu’ (default: ‘#f’)
          If set, sets the MTU for TFTP packets to that value.

     ‘tftp-no-blocksize?’ (default: ‘#f’)
          If true, stops the TFTP server from negotiating the blocksize
          with a client.

     ‘tftp-lowercase?’ (default: ‘#f’)
          Whether to convert all filenames in TFTP requests to
          lowercase.

     ‘tftp-port-range’ (default: ‘#f’)
          If set, fixes the dynamical ports (one per client) to the
          given range (‘"<start>,<end>"’).

     ‘tftp-root’ (default: ‘/var/empty,lo’)
          Look for files to transfer using TFTP relative to the given
          directory.  When this is set, TFTP paths which include ‘..’
          are rejected, to stop clients getting outside the specified
          root.  Absolute paths (starting with ‘/’) are allowed, but
          they must be within the TFTP-root.  If the optional interface
          argument is given, the directory is only used for TFTP
          requests via that interface.

     ‘tftp-unique-root’ (default: ‘#f’)
          If set, add the IP or hardware address of the TFTP client as a
          path component on the end of the TFTP-root.  Only valid if a
          TFTP root is set and the directory exists.  Defaults to adding
          IP address (in standard dotted-quad format).

          For instance, if ‘--tftp-root’ is ‘/tftp’ and client ‘1.2.3.4’
          requests file ‘myfile’ then the effective path will be
          ‘/tftp/1.2.3.4/myfile’ if ‘/tftp/1.2.3.4’ exists or
          ‘/tftp/myfile’ otherwise.  When ‘=mac’ is specified it will
          append the MAC address instead, using lowercase zero padded
          digits separated by dashes, e.g.: ‘01-02-03-04-aa-bb’.  Note
          that resolving MAC addresses is only possible if the client is
          in the local network or obtained a DHCP lease from dnsmasq.

     ‘conf-file’ (default: ‘'()’)
          File names of configuration files to use.  Strings and
          file-like objects are accepted.

     ‘conf-dir’ (default: ‘#f’)
          Read all the files in the given directory as configuration
          files.  Support for ‘dnsmasq’ field extensions is not
          implemented; users can use ‘computed-file’ to build a
          directory of files instead.  The configuration files are
          loaded in alphabetical order of file name.

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

Unbound Service
...............

 -- Variable: unbound-service-type
     This is the type of the service to run Unbound
     (https://www.unbound.net), a validating, recursive, and caching DNS
     resolver.  Its value must be a ‘unbound-configuration’ object as in
     this example:

          (service unbound-service-type
                   (unbound-configuration
                    (forward-zone
                     (list
                      (unbound-zone
                       (name ".")
                       (forward-addr '("149.112.112.112#dns.quad9.net"
                                       "2620:fe::9#dns.quad9.net"))
                       (forward-tls-upstream #t))))))

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

     ‘server’ (type: unbound-server)
          General options for the Unbound server.

     ‘remote-control’ (type: unbound-remote)
          Remote control options for the daemon.

     ‘forward-zone’ (default: ‘()’) (type: list-of-unbound-zone)
          A zone for which queries should be forwarded to another
          resolver.

     ‘extra-content’ (type: maybe-string)
          Raw content to add to the configuration file.

 -- Data Type: unbound-server
     Available ‘unbound-server’ fields are:

     ‘interface’ (type: maybe-list-of-strings)
          Interfaces listened on for queries from clients.

     ‘hide-version’ (type: maybe-boolean)
          Refuse the version.server and version.bind queries.

     ‘hide-identity’ (type: maybe-boolean)
          Refuse the id.server and hostname.bind queries.

     ‘tls-cert-bundle’ (type: maybe-string)
          Certificate bundle file, used for DNS over TLS.

     ‘extra-options’ (default: ‘()’) (type: alist)
          An association list of options to append.

 -- Data Type: unbound-remote
     Available ‘unbound-remote’ fields are:

     ‘control-enable’ (type: maybe-boolean)
          Enable remote control.

     ‘control-interface’ (type: maybe-string)
          IP address or local socket path to listen on for remote
          control.

     ‘extra-options’ (default: ‘()’) (type: alist)
          An association list of options to append.

 -- Data Type: unbound-zone
     Available ‘unbound-zone’ fields are:

     ‘name’ (type: string)
          Zone name.

     ‘forward-addr’ (type: maybe-list-of-strings)
          IP address of server to forward to.

     ‘forward-tls-upstream’ (type: maybe-boolean)
          Whether the queries to this forwarder use TLS for transport.

     ‘extra-options’ (default: ‘()’) (type: alist)
          An association list of options to append.


File: guix.info,  Node: VNC Services,  Next: VPN Services,  Prev: DNS Services,  Up: Services

11.10.24 VNC Services
---------------------

The ‘(gnu services vnc)’ module provides services related to “Virtual
Network Computing” (VNC), which makes it possible to locally use
graphical Xorg applications running on a remote machine.  Combined with
a graphical manager that supports the “X Display Manager Control
Protocol”, such as GDM (*note gdm::) or LightDM (*note lightdm::), it is
possible to remote an entire desktop for a multi-user environment.

Xvnc
....

Xvnc is a VNC server that spawns its own X window server; which means it
can run on headless servers.  The Xvnc implementations provided by the
‘tigervnc-server’ and ‘turbovnc’ aim to be fast and efficient.

 -- Variable: xvnc-service-type

     The ‘xvnc-service-type’ service can be configured via the
     ‘xvnc-configuration’ record, documented below.  A second virtual
     display could be made available on a remote machine via the
     following configuration:

     (service xvnc-service-type
              (xvnc-configuration (display-number 10)))

   As a demonstration, the ‘xclock’ command could then be started on the
remote machine on display number 10, and it could be displayed locally
via the ‘vncviewer’ command:
     # Start xclock on the remote machine.
     ssh -L5910:localhost:5910 YOUR-HOST -- guix shell xclock \
         -- env DISPLAY=:10 xclock
     # Access it via VNC.
     guix shell tigervnc-client -- vncviewer localhost:5910

   The following configuration combines XDMCP and Inetd to allow
multiple users to concurrently use the remote system and login
graphically via the GDM display manager:

     (operating-system
       [...]
       (services (cons*
                  [...]
                  (service xvnc-service-type (xvnc-configuration
                                              (display-number 5)
                                              (localhost? #f)
                                              (xdmcp? #t)
                                              (inetd? #t)))
                  (modify-services %desktop-services
                    (gdm-service-type config => (gdm-configuration
                                                 (inherit config)
                                                 (auto-suspend? #f)
                                                 (xdmcp? #t)))))))

   A remote user could then connect to it by using the ‘vncviewer’
command or a compatible VNC client and start a desktop session of their
choosing:
     vncviewer remote-host:5905

     Warning: Unless your machine is in a controlled environment, for
     security reasons, the ‘localhost?’ configuration of the
     ‘xvnc-configuration’ record should be left to its default ‘#t’
     value and exposed via a secure means such as an SSH port forward.
     The XDMCP port, UDP 177 should also be blocked from the outside by
     a firewall, as it is not a secure protocol and can expose login
     credentials in clear.

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

     ‘xvnc’ (default: ‘tigervnc-server’) (type: file-like)
          The package that provides the Xvnc binary.

     ‘display-number’ (default: ‘0’) (type: number)
          The display number used by Xvnc.  You should set this to a
          number not already used a Xorg server.

     ‘geometry’ (default: ‘"1024x768"’) (type: string)
          The size of the desktop to be created.

     ‘depth’ (default: ‘24’) (type: color-depth)
          The pixel depth in bits of the desktop to be created.
          Accepted values are 16, 24 or 32.

     ‘port’ (type: maybe-port)
          The port on which to listen for connections from viewers.
          When left unspecified, it defaults to 5900 plus the display
          number.

     ‘ipv4?’ (default: ‘#t’) (type: boolean)
          Use IPv4 for incoming and outgoing connections.

     ‘ipv6?’ (default: ‘#t’) (type: boolean)
          Use IPv6 for incoming and outgoing connections.

     ‘password-file’ (type: maybe-string)
          The password file to use, if any.  Refer to vncpasswd(1) to
          learn how to generate such a file.

     ‘xdmcp?’ (default: ‘#f’) (type: boolean)
          Query the XDMCP server for a session.  This enables users to
          log in a desktop session from the login manager screen.  For a
          multiple users scenario, you’ll want to enable the ‘inetd?’
          option as well, so that each connection to the VNC server is
          handled separately rather than shared.

     ‘inetd?’ (default: ‘#f’) (type: boolean)
          Use an Inetd-style service, which runs the Xvnc server on
          demand.

     ‘frame-rate’ (default: ‘60’) (type: number)
          The maximum number of updates per second sent to each client.

     ‘security-types’ (default: ‘'("None")’) (type: security-types)
          The allowed security schemes to use for incoming connections.
          The default is "None", which is safe given that Xvnc is
          configured to authenticate the user via the display manager,
          and only for local connections.  Accepted values are any of
          the following: ("None" "VncAuth" "Plain" "TLSNone" "TLSVnc"
          "TLSPlain" "X509None" "X509Vnc")

     ‘localhost?’ (default: ‘#t’) (type: boolean)
          Only allow connections from the same machine.  It is set to
          #true by default for security, which means SSH or another
          secure means should be used to expose the remote port.

     ‘log-level’ (default: ‘30’) (type: log-level)
          The log level, a number between 0 and 100, 100 meaning most
          verbose output.  The log messages are output to syslog.

     ‘extra-options’ (default: ‘'()’) (type: strings)
          This can be used to provide extra Xvnc options not exposed via
          this <xvnc-configuration> record.


File: guix.info,  Node: VPN Services,  Next: Network File System,  Prev: VNC Services,  Up: Services

11.10.25 VPN Services
---------------------

The ‘(gnu services vpn)’ module provides services related to “virtual
private networks” (VPNs).

Bitmask
.......

 -- Variable: bitmask-service-type
     A service type for the Bitmask (https://bitmask.net) VPN client.
     It makes the client available in the system and loads its polkit
     policy.  Please note that the client expects an active
     polkit-agent, which is either run by your desktop-environment or
     should be run manually.

OpenVPN
.......

It provides a _client_ service for your machine to connect to a VPN, and
a _server_ service for your machine to host a VPN.  Both
‘openvpn-client-service-type’ and ‘openvpn-server-service-type’ can be
run simultaneously.

 -- Variable: openvpn-client-service-type
     Type of the service that runs ‘openvpn’, a VPN daemon, as a client.

     The value for this service is a ‘<openvpn-client-configuration>’
     object.

 -- Variable: openvpn-server-service-type
     Type of the service that runs ‘openvpn’, a VPN daemon, as a server.

     The value for this service is a ‘<openvpn-server-configuration>’
     object.

 -- Data Type: openvpn-client-configuration
     Available ‘openvpn-client-configuration’ fields are:

     ‘openvpn’ (default: ‘openvpn’) (type: file-like)
          The OpenVPN package.

     ‘pid-file’ (default: ‘"/var/run/openvpn/openvpn.pid"’) (type: string)
          The OpenVPN pid file.

     ‘proto’ (default: ‘udp’) (type: proto)
          The protocol (UDP or TCP) used to open a channel between
          clients and servers.

     ‘dev’ (default: ‘tun’) (type: dev)
          The device type used to represent the VPN connection.

     ‘ca’ (default: ‘"/etc/openvpn/ca.crt"’) (type: maybe-string)
          The certificate authority to check connections against.

     ‘cert’ (default: ‘"/etc/openvpn/client.crt"’) (type: maybe-string)
          The certificate of the machine the daemon is running on.  It
          should be signed by the authority given in ‘ca’.

     ‘key’ (default: ‘"/etc/openvpn/client.key"’) (type: maybe-string)
          The key of the machine the daemon is running on.  It must be
          the key whose certificate is ‘cert’.

     ‘comp-lzo?’ (default: ‘#t’) (type: boolean)
          Whether to use the lzo compression algorithm.

     ‘persist-key?’ (default: ‘#t’) (type: boolean)
          Don’t re-read key files across SIGUSR1 or –ping-restart.

     ‘persist-tun?’ (default: ‘#t’) (type: boolean)
          Don’t close and reopen TUN/TAP device or run up/down scripts
          across SIGUSR1 or –ping-restart restarts.

     ‘fast-io?’ (default: ‘#f’) (type: boolean)
          (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a
          call to poll/epoll/select prior to the write operation.

     ‘verbosity’ (default: ‘3’) (type: number)
          Verbosity level.

     ‘tls-auth’ (default: ‘#f’) (type: tls-auth-client)
          Add an additional layer of HMAC authentication on top of the
          TLS control channel to protect against DoS attacks.

     ‘auth-user-pass’ (type: maybe-string)
          Authenticate with server using username/password.  The option
          is a file containing username/password on 2 lines.  Do not use
          a file-like object as it would be added to the store and
          readable by any user.

     ‘verify-key-usage?’ (default: ‘#t’) (type: key-usage)
          Whether to check the server certificate has server usage
          extension.

     ‘bind?’ (default: ‘#f’) (type: bind)
          Bind to a specific local port number.

     ‘resolv-retry?’ (default: ‘#t’) (type: resolv-retry)
          Retry resolving server address.

     ‘remote’ (default: ‘'()’) (type: openvpn-remote-list)
          A list of remote servers to connect to.

           -- Data Type: openvpn-remote-configuration
               Available ‘openvpn-remote-configuration’ fields are:

               ‘name’ (default: ‘"my-server"’) (type: string)
                    Server name.

               ‘port’ (default: ‘1194’) (type: number)
                    Port number the server listens to.

 -- Data Type: openvpn-server-configuration
     Available ‘openvpn-server-configuration’ fields are:

     ‘openvpn’ (default: ‘openvpn’) (type: file-like)
          The OpenVPN package.

     ‘pid-file’ (default: ‘"/var/run/openvpn/openvpn.pid"’) (type: string)
          The OpenVPN pid file.

     ‘proto’ (default: ‘udp’) (type: proto)
          The protocol (UDP or TCP) used to open a channel between
          clients and servers.

     ‘dev’ (default: ‘tun’) (type: dev)
          The device type used to represent the VPN connection.

     ‘ca’ (default: ‘"/etc/openvpn/ca.crt"’) (type: maybe-string)
          The certificate authority to check connections against.

     ‘cert’ (default: ‘"/etc/openvpn/client.crt"’) (type: maybe-string)
          The certificate of the machine the daemon is running on.  It
          should be signed by the authority given in ‘ca’.

     ‘key’ (default: ‘"/etc/openvpn/client.key"’) (type: maybe-string)
          The key of the machine the daemon is running on.  It must be
          the key whose certificate is ‘cert’.

     ‘comp-lzo?’ (default: ‘#t’) (type: boolean)
          Whether to use the lzo compression algorithm.

     ‘persist-key?’ (default: ‘#t’) (type: boolean)
          Don’t re-read key files across SIGUSR1 or –ping-restart.

     ‘persist-tun?’ (default: ‘#t’) (type: boolean)
          Don’t close and reopen TUN/TAP device or run up/down scripts
          across SIGUSR1 or –ping-restart restarts.

     ‘fast-io?’ (default: ‘#f’) (type: boolean)
          (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a
          call to poll/epoll/select prior to the write operation.

     ‘verbosity’ (default: ‘3’) (type: number)
          Verbosity level.

     ‘tls-auth’ (default: ‘#f’) (type: tls-auth-server)
          Add an additional layer of HMAC authentication on top of the
          TLS control channel to protect against DoS attacks.

     ‘port’ (default: ‘1194’) (type: number)
          Specifies the port number on which the server listens.

     ‘server’ (default: ‘"10.8.0.0 255.255.255.0"’) (type: ip-mask)
          An ip and mask specifying the subnet inside the virtual
          network.

     ‘server-ipv6’ (default: ‘#f’) (type: cidr6)
          A CIDR notation specifying the IPv6 subnet inside the virtual
          network.

     ‘dh’ (default: ‘"/etc/openvpn/dh2048.pem"’) (type: string)
          The Diffie-Hellman parameters file.

     ‘ifconfig-pool-persist’ (default: ‘"/etc/openvpn/ipp.txt"’) (type: string)
          The file that records client IPs.

     ‘redirect-gateway?’ (default: ‘#f’) (type: gateway)
          When true, the server will act as a gateway for its clients.

     ‘client-to-client?’ (default: ‘#f’) (type: boolean)
          When true, clients are allowed to talk to each other inside
          the VPN.

     ‘keepalive’ (default: ‘(10 120)’) (type: keepalive)
          Causes ping-like messages to be sent back and forth over the
          link so that each side knows when the other side has gone
          down.  ‘keepalive’ requires a pair.  The first element is the
          period of the ping sending, and the second element is the
          timeout before considering the other side down.

     ‘max-clients’ (default: ‘100’) (type: number)
          The maximum number of clients.

     ‘status’ (default: ‘"/var/run/openvpn/status"’) (type: string)
          The status file.  This file shows a small report on current
          connection.  It is truncated and rewritten every minute.

     ‘client-config-dir’ (default: ‘'()’) (type: openvpn-ccd-list)
          The list of configuration for some clients.

strongSwan
----------

Currently, the strongSwan service only provides legacy-style
configuration with ‘ipsec.conf’ and ‘ipsec.secrets’ files.

 -- Variable: strongswan-service-type
     A service type for configuring strongSwan for IPsec VPN (Virtual
     Private Networking).  Its value must be a
     ‘strongswan-configuration’ record as in this example:

          (service strongswan-service-type
                   (strongswan-configuration
                    (ipsec-conf "/etc/ipsec.conf")
                    (ipsec-secrets "/etc/ipsec.secrets")))

 -- Data Type: strongswan-configuration
     Data type representing the configuration of the StrongSwan service.

     ‘strongswan’
          The strongSwan package to use for this service.

     ‘ipsec-conf’ (default: ‘#f’)
          The file name of your ‘ipsec.conf’.  If not ‘#f’, then this
          and ‘ipsec-secrets’ must both be strings.

     ‘ipsec-secrets’ (default ‘#f’)
          The file name of your ‘ipsec.secrets’.  If not ‘#f’, then this
          and ‘ipsec-conf’ must both be strings.

Wireguard
.........

 -- Variable: wireguard-service-type
     A service type for a Wireguard tunnel interface.  Its value must be
     a ‘wireguard-configuration’ record as in this example:

          (service wireguard-service-type
                   (wireguard-configuration
                    (peers
                     (list
                      (wireguard-peer
                       (name "my-peer")
                       (endpoint "my.wireguard.com:51820")
                       (public-key "hzpKg9X1yqu1axN6iJp0mWf6BZGo8m1wteKwtTmDGF4=")
                       (allowed-ips '("10.0.0.2/32")))))))

 -- Data Type: wireguard-configuration
     Data type representing the configuration of the Wireguard service.

     ‘wireguard’
          The wireguard package to use for this service.

     ‘interface’ (default: ‘"wg0"’)
          The interface name for the VPN.

     ‘addresses’ (default: ‘'("10.0.0.1/32")’)
          List of strings or G-expressions which represent the IP
          addresses to be assigned to the above interface.

     ‘port’ (default: ‘51820’)
          The port on which to listen for incoming connections.

     ‘dns’ (default: ‘'())’)
          List of strings or G-expressions which represent the DNS
          server(s) to announce to VPN clients via DHCP.

     ‘monitor-ips?’ (default: ‘#f’)
          Whether to monitor the resolved Internet addresses (IPs) of
          the endpoints of the configured peers, resetting the peer
          endpoints using an IP address that no longer correspond to
          their freshly resolved host name.  Set this to ‘#t’ if one or
          more endpoints use host names provided by a dynamic DNS
          service to keep the sessions alive.

     ‘monitor-ips-interval’ (default: ‘"*/5 * * * *"’)
          This is the monitoring schedule, expressed as a string in
          traditional cron syntax or as a gexp evaluating to a Shepherd
          calendar event (*note (shepherd)Timers::).

     ‘private-key’ (default: ‘"/etc/wireguard/private.key"’)
          The private key file for the interface.  It is automatically
          generated if the file does not exist.  If this field is ‘#f’,
          a private key is not automatically created and the path is not
          serialized to the configuration file.

     ‘bootstrap-private-key?’ (default: ‘#t’)
          Whether or not the private key should be generated
          automatically if it does not exist.

          Setting this to ‘#f’ allows one to set the private key using
          command substitution.  One example shown in the ‘wg-quick(8)’
          manual is retrieving a private key using ‘password-store’.
          This can be achieved with the following code:

               (wireguard-configuration
                (private-key
                 #~(string-append "<("
                                  #$(file-append password-store "/bin/pass")
                                  ;; Wireguard replaces %i with the interface name.
                                  " WireGuard/private-keys/%i)")))

     ‘peers’ (default: ‘'()’)
          The authorized peers on this interface.  This is a list of
          WIREGUARD-PEER records.

     ‘pre-up’ (default: ‘'()’)
          List of strings or G-expressions.  These are script snippets
          which will be executed before setting up the interface.

     ‘post-up’ (default: ‘'()’)
          List of strings or G-expressions.  These are script snippets
          which will be executed after setting up the interface.

     ‘pre-down’ (default: ‘'()’)
          List of strings or G-expressions.  These are script snippets
          which will be executed before tearing down the interface.

     ‘post-down’ (default: ‘'()’)
          List of strings or G-expressions.  These are script snippets
          which will be executed after tearing down the interface.

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

     ‘table’ (default: ‘"auto"’)
          The routing table to which routes are added, as a string.
          There are two special values: ‘"off"’ that disables the
          creation of routes altogether, and ‘"auto"’ (the default) that
          adds routes to the default table and enables special handling
          of default routes.

     ‘auto-start?’ (default: ‘#t"’)
          Whether the Wireguard network should be started automatically
          by the Shepherd.  If it is ‘#f’ the service has to be started
          manually with ‘herd start wireguard-$interface’ (for example:
          ‘herd start wireguard-wg0’).

 -- Data Type: wireguard-peer
     Data type representing a Wireguard peer attached to a given
     interface.

     ‘name’
          The peer name.

     ‘endpoint’ (default: ‘#f’)
          The optional endpoint for the peer, such as
          ‘"demo.wireguard.com:51820"’.

     ‘public-key’
          The peer public-key represented as a base64 string.

     ‘preshared-key’ (default: ‘#f’)
          An optional pre-shared key file for this peer that can be
          either a string or a G-expression.  The given file will not be
          autogenerated.

     ‘allowed-ips’
          A list of IP addresses from which incoming traffic for this
          peer is allowed and to which incoming traffic for this peer is
          directed.

     ‘keep-alive’ (default: ‘#f’)
          An optional time interval in seconds.  A packet will be sent
          to the server endpoint once per time interval.  This helps
          receiving incoming connections from this peer when you are
          behind a NAT or a firewall.


File: guix.info,  Node: Network File System,  Next: Samba Services,  Prev: VPN Services,  Up: Services

11.10.26 Network File System
----------------------------

The ‘(gnu services nfs)’ module provides the following services, which
are most commonly used in relation to mounting or exporting directory
trees as “network file systems” (NFS).

   While it is possible to use the individual components that together
make up a Network File System service, we recommended to configure an
NFS server with the ‘nfs-service-type’.

NFS Service
...........

The NFS service takes care of setting up all NFS component services,
kernel configuration file systems, and installs configuration files in
the locations that NFS expects.

 -- Variable: nfs-service-type
     A service type for a complete NFS server.

 -- Data Type: nfs-configuration
     This data type represents the configuration of the NFS service and
     all of its subsystems.

     It has the following parameters:
     ‘nfs-utils’ (default: ‘nfs-utils’)
          The nfs-utils package to use.

     ‘nfs-versions’ (default: ‘'("4.2" "4.1" "4.0")’)
          If a list of string values is provided, the ‘rpc.nfsd’ daemon
          will be limited to supporting the given versions of the NFS
          protocol.

     ‘exports’ (default: ‘'()’)
          This is a list of directories the NFS server should export.
          Each entry is a list consisting of two elements: a directory
          name and a string containing all options.  This is an example
          in which the directory ‘/export’ is served to all NFS clients
          as a read-only share:

               (nfs-configuration
                (exports
                 '(("/export"
                    "*(ro,insecure,no_subtree_check,crossmnt,fsid=0)"))))

     ‘rpcmountd-port’ (default: ‘#f’)
          The network port that the ‘rpc.mountd’ daemon should use.

     ‘rpcstatd-port’ (default: ‘#f’)
          The network port that the ‘rpc.statd’ daemon should use.

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

     ‘idmap-domain’ (default: ‘"localdomain"’)
          The local NFSv4 domain name.

     ‘nfsd-port’ (default: ‘2049’)
          The network port that the ‘nfsd’ daemon should use.

     ‘nfsd-threads’ (default: ‘8’)
          The number of threads used by the ‘nfsd’ daemon.

     ‘nfsd-tcp?’ (default: ‘#t’)
          Whether the ‘nfsd’ daemon should listen on a TCP socket.

     ‘nfsd-udp?’ (default: ‘#f’)
          Whether the ‘nfsd’ daemon should listen on a UDP socket.

     ‘pipefs-directory’ (default: ‘"/var/lib/nfs/rpc_pipefs"’)
          The directory where the pipefs file system is mounted.

     ‘debug’ (default: ‘'()"’)
          A list of subsystems for which debugging output should be
          enabled.  This is a list of symbols.  Any of these symbols are
          valid: ‘nfsd’, ‘nfs’, ‘rpc’, ‘idmap’, ‘statd’, or ‘mountd’.

   If you don’t need a complete NFS service or prefer to build it
yourself you can use the individual component services that are
documented below.

RPC Bind Service
................

The RPC Bind service provides a facility to map program numbers into
universal addresses.  Many NFS related services use this facility.
Hence it is automatically started when a dependent service starts.

 -- Variable: rpcbind-service-type
     A service type for the RPC portmapper daemon.

 -- Data Type: rpcbind-configuration
     Data type representing the configuration of the RPC Bind Service.
     This type has the following parameters:
     ‘rpcbind’ (default: ‘rpcbind’)
          The rpcbind package to use.

     ‘warm-start?’ (default: ‘#t’)
          If this parameter is ‘#t’, then the daemon will read a state
          file on startup thus reloading state information saved by a
          previous instance.

Pipefs Pseudo File System
.........................

The pipefs file system is used to transfer NFS related data between the
kernel and user space programs.

 -- Variable: pipefs-service-type
     A service type for the pipefs pseudo file system.

 -- Data Type: pipefs-configuration
     Data type representing the configuration of the pipefs pseudo file
     system service.  This type has the following parameters:
     ‘mount-point’ (default: ‘"/var/lib/nfs/rpc_pipefs"’)
          The directory to which the file system is to be attached.

GSS Daemon Service
..................

The “global security system” (GSS) daemon provides strong security for
RPC based protocols.  Before exchanging RPC requests an RPC client must
establish a security context.  Typically this is done using the Kerberos
command ‘kinit’ or automatically at login time using PAM services (*note
Kerberos Services::).

 -- Variable: gss-service-type
     A service type for the Global Security System (GSS) daemon.

 -- Data Type: gss-configuration
     Data type representing the configuration of the GSS daemon service.
     This type has the following parameters:
     ‘nfs-utils’ (default: ‘nfs-utils’)
          The package in which the ‘rpc.gssd’ command is to be found.

     ‘pipefs-directory’ (default: ‘"/var/lib/nfs/rpc_pipefs"’)
          The directory where the pipefs file system is mounted.

IDMAP Daemon Service
....................

The idmap daemon service provides mapping between user IDs and user
names.  Typically it is required in order to access file systems mounted
via NFSv4.

 -- Variable: idmap-service-type
     A service type for the Identity Mapper (IDMAP) daemon.

 -- Data Type: idmap-configuration
     Data type representing the configuration of the IDMAP daemon
     service.  This type has the following parameters:
     ‘nfs-utils’ (default: ‘nfs-utils’)
          The package in which the ‘rpc.idmapd’ command is to be found.

     ‘pipefs-directory’ (default: ‘"/var/lib/nfs/rpc_pipefs"’)
          The directory where the pipefs file system is mounted.

     ‘domain’ (default: ‘#f’)
          The local NFSv4 domain name.  This must be a string or ‘#f’.
          If it is ‘#f’ then the daemon will use the host’s fully
          qualified domain name.

     ‘verbosity’ (default: ‘0’)
          The verbosity level of the daemon.

Autofs Service
..............

The autofs service automatically mounts and unmounts filesystems.  It
can mount both network and local storage, but is most often used to
manage NFS mounts.

   A typical configuration might look like:

     (operating-system
       (services
        (append
         (list
          (service nfs-service-type (nfs-configuration))
          (service autofs-service-type
                   (autofs-configuration
                    (mounts
                     (list
                      (autofs-indirect-map
                       (mount-point "/net/home")
                       (entries
                        (list
                         ;; Accessing /net/home/foo will mount
                         ;; big.network.server:/home/foo.
                         (autofs-map-entry
                          (type "nfs")
                          (device "big.network.server:/home/&")
                          (mount-point "*"))))))))))
         %base-services)))

 -- Data Type: autofs-indirect-map
     Available ‘autofs-indirect-map’ fields are:

     ‘mount-point’ (type: string)
          Where to mount the indirect map.

     ‘entries’ (default: ‘()’) (type: autofs-map-entries)
          Entries in this map.

 -- Data Type: autofs-map-entry
     Available ‘autofs-map-entry’ fields are:

     ‘type’ (default: ‘"auto"’) (type: string)
          The type of the filesystem.

     ‘device’ (type: string)
          Device or remote host to mount.  May contain special character
          ‘&’, which can be referenced in the MOUNT-POINT field.

     ‘mount-point’ (type: string)
          Directory to mount this device on.  Map entries come in two
          flavors: direct and indirect.  Direct entries map a single
          device to a single mountpoint, while indirect entries can map
          multiple devices to multiple mountpoints.  A direct entry has
          a MOUNT-POINT beginning with ‘/’, representing the absolute
          path of the directory to mount the device on.  For example:

               (autofs-map-entry
                (type "ext4")
                (device "/dev/sdb1")
                (mount-point "/mnt/external-disk"))

          An indirect entry has a MOUNT-POINT not beginning with ‘/’,
          representing the subdirectory within the parent indirect map
          for this entry.  Indirect maps may also use the special
          character ‘*’, which will be replaced with the value of
          special character ‘&’ in the DEVICE field of this entry.  For
          example:

               (autofs-indirect-map
                (mount-point "/devices")
                (entries
                 (list
                  ;; Automount any block device r/o by ID.
                  (autofs-map-entry
                   (type "auto")
                   (mount-point "ro/uuid/*")
                   (device "/dev/disk/by-id/&")
                   (options '(ro)))
                  ;; Automount any block device by UUID.
                  (autofs-map-entry
                   (type "auto")
                   (mount-point "rw/uuid/*")
                   (device "/dev/disk/by-uuid/&")))))

     ‘options’ (default: ‘()’) (type: file-system-options)
          List of mount options.  Some options are simple flags, such as
          ro, noexec, nosuid, etc.  These may be expressed as strings or
          symbols.  Other options also accept a value.  These are
          expressed as pairs of ‘(option . value)’.  ‘option’ may be a
          string or symbol, as with flags.  ‘value’ may be a string,
          symbol, or number.  Example: ‘(ro (errors . remount-ro)
          noexec)’

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

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

     ‘mounts’ (default: ‘()’) (type: autofs-mount-maps)
          Mount maps to manage.  This is a list of either direct map
          entries or indirect mount maps.

     ‘timeout’ (default: ‘300’) (type: conf-integer)
          Sets the default mount timeout in seconds.

     ‘master-wait’ (default: ‘10’) (type: conf-integer)
          Sets the default maximum number of retries (actual iterations
          is half this, each is delayed by 2 seconds before retrying)
          waiting for the master map to become available if it cannot be
          read at program start.  This can be longer if the map source
          itself waits for availability (such as sss).

     ‘negative-timeout’ (default: ‘60’) (type: conf-integer)
          Set the default timeout for caching failed key lookups.

     ‘mount-verbose?’ (default: ‘#f’) (type: conf-boolean)
          Use the verbose flag when spawning mount(8), and log some
          process info about the requestor and its parent.

     ‘mount-wait’ (default: ‘-1’) (type: conf-integer)
          Set the default time to wait for a response from a spawned
          mount(8) before sending it a SIGTERM. Note that we still need
          to wait for the RPC layer to timeout before the sub-process
          exits so this isn’t ideal but it is the best we can do.  The
          default is to wait until mount(8) returns without
          intervention.

     ‘umount-wait’ (default: ‘12’) (type: conf-integer)
          Set the default time to wait for a response from a spawned
          umount(8) before sending it a SIGTERM. Note that we still need
          to wait for the RPC layer to timeout before the sub-process
          exits so this isn’t ideal but it is the best we can do.

     ‘browse-mode?’ (default: ‘#t’) (type: conf-boolean)
          Should maps be browsable by default?

     ‘mount-nfs-default-protocol’ (default: ‘3’) (type: conf-integer)
          Set the default protocol that mount.nfs(8) uses when
          performing a mount.  Autofs needs to know the default NFS
          protocol that mount.nfs(8) uses so it can do special case
          handling for its availability probe for different NFS
          protocols.  Since we can’t identify this default automatically
          we need to set it in the autofs configuration.

     ‘append-options?’ (default: ‘#t’) (type: conf-boolean)
          When #t, global options are appended to map entry options.
          When #f, map entry options replace the global options.

     ‘logging’ (type: conf-log-level)
          Default log level.  May be #:none, #:verbose, or #:debug.

     ‘force-standard-program-map-env?’ (default: ‘#f’) (type: conf-boolean)
          Override the use of a prefix with standard environment
          variables when a program map is executed.  Since program maps
          are run as the privileged user setting these standard
          environment variables opens automount(8) to potential user
          privilege escalation when the program map is written in a
          language that can load components from, for example, a user
          home directory.

     ‘map-hash-table-size’ (default: ‘1024’) (type: conf-integer)
          This configuration option may be used to change the number of
          hash table slots.  This configuration option affects the
          overhead of searching the map entry cache for map entries when
          there are a large number of entries.  It affects the number of
          entries that must be looked at to locate a map entry in the
          map entry cache.  For example, the default of 1024 and a
          direct map with 8000 entries would result in each slot
          containing an average of 8 entries, which should be
          acceptable.  However, if excessive CPU usage is observed
          during automount lookups increasing this option can reduce the
          CPU overhead considerably because it reduces the length of the
          search chains.  Note that the number of entries in a map
          doesn’t necessarily relate to the number of entries used in
          the map entry cache.  There are two distinct cases where the
          map hash table can make a significant difference, direct maps
          and indirect maps that use the "browse" option.  For indirect
          maps that do not use the "browse" option entries are added to
          the map entry cache at lookup so the number of active cache
          entries, in this case, is usually much less than the number of
          entries in the map.  In this last case it would be unusual for
          the map entry cache to grow large enough to warrant increasing
          the default before an event that cleans stale entries, a map
          re-read for example.

     ‘use-hostname-for-mounts?’ (default: ‘#f’) (type: conf-boolean)
          NFS mounts where the host name resolves to more than one IP
          address are probed for availability and to establish the order
          in which mounts to them should be tried.  To ensure that mount
          attempts are made only to hosts that are responding and are
          tried in the order of hosts with the quickest response the IP
          address of the host needs to be used for the mount.  If it is
          necessary to use the hostname given in the map entry for the
          mount regardless, then set this option to #t.  Be aware that
          if this is done there is no defense against the host name
          resolving to one that isn’t responding and while the number of
          attempts at a successful mount will correspond to the number
          of addresses the host name resolves to the order will also not
          correspond to fastest responding hosts.

     ‘disable-not-found-message?’ (default: ‘#f’) (type: conf-boolean)
          The original request to add this log message needed it to be
          unconditional.  That produces, IMHO, unnecessary noise in the
          log so a configuration option has been added to provide the
          ability to turn it off.

     ‘use-ignore-mount-option?’ (default: ‘#f’) (type: conf-boolean)
          An option to enable the use of autofs pseudo option "disable".
          This option is used as a hint to user space that the mount
          entry should be omitted from mount table listings.  The
          default is #f to avoid unexpected changes in behaviour and so
          is an opt-in setting.

     ‘sss-master-map-wait’ (default: ‘0’) (type: conf-integer)
          Set the time to wait and retry if sssd is unable to read the
          master map at program start.  Default is 0 (don’t wait) or 10
          if sss supports returning EHSTDOWN when the provider isn’t
          available.  If the sss library upports returning EHOSTDOWN
          when the provider is down then this value is how long to wait
          between re‐ tries reading the master map.  When reading
          dependent maps or looking up a map key this value is
          multiplied by the number of retries that would be used when
          reading the master map.

     ‘use-mount-request-log-id?’ (default: ‘#f’) (type: conf-boolean)
          Set whether to use a mount request log id so that log entries
          for specific mount requests can be easily identified in logs
          that have multiple concurrent requests.

