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

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

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

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


File: guix.info,  Node: Desktop Services,  Next: Sound Services,  Prev: Printing Services,  Up: Services

12.9.9 Desktop Services
-----------------------

The ‘(gnu services desktop)’ module provides services that are usually
useful in the context of a “desktop” setup—that is, on a machine running
a graphical display server, possibly with graphical user interfaces,
etc.  It also defines services that provide specific desktop
environments like GNOME, Xfce or MATE.

   To simplify things, the module defines a variable containing the set
of services that users typically expect on a machine with a graphical
environment and networking:

 -- Scheme Variable: %desktop-services
     This is a list of services that builds upon ‘%base-services’ and
     adds or adjusts services for a typical “desktop” setup.

     In particular, it adds a graphical login manager (*note
     ‘gdm-service-type’: X Window.), screen lockers, a network
     management tool (*note ‘network-manager-service-type’: Networking
     Services.) with modem support (*note ‘modem-manager-service-type’:
     Networking Services.), energy and color management services, the
     ‘elogind’ login and seat manager, the Polkit privilege service, the
     GeoClue location service, the AccountsService daemon that allows
     authorized users change system passwords, an NTP client (*note
     Networking Services::), the Avahi daemon, and has the name service
     switch service configured to be able to use ‘nss-mdns’ (*note mDNS:
     Name Service Switch.).

   The ‘%desktop-services’ variable can be used as the ‘services’ field
of an ‘operating-system’ declaration (*note ‘services’: operating-system
Reference.).

   Additionally, the ‘gnome-desktop-service-type’,
‘xfce-desktop-service’, ‘mate-desktop-service-type’,
‘lxqt-desktop-service-type’ and ‘enlightenment-desktop-service-type’
procedures can add GNOME, Xfce, MATE and/or Enlightenment to a system.
To “add GNOME” means that system-level services like the backlight
adjustment helpers and the power management utilities are added to the
system, extending ‘polkit’ and ‘dbus’ appropriately, allowing GNOME to
operate with elevated privileges on a limited number of special-purpose
system interfaces.  Additionally, adding a service made by
‘gnome-desktop-service-type’ adds the GNOME metapackage to the system
profile.  Likewise, adding the Xfce service not only adds the ‘xfce’
metapackage to the system profile, but it also gives the Thunar file
manager the ability to open a “root-mode” file management window, if the
user authenticates using the administrator’s password via the standard
polkit graphical interface.  To “add MATE” means that ‘polkit’ and
‘dbus’ are extended appropriately, allowing MATE to operate with
elevated privileges on a limited number of special-purpose system
interfaces.  Additionally, adding a service of type
‘mate-desktop-service-type’ adds the MATE metapackage to the system
profile.  “Adding Enlightenment” means that ‘dbus’ is extended
appropriately, and several of Enlightenment’s binaries are set as
setuid, allowing Enlightenment’s screen locker and other functionality
to work as expected.

   The desktop environments in Guix use the Xorg display server by
