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

Copyright © 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021
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 Ricardo Wurmus
Copyright © 2016 Ben Woodcroft
Copyright © 2016, 2017, 2018, 2021 Chris Marusich
Copyright © 2016, 2017, 2018, 2019, 2020, 2021 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 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 Mathieu Othacehe
Copyright © 2017 Federico Beffa
Copyright © 2017, 2018 Carlo Zancanaro
Copyright © 2017 Thomas Danckaert
Copyright © 2017 humanitiesNerd
Copyright © 2017, 2021 Christopher Lemmer Webber
Copyright © 2017, 2018, 2019, 2020 Marius Bakke
Copyright © 2017, 2019, 2020 Hartmut Goebel
Copyright © 2017, 2019, 2020, 2021 Maxim Cournoyer
Copyright © 2017, 2018, 2019, 2020, 2021 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 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 Guillaume Le Vaillant
Copyright © 2020 Leo Prikler
Copyright © 2019, 2020 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 Brice Waegeneire
Copyright © 2020 R Veera Kumar
Copyright © 2020 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 Maxime Devos

   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 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: Scheduled Job Execution,  Next: Log Rotation,  Prev: Base Services,  Up: Services

10.8.2 Scheduled Job Execution
------------------------------

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

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

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

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

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

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

     (operating-system
       ;; ...

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

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

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

                   (define %min-level 20)

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

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

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

     # herd schedule mcron

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

     # herd schedule mcron 10

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

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

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

     ‘mcron’ (default: MCRON)
          The mcron package to use.

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


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

10.8.3 Log Rotation
-------------------

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     The list of fields is as follows:

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

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

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

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

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

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


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

10.8.4 Networking Services
--------------------------

The ‘(gnu services networking)’ module provides services to configure
the network interface.

 -- Scheme Variable: dhcp-client-service-type
     This is the type of services that run DHCP, a Dynamic Host
     Configuration Protocol (DHCP) client, on all the non-loopback
     network interfaces.  Its value is the DHCP client package to use,
     ‘isc-dhcp’ by default.

 -- Scheme Procedure: dhcpd-service-type
     This type defines a service that runs a DHCP daemon.  To create a
     service of this type, you must supply a ‘<dhcpd-configuration>’.
     For example:

          (service dhcpd-service-type
                   (dhcpd-configuration
                    (config-file (local-file "my-dhcpd.conf"))
                    (interfaces '("enp0s25"))))

 -- Data Type: dhcpd-configuration
     ‘package’ (default: ‘isc-dhcp’)
          The package that provides the DHCP daemon.  This package is
          expected to provide the daemon at ‘sbin/dhcpd’ relative to its
          output directory.  The default package is the ISC’s DHCP
          server (https://www.isc.org/products/DHCP).
     ‘config-file’ (default: ‘#f’)
          The configuration file to use.  This is required.  It will be
          passed to ‘dhcpd’ via its ‘-cf’ option.  This may be any
          “file-like” object (*note file-like objects: G-Expressions.).
          See ‘man dhcpd.conf’ for details on the configuration file
          syntax.
     ‘version’ (default: ‘"4"’)
          The DHCP version to use.  The ISC DHCP server supports the
          values “4”, “6”, and “4o6”.  These correspond to the ‘dhcpd’
          program options ‘-4’, ‘-6’, and ‘-4o6’.  See ‘man dhcpd’ for
          details.
     ‘run-directory’ (default: ‘"/run/dhcpd"’)
          The run directory to use.  At service activation time, this
          directory will be created if it does not exist.
     ‘pid-file’ (default: ‘"/run/dhcpd/dhcpd.pid"’)
          The PID file to use.  This corresponds to the ‘-pf’ option of
          ‘dhcpd’.  See ‘man dhcpd’ for details.
     ‘interfaces’ (default: ‘'()’)
          The names of the network interfaces on which dhcpd should
          listen for broadcasts.  If this list is not empty, then its
          elements (which must be strings) will be appended to the
          ‘dhcpd’ invocation when starting the daemon.  It may not be
          necessary to explicitly specify any interfaces here; see ‘man
          dhcpd’ for details.

 -- Scheme Variable: static-networking-service-type
     This is the type for statically-configured network interfaces.

 -- Scheme Procedure: static-networking-service INTERFACE IP [#:netmask
          #f] [#:gateway #f] [#:name-servers ‘'()’] [#:requirement
          ‘'(udev)’]
     Return a service that starts INTERFACE with address IP.  If NETMASK
     is true, use it as the network mask.  If GATEWAY is true, it must
     be a string specifying the default network gateway.  REQUIREMENT
     can be used to declare a dependency on another service before
     configuring the interface.

     This procedure can be called several times, one for each network
     interface of interest.  Behind the scenes what it does is extend
     ‘static-networking-service-type’ with additional network interfaces
     to handle.

     For example:

          (static-networking-service "eno1" "192.168.1.82"
                                     #:gateway "192.168.1.2"
                                     #:name-servers '("192.168.1.2"))

 -- Scheme Procedure: wicd-service [#:wicd WICD]
     Return a service that runs Wicd (https://launchpad.net/wicd), a
     network management daemon that aims to simplify wired and wireless
     networking.

     This service adds the WICD package to the global profile, providing
     several commands to interact with the daemon and configure
     networking: ‘wicd-client’, a graphical user interface, and the
     ‘wicd-cli’ and ‘wicd-curses’ user interfaces.

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

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

 -- Data Type: modem-manager-configuration
     Data type representing the configuration of ModemManager.

     ‘modem-manager’ (default: ‘modem-manager’)
          The ModemManager package to use.

 -- Scheme Variable: usb-modeswitch-service-type
     This is the service type for the USB_ModeSwitch
     (https://www.draisberghof.de/usb_modeswitch/) service.  The value
     for this service type is a ‘usb-modeswitch-configuration’ record.

     When plugged in, some USB modems (and other USB devices) initially
     present themselves as a read-only storage medium and not as a
     modem.  They need to be “modeswitched” before they are usable.  The
     USB_ModeSwitch service type installs udev rules to automatically
     modeswitch these devices when they are plugged in.

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

 -- Data Type: usb-modeswitch-configuration
     Data type representing the configuration of USB_ModeSwitch.

     ‘usb-modeswitch’ (default: ‘usb-modeswitch’)
          The USB_ModeSwitch package providing the binaries for
          modeswitching.

     ‘usb-modeswitch-data’ (default: ‘usb-modeswitch-data’)
          The package providing the device data and udev rules file used
          by USB_ModeSwitch.

     ‘config-file’ (default: ‘#~(string-append #$usb-modeswitch:dispatcher "/etc/usb_modeswitch.conf")’)
          Which config file to use for the USB_ModeSwitch dispatcher.
          By default the config file shipped with USB_ModeSwitch is used
          which disables logging to ‘/var/log’ among other default
          settings.  If set to ‘#f’, no config file is used.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     Its value must be an ‘connman-configuration’ record as in this
     example:

          (service connman-service-type
                   (connman-configuration
                     (disable-vpn? #t)))

     See below for details about ‘connman-configuration’.

 -- Data Type: connman-configuration
     Data Type representing the configuration of connman.

     ‘connman’ (default: CONNMAN)
          The connman package to use.

     ‘disable-vpn?’ (default: ‘#f’)
          When true, disable connman’s vpn plugin.

 -- Scheme Variable: wpa-supplicant-service-type
     This is the service type to run WPA supplicant
     (https://w1.fi/wpa_supplicant/), an authentication daemon required
     to authenticate against encrypted WiFi or ethernet networks.

 -- Data Type: wpa-supplicant-configuration
     Data type representing the configuration of WPA Supplicant.

     It takes the following parameters:

     ‘wpa-supplicant’ (default: ‘wpa-supplicant’)
          The WPA Supplicant package to use.

     ‘requirement’ (default: ‘'(user-processes loopback syslogd)’
          List of services that should be started before WPA Supplicant
          starts.

     ‘dbus?’ (default: ‘#t’)
          Whether to listen for requests on D-Bus.

     ‘pid-file’ (default: ‘"/var/run/wpa_supplicant.pid"’)
          Where to store the PID file.

     ‘interface’ (default: ‘#f’)
          If this is set, it must specify the name of a network
          interface that WPA supplicant will control.

     ‘config-file’ (default: ‘#f’)
          Optional configuration file to use.

     ‘extra-options’ (default: ‘'()’)
          List of additional command-line arguments to pass to the
          daemon.

 -- Scheme Variable: hostapd-service-type
     This is the service type to run the hostapd
     (https://w1.fi/hostapd/) daemon to set up WiFi (IEEE 802.11) access
     points and authentication servers.  Its associated value must be a
     ‘hostapd-configuration’ as shown below:

          ;; Use wlan1 to run the access point for "My Network".
          (service hostapd-service-type
                   (hostapd-configuration
                    (interface "wlan1")
                    (ssid "My Network")
                    (channel 12)))

 -- Data Type: hostapd-configuration
     This data type represents the configuration of the hostapd service,
     with the following fields:

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

     ‘interface’ (default: ‘"wlan0"’)
          The network interface to run the WiFi access point.

     ‘ssid’
          The SSID (“service set identifier”), a string that identifies
          this network.

     ‘broadcast-ssid?’ (default: ‘#t’)
          Whether to broadcast this SSID.

     ‘channel’ (default: ‘1’)
          The WiFi channel to use.

     ‘driver’ (default: ‘"nl80211"’)
          The driver interface type.  ‘"nl80211"’ is used with all Linux
          mac80211 drivers.  Use ‘"none"’ if building hostapd as a
          standalone RADIUS server that does # not control any
          wireless/wired driver.

     ‘extra-settings’ (default: ‘""’)
          Extra settings to append as-is to the hostapd configuration
          file.  See
          <https://w1.fi/cgit/hostap/plain/hostapd/hostapd.conf> for the
          configuration file reference.

 -- Scheme Variable: simulated-wifi-service-type
     This is the type of a service to simulate WiFi networking, which
     can be useful in virtual machines for testing purposes.  The
     service loads the Linux kernel ‘mac80211_hwsim’ module
     (https://www.kernel.org/doc/html/latest/networking/mac80211_hwsim/mac80211_hwsim.html)
     and starts hostapd to create a pseudo WiFi network that can be seen
     on ‘wlan0’, by default.

     The service’s value is a ‘hostapd-configuration’ record.

 -- Scheme Variable: iptables-service-type
     This is the service type to set up an iptables configuration.
     iptables is a packet filtering framework supported by the Linux
     kernel.  This service supports configuring iptables for both IPv4
     and IPv6.  A simple example configuration rejecting all incoming
     connections except those to the ssh port 22 is shown below.

          (service iptables-service-type
                   (iptables-configuration
                    (ipv4-rules (plain-file "iptables.rules" "*filter
          :INPUT ACCEPT
          :FORWARD ACCEPT
          :OUTPUT ACCEPT
          -A INPUT -p tcp --dport 22 -j ACCEPT
          -A INPUT -j REJECT --reject-with icmp-port-unreachable
          COMMIT
          "))
                    (ipv6-rules (plain-file "ip6tables.rules" "*filter
          :INPUT ACCEPT
          :FORWARD ACCEPT
          :OUTPUT ACCEPT
          -A INPUT -p tcp --dport 22 -j ACCEPT
          -A INPUT -j REJECT --reject-with icmp6-port-unreachable
          COMMIT
          "))))

 -- Data Type: iptables-configuration
     The data type representing the configuration of iptables.

     ‘iptables’ (default: ‘iptables’)
          The iptables package that provides ‘iptables-restore’ and
          ‘ip6tables-restore’.
     ‘ipv4-rules’ (default: ‘%iptables-accept-all-rules’)
          The iptables rules to use.  It will be passed to
          ‘iptables-restore’.  This may be any “file-like” object (*note
          file-like objects: G-Expressions.).
     ‘ipv6-rules’ (default: ‘%iptables-accept-all-rules’)
          The ip6tables rules to use.  It will be passed to
          ‘ip6tables-restore’.  This may be any “file-like” object
          (*note file-like objects: G-Expressions.).

 -- Scheme Variable: nftables-service-type
     This is the service type to set up a nftables configuration.
     nftables is a netfilter project that aims to replace the existing
     iptables, ip6tables, arptables and ebtables framework.  It provides
     a new packet filtering framework, a new user-space utility ‘nft’,
     and a compatibility layer for iptables.  This service comes with a
     default ruleset ‘%default-nftables-ruleset’ that rejecting all
     incoming connections except those to the ssh port 22.  To use it,
     simply write:

          (service nftables-service-type)

 -- Data Type: nftables-configuration
     The data type representing the configuration of nftables.

     ‘package’ (default: ‘nftables’)
          The nftables package that provides ‘nft’.
     ‘ruleset’ (default: ‘%default-nftables-ruleset’)
          The nftables ruleset to use.  This may be any “file-like”
          object (*note file-like objects: G-Expressions.).

 -- Scheme Variable: ntp-service-type
     This is the type of the service running the Network Time Protocol
     (NTP) (https://www.ntp.org) daemon, ‘ntpd’.  The daemon will keep
     the system clock synchronized with that of the specified NTP
     servers.

     The value of this service is an ‘ntpd-configuration’ object, as
     described below.

 -- Data Type: ntp-configuration
     This is the data type for the NTP service configuration.

     ‘servers’ (default: ‘%ntp-servers’)
          This is the list of servers (‘<ntp-server>’ records) with
          which ‘ntpd’ will be synchronized.  See the ‘ntp-server’ data
          type definition below.

     ‘allow-large-adjustment?’ (default: ‘#t’)
          This determines whether ‘ntpd’ is allowed to make an initial
          adjustment of more than 1,000 seconds.

     ‘ntp’ (default: ‘ntp’)
          The NTP package to use.

 -- Scheme Variable: %ntp-servers
     List of host names used as the default NTP servers.  These are
     servers of the NTP Pool Project (https://www.ntppool.org/en/).

 -- Data Type: ntp-server
     The data type representing the configuration of a NTP server.

     ‘type’ (default: ‘'server’)
          The type of the NTP server, given as a symbol.  One of
          ‘'pool’, ‘'server’, ‘'peer’, ‘'broadcast’ or
          ‘'manycastclient’.

     ‘address’
          The address of the server, as a string.

     ‘options’
          NTPD options to use with that specific server, given as a list
          of option names and/or of option names and values tuples.  The
          following example define a server to use with the options
          ‘iburst’ and ‘prefer’, as well as ‘version’ 3 and a ‘maxpoll’
          time of 16 seconds.

               (ntp-server
                (type 'server)
                (address "some.ntp.server.org")
                (options `(iburst (version 3) (maxpoll 16) prefer))))

 -- Scheme Procedure: openntpd-service-type
     Run the ‘ntpd’, the Network Time Protocol (NTP) daemon, as
     implemented by OpenNTPD (http://www.openntpd.org).  The daemon will
     keep the system clock synchronized with that of the given servers.

          (service
           openntpd-service-type
           (openntpd-configuration
            (listen-on '("127.0.0.1" "::1"))
            (sensor '("udcf0 correction 70000"))
            (constraint-from '("www.gnu.org"))
            (constraints-from '("https://www.google.com/"))))


 -- Scheme Variable: %openntpd-servers
     This variable is a list of the server addresses defined in
     ‘%ntp-servers’.

 -- Data Type: openntpd-configuration
     ‘openntpd’ (default: ‘(file-append openntpd "/sbin/ntpd")’)
          The openntpd executable to use.
     ‘listen-on’ (default: ‘'("127.0.0.1" "::1")’)
          A list of local IP addresses or hostnames the ntpd daemon
          should listen on.
     ‘query-from’ (default: ‘'()’)
          A list of local IP address the ntpd daemon should use for
          outgoing queries.
     ‘sensor’ (default: ‘'()’)
          Specify a list of timedelta sensor devices ntpd should use.
          ‘ntpd’ will listen to each sensor that actually exists and
          ignore non-existent ones.  See upstream documentation
          (https://man.openbsd.org/ntpd.conf) for more information.
     ‘server’ (default: ‘'()’)
          Specify a list of IP addresses or hostnames of NTP servers to
          synchronize to.
     ‘servers’ (default: ‘%openntp-servers’)
          Specify a list of IP addresses or hostnames of NTP pools to
          synchronize to.
     ‘constraint-from’ (default: ‘'()’)
          ‘ntpd’ can be configured to query the ‘Date’ from trusted
          HTTPS servers via TLS. This time information is not used for
          precision but acts as an authenticated constraint, thereby
          reducing the impact of unauthenticated NTP man-in-the-middle
          attacks.  Specify a list of URLs, IP addresses or hostnames of
          HTTPS servers to provide a constraint.
     ‘constraints-from’ (default: ‘'()’)
          As with constraint from, specify a list of URLs, IP addresses
          or hostnames of HTTPS servers to provide a constraint.  Should
          the hostname resolve to multiple IP addresses, ‘ntpd’ will
          calculate a median constraint from all of them.

 -- Scheme variable: inetd-service-type
     This service runs the ‘inetd’ (*note (inetutils)inetd invocation::)
     daemon.  ‘inetd’ listens for connections on internet sockets, and
     lazily starts the specified server program when a connection is
     made on one of these sockets.

     The value of this service is an ‘inetd-configuration’ object.  The
     following example configures the ‘inetd’ daemon to provide the
     built-in ‘echo’ service, as well as an smtp service which forwards
     smtp traffic over ssh to a server ‘smtp-server’ behind a gateway
     ‘hostname’:

          (service
           inetd-service-type
           (inetd-configuration
            (entries (list
                      (inetd-entry
                       (name "echo")
                       (socket-type 'stream)
                       (protocol "tcp")
                       (wait? #f)
                       (user "root"))
                      (inetd-entry
                       (node "127.0.0.1")
                       (name "smtp")
                       (socket-type 'stream)
                       (protocol "tcp")
                       (wait? #f)
                       (user "root")
                       (program (file-append openssh "/bin/ssh"))
                       (arguments
                        '("ssh" "-qT" "-i" "/path/to/ssh_key"
                          "-W" "smtp-server:25" "user@hostname")))))))

     See below for more details about ‘inetd-configuration’.

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

     ‘program’ (default: ‘(file-append inetutils "/libexec/inetd")’)
          The ‘inetd’ executable to use.

     ‘entries’ (default: ‘'()’)
          A list of ‘inetd’ service entries.  Each entry should be
          created by the ‘inetd-entry’ constructor.

 -- Data Type: inetd-entry
     Data type representing an entry in the ‘inetd’ configuration.  Each
     entry corresponds to a socket where ‘inetd’ will listen for
     requests.

     ‘node’ (default: ‘#f’)
          Optional string, a comma-separated list of local addresses
          ‘inetd’ should use when listening for this service.  *Note
          (inetutils)Configuration file:: for a complete description of
          all options.
     ‘name’
          A string, the name must correspond to an entry in
          ‘/etc/services’.
     ‘socket-type’
          One of ‘'stream’, ‘'dgram’, ‘'raw’, ‘'rdm’ or ‘'seqpacket’.
     ‘protocol’
          A string, must correspond to an entry in ‘/etc/protocols’.
     ‘wait?’ (default: ‘#t’)
          Whether ‘inetd’ should wait for the server to exit before
          listening to new service requests.
     ‘user’
          A string containing the user (and, optionally, group) name of
          the user as whom the server should run.  The group name can be
          specified in a suffix, separated by a colon or period, i.e.
          ‘"user"’, ‘"user:group"’ or ‘"user.group"’.
     ‘program’ (default: ‘"internal"’)
          The server program which will serve the requests, or
          ‘"internal"’ if ‘inetd’ should use a built-in service.
     ‘arguments’ (default: ‘'()’)
          A list strings or file-like objects, which are the server
          program’s arguments, starting with the zeroth argument, i.e.
          the name of the program itself.  For ‘inetd’’s internal
          services, this entry must be ‘'()’ or ‘'("internal")’.

     *Note (inetutils)Configuration file:: for a more detailed
     discussion of each configuration field.

 -- Scheme Variable: tor-service-type
     This is the type for a service that runs the Tor
     (https://torproject.org) anonymous networking daemon.  The service
     is configured using a ‘<tor-configuration>’ record.  By default,
     the Tor daemon runs as the ‘tor’ unprivileged user, which is a
     member of the ‘tor’ group.

 -- Data Type: tor-configuration
     ‘tor’ (default: ‘tor’)
          The package that provides the Tor daemon.  This package is
          expected to provide the daemon at ‘bin/tor’ relative to its
          output directory.  The default package is the Tor Project’s
          (https://www.torproject.org) implementation.

     ‘config-file’ (default: ‘(plain-file "empty" "")’)
          The configuration file to use.  It will be appended to a
          default configuration file, and the final configuration file
          will be passed to ‘tor’ via its ‘-f’ option.  This may be any
          “file-like” object (*note file-like objects: G-Expressions.).
          See ‘man tor’ for details on the configuration file syntax.

     ‘hidden-services’ (default: ‘'()’)
          The list of ‘<hidden-service>’ records to use.  For any hidden
          service you include in this list, appropriate configuration to
          enable the hidden service will be automatically added to the
          default configuration file.  You may conveniently create
          ‘<hidden-service>’ records using the ‘tor-hidden-service’
          procedure described below.

     ‘socks-socket-type’ (default: ‘'tcp’)
          The default socket type that Tor should use for its SOCKS
          socket.  This must be either ‘'tcp’ or ‘'unix’.  If it is
          ‘'tcp’, then by default Tor will listen on TCP port 9050 on
          the loopback interface (i.e., localhost).  If it is ‘'unix’,
          then Tor will listen on the UNIX domain socket
          ‘/var/run/tor/socks-sock’, which will be made writable by
          members of the ‘tor’ group.

          If you want to customize the SOCKS socket in more detail,
          leave ‘socks-socket-type’ at its default value of ‘'tcp’ and
          use ‘config-file’ to override the default by providing your
          own ‘SocksPort’ option.

     ‘control-socket?’ (default: ‘#f’)
          Whether or not to provide a “control socket” by which Tor can
          be controlled to, for instance, dynamically instantiate tor
          onion services.  If ‘#t’, Tor will listen for control commands
          on the UNIX domain socket ‘/var/run/tor/control-sock’, which
          will be made writable by members of the ‘tor’ group.

 -- Scheme Procedure: tor-hidden-service NAME MAPPING
     Define a new Tor “hidden service” called NAME and implementing
     MAPPING.  MAPPING is a list of port/host tuples, such as:

           '((22 "127.0.0.1:22")
             (80 "127.0.0.1:8080"))

     In this example, port 22 of the hidden service is mapped to local
     port 22, and port 80 is mapped to local port 8080.

     This creates a ‘/var/lib/tor/hidden-services/NAME’ directory, where
     the ‘hostname’ file contains the ‘.onion’ host name for the hidden
     service.

     See the Tor project’s documentation
     (https://www.torproject.org/docs/tor-hidden-service.html.en) for
     more information.

   The ‘(gnu services rsync)’ module provides the following services:

   You might want an rsync daemon if you have files that you want
available so anyone (or just yourself) can download existing files or
upload new files.

 -- Scheme Variable: rsync-service-type
     This is the service type for the rsync (https://rsync.samba.org)
     daemon, The value for this service type is a ‘rsync-configuration’
     record as in this example:

          (service rsync-service-type)

     See below for details about ‘rsync-configuration’.

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

     ‘package’ (default: RSYNC)
          ‘rsync’ package to use.

     ‘port-number’ (default: ‘873’)
          TCP port on which ‘rsync’ listens for incoming connections.
          If port is less than ‘1024’ ‘rsync’ needs to be started as the
          ‘root’ user and group.

     ‘pid-file’ (default: ‘"/var/run/rsyncd/rsyncd.pid"’)
          Name of the file where ‘rsync’ writes its PID.

     ‘lock-file’ (default: ‘"/var/run/rsyncd/rsyncd.lock"’)
          Name of the file where ‘rsync’ writes its lock file.

     ‘log-file’ (default: ‘"/var/log/rsyncd.log"’)
          Name of the file where ‘rsync’ writes its log file.

     ‘use-chroot?’ (default: #T)
          Whether to use chroot for ‘rsync’ shared directory.

     ‘share-path’ (default: ‘/srv/rsync’)
          Location of the ‘rsync’ shared directory.

     ‘share-comment’ (default: ‘"Rsync share"’)
          Comment of the ‘rsync’ shared directory.

     ‘read-only?’ (default: #F)
          Read-write permissions to shared directory.

     ‘timeout’ (default: ‘300’)
          I/O timeout in seconds.

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

     ‘group’ (default: "ROOT")
          Group of the ‘rsync’ process.

     ‘uid’ (default: "RSYNCD")
          User name or user ID that file transfers to and from that
          module should take place as when the daemon was run as ‘root’.

     ‘gid’ (default: "RSYNCD")
          Group name or group ID that will be used when accessing the
          module.

   The ‘(gnu services syncthing)’ module provides the following
services:

   You might want a syncthing daemon if you have files between two or
more computers and want to sync them in real time, safely protected from
prying eyes.

 -- Scheme Variable: syncthing-service-type
     This is the service type for the syncthing (https://syncthing.net/)
     daemon, The value for this service type is a
     ‘syncthing-configuration’ record as in this example:

          (service syncthing-service-type
                   (syncthing-configuration (user "alice")))

     See below for details about ‘syncthing-configuration’.

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

          ‘syncthing’ (default: SYNCTHING)
               ‘syncthing’ package to use.

          ‘arguments’ (default: ’())
               List of command-line arguments passing to ‘syncthing’
               binary.

          ‘logflags’ (default: 0)
               Sum of logging flags, see Syncthing documentation
               logflags
               (https://docs.syncthing.net/users/syncthing.html#cmdoption-logflags).

          ‘user’ (default: #F)
               The user as which the Syncthing service is to be run.
               This assumes that the specified user exists.

          ‘group’ (default: "USERS")
               The group as which the Syncthing service is to be run.
               This assumes that the specified group exists.

          ‘home’ (default: #F)
               Common configuration and data directory.  The default
               configuration directory is ‘$HOME’ of the specified
               Syncthing ‘user’.

   Furthermore, ‘(gnu services ssh)’ provides the following services.

 -- Scheme Procedure: lsh-service [#:host-key "/etc/lsh/host-key"]
          [#:daemonic? #t] [#:interfaces '()] [#:port-number 22]
          [#:allow-empty-passwords? #f] [#:root-login? #f]
          [#:syslog-output? #t] [#:x11-forwarding? #t]
          [#:tcp/ip-forwarding? #t] [#:password-authentication? #t]
          [#:public-key-authentication? #t] [#:initialize? #t]
     Run the ‘lshd’ program from LSH to listen on port PORT-NUMBER.
     HOST-KEY must designate a file containing the host key, and
     readable only by root.

     When DAEMONIC? is true, ‘lshd’ will detach from the controlling
     terminal and log its output to syslogd, unless one sets
     SYSLOG-OUTPUT? to false.  Obviously, it also makes lsh-service
     depend on existence of syslogd service.  When PID-FILE? is true,
     ‘lshd’ writes its PID to the file called PID-FILE.

     When INITIALIZE? is true, automatically create the seed and host
     key upon service activation if they do not exist yet.  This may
     take long and require interaction.

     When INITIALIZE? is false, it is up to the user to initialize the
     randomness generator (*note (lsh)lsh-make-seed::), and to create a
     key pair with the private key stored in file HOST-KEY (*note
     (lsh)lshd basics::).

     When INTERFACES is empty, lshd listens for connections on all the
     network interfaces; otherwise, INTERFACES must be a list of host
     names or addresses.

     ALLOW-EMPTY-PASSWORDS? specifies whether to accept log-ins with
     empty passwords, and ROOT-LOGIN? specifies whether to accept
     log-ins as root.

     The other options should be self-descriptive.

 -- Scheme Variable: openssh-service-type
     This is the type for the OpenSSH (http://www.openssh.org) secure
     shell daemon, ‘sshd’.  Its value must be an ‘openssh-configuration’
     record as in this example:

          (service openssh-service-type
                   (openssh-configuration
                     (x11-forwarding? #t)
                     (permit-root-login 'without-password)
                     (authorized-keys
                       `(("alice" ,(local-file "alice.pub"))
                         ("bob" ,(local-file "bob.pub"))))))

     See below for details about ‘openssh-configuration’.

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

          (service-extension openssh-service-type
                             (const `(("charlie"
                                       ,(local-file "charlie.pub")))))

 -- Data Type: openssh-configuration
     This is the configuration record for OpenSSH’s ‘sshd’.

     ‘openssh’ (default OPENSSH)
          The Openssh package to use.

     ‘pid-file’ (default: ‘"/var/run/sshd.pid"’)
          Name of the file where ‘sshd’ writes its PID.

     ‘port-number’ (default: ‘22’)
          TCP port on which ‘sshd’ listens for incoming connections.

     ‘permit-root-login’ (default: ‘#f’)
          This field determines whether and when to allow logins as
          root.  If ‘#f’, root logins are disallowed; if ‘#t’, they are
          allowed.  If it’s the symbol ‘'without-password’, then root
          logins are permitted but not with password-based
          authentication.

     ‘allow-empty-passwords?’ (default: ‘#f’)
          When true, users with empty passwords may log in.  When false,
          they may not.

     ‘password-authentication?’ (default: ‘#t’)
          When true, users may log in with their password.  When false,
          they have other authentication methods.

     ‘public-key-authentication?’ (default: ‘#t’)
          When true, users may log in using public key authentication.
          When false, users have to use other authentication method.

          Authorized public keys are stored in ‘~/.ssh/authorized_keys’.
          This is used only by protocol version 2.

     ‘x11-forwarding?’ (default: ‘#f’)
          When true, forwarding of X11 graphical client connections is
          enabled—in other words, ‘ssh’ options ‘-X’ and ‘-Y’ will work.

     ‘allow-agent-forwarding?’ (default: ‘#t’)
          Whether to allow agent forwarding.

     ‘allow-tcp-forwarding?’ (default: ‘#t’)
          Whether to allow TCP forwarding.

     ‘gateway-ports?’ (default: ‘#f’)
          Whether to allow gateway ports.

     ‘challenge-response-authentication?’ (default: ‘#f’)
          Specifies whether challenge response authentication is allowed
          (e.g. via PAM).

     ‘use-pam?’ (default: ‘#t’)
          Enables the Pluggable Authentication Module interface.  If set
          to ‘#t’, this will enable PAM authentication using
          ‘challenge-response-authentication?’ and
          ‘password-authentication?’, in addition to PAM account and
          session module processing for all authentication types.

          Because PAM challenge response authentication usually serves
          an equivalent role to password authentication, you should
          disable either ‘challenge-response-authentication?’ or
          ‘password-authentication?’.

     ‘print-last-log?’ (default: ‘#t’)
          Specifies whether ‘sshd’ should print the date and time of the
          last user login when a user logs in interactively.

     ‘subsystems’ (default: ‘'(("sftp" "internal-sftp"))’)
          Configures external subsystems (e.g. file transfer daemon).

          This is a list of two-element lists, each of which containing
          the subsystem name and a command (with optional arguments) to
          execute upon subsystem request.

          The command ‘internal-sftp’ implements an in-process SFTP
          server.  Alternatively, one can specify the ‘sftp-server’
          command:
               (service openssh-service-type
                        (openssh-configuration
                         (subsystems
                          `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))

     ‘accepted-environment’ (default: ‘'()’)
          List of strings describing which environment variables may be
          exported.

          Each string gets on its own line.  See the ‘AcceptEnv’ option
          in ‘man sshd_config’.

          This example allows ssh-clients to export the ‘COLORTERM’
          variable.  It is set by terminal emulators, which support
          colors.  You can use it in your shell’s resource file to
          enable colors for the prompt and commands if this variable is
          set.

               (service openssh-service-type
                        (openssh-configuration
                          (accepted-environment '("COLORTERM"))))

     ‘authorized-keys’ (default: ‘'()’)
          This is the list of authorized keys.  Each element of the list
          is a user name followed by one or more file-like objects that
          represent SSH public keys.  For example:

               (openssh-configuration
                 (authorized-keys
                   `(("rekado" ,(local-file "rekado.pub"))
                     ("chris" ,(local-file "chris.pub"))
                     ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))

          registers the specified public keys for user accounts
          ‘rekado’, ‘chris’, and ‘root’.

          Additional authorized keys can be specified via
          ‘service-extension’.

          Note that this does _not_ interfere with the use of
          ‘~/.ssh/authorized_keys’.

     ‘log-level’ (default: ‘'info’)
          This is a symbol specifying the logging level: ‘quiet’,
          ‘fatal’, ‘error’, ‘info’, ‘verbose’, ‘debug’, etc.  See the
          man page for ‘sshd_config’ for the full list of level names.

     ‘extra-content’ (default: ‘""’)
          This field can be used to append arbitrary text to the
          configuration file.  It is especially useful for elaborate
          configurations that cannot be expressed otherwise.  This
          configuration, for example, would generally disable root
          logins, but permit them from one specific IP address:

               (openssh-configuration
                 (extra-content "\
               Match Address 192.168.0.1
                 PermitRootLogin yes"))

 -- Scheme Procedure: dropbear-service [CONFIG]
     Run the Dropbear SSH daemon
     (https://matt.ucc.asn.au/dropbear/dropbear.html) with the given
     CONFIG, a ‘<dropbear-configuration>’ object.

     For example, to specify a Dropbear service listening on port 1234,
     add this call to the operating system’s ‘services’ field:

          (dropbear-service (dropbear-configuration
                              (port-number 1234)))

 -- Data Type: dropbear-configuration
     This data type represents the configuration of a Dropbear SSH
     daemon.

     ‘dropbear’ (default: DROPBEAR)
          The Dropbear package to use.

     ‘port-number’ (default: 22)
          The TCP port where the daemon waits for incoming connections.

     ‘syslog-output?’ (default: ‘#t’)
          Whether to enable syslog output.

     ‘pid-file’ (default: ‘"/var/run/dropbear.pid"’)
          File name of the daemon’s PID file.

     ‘root-login?’ (default: ‘#f’)
          Whether to allow ‘root’ logins.

     ‘allow-empty-passwords?’ (default: ‘#f’)
          Whether to allow empty passwords.

     ‘password-authentication?’ (default: ‘#t’)
          Whether to enable password-based authentication.

 -- Scheme Variable: autossh-service-type
     This is the type for the AutoSSH
     (https://www.harding.motd.ca/autossh) program that runs a copy of
     ‘ssh’ and monitors it, restarting it as necessary should it die or
     stop passing traffic.  AutoSSH can be run manually from the
     command-line by passing arguments to the binary ‘autossh’ from the
     package ‘autossh’, but it can also be run as a Guix service.  This
     latter use case is documented here.

     AutoSSH can be used to forward local traffic to a remote machine
     using an SSH tunnel, and it respects the ‘~/.ssh/config’ of the
     user it is run as.

     For example, to specify a service running autossh as the user
     ‘pino’ and forwarding all local connections to port ‘8081’ to
     ‘remote:8081’ using an SSH tunnel, add this call to the operating
     system’s ‘services’ field:

          (service autossh-service-type
                   (autossh-configuration
                    (user "pino")
                    (ssh-options (list "-T" "-N" "-L" "8081:localhost:8081" "remote.net"))))

 -- Data Type: autossh-configuration
     This data type represents the configuration of an AutoSSH service.

     ‘user’ (default ‘"autossh"’)
          The user as which the AutoSSH service is to be run.  This
          assumes that the specified user exists.

     ‘poll’ (default ‘600’)
          Specifies the connection poll time in seconds.

     ‘first-poll’ (default ‘#f’)
          Specifies how many seconds AutoSSH waits before the first
          connection test.  After this first test, polling is resumed at
          the pace defined in ‘poll’.  When set to ‘#f’, the first poll
          is not treated specially and will also use the connection poll
          specified in ‘poll’.

     ‘gate-time’ (default ‘30’)
          Specifies how many seconds an SSH connection must be active
          before it is considered successful.

     ‘log-level’ (default ‘1’)
          The log level, corresponding to the levels used by syslog—so
          ‘0’ is the most silent while ‘7’ is the chattiest.

     ‘max-start’ (default ‘#f’)
          The maximum number of times SSH may be (re)started before
          AutoSSH exits.  When set to ‘#f’, no maximum is configured and
          AutoSSH may restart indefinitely.

     ‘message’ (default ‘""’)
          The message to append to the echo message sent when testing
          connections.

     ‘port’ (default ‘"0"’)
          The ports used for monitoring the connection.  When set to
          ‘"0"’, monitoring is disabled.  When set to ‘"N"’ where N is a
          positive integer, ports N and N+1 are used for monitoring the
          connection, such that port N is the base monitoring port and
          ‘n+1’ is the echo port.  When set to ‘"N:M"’ where N and M are
          positive integers, the ports N and M are used for monitoring
          the connection, such that port N is the base monitoring port
          and M is the echo port.

     ‘ssh-options’ (default ‘'()’)
          The list of command-line arguments to pass to ‘ssh’ when it is
          run.  Options ‘-f’ and ‘-M’ are reserved for AutoSSH and may
          cause undefined behaviour.

 -- Scheme Variable: webssh-service-type
     This is the type for the WebSSH (https://webssh.huashengdun.org/)
     program that runs a web SSH client.  WebSSH can be run manually
     from the command-line by passing arguments to the binary ‘wssh’
     from the package ‘webssh’, but it can also be run as a Guix
     service.  This latter use case is documented here.

     For example, to specify a service running WebSSH on loopback
     interface on port ‘8888’ with reject policy with a list of allowed
     to connection hosts, and NGINX as a reverse-proxy to this service
     listening for HTTPS connection, add this call to the operating
     system’s ‘services’ field:

          (service webssh-service-type
            (webssh-configuration (address "127.0.0.1")
                                  (port 8888)
                                  (policy 'reject)
                                  (known-hosts '("localhost ecdsa-sha2-nistp256 AAAA…"
                                                 "127.0.0.1 ecdsa-sha2-nistp256 AAAA…"))))

          (service nginx-service-type
                   (nginx-configuration
                    (server-blocks
                     (list
                      (nginx-server-configuration
                       (inherit %webssh-configuration-nginx)
                       (server-name '("webssh.example.com"))
                       (listen '("443 ssl"))
                       (ssl-certificate (letsencrypt-certificate "webssh.example.com"))
                       (ssl-certificate-key (letsencrypt-key "webssh.example.com"))
                       (locations
                        (cons (nginx-location-configuration
                               (uri "/.well-known")
                               (body '("root /var/www;")))
                              (nginx-server-configuration-locations %webssh-configuration-nginx))))))))

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

     ‘package’ (default: WEBSSH)
          ‘webssh’ package to use.

     ‘user-name’ (default: "WEBSSH")
          User name or user ID that file transfers to and from that
          module should take place.

     ‘group-name’ (default: "WEBSSH")
          Group name or group ID that will be used when accessing the
          module.

     ‘address’ (default: #F)
          IP address on which ‘webssh’ listens for incoming connections.

     ‘port’ (default: 8888)
          TCP port on which ‘webssh’ listens for incoming connections.

     ‘policy’ (default: #F)
          Connection policy.  REJECT policy requires to specify
          KNOWN-HOSTS.

     ‘known-hosts’ (default: ’())
          List of hosts which allowed for SSH connection from ‘webssh’.

     ‘log-file’ (default: ‘"/var/log/webssh.log"’)
          Name of the file where ‘webssh’ writes its log file.

     ‘log-level’ (default: #F)
          Logging level.

 -- Scheme Variable: %facebook-host-aliases
     This variable contains a string for use in ‘/etc/hosts’ (*note
     (libc)Host Names::).  Each line contains a entry that maps a known
     server name of the Facebook on-line service—e.g.,
     ‘www.facebook.com’—to the local host—‘127.0.0.1’ or its IPv6
     equivalent, ‘::1’.

     This variable is typically used in the ‘hosts-file’ field of an
     ‘operating-system’ declaration (*note ‘/etc/hosts’:
     operating-system Reference.):

          (use-modules (gnu) (guix))

          (operating-system
            (host-name "mymachine")
            ;; ...
            (hosts-file
              ;; Create a /etc/hosts file with aliases for "localhost"
              ;; and "mymachine", as well as for Facebook servers.
              (plain-file "hosts"
                          (string-append (local-host-aliases host-name)
                                         %facebook-host-aliases))))

     This mechanism can prevent programs running locally, such as Web
     browsers, from accessing Facebook.

   The ‘(gnu services avahi)’ provides the following definition.

 -- Scheme Variable: avahi-service-type
     This is the service that runs ‘avahi-daemon’, a system-wide
     mDNS/DNS-SD responder that allows for service discovery and
     “zero-configuration” host name lookups (see <https://avahi.org/>).
     Its value must be an ‘avahi-configuration’ record—see below.

     This service extends the name service cache daemon (nscd) so that
     it can resolve ‘.local’ host names using nss-mdns
     (https://0pointer.de/lennart/projects/nss-mdns/).  *Note Name
     Service Switch::, for information on host name resolution.

     Additionally, add the AVAHI package to the system profile so that
     commands such as ‘avahi-browse’ are directly usable.

 -- Data Type: avahi-configuration
     Data type representation the configuration for Avahi.

     ‘host-name’ (default: ‘#f’)
          If different from ‘#f’, use that as the host name to publish
          for this machine; otherwise, use the machine’s actual host
          name.

     ‘publish?’ (default: ‘#t’)
          When true, allow host names and services to be published
          (broadcast) over the network.

     ‘publish-workstation?’ (default: ‘#t’)
          When true, ‘avahi-daemon’ publishes the machine’s host name
          and IP address via mDNS on the local network.  To view the
          host names published on your local network, you can run:

               avahi-browse _workstation._tcp

     ‘wide-area?’ (default: ‘#f’)
          When true, DNS-SD over unicast DNS is enabled.

     ‘ipv4?’ (default: ‘#t’)
     ‘ipv6?’ (default: ‘#t’)
          These fields determine whether to use IPv4/IPv6 sockets.

     ‘domains-to-browse’ (default: ‘'()’)
          This is a list of domains to browse.

 -- Scheme Variable: openvswitch-service-type
     This is the type of the Open vSwitch (https://www.openvswitch.org)
     service, whose value should be an ‘openvswitch-configuration’
     object.

 -- Data Type: openvswitch-configuration
     Data type representing the configuration of Open vSwitch, a
     multilayer virtual switch which is designed to enable massive
     network automation through programmatic extension.

     ‘package’ (default: OPENVSWITCH)
          Package object of the Open vSwitch.

 -- Scheme Variable: pagekite-service-type
     This is the service type for the PageKite (https://pagekite.net)
     service, a tunneling solution for making localhost servers publicly
     visible, even from behind restrictive firewalls or NAT without
     forwarded ports.  The value for this service type is a
     ‘pagekite-configuration’ record.

     Here’s an example exposing the local HTTP and SSH daemons:

          (service pagekite-service-type
                   (pagekite-configuration
                     (kites '("http:@kitename:localhost:80:@kitesecret"
                              "raw/22:@kitename:localhost:22:@kitesecret"))
                     (extra-file "/etc/pagekite.rc")))

 -- Data Type: pagekite-configuration
     Data type representing the configuration of PageKite.

     ‘package’ (default: PAGEKITE)
          Package object of PageKite.

     ‘kitename’ (default: ‘#f’)
          PageKite name for authenticating to the frontend server.

     ‘kitesecret’ (default: ‘#f’)
          Shared secret for authenticating to the frontend server.  You
          should probably put this inside ‘extra-file’ instead.

     ‘frontend’ (default: ‘#f’)
          Connect to the named PageKite frontend server instead of the
          pagekite.net service.

     ‘kites’ (default: ‘'("http:@kitename:localhost:80:@kitesecret")’)
          List of service kites to use.  Exposes HTTP on port 80 by
          default.  The format is ‘proto:kitename:host:port:secret’.

     ‘extra-file’ (default: ‘#f’)
          Extra configuration file to read, which you are expected to
          create manually.  Use this to add additional options and
          manage shared secrets out-of-band.

 -- Scheme Variable: yggdrasil-service-type
     The service type for connecting to the Yggdrasil network
     (https://yggdrasil-network.github.io/), an early-stage
     implementation of a fully end-to-end encrypted IPv6 network.

          Yggdrasil provides name-independent routing with
          cryptographically generated addresses.  Static addressing
          means you can keep the same address as long as you want, even
          if you move to a new location, or generate a new address (by
          generating new keys) whenever you want.
          <https://yggdrasil-network.github.io/2018/07/28/addressing.html>

     Pass it a value of ‘yggdrasil-configuration’ to connect it to
     public peers and/or local peers.

     Here is an example using public peers and a static address.  The
     static signing and encryption keys are defined in
     ‘/etc/yggdrasil-private.conf’ (the default value for
     ‘config-file’).

          ;; part of the operating-system declaration
          (service yggdrasil-service-type
                        (yggdrasil-configuration
                         (autoconf? #f) ;; use only the public peers
                         (json-config
                         ;; choose one from
                         ;; https://github.com/yggdrasil-network/public-peers
                          '((peers . #("tcp://1.2.3.4:1337"))))
                         ;; /etc/yggdrasil-private.conf is the default value for config-file
                         ))
          # sample content for /etc/yggdrasil-private.conf
          {
            # Your public encryption key. Your peers may ask you for this to put
            # into their AllowedEncryptionPublicKeys configuration.
            EncryptionPublicKey: 378dc5...

            # Your private encryption key. DO NOT share this with anyone!
            EncryptionPrivateKey: 0777...

            # Your public signing key. You should not ordinarily need to share
            # this with anyone.
            SigningPublicKey: e1664...

            # Your private signing key. DO NOT share this with anyone!
            SigningPrivateKey: 0589d...
          }

 -- Data Type: yggdrasil-configuration
     Data type representing the configuration of Yggdrasil.

     ‘package’ (default: ‘yggdrasil’)
          Package object of Yggdrasil.

     ‘json-config’ (default: ‘'()’)
          Contents of ‘/etc/yggdrasil.conf’.  Will be merged with
          ‘/etc/yggdrasil-private.conf’.  Note that these settings are
          stored in the Guix store, which is readable to all users.  *Do
          not store your private keys in it*.  See the output of
          ‘yggdrasil -genconf’ for a quick overview of valid keys and
          their default values.

     ‘autoconf?’ (default: ‘#f’)
          Whether to use automatic mode.  Enabling it makes Yggdrasil
          use adynamic IP and peer with IPv6 neighbors.

     ‘log-level’ (default: ‘'info’)
          How much detail to include in logs.  Use ‘'debug’ for more
          detail.

     ‘log-to’ (default: ‘'stdout’)
          Where to send logs.  By default, the service logs standard
          output to ‘/var/log/yggdrasil.log’.  The alternative is
          ‘'syslog’, which sends output to the running syslog service.

     ‘config-file’ (default: ‘"/etc/yggdrasil-private.conf"’)
          What HJSON file to load sensitive data from.  This is where
          private keys should be stored, which are necessary to specify
          if you don’t want a randomized address after each restart.
          Use ‘#f’ to disable.  Options defined in this file take
          precedence over ‘json-config’.  Use the output of ‘yggdrasil
          -genconf’ as a starting point.  To configure a static address,
          delete everything except these options:

             • ‘EncryptionPublicKey’
             • ‘EncryptionPrivateKey’
             • ‘SigningPublicKey’
             • ‘SigningPrivateKey’

 -- Scheme Variable: ipfs-service-type
     The service type for connecting to the IPFS network
     (https://ipfs.io), a global, versioned, peer-to-peer file system.
     Pass it a ‘ipfs-configuration’ to change the ports used for the
     gateway and API.

     Here’s an example configuration, using some non-standard ports:

          (service ipfs-service-type
                   (ipfs-configuration
                    (gateway "/ip4/127.0.0.1/tcp/8880")
                    (api "/ip4/127.0.0.1/tcp/8881")))

 -- Data Type: ipfs-configuration
     Data type representing the configuration of IPFS.

     ‘package’ (default: ‘go-ipfs’)
          Package object of IPFS.

     ‘gateway’ (default: ‘"/ip4/127.0.0.1/tcp/8082"’)
          Address of the gateway, in ‘multiaddress’ format.

     ‘api’ (default: ‘"/ip4/127.0.0.1/tcp/5001"’)
          Address of the API endpoint, in ‘multiaddress’ format.

 -- Scheme Variable: keepalived-service-type
     This is the type for the Keepalived (https://www.keepalived.org/)
     routing software, ‘keepalived’.  Its value must be an
     ‘keepalived-configuration’ record as in this example for master
     machine:

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

     where ‘keepalived-master.conf’:

          vrrp_instance my-group {
            state MASTER
            interface enp9s0
            virtual_router_id 100
            priority 100
            unicast_peer { 10.0.0.2 }
            virtual_ipaddress {
              10.0.0.4/24
            }
          }

     and for backup machine:

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

     where ‘keepalived-backup.conf’:

          vrrp_instance my-group {
            state BACKUP
            interface enp9s0
            virtual_router_id 100
            priority 99
            unicast_peer { 10.0.0.3 }
            virtual_ipaddress {
              10.0.0.4/24
            }
          }


File: guix.info,  Node: Unattended Upgrades,  Next: X Window,  Prev: Networking Services,  Up: Services

10.8.5 Unattended Upgrades
--------------------------

Guix provides a service to perform _unattended upgrades_: periodically,
the system automatically reconfigures itself from the latest Guix.  Guix
System has several properties that make unattended upgrades safe:

   • upgrades are transactional (either the upgrade succeeds or it
     fails, but you cannot end up with an “in-between” system state);
   • the upgrade log is kept—you can view it with ‘guix system
     list-generations’—and you can roll back to any previous generation,
     should the upgraded system fail to behave as intended;
   • channel code is authenticated so you know you can only run genuine
     code (*note Channels::);
   • ‘guix system reconfigure’ prevents downgrades, which makes it
     immune to “downgrade attacks”.

   To set up unattended upgrades, add an instance of
‘unattended-upgrade-service-type’ like the one below to the list of your
operating system services:

     (service unattended-upgrade-service-type)

   The defaults above set up weekly upgrades: every Sunday at midnight.
You do not need to provide the operating system configuration file: it
uses ‘/run/current-system/configuration.scm’, which ensures it always
uses your latest configuration—*note provenance-service-type::, for more
information about this file.

   There are several things that can be configured, in particular the
periodicity and services (daemons) to be restarted upon completion.
When the upgrade is successful, the service takes care of deleting
system generations older that some threshold, as per ‘guix system
delete-generations’.  See the reference below for details.

   To ensure that upgrades are actually happening, you can run ‘guix
system describe’.  To investigate upgrade failures, visit the unattended
upgrade log file (see below).

 -- Scheme Variable: unattended-upgrade-service-type
     This is the service type for unattended upgrades.  It sets up an
     mcron job (*note Scheduled Job Execution::) that runs ‘guix system
     reconfigure’ from the latest version of the specified channels.

     Its value must be a ‘unattended-upgrade-configuration’ record (see
     below).

 -- Data Type: unattended-upgrade-configuration
     This data type represents the configuration of the unattended
     upgrade service.  The following fields are available:

     ‘schedule’ (default: ‘"30 01 * * 0"’)
          This is the schedule of upgrades, expressed as a gexp
          containing an mcron job schedule (*note mcron job
          specifications: (mcron)Guile Syntax.).

     ‘channels’ (default: ‘#~%default-channels’)
          This gexp specifies the channels to use for the upgrade (*note
          Channels::).  By default, the tip of the official ‘guix’
          channel is used.

     ‘operating-system-file’ (default: ‘"/run/current-system/configuration.scm"’)
          This field specifies the operating system configuration file
          to use.  The default is to reuse the config file of the
          current configuration.

          There are cases, though, where referring to
          ‘/run/current-system/configuration.scm’ is not enough, for
          instance because that file refers to extra files (SSH public
          keys, extra configuration files, etc.)  via ‘local-file’ and
          similar constructs.  For those cases, we recommend something
          along these lines:

               (unattended-upgrade-configuration
                 (operating-system-file
                   (file-append (local-file "." "config-dir" #:recursive? #t)
                                "/config.scm")))

          The effect here is to import all of the current directory into
          the store, and to refer to ‘config.scm’ within that directory.
          Therefore, uses of ‘local-file’ within ‘config.scm’ will work
          as expected.  *Note G-Expressions::, for information about
          ‘local-file’ and ‘file-append’.

     ‘services-to-restart’ (default: ‘'(mcron)’)
          This field specifies the Shepherd services to restart when the
          upgrade completes.

          Those services are restarted right away upon completion, as
          with ‘herd restart’, which ensures that the latest version is
          running—remember that by default ‘guix system reconfigure’
          only restarts services that are not currently running, which
          is conservative: it minimizes disruption but leaves outdated
          services running.

          Use ‘herd status’ to find out candidates for restarting.
          *Note Services::, for general information about services.
          Common services to restart would include ‘ntpd’ and
          ‘ssh-daemon’.

          By default, the ‘mcron’ service is restarted.  This ensures
          that the latest version of the unattended upgrade job will be
          used next time.

     ‘system-expiration’ (default: ‘(* 3 30 24 3600)’)
          This is the expiration time in seconds for system generations.
          System generations older that this amount of time are deleted
          with ‘guix system delete-generations’ when an upgrade
          completes.

               Note: The unattended upgrade service does not run the
               garbage collector.  You will probably want to set up your
               own mcron job to run ‘guix gc’ periodically.

     ‘maximum-duration’ (default: ‘3600’)
          Maximum duration in seconds for the upgrade; past that time,
          the upgrade aborts.

          This is primarily useful to ensure the upgrade does not end up
          rebuilding or re-downloading “the world”.

     ‘log-file’ (default: ‘"/var/log/unattended-upgrade.log"’)
          File where unattended upgrades are logged.


File: guix.info,  Node: X Window,  Next: Printing Services,  Prev: Unattended Upgrades,  Up: Services

10.8.6 X Window
---------------

Support for the X Window graphical display system—specifically Xorg—is
provided by the ‘(gnu services xorg)’ module.  Note that there is no
‘xorg-service’ procedure.  Instead, the X server is started by the
“login manager”, by default the GNOME Display Manager (GDM).

   GDM of course allows users to log in into window managers and desktop
environments other than GNOME; for those using GNOME, GDM is required
for features such as automatic screen locking.

   To use X11, you must install at least one “window manager”—for
example the ‘windowmaker’ or ‘openbox’ packages—preferably by adding it
to the ‘packages’ field of your operating system definition (*note
system-wide packages: operating-system Reference.).

 -- Scheme Variable: gdm-service-type
     This is the type for the GNOME Desktop Manager
     (https://wiki.gnome.org/Projects/GDM/) (GDM), a program that
     manages graphical display servers and handles graphical user
     logins.  Its value must be a ‘gdm-configuration’ (see below).

     GDM looks for “session types” described by the ‘.desktop’ files in
     ‘/run/current-system/profile/share/xsessions’ and allows users to
     choose a session from the log-in screen.  Packages such as ‘gnome’,
     ‘xfce’, and ‘i3’ provide ‘.desktop’ files; adding them to the
     system-wide set of packages automatically makes them available at
     the log-in screen.

     In addition, ‘~/.xsession’ files are honored.  When available,
     ‘~/.xsession’ must be an executable that starts a window manager
     and/or other X clients.

 -- Data Type: gdm-configuration
     ‘auto-login?’ (default: ‘#f’)
     ‘default-user’ (default: ‘#f’)
          When ‘auto-login?’ is false, GDM presents a log-in screen.

          When ‘auto-login?’ is true, GDM logs in directly as
          ‘default-user’.

     ‘debug?’ (default: ‘#f’)
          When true, GDM writes debug messages to its log.

     ‘gnome-shell-assets’ (default: ...)
          List of GNOME Shell assets needed by GDM: icon theme, fonts,
          etc.

     ‘xorg-configuration’ (default: ‘(xorg-configuration)’)
          Configuration of the Xorg graphical server.

     ‘xsession’ (default: ‘(xinitrc)’)
          Script to run before starting a X session.

     ‘dbus-daemon’ (default: ‘dbus-daemon-wrapper’)
          File name of the ‘dbus-daemon’ executable.

     ‘gdm’ (default: ‘gdm’)
          The GDM package to use.

 -- Scheme Variable: slim-service-type
     This is the type for the SLiM graphical login manager for X11.

     Like GDM, SLiM looks for session types described by ‘.desktop’
     files and allows users to choose a session from the log-in screen
     using ‘F1’.  It also honors ‘~/.xsession’ files.

     Unlike GDM, SLiM does not spawn the user session on a different VT
     after logging in, which means that you can only start one graphical
     session.  If you want to be able to run multiple graphical sessions
     at the same time you have to add multiple SLiM services to your
     system services.  The following example shows how to replace the
     default GDM service with two SLiM services on tty7 and tty8.

          (use-modules (gnu services)
                       (gnu services desktop)
                       (gnu services xorg)
                       (srfi srfi-1))  ;for 'remove'

          (operating-system
            ;; ...
            (services (cons* (service slim-service-type (slim-configuration
                                                         (display ":0")
                                                         (vt "vt7")))
                             (service slim-service-type (slim-configuration
                                                         (display ":1")
                                                         (vt "vt8")))
                             (modify-services %desktop-services
                               (delete gdm-service-type)))))

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

     ‘allow-empty-passwords?’ (default: ‘#t’)
          Whether to allow logins with empty passwords.

     ‘auto-login?’ (default: ‘#f’)
     ‘default-user’ (default: ‘""’)
          When ‘auto-login?’ is false, SLiM presents a log-in screen.

          When ‘auto-login?’ is true, SLiM logs in directly as
          ‘default-user’.

     ‘theme’ (default: ‘%default-slim-theme’)
     ‘theme-name’ (default: ‘%default-slim-theme-name’)
          The graphical theme to use and its name.

     ‘auto-login-session’ (default: ‘#f’)
          If true, this must be the name of the executable to start as
          the default session—e.g., ‘(file-append windowmaker
          "/bin/windowmaker")’.

          If false, a session described by one of the available
          ‘.desktop’ files in ‘/run/current-system/profile’ and
          ‘~/.guix-profile’ will be used.

               Note: You must install at least one window manager in the
               system profile or in your user profile.  Failing to do
               that, if ‘auto-login-session’ is false, you will be
               unable to log in.

     ‘xorg-configuration’ (default ‘(xorg-configuration)’)
          Configuration of the Xorg graphical server.

     ‘display’ (default ‘":0"’)
          The display on which to start the Xorg graphical server.

     ‘vt’ (default ‘"vt7"’)
          The VT on which to start the Xorg graphical server.

     ‘xauth’ (default: ‘xauth’)
          The XAuth package to use.

     ‘shepherd’ (default: ‘shepherd’)
          The Shepherd package used when invoking ‘halt’ and ‘reboot’.

     ‘sessreg’ (default: ‘sessreg’)
          The sessreg package used in order to register the session.

     ‘slim’ (default: ‘slim’)
          The SLiM package to use.

 -- Scheme Variable: %default-theme
 -- Scheme Variable: %default-theme-name
     The default SLiM theme and its name.

 -- Data Type: sddm-configuration
     This is the data type representing the SDDM service configuration.

     ‘display-server’ (default: "x11")
          Select display server to use for the greeter.  Valid values
          are ‘"x11"’ or ‘"wayland"’.

     ‘numlock’ (default: "on")
          Valid values are ‘"on"’, ‘"off"’ or ‘"none"’.

     ‘halt-command’ (default ‘#~(string-apppend #$shepherd "/sbin/halt")’)
          Command to run when halting.

     ‘reboot-command’ (default ‘#~(string-append #$shepherd "/sbin/reboot")’)
          Command to run when rebooting.

     ‘theme’ (default "maldives")
          Theme to use.  Default themes provided by SDDM are ‘"elarun"’,
          ‘"maldives"’ or ‘"maya"’.

     ‘themes-directory’ (default "/run/current-system/profile/share/sddm/themes")
          Directory to look for themes.

     ‘faces-directory’ (default "/run/current-system/profile/share/sddm/faces")
          Directory to look for faces.

     ‘default-path’ (default "/run/current-system/profile/bin")
          Default PATH to use.

     ‘minimum-uid’ (default: 1000)
          Minimum UID displayed in SDDM and allowed for log-in.

     ‘maximum-uid’ (default: 2000)
          Maximum UID to display in SDDM.

     ‘remember-last-user?’ (default #t)
          Remember last user.

     ‘remember-last-session?’ (default #t)
          Remember last session.

     ‘hide-users’ (default "")
          Usernames to hide from SDDM greeter.

     ‘hide-shells’ (default ‘#~(string-append #$shadow "/sbin/nologin")’)
          Users with shells listed will be hidden from the SDDM greeter.

     ‘session-command’ (default ‘#~(string-append #$sddm "/share/sddm/scripts/wayland-session")’)
          Script to run before starting a wayland session.

     ‘sessions-directory’ (default "/run/current-system/profile/share/wayland-sessions")
          Directory to look for desktop files starting wayland sessions.

     ‘xorg-configuration’ (default ‘(xorg-configuration)’)
          Configuration of the Xorg graphical server.

     ‘xauth-path’ (default ‘#~(string-append #$xauth "/bin/xauth")’)
          Path to xauth.

     ‘xephyr-path’ (default ‘#~(string-append #$xorg-server "/bin/Xephyr")’)
          Path to Xephyr.

     ‘xdisplay-start’ (default ‘#~(string-append #$sddm "/share/sddm/scripts/Xsetup")’)
          Script to run after starting xorg-server.

     ‘xdisplay-stop’ (default ‘#~(string-append #$sddm "/share/sddm/scripts/Xstop")’)
          Script to run before stopping xorg-server.

     ‘xsession-command’ (default: ‘xinitrc’)
          Script to run before starting a X session.

     ‘xsessions-directory’ (default: "/run/current-system/profile/share/xsessions")
          Directory to look for desktop files starting X sessions.

     ‘minimum-vt’ (default: 7)
          Minimum VT to use.

     ‘auto-login-user’ (default "")
          User to use for auto-login.

     ‘auto-login-session’ (default "")
          Desktop file to use for auto-login.

     ‘relogin?’ (default #f)
          Relogin after logout.

 -- Scheme Variable: sddm-service-type
     This is the type of the service to run the SDDM display manager
     (https://github.com/sddm/sddm).  Its value must be a
     ‘sddm-configuration’ record (see below).

     Here’s an example use:

          (service sddm-service-type
                   (sddm-configuration
                     (auto-login-user "alice")
                     (auto-login-session "xfce.desktop")))

 -- Data Type: sddm-configuration
     This data type represents the configuration of the SDDM login
     manager.  The available fields are:

     ‘sddm’ (default: ‘sddm’)
          The SDDM package to use.

     ‘display-server’ (default: ‘"x11"’)
          This must be either ‘"x11"’ or ‘"wayland"’.

     ‘auto-login-user’ (default: ‘""’)
          If non-empty, this is the user account under which to log in
          automatically.

     ‘auto-login-session’ (default: ‘""’)
          If non-empty, this is the ‘.desktop’ file name to use as the
          auto-login session.

 -- Data Type: xorg-configuration
     This data type represents the configuration of the Xorg graphical
     display server.  Note that there is no Xorg service; instead, the X
     server is started by a “display manager” such as GDM, SDDM, and
     SLiM.  Thus, the configuration of these display managers aggregates
     an ‘xorg-configuration’ record.

     ‘modules’ (default: ‘%default-xorg-modules’)
          This is a list of “module packages” loaded by the Xorg
          server—e.g., ‘xf86-video-vesa’, ‘xf86-input-keyboard’, and so
          on.

     ‘fonts’ (default: ‘%default-xorg-fonts’)
          This is a list of font directories to add to the server’s
          “font path”.

     ‘drivers’ (default: ‘'()’)
          This must be either the empty list, in which case Xorg chooses
          a graphics driver automatically, or a list of driver names
          that will be tried in this order—e.g., ‘("modesetting"
          "vesa")’.

     ‘resolutions’ (default: ‘'()’)
          When ‘resolutions’ is the empty list, Xorg chooses an
          appropriate screen resolution.  Otherwise, it must be a list
          of resolutions—e.g., ‘((1024 768) (640 480))’.

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

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

     ‘extra-config’ (default: ‘'()’)
          This is a list of strings or objects appended to the
          configuration file.  It is used to pass extra text to be added
          verbatim to the configuration file.

     ‘server’ (default: ‘xorg-server’)
          This is the package providing the Xorg server.

     ‘server-arguments’ (default: ‘%default-xorg-server-arguments’)
          This is the list of command-line arguments to pass to the X
          server.  The default is ‘-nolisten tcp’.

 -- Scheme Procedure: set-xorg-configuration CONFIG
          [LOGIN-MANAGER-SERVICE-TYPE]
     Tell the log-in manager (of type LOGIN-MANAGER-SERVICE-TYPE) to use
     CONFIG, an ‘<xorg-configuration>’ record.

     Since the Xorg configuration is embedded in the log-in manager’s
     configuration—e.g., ‘gdm-configuration’—this procedure provides a
     shorthand to set the Xorg configuration.

 -- Scheme Procedure: xorg-start-command [CONFIG]
     Return a ‘startx’ script in which the modules, fonts, etc.
     specified in CONFIG, are available.  The result should be used in
     place of ‘startx’.

     Usually the X server is started by a login manager.

 -- Scheme Procedure: screen-locker-service PACKAGE [PROGRAM]
     Add PACKAGE, a package for a screen locker or screen saver whose
     command is PROGRAM, to the set of setuid programs and add a PAM
     entry for it.  For example:

          (screen-locker-service xlockmore "xlock")

     makes the good ol’ XlockMore usable.


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

10.8.7 Printing Services
------------------------

The ‘(gnu services cups)’ module provides a Guix service definition for
the CUPS printing service.  To add printer support to a Guix system, add
a ‘cups-service’ to the operating system definition:

 -- Scheme Variable: cups-service-type
     The service type for the CUPS print server.  Its value should be a
     valid CUPS configuration (see below).  To use the default settings,
     simply write:
          (service cups-service-type)

   The CUPS configuration controls the basic things about your CUPS
installation: what interfaces it listens on, what to do if a print job
fails, how much logging to do, and so on.  To actually add a printer,
you have to visit the <http://localhost:631> URL, or use a tool such as
GNOME’s printer configuration services.  By default, configuring a CUPS
service will generate a self-signed certificate if needed, for secure
connections to the print server.

   Suppose you want to enable the Web interface of CUPS and also add
support for Epson printers via the ‘epson-inkjet-printer-escpr’ package
and for HP printers via the ‘hplip-minimal’ package.  You can do that
directly, like this (you need to use the ‘(gnu packages cups)’ module):

     (service cups-service-type
              (cups-configuration
                (web-interface? #t)
                (extensions
                  (list cups-filters epson-inkjet-printer-escpr hplip-minimal))))

   Note: If you wish to use the Qt5 based GUI which comes with the hplip
package then it is suggested that you install the ‘hplip’ package,
either in your OS configuration file or as your user.

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

   Available ‘cups-configuration’ fields are:

 -- ‘cups-configuration’ parameter: package cups
     The CUPS package.

 -- ‘cups-configuration’ parameter: package-list extensions (default:
          ‘(list brlaser cups-filters epson-inkjet-printer-escpr
          foomatic-filters hplip-minimal splix)’)
     Drivers and other extensions to the CUPS package.

 -- ‘cups-configuration’ parameter: files-configuration
          files-configuration
     Configuration of where to write logs, what directories to use for
     print spools, and related privileged configuration parameters.

     Available ‘files-configuration’ fields are:

      -- ‘files-configuration’ parameter: log-location access-log
          Defines the access log filename.  Specifying a blank filename
          disables access log generation.  The value ‘stderr’ causes log
          entries to be sent to the standard error file when the
          scheduler is running in the foreground, or to the system log
          daemon when run in the background.  The value ‘syslog’ causes
          log entries to be sent to the system log daemon.  The server
          name may be included in filenames using the string ‘%s’, as in
          ‘/var/log/cups/%s-access_log’.

          Defaults to ‘"/var/log/cups/access_log"’.

      -- ‘files-configuration’ parameter: file-name cache-dir
          Where CUPS should cache data.

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

      -- ‘files-configuration’ parameter: string config-file-perm
          Specifies the permissions for all configuration files that the
          scheduler writes.

          Note that the permissions for the printers.conf file are
          currently masked to only allow access from the scheduler user
          (typically root).  This is done because printer device URIs
          sometimes contain sensitive authentication information that
          should not be generally known on the system.  There is no way
          to disable this security feature.

          Defaults to ‘"0640"’.

      -- ‘files-configuration’ parameter: log-location error-log
          Defines the error log filename.  Specifying a blank filename
          disables error log generation.  The value ‘stderr’ causes log
          entries to be sent to the standard error file when the
          scheduler is running in the foreground, or to the system log
          daemon when run in the background.  The value ‘syslog’ causes
          log entries to be sent to the system log daemon.  The server
          name may be included in filenames using the string ‘%s’, as in
          ‘/var/log/cups/%s-error_log’.

          Defaults to ‘"/var/log/cups/error_log"’.

      -- ‘files-configuration’ parameter: string fatal-errors
          Specifies which errors are fatal, causing the scheduler to
          exit.  The kind strings are:

          ‘none’
               No errors are fatal.

          ‘all’
               All of the errors below are fatal.

          ‘browse’
               Browsing initialization errors are fatal, for example
               failed connections to the DNS-SD daemon.

          ‘config’
               Configuration file syntax errors are fatal.

          ‘listen’
               Listen or Port errors are fatal, except for IPv6 failures
               on the loopback or ‘any’ addresses.

          ‘log’
               Log file creation or write errors are fatal.

          ‘permissions’
               Bad startup file permissions are fatal, for example
               shared TLS certificate and key files with world-read
               permissions.

          Defaults to ‘"all -browse"’.

      -- ‘files-configuration’ parameter: boolean file-device?
          Specifies whether the file pseudo-device can be used for new
          printer queues.  The URI <file:///dev/null> is always allowed.

          Defaults to ‘#f’.

      -- ‘files-configuration’ parameter: string group
          Specifies the group name or ID that will be used when
          executing external programs.

          Defaults to ‘"lp"’.

      -- ‘files-configuration’ parameter: string log-file-perm
          Specifies the permissions for all log files that the scheduler
          writes.

          Defaults to ‘"0644"’.

      -- ‘files-configuration’ parameter: log-location page-log
          Defines the page log filename.  Specifying a blank filename
          disables page log generation.  The value ‘stderr’ causes log
          entries to be sent to the standard error file when the
          scheduler is running in the foreground, or to the system log
          daemon when run in the background.  The value ‘syslog’ causes
          log entries to be sent to the system log daemon.  The server
          name may be included in filenames using the string ‘%s’, as in
          ‘/var/log/cups/%s-page_log’.

          Defaults to ‘"/var/log/cups/page_log"’.

      -- ‘files-configuration’ parameter: string remote-root
          Specifies the username that is associated with unauthenticated
          accesses by clients claiming to be the root user.  The default
          is ‘remroot’.

          Defaults to ‘"remroot"’.

      -- ‘files-configuration’ parameter: file-name request-root
          Specifies the directory that contains print jobs and other
          HTTP request data.

          Defaults to ‘"/var/spool/cups"’.

      -- ‘files-configuration’ parameter: sandboxing sandboxing
          Specifies the level of security sandboxing that is applied to
          print filters, backends, and other child processes of the
          scheduler; either ‘relaxed’ or ‘strict’.  This directive is
          currently only used/supported on macOS.

          Defaults to ‘strict’.

      -- ‘files-configuration’ parameter: file-name server-keychain
          Specifies the location of TLS certificates and private keys.
          CUPS will look for public and private keys in this directory:
          ‘.crt’ files for PEM-encoded certificates and corresponding
          ‘.key’ files for PEM-encoded private keys.

          Defaults to ‘"/etc/cups/ssl"’.

      -- ‘files-configuration’ parameter: file-name server-root
          Specifies the directory containing the server configuration
          files.

          Defaults to ‘"/etc/cups"’.

      -- ‘files-configuration’ parameter: boolean sync-on-close?
          Specifies whether the scheduler calls fsync(2) after writing
          configuration or state files.

          Defaults to ‘#f’.

      -- ‘files-configuration’ parameter: space-separated-string-list
               system-group
          Specifies the group(s) to use for ‘@SYSTEM’ group
          authentication.

      -- ‘files-configuration’ parameter: file-name temp-dir
          Specifies the directory where temporary files are stored.

          Defaults to ‘"/var/spool/cups/tmp"’.

      -- ‘files-configuration’ parameter: string user
          Specifies the user name or ID that is used when running
          external programs.

          Defaults to ‘"lp"’.

      -- ‘files-configuration’ parameter: string set-env
          Set the specified environment variable to be passed to child
          processes.

          Defaults to ‘"variable value"’.

 -- ‘cups-configuration’ parameter: access-log-level access-log-level
     Specifies the logging level for the AccessLog file.  The ‘config’
     level logs when printers and classes are added, deleted, or
     modified and when configuration files are accessed or updated.  The
     ‘actions’ level logs when print jobs are submitted, held, released,
     modified, or canceled, and any of the conditions for ‘config’.  The
     ‘all’ level logs all requests.

     Defaults to ‘actions’.

 -- ‘cups-configuration’ parameter: boolean auto-purge-jobs?
     Specifies whether to purge job history data automatically when it
     is no longer required for quotas.

     Defaults to ‘#f’.

 -- ‘cups-configuration’ parameter: comma-separated-string-list
          browse-dns-sd-sub-types
     Specifies a list of DNS-SD sub-types to advertise for each shared
     printer.  For example, ‘"_cups" "_print"’ will tell network clients
     that both CUPS sharing and IPP Everywhere are supported.

     Defaults to ‘"_cups"’.

 -- ‘cups-configuration’ parameter: browse-local-protocols
          browse-local-protocols
     Specifies which protocols to use for local printer sharing.

     Defaults to ‘dnssd’.

 -- ‘cups-configuration’ parameter: boolean browse-web-if?
     Specifies whether the CUPS web interface is advertised.

     Defaults to ‘#f’.

 -- ‘cups-configuration’ parameter: boolean browsing?
     Specifies whether shared printers are advertised.

     Defaults to ‘#f’.

 -- ‘cups-configuration’ parameter: string classification
     Specifies the security classification of the server.  Any valid
     banner name can be used, including ‘"classified"’,
     ‘"confidential"’, ‘"secret"’, ‘"topsecret"’, and ‘"unclassified"’,
     or the banner can be omitted to disable secure printing functions.

     Defaults to ‘""’.

 -- ‘cups-configuration’ parameter: boolean classify-override?
     Specifies whether users may override the classification (cover
     page) of individual print jobs using the ‘job-sheets’ option.

     Defaults to ‘#f’.

 -- ‘cups-configuration’ parameter: default-auth-type default-auth-type
     Specifies the default type of authentication to use.

     Defaults to ‘Basic’.

 -- ‘cups-configuration’ parameter: default-encryption
          default-encryption
     Specifies whether encryption will be used for authenticated
     requests.

     Defaults to ‘Required’.

 -- ‘cups-configuration’ parameter: string default-language
     Specifies the default language to use for text and web content.

     Defaults to ‘"en"’.

 -- ‘cups-configuration’ parameter: string default-paper-size
     Specifies the default paper size for new print queues.  ‘"Auto"’
     uses a locale-specific default, while ‘"None"’ specifies there is
     no default paper size.  Specific size names are typically
     ‘"Letter"’ or ‘"A4"’.

     Defaults to ‘"Auto"’.

 -- ‘cups-configuration’ parameter: string default-policy
     Specifies the default access policy to use.

     Defaults to ‘"default"’.

 -- ‘cups-configuration’ parameter: boolean default-shared?
     Specifies whether local printers are shared by default.

     Defaults to ‘#t’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          dirty-clean-interval
     Specifies the delay for updating of configuration and state files,
     in seconds.  A value of 0 causes the update to happen as soon as
     possible, typically within a few milliseconds.

     Defaults to ‘30’.

 -- ‘cups-configuration’ parameter: error-policy error-policy
     Specifies what to do when an error occurs.  Possible values are
     ‘abort-job’, which will discard the failed print job; ‘retry-job’,
     which will retry the job at a later time; ‘retry-current-job’,
     which retries the failed job immediately; and ‘stop-printer’, which
     stops the printer.

     Defaults to ‘stop-printer’.

 -- ‘cups-configuration’ parameter: non-negative-integer filter-limit
     Specifies the maximum cost of filters that are run concurrently,
     which can be used to minimize disk, memory, and CPU resource
     problems.  A limit of 0 disables filter limiting.  An average print
     to a non-PostScript printer needs a filter limit of about 200.  A
     PostScript printer needs about half that (100).  Setting the limit
     below these thresholds will effectively limit the scheduler to
     printing a single job at any time.

     Defaults to ‘0’.

 -- ‘cups-configuration’ parameter: non-negative-integer filter-nice
     Specifies the scheduling priority of filters that are run to print
     a job.  The nice value ranges from 0, the highest priority, to 19,
     the lowest priority.

     Defaults to ‘0’.

 -- ‘cups-configuration’ parameter: host-name-lookups host-name-lookups
     Specifies whether to do reverse lookups on connecting clients.  The
     ‘double’ setting causes ‘cupsd’ to verify that the hostname
     resolved from the address matches one of the addresses returned for
     that hostname.  Double lookups also prevent clients with
     unregistered addresses from connecting to your server.  Only set
     this option to ‘#t’ or ‘double’ if absolutely required.

     Defaults to ‘#f’.

 -- ‘cups-configuration’ parameter: non-negative-integer job-kill-delay
     Specifies the number of seconds to wait before killing the filters
     and backend associated with a canceled or held job.

     Defaults to ‘30’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          job-retry-interval
     Specifies the interval between retries of jobs in seconds.  This is
     typically used for fax queues but can also be used with normal
     print queues whose error policy is ‘retry-job’ or
     ‘retry-current-job’.

     Defaults to ‘30’.

 -- ‘cups-configuration’ parameter: non-negative-integer job-retry-limit
     Specifies the number of retries that are done for jobs.  This is
     typically used for fax queues but can also be used with normal
     print queues whose error policy is ‘retry-job’ or
     ‘retry-current-job’.

     Defaults to ‘5’.

 -- ‘cups-configuration’ parameter: boolean keep-alive?
     Specifies whether to support HTTP keep-alive connections.

     Defaults to ‘#t’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          keep-alive-timeout
     Specifies how long an idle client connection remains open, in
     seconds.

     Defaults to ‘30’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          limit-request-body
     Specifies the maximum size of print files, IPP requests, and HTML
     form data.  A limit of 0 disables the limit check.

     Defaults to ‘0’.

 -- ‘cups-configuration’ parameter: multiline-string-list listen
     Listens on the specified interfaces for connections.  Valid values
     are of the form ADDRESS:PORT, where ADDRESS is either an IPv6
     address enclosed in brackets, an IPv4 address, or ‘*’ to indicate
     all addresses.  Values can also be file names of local UNIX domain
     sockets.  The Listen directive is similar to the Port directive but
     allows you to restrict access to specific interfaces or networks.

 -- ‘cups-configuration’ parameter: non-negative-integer listen-back-log
     Specifies the number of pending connections that will be allowed.
     This normally only affects very busy servers that have reached the
     MaxClients limit, but can also be triggered by large numbers of
     simultaneous connections.  When the limit is reached, the operating
     system will refuse additional connections until the scheduler can
     accept the pending ones.

     Defaults to ‘128’.

 -- ‘cups-configuration’ parameter: location-access-control-list
          location-access-controls
     Specifies a set of additional access controls.

     Available ‘location-access-controls’ fields are:

      -- ‘location-access-controls’ parameter: file-name path
          Specifies the URI path to which the access control applies.

      -- ‘location-access-controls’ parameter: access-control-list
               access-controls
          Access controls for all access to this path, in the same
          format as the ‘access-controls’ of ‘operation-access-control’.

          Defaults to ‘()’.

      -- ‘location-access-controls’ parameter:
               method-access-control-list method-access-controls
          Access controls for method-specific access to this path.

          Defaults to ‘()’.

          Available ‘method-access-controls’ fields are:

           -- ‘method-access-controls’ parameter: boolean reverse?
               If ‘#t’, apply access controls to all methods except the
               listed methods.  Otherwise apply to only the listed
               methods.

               Defaults to ‘#f’.

           -- ‘method-access-controls’ parameter: method-list methods
               Methods to which this access control applies.

               Defaults to ‘()’.

           -- ‘method-access-controls’ parameter: access-control-list
                    access-controls
               Access control directives, as a list of strings.  Each
               string should be one directive, such as ‘"Order
               allow,deny"’.

               Defaults to ‘()’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          log-debug-history
     Specifies the number of debugging messages that are retained for
     logging if an error occurs in a print job.  Debug messages are
     logged regardless of the LogLevel setting.

     Defaults to ‘100’.

 -- ‘cups-configuration’ parameter: log-level log-level
     Specifies the level of logging for the ErrorLog file.  The value
     ‘none’ stops all logging while ‘debug2’ logs everything.

     Defaults to ‘info’.

 -- ‘cups-configuration’ parameter: log-time-format log-time-format
     Specifies the format of the date and time in the log files.  The
     value ‘standard’ logs whole seconds while ‘usecs’ logs
     microseconds.

     Defaults to ‘standard’.

 -- ‘cups-configuration’ parameter: non-negative-integer max-clients
     Specifies the maximum number of simultaneous clients that are
     allowed by the scheduler.

     Defaults to ‘100’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          max-clients-per-host
     Specifies the maximum number of simultaneous clients that are
     allowed from a single address.

     Defaults to ‘100’.

 -- ‘cups-configuration’ parameter: non-negative-integer max-copies
     Specifies the maximum number of copies that a user can print of
     each job.

     Defaults to ‘9999’.

 -- ‘cups-configuration’ parameter: non-negative-integer max-hold-time
     Specifies the maximum time a job may remain in the ‘indefinite’
     hold state before it is canceled.  A value of 0 disables
     cancellation of held jobs.

     Defaults to ‘0’.

 -- ‘cups-configuration’ parameter: non-negative-integer max-jobs
     Specifies the maximum number of simultaneous jobs that are allowed.
     Set to 0 to allow an unlimited number of jobs.

     Defaults to ‘500’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          max-jobs-per-printer
     Specifies the maximum number of simultaneous jobs that are allowed
     per printer.  A value of 0 allows up to MaxJobs jobs per printer.

     Defaults to ‘0’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          max-jobs-per-user
     Specifies the maximum number of simultaneous jobs that are allowed
     per user.  A value of 0 allows up to MaxJobs jobs per user.

     Defaults to ‘0’.

 -- ‘cups-configuration’ parameter: non-negative-integer max-job-time
     Specifies the maximum time a job may take to print before it is
     canceled, in seconds.  Set to 0 to disable cancellation of “stuck”
     jobs.

     Defaults to ‘10800’.

 -- ‘cups-configuration’ parameter: non-negative-integer max-log-size
     Specifies the maximum size of the log files before they are
     rotated, in bytes.  The value 0 disables log rotation.

     Defaults to ‘1048576’.

 -- ‘cups-configuration’ parameter: non-negative-integer
          multiple-operation-timeout
     Specifies the maximum amount of time to allow between files in a
     multiple file print job, in seconds.

     Defaults to ‘300’.

 -- ‘cups-configuration’ parameter: string page-log-format
     Specifies the format of PageLog lines.  Sequences beginning with
     percent (‘%’) characters are replaced with the corresponding
     information, while all other characters are copied literally.  The
     following percent sequences are recognized:

     ‘%%’
          insert a single percent character

     ‘%{name}’
          insert the value of the specified IPP attribute

     ‘%C’
          insert the number of copies for the current page

     ‘%P’
          insert the current page number

     ‘%T’
          insert the current date and time in common log format

     ‘%j’
          insert the job ID

     ‘%p’
          insert the printer name

     ‘%u’
          insert the username

     A value of the empty string disables page logging.  The string ‘%p
     %u %j %T %P %C %{job-billing} %{job-originating-host-name}
     %{job-name} %{media} %{sides}’ creates a page log with the standard
     items.

     Defaults to ‘""’.

 -- ‘cups-configuration’ parameter: environment-variables
          environment-variables
     Passes the specified environment variable(s) to child processes; a
     list of strings.

     Defaults to ‘()’.

 -- ‘cups-configuration’ parameter: policy-configuration-list policies
     Specifies named access control policies.

     Available ‘policy-configuration’ fields are:

      -- ‘policy-configuration’ parameter: string name
          Name of the policy.

      -- ‘policy-configuration’ parameter: string job-private-access
          Specifies an access list for a job’s private values.  ‘@ACL’
          maps to the printer’s requesting-user-name-allowed or
          requesting-user-name-denied values.  ‘@OWNER’ maps to the
          job’s owner.  ‘@SYSTEM’ maps to the groups listed for the
          ‘system-group’ field of the ‘files-config’ configuration,
          which is reified into the ‘cups-files.conf(5)’ file.  Other
          possible elements of the access list include specific user
          names, and ‘@GROUP’ to indicate members of a specific group.
          The access list may also be simply ‘all’ or ‘default’.

          Defaults to ‘"@OWNER @SYSTEM"’.

      -- ‘policy-configuration’ parameter: string job-private-values
          Specifies the list of job values to make private, or ‘all’,
          ‘default’, or ‘none’.

          Defaults to ‘"job-name job-originating-host-name
          job-originating-user-name phone"’.

      -- ‘policy-configuration’ parameter: string
               subscription-private-access
          Specifies an access list for a subscription’s private values.
          ‘@ACL’ maps to the printer’s requesting-user-name-allowed or
          requesting-user-name-denied values.  ‘@OWNER’ maps to the
          job’s owner.  ‘@SYSTEM’ maps to the groups listed for the
          ‘system-group’ field of the ‘files-config’ configuration,
          which is reified into the ‘cups-files.conf(5)’ file.  Other
          possible elements of the access list include specific user
          names, and ‘@GROUP’ to indicate members of a specific group.
          The access list may also be simply ‘all’ or ‘default’.

          Defaults to ‘"@OWNER @SYSTEM"’.

      -- ‘policy-configuration’ parameter: string
               subscription-private-values
          Specifies the list of job values to make private, or ‘all’,
          ‘default’, or ‘none’.

          Defaults to ‘"notify-events notify-pull-method
          notify-recipient-uri notify-subscriber-user-name
          notify-user-data"’.

      -- ‘policy-configuration’ parameter: operation-access-control-list
               access-controls
          Access control by IPP operation.

          Defaults to ‘()’.

 -- ‘cups-configuration’ parameter: boolean-or-non-negative-integer
          preserve-job-files
     Specifies whether job files (documents) are preserved after a job
     is printed.  If a numeric value is specified, job files are
     preserved for the indicated number of seconds after printing.
     Otherwise a boolean value applies indefinitely.

     Defaults to ‘86400’.

 -- ‘cups-configuration’ parameter: boolean-or-non-negative-integer
          preserve-job-history
     Specifies whether the job history is preserved after a job is
     printed.  If a numeric value is specified, the job history is
     preserved for the indicated number of seconds after printing.  If
     ‘#t’, the job history is preserved until the MaxJobs limit is
     reached.

     Defaults to ‘#t’.

 -- ‘cups-configuration’ parameter: non-negative-integer reload-timeout
     Specifies the amount of time to wait for job completion before
     restarting the scheduler.

     Defaults to ‘30’.

 -- ‘cups-configuration’ parameter: string rip-cache
     Specifies the maximum amount of memory to use when converting
     documents into bitmaps for a printer.

     Defaults to ‘"128m"’.

 -- ‘cups-configuration’ parameter: string server-admin
     Specifies the email address of the server administrator.

     Defaults to ‘"root@localhost.localdomain"’.

 -- ‘cups-configuration’ parameter: host-name-list-or-* server-alias
     The ServerAlias directive is used for HTTP Host header validation
     when clients connect to the scheduler from external interfaces.
     Using the special name ‘*’ can expose your system to known
     browser-based DNS rebinding attacks, even when accessing sites
     through a firewall.  If the auto-discovery of alternate names does
     not work, we recommend listing each alternate name with a
     ServerAlias directive instead of using ‘*’.

     Defaults to ‘*’.

 -- ‘cups-configuration’ parameter: string server-name
     Specifies the fully-qualified host name of the server.

     Defaults to ‘"localhost"’.

 -- ‘cups-configuration’ parameter: server-tokens server-tokens
     Specifies what information is included in the Server header of HTTP
     responses.  ‘None’ disables the Server header.  ‘ProductOnly’
     reports ‘CUPS’.  ‘Major’ reports ‘CUPS 2’.  ‘Minor’ reports ‘CUPS
     2.0’.  ‘Minimal’ reports ‘CUPS 2.0.0’.  ‘OS’ reports ‘CUPS 2.0.0
     (UNAME)’ where UNAME is the output of the ‘uname’ command.  ‘Full’
     reports ‘CUPS 2.0.0 (UNAME) IPP/2.0’.

     Defaults to ‘Minimal’.

 -- ‘cups-configuration’ parameter: multiline-string-list ssl-listen
     Listens on the specified interfaces for encrypted connections.
     Valid values are of the form ADDRESS:PORT, where ADDRESS is either
     an IPv6 address enclosed in brackets, an IPv4 address, or ‘*’ to
     indicate all addresses.

     Defaults to ‘()’.

 -- ‘cups-configuration’ parameter: ssl-options ssl-options
     Sets encryption options.  By default, CUPS only supports encryption
     using TLS v1.0 or higher using known secure cipher suites.
     Security is reduced when ‘Allow’ options are used, and enhanced
     when ‘Deny’ options are used.  The ‘AllowRC4’ option enables the
     128-bit RC4 cipher suites, which are required for some older
     clients.  The ‘AllowSSL3’ option enables SSL v3.0, which is
     required for some older clients that do not support TLS v1.0.  The
     ‘DenyCBC’ option disables all CBC cipher suites.  The ‘DenyTLS1.0’
     option disables TLS v1.0 support - this sets the minimum protocol
     version to TLS v1.1.

     Defaults to ‘()’.

 -- ‘cups-configuration’ parameter: boolean strict-conformance?
     Specifies whether the scheduler requires clients to strictly adhere
     to the IPP specifications.

     Defaults to ‘#f’.

 -- ‘cups-configuration’ parameter: non-negative-integer timeout
     Specifies the HTTP request timeout, in seconds.

     Defaults to ‘300’.

 -- ‘cups-configuration’ parameter: boolean web-interface?
     Specifies whether the web interface is enabled.

     Defaults to ‘#f’.

   At this point you’re probably thinking “oh dear, Guix manual, I like
you but you can stop already with the configuration options”.  Indeed.
However, one more point: it could be that you have an existing
‘cupsd.conf’ that you want to use.  In that case, you can pass an
‘opaque-cups-configuration’ as the configuration of a
‘cups-service-type’.

   Available ‘opaque-cups-configuration’ fields are:

 -- ‘opaque-cups-configuration’ parameter: package cups
     The CUPS package.

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

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

   For example, if your ‘cupsd.conf’ and ‘cups-files.conf’ are in
strings of the same name, you could instantiate a CUPS service like
this:

     (service cups-service-type
              (opaque-cups-configuration
                (cupsd.conf cupsd.conf)
                (cups-files.conf cups-files.conf)))


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

10.8.8 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 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.github.io).  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 '()]
     Return a service that runs the “system bus”, using DBUS, with
     support for SERVICES.

     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’
          ‘ignore’
     ‘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: ‘#f’)
          Whether battery percentage based policy should be used.  The
          default is to use the time left, change to ‘#t’ to use the
          percentage.

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

     ‘percentage-critical’ (default: ‘3’)
          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: 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’.


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

10.8.9 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 a 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’.

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

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

10.8.10 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: ‘#false’)
          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.

     ‘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

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

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 it’s
               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

10.8.12 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 ‘'disabled’.

   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

10.8.13 Telephony Services
--------------------------

This section describes how to set up and run a Murmur server.  Murmur is
the server of the Mumble (https://mumble.info) voice-over-IP (VoIP)
suite.

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

          (service murmur-service-type
                   (murmur-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 murmur
     ‘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 ‘murmur-configuration’ fields are:

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

     ‘user’ (default: ‘"murmur"’)
          User who will run the Murmur server.

     ‘group’ (default: ‘"murmur"’)
          Group of the user who will run the murmur 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/murmur/db.sqlite"’)
          File name of the sqlite database.  The service’s user will
          become the owner of the directory.

     ‘log-file’ (default: ‘"/var/log/murmur/murmur.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 murmur 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 murmur server version be exposed in ping requests.

     ‘log-days’ (default: ‘31’)
          Murmur 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 Murmur log to
          ensure that Murmur is using the cipher suites that you
          expected it to.

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

     ‘public-registration’ (default: ‘#f’)
          Must be a ‘<murmur-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: murmur-public-registration-configuration
     Configuration for public registration of a murmur 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.


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

10.8.14 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’ (or set to ‘disabled’, in which case 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’.