default.  If you’d like to use the newer display server protocol called
Wayland, you need to enable Wayland support in GDM (*note
wayland-gdm::).  Another solution is to use the ‘sddm-service’ instead
of GDM as the graphical login manager.  You should then select the
“GNOME (Wayland)” session in SDDM.  Alternatively you can also try
starting GNOME on Wayland manually from a TTY with the command
“XDG_SESSION_TYPE=wayland exec dbus-run-session gnome-session“.
Currently only GNOME has support for Wayland.

 -- Scheme Variable: gnome-desktop-service-type
     This is the type of the service that adds the GNOME
     (https://www.gnome.org) desktop environment.  Its value is a
     ‘gnome-desktop-configuration’ object (see below).

     This service adds the ‘gnome’ package to the system profile, and
     extends polkit with the actions from ‘gnome-settings-daemon’.

 -- Data Type: gnome-desktop-configuration
     Configuration record for the GNOME desktop environment.

     ‘gnome’ (default: ‘gnome’)
          The GNOME package to use.

 -- Scheme Variable: xfce-desktop-service-type
     This is the type of a service to run the https://xfce.org/ (Xfce)
     desktop environment.  Its value is an ‘xfce-desktop-configuration’
     object (see below).

     This service adds the ‘xfce’ package to the system profile, and
     extends polkit with the ability for ‘thunar’ to manipulate the file
     system as root from within a user session, after the user has
     authenticated with the administrator’s password.

     Note that ‘xfce4-panel’ and its plugin packages should be installed
     in the same profile to ensure compatibility.  When using this
     service, you should add extra plugins (‘xfce4-whiskermenu-plugin’,
     ‘xfce4-weather-plugin’, etc.)  to the ‘packages’ field of your
     ‘operating-system’.

 -- Data Type: xfce-desktop-configuration
     Configuration record for the Xfce desktop environment.

     ‘xfce’ (default: ‘xfce’)
          The Xfce package to use.

 -- Scheme Variable: mate-desktop-service-type
     This is the type of the service that runs the MATE desktop
     environment (https://mate-desktop.org/).  Its value is a
     ‘mate-desktop-configuration’ object (see below).

     This service adds the ‘mate’ package to the system profile, and
     extends polkit with the actions from ‘mate-settings-daemon’.

 -- Data Type: mate-desktop-configuration
     Configuration record for the MATE desktop environment.

     ‘mate’ (default: ‘mate’)
          The MATE package to use.

 -- Scheme Variable: lxqt-desktop-service-type
     This is the type of the service that runs the LXQt desktop
     environment (https://lxqt-project.org).  Its value is a
     ‘lxqt-desktop-configuration’ object (see below).

     This service adds the ‘lxqt’ package to the system profile.

 -- Data Type: lxqt-desktop-configuration
     Configuration record for the LXQt desktop environment.

     ‘lxqt’ (default: ‘lxqt’)
          The LXQT package to use.

 -- Scheme Variable: enlightenment-desktop-service-type
     Return a service that adds the ‘enlightenment’ package to the
     system profile, and extends dbus with actions from ‘efl’.

 -- Data Type: enlightenment-desktop-service-configuration
     ‘enlightenment’ (default: ‘enlightenment’)
          The enlightenment package to use.

   Because the GNOME, Xfce and MATE desktop services pull in so many
packages, the default ‘%desktop-services’ variable doesn’t include any
of them by default.  To add GNOME, Xfce or MATE, just ‘cons’ them onto
‘%desktop-services’ in the ‘services’ field of your ‘operating-system’:

     (use-modules (gnu))
     (use-service-modules desktop)
     (operating-system
       ...
       ;; cons* adds items to the list given as its last argument.
       (services (cons* (service gnome-desktop-service-type)
                        (service xfce-desktop-service)
                        %desktop-services))
       ...)

   These desktop environments will then be available as options in the
graphical login window.

   The actual service definitions included in ‘%desktop-services’ and
provided by ‘(gnu services dbus)’ and ‘(gnu services desktop)’ are
described below.

 -- Scheme Procedure: dbus-service [#:dbus DBUS] [#:services '()]
          [#:verbose?]
     Return a service that runs the “system bus”, using DBUS, with
     support for SERVICES.  When VERBOSE? is true, it causes the
     ‘DBUS_VERBOSE’ environment variable to be set to ‘1’; a
     verbose-enabled D-Bus package such as ‘dbus-verbose’ should be
     provided as DBUS in this scenario.  The verbose output is logged to
     ‘/var/log/dbus-daemon.log’.

     D-Bus (https://dbus.freedesktop.org/) is an inter-process
     communication facility.  Its system bus is used to allow system
     services to communicate and to be notified of system-wide events.

     SERVICES must be a list of packages that provide an
     ‘etc/dbus-1/system.d’ directory containing additional D-Bus
     configuration and policy files.  For example, to allow avahi-daemon
     to use the system bus, SERVICES must be equal to ‘(list avahi)’.

 -- Scheme Procedure: elogind-service [#:config CONFIG]
     Return a service that runs the ‘elogind’ login and seat management
     daemon.  Elogind (https://github.com/elogind/elogind) exposes a
     D-Bus interface that can be used to know which users are logged in,
     know what kind of sessions they have open, suspend the system,
     inhibit system suspend, reboot the system, and other tasks.

     Elogind handles most system-level power events for a computer, for
     example suspending the system when a lid is closed, or shutting it
     down when the power button is pressed.

     The CONFIG keyword argument specifies the configuration for
     elogind, and should be the result of an ‘(elogind-configuration
     (PARAMETER VALUE)...)’ invocation.  Available parameters and their
     default values are:

     ‘kill-user-processes?’
          ‘#f’
     ‘kill-only-users’
          ‘()’
     ‘kill-exclude-users’
          ‘("root")’
     ‘inhibit-delay-max-seconds’
          ‘5’
     ‘handle-power-key’
          ‘poweroff’
     ‘handle-suspend-key’
          ‘suspend’
     ‘handle-hibernate-key’
          ‘hibernate’
     ‘handle-lid-switch’
          ‘suspend’
     ‘handle-lid-switch-docked’
          ‘ignore’
     ‘handle-lid-switch-external-power’
          ‘*unspecified*’
     ‘power-key-ignore-inhibited?’
          ‘#f’
     ‘suspend-key-ignore-inhibited?’
          ‘#f’
     ‘hibernate-key-ignore-inhibited?’
          ‘#f’
     ‘lid-switch-ignore-inhibited?’
          ‘#t’
     ‘holdoff-timeout-seconds’
          ‘30’
     ‘idle-action’
          ‘ignore’
     ‘idle-action-seconds’
          ‘(* 30 60)’
     ‘runtime-directory-size-percent’
          ‘10’
     ‘runtime-directory-size’
          ‘#f’
     ‘remove-ipc?’
          ‘#t’
     ‘suspend-state’
          ‘("mem" "standby" "freeze")’
     ‘suspend-mode’
          ‘()’
     ‘hibernate-state’
          ‘("disk")’
     ‘hibernate-mode’
          ‘("platform" "shutdown")’
     ‘hybrid-sleep-state’
          ‘("disk")’
     ‘hybrid-sleep-mode’
          ‘("suspend" "platform" "shutdown")’

 -- Scheme Procedure: accountsservice-service [#:accountsservice
          ACCOUNTSSERVICE]
     Return a service that runs AccountsService, a system service that
     can list available accounts, change their passwords, and so on.
     AccountsService integrates with PolicyKit to enable unprivileged
     users to acquire the capability to modify their system
     configuration.  the accountsservice web site
     (https://www.freedesktop.org/wiki/Software/AccountsService/) for
     more information.

     The ACCOUNTSSERVICE keyword argument is the ‘accountsservice’
     package to expose as a service.

 -- Scheme Procedure: polkit-service [#:polkit POLKIT]
     Return a service that runs the Polkit privilege management service
     (https://www.freedesktop.org/wiki/Software/polkit/), which allows
     system administrators to grant access to privileged operations in a
     structured way.  By querying the Polkit service, a privileged
     system component can know when it should grant additional
     capabilities to ordinary users.  For example, an ordinary user can
     be granted the capability to suspend the system if the user is
     logged in locally.

 -- Scheme Variable: polkit-wheel-service
     Service that adds the ‘wheel’ group as admins to the Polkit
     service.  This makes it so that users in the ‘wheel’ group are
     queried for their own passwords when performing administrative
     actions instead of ‘root’’s, similar to the behaviour used by
     ‘sudo’.

 -- Scheme Variable: upower-service-type
     Service that runs ‘upowerd’ (https://upower.freedesktop.org/), a
     system-wide monitor for power consumption and battery levels, with
     the given configuration settings.

     It implements the ‘org.freedesktop.UPower’ D-Bus interface, and is
     notably used by GNOME.

 -- Data Type: upower-configuration
     Data type representation the configuration for UPower.

     ‘upower’ (default: UPOWER)
          Package to use for ‘upower’.

     ‘watts-up-pro?’ (default: ‘#f’)
          Enable the Watts Up Pro device.

     ‘poll-batteries?’ (default: ‘#t’)
          Enable polling the kernel for battery level changes.

     ‘ignore-lid?’ (default: ‘#f’)
          Ignore the lid state, this can be useful if it’s incorrect on
          a device.

     ‘use-percentage-for-policy?’ (default: ‘#t’)
          Whether to use a policy based on battery percentage rather
          than on estimated time left.  A policy based on battery
          percentage is usually more reliable.

     ‘percentage-low’ (default: ‘20’)
          When ‘use-percentage-for-policy?’ is ‘#t’, this sets the
          percentage at which the battery is considered low.

     ‘percentage-critical’ (default: ‘5’)
          When ‘use-percentage-for-policy?’ is ‘#t’, this sets the
          percentage at which the battery is considered critical.

     ‘percentage-action’ (default: ‘2’)
          When ‘use-percentage-for-policy?’ is ‘#t’, this sets the
          percentage at which action will be taken.

     ‘time-low’ (default: ‘1200’)
          When ‘use-time-for-policy?’ is ‘#f’, this sets the time
          remaining in seconds at which the battery is considered low.

     ‘time-critical’ (default: ‘300’)
          When ‘use-time-for-policy?’ is ‘#f’, this sets the time
          remaining in seconds at which the battery is considered
          critical.

     ‘time-action’ (default: ‘120’)
          When ‘use-time-for-policy?’ is ‘#f’, this sets the time
          remaining in seconds at which action will be taken.

     ‘critical-power-action’ (default: ‘'hybrid-sleep’)
          The action taken when ‘percentage-action’ or ‘time-action’ is
          reached (depending on the configuration of
          ‘use-percentage-for-policy?’).

          Possible values are:

             • ‘'power-off’

             • ‘'hibernate’

             • ‘'hybrid-sleep’.

 -- Scheme Procedure: udisks-service [#:udisks UDISKS]
     Return a service for UDisks
     (https://udisks.freedesktop.org/docs/latest/), a “disk management”
     daemon that provides user interfaces with notifications and ways to
     mount/unmount disks.  Programs that talk to UDisks include the
     ‘udisksctl’ command, part of UDisks, and GNOME Disks.  Note that
     Udisks relies on the ‘mount’ command, so it will only be able to
     use the file-system utilities installed in the system profile.  For
     example if you want to be able to mount NTFS file-systems in read
     and write fashion, you’ll need to have ‘ntfs-3g’ installed
     system-wide.

 -- Scheme Variable: colord-service-type
     This is the type of the service that runs ‘colord’, a system
     service with a D-Bus interface to manage the color profiles of
     input and output devices such as screens and scanners.  It is
     notably used by the GNOME Color Manager graphical tool.  See the
     colord web site (https://www.freedesktop.org/software/colord/) for
     more information.

 -- Scheme Variable: sane-service-type
     This service provides access to scanners via SANE
     (http://www.sane-project.org) by installing the necessary udev
     rules.  It is included in ‘%desktop-services’ (*note Desktop
     Services::) and relies by default on ‘sane-backends-minimal’
     package (see below) for hardware support.

 -- Scheme Variable: sane-backends-minimal
     The default package which the ‘sane-service-type’ installs.  It
     supports many recent scanners.

 -- Scheme Variable: sane-backends
     This package includes support for all scanners that
     ‘sane-backends-minimal’ supports, plus older Hewlett-Packard
     scanners supported by ‘hplip’ package.  In order to use this on a
     system which relies on ‘%desktop-services’, you may use
     ‘modify-services’ (*note ‘modify-services’: Service Reference.) as
     illustrated below:

          (use-modules (gnu))
          (use-service-modules
            ...
            desktop)
          (use-package-modules
            ...
            scanner)

          (define %my-desktop-services
            ;; List of desktop services that supports a broader range of scanners.
            (modify-services %desktop-services
              (sane-service-type _ => sane-backends)))

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

 -- Scheme Procedure: geoclue-application name [#:allowed? #t]
          [#:system? #f] [#:users '()]
     Return a configuration allowing an application to access GeoClue
     location data.  NAME is the Desktop ID of the application, without
     the ‘.desktop’ part.  If ALLOWED? is true, the application will
     have access to location information by default.  The boolean
     SYSTEM? value indicates whether an application is a system
     component or not.  Finally USERS is a list of UIDs of all users for
     which this application is allowed location info access.  An empty
     users list means that all users are allowed.

 -- Scheme Variable: %standard-geoclue-applications
     The standard list of well-known GeoClue application configurations,
     granting authority to the GNOME date-and-time utility to ask for
     the current location in order to set the time zone, and allowing
     the IceCat and Epiphany web browsers to request location
     information.  IceCat and Epiphany both query the user before
     allowing a web page to know the user’s location.

 -- Scheme Procedure: geoclue-service [#:colord COLORD] [#:whitelist
          '()] [#:wifi-geolocation-url
          "https://location.services.mozilla.com/v1/geolocate?key=geoclue"]
          [#:submit-data? #f]
     [#:wifi-submission-url
     "https://location.services.mozilla.com/v1/submit?key=geoclue"]  
     [#:submission-nick "geoclue"]   [#:applications
     %standard-geoclue-applications] Return a service that runs the
     GeoClue location service.  This service provides a D-Bus interface
     to allow applications to request access to a user’s physical
     location, and optionally to add information to online location
     databases.  See the GeoClue web site
     (https://wiki.freedesktop.org/www/Software/GeoClue/) for more
     information.

 -- Scheme Procedure: bluetooth-service [#:bluez BLUEZ]
          [#:auto-enable? #f]
     Return a service that runs the ‘bluetoothd’ daemon, which manages
     all the Bluetooth devices and provides a number of D-Bus
     interfaces.  When AUTO-ENABLE? is true, the bluetooth controller is
     powered automatically at boot, which can be useful when using a
     bluetooth keyboard or mouse.

     Users need to be in the ‘lp’ group to access the D-Bus service.

 -- Scheme Variable: bluetooth-service-type
     This is the type for the Linux Bluetooth Protocol Stack
     (https://bluez.org/) (BlueZ) system, which generates the
     ‘/etc/bluetooth/main.conf’ configuration file.  The value for this
     type is a ‘bluetooth-configuration’ record as in this example:

          (service bluetooth-service-type)

     See below for details about ‘bluetooth-configuration’.

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

     ‘bluez’ (default: ‘bluez’)
          ‘bluez’ package to use.

     ‘name’ (default: ‘"BlueZ"’)
          Default adapter name.

     ‘class’ (default: ‘#x000000’)
          Default device class.  Only the major and minor device class
          bits are considered.

     ‘discoverable-timeout’ (default: ‘180’)
          How long to stay in discoverable mode before going back to
          non-discoverable.  The value is in seconds.

     ‘always-pairable?’ (default: ‘#f’)
          Always allow pairing even if there are no agents registered.

     ‘pairable-timeout’ (default: ‘0’)
          How long to stay in pairable mode before going back to
          non-discoverable.  The value is in seconds.

     ‘device-id’ (default: ‘#f’)
          Use vendor id source (assigner), vendor, product and version
          information for DID profile support.  The values are separated
          by ":" and ASSIGNER, VID, PID and VERSION.

          Possible values are:

             • ‘#f’ to disable it,

             • ‘"assigner:1234:5678:abcd"’, where ASSIGNER is either
               ‘usb’ (default) or ‘bluetooth’.

     ‘reverse-service-discovery?’ (default: ‘#t’)
          Do reverse service discovery for previously unknown devices
          that connect to us.  For BR/EDR this option is really only
          needed for qualification since the BITE tester doesn’t like us
          doing reverse SDP for some test cases, for LE this disables
          the GATT client functionally so it can be used in system which
          can only operate as peripheral.

     ‘name-resolving?’ (default: ‘#t’)
          Enable name resolving after inquiry.  Set it to ‘#f’ if you
          don’t need remote devices name and want shorter discovery
          cycle.

     ‘debug-keys?’ (default: ‘#f’)
          Enable runtime persistency of debug link keys.  Default is
          false which makes debug link keys valid only for the duration
          of the connection that they were created for.

     ‘controller-mode’ (default: ‘'dual’)
          Restricts all controllers to the specified transport.  ‘'dual’
          means both BR/EDR and LE are enabled (if supported by the
          hardware).

          Possible values are:

             • ‘'dual’

             • ‘'bredr’

             • ‘'le’

     ‘multi-profile’ (default: ‘'off’)
          Enables Multi Profile Specification support.  This allows to
          specify if system supports only Multiple Profiles Single
          Device (MPSD) configuration or both Multiple Profiles Single
          Device (MPSD) and Multiple Profiles Multiple Devices (MPMD)
          configurations.

          Possible values are:

             • ‘'off’

             • ‘'single’

             • ‘'multiple’

     ‘fast-connectable?’ (default: ‘#f’)
          Permanently enables the Fast Connectable setting for adapters
          that support it.  When enabled other devices can connect
          faster to us, however the tradeoff is increased power
          consumptions.  This feature will fully work only on kernel
          version 4.1 and newer.

     ‘privacy’ (default: ‘'off’)
          Default privacy settings.

             • ‘'off’: Disable local privacy

             • ‘'network/on’: A device will only accept advertising
               packets from peer devices that contain private addresses.
               It may not be compatible with some legacy devices since
               it requires the use of RPA(s) all the time

             • ‘'device’: A device in device privacy mode is only
               concerned about the privacy of the device and will accept
               advertising packets from peer devices that contain their
               Identity Address as well as ones that contain a private
               address, even if the peer device has distributed its IRK
               in the past

          and additionally, if CONTROLLER-MODE is set to ‘'dual’:

             • ‘'limited-network’: Apply Limited Discoverable Mode to
               advertising, which follows the same policy as to BR/EDR
               that publishes the identity address when discoverable,
               and Network Privacy Mode for scanning

             • ‘'limited-device’: Apply Limited Discoverable Mode to
               advertising, which follows the same policy as to BR/EDR
               that publishes the identity address when discoverable,
               and Device Privacy Mode for scanning.

     ‘just-works-repairing’ (default: ‘'never’)
          Specify the policy to the JUST-WORKS repairing initiated by
          peer.

          Possible values:
             • ‘'never’

             • ‘'confirm’

             • ‘'always’

     ‘temporary-timeout’ (default: ‘30’)
          How long to keep temporary devices around.  The value is in
          seconds.  ‘0’ disables the timer completely.

     ‘refresh-discovery?’ (default: ‘#t’)
          Enables the device to issue an SDP request to update known
          services when profile is connected.

     ‘experimental’ (default: ‘#f’)
          Enables experimental features and interfaces, alternatively a
          list of UUIDs can be given.

          Possible values:

             • ‘#t’

             • ‘#f’

             • ‘(list (uuid <uuid-1>) (uuid <uuid-2>) ...)’.

          List of possible UUIDs:
             • ‘d4992530-b9ec-469f-ab01-6c481c47da1c’: BlueZ
               Experimental Debug,

             • ‘671b10b5-42c0-4696-9227-eb28d1b049d6’: BlueZ
               Experimental Simultaneous Central and Peripheral,

             • ‘"15c0a148-c273-11ea-b3de-0242ac130004’: BlueZ
               Experimental LL privacy,

             • ‘330859bc-7506-492d-9370-9a6f0614037f’: BlueZ
               Experimental Bluetooth Quality Report,

             • ‘a6695ace-ee7f-4fb9-881a-5fac66c629af’: BlueZ
               Experimental Offload Codecs.

     ‘remote-name-request-retry-delay’ (default: ‘300’)
          The duration to avoid retrying to resolve a peer’s name, if
          the previous try failed.

     ‘page-scan-type’ (default: ‘#f’)
          BR/EDR Page scan activity type.

     ‘page-scan-interval’ (default: ‘#f’)
          BR/EDR Page scan activity interval.

     ‘page-scan-window’ (default: ‘#f’)
          BR/EDR Page scan activity window.

     ‘inquiry-scan-type’ (default: ‘#f’)
          BR/EDR Inquiry scan activity type.

     ‘inquiry-scan-interval’ (default: ‘#f’)
          BR/EDR Inquiry scan activity interval.

     ‘inquiry-scan-window’ (default: ‘#f’)
          BR/EDR Inquiry scan activity window.

     ‘link-supervision-timeout’ (default: ‘#f’)
          BR/EDR Link supervision timeout.

     ‘page-timeout’ (default: ‘#f’)
          BR/EDR Page timeout.

     ‘min-sniff-interval’ (default: ‘#f’)
          BR/EDR minimum sniff interval.

     ‘max-sniff-interval’ (default: ‘#f’)
          BR/EDR maximum sniff interval.

     ‘min-advertisement-interval’ (default: ‘#f’)
          LE minimum advertisement interval (used for legacy
          advertisement only).

     ‘max-advertisement-interval’ (default: ‘#f’)
          LE maximum advertisement interval (used for legacy
          advertisement only).

     ‘multi-advertisement-rotation-interval’ (default: ‘#f’)
          LE multiple advertisement rotation interval.

     ‘scan-interval-auto-connect’ (default: ‘#f’)
          LE scanning interval used for passive scanning supporting auto
          connect.

     ‘scan-window-auto-connect’ (default: ‘#f’)
          LE scanning window used for passive scanning supporting auto
          connect.

     ‘scan-interval-suspend’ (default: ‘#f’)
          LE scanning interval used for active scanning supporting wake
          from suspend.

     ‘scan-window-suspend’ (default: ‘#f’)
          LE scanning window used for active scanning supporting wake
          from suspend.

     ‘scan-interval-discovery’ (default: ‘#f’)
          LE scanning interval used for active scanning supporting
          discovery.

     ‘scan-window-discovery’ (default: ‘#f’)
          LE scanning window used for active scanning supporting
          discovery.

     ‘scan-interval-adv-monitor’ (default: ‘#f’)
          LE scanning interval used for passive scanning supporting the
          advertisement monitor APIs.

     ‘scan-window-adv-monitor’ (default: ‘#f’)
          LE scanning window used for passive scanning supporting the
          advertisement monitor APIs.

     ‘scan-interval-connect’ (default: ‘#f’)
          LE scanning interval used for connection establishment.

     ‘scan-window-connect’ (default: ‘#f’)
          LE scanning window used for connection establishment.

     ‘min-connection-interval’ (default: ‘#f’)
          LE default minimum connection interval.  This value is
          superseded by any specific value provided via the Load
          Connection Parameters interface.

     ‘max-connection-interval’ (default: ‘#f’)
          LE default maximum connection interval.  This value is
          superseded by any specific value provided via the Load
          Connection Parameters interface.

     ‘connection-latency’ (default: ‘#f’)
          LE default connection latency.  This value is superseded by
          any specific value provided via the Load Connection Parameters
          interface.

     ‘connection-supervision-timeout’ (default: ‘#f’)
          LE default connection supervision timeout.  This value is
          superseded by any specific value provided via the Load
          Connection Parameters interface.

     ‘autoconnect-timeout’ (default: ‘#f’)
          LE default autoconnect timeout.  This value is superseded by
          any specific value provided via the Load Connection Parameters
          interface.

     ‘adv-mon-allowlist-scan-duration’ (default: ‘300’)
          Allowlist scan duration during interleaving scan.  Only used
          when scanning for ADV monitors.  The units are msec.

     ‘adv-mon-no-filter-scan-duration’ (default: ‘500’)
          No filter scan duration during interleaving scan.  Only used
          when scanning for ADV monitors.  The units are msec.

     ‘enable-adv-mon-interleave-scan?’ (default: ‘#t’)
          Enable/Disable Advertisement Monitor interleave scan for power
          saving.

     ‘cache’ (default: ‘'always’)
          GATT attribute cache.

          Possible values are:
             • ‘'always’: Always cache attributes even for devices not
               paired, this is recommended as it is best for
               interoperability, with more consistent reconnection times
               and enables proper tracking of notifications for all
               devices

             • ‘'yes’: Only cache attributes of paired devices

             • ‘'no’: Never cache attributes.

     ‘key-size’ (default: ‘0’)
          Minimum required Encryption Key Size for accessing secured
          characteristics.

          Possible values are:
             • ‘0’: Don’t care

             • ‘7 <= N <= 16’

     ‘exchange-mtu’ (default: ‘517’)
          Exchange MTU size.  Possible values are:

             • ‘23 <= N <= 517’

     ‘att-channels’ (default: ‘3’)
          Number of ATT channels.  Possible values are:

             • ‘1’: Disables EATT

             • ‘2 <= N <= 5’

     ‘session-mode’ (default: ‘'basic’)
          AVDTP L2CAP signalling channel mode.

          Possible values are:

             • ‘'basic’: Use L2CAP basic mode

             • ‘'ertm’: Use L2CAP enhanced retransmission mode.

     ‘stream-mode’ (default: ‘'basic’)
          AVDTP L2CAP transport channel mode.

          Possible values are:

             • ‘'basic’: Use L2CAP basic mode

             • ‘'streaming’: Use L2CAP streaming mode.

     ‘reconnect-uuids’ (default: ‘'()’)
          The ReconnectUUIDs defines the set of remote services that
          should try to be reconnected to in case of a link loss (link
          supervision timeout).  The policy plugin should contain a sane
          set of values by default, but this list can be overridden
          here.  By setting the list to empty the reconnection feature
          gets disabled.

          Possible values:

             • ‘'()’

             • ‘(list (uuid <uuid-1>) (uuid <uuid-2>) ...)’.

     ‘reconnect-attempts’ (default: ‘7’)
          Defines the number of attempts to reconnect after a link lost.
          Setting the value to 0 disables reconnecting feature.

     ‘reconnect-intervals’ (default: ‘'(1 2 4 8 16 32 64)’)
          Defines a list of intervals in seconds to use in between
          attempts.  If the number of attempts defined in
          RECONNECT-ATTEMPTS is bigger than the list of intervals the
          last interval is repeated until the last attempt.

     ‘auto-enable?’ (default: ‘#f’)
          Defines option to enable all controllers when they are found.
          This includes adapters present on start as well as adapters
          that are plugged in later on.

     ‘resume-delay’ (default: ‘2’)
          Audio devices that were disconnected due to suspend will be
          reconnected on resume.  RESUME-DELAY determines the delay
          between when the controller resumes from suspend and a
          connection attempt is made.  A longer delay is better for
          better co-existence with Wi-Fi.  The value is in seconds.

     ‘rssi-sampling-period’ (default: ‘#xFF’)
          Default RSSI Sampling Period.  This is used when a client
          registers an advertisement monitor and leaves the
          RSSISamplingPeriod unset.

          Possible values are:
             • ‘#x0’: Report all advertisements

             • ‘N = #xXX’: Report advertisements every N x 100 msec
               (range: #x01 to #xFE)

             • ‘#xFF’: Report only one advertisement per device during
               monitoring period.

 -- Scheme Variable: gnome-keyring-service-type
     This is the type of the service that adds the GNOME Keyring
     (https://wiki.gnome.org/Projects/GnomeKeyring).  Its value is a
     ‘gnome-keyring-configuration’ object (see below).

     This service adds the ‘gnome-keyring’ package to the system profile
     and extends PAM with entries using ‘pam_gnome_keyring.so’,
     unlocking a user’s login keyring when they log in or setting its
     password with passwd.

 -- Data Type: gnome-keyring-configuration
     Configuration record for the GNOME Keyring service.

     ‘keyring’ (default: ‘gnome-keyring’)
          The GNOME keyring package to use.

     ‘pam-services’
          A list of ‘(SERVICE . KIND)’ pairs denoting PAM services to
          extend, where SERVICE is the name of an existing service to
          extend and KIND is one of ‘login’ or ‘passwd’.

          If ‘login’ is given, it adds an optional
          ‘pam_gnome_keyring.so’ to the auth block without arguments and
          to the session block with ‘auto_start’.  If ‘passwd’ is given,
          it adds an optional ‘pam_gnome_keyring.so’ to the password
          block without arguments.

          By default, this field contains “gdm-password” with the value
          ‘login’ and “passwd” is with the value ‘passwd’.

 -- Scheme Variable: seatd-service-type
     seatd (https://sr.ht/~kennylevinsen/seatd/) is a minimal seat
     management daemon.

     Seat management takes care of mediating access to shared devices
     (graphics, input), without requiring the applications needing
     access to be root.

          (append
            (list
             ;; make sure seatd is running
             (service seatd-service-type))

            ;; normally one would want %base-services
            %base-services)


     ‘seatd’ operates over a UNIX domain socket, with ‘libseat’
     providing the client side of the protocol.  Applications that
     acquire access to the shared resources via ‘seatd’ (e.g.  ‘sway’)
     need to be able to talk to this socket.  This can be achieved by
     adding the user they run under to the group owning ‘seatd’’s socket
     (usually “seat”), like so:

          (user-account
            (name "alice")
            (group "users")
            (supplementary-groups '("wheel"   ; allow use of sudo, etc.
                                    "seat"    ; seat management
                                    "audio"   ; sound card
                                    "video"   ; video devices such as webcams
                                    "cdrom")) ; the good ol' CD-ROM
            (comment "Bob's sister"))

     Depending on your setup, you will have to not only add regular
     users, but also system users to this group.  For instance, some
     greetd greeters require graphics and therefore also need to
     negotiate with seatd.

 -- Data Type: seatd-configuration
     Configuration record for the seatd daemon service.

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

     ‘group’ (default: ‘"seat"’)
          Group to own the seatd socket.

     ‘socket’ (default: ‘"/run/seatd.sock"’)
          Where to create the seatd socket.

     ‘logfile’ (default: ‘"/var/log/seatd.log"’)
          Log file to write to.

     ‘loglevel’ (default: ‘"error"’)
          Log level to output logs.  Possible values: ‘"silent"’,
          ‘"error"’, ‘"info"’ and ‘"debug"’.


File: guix.info,  Node: Sound Services,  Next: Database Services,  Prev: Desktop Services,  Up: Services

12.9.10 Sound Services
----------------------

The ‘(gnu services sound)’ module provides a service to configure the
Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio
the preferred ALSA output driver.

 -- Scheme Variable: alsa-service-type
     This is the type for the Advanced Linux Sound Architecture
     (https://alsa-project.org/) (ALSA) system, which generates the
     ‘/etc/asound.conf’ configuration file.  The value for this type is
     a ‘alsa-configuration’ record as in this example:

          (service alsa-service-type)

     See below for details about ‘alsa-configuration’.

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

     ‘alsa-plugins’ (default: ALSA-PLUGINS)
          ‘alsa-plugins’ package to use.

     ‘pulseaudio?’ (default: #T)
          Whether ALSA applications should transparently be made to use
          the PulseAudio (https://www.pulseaudio.org/) sound server.

          Using PulseAudio allows you to run several sound-producing
          applications at the same time and to individual control them
          via ‘pavucontrol’, among other things.

     ‘extra-options’ (default: "")
          String to append to the ‘/etc/asound.conf’ file.

   Individual users who want to override the system configuration of
ALSA can do it with the ‘~/.asoundrc’ file:

     # In guix, we have to specify the absolute path for plugins.
     pcm_type.jack {
       lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so"
     }

     # Routing ALSA to jack:
     # <http://jackaudio.org/faq/routing_alsa.html>.
     pcm.rawjack {
       type jack
       playback_ports {
         0 system:playback_1
         1 system:playback_2
       }

       capture_ports {
         0 system:capture_1
         1 system:capture_2
       }
     }

     pcm.!default {
       type plug
       slave {
         pcm "rawjack"
       }
     }

   See <https://www.alsa-project.org/main/index.php/Asoundrc> for the
details.

 -- Scheme Variable: pulseaudio-service-type
     This is the type for the PulseAudio (https://www.pulseaudio.org/)
     sound server.  It exists to allow system overrides of the default
     settings via ‘pulseaudio-configuration’, see below.

          Warning: This service overrides per-user configuration files.
          If you want PulseAudio to honor configuration files in
          ‘~/.config/pulse’ you have to unset the environment variables
          ‘PULSE_CONFIG’ and ‘PULSE_CLIENTCONFIG’ in your
          ‘~/.bash_profile’.

          Warning: This service on its own does not ensure, that the
          ‘pulseaudio’ package exists on your machine.  It merely adds
          configuration files for it, as detailed below.  In the
          (admittedly unlikely) case, that you find yourself without a
          ‘pulseaudio’ package, consider enabling it through the
          ‘alsa-service-type’ above.

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

     ‘client-conf’ (default: ‘'()’)
          List of settings to set in ‘client.conf’.  Accepts a list of
          strings or symbol-value pairs.  A string will be inserted
          as-is with a newline added.  A pair will be formatted as “key
          = value”, again with a newline added.

     ‘daemon-conf’ (default: ‘'((flat-volumes . no))’)
          List of settings to set in ‘daemon.conf’, formatted just like
          CLIENT-CONF.

     ‘script-file’ (default: ‘(file-append pulseaudio "/etc/pulse/default.pa")’)
          Script file to use as ‘default.pa’.  In case the
          ‘extra-script-files’ field below is used, an ‘.include’
          directive pointing to ‘/etc/pulse/default.pa.d’ is appended to
          the provided script.

     ‘extra-script-files’ (default: ‘'()’)
          A list of file-like objects defining extra PulseAudio scripts
          to run at the initialization of the ‘pulseaudio’ daemon, after
          the main ‘script-file’.  The scripts are deployed to the
          ‘/etc/pulse/default.pa.d’ directory; they should have the
          ‘.pa’ file name extension.  For a reference of the available
          commands, refer to ‘man pulse-cli-syntax’.

     ‘system-script-file’ (default: ‘(file-append pulseaudio "/etc/pulse/system.pa")’)
          Script file to use as ‘system.pa’.

     The example below sets the default PulseAudio card profile, the
     default sink and the default source to use for a old SoundBlaster
     Audigy sound card:
          (pulseaudio-configuration
           (extra-script-files
            (list (plain-file "audigy.pa"
                              (string-append "\
          set-card-profile alsa_card.pci-0000_01_01.0 \
            output:analog-surround-40+input:analog-mono
          set-default-source alsa_input.pci-0000_01_01.0.analog-mono
          set-default-sink alsa_output.pci-0000_01_01.0.analog-surround-40\n")))))

     Note that ‘pulseaudio-service-type’ is part of ‘%desktop-services’;
     if your operating system declaration was derived from one of the
     desktop templates, you’ll want to adjust the above example to
     modify the existing ‘pulseaudio-service-type’ via ‘modify-services’
     (*note ‘modify-services’: Service Reference.), instead of defining
     a new one.

 -- Scheme Variable: ladspa-service-type
     This service sets the LADSPA_PATH variable, so that programs, which
     respect it, e.g.  PulseAudio, can load LADSPA plugins.

     The following example will setup the service to enable modules from
     the ‘swh-plugins’ package:

          (service ladspa-service-type
                   (ladspa-configuration (plugins (list swh-plugins))))

     See <http://plugin.org.uk/ladspa-swh/docs/ladspa-swh.html> for the
     details.


File: guix.info,  Node: Database Services,  Next: Mail Services,  Prev: Sound Services,  Up: Services

12.9.11 Database Services
-------------------------

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

PostgreSQL
..........

The following example describes a PostgreSQL service with the default
configuration.

     (service postgresql-service-type
              (postgresql-configuration
               (postgresql postgresql-10)))

   If the services fails to start, it may be due to an incompatible
cluster already present in DATA-DIRECTORY.  Adjust it (or, if you don’t
need the cluster anymore, delete DATA-DIRECTORY), then restart the
service.

   Peer authentication is used by default and the ‘postgres’ user
account has no shell, which prevents the direct execution of ‘psql’
commands as this user.  To use ‘psql’, you can temporarily log in as
‘postgres’ using a shell, create a PostgreSQL superuser with the same
name as one of the system users and then create the associated database.

     sudo -u postgres -s /bin/sh
     createuser --interactive
     createdb $MY_USER_LOGIN      # Replace appropriately.

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

     ‘postgresql’
          PostgreSQL package to use for the service.

     ‘port’ (default: ‘5432’)
          Port on which PostgreSQL should listen.

     ‘locale’ (default: ‘"en_US.utf8"’)
          Locale to use as the default when creating the database
          cluster.

     ‘config-file’ (default: ‘(postgresql-config-file)’)
          The configuration file to use when running PostgreSQL.  The
          default behaviour uses the postgresql-config-file record with
          the default values for the fields.

     ‘log-directory’ (default: ‘"/var/log/postgresql"’)
          The directory where ‘pg_ctl’ output will be written in a file
          named ‘"pg_ctl.log"’.  This file can be useful to debug
          PostgreSQL configuration errors for instance.

     ‘data-directory’ (default: ‘"/var/lib/postgresql/data"’)
          Directory in which to store the data.

     ‘extension-packages’ (default: ‘'()’)
          Additional extensions are loaded from packages listed in
          EXTENSION-PACKAGES.  Extensions are available at runtime.  For
          instance, to create a geographic database using the ‘postgis’
          extension, a user can configure the postgresql-service as in
          this example:

               (use-package-modules databases geo)

               (operating-system
                 ...
                 ;; postgresql is required to run `psql' but postgis is not required for
                 ;; proper operation.
                 (packages (cons* postgresql %base-packages))
                 (services
                   (cons*
                     (service postgresql-service-type
                              (postgresql-configuration
                               (postgresql postgresql-10)
                               (extension-packages (list postgis))))
                     %base-services)))

          Then the extension becomes visible and you can initialise an
          empty geographic database in this way:

               psql -U postgres
               > create database postgistest;
               > \connect postgistest;
               > create extension postgis;
               > create extension postgis_topology;

          There is no need to add this field for contrib extensions such
          as hstore or dblink as they are already loadable by
          postgresql.  This field is only required to add extensions
          provided by other packages.

 -- Data Type: postgresql-config-file
     Data type representing the PostgreSQL configuration file.  As shown
     in the following example, this can be used to customize the
     configuration of PostgreSQL.  Note that you can use any
     G-expression or filename in place of this record, if you already
     have a configuration file you’d like to use for example.

          (service postgresql-service-type
                   (postgresql-configuration
                    (config-file
                     (postgresql-config-file
                      (log-destination "stderr")
                      (hba-file
                       (plain-file "pg_hba.conf"
                                   "
          local	all	all			trust
          host	all	all	127.0.0.1/32 	md5
          host	all	all	::1/128 	md5"))
                      (extra-config
                       '(("session_preload_libraries"     "auto_explain")
                         ("random_page_cost"              2)
                         ("auto_explain.log_min_duration" "100 ms")
                         ("work_mem"                      "500 MB")
                         ("logging_collector"             #t)
                         ("log_directory"                 "/var/log/postgresql")))))))

     ‘log-destination’ (default: ‘"syslog"’)
          The logging method to use for PostgreSQL.  Multiple values are
          accepted, separated by commas.

     ‘hba-file’ (default: ‘%default-postgres-hba’)
          Filename or G-expression for the host-based authentication
          configuration.

     ‘ident-file’ (default: ‘%default-postgres-ident’)
          Filename or G-expression for the user name mapping
          configuration.

     ‘socket-directory’ (default: ‘"/var/run/postgresql"’)
          Specifies the directory of the Unix-domain socket(s) on which
          PostgreSQL is to listen for connections from client
          applications.  If set to ‘""’ PostgreSQL does not listen on
          any Unix-domain sockets, in which case only TCP/IP sockets can
          be used to connect to the server.

          By default, the ‘#false’ value means the PostgreSQL default
          value will be used, which is currently ‘/tmp’.

     ‘extra-config’ (default: ‘'()’)
          List of additional keys and values to include in the
          PostgreSQL config file.  Each entry in the list should be a
          list where the first element is the key, and the remaining
          elements are the values.

          The values can be numbers, booleans or strings and will be
          mapped to PostgreSQL parameters types ‘Boolean’, ‘String’,
          ‘Numeric’, ‘Numeric with Unit’ and ‘Enumerated’ described here
          (https://www.postgresql.org/docs/current/config-setting.html).

 -- Scheme Variable: postgresql-role-service-type
     This service allows to create PostgreSQL roles and databases after
     PostgreSQL service start.  Here is an example of its use.

          (service postgresql-role-service-type
                      (postgresql-role-configuration
                       (roles
                        (list (postgresql-role
                               (name "test")
                               (create-database? #t))))))

     This service can be extended with extra roles, as in this example:

          (service-extension postgresql-role-service-type
                             (const (postgresql-role
                                     (name "alice")
                                     (create-database? #t))))

 -- Data Type: postgresql-role
     PostgreSQL manages database access permissions using the concept of
     roles.  A role can be thought of as either a database user, or a
     group of database users, depending on how the role is set up.
     Roles can own database objects (for example, tables) and can assign
     privileges on those objects to other roles to control who has
     access to which objects.

     ‘name’
          The role name.

     ‘permissions’ (default: ‘'(createdb login)’)
          The role permissions list.  Supported permissions are
          ‘bypassrls’, ‘createdb’, ‘createrole’, ‘login’, ‘replication’
          and ‘superuser’.

     ‘create-database?’ (default: ‘#f’)
          Whether to create a database with the same name as the role.

 -- Data Type: postgresql-role-configuration
     Data type representing the configuration of
     POSTGRESQL-ROLE-SERVICE-TYPE.

     ‘host’ (default: ‘"/var/run/postgresql"’)
          The PostgreSQL host to connect to.

     ‘log’ (default: ‘"/var/log/postgresql_roles.log"’)
          File name of the log file.

     ‘roles’ (default: ‘'()’)
          The initial PostgreSQL roles to create.

MariaDB/MySQL
.............

 -- Scheme Variable: mysql-service-type
     This is the service type for a MySQL or MariaDB database server.
     Its value is a ‘mysql-configuration’ object that specifies which
     package to use, as well as various settings for the ‘mysqld’
     daemon.

 -- Data Type: mysql-configuration
     Data type representing the configuration of MYSQL-SERVICE-TYPE.

     ‘mysql’ (default: MARIADB)
          Package object of the MySQL database server, can be either
          MARIADB or MYSQL.

          For MySQL, a temporary root password will be displayed at
          activation time.  For MariaDB, the root password is empty.

     ‘bind-address’ (default: ‘"127.0.0.1"’)
          The IP on which to listen for network connections.  Use
          ‘"0.0.0.0"’ to bind to all available network interfaces.

     ‘port’ (default: ‘3306’)
          TCP port on which the database server listens for incoming
          connections.

     ‘socket’ (default: ‘"/run/mysqld/mysqld.sock"’)
          Socket file to use for local (non-network) connections.

     ‘extra-content’ (default: ‘""’)
          Additional settings for the ‘my.cnf’ configuration file.

     ‘extra-environment’ (default: ‘#~'()’)
          List of environment variables passed to the ‘mysqld’ process.

     ‘auto-upgrade?’ (default: ‘#t’)
          Whether to automatically run ‘mysql_upgrade’ after starting
          the service.  This is necessary to upgrade the “system schema”
          after “major” updates (such as switching from MariaDB 10.4 to
          10.5), but can be disabled if you would rather do that
          manually.

Memcached
.........

 -- Scheme Variable: memcached-service-type
     This is the service type for the Memcached (https://memcached.org/)
     service, which provides a distributed in memory cache.  The value
     for the service type is a ‘memcached-configuration’ object.

     (service memcached-service-type)

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

     ‘memcached’ (default: ‘memcached’)
          The Memcached package to use.

     ‘interfaces’ (default: ‘'("0.0.0.0")’)
          Network interfaces on which to listen.

     ‘tcp-port’ (default: ‘11211’)
          Port on which to accept connections.

     ‘udp-port’ (default: ‘11211’)
          Port on which to accept UDP connections on, a value of 0 will
          disable listening on a UDP socket.

     ‘additional-options’ (default: ‘'()’)
          Additional command line options to pass to ‘memcached’.

Redis
.....

 -- Scheme Variable: redis-service-type
     This is the service type for the Redis (https://redis.io/)
     key/value store, whose value is a ‘redis-configuration’ object.

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

     ‘redis’ (default: ‘redis’)
          The Redis package to use.

     ‘bind’ (default: ‘"127.0.0.1"’)
          Network interface on which to listen.

     ‘port’ (default: ‘6379’)
          Port on which to accept connections on, a value of 0 will
          disable listening on a TCP socket.

     ‘working-directory’ (default: ‘"/var/lib/redis"’)
          Directory in which to store the database and related files.


File: guix.info,  Node: Mail Services,  Next: Messaging Services,  Prev: Database Services,  Up: Services

12.9.12 Mail Services
---------------------

The ‘(gnu services mail)’ module provides Guix service definitions for
email services: IMAP, POP3, and LMTP servers, as well as mail transport
agents (MTAs).  Lots of acronyms!  These services are detailed in the
subsections below.

Dovecot Service
...............

 -- Scheme Procedure: dovecot-service [#:config (dovecot-configuration)]
     Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.

   By default, Dovecot does not need much configuration; the default
configuration object created by ‘(dovecot-configuration)’ will suffice
if your mail is delivered to ‘~/Maildir’.  A self-signed certificate
will be generated for TLS-protected connections, though Dovecot will
also listen on cleartext ports by default.  There are a number of
options, though, which mail administrators might need to change, and as
is the case with other services, Guix allows the system administrator to
specify these parameters via a uniform Scheme interface.

   For example, to specify that mail is located at ‘maildir~/.mail’, one
would instantiate the Dovecot service like this:

     (dovecot-service #:config
                      (dovecot-configuration
                       (mail-location "maildir:~/.mail")))

   The available configuration parameters follow.  Each parameter
definition is preceded by its type; for example, ‘string-list foo’
indicates that the ‘foo’ parameter should be specified as a list of
strings.  There is also a way to specify the configuration as a string,
if you have an old ‘dovecot.conf’ file that you want to port over from
some other system; see the end for more details.

   Available ‘dovecot-configuration’ fields are:

 -- ‘dovecot-configuration’ parameter: package dovecot
     The dovecot package.

 -- ‘dovecot-configuration’ parameter: comma-separated-string-list
          listen
     A list of IPs or hosts where to listen for connections.  ‘*’
     listens on all IPv4 interfaces, ‘::’ listens on all IPv6
     interfaces.  If you want to specify non-default ports or anything
     more complex, customize the address and port fields of the
     ‘inet-listener’ of the specific services you are interested in.

 -- ‘dovecot-configuration’ parameter: protocol-configuration-list
          protocols
     List of protocols we want to serve.  Available protocols include
     ‘imap’, ‘pop3’, and ‘lmtp’.

     Available ‘protocol-configuration’ fields are:

      -- ‘protocol-configuration’ parameter: string name
          The name of the protocol.

      -- ‘protocol-configuration’ parameter: string auth-socket-path
          UNIX socket path to the master authentication server to find
          users.  This is used by imap (for shared users) and lda.  It
          defaults to ‘"/var/run/dovecot/auth-userdb"’.

      -- ‘protocol-configuration’ parameter: boolean imap-metadata?
          Whether to enable the ‘IMAP METADATA’ extension as defined in
          RFC 5464 (https://tools.ietf.org/html/rfc5464), which provides
          a means for clients to set and retrieve per-mailbox, per-user
          metadata and annotations over IMAP.

          If this is ‘#t’, you must also specify a dictionary via the
          ‘mail-attribute-dict’ setting.

          Defaults to ‘#f’.

      -- ‘protocol-configuration’ parameter: space-separated-string-list
               managesieve-notify-capabilities
          Which NOTIFY capabilities to report to clients that first
          connect to the ManageSieve service, before authentication.
          These may differ from the capabilities offered to
          authenticated users.  If this field is left empty, report what
          the Sieve interpreter supports by default.

          Defaults to ‘()’.

      -- ‘protocol-configuration’ parameter: space-separated-string-list
               managesieve-sieve-capability
          Which SIEVE capabilities to report to clients that first
          connect to the ManageSieve service, before authentication.
          These may differ from the capabilities offered to
          authenticated users.  If this field is left empty, report what
          the Sieve interpreter supports by default.

          Defaults to ‘()’.

      -- ‘protocol-configuration’ parameter: space-separated-string-list
               mail-plugins
          Space separated list of plugins to load.

      -- ‘protocol-configuration’ parameter: non-negative-integer
               mail-max-userip-connections
          Maximum number of IMAP connections allowed for a user from
          each IP address.  NOTE: The username is compared
          case-sensitively.  Defaults to ‘10’.

 -- ‘dovecot-configuration’ parameter: service-configuration-list
          services
     List of services to enable.  Available services include ‘imap’,
     ‘imap-login’, ‘pop3’, ‘pop3-login’, ‘auth’, and ‘lmtp’.

     Available ‘service-configuration’ fields are:

      -- ‘service-configuration’ parameter: string kind
          The service kind.  Valid values include ‘director’,
          ‘imap-login’, ‘pop3-login’, ‘lmtp’, ‘imap’, ‘pop3’, ‘auth’,
          ‘auth-worker’, ‘dict’, ‘tcpwrap’, ‘quota-warning’, or anything
          else.

      -- ‘service-configuration’ parameter: listener-configuration-list
               listeners
          Listeners for the service.  A listener is either a
          ‘unix-listener-configuration’, a
          ‘fifo-listener-configuration’, or an
          ‘inet-listener-configuration’.  Defaults to ‘()’.

          Available ‘unix-listener-configuration’ fields are:

           -- ‘unix-listener-configuration’ parameter: string path
               Path to the file, relative to ‘base-dir’ field.  This is
               also used as the section name.

           -- ‘unix-listener-configuration’ parameter: string mode
               The access mode for the socket.  Defaults to ‘"0600"’.

           -- ‘unix-listener-configuration’ parameter: string user
               The user to own the socket.  Defaults to ‘""’.

           -- ‘unix-listener-configuration’ parameter: string group
               The group to own the socket.  Defaults to ‘""’.

          Available ‘fifo-listener-configuration’ fields are:

           -- ‘fifo-listener-configuration’ parameter: string path
               Path to the file, relative to ‘base-dir’ field.  This is
               also used as the section name.

           -- ‘fifo-listener-configuration’ parameter: string mode
               The access mode for the socket.  Defaults to ‘"0600"’.

           -- ‘fifo-listener-configuration’ parameter: string user
               The user to own the socket.  Defaults to ‘""’.

           -- ‘fifo-listener-configuration’ parameter: string group
               The group to own the socket.  Defaults to ‘""’.

          Available ‘inet-listener-configuration’ fields are:

           -- ‘inet-listener-configuration’ parameter: string protocol
               The protocol to listen for.

           -- ‘inet-listener-configuration’ parameter: string address
               The address on which to listen, or empty for all
               addresses.  Defaults to ‘""’.

           -- ‘inet-listener-configuration’ parameter:
                    non-negative-integer port
               The port on which to listen.

           -- ‘inet-listener-configuration’ parameter: boolean ssl?
               Whether to use SSL for this service; ‘yes’, ‘no’, or
               ‘required’.  Defaults to ‘#t’.

      -- ‘service-configuration’ parameter: non-negative-integer
               client-limit
          Maximum number of simultaneous client connections per process.
          Once this number of connections is received, the next incoming
          connection will prompt Dovecot to spawn another process.  If
          set to 0, ‘default-client-limit’ is used instead.

          Defaults to ‘0’.

      -- ‘service-configuration’ parameter: non-negative-integer
               service-count
          Number of connections to handle before starting a new process.
          Typically the only useful values are 0 (unlimited) or 1.  1 is
          more secure, but 0 is faster.  <doc/wiki/LoginProcess.txt>.
          Defaults to ‘1’.

      -- ‘service-configuration’ parameter: non-negative-integer
               process-limit
          Maximum number of processes that can exist for this service.
          If set to 0, ‘default-process-limit’ is used instead.

          Defaults to ‘0’.

      -- ‘service-configuration’ parameter: non-negative-integer
               process-min-avail
          Number of processes to always keep waiting for more
          connections.  Defaults to ‘0’.

      -- ‘service-configuration’ parameter: non-negative-integer
               vsz-limit
          If you set ‘service-count 0’, you probably need to grow this.
          Defaults to ‘256000000’.

 -- ‘dovecot-configuration’ parameter: dict-configuration dict
     Dict configuration, as created by the ‘dict-configuration’
     constructor.

     Available ‘dict-configuration’ fields are:

      -- ‘dict-configuration’ parameter: free-form-fields entries
          A list of key-value pairs that this dict should hold.
          Defaults to ‘()’.

 -- ‘dovecot-configuration’ parameter: passdb-configuration-list passdbs
     A list of passdb configurations, each one created by the
     ‘passdb-configuration’ constructor.

     Available ‘passdb-configuration’ fields are:

      -- ‘passdb-configuration’ parameter: string driver
          The driver that the passdb should use.  Valid values include
          ‘pam’, ‘passwd’, ‘shadow’, ‘bsdauth’, and ‘static’.  Defaults
          to ‘"pam"’.

      -- ‘passdb-configuration’ parameter: space-separated-string-list
               args
          Space separated list of arguments to the passdb driver.
          Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: userdb-configuration-list userdbs
     List of userdb configurations, each one created by the
     ‘userdb-configuration’ constructor.

     Available ‘userdb-configuration’ fields are:

      -- ‘userdb-configuration’ parameter: string driver
          The driver that the userdb should use.  Valid values include
          ‘passwd’ and ‘static’.  Defaults to ‘"passwd"’.

      -- ‘userdb-configuration’ parameter: space-separated-string-list
               args
          Space separated list of arguments to the userdb driver.
          Defaults to ‘""’.

      -- ‘userdb-configuration’ parameter: free-form-args
               override-fields
          Override fields from passwd.  Defaults to ‘()’.

 -- ‘dovecot-configuration’ parameter: plugin-configuration
          plugin-configuration
     Plug-in configuration, created by the ‘plugin-configuration’
     constructor.

 -- ‘dovecot-configuration’ parameter: list-of-namespace-configuration
          namespaces
     List of namespaces.  Each item in the list is created by the
     ‘namespace-configuration’ constructor.

     Available ‘namespace-configuration’ fields are:

      -- ‘namespace-configuration’ parameter: string name
          Name for this namespace.

      -- ‘namespace-configuration’ parameter: string type
          Namespace type: ‘private’, ‘shared’ or ‘public’.  Defaults to
          ‘"private"’.

      -- ‘namespace-configuration’ parameter: string separator
          Hierarchy separator to use.  You should use the same separator
          for all namespaces or some clients get confused.  ‘/’ is
          usually a good one.  The default however depends on the
          underlying mail storage format.  Defaults to ‘""’.

      -- ‘namespace-configuration’ parameter: string prefix
          Prefix required to access this namespace.  This needs to be
          different for all namespaces.  For example ‘Public/’.
          Defaults to ‘""’.

      -- ‘namespace-configuration’ parameter: string location
          Physical location of the mailbox.  This is in the same format
          as mail_location, which is also the default for it.  Defaults
          to ‘""’.

      -- ‘namespace-configuration’ parameter: boolean inbox?
          There can be only one INBOX, and this setting defines which
          namespace has it.  Defaults to ‘#f’.

      -- ‘namespace-configuration’ parameter: boolean hidden?
          If namespace is hidden, it’s not advertised to clients via
          NAMESPACE extension.  You’ll most likely also want to set
          ‘list? #f’.  This is mostly useful when converting from
          another server with different namespaces which you want to
          deprecate but still keep working.  For example you can create
          hidden namespaces with prefixes ‘~/mail/’, ‘~%u/mail/’ and
          ‘mail/’.  Defaults to ‘#f’.

      -- ‘namespace-configuration’ parameter: boolean list?
          Show the mailboxes under this namespace with the LIST command.
          This makes the namespace visible for clients that do not
          support the NAMESPACE extension.  The special ‘children’ value
          lists child mailboxes, but hides the namespace prefix.
          Defaults to ‘#t’.

      -- ‘namespace-configuration’ parameter: boolean subscriptions?
          Namespace handles its own subscriptions.  If set to ‘#f’, the
          parent namespace handles them.  The empty prefix should always
          have this as ‘#t’).  Defaults to ‘#t’.

      -- ‘namespace-configuration’ parameter: mailbox-configuration-list
               mailboxes
          List of predefined mailboxes in this namespace.  Defaults to
          ‘()’.

          Available ‘mailbox-configuration’ fields are:

           -- ‘mailbox-configuration’ parameter: string name
               Name for this mailbox.

           -- ‘mailbox-configuration’ parameter: string auto
               ‘create’ will automatically create this mailbox.
               ‘subscribe’ will both create and subscribe to the
               mailbox.  Defaults to ‘"no"’.

           -- ‘mailbox-configuration’ parameter:
                    space-separated-string-list special-use
               List of IMAP ‘SPECIAL-USE’ attributes as specified by RFC
               6154.  Valid values are ‘\All’, ‘\Archive’, ‘\Drafts’,
               ‘\Flagged’, ‘\Junk’, ‘\Sent’, and ‘\Trash’.  Defaults to
               ‘()’.

 -- ‘dovecot-configuration’ parameter: file-name base-dir
     Base directory where to store runtime data.  Defaults to
     ‘"/var/run/dovecot/"’.

 -- ‘dovecot-configuration’ parameter: string login-greeting
     Greeting message for clients.  Defaults to ‘"Dovecot ready."’.

 -- ‘dovecot-configuration’ parameter: space-separated-string-list
          login-trusted-networks
     List of trusted network ranges.  Connections from these IPs are
     allowed to override their IP addresses and ports (for logging and
     for authentication checks).  ‘disable-plaintext-auth’ is also
     ignored for these networks.  Typically you would specify your IMAP
     proxy servers here.  Defaults to ‘()’.

 -- ‘dovecot-configuration’ parameter: space-separated-string-list
          login-access-sockets
     List of login access check sockets (e.g. tcpwrap).  Defaults to
     ‘()’.

 -- ‘dovecot-configuration’ parameter: boolean verbose-proctitle?
     Show more verbose process titles (in ps).  Currently shows user
     name and IP address.  Useful for seeing who is actually using the
     IMAP processes (e.g. shared mailboxes or if the same uid is used
     for multiple accounts).  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: boolean shutdown-clients?
     Should all processes be killed when Dovecot master process shuts
     down.  Setting this to ‘#f’ means that Dovecot can be upgraded
     without forcing existing client connections to close (although that
     could also be a problem if the upgrade is e.g. due to a security
     fix).  Defaults to ‘#t’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          doveadm-worker-count
     If non-zero, run mail commands via this many connections to doveadm
     server, instead of running them directly in the same process.
     Defaults to ‘0’.

 -- ‘dovecot-configuration’ parameter: string doveadm-socket-path
     UNIX socket or host:port used for connecting to doveadm server.
     Defaults to ‘"doveadm-server"’.

 -- ‘dovecot-configuration’ parameter: space-separated-string-list
          import-environment
     List of environment variables that are preserved on Dovecot startup
     and passed down to all of its child processes.  You can also give
     key=value pairs to always set specific settings.

 -- ‘dovecot-configuration’ parameter: boolean disable-plaintext-auth?
     Disable LOGIN command and all other plaintext authentications
     unless SSL/TLS is used (LOGINDISABLED capability).  Note that if
     the remote IP matches the local IP (i.e. you’re connecting from the
     same computer), the connection is considered secure and plaintext
     authentication is allowed.  See also ssl=required setting.
     Defaults to ‘#t’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          auth-cache-size
     Authentication cache size (e.g. ‘#e10e6’).  0 means it’s disabled.
     Note that bsdauth, PAM and vpopmail require ‘cache-key’ to be set
     for caching to be used.  Defaults to ‘0’.

 -- ‘dovecot-configuration’ parameter: string auth-cache-ttl
     Time to live for cached data.  After TTL expires the cached record
     is no longer used, *except* if the main database lookup returns
     internal failure.  We also try to handle password changes
     automatically: If user’s previous authentication was successful,
     but this one wasn’t, the cache isn’t used.  For now this works only
     with plaintext authentication.  Defaults to ‘"1 hour"’.

 -- ‘dovecot-configuration’ parameter: string auth-cache-negative-ttl
     TTL for negative hits (user not found, password mismatch).  0
     disables caching them completely.  Defaults to ‘"1 hour"’.

 -- ‘dovecot-configuration’ parameter: space-separated-string-list
          auth-realms
     List of realms for SASL authentication mechanisms that need them.
     You can leave it empty if you don’t want to support multiple
     realms.  Many clients simply use the first one listed here, so keep
     the default realm first.  Defaults to ‘()’.

 -- ‘dovecot-configuration’ parameter: string auth-default-realm
     Default realm/domain to use if none was specified.  This is used
     for both SASL realms and appending @domain to username in plaintext
     logins.  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string auth-username-chars
     List of allowed characters in username.  If the user-given username
     contains a character not listed in here, the login automatically
     fails.  This is just an extra check to make sure user can’t exploit
     any potential quote escaping vulnerabilities with SQL/LDAP
     databases.  If you want to allow all characters, set this value to
     empty.  Defaults to
     ‘"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@"’.

 -- ‘dovecot-configuration’ parameter: string auth-username-translation
     Username character translations before it’s looked up from
     databases.  The value contains series of from -> to characters.
     For example ‘#@/@’ means that ‘#’ and ‘/’ characters are translated
     to ‘@’.  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string auth-username-format
     Username formatting before it’s looked up from databases.  You can
     use the standard variables here, e.g. %Lu would lowercase the
     username, %n would drop away the domain if it was given, or
     ‘%n-AT-%d’ would change the ‘@’ into ‘-AT-’.  This translation is
     done after ‘auth-username-translation’ changes.  Defaults to
     ‘"%Lu"’.

 -- ‘dovecot-configuration’ parameter: string auth-master-user-separator
     If you want to allow master users to log in by specifying the
     master username within the normal username string (i.e. not using
     SASL mechanism’s support for it), you can specify the separator
     character here.  The format is then <username><separator><master
     username>.  UW-IMAP uses ‘*’ as the separator, so that could be a
     good choice.  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string auth-anonymous-username
     Username to use for users logging in with ANONYMOUS SASL mechanism.
     Defaults to ‘"anonymous"’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          auth-worker-max-count
     Maximum number of dovecot-auth worker processes.  They’re used to
     execute blocking passdb and userdb queries (e.g. MySQL and PAM).
     They’re automatically created and destroyed as needed.  Defaults to
     ‘30’.

 -- ‘dovecot-configuration’ parameter: string auth-gssapi-hostname
     Host name to use in GSSAPI principal names.  The default is to use
     the name returned by gethostname().  Use ‘$ALL’ (with quotes) to
     allow all keytab entries.  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string auth-krb5-keytab
     Kerberos keytab to use for the GSSAPI mechanism.  Will use the
     system default (usually ‘/etc/krb5.keytab’) if not specified.  You
     may need to change the auth service to run as root to be able to
     read this file.  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: boolean auth-use-winbind?
     Do NTLM and GSS-SPNEGO authentication using Samba’s winbind daemon
     and ‘ntlm-auth’ helper.
     <doc/wiki/Authentication/Mechanisms/Winbind.txt>.  Defaults to
     ‘#f’.

 -- ‘dovecot-configuration’ parameter: file-name
          auth-winbind-helper-path
     Path for Samba’s ‘ntlm-auth’ helper binary.  Defaults to
     ‘"/usr/bin/ntlm_auth"’.

 -- ‘dovecot-configuration’ parameter: string auth-failure-delay
     Time to delay before replying to failed authentications.  Defaults
     to ‘"2 secs"’.

 -- ‘dovecot-configuration’ parameter: boolean
          auth-ssl-require-client-cert?
     Require a valid SSL client certificate or the authentication fails.
     Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: boolean
          auth-ssl-username-from-cert?
     Take the username from client’s SSL certificate, using
     ‘X509_NAME_get_text_by_NID()’ which returns the subject’s DN’s
     CommonName.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: space-separated-string-list
          auth-mechanisms
     List of wanted authentication mechanisms.  Supported mechanisms
     are: ‘plain’, ‘login’, ‘digest-md5’, ‘cram-md5’, ‘ntlm’, ‘rpa’,
     ‘apop’, ‘anonymous’, ‘gssapi’, ‘otp’, ‘skey’, and ‘gss-spnego’.
     NOTE: See also ‘disable-plaintext-auth’ setting.

 -- ‘dovecot-configuration’ parameter: space-separated-string-list
          director-servers
     List of IPs or hostnames to all director servers, including
     ourself.  Ports can be specified as ip:port.  The default port is
     the same as what director service’s ‘inet-listener’ is using.
     Defaults to ‘()’.

 -- ‘dovecot-configuration’ parameter: space-separated-string-list
          director-mail-servers
     List of IPs or hostnames to all backend mail servers.  Ranges are
     allowed too, like 10.0.0.10-10.0.0.30.  Defaults to ‘()’.

 -- ‘dovecot-configuration’ parameter: string director-user-expire
     How long to redirect users to a specific server after it no longer
     has any connections.  Defaults to ‘"15 min"’.

 -- ‘dovecot-configuration’ parameter: string director-username-hash
     How the username is translated before being hashed.  Useful values
     include %Ln if user can log in with or without @domain, %Ld if
     mailboxes are shared within domain.  Defaults to ‘"%Lu"’.

 -- ‘dovecot-configuration’ parameter: string log-path
     Log file to use for error messages.  ‘syslog’ logs to syslog,
     ‘/dev/stderr’ logs to stderr.  Defaults to ‘"syslog"’.

 -- ‘dovecot-configuration’ parameter: string info-log-path
     Log file to use for informational messages.  Defaults to
     ‘log-path’.  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string debug-log-path
     Log file to use for debug messages.  Defaults to ‘info-log-path’.
     Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string syslog-facility
     Syslog facility to use if you’re logging to syslog.  Usually if you
     don’t want to use ‘mail’, you’ll use local0..local7.  Also other
     standard facilities are supported.  Defaults to ‘"mail"’.

 -- ‘dovecot-configuration’ parameter: boolean auth-verbose?
     Log unsuccessful authentication attempts and the reasons why they
     failed.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: string auth-verbose-passwords
     In case of password mismatches, log the attempted password.  Valid
     values are no, plain and sha1.  sha1 can be useful for detecting
     brute force password attempts vs.  user simply trying the same
     password over and over again.  You can also truncate the value to n
     chars by appending ":n" (e.g. sha1:6).  Defaults to ‘"no"’.

 -- ‘dovecot-configuration’ parameter: boolean auth-debug?
     Even more verbose logging for debugging purposes.  Shows for
     example SQL queries.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: boolean auth-debug-passwords?
     In case of password mismatches, log the passwords and used scheme
     so the problem can be debugged.  Enabling this also enables
     ‘auth-debug’.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: boolean mail-debug?
     Enable mail process debugging.  This can help you figure out why
     Dovecot isn’t finding your mails.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: boolean verbose-ssl?
     Show protocol level SSL errors.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: string log-timestamp
     Prefix for each line written to log file.  % codes are in
     strftime(3) format.  Defaults to ‘"\"%b %d %H:%M:%S \""’.

 -- ‘dovecot-configuration’ parameter: space-separated-string-list
          login-log-format-elements
     List of elements we want to log.  The elements which have a
     non-empty variable value are joined together to form a
     comma-separated string.

 -- ‘dovecot-configuration’ parameter: string login-log-format
     Login log format.  %s contains ‘login-log-format-elements’ string,
     %$ contains the data we want to log.  Defaults to ‘"%$: %s"’.

 -- ‘dovecot-configuration’ parameter: string mail-log-prefix
     Log prefix for mail processes.  See doc/wiki/Variables.txt for list
     of possible variables you can use.  Defaults to
     ‘"\"%s(%u)<%{pid}><%{session}>: \""’.

 -- ‘dovecot-configuration’ parameter: string deliver-log-format
     Format to use for logging mail deliveries.  You can use variables:
     ‘%$’
          Delivery status message (e.g. ‘saved to INBOX’)
     ‘%m’
          Message-ID
     ‘%s’
          Subject
     ‘%f’
          From address
     ‘%p’
          Physical size
     ‘%w’
          Virtual size.
     Defaults to ‘"msgid=%m: %$"’.

 -- ‘dovecot-configuration’ parameter: string mail-location
     Location for users’ mailboxes.  The default is empty, which means
     that Dovecot tries to find the mailboxes automatically.  This won’t
     work if the user doesn’t yet have any mail, so you should
     explicitly tell Dovecot the full location.

     If you’re using mbox, giving a path to the INBOX file (e.g.
     ‘/var/mail/%u’) isn’t enough.  You’ll also need to tell Dovecot
     where the other mailboxes are kept.  This is called the _root mail
     directory_, and it must be the first path given in the
     ‘mail-location’ setting.

     There are a few special variables you can use, e.g.:

     ‘%u’
          username
     ‘%n’
          user part in user@domain, same as %u if there’s no domain
     ‘%d’
          domain part in user@domain, empty if there’s no domain
     ‘%h’
          home director

     See doc/wiki/Variables.txt for full list.  Some examples:
     ‘maildir:~/Maildir’
     ‘mbox:~/mail:INBOX=/var/mail/%u’
     ‘mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%’
     Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string mail-uid
     System user and group used to access mails.  If you use multiple,
     userdb can override these by returning uid or gid fields.  You can
     use either numbers or names.  <doc/wiki/UserIds.txt>.  Defaults to
     ‘""’.

 -- ‘dovecot-configuration’ parameter: string mail-gid

     Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string mail-privileged-group
     Group to enable temporarily for privileged operations.  Currently
     this is used only with INBOX when either its initial creation or
     dotlocking fails.  Typically this is set to ‘"mail"’ to give access
     to ‘/var/mail’.  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string mail-access-groups
     Grant access to these supplementary groups for mail processes.
     Typically these are used to set up access to shared mailboxes.
     Note that it may be dangerous to set these if users can create
     symlinks (e.g. if ‘mail’ group is set here, ‘ln -s /var/mail
     ~/mail/var’ could allow a user to delete others’ mailboxes, or ‘ln
     -s /secret/shared/box ~/mail/mybox’ would allow reading it).
     Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string mail-attribute-dict
     The location of a dictionary used to store ‘IMAP METADATA’ as
     defined by RFC 5464 (https://tools.ietf.org/html/rfc5464).

     The IMAP METADATA commands are available only if the “imap”
     protocol configuration’s ‘imap-metadata?’ field is ‘#t’.

     Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: boolean
          mail-full-filesystem-access?
     Allow full file system access to clients.  There’s no access checks
     other than what the operating system does for the active UID/GID.
     It works with both maildir and mboxes, allowing you to prefix
     mailboxes names with e.g. ‘/path/’ or ‘~user/’.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: boolean mmap-disable?
     Don’t use ‘mmap()’ at all.  This is required if you store indexes
     to shared file systems (NFS or clustered file system).  Defaults to
     ‘#f’.

 -- ‘dovecot-configuration’ parameter: boolean dotlock-use-excl?
     Rely on ‘O_EXCL’ to work when creating dotlock files.  NFS supports
     ‘O_EXCL’ since version 3, so this should be safe to use nowadays by
     default.  Defaults to ‘#t’.

 -- ‘dovecot-configuration’ parameter: string mail-fsync
     When to use fsync() or fdatasync() calls:
     ‘optimized’
          Whenever necessary to avoid losing important data
     ‘always’
          Useful with e.g. NFS when ‘write()’s are delayed
     ‘never’
          Never use it (best performance, but crashes can lose data).
     Defaults to ‘"optimized"’.

 -- ‘dovecot-configuration’ parameter: boolean mail-nfs-storage?
     Mail storage exists in NFS.  Set this to yes to make Dovecot flush
     NFS caches whenever needed.  If you’re using only a single mail
     server this isn’t needed.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: boolean mail-nfs-index?
     Mail index files also exist in NFS.  Setting this to yes requires
     ‘mmap-disable? #t’ and ‘fsync-disable? #f’.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: string lock-method
     Locking method for index files.  Alternatives are fcntl, flock and
     dotlock.  Dotlocking uses some tricks which may create more disk
     I/O than other locking methods.  NFS users: flock doesn’t work,
     remember to change ‘mmap-disable’.  Defaults to ‘"fcntl"’.

 -- ‘dovecot-configuration’ parameter: file-name mail-temp-dir
     Directory in which LDA/LMTP temporarily stores incoming mails >128
     kB. Defaults to ‘"/tmp"’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          first-valid-uid
     Valid UID range for users.  This is mostly to make sure that users
     can’t log in as daemons or other system users.  Note that denying
     root logins is hardcoded to dovecot binary and can’t be done even
     if ‘first-valid-uid’ is set to 0.  Defaults to ‘500’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          last-valid-uid

     Defaults to ‘0’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          first-valid-gid
     Valid GID range for users.  Users having non-valid GID as primary
     group ID aren’t allowed to log in.  If user belongs to
     supplementary groups with non-valid GIDs, those groups are not set.
     Defaults to ‘1’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          last-valid-gid

     Defaults to ‘0’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          mail-max-keyword-length
     Maximum allowed length for mail keyword name.  It’s only forced
     when trying to create new keywords.  Defaults to ‘50’.

 -- ‘dovecot-configuration’ parameter: colon-separated-file-name-list
          valid-chroot-dirs
     List of directories under which chrooting is allowed for mail
     processes (i.e. ‘/var/mail’ will allow chrooting to
     ‘/var/mail/foo/bar’ too).  This setting doesn’t affect
     ‘login-chroot’ ‘mail-chroot’ or auth chroot settings.  If this
     setting is empty, ‘/./’ in home dirs are ignored.  WARNING: Never
     add directories here which local users can modify, that may lead to
     root exploit.  Usually this should be done only if you don’t allow
     shell access for users.  <doc/wiki/Chrooting.txt>.  Defaults to
     ‘()’.

 -- ‘dovecot-configuration’ parameter: string mail-chroot
     Default chroot directory for mail processes.  This can be
     overridden for specific users in user database by giving ‘/./’ in
     user’s home directory (e.g. ‘/home/./user’ chroots into ‘/home’).
     Note that usually there is no real need to do chrooting, Dovecot
     doesn’t allow users to access files outside their mail directory
     anyway.  If your home directories are prefixed with the chroot
     directory, append ‘/.’ to ‘mail-chroot’.  <doc/wiki/Chrooting.txt>.
     Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: file-name auth-socket-path
     UNIX socket path to master authentication server to find users.
     This is used by imap (for shared users) and lda.  Defaults to
     ‘"/var/run/dovecot/auth-userdb"’.

 -- ‘dovecot-configuration’ parameter: file-name mail-plugin-dir
     Directory where to look up mail plugins.  Defaults to
     ‘"/usr/lib/dovecot"’.

 -- ‘dovecot-configuration’ parameter: space-separated-string-list
          mail-plugins
     List of plugins to load for all services.  Plugins specific to
     IMAP, LDA, etc. are added to this list in their own .conf files.
     Defaults to ‘()’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          mail-cache-min-mail-count
     The minimum number of mails in a mailbox before updates are done to
     cache file.  This allows optimizing Dovecot’s behavior to do less
     disk writes at the cost of more disk reads.  Defaults to ‘0’.

 -- ‘dovecot-configuration’ parameter: string
          mailbox-idle-check-interval
     When IDLE command is running, mailbox is checked once in a while to
     see if there are any new mails or other changes.  This setting
     defines the minimum time to wait between those checks.  Dovecot can
     also use dnotify, inotify and kqueue to find out immediately when
     changes occur.  Defaults to ‘"30 secs"’.

 -- ‘dovecot-configuration’ parameter: boolean mail-save-crlf?
     Save mails with CR+LF instead of plain LF.  This makes sending
     those mails take less CPU, especially with sendfile() syscall with
     Linux and FreeBSD.  But it also creates a bit more disk I/O which
     may just make it slower.  Also note that if other software reads
     the mboxes/maildirs, they may handle the extra CRs wrong and cause
     problems.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: boolean maildir-stat-dirs?
     By default LIST command returns all entries in maildir beginning
     with a dot.  Enabling this option makes Dovecot return only entries
     which are directories.  This is done by stat()ing each entry, so it
     causes more disk I/O. (For systems setting struct ‘dirent->d_type’
     this check is free and it’s done always regardless of this
     setting).  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: boolean
          maildir-copy-with-hardlinks?
     When copying a message, do it with hard links whenever possible.
     This makes the performance much better, and it’s unlikely to have
     any side effects.  Defaults to ‘#t’.

 -- ‘dovecot-configuration’ parameter: boolean maildir-very-dirty-syncs?
     Assume Dovecot is the only MUA accessing Maildir: Scan cur/
     directory only when its mtime changes unexpectedly or when we can’t
     find the mail otherwise.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: space-separated-string-list
          mbox-read-locks
     Which locking methods to use for locking mbox.  There are four
     available:

     ‘dotlock’
          Create <mailbox>.lock file.  This is the oldest and most
          NFS-safe solution.  If you want to use /var/mail/ like
          directory, the users will need write access to that directory.
     ‘dotlock-try’
          Same as dotlock, but if it fails because of permissions or
          because there isn’t enough disk space, just skip it.
     ‘fcntl’
          Use this if possible.  Works with NFS too if lockd is used.
     ‘flock’
          May not exist in all systems.  Doesn’t work with NFS.
     ‘lockf’
          May not exist in all systems.  Doesn’t work with NFS.

     You can use multiple locking methods; if you do the order they’re
     declared in is important to avoid deadlocks if other MTAs/MUAs are
     using multiple locking methods as well.  Some operating systems
     don’t allow using some of them simultaneously.

 -- ‘dovecot-configuration’ parameter: space-separated-string-list
          mbox-write-locks

 -- ‘dovecot-configuration’ parameter: string mbox-lock-timeout
     Maximum time to wait for lock (all of them) before aborting.
     Defaults to ‘"5 mins"’.

 -- ‘dovecot-configuration’ parameter: string
          mbox-dotlock-change-timeout
     If dotlock exists but the mailbox isn’t modified in any way,
     override the lock file after this much time.  Defaults to ‘"2
     mins"’.

 -- ‘dovecot-configuration’ parameter: boolean mbox-dirty-syncs?
     When mbox changes unexpectedly we have to fully read it to find out
     what changed.  If the mbox is large this can take a long time.
     Since the change is usually just a newly appended mail, it’d be
     faster to simply read the new mails.  If this setting is enabled,
     Dovecot does this but still safely fallbacks to re-reading the
     whole mbox file whenever something in mbox isn’t how it’s expected
     to be.  The only real downside to this setting is that if some
     other MUA changes message flags, Dovecot doesn’t notice it
     immediately.  Note that a full sync is done with SELECT, EXAMINE,
     EXPUNGE and CHECK commands.  Defaults to ‘#t’.

 -- ‘dovecot-configuration’ parameter: boolean mbox-very-dirty-syncs?
     Like ‘mbox-dirty-syncs’, but don’t do full syncs even with SELECT,
     EXAMINE, EXPUNGE or CHECK commands.  If this is set,
     ‘mbox-dirty-syncs’ is ignored.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: boolean mbox-lazy-writes?
     Delay writing mbox headers until doing a full write sync (EXPUNGE
     and CHECK commands and when closing the mailbox).  This is
     especially useful for POP3 where clients often delete all mails.
     The downside is that our changes aren’t immediately visible to
     other MUAs.  Defaults to ‘#t’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          mbox-min-index-size
     If mbox size is smaller than this (e.g. 100k), don’t write index
     files.  If an index file already exists it’s still read, just not
     updated.  Defaults to ‘0’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          mdbox-rotate-size
     Maximum dbox file size until it’s rotated.  Defaults to ‘10000000’.

 -- ‘dovecot-configuration’ parameter: string mdbox-rotate-interval
     Maximum dbox file age until it’s rotated.  Typically in days.  Day
     begins from midnight, so 1d = today, 2d = yesterday, etc.  0 =
     check disabled.  Defaults to ‘"1d"’.

 -- ‘dovecot-configuration’ parameter: boolean mdbox-preallocate-space?
     When creating new mdbox files, immediately preallocate their size
     to ‘mdbox-rotate-size’.  This setting currently works only in Linux
     with some file systems (ext4, xfs).  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: string mail-attachment-dir
     sdbox and mdbox support saving mail attachments to external files,
     which also allows single instance storage for them.  Other backends
     don’t support this for now.

     WARNING: This feature hasn’t been tested much yet.  Use at your own
     risk.

     Directory root where to store mail attachments.  Disabled, if
     empty.  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          mail-attachment-min-size
     Attachments smaller than this aren’t saved externally.  It’s also
     possible to write a plugin to disable saving specific attachments
     externally.  Defaults to ‘128000’.

 -- ‘dovecot-configuration’ parameter: string mail-attachment-fs
     File system backend to use for saving attachments:
     ‘posix’
          No SiS done by Dovecot (but this might help FS’s own
          deduplication)
     ‘sis posix’
          SiS with immediate byte-by-byte comparison during saving
     ‘sis-queue posix’
          SiS with delayed comparison and deduplication.
     Defaults to ‘"sis posix"’.

 -- ‘dovecot-configuration’ parameter: string mail-attachment-hash
     Hash format to use in attachment filenames.  You can add any text
     and variables: ‘%{md4}’, ‘%{md5}’, ‘%{sha1}’, ‘%{sha256}’,
     ‘%{sha512}’, ‘%{size}’.  Variables can be truncated, e.g.
     ‘%{sha256:80}’ returns only first 80 bits.  Defaults to
     ‘"%{sha1}"’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          default-process-limit

     Defaults to ‘100’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          default-client-limit

     Defaults to ‘1000’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          default-vsz-limit
     Default VSZ (virtual memory size) limit for service processes.
     This is mainly intended to catch and kill processes that leak
     memory before they eat up everything.  Defaults to ‘256000000’.

 -- ‘dovecot-configuration’ parameter: string default-login-user
     Login user is internally used by login processes.  This is the most
     untrusted user in Dovecot system.  It shouldn’t have access to
     anything at all.  Defaults to ‘"dovenull"’.

 -- ‘dovecot-configuration’ parameter: string default-internal-user
     Internal user is used by unprivileged processes.  It should be
     separate from login user, so that login processes can’t disturb
     other processes.  Defaults to ‘"dovecot"’.

 -- ‘dovecot-configuration’ parameter: string ssl?
     SSL/TLS support: yes, no, required.  <doc/wiki/SSL.txt>.  Defaults
     to ‘"required"’.

 -- ‘dovecot-configuration’ parameter: string ssl-cert
     PEM encoded X.509 SSL/TLS certificate (public key).  Defaults to
     ‘"</etc/dovecot/default.pem"’.

 -- ‘dovecot-configuration’ parameter: string ssl-key
     PEM encoded SSL/TLS private key.  The key is opened before dropping
     root privileges, so keep the key file unreadable by anyone but
     root.  Defaults to ‘"</etc/dovecot/private/default.pem"’.

 -- ‘dovecot-configuration’ parameter: string ssl-key-password
     If key file is password protected, give the password here.
     Alternatively give it when starting dovecot with -p parameter.
     Since this file is often world-readable, you may want to place this
     setting instead to a different.  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string ssl-ca
     PEM encoded trusted certificate authority.  Set this only if you
     intend to use ‘ssl-verify-client-cert? #t’.  The file should
     contain the CA certificate(s) followed by the matching CRL(s).
     (e.g. ‘ssl-ca </etc/ssl/certs/ca.pem’).  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: boolean ssl-require-crl?
     Require that CRL check succeeds for client certificates.  Defaults
     to ‘#t’.

 -- ‘dovecot-configuration’ parameter: boolean ssl-verify-client-cert?
     Request client to send a certificate.  If you also want to require
     it, set ‘auth-ssl-require-client-cert? #t’ in auth section.
     Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: string ssl-cert-username-field
     Which field from certificate to use for username.  commonName and
     x500UniqueIdentifier are the usual choices.  You’ll also need to
     set ‘auth-ssl-username-from-cert? #t’.  Defaults to ‘"commonName"’.

 -- ‘dovecot-configuration’ parameter: string ssl-min-protocol
     Minimum SSL protocol version to accept.  Defaults to ‘"TLSv1"’.

 -- ‘dovecot-configuration’ parameter: string ssl-cipher-list
     SSL ciphers to use.  Defaults to
     ‘"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@STRENGTH"’.

 -- ‘dovecot-configuration’ parameter: string ssl-crypto-device
     SSL crypto device to use, for valid values run "openssl engine".
     Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string postmaster-address
     Address to use when sending rejection mails.  %d expands to
     recipient domain.  Defaults to ‘"postmaster@%d"’.

 -- ‘dovecot-configuration’ parameter: string hostname
     Hostname to use in various parts of sent mails (e.g. in Message-Id)
     and in LMTP replies.  Default is the system’s real hostname@domain.
     Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: boolean quota-full-tempfail?
     If user is over quota, return with temporary failure instead of
     bouncing the mail.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: file-name sendmail-path
     Binary to use for sending mails.  Defaults to
     ‘"/usr/sbin/sendmail"’.

 -- ‘dovecot-configuration’ parameter: string submission-host
     If non-empty, send mails via this SMTP host[:port] instead of
     sendmail.  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string rejection-subject
     Subject: header to use for rejection mails.  You can use the same
     variables as for ‘rejection-reason’ below.  Defaults to ‘"Rejected:
     %s"’.

 -- ‘dovecot-configuration’ parameter: string rejection-reason
     Human readable error message for rejection mails.  You can use
     variables:

     ‘%n’
          CRLF
     ‘%r’
          reason
     ‘%s’
          original subject
     ‘%t’
          recipient
     Defaults to ‘"Your message to <%t> was automatically
     rejected:%n%r"’.

 -- ‘dovecot-configuration’ parameter: string recipient-delimiter
     Delimiter character between local-part and detail in email address.
     Defaults to ‘"+"’.

 -- ‘dovecot-configuration’ parameter: string
          lda-original-recipient-header
     Header where the original recipient address (SMTP’s RCPT TO:
     address) is taken from if not available elsewhere.  With
     dovecot-lda -a parameter overrides this.  A commonly used header
     for this is X-Original-To.  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: boolean lda-mailbox-autocreate?
     Should saving a mail to a nonexistent mailbox automatically create
     it?.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: boolean
          lda-mailbox-autosubscribe?
     Should automatically created mailboxes be also automatically
     subscribed?.  Defaults to ‘#f’.

 -- ‘dovecot-configuration’ parameter: non-negative-integer
          imap-max-line-length
     Maximum IMAP command line length.  Some clients generate very long
     command lines with huge mailboxes, so you may need to raise this if
     you get "Too long argument" or "IMAP command line too large" errors
     often.  Defaults to ‘64000’.

 -- ‘dovecot-configuration’ parameter: string imap-logout-format
     IMAP logout format string:
     ‘%i’
          total number of bytes read from client
     ‘%o’
          total number of bytes sent to client.
     See ‘doc/wiki/Variables.txt’ for a list of all the variables you
     can use.  Defaults to ‘"in=%i out=%o deleted=%{deleted}
     expunged=%{expunged} trashed=%{trashed}
     hdr_count=%{fetch_hdr_count} hdr_bytes=%{fetch_hdr_bytes}
     body_count=%{fetch_body_count} body_bytes=%{fetch_body_bytes}"’.

 -- ‘dovecot-configuration’ parameter: string imap-capability
     Override the IMAP CAPABILITY response.  If the value begins with
     ’+’, add the given capabilities on top of the defaults (e.g. +XFOO
     XBAR). Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string imap-idle-notify-interval
     How long to wait between "OK Still here" notifications when client
     is IDLEing.  Defaults to ‘"2 mins"’.

 -- ‘dovecot-configuration’ parameter: string imap-id-send
     ID field names and values to send to clients.  Using * as the value
     makes Dovecot use the default value.  The following fields have
     default values currently: name, version, os, os-version,
     support-url, support-email.  Defaults to ‘""’.

 -- ‘dovecot-configuration’ parameter: string imap-id-log
     ID fields sent by client to log.  * means everything.  Defaults to
     ‘""’.

 -- ‘dovecot-configuration’ parameter: space-separated-string-list
          imap-client-workarounds
     Workarounds for various client bugs:

     ‘delay-newmail’
          Send EXISTS/RECENT new mail notifications only when replying
          to NOOP and CHECK commands.  Some clients ignore them
          otherwise, for example OSX Mail (<v2.1).  Outlook Express
          breaks more badly though, without this it may show user
          "Message no longer in server" errors.  Note that OE6 still
          breaks even with this workaround if synchronization is set to
          "Headers Only".

     ‘tb-extra-mailbox-sep’
          Thunderbird gets somehow confused with LAYOUT=fs (mbox and
          dbox) and adds extra ‘/’ suffixes to mailbox names.  This
          option causes Dovecot to ignore the extra ‘/’ instead of
          treating it as invalid mailbox name.

     ‘tb-lsub-flags’
          Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.
          mbox).  This makes Thunderbird realize they aren’t selectable
          and show them greyed out, instead of only later giving "not
          selectable" popup error.
     Defaults to ‘()’.

 -- ‘dovecot-configuration’ parameter: string imap-urlauth-host
     Host allowed in URLAUTH URLs sent by client.  "*" allows all.
     Defaults to ‘""’.

   Whew!  Lots of configuration options.  The nice thing about it though
is that Guix has a complete interface to Dovecot’s configuration
language.  This allows not only a nice way to declare configurations,
but also offers reflective capabilities as well: users can write code to
inspect and transform configurations from within Scheme.

   However, it could be that you just want to get a ‘dovecot.conf’ up
and running.  In that case, you can pass an
‘opaque-dovecot-configuration’ as the ‘#:config’ parameter to
‘dovecot-service’.  As its name indicates, an opaque configuration does
not have easy reflective capabilities.

   Available ‘opaque-dovecot-configuration’ fields are:

 -- ‘opaque-dovecot-configuration’ parameter: package dovecot
     The dovecot package.

 -- ‘opaque-dovecot-configuration’ parameter: string string
     The contents of the ‘dovecot.conf’, as a string.

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

     (dovecot-service #:config
                      (opaque-dovecot-configuration
                       (string "")))

OpenSMTPD Service
.................

 -- Scheme Variable: opensmtpd-service-type
     This is the type of the OpenSMTPD (https://www.opensmtpd.org)
     service, whose value should be an ‘opensmtpd-configuration’ object
     as in this example:

          (service opensmtpd-service-type
                   (opensmtpd-configuration
                     (config-file (local-file "./my-smtpd.conf"))))

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

     ‘package’ (default: OPENSMTPD)
          Package object of the OpenSMTPD SMTP server.

     ‘config-file’ (default: ‘%default-opensmtpd-config-file’)
          File-like object of the OpenSMTPD configuration file to use.
          By default it listens on the loopback network interface, and
          allows for mail from users and daemons on the local machine,
          as well as permitting email to remote servers.  Run ‘man
          smtpd.conf’ for more information.

     ‘setgid-commands?’ (default: ‘#t’)
          Make the following commands setgid to ‘smtpq’ so they can be
          executed: ‘smtpctl’, ‘sendmail’, ‘send-mail’, ‘makemap’,
          ‘mailq’, and ‘newaliases’.  *Note Setuid Programs::, for more
          information on setgid programs.

Exim Service
............

 -- Scheme Variable: exim-service-type
     This is the type of the Exim (https://exim.org) mail transfer agent
     (MTA), whose value should be an ‘exim-configuration’ object as in
     this example:

          (service exim-service-type
                   (exim-configuration
                     (config-file (local-file "./my-exim.conf"))))

   In order to use an ‘exim-service-type’ service you must also have a
‘mail-aliases-service-type’ service present in your ‘operating-system’
(even if it has no aliases).

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

     ‘package’ (default: EXIM)
          Package object of the Exim server.

     ‘config-file’ (default: ‘#f’)
          File-like object of the Exim configuration file to use.  If
          its value is ‘#f’ then use the default configuration file from
          the package provided in ‘package’.  The resulting
          configuration file is loaded after setting the ‘exim_user’ and
          ‘exim_group’ configuration variables.

Getmail service
...............

 -- Scheme Variable: getmail-service-type
     This is the type of the Getmail
     (http://pyropus.ca/software/getmail/) mail retriever, whose value
     should be an ‘getmail-configuration’.

   Available ‘getmail-configuration’ fields are:

 -- ‘getmail-configuration’ parameter: symbol name
     A symbol to identify the getmail service.

     Defaults to ‘"unset"’.

 -- ‘getmail-configuration’ parameter: package package
     The getmail package to use.

 -- ‘getmail-configuration’ parameter: string user
     The user to run getmail as.

     Defaults to ‘"getmail"’.

 -- ‘getmail-configuration’ parameter: string group
     The group to run getmail as.

     Defaults to ‘"getmail"’.

 -- ‘getmail-configuration’ parameter: string directory
     The getmail directory to use.

     Defaults to ‘"/var/lib/getmail/default"’.

 -- ‘getmail-configuration’ parameter: getmail-configuration-file rcfile
     The getmail configuration file to use.

     Available ‘getmail-configuration-file’ fields are:

      -- ‘getmail-configuration-file’ parameter:
               getmail-retriever-configuration retriever
          What mail account to retrieve mail from, and how to access
          that account.

          Available ‘getmail-retriever-configuration’ fields are:

           -- ‘getmail-retriever-configuration’ parameter: string type
               The type of mail retriever to use.  Valid values include
               ‘passwd’ and ‘static’.

               Defaults to ‘"SimpleIMAPSSLRetriever"’.

           -- ‘getmail-retriever-configuration’ parameter: string server
               Username to login to the mail server with.

               Defaults to ‘unset’.

           -- ‘getmail-retriever-configuration’ parameter: string
                    username
               Username to login to the mail server with.

               Defaults to ‘unset’.

           -- ‘getmail-retriever-configuration’ parameter:
                    non-negative-integer port
               Port number to connect to.

               Defaults to ‘#f’.

           -- ‘getmail-retriever-configuration’ parameter: string
                    password
               Override fields from passwd.

               Defaults to ‘""’.

           -- ‘getmail-retriever-configuration’ parameter: list
                    password-command
               Override fields from passwd.

               Defaults to ‘()’.

           -- ‘getmail-retriever-configuration’ parameter: string
                    keyfile
               PEM-formatted key file to use for the TLS negotiation.

               Defaults to ‘""’.

           -- ‘getmail-retriever-configuration’ parameter: string
                    certfile
               PEM-formatted certificate file to use for the TLS
               negotiation.

               Defaults to ‘""’.

           -- ‘getmail-retriever-configuration’ parameter: string
                    ca-certs
               CA certificates to use.

               Defaults to ‘""’.

           -- ‘getmail-retriever-configuration’ parameter:
                    parameter-alist extra-parameters
               Extra retriever parameters.

               Defaults to ‘()’.

      -- ‘getmail-configuration-file’ parameter:
               getmail-destination-configuration destination
          What to do with retrieved messages.

          Available ‘getmail-destination-configuration’ fields are:

           -- ‘getmail-destination-configuration’ parameter: string type
               The type of mail destination.  Valid values include
               ‘Maildir’, ‘Mboxrd’ and ‘MDA_external’.

               Defaults to ‘unset’.

           -- ‘getmail-destination-configuration’ parameter:
                    string-or-filelike path
               The path option for the mail destination.  The behaviour
               depends on the chosen type.

               Defaults to ‘""’.

           -- ‘getmail-destination-configuration’ parameter:
                    parameter-alist extra-parameters
               Extra destination parameters

               Defaults to ‘()’.

      -- ‘getmail-configuration-file’ parameter:
               getmail-options-configuration options
          Configure getmail.

          Available ‘getmail-options-configuration’ fields are:

           -- ‘getmail-options-configuration’ parameter:
                    non-negative-integer verbose
               If set to ‘0’, getmail will only print warnings and
               errors.  A value of ‘1’ means that messages will be
               printed about retrieving and deleting messages.  If set
               to ‘2’, getmail will print messages about each of its
               actions.

               Defaults to ‘1’.

           -- ‘getmail-options-configuration’ parameter: boolean
                    read-all
               If true, getmail will retrieve all available messages.
               Otherwise it will only retrieve messages it hasn’t seen
               previously.

               Defaults to ‘#t’.

           -- ‘getmail-options-configuration’ parameter: boolean delete
               If set to true, messages will be deleted from the server
               after retrieving and successfully delivering them.
               Otherwise, messages will be left on the server.

               Defaults to ‘#f’.

           -- ‘getmail-options-configuration’ parameter:
                    non-negative-integer delete-after
               Getmail will delete messages this number of days after
               seeing them, if they have been delivered.  This means
               messages will be left on the server this number of days
               after delivering them.  A value of ‘0’ disabled this
               feature.

               Defaults to ‘0’.

           -- ‘getmail-options-configuration’ parameter:
                    non-negative-integer delete-bigger-than
               Delete messages larger than this of bytes after
               retrieving them, even if the delete and delete-after
               options are disabled.  A value of ‘0’ disables this
               feature.

               Defaults to ‘0’.

           -- ‘getmail-options-configuration’ parameter:
                    non-negative-integer max-bytes-per-session
               Retrieve messages totalling up to this number of bytes
               before closing the session with the server.  A value of
               ‘0’ disables this feature.

               Defaults to ‘0’.

           -- ‘getmail-options-configuration’ parameter:
                    non-negative-integer max-message-size
               Don’t retrieve messages larger than this number of bytes.
               A value of ‘0’ disables this feature.

               Defaults to ‘0’.

           -- ‘getmail-options-configuration’ parameter: boolean
                    delivered-to
               If true, getmail will add a Delivered-To header to
               messages.

               Defaults to ‘#t’.

           -- ‘getmail-options-configuration’ parameter: boolean
                    received
               If set, getmail adds a Received header to the messages.

               Defaults to ‘#t’.

           -- ‘getmail-options-configuration’ parameter: string
                    message-log
               Getmail will record a log of its actions to the named
               file.  A value of ‘""’ disables this feature.

               Defaults to ‘""’.

           -- ‘getmail-options-configuration’ parameter: boolean
                    message-log-syslog
               If true, getmail will record a log of its actions using
               the system logger.

               Defaults to ‘#f’.

           -- ‘getmail-options-configuration’ parameter: boolean
                    message-log-verbose
               If true, getmail will log information about messages not
               retrieved and the reason for not retrieving them, as well
               as starting and ending information lines.

               Defaults to ‘#f’.

           -- ‘getmail-options-configuration’ parameter: parameter-alist
                    extra-parameters
               Extra options to include.

               Defaults to ‘()’.

 -- ‘getmail-configuration’ parameter: list idle
     A list of mailboxes that getmail should wait on the server for new
     mail notifications.  This depends on the server supporting the IDLE
     extension.

     Defaults to ‘()’.

 -- ‘getmail-configuration’ parameter: list environment-variables
     Environment variables to set for getmail.

     Defaults to ‘()’.

Mail Aliases Service
....................

 -- Scheme Variable: mail-aliases-service-type
     This is the type of the service which provides ‘/etc/aliases’,
     specifying how to deliver mail to users on this system.

          (service mail-aliases-service-type
                   '(("postmaster" "bob")
                     ("bob" "bob@example.com" "bob@example2.com")))

   The configuration for a ‘mail-aliases-service-type’ service is an
association list denoting how to deliver mail that comes to this system.
Each entry is of the form ‘(alias addresses ...)’, with ‘alias’
specifying the local alias and ‘addresses’ specifying where to deliver
this user’s mail.

   The aliases aren’t required to exist as users on the local system.
In the above example, there doesn’t need to be a ‘postmaster’ entry in
the ‘operating-system’’s ‘user-accounts’ in order to deliver the
‘postmaster’ mail to ‘bob’ (which subsequently would deliver mail to
‘bob@example.com’ and ‘bob@example2.com’).

GNU Mailutils IMAP4 Daemon
..........................

 -- Scheme Variable: imap4d-service-type
     This is the type of the GNU Mailutils IMAP4 Daemon (*note
     (mailutils)imap4d::), whose value should be an
     ‘imap4d-configuration’ object as in this example:

          (service imap4d-service-type
                   (imap4d-configuration
                     (config-file (local-file "imap4d.conf"))))

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

     ‘package’ (default: ‘mailutils’)
          The package that provides ‘imap4d’.

     ‘config-file’ (default: ‘%default-imap4d-config-file’)
          File-like object of the configuration file to use, by default
          it will listen on TCP port 143 of ‘localhost’.  *Note
          (mailutils)Conf-imap4d::, for details.

Radicale Service
................

 -- Scheme Variable: radicale-service-type
     This is the type of the Radicale (https://radicale.org)
     CalDAV/CardDAV server whose value should be a
     ‘radicale-configuration’.

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

     ‘package’ (default: ‘radicale’)
          The package that provides ‘radicale’.

     ‘config-file’ (default: ‘%default-radicale-config-file’)
          File-like object of the configuration file to use, by default
          it will listen on TCP port 5232 of ‘localhost’ and use the
          ‘htpasswd’ file at ‘/var/lib/radicale/users’ with no (‘plain’)
          encryption.


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

12.9.13 Messaging Services
--------------------------

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

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

 -- Scheme 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/letsencrypt/live

   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: 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’,
     ‘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’,
     ‘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’,
     ‘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.

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

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.

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


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

12.9.14 Telephony Services
--------------------------

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

Jami
....

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-string-list)
          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).

 -- 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/letsencrypt/live/mumble.example.com/fullchain.pem")
                    (ssl-key "/etc/letsencrypt/live/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/letsencrypt/live/example.com/fullchain.pem")
     ‘ssl-key’ (default: ‘#f’)
          Filepath to the ssl private key used for encrypted
          connections.
               (ssl-key "/etc/letsencrypt/live/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

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

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

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

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

12.9.16 Monitoring Services
---------------------------

Tailon Service
..............

Tailon (https://tailon.readthedocs.io/) is a web application for viewing
and searching log files.

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

     (service tailon-service-type)

   The following example customises more of the Tailon configuration,
adding ‘sed’ to the list of allowed commands.

     (service tailon-service-type
              (tailon-configuration
                (config-file
                  (tailon-configuration-file
                    (allowed-commands '("tail" "grep" "awk" "sed"))))))

 -- Data Type: tailon-configuration
     Data type representing the configuration of Tailon.  This type has
     the following parameters:

     ‘config-file’ (default: ‘(tailon-configuration-file)’)
          The configuration file to use for Tailon.  This can be set to
          a “tailon-configuration-file” record value, or any gexp (*note
          G-Expressions::).

          For example, to instead use a local file, the ‘local-file’
          function can be used:

               (service tailon-service-type
                        (tailon-configuration
                          (config-file (local-file "./my-tailon.conf"))))

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

 -- Data Type: tailon-configuration-file
     Data type representing the configuration options for Tailon.  This
     type has the following parameters:

     ‘files’ (default: ‘(list "/var/log")’)
          List of files to display.  The list can include strings for a
          single file or directory, or a list, where the first item is
          the name of a subsection, and the remaining items are the
          files or directories in that subsection.

     ‘bind’ (default: ‘"localhost:8080"’)
          Address and port to which Tailon should bind on.

     ‘relative-root’ (default: ‘#f’)
          URL path to use for Tailon, set to ‘#f’ to not use a path.

     ‘allow-transfers?’ (default: ‘#t’)
          Allow downloading the log files in the web interface.

     ‘follow-names?’ (default: ‘#t’)
          Allow tailing of not-yet existent files.

     ‘tail-lines’ (default: ‘200’)
          Number of lines to read initially from each file.

     ‘allowed-commands’ (default: ‘(list "tail" "grep" "awk")’)
          Commands to allow running.  By default, ‘sed’ is disabled.

     ‘debug?’ (default: ‘#f’)
          Set ‘debug?’ to ‘#t’ to show debug messages.

     ‘wrap-lines’ (default: ‘#t’)
          Initial line wrapping state in the web interface.  Set to ‘#t’
          to initially wrap lines (the default), or to ‘#f’ to initially
          not wrap lines.

     ‘http-auth’ (default: ‘#f’)
          HTTP authentication type to use.  Set to ‘#f’ to disable
          authentication (the default).  Supported values are ‘"digest"’
          or ‘"basic"’.

     ‘users’ (default: ‘#f’)
          If HTTP authentication is enabled (see ‘http-auth’), access
          will be restricted to the credentials provided here.  To
          configure users, use a list of pairs, where the first element
          of the pair is the username, and the 2nd element of the pair
          is the password.

               (tailon-configuration-file
                 (http-auth "basic")
                 (users     '(("user1" . "password1")
                              ("user2" . "password2"))))

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

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

 -- Variable: Scheme 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: Scheme 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.

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: Scheme 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: group)
          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: Scheme 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: group)
          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: Scheme 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

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

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

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

12.9.18 LDAP Services
---------------------

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 ‘()’.


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

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

 -- Scheme 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")’.

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

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

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

     ‘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: ‘""’)
          Extra content for the ‘http’ block.  Should be string or a
          string valued G-expression.

 -- 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 raw lines added to the server block.

 -- 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’
          A string or list of strings to add to the upstream block.

 -- 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.
          This can contain many configuration directives.  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.

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.

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

Patchwork
.........

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

 -- Scheme 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://git.elephly.net/gitweb.cgi?p=software/mumi.git) 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.

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

     ‘mailer?’ (default: ‘#true’)
          Whether to enable or disable the mailer component.

     ‘mumi-configuration-sender’
          The email address used as the sender for comments.

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

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.

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

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

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

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

 -- Scheme 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’
          A gexp (*note G-Expressions::) specifying the hpcguix-web
          service configuration.  The main items available in this spec
          are:

          ‘title-prefix’ (default: ‘"hpcguix | "’)
               The page title prefix.

          ‘guix-command’ (default: ‘"guix"’)
               The ‘guix’ command.

          ‘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
                #~(define site-config
                    (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.

     Thus, make sure to add ‘nss-certs’ or another certificate package
     to the ‘packages’ field of your configuration.  *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.

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

 -- Scheme 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")
          	   (cert "/srv/cert.pem")
          	   (key "/srv/key.rsa")))

     The example above represents the minimal tweaking necessary to get
     Agate up and running.  Specifying the path to the certificate and
     key is always necessary, as the Gemini protocol requires TLS by
     default.

     To obtain a certificate and a key, you could, for example, use
     OpenSSL, running a command similar to the following example:

          openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \
              -days 3650 -nodes -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 generated key and certificate.

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

     ‘cert’ (default: ‘#f’)
          The path to the TLS certificate PEM file to be used for
          encrypted connections.  Must be filled in with a value from
          the user.

     ‘key’ (default: ‘#f’)
          The path to the PKCS8 private key file to be used for
          encrypted connections.  Must be filled in with a value from
          the user.

     ‘addr’ (default: ‘'("0.0.0.0:1965" "[::]:1965")’)
          A list of the addresses to listen on.

     ‘hostname’ (default: ‘#f’)
          The domain name of this Gemini server.  Optional.

     ‘lang’ (default: ‘#f’)
          RFC 4646 language code(s) for text/gemini documents.
          Optional.

     ‘silent?’ (default: ‘#f’)
          Set to ‘#t’ to disable logging output.

     ‘serve-secret?’ (default: ‘#f’)
          Set to ‘#t’ to serve secret files (files/directories starting
          with a dot).

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


File: guix.info,  Node: Certificate Services,  Next: DNS Services,  Prev: Web Services,  Up: Services

12.9.20 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-v01.api.letsencrypt.org/directory>.

 -- Scheme 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:

          (define %nginx-deploy-hook
            (program-file
             "nginx-deploy-hook"
             #~(let ((pid (call-with-input-file "/var/run/nginx/pid" read)))
                 (kill pid SIGHUP))))

          (service certbot-service-type
                   (certbot-configuration
                    (email "foo@example.net")
                    (certificates
                     (list
                      (certificate-configuration
                       (domains '("example.net" "www.example.net"))
                       (deploy-hook %nginx-deploy-hook))
                      (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 ‘auth-hook’.  For
          this command, the shell variables available in the ‘auth-hook’
          script are still available, and additionally
          ‘$CERTBOT_AUTH_OUTPUT’ will contain the standard output of the
          ‘auth-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"’.

   For each ‘certificate-configuration’, the certificate is saved to
‘/etc/letsencrypt/live/NAME/fullchain.pem’ and the key is saved to
‘/etc/letsencrypt/live/NAME/privkey.pem’.


File: guix.info,  Node: DNS Services,  Next: VNC Services,  Prev: Certificate Services,  Up: Services

12.9.21 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)))

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

 -- Scheme Variable: knot-resolver-service-type
     This is the type of the knot resolver service, whose value should
     be an ‘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.org/en/stable/daemon.html#configuration).

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

 -- Scheme Variable: dnsmasq-service-type
     This is the type of the dnsmasq service, whose value should be an
     ‘dnsmasq-configuration’ object as in this example:

          (service dnsmasq-service-type
                   (dnsmasq-configuration
                     (no-resolv? #t)
                     (servers '("192.168.1.1"))))

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

     ‘package’ (default: DNSMASQ)
          Package object of the dnsmasq server.

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

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

ddclient Service
................

The ddclient service described below runs the ddclient daemon, which
takes care of automatically updating DNS entries for service providers
such as Dyn (https://dyn.com/dns/).

   The following example show instantiates the service with its default
configuration:

     (service ddclient-service-type)

   Note that ddclient needs to access credentials that are stored in a
“secret file”, by default ‘/etc/ddclient/secrets’ (see ‘secret-file’
below).  You are expected to create this file manually, in an
“out-of-band” fashion (you _could_ make this file part of the service
configuration, for instance by using ‘plain-file’, but it will be
world-readable via ‘/gnu/store’).  See the examples in the
‘share/ddclient’ directory of the ‘ddclient’ package.

   Available ‘ddclient-configuration’ fields are:

 -- ‘ddclient-configuration’ parameter: package ddclient
     The ddclient package.

 -- ‘ddclient-configuration’ parameter: integer daemon
     The period after which ddclient will retry to check IP and domain
     name.

     Defaults to ‘300’.

 -- ‘ddclient-configuration’ parameter: boolean syslog
     Use syslog for the output.

     Defaults to ‘#t’.

 -- ‘ddclient-configuration’ parameter: string mail
     Mail to user.

     Defaults to ‘"root"’.

 -- ‘ddclient-configuration’ parameter: string mail-failure
     Mail failed update to user.

     Defaults to ‘"root"’.

 -- ‘ddclient-configuration’ parameter: string pid
     The ddclient PID file.

     Defaults to ‘"/var/run/ddclient/ddclient.pid"’.

 -- ‘ddclient-configuration’ parameter: boolean ssl
     Enable SSL support.

     Defaults to ‘#t’.

 -- ‘ddclient-configuration’ parameter: string user
     Specifies the user name or ID that is used when running ddclient
     program.

     Defaults to ‘"ddclient"’.

 -- ‘ddclient-configuration’ parameter: string group
     Group of the user who will run the ddclient program.

     Defaults to ‘"ddclient"’.

 -- ‘ddclient-configuration’ parameter: string secret-file
     Secret file which will be appended to ‘ddclient.conf’ file.  This
     file contains credentials for use by ddclient.  You are expected to
     create it manually.

     Defaults to ‘"/etc/ddclient/secrets.conf"’.

 -- ‘ddclient-configuration’ parameter: list extra-options
     Extra options will be appended to ‘ddclient.conf’ file.

     Defaults to ‘()’.

