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

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

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

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


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

12.9.22 VNC Services
--------------------

The ‘(gnu services vnc)’ module provides services related to “Virtual
Network Computing” (VNC), which makes it possible to locally use
graphical Xorg applications running on a remote machine.  Combined with
a graphical manager that supports the “X Display Manager Control
Protocol”, such as GDM (*note gdm::) or LightDM (*note lightdm::), it is
possible to remote an entire desktop for a multi-user environment.

Xvnc
....

Xvnc is a VNC server that spawns its own X window server; which means it
can run on headless servers.  The Xvnc implementations provided by the
‘tigervnc-server’ and ‘turbovnc’ aim to be fast and efficient.

 -- Variable: Scheme Variable xvnc-service-type

     The ‘xvnc-server-type’ service can be configured via the
     ‘xvnc-configuration’ record, documented below.  A second virtual
     display could be made available on a remote machine via the
     following configuration:

     (service xvnc-service-type
              (xvnc-configuration (display-number 10)))

   As a demonstration, the ‘xclock’ command could then be started on the
remote machine on display number 10, and it could be displayed locally
via the ‘vncviewer’ command:
     # Start xclock on the remote machine.
     ssh -L5910:localhost:5910 -- guix shell xclock -- env DISPLAY=:10 xclock
     # Access it via VNC.
     guix shell tigervnc-client -- vncviewer localhost:5910

   The following configuration combines XDMCP and Inetd to allow
multiple users to concurrently use the remote system, login in
graphically via the GDM display manager:

     (operating-system
       [...]
       (services (cons*
                  [...]
                  (service xvnc-service-type (xvnc-configuration
                                              (display-number 5)
                                              (localhost? #f)
                                              (xdmcp? #t)
                                              (inetd? #t)))
                  (modify-services %desktop-services
                    (gdm-service-type config => (gdm-configuration
                                                 (inherit config)
                                                 (auto-suspend? #f)
                                                 (xdmcp? #t)))))))

   A remote user could then connect to it by using the ‘vncviewer’
command or a compatible VNC client and start a desktop session of their
choosing:
     vncviewer remote-host:5905

     Warning: Unless your machine is in a controlled environment, for
     security reasons, the ‘localhost?’ configuration of the
     ‘xvnc-configuration’ record should be left to its default ‘#t’
     value and exposed via a secure means such as an SSH port forward.
     The XDMCP port, UDP 177 should also be blocked from the outside by
     a firewall, as it is not a secure protocol and can expose login
     credentials in clear.

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

     ‘xvnc’ (default: ‘tigervnc-server’) (type: file-like)
          The package that provides the Xvnc binary.

     ‘display-number’ (default: ‘0’) (type: number)
          The display number used by Xvnc.  You should set this to a
          number not already used a Xorg server.

     ‘geometry’ (default: ‘"1024x768"’) (type: string)
          The size of the desktop to be created.

     ‘depth’ (default: ‘24’) (type: color-depth)
          The pixel depth in bits of the desktop to be created.
          Accepted values are 16, 24 or 32.

     ‘port’ (type: maybe-port)
          The port on which to listen for connections from viewers.
          When left unspecified, it defaults to 5900 plus the display
          number.

     ‘ipv4?’ (default: ‘#t’) (type: boolean)
          Use IPv4 for incoming and outgoing connections.

     ‘ipv6?’ (default: ‘#t’) (type: boolean)
          Use IPv6 for incoming and outgoing connections.

     ‘password-file’ (type: maybe-string)
          The password file to use, if any.  Refer to vncpasswd(1) to
          learn how to generate such a file.

     ‘xdmcp?’ (default: ‘#f’) (type: boolean)
          Query the XDMCP server for a session.  This enables users to
          log in a desktop session from the login manager screen.  For a
          multiple users scenario, you’ll want to enable the ‘inetd?’
          option as well, so that each connection to the VNC server is
          handled separately rather than shared.

     ‘inetd?’ (default: ‘#f’) (type: boolean)
          Use an Inetd-style service, which runs the Xvnc server on
          demand.

     ‘frame-rate’ (default: ‘60’) (type: number)
          The maximum number of updates per second sent to each client.

     ‘security-types’ (default: ‘("None")’) (type: security-types)
          The allowed security schemes to use for incoming connections.
          The default is "None", which is safe given that Xvnc is
          configured to authenticate the user via the display manager,
          and only for local connections.  Accepted values are any of
          the following: ("None" "VncAuth" "Plain" "TLSNone" "TLSVnc"
          "TLSPlain" "X509None" "X509Vnc")

     ‘localhost?’ (default: ‘#t’) (type: boolean)
          Only allow connections from the same machine.  It is set to
          #true by default for security, which means SSH or another
          secure means should be used to expose the remote port.

     ‘log-level’ (default: ‘30’) (type: log-level)
          The log level, a number between 0 and 100, 100 meaning most
          verbose output.  The log messages are output to syslog.

     ‘extra-options’ (default: ‘()’) (type: strings)
          This can be used to provide extra Xvnc options not exposed via
          this <xvnc-configuration> record.


File: guix.info,  Node: VPN Services,  Next: Network File System,  Prev: VNC Services,  Up: Services

12.9.23 VPN Services
--------------------

The ‘(gnu services vpn)’ module provides services related to “virtual
private networks” (VPNs).

Bitmask
.......

 -- Scheme Variable: bitmask-service-type
     A service type for the Bitmask (https://bitmask.net) VPN client.
     It makes the client available in the system and loads its polkit
     policy.  Please note that the client expects an active
     polkit-agent, which is either run by your desktop-environment or
     should be run manually.

OpenVPN
.......

It provides a _client_ service for your machine to connect to a VPN, and
a _server_ service for your machine to host a VPN.

 -- Scheme Procedure: openvpn-client-service [#:config
          (openvpn-client-configuration)]

     Return a service that runs ‘openvpn’, a VPN daemon, as a client.

 -- Scheme Procedure: openvpn-server-service [#:config
          (openvpn-server-configuration)]

     Return a service that runs ‘openvpn’, a VPN daemon, as a server.

     Both can be run simultaneously.

 -- Data Type: openvpn-client-configuration
     Available ‘openvpn-client-configuration’ fields are:

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

     ‘pid-file’ (default: ‘"/var/run/openvpn/openvpn.pid"’) (type: string)
          The OpenVPN pid file.

     ‘proto’ (default: ‘udp’) (type: proto)
          The protocol (UDP or TCP) used to open a channel between
          clients and servers.

     ‘dev’ (default: ‘tun’) (type: dev)
          The device type used to represent the VPN connection.

     ‘ca’ (default: ‘"/etc/openvpn/ca.crt"’) (type: maybe-string)
          The certificate authority to check connections against.

     ‘cert’ (default: ‘"/etc/openvpn/client.crt"’) (type: maybe-string)
          The certificate of the machine the daemon is running on.  It
          should be signed by the authority given in ‘ca’.

     ‘key’ (default: ‘"/etc/openvpn/client.key"’) (type: maybe-string)
          The key of the machine the daemon is running on.  It must be
          the key whose certificate is ‘cert’.

     ‘comp-lzo?’ (default: ‘#t’) (type: boolean)
          Whether to use the lzo compression algorithm.

     ‘persist-key?’ (default: ‘#t’) (type: boolean)
          Don’t re-read key files across SIGUSR1 or –ping-restart.

     ‘persist-tun?’ (default: ‘#t’) (type: boolean)
          Don’t close and reopen TUN/TAP device or run up/down scripts
          across SIGUSR1 or –ping-restart restarts.

     ‘fast-io?’ (default: ‘#f’) (type: boolean)
          (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a
          call to poll/epoll/select prior to the write operation.

     ‘verbosity’ (default: ‘3’) (type: number)
          Verbosity level.

     ‘tls-auth’ (default: ‘#f’) (type: tls-auth-client)
          Add an additional layer of HMAC authentication on top of the
          TLS control channel to protect against DoS attacks.

     ‘auth-user-pass’ (type: maybe-string)
          Authenticate with server using username/password.  The option
          is a file containing username/password on 2 lines.  Do not use
          a file-like object as it would be added to the store and
          readable by any user.

     ‘verify-key-usage?’ (default: ‘#t’) (type: key-usage)
          Whether to check the server certificate has server usage
          extension.

     ‘bind?’ (default: ‘#f’) (type: bind)
          Bind to a specific local port number.

     ‘resolv-retry?’ (default: ‘#t’) (type: resolv-retry)
          Retry resolving server address.

     ‘remote’ (default: ‘()’) (type: openvpn-remote-list)
          A list of remote servers to connect to.

           -- Data Type: openvpn-remote-configuration
               Available ‘openvpn-remote-configuration’ fields are:

               ‘name’ (default: ‘"my-server"’) (type: string)
                    Server name.

               ‘port’ (default: ‘1194’) (type: number)
                    Port number the server listens to.

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

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

     ‘pid-file’ (default: ‘"/var/run/openvpn/openvpn.pid"’) (type: string)
          The OpenVPN pid file.

     ‘proto’ (default: ‘udp’) (type: proto)
          The protocol (UDP or TCP) used to open a channel between
          clients and servers.

     ‘dev’ (default: ‘tun’) (type: dev)
          The device type used to represent the VPN connection.

     ‘ca’ (default: ‘"/etc/openvpn/ca.crt"’) (type: maybe-string)
          The certificate authority to check connections against.

     ‘cert’ (default: ‘"/etc/openvpn/client.crt"’) (type: maybe-string)
          The certificate of the machine the daemon is running on.  It
          should be signed by the authority given in ‘ca’.

     ‘key’ (default: ‘"/etc/openvpn/client.key"’) (type: maybe-string)
          The key of the machine the daemon is running on.  It must be
          the key whose certificate is ‘cert’.

     ‘comp-lzo?’ (default: ‘#t’) (type: boolean)
          Whether to use the lzo compression algorithm.

     ‘persist-key?’ (default: ‘#t’) (type: boolean)
          Don’t re-read key files across SIGUSR1 or –ping-restart.

     ‘persist-tun?’ (default: ‘#t’) (type: boolean)
          Don’t close and reopen TUN/TAP device or run up/down scripts
          across SIGUSR1 or –ping-restart restarts.

     ‘fast-io?’ (default: ‘#f’) (type: boolean)
          (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a
          call to poll/epoll/select prior to the write operation.

     ‘verbosity’ (default: ‘3’) (type: number)
          Verbosity level.

     ‘tls-auth’ (default: ‘#f’) (type: tls-auth-server)
          Add an additional layer of HMAC authentication on top of the
          TLS control channel to protect against DoS attacks.

     ‘port’ (default: ‘1194’) (type: number)
          Specifies the port number on which the server listens.

     ‘server’ (default: ‘"10.8.0.0 255.255.255.0"’) (type: ip-mask)
          An ip and mask specifying the subnet inside the virtual
          network.

     ‘server-ipv6’ (default: ‘#f’) (type: cidr6)
          A CIDR notation specifying the IPv6 subnet inside the virtual
          network.

     ‘dh’ (default: ‘"/etc/openvpn/dh2048.pem"’) (type: string)
          The Diffie-Hellman parameters file.

     ‘ifconfig-pool-persist’ (default: ‘"/etc/openvpn/ipp.txt"’) (type: string)
          The file that records client IPs.

     ‘redirect-gateway?’ (default: ‘#f’) (type: gateway)
          When true, the server will act as a gateway for its clients.

     ‘client-to-client?’ (default: ‘#f’) (type: boolean)
          When true, clients are allowed to talk to each other inside
          the VPN.

     ‘keepalive’ (default: ‘(10 120)’) (type: keepalive)
          Causes ping-like messages to be sent back and forth over the
          link so that each side knows when the other side has gone
          down.  ‘keepalive’ requires a pair.  The first element is the
          period of the ping sending, and the second element is the
          timeout before considering the other side down.

     ‘max-clients’ (default: ‘100’) (type: number)
          The maximum number of clients.

     ‘status’ (default: ‘"/var/run/openvpn/status"’) (type: string)
          The status file.  This file shows a small report on current
          connection.  It is truncated and rewritten every minute.

     ‘client-config-dir’ (default: ‘()’) (type: openvpn-ccd-list)
          The list of configuration for some clients.

strongSwan
----------

Currently, the strongSwan service only provides legacy-style
configuration with ‘ipsec.conf’ and ‘ipsec.secrets’ files.

 -- Scheme Variable: strongswan-service-type
     A service type for configuring strongSwan for IPsec VPN (Virtual
     Private Networking).  Its value must be a
     ‘strongswan-configuration’ record as in this example:

          (service strongswan-service-type
                   (strongswan-configuration
                    (ipsec-conf "/etc/ipsec.conf")
                    (ipsec-secrets "/etc/ipsec.secrets")))

 -- Data Type: strongswan-configuration
     Data type representing the configuration of the StrongSwan service.

     ‘strongswan’
          The strongSwan package to use for this service.

     ‘ipsec-conf’ (default: ‘#f’)
          The file name of your ‘ipsec.conf’.  If not ‘#f’, then this
          and ‘ipsec-secrets’ must both be strings.

     ‘ipsec-secrets’ (default ‘#f’)
          The file name of your ‘ipsec.secrets’.  If not ‘#f’, then this
          and ‘ipsec-conf’ must both be strings.

Wireguard
.........

 -- Scheme Variable: wireguard-service-type
     A service type for a Wireguard tunnel interface.  Its value must be
     a ‘wireguard-configuration’ record as in this example:

          (service wireguard-service-type
                   (wireguard-configuration
                    (peers
                     (list
                      (wireguard-peer
                       (name "my-peer")
                       (endpoint "my.wireguard.com:51820")
                       (public-key "hzpKg9X1yqu1axN6iJp0mWf6BZGo8m1wteKwtTmDGF4=")
                       (allowed-ips '("10.0.0.2/32")))))))

 -- Data Type: wireguard-configuration
     Data type representing the configuration of the Wireguard service.

     ‘wireguard’
          The wireguard package to use for this service.

     ‘interface’ (default: ‘"wg0"’)
          The interface name for the VPN.

     ‘addresses’ (default: ‘'("10.0.0.1/32")’)
          The IP addresses to be assigned to the above interface.

     ‘port’ (default: ‘51820’)
          The port on which to listen for incoming connections.

     ‘dns’ (default: ‘#f’)
          The DNS server(s) to announce to VPN clients via DHCP.

     ‘private-key’ (default: ‘"/etc/wireguard/private.key"’)
          The private key file for the interface.  It is automatically
          generated if the file does not exist.

     ‘peers’ (default: ‘'()’)
          The authorized peers on this interface.  This is a list of
          WIREGUARD-PEER records.

     ‘pre-up’ (default: ‘'()’)
          The script commands to be run before setting up the interface.

     ‘post-up’ (default: ‘'()’)
          The script commands to be run after setting up the interface.

     ‘pre-down’ (default: ‘'()’)
          The script commands to be run before tearing down the
          interface.

     ‘post-down’ (default: ‘'()’)
          The script commands to be run after tearing down the
          interface.

     ‘table’ (default: ‘"auto"’)
          The routing table to which routes are added, as a string.
          There are two special values: ‘"off"’ that disables the
          creation of routes altogether, and ‘"auto"’ (the default) that
          adds routes to the default table and enables special handling
          of default routes.

 -- Data Type: wireguard-peer
     Data type representing a Wireguard peer attached to a given
     interface.

     ‘name’
          The peer name.

     ‘endpoint’ (default: ‘#f’)
          The optional endpoint for the peer, such as
          ‘"demo.wireguard.com:51820"’.

     ‘public-key’
          The peer public-key represented as a base64 string.

     ‘allowed-ips’
          A list of IP addresses from which incoming traffic for this
          peer is allowed and to which incoming traffic for this peer is
          directed.

     ‘keep-alive’ (default: ‘#f’)
          An optional time interval in seconds.  A packet will be sent
          to the server endpoint once per time interval.  This helps
          receiving incoming connections from this peer when you are
          behind a NAT or a firewall.


File: guix.info,  Node: Network File System,  Next: Samba Services,  Prev: VPN Services,  Up: Services

12.9.24 Network File System
---------------------------

The ‘(gnu services nfs)’ module provides the following services, which
are most commonly used in relation to mounting or exporting directory
trees as “network file systems” (NFS).

   While it is possible to use the individual components that together
make up a Network File System service, we recommended to configure an
NFS server with the ‘nfs-service-type’.

NFS Service
...........

The NFS service takes care of setting up all NFS component services,
kernel configuration file systems, and installs configuration files in
the locations that NFS expects.

 -- Scheme Variable: nfs-service-type
     A service type for a complete NFS server.

 -- Data Type: nfs-configuration
     This data type represents the configuration of the NFS service and
     all of its subsystems.

     It has the following parameters:
     ‘nfs-utils’ (default: ‘nfs-utils’)
          The nfs-utils package to use.

     ‘nfs-versions’ (default: ‘'("4.2" "4.1" "4.0")’)
          If a list of string values is provided, the ‘rpc.nfsd’ daemon
          will be limited to supporting the given versions of the NFS
          protocol.

     ‘exports’ (default: ‘'()’)
          This is a list of directories the NFS server should export.
          Each entry is a list consisting of two elements: a directory
          name and a string containing all options.  This is an example
          in which the directory ‘/export’ is served to all NFS clients
          as a read-only share:

               (nfs-configuration
                (exports
                 '(("/export"
                    "*(ro,insecure,no_subtree_check,crossmnt,fsid=0)"))))

     ‘rpcmountd-port’ (default: ‘#f’)
          The network port that the ‘rpc.mountd’ daemon should use.

     ‘rpcstatd-port’ (default: ‘#f’)
          The network port that the ‘rpc.statd’ daemon should use.

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

     ‘idmap-domain’ (default: ‘"localdomain"’)
          The local NFSv4 domain name.

     ‘nfsd-port’ (default: ‘2049’)
          The network port that the ‘nfsd’ daemon should use.

     ‘nfsd-threads’ (default: ‘8’)
          The number of threads used by the ‘nfsd’ daemon.

     ‘nfsd-tcp?’ (default: ‘#t’)
          Whether the ‘nfsd’ daemon should listen on a TCP socket.

     ‘nfsd-udp?’ (default: ‘#f’)
          Whether the ‘nfsd’ daemon should listen on a UDP socket.

     ‘pipefs-directory’ (default: ‘"/var/lib/nfs/rpc_pipefs"’)
          The directory where the pipefs file system is mounted.

     ‘debug’ (default: ‘'()"’)
          A list of subsystems for which debugging output should be
          enabled.  This is a list of symbols.  Any of these symbols are
          valid: ‘nfsd’, ‘nfs’, ‘rpc’, ‘idmap’, ‘statd’, or ‘mountd’.

   If you don’t need a complete NFS service or prefer to build it
yourself you can use the individual component services that are
documented below.

RPC Bind Service
................

The RPC Bind service provides a facility to map program numbers into
universal addresses.  Many NFS related services use this facility.
Hence it is automatically started when a dependent service starts.

 -- Scheme Variable: rpcbind-service-type
     A service type for the RPC portmapper daemon.

 -- Data Type: rpcbind-configuration
     Data type representing the configuration of the RPC Bind Service.
     This type has the following parameters:
     ‘rpcbind’ (default: ‘rpcbind’)
          The rpcbind package to use.

     ‘warm-start?’ (default: ‘#t’)
          If this parameter is ‘#t’, then the daemon will read a state
          file on startup thus reloading state information saved by a
          previous instance.

Pipefs Pseudo File System
.........................

The pipefs file system is used to transfer NFS related data between the
kernel and user space programs.

 -- Scheme Variable: pipefs-service-type
     A service type for the pipefs pseudo file system.

 -- Data Type: pipefs-configuration
     Data type representing the configuration of the pipefs pseudo file
     system service.  This type has the following parameters:
     ‘mount-point’ (default: ‘"/var/lib/nfs/rpc_pipefs"’)
          The directory to which the file system is to be attached.

GSS Daemon Service
..................

The “global security system” (GSS) daemon provides strong security for
RPC based protocols.  Before exchanging RPC requests an RPC client must
establish a security context.  Typically this is done using the Kerberos
command ‘kinit’ or automatically at login time using PAM services (*note
Kerberos Services::).

 -- Scheme Variable: gss-service-type
     A service type for the Global Security System (GSS) daemon.

 -- Data Type: gss-configuration
     Data type representing the configuration of the GSS daemon service.
     This type has the following parameters:
     ‘nfs-utils’ (default: ‘nfs-utils’)
          The package in which the ‘rpc.gssd’ command is to be found.

     ‘pipefs-directory’ (default: ‘"/var/lib/nfs/rpc_pipefs"’)
          The directory where the pipefs file system is mounted.

IDMAP Daemon Service
....................

The idmap daemon service provides mapping between user IDs and user
names.  Typically it is required in order to access file systems mounted
via NFSv4.

 -- Scheme Variable: idmap-service-type
     A service type for the Identity Mapper (IDMAP) daemon.

 -- Data Type: idmap-configuration
     Data type representing the configuration of the IDMAP daemon
     service.  This type has the following parameters:
     ‘nfs-utils’ (default: ‘nfs-utils’)
          The package in which the ‘rpc.idmapd’ command is to be found.

     ‘pipefs-directory’ (default: ‘"/var/lib/nfs/rpc_pipefs"’)
          The directory where the pipefs file system is mounted.

     ‘domain’ (default: ‘#f’)
          The local NFSv4 domain name.  This must be a string or ‘#f’.
          If it is ‘#f’ then the daemon will use the host’s fully
          qualified domain name.

     ‘verbosity’ (default: ‘0’)
          The verbosity level of the daemon.


File: guix.info,  Node: Samba Services,  Next: Continuous Integration,  Prev: Network File System,  Up: Services

12.9.25 Samba Services
----------------------

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

Samba
.....

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

 -- Variable: Scheme variable samba-service-type

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

12.9.26 Continuous Integration
------------------------------

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     ‘use-substitutes?’ (default: ‘#f’)
          This allows using substitutes to avoid building every
          dependencies of a job from source.

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

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

     ‘extra-options’ (default: ‘'()’)
          Extra options to pass when running the Cuirass processes.

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

Cuirass supports two mechanisms to build derivations.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Laminar
.......

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

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

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

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

          (service laminar-service-type)

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

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

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

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

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

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

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

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

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


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

12.9.27 Power Management Services
---------------------------------

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

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

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

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

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

   Available ‘tlp-configuration’ fields are:

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

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

     Defaults to ‘#t’.

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

     Defaults to ‘"AC"’.

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

     Defaults to ‘0’.

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

     Defaults to ‘2’.

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

     Defaults to ‘15’.

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

     Defaults to ‘60’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘#t’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘"performance"’.

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

     Defaults to ‘"powersave"’.

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

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

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

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘"max_performance"’.

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

     Defaults to ‘"min_power"’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘15’.

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

     Defaults to ‘"performance"’.

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

     Defaults to ‘"powersave"’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘"high"’.

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

     Defaults to ‘"low"’.

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

     Defaults to ‘"performance"’.

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

     Defaults to ‘"battery"’.

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

     Defaults to ‘"auto"’.

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

     Defaults to ‘"auto"’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘#t’.

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

     Defaults to ‘#t’.

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

     Defaults to ‘0’.

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

     Defaults to ‘1’.

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

     Defaults to ‘#t’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘"sr0"’.

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

     Defaults to ‘"on"’.

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

     Defaults to ‘"auto"’.

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

     Defaults to ‘#t’.

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

     Defaults to ‘disabled’.

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

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

     Defaults to ‘#t’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘#t’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘disabled’.

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

     Defaults to ‘#f’.

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

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

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

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

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

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

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


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

12.9.28 Audio Services
----------------------

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

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

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

   The following example shows how one might run ‘mpd’ as user ‘"bob"’
on port ‘6666’.  It uses pulseaudio for output.

     (service mpd-service-type
              (mpd-configuration
               (user "bob")
               (port "6666")))

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

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

     ‘user’ (default: ‘"mpd"’)
          The user to run mpd as.

     ‘music-dir’ (default: ‘"~/Music"’)
          The directory to scan for music files.

     ‘playlist-dir’ (default: ‘"~/.mpd/playlists"’)
          The directory to store playlists.

     ‘db-file’ (default: ‘"~/.mpd/tag_cache"’)
          The location of the music database.

     ‘state-file’ (default: ‘"~/.mpd/state"’)
          The location of the file that stores current MPD’s state.

     ‘sticker-file’ (default: ‘"~/.mpd/sticker.sql"’)
          The location of the sticker database.

     ‘port’ (default: ‘"6600"’)
          The port to run mpd on.

     ‘address’ (default: ‘"any"’)
          The address that mpd will bind to.  To use a Unix domain
          socket, an absolute path can be specified here.

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

 -- Data Type: mpd-output
     Data type representing an ‘mpd’ audio output.

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

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

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

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

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

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

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

   The following example shows a configuration of ‘mpd’ that provides an
HTTP audio streaming output.

     (service mpd-service-type
              (mpd-configuration
                (outputs
                  (list (mpd-output
                          (name "streaming")
                          (type "httpd")
                          (mixer-type 'null)
                          (extra-options
                           `((encoder . "vorbis")
                             (port    . "8080"))))))))


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

12.9.29 Virtualization Services
-------------------------------

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

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

‘libvirtd’ is the server side daemon component of the libvirt
virtualization management system.  This daemon runs on host servers and
performs required management tasks for virtualized guests.

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

          (service libvirt-service-type
                   (libvirt-configuration
                    (unix-sock-group "libvirt")
                    (tls-port "16555")))

   Available ‘libvirt-configuration’ fields are:

 -- ‘libvirt-configuration’ parameter: package libvirt
     Libvirt package.

 -- ‘libvirt-configuration’ parameter: boolean listen-tls?
     Flag listening for secure TLS connections on the public TCP/IP
     port.  You must set ‘listen’ for this to have any effect.

     It is necessary to setup a CA and issue server certificates before
     using this capability.

     Defaults to ‘#t’.

 -- ‘libvirt-configuration’ parameter: boolean listen-tcp?
     Listen for unencrypted TCP connections on the public TCP/IP port.
     You must set ‘listen’ for this to have any effect.

     Using the TCP socket requires SASL authentication by default.  Only
     SASL mechanisms which support data encryption are allowed.  This is
     DIGEST_MD5 and GSSAPI (Kerberos5).

     Defaults to ‘#f’.

 -- ‘libvirt-configuration’ parameter: string tls-port
     Port for accepting secure TLS connections.  This can be a port
     number, or service name.

     Defaults to ‘"16514"’.

 -- ‘libvirt-configuration’ parameter: string tcp-port
     Port for accepting insecure TCP connections.  This can be a port
     number, or service name.

     Defaults to ‘"16509"’.

 -- ‘libvirt-configuration’ parameter: string listen-addr
     IP address or hostname used for client connections.

     Defaults to ‘"0.0.0.0"’.

 -- ‘libvirt-configuration’ parameter: boolean mdns-adv?
     Flag toggling mDNS advertisement of the libvirt service.

     Alternatively can disable for all services on a host by stopping
     the Avahi daemon.

     Defaults to ‘#f’.

 -- ‘libvirt-configuration’ parameter: string mdns-name
     Default mDNS advertisement name.  This must be unique on the
     immediate broadcast network.

     Defaults to ‘"Virtualization Host <hostname>"’.

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

     Defaults to ‘"root"’.

 -- ‘libvirt-configuration’ parameter: string unix-sock-ro-perms
     UNIX socket permissions for the R/O socket.  This is used for
     monitoring VM status only.

     Defaults to ‘"0777"’.

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

     Defaults to ‘"0770"’.

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

     Defaults to ‘"0777"’.

 -- ‘libvirt-configuration’ parameter: string unix-sock-dir
     The directory in which sockets will be found/created.

     Defaults to ‘"/var/run/libvirt"’.

 -- ‘libvirt-configuration’ parameter: string auth-unix-ro
     Authentication scheme for UNIX read-only sockets.  By default
     socket permissions allow anyone to connect

     Defaults to ‘"polkit"’.

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

     Defaults to ‘"polkit"’.

 -- ‘libvirt-configuration’ parameter: string auth-tcp
     Authentication scheme for TCP sockets.  If you don’t enable SASL,
     then all TCP traffic is cleartext.  Don’t do this outside of a
     dev/test scenario.

     Defaults to ‘"sasl"’.

 -- ‘libvirt-configuration’ parameter: string auth-tls
     Authentication scheme for TLS sockets.  TLS sockets already have
     encryption provided by the TLS layer, and limited authentication is
     done by certificates.

     It is possible to make use of any SASL authentication mechanism as
     well, by using ’sasl’ for this option

     Defaults to ‘"none"’.

 -- ‘libvirt-configuration’ parameter: optional-list access-drivers
     API access control scheme.

     By default an authenticated user is allowed access to all APIs.
     Access drivers can place restrictions on this.

     Defaults to ‘()’.

 -- ‘libvirt-configuration’ parameter: string key-file
     Server key file path.  If set to an empty string, then no private
     key is loaded.

     Defaults to ‘""’.

 -- ‘libvirt-configuration’ parameter: string cert-file
     Server key file path.  If set to an empty string, then no
     certificate is loaded.

     Defaults to ‘""’.

 -- ‘libvirt-configuration’ parameter: string ca-file
     Server key file path.  If set to an empty string, then no CA
     certificate is loaded.

     Defaults to ‘""’.

 -- ‘libvirt-configuration’ parameter: string crl-file
     Certificate revocation list path.  If set to an empty string, then
     no CRL is loaded.

     Defaults to ‘""’.

 -- ‘libvirt-configuration’ parameter: boolean tls-no-sanity-cert
     Disable verification of our own server certificates.

     When libvirtd starts it performs some sanity checks against its own
     certificates.

     Defaults to ‘#f’.

 -- ‘libvirt-configuration’ parameter: boolean tls-no-verify-cert
     Disable verification of client certificates.

     Client certificate verification is the primary authentication
     mechanism.  Any client which does not present a certificate signed
     by the CA will be rejected.

     Defaults to ‘#f’.

 -- ‘libvirt-configuration’ parameter: optional-list tls-allowed-dn-list
     Whitelist of allowed x509 Distinguished Name.

     Defaults to ‘()’.

 -- ‘libvirt-configuration’ parameter: optional-list
          sasl-allowed-usernames
     Whitelist of allowed SASL usernames.  The format for username
     depends on the SASL authentication mechanism.

     Defaults to ‘()’.

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

     Defaults to ‘"NORMAL"’.

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

     Defaults to ‘5000’.

 -- ‘libvirt-configuration’ parameter: integer max-queued-clients
     Maximum length of queue of connections waiting to be accepted by
     the daemon.  Note, that some protocols supporting retransmission
     may obey this so that a later reattempt at connection succeeds.

     Defaults to ‘1000’.

 -- ‘libvirt-configuration’ parameter: integer max-anonymous-clients
     Maximum length of queue of accepted but not yet authenticated
     clients.  Set this to zero to turn this feature off

     Defaults to ‘20’.

 -- ‘libvirt-configuration’ parameter: integer min-workers
     Number of workers to start up initially.

     Defaults to ‘5’.

 -- ‘libvirt-configuration’ parameter: integer max-workers
     Maximum number of worker threads.

     If the number of active clients exceeds ‘min-workers’, then more
     threads are spawned, up to max_workers limit.  Typically you’d want
     max_workers to equal maximum number of clients allowed.

     Defaults to ‘20’.

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

     Defaults to ‘5’.

 -- ‘libvirt-configuration’ parameter: integer max-requests
     Total global limit on concurrent RPC calls.

     Defaults to ‘20’.

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

     Defaults to ‘5’.

 -- ‘libvirt-configuration’ parameter: integer admin-min-workers
     Same as ‘min-workers’ but for the admin interface.

     Defaults to ‘1’.

 -- ‘libvirt-configuration’ parameter: integer admin-max-workers
     Same as ‘max-workers’ but for the admin interface.

     Defaults to ‘5’.

 -- ‘libvirt-configuration’ parameter: integer admin-max-clients
     Same as ‘max-clients’ but for the admin interface.

     Defaults to ‘5’.

 -- ‘libvirt-configuration’ parameter: integer admin-max-queued-clients
     Same as ‘max-queued-clients’ but for the admin interface.

     Defaults to ‘5’.

 -- ‘libvirt-configuration’ parameter: integer admin-max-client-requests
     Same as ‘max-client-requests’ but for the admin interface.

     Defaults to ‘5’.

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

     Defaults to ‘3’.

 -- ‘libvirt-configuration’ parameter: string log-filters
     Logging filters.

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

        • x:name

        • x:+name

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

        • 1: DEBUG

        • 2: INFO

        • 3: WARNING

        • 4: ERROR

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

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

 -- ‘libvirt-configuration’ parameter: string log-outputs
     Logging outputs.

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

     ‘x:stderr’
          output goes to stderr

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

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

     ‘x:journald’
          output to journald logging system

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

        • 1: DEBUG

        • 2: INFO

        • 3: WARNING

        • 4: ERROR

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

     Defaults to ‘"3:stderr"’.

 -- ‘libvirt-configuration’ parameter: integer audit-level
     Allows usage of the auditing subsystem to be altered

        • 0: disable all auditing

        • 1: enable auditing, only if enabled on host

        • 2: enable auditing, and exit if disabled on host.

     Defaults to ‘1’.

 -- ‘libvirt-configuration’ parameter: boolean audit-logging
     Send audit messages via libvirt logging infrastructure.

     Defaults to ‘#f’.

 -- ‘libvirt-configuration’ parameter: optional-string host-uuid
     Host UUID.  UUID must not have all digits be the same.

     Defaults to ‘""’.

 -- ‘libvirt-configuration’ parameter: string host-uuid-source
     Source to read host UUID.

        • ‘smbios’: fetch the UUID from ‘dmidecode -s system-uuid’

        • ‘machine-id’: fetch the UUID from ‘/etc/machine-id’

     If ‘dmidecode’ does not provide a valid UUID a temporary UUID will
     be generated.

     Defaults to ‘"smbios"’.

 -- ‘libvirt-configuration’ parameter: integer keepalive-interval
     A keepalive message is sent to a client after ‘keepalive_interval’
     seconds of inactivity to check if the client is still responding.
     If set to -1, libvirtd will never send keepalive requests; however
     clients can still send them and the daemon will send responses.

     Defaults to ‘5’.

 -- ‘libvirt-configuration’ parameter: integer keepalive-count
     Maximum number of keepalive messages that are allowed to be sent to
     the client without getting any response before the connection is
     considered broken.

     In other words, the connection is automatically closed
     approximately after ‘keepalive_interval * (keepalive_count + 1)’
     seconds since the last message received from the client.  When
     ‘keepalive-count’ is set to 0, connections will be automatically
     closed after ‘keepalive-interval’ seconds of inactivity without
     sending any keepalive messages.

     Defaults to ‘5’.

 -- ‘libvirt-configuration’ parameter: integer admin-keepalive-interval
     Same as above but for admin interface.

     Defaults to ‘5’.

 -- ‘libvirt-configuration’ parameter: integer admin-keepalive-count
     Same as above but for admin interface.

     Defaults to ‘5’.

 -- ‘libvirt-configuration’ parameter: integer ovs-timeout
     Timeout for Open vSwitch calls.

     The ‘ovs-vsctl’ utility is used for the configuration and its
     timeout option is set by default to 5 seconds to avoid potential
     infinite waits blocking libvirt.

     Defaults to ‘5’.

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

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

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

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

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

 -- Variable: ‘libvirt’ parameter package libvirt
     Libvirt package.

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

     Defaults to ‘3’.

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

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

        • x:name

        • x:+name

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

        • 1: DEBUG

        • 2: INFO

        • 3: WARNING

        • 4: ERROR

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

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

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

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

     ‘x:stderr’
          output goes to stderr

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

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

     ‘x:journald’
          output to journald logging system

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

        • 1: DEBUG

        • 2: INFO

        • 3: WARNING

        • 4: ERROR

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

     Defaults to ‘"3:stderr"’.

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

     Defaults to ‘1024’.

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

     Defaults to ‘2MB’

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

     Defaults to ‘3’

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

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

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

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

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

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

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

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

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

          You can run:

               guix build -s armhf-linux inkscape

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     herd start hurd-vm
     herd stop childhurd

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

     guix shell tigervnc-client -- vncviewer localhost:5900

   The default configuration (see ‘hurd-vm-configuration’ below) spawns
a secure shell (SSH) server in your GNU/Hurd system, which QEMU (the
virtual machine emulator) redirects to port 10222 on the host.  Thus,
you can connect over SSH to the childhurd with:

     ssh root@localhost -p 10022

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

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

     For example:

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

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

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

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

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

     ‘image’ (default: HURD-VM-DISK-IMAGE)
          The procedure used to build the disk-image built from this
          configuration.

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

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

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

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

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

          By default, it produces

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

          with forwarded ports:

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

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

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

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

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

          These files are automatically sent to the guest Hurd VM when
          it boots, including permissions.

          Having these files in place means that only a couple of things
          are missing to allow the host to offload ‘i586-gnu’ builds to
          the childhurd:

            1. Authorizing the childhurd’s key on the host so that the
               host accepts build results coming from the childhurd,
               which can be done like so:

                    guix archive --authorize < \
                      /etc/childhurd/etc/guix/signing-key.pub

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

          We’re working towards making that happen automatically—get in
          touch with us at <guix-devel@gnu.org> to discuss it!

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

     (service hurd-vm-service-type
              (hurd-vm-configuration
               (image   (const "/out/of/store/writable/hurd.img"))
               (options '())))

Ganeti
......

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

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

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

     (use-package-modules virtualization)
     (use-service-modules base ganeti networking ssh)
     (operating-system
       ;; ...
       (host-name "node1")
       (hosts-file (plain-file "hosts" (format #f "
     127.0.0.1       localhost
     ::1             localhost

     192.168.1.200   ganeti.example.com
     192.168.1.201   node1.example.com node1
     192.168.1.202   node2.example.com node2
     ")))

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     ‘name’
          The name of this variant.

     ‘configuration’
          A configuration file for this variant.

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

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

 -- Data Type: debootstrap-configuration

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

 -- Data Type: ganeti-kvmd-configuration

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

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

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

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

 -- Data Type: ganeti-mond-configuration

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

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

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

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

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

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

 -- Data Type: ganeti-metad-configuration

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

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

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

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

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

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

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

 -- Data Type: ganeti-watcher-configuration

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

     ‘schedule’ (default: ‘'(next-second-from (next-minute (range 0 60 5)))’)
          How often to run the script.  The default is every five
          minutes.

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

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

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

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

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

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

 -- Data Type: ganeti-cleaner-configuration

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

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

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


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

12.9.30 Version Control Services
--------------------------------

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

 -- Scheme Procedure: git-daemon-service [#:config
          (git-daemon-configuration)]

     Return a service that runs ‘git daemon’, a simple TCP server to
     expose repositories over the Git protocol for anonymous access.

     The optional CONFIG argument should be a
     ‘<git-daemon-configuration>’ object, by default it allows read-only
     access to exported(1) repositories under ‘/srv/git’.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

     (service cgit-service-type)

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

   Available ‘cgit-configuration’ fields are:

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

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

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

     Defaults to ‘""’.

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

     Defaults to ‘""’.

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

     Defaults to ‘""’.

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

     Defaults to ‘"name"’.

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

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

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

     Defaults to ‘-1’.

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

     Defaults to ‘5’.

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

     Defaults to ‘5’.

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

     Defaults to ‘5’.

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

     Defaults to ‘15’.

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

     Defaults to ‘15’.

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

     Defaults to ‘5’.

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

     Defaults to ‘0’.

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

     Defaults to ‘#t’.

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

     Defaults to ‘()’.

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

     Defaults to ‘()’.

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

     Defaults to ‘""’.

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

     Defaults to ‘"git log"’.

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

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

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

     Defaults to ‘""’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘#t’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘#t’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘#t’.

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

     Defaults to ‘#f’.

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

     Defaults to ‘"/favicon.ico"’.

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

     Defaults to ‘""’.

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

     Defaults to ‘""’.

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

     Defaults to ‘""’.

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

     Defaults to ‘""’.

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

     Defaults to ‘""’.

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

     Defaults to ‘""’.

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

     Defaults to ‘#f’.

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

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

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

     Defaults to ‘""’.

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

     Defaults to ‘""’.

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

     Defaults to ‘10’.

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

     Defaults to ‘50’.

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

     Defaults to ‘80’.

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

     Defaults to ‘50’.

 -- ‘cgit-configuration’ parameter: integer max-repodesc-length
     Specifies the maximum number of repo description characters to
     display on the repository index page.

     Defaults to ‘80’.

 -- ‘cgit-configuration’ parameter: integer max-blob-size
     Specifies the maximum size of a blob to display HTML for in KBytes.

     Defaults to ‘0’.

 -- ‘cgit-configuration’ parameter: string max-stats
     Maximum statistics period.  Valid values are ‘week’,‘month’,
     ‘quarter’ and ‘year’.

     Defaults to ‘""’.

 -- ‘cgit-configuration’ parameter: mimetype-alist mimetype
     Mimetype for the specified filename extension.

     Defaults to ‘((gif "image/gif") (html "text/html") (jpg
     "image/jpeg") (jpeg "image/jpeg") (pdf "application/pdf") (png
     "image/png") (svg "image/svg+xml"))’.

 -- ‘cgit-configuration’ parameter: file-object mimetype-file
     Specifies the file to use for automatic mimetype lookup.

     Defaults to ‘""’.

 -- ‘cgit-configuration’ parameter: string module-link
     Text which will be used as the formatstring for a hyperlink when a
     submodule is printed in a directory listing.

     Defaults to ‘""’.

 -- ‘cgit-configuration’ parameter: boolean nocache?
     If set to the value ‘#t’ caching will be disabled.

     Defaults to ‘#f’.

 -- ‘cgit-configuration’ parameter: boolean noplainemail?
     If set to ‘#t’ showing full author email addresses will be
     disabled.

     Defaults to ‘#f’.

 -- ‘cgit-configuration’ parameter: boolean noheader?
     Flag which, when set to ‘#t’, will make cgit omit the standard
     header on all pages.

     Defaults to ‘#f’.

 -- ‘cgit-configuration’ parameter: project-list project-list
     A list of subdirectories inside of ‘repository-directory’, relative
     to it, that should loaded as Git repositories.  An empty list means
     that all subdirectories will be loaded.

     Defaults to ‘()’.

 -- ‘cgit-configuration’ parameter: file-object readme
     Text which will be used as default value for ‘cgit-repo-readme’.

     Defaults to ‘""’.

 -- ‘cgit-configuration’ parameter: boolean remove-suffix?
     If set to ‘#t’ and ‘repository-directory’ is enabled, if any
     repositories are found with a suffix of ‘.git’, this suffix will be
     removed for the URL and name.

     Defaults to ‘#f’.

 -- ‘cgit-configuration’ parameter: integer renamelimit
     Maximum number of files to consider when detecting renames.

     Defaults to ‘-1’.

 -- ‘cgit-configuration’ parameter: string repository-sort
     The way in which repositories in each section are sorted.

     Defaults to ‘""’.

 -- ‘cgit-configuration’ parameter: robots-list robots
     Text used as content for the ‘robots’ meta-tag.

     Defaults to ‘("noindex" "nofollow")’.

 -- ‘cgit-configuration’ parameter: string root-desc
     Text printed below the heading on the repository index page.

     Defaults to ‘"a fast webinterface for the git dscm"’.

 -- ‘cgit-configuration’ parameter: string root-readme
     The content of the file specified with this option will be included
     verbatim below the “about” link on the repository index page.

     Defaults to ‘""’.

 -- ‘cgit-configuration’ parameter: string root-title
     Text printed as heading on the repository index page.

     Defaults to ‘""’.

 -- ‘cgit-configuration’ parameter: boolean scan-hidden-path
     If set to ‘#t’ and repository-directory is enabled,
     repository-directory will recurse into directories whose name
     starts with a period.  Otherwise, repository-directory will stay
     away from such directories, considered as “hidden”.  Note that this
     does not apply to the ‘.git’ directory in non-bare repos.

     Defaults to ‘#f’.

 -- ‘cgit-configuration’ parameter: list snapshots
     Text which specifies the default set of snapshot formats that cgit
     generates links for.

     Defaults to ‘()’.

 -- ‘cgit-configuration’ parameter: repository-directory
          repository-directory
     Name of the directory to scan for repositories (represents
     ‘scan-path’).

     Defaults to ‘"/srv/git"’.

 -- ‘cgit-configuration’ parameter: string section
     The name of the current repository section - all repositories
     defined after this option will inherit the current section name.

     Defaults to ‘""’.

 -- ‘cgit-configuration’ parameter: string section-sort
     Flag which, when set to ‘1’, will sort the sections on the
     repository listing by name.

     Defaults to ‘""’.

 -- ‘cgit-configuration’ parameter: integer section-from-path
     A number which, if defined prior to repository-directory, specifies
     how many path elements from each repo path to use as a default
     section name.

     Defaults to ‘0’.

 -- ‘cgit-configuration’ parameter: boolean side-by-side-diffs?
     If set to ‘#t’ shows side-by-side diffs instead of unidiffs per
     default.

     Defaults to ‘#f’.

 -- ‘cgit-configuration’ parameter: file-object source-filter
     Specifies a command which will be invoked to format plaintext blobs
     in the tree view.

     Defaults to ‘""’.

 -- ‘cgit-configuration’ parameter: integer summary-branches
     Specifies the number of branches to display in the repository
     “summary” view.

     Defaults to ‘10’.

 -- ‘cgit-configuration’ parameter: integer summary-log
     Specifies the number of log entries to display in the repository
     “summary” view.

     Defaults to ‘10’.

 -- ‘cgit-configuration’ parameter: integer summary-tags
     Specifies the number of tags to display in the repository “summary”
     view.

     Defaults to ‘10’.

 -- ‘cgit-configuration’ parameter: string strict-export
     Filename which, if specified, needs to be present within the
     repository for cgit to allow access to that repository.

     Defaults to ‘""’.

 -- ‘cgit-configuration’ parameter: string virtual-root
     URL which, if specified, will be used as root for all cgit links.

     Defaults to ‘"/"’.

 -- ‘cgit-configuration’ parameter: repository-cgit-configuration-list
          repositories
     A list of “cgit-repo” records to use with config.

     Defaults to ‘()’.

     Available ‘repository-cgit-configuration’ fields are:

      -- ‘repository-cgit-configuration’ parameter: repo-list snapshots
          A mask of snapshot formats for this repo that cgit generates
          links for, restricted by the global ‘snapshots’ setting.

          Defaults to ‘()’.

      -- ‘repository-cgit-configuration’ parameter: repo-file-object
               source-filter
          Override the default ‘source-filter’.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-string url
          The relative URL used to access the repository.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-file-object
               about-filter
          Override the default ‘about-filter’.

          Defaults to ‘""’.

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

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-list clone-url
          A list of URLs which can be used to clone repo.

          Defaults to ‘()’.

      -- ‘repository-cgit-configuration’ parameter: repo-file-object
               commit-filter
          Override the default ‘commit-filter’.

          Defaults to ‘""’.

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

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-string
               defbranch
          The name of the default branch for this repository.  If no
          such branch exists in the repository, the first branch name
          (when sorted) is used as default instead.  By default branch
          pointed to by HEAD, or “master” if there is no suitable HEAD.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-string desc
          The value to show as repository description.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-string homepage
          The value to show as repository homepage.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-file-object
               email-filter
          Override the default ‘email-filter’.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: maybe-repo-boolean
               enable-commit-graph?
          A flag which can be used to disable the global setting
          ‘enable-commit-graph?’.

          Defaults to ‘disabled’.

      -- ‘repository-cgit-configuration’ parameter: maybe-repo-boolean
               enable-log-filecount?
          A flag which can be used to disable the global setting
          ‘enable-log-filecount?’.

          Defaults to ‘disabled’.

      -- ‘repository-cgit-configuration’ parameter: maybe-repo-boolean
               enable-log-linecount?
          A flag which can be used to disable the global setting
          ‘enable-log-linecount?’.

          Defaults to ‘disabled’.

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

          Defaults to ‘disabled’.

      -- ‘repository-cgit-configuration’ parameter: maybe-repo-boolean
               enable-subject-links?
          A flag which can be used to override the global setting
          ‘enable-subject-links?’.

          Defaults to ‘disabled’.

      -- ‘repository-cgit-configuration’ parameter: maybe-repo-boolean
               enable-html-serving?
          A flag which can be used to override the global setting
          ‘enable-html-serving?’.

          Defaults to ‘disabled’.

      -- ‘repository-cgit-configuration’ parameter: repo-boolean hide?
          Flag which, when set to ‘#t’, hides the repository from the
          repository index.

          Defaults to ‘#f’.

      -- ‘repository-cgit-configuration’ parameter: repo-boolean ignore?
          Flag which, when set to ‘#t’, ignores the repository.

          Defaults to ‘#f’.

      -- ‘repository-cgit-configuration’ parameter: repo-file-object
               logo
          URL which specifies the source of an image which will be used
          as a logo on this repo’s pages.

          Defaults to ‘""’.

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

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-file-object
               owner-filter
          Override the default ‘owner-filter’.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-string
               module-link
          Text which will be used as the formatstring for a hyperlink
          when a submodule is printed in a directory listing.  The
          arguments for the formatstring are the path and SHA1 of the
          submodule commit.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: module-link-path
               module-link-path
          Text which will be used as the formatstring for a hyperlink
          when a submodule with the specified subdirectory path is
          printed in a directory listing.

          Defaults to ‘()’.

      -- ‘repository-cgit-configuration’ parameter: repo-string
               max-stats
          Override the default maximum statistics period.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-string name
          The value to show as repository name.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-string owner
          A value used to identify the owner of the repository.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-string path
          An absolute path to the repository directory.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-string readme
          A path (relative to repo) which specifies a file to include
          verbatim as the “About” page for this repo.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-string section
          The name of the current repository section - all repositories
          defined after this option will inherit the current section
          name.

          Defaults to ‘""’.

      -- ‘repository-cgit-configuration’ parameter: repo-list
               extra-options
          Extra options will be appended to cgitrc file.

          Defaults to ‘()’.

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

     Defaults to ‘()’.

   However, it could be that you just want to get a ‘cgitrc’ up and
running.  In that case, you can pass an ‘opaque-cgit-configuration’ as a
record to ‘cgit-service-type’.  As its name indicates, an opaque
configuration does not have easy reflective capabilities.

   Available ‘opaque-cgit-configuration’ fields are:

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

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

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

     (service cgit-service-type
              (opaque-cgit-configuration
               (cgitrc "")))

Gitolite Service
................

Gitolite (https://gitolite.com/gitolite/) is a tool for hosting Git
repositories on a central server.

   Gitolite can handle multiple repositories and users, and supports
flexible configuration of the permissions for the users on the
repositories.

   The following example will configure Gitolite using the default ‘git’
user, and the provided SSH public key.

     (service gitolite-service-type
              (gitolite-configuration
                (admin-pubkey (plain-file
                                "yourname.pub"
                                "ssh-rsa AAAA... guix@example.com"))))

   Gitolite is configured through a special admin repository which you
can clone, for example, if you setup Gitolite on ‘example.com’, you
would run the following command to clone the admin repository.

     git clone git@example.com:gitolite-admin

   When the Gitolite service is activated, the provided ‘admin-pubkey’
will be inserted in to the ‘keydir’ directory in the gitolite-admin
repository.  If this results in a change in the repository, it will be
committed using the message “gitolite setup by GNU Guix”.

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

     ‘package’ (default: GITOLITE)
          Gitolite package to use.  There are optional Gitolite
          dependencies that are not included in the default package,
          such as Redis and git-annex.  These features can be made
          available by using the ‘make-gitolite’ procedure in the ‘(gnu
          packages version-control’) module to produce a variant of
          Gitolite with the desired additional dependencies.

          The following code returns a package in which the Redis and
          git-annex programs can be invoked by Gitolite’s scripts:

               (use-modules (gnu packages databases)
                            (gnu packages haskell-apps)
                            (gnu packages version-control))
               (make-gitolite (list redis git-annex))

     ‘user’ (default: GIT)
          User to use for Gitolite.  This will be user that you use when
          accessing Gitolite over SSH.

     ‘group’ (default: GIT)
          Group to use for Gitolite.

     ‘home-directory’ (default: "/VAR/LIB/GITOLITE")
          Directory in which to store the Gitolite configuration and
          repositories.

     ‘rc-file’ (default: (GITOLITE-RC-FILE))
          A “file-like” object (*note file-like objects:
          G-Expressions.), representing the configuration for Gitolite.

     ‘admin-pubkey’ (default: #F)
          A “file-like” object (*note file-like objects: G-Expressions.)
          used to setup Gitolite.  This will be inserted in to the
          ‘keydir’ directory within the gitolite-admin repository.

          To specify the SSH key as a string, use the ‘plain-file’
          function.

               (plain-file "yourname.pub" "ssh-rsa AAAA... guix@example.com")

 -- Data Type: gitolite-rc-file
     Data type representing the Gitolite RC file.

     ‘umask’ (default: ‘#o0077’)
          This controls the permissions Gitolite sets on the
          repositories and their contents.

          A value like ‘#o0027’ will give read access to the group used
          by Gitolite (by default: ‘git’).  This is necessary when using
          Gitolite with software like cgit or gitweb.

     ‘local-code’ (default: ‘"$rc{GL_ADMIN_BASE}/local"’)
          Allows you to add your own non-core programs, or even override
          the shipped ones with your own.

          Please supply the FULL path to this variable.  By default,
          directory called "local" in your gitolite clone is used,
          providing the benefits of versioning them as well as making
          changes to them without having to log on to the server.

     ‘unsafe-pattern’ (default: ‘#f’)
          An optional Perl regular expression for catching unsafe
          configurations in the configuration file.  See Gitolite’s
          documentation
          (https://gitolite.com/gitolite/git-config.html#compensating-for-unsafe_patt)
          for more information.

          When the value is not ‘#f’, it should be a string containing a
          Perl regular expression, such as ‘"[`~#\$\&()|;<>]"’, which is
          the default value used by gitolite.  It rejects any special
          character in configuration that might be interpreted by a
          shell, which is useful when sharing the administration burden
          with other people that do not otherwise have shell access on
          the server.

     ‘git-config-keys’ (default: ‘""’)
          Gitolite allows you to set git config values using the
          ‘config’ keyword.  This setting allows control over the config
          keys to accept.

     ‘roles’ (default: ‘'(("READERS" . 1) ("WRITERS" . ))’)
          Set the role names allowed to be used by users running the
          perms command.

     ‘enable’ (default: ‘'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")’)
          This setting controls the commands and features to enable
          within Gitolite.

Gitile Service
..............

Gitile (https://git.lepiller.eu/gitile) is a Git forge for viewing
public git repository contents from a web browser.

   Gitile works best in collaboration with Gitolite, and will serve the
public repositories from Gitolite by default.  The service should listen
only on a local port, and a webserver should be configured to serve
static resources.  The gitile service provides an easy way to extend the
Nginx service for that purpose (*note NGINX::).

   The following example will configure Gitile to serve repositories
from a custom location, with some default messages for the home page and
the footers.

     (service gitile-service-type
              (gitile-configuration
                (repositories "/srv/git")
                (base-git-url "https://myweb.site/git")
                (index-title "My git repositories")
                (intro '((p "This is all my public work!")))
                (footer '((p "This is the end")))
                (nginx-server-block
                  (nginx-server-configuration
                    (ssl-certificate
                      "/etc/letsencrypt/live/myweb.site/fullchain.pem")
                    (ssl-certificate-key
                      "/etc/letsencrypt/live/myweb.site/privkey.pem")
                    (listen '("443 ssl http2" "[::]:443 ssl http2"))
                    (locations
                      (list
                        ;; Allow for https anonymous fetch on /git/ urls.
                        (git-http-nginx-location-configuration
                          (git-http-configuration
                            (uri-path "/git/")
                            (git-root "/var/lib/gitolite/repositories")))))))))

   In addition to the configuration record, you should configure your
git repositories to contain some optional information.  First, your
public repositories need to contain the ‘git-daemon-export-ok’ magic
file that allows Git to export the repository.  Gitile uses the presence
of this file to detect public repositories it should make accessible.
To do so with Gitolite for instance, modify your ‘conf/gitolite.conf’ to
include this in the repositories you want to make public:

     repo foo
         R = daemon

   In addition, Gitile can read the repository configuration to display
more information on the repository.  Gitile uses the gitweb namespace
for its configuration.  As an example, you can use the following in your
‘conf/gitolite.conf’:

     repo foo
         R = daemon
         desc = A long description, optionally with <i>HTML</i>, shown on the index page
         config gitweb.name = The Foo Project
         config gitweb.synopsis = A short description, shown on the main page of the project

   Do not forget to commit and push these changes once you are
satisfied.  You may need to change your gitolite configuration to allow
the previous configuration options to be set.  One way to do that is to
add the following service definition:

     (service gitolite-service-type
               (gitolite-configuration
                 (admin-pubkey (local-file "key.pub"))
                 (rc-file
                   (gitolite-rc-file
                     (umask #o0027)
                     ;; Allow to set any configuration key
                     (git-config-keys ".*")
                     ;; Allow any text as a valid configuration value
                     (unsafe-patt "^$")))))

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

     ‘package’ (default: GITILE)
          Gitile package to use.

     ‘host’ (default: ‘"localhost"’)
          The host on which gitile is listening.

     ‘port’ (default: ‘8080’)
          The port on which gitile is listening.

     ‘database’ (default: ‘"/var/lib/gitile/gitile-db.sql"’)
          The location of the database.

     ‘repositories’ (default: ‘"/var/lib/gitolite/repositories"’)
          The location of the repositories.  Note that only public
          repositories will be shown by Gitile.  To make a repository
          public, add an empty ‘git-daemon-export-ok’ file at the root
          of that repository.

     ‘base-git-url’
          The base git url that will be used to show clone commands.

     ‘index-title’ (default: ‘"Index"’)
          The page title for the index page that lists all the available
          repositories.

     ‘intro’ (default: ‘'()’)
          The intro content, as a list of sxml expressions.  This is
          shown above the list of repositories, on the index page.

     ‘footer’ (default: ‘'()’)
          The footer content, as a list of sxml expressions.  This is
          shown on every page served by Gitile.

     ‘nginx-server-block’
          An nginx server block that will be extended and used as a
          reverse proxy by Gitile to serve its pages, and as a normal
          web server to serve its assets.

          You can use this block to add more custom URLs to your domain,
          such as a ‘/git/’ URL for anonymous clones, or serving any
          other files you would like to serve.

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

   (1) By creating the magic file ‘git-daemon-export-ok’ in the
repository directory.


File: guix.info,  Node: Game Services,  Next: PAM Mount Service,  Prev: Version Control Services,  Up: Services

12.9.31 Game Services
---------------------

The Battle for Wesnoth Service
..............................

The Battle for Wesnoth (https://wesnoth.org) is a fantasy, turn based
tactical strategy game, with several single player campaigns, and
multiplayer games (both networked and local).

 -- Variable: Scheme Variable wesnothd-service-type
     Service type for the wesnothd service.  Its value must be a
     ‘wesnothd-configuration’ object.  To run wesnothd in the default
     configuration, instantiate it as:

          (service wesnothd-service-type)

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

     ‘package’ (default: ‘wesnoth-server’)
          The wesnoth server package to use.

     ‘port’ (default: ‘15000’)
          The port to bind the server to.


File: guix.info,  Node: PAM Mount Service,  Next: Guix Services,  Prev: Game Services,  Up: Services

12.9.32 PAM Mount Service
-------------------------

The ‘(gnu services pam-mount)’ module provides a service allowing users
to mount volumes when they log in.  It should be able to mount any
volume format supported by the system.

 -- Variable: Scheme Variable pam-mount-service-type
     Service type for PAM Mount support.

 -- Data Type: pam-mount-configuration
     Data type representing the configuration of PAM Mount.

     It takes the following parameters:

     ‘rules’
          The configuration rules that will be used to generate
          ‘/etc/security/pam_mount.conf.xml’.

          The configuration rules are SXML elements (*note
          (guile)SXML::), and the default ones don’t mount anything for
          anyone at login:

               `((debug (@ (enable "0")))
                 (mntoptions (@ (allow ,(string-join
                                         '("nosuid" "nodev" "loop"
                                           "encryption" "fsck" "nonempty"
                                           "allow_root" "allow_other")
                                         ","))))
                 (mntoptions (@ (require "nosuid,nodev")))
                 (logout (@ (wait "0")
                            (hup "0")
                            (term "no")
                            (kill "no")))
                 (mkmountpoint (@ (enable "1")
                                  (remove "true"))))

          Some ‘volume’ elements must be added to automatically mount
          volumes at login.  Here’s an example allowing the user ‘alice’
          to mount her encrypted ‘HOME’ directory and allowing the user
          ‘bob’ to mount the partition where he stores his data:

               (define pam-mount-rules
               `((debug (@ (enable "0")))
                           (volume (@ (user "alice")
                                      (fstype "crypt")
                                      (path "/dev/sda2")
                                      (mountpoint "/home/alice")))
                           (volume (@ (user "bob")
                                      (fstype "auto")
                                      (path "/dev/sdb3")
                                      (mountpoint "/home/bob/data")
                                      (options "defaults,autodefrag,compress")))
                           (mntoptions (@ (allow ,(string-join
                                                   '("nosuid" "nodev" "loop"
                                                     "encryption" "fsck" "nonempty"
                                                     "allow_root" "allow_other")
                                                   ","))))
                           (mntoptions (@ (require "nosuid,nodev")))
                           (logout (@ (wait "0")
                                      (hup "0")
                                      (term "no")
                                      (kill "no")))
                           (mkmountpoint (@ (enable "1")
                                            (remove "true")))))

               (service pam-mount-service-type
                        (pam-mount-configuration
                          (rules pam-mount-rules)))

          The complete list of possible options can be found in the man
          page for pam_mount.conf
          (http://pam-mount.sourceforge.net/pam_mount.conf.5.html).


File: guix.info,  Node: Guix Services,  Next: Linux Services,  Prev: PAM Mount Service,  Up: Services

12.9.33 Guix Services
---------------------

Guix Build Coordinator
......................

The Guix Build Coordinator
(https://git.cbaines.net/guix/build-coordinator/) aids in distributing
derivation builds among machines running an “agent”.  The build daemon
is still used to build the derivations, but the Guix Build Coordinator
manages allocating builds and working with the results.

   The Guix Build Coordinator consists of one “coordinator”, and one or
more connected “agent” processes.  The coordinator process handles
clients submitting builds, and allocating builds to agents.  The agent
processes talk to a build daemon to actually perform the builds, then
send the results back to the coordinator.

   There is a script to run the coordinator component of the Guix Build
Coordinator, but the Guix service uses a custom Guile script instead, to
provide better integration with G-expressions used in the configuration.

 -- Variable: Scheme Variable guix-build-coordinator-service-type
     Service type for the Guix Build Coordinator.  Its value must be a
     ‘guix-build-coordinator-configuration’ object.

 -- Data Type: guix-build-coordinator-configuration
     Data type representing the configuration of the Guix Build
     Coordinator.

     ‘package’ (default: ‘guix-build-coordinator’)
          The Guix Build Coordinator package to use.

     ‘user’ (default: ‘"guix-build-coordinator"’)
          The system user to run the service as.

     ‘group’ (default: ‘"guix-build-coordinator"’)
          The system group to run the service as.

     ‘database-uri-string’ (default: ‘"sqlite:///var/lib/guix-build-coordinator/guix_build_coordinator.db"’)
          The URI to use for the database.

     ‘agent-communication-uri’ (default: ‘"http://0.0.0.0:8745"’)
          The URI describing how to listen to requests from agent
          processes.

     ‘client-communication-uri’ (default: ‘"http://127.0.0.1:8746"’)
          The URI describing how to listen to requests from clients.
          The client API allows submitting builds and currently isn’t
          authenticated, so take care when configuring this value.

     ‘allocation-strategy’ (default: ‘#~basic-build-allocation-strategy’)
          A G-expression for the allocation strategy to be used.  This
          is a procedure that takes the datastore as an argument and
          populates the allocation plan in the database.

     ‘hooks’ (default: ’())
          An association list of hooks.  These provide a way to execute
          arbitrary code upon certain events, like a build result being
          processed.

     ‘parallel-hooks’ (default: ’())
          Hooks can be configured to run in parallel.  This parameter is
          an association list of hooks to do in parallel, where the key
          is the symbol for the hook and the value is the number of
          threads to run.

     ‘guile’ (default: ‘guile-3.0-latest’)
          The Guile package with which to run the Guix Build
          Coordinator.

 -- Variable: Scheme Variable guix-build-coordinator-agent-service-type
     Service type for a Guix Build Coordinator agent.  Its value must be
     a ‘guix-build-coordinator-agent-configuration’ object.

 -- Data Type: guix-build-coordinator-agent-configuration
     Data type representing the configuration a Guix Build Coordinator
     agent.

     ‘package’ (default: ‘guix-build-coordinator/agent-only’)
          The Guix Build Coordinator package to use.

     ‘user’ (default: ‘"guix-build-coordinator-agent"’)
          The system user to run the service as.

     ‘coordinator’ (default: ‘"http://localhost:8745"’)
          The URI to use when connecting to the coordinator.

     ‘authentication’
          Record describing how this agent should authenticate with the
          coordinator.  Possible record types are described below.

     ‘systems’ (default: ‘#f’)
          The systems for which this agent should fetch builds.  The
          agent process will use the current system it’s running on as
          the default.

     ‘max-parallel-builds’ (default: ‘1’)
          The number of builds to perform in parallel.

     ‘max-allocated-builds’ (default: ‘#f’)
          The maximum number of builds this agent can be allocated.

     ‘max-1min-load-average’ (default: ‘#f’)
          Load average value to look at when considering starting new
          builds, if the 1 minute load average exceeds this value, the
          agent will wait before starting new builds.

          This will be unspecified if the value is ‘#f’, and the agent
          will use the number of cores reported by the system as the max
          1 minute load average.

     ‘derivation-substitute-urls’ (default: ‘#f’)
          URLs from which to attempt to fetch substitutes for
          derivations, if the derivations aren’t already available.

     ‘non-derivation-substitute-urls’ (default: ‘#f’)
          URLs from which to attempt to fetch substitutes for build
          inputs, if the input store items aren’t already available.

 -- Data Type: guix-build-coordinator-agent-password-auth
     Data type representing an agent authenticating with a coordinator
     via a UUID and password.

     ‘uuid’
          The UUID of the agent.  This should be generated by the
          coordinator process, stored in the coordinator database, and
          used by the intended agent.

     ‘password’
          The password to use when connecting to the coordinator.

 -- Data Type: guix-build-coordinator-agent-password-file-auth
     Data type representing an agent authenticating with a coordinator
     via a UUID and password read from a file.

     ‘uuid’
          The UUID of the agent.  This should be generated by the
          coordinator process, stored in the coordinator database, and
          used by the intended agent.

     ‘password-file’
          A file containing the password to use when connecting to the
          coordinator.

 -- Data Type: guix-build-coordinator-agent-dynamic-auth
     Data type representing an agent authenticating with a coordinator
     via a dynamic auth token and agent name.

     ‘agent-name’
          Name of an agent, this is used to match up to an existing
          entry in the database if there is one.  When no existing entry
          is found, a new entry is automatically added.

     ‘token’
          Dynamic auth token, this is created and stored in the
          coordinator database, and is used by the agent to
          authenticate.

 -- Data Type: guix-build-coordinator-agent-dynamic-auth-with-file
     Data type representing an agent authenticating with a coordinator
     via a dynamic auth token read from a file and agent name.

     ‘agent-name’
          Name of an agent, this is used to match up to an existing
          entry in the database if there is one.  When no existing entry
          is found, a new entry is automatically added.

     ‘token-file’
          File containing the dynamic auth token, this is created and
          stored in the coordinator database, and is used by the agent
          to authenticate.

   The Guix Build Coordinator package contains a script to query an
instance of the Guix Data Service for derivations to build, and then
submit builds for those derivations to the coordinator.  The service
type below assists in running this script.  This is an additional tool
that may be useful when building derivations contained within an
instance of the Guix Data Service.

 -- Variable: Scheme Variable
          guix-build-coordinator-queue-builds-service-type
     Service type for the
     guix-build-coordinator-queue-builds-from-guix-data-service script.
     Its value must be a
     ‘guix-build-coordinator-queue-builds-configuration’ object.

 -- Data Type: guix-build-coordinator-queue-builds-configuration
     Data type representing the options to the queue builds from guix
     data service script.

     ‘package’ (default: ‘guix-build-coordinator’)
          The Guix Build Coordinator package to use.

     ‘user’ (default: ‘"guix-build-coordinator-queue-builds"’)
          The system user to run the service as.

     ‘coordinator’ (default: ‘"http://localhost:8746"’)
          The URI to use when connecting to the coordinator.

     ‘systems’ (default: ‘#f’)
          The systems for which to fetch derivations to build.

     ‘systems-and-targets’ (default: ‘#f’)
          An association list of system and target pairs for which to
          fetch derivations to build.

     ‘guix-data-service’ (default: ‘"https://data.guix.gnu.org"’)
          The Guix Data Service instance from which to query to find out
          about derivations to build.

     ‘guix-data-service-build-server-id’ (default: ‘#f’)
          The Guix Data Service build server ID corresponding to the
          builds being submitted.  Providing this speeds up the
          submitting of builds as derivations that have already been
          submitted can be skipped before asking the coordinator to
          build them.

     ‘processed-commits-file’ (default: ‘"/var/cache/guix-build-coordinator-queue-builds/processed-commits"’)
          A file to record which commits have been processed, to avoid
          needlessly processing them again if the service is restarted.

Guix Data Service
.................

The Guix Data Service (http://data.guix.gnu.org) processes, stores and
provides data about GNU Guix.  This includes information about packages,
derivations and lint warnings.

   The data is stored in a PostgreSQL database, and available through a
web interface.

 -- Variable: Scheme Variable guix-data-service-type
     Service type for the Guix Data Service.  Its value must be a
     ‘guix-data-service-configuration’ object.  The service optionally
     extends the getmail service, as the guix-commits mailing list is
     used to find out about changes in the Guix git repository.

 -- Data Type: guix-data-service-configuration
     Data type representing the configuration of the Guix Data Service.

     ‘package’ (default: ‘guix-data-service’)
          The Guix Data Service package to use.

     ‘user’ (default: ‘"guix-data-service"’)
          The system user to run the service as.

     ‘group’ (default: ‘"guix-data-service"’)
          The system group to run the service as.

     ‘port’ (default: ‘8765’)
          The port to bind the web service to.

     ‘host’ (default: ‘"127.0.0.1"’)
          The host to bind the web service to.

     ‘getmail-idle-mailboxes’ (default: ‘#f’)
          If set, this is the list of mailboxes that the getmail service
          will be configured to listen to.

     ‘commits-getmail-retriever-configuration’ (default: ‘#f’)
          If set, this is the ‘getmail-retriever-configuration’ object
          with which to configure getmail to fetch mail from the
          guix-commits mailing list.

     ‘extra-options’ (default: ’())
          Extra command line options for ‘guix-data-service’.

     ‘extra-process-jobs-options’ (default: ’())
          Extra command line options for
          ‘guix-data-service-process-jobs’.

Nar Herder
..........

The Nar Herder (https://git.cbaines.net/guix/nar-herder/about/) is a
utility for managing a collection of nars.

 -- Variable: Scheme Variable nar-herder-type
     Service type for the Guix Data Service.  Its value must be a
     ‘nar-herder-configuration’ object.  The service optionally extends
     the getmail service, as the guix-commits mailing list is used to
     find out about changes in the Guix git repository.

 -- Data Type: nar-herder-configuration
     Data type representing the configuration of the Guix Data Service.

     ‘package’ (default: ‘nar-herder’)
          The Nar Herder package to use.

     ‘user’ (default: ‘"nar-herder"’)
          The system user to run the service as.

     ‘group’ (default: ‘"nar-herder"’)
          The system group to run the service as.

     ‘port’ (default: ‘8734’)
          The port to bind the server to.

     ‘host’ (default: ‘"127.0.0.1"’)
          The host to bind the server to.

     ‘mirror’ (default: ‘#f’)
          Optional URL of the other Nar Herder instance which should be
          mirrored.  This means that this Nar Herder instance will
          download it’s database, and keep it up to date.

     ‘database’ (default: ‘"/var/lib/nar-herder/nar_herder.db"’)
          Location for the database.  If this Nar Herder instance is
          mirroring another, the database will be downloaded if it
          doesn’t exist.  If this Nar Herder instance isn’t mirroring
          another, an empty database will be created.

     ‘database-dump’ (default: ‘"/var/lib/nar-herder/nar_herder_dump.db"’)
          Location of the database dump.  This is created and regularly
          updated by taking a copy of the database.  This is the version
          of the database that is available to download.

     ‘storage’ (default: ‘#f’)
          Optional location in which to store nars.

     ‘storage-limit’ (default: ‘"none"’)
          Limit in bytes for the nars stored in the storage location.
          This can also be set to “none” so that there is no limit.

          When the storage location exceeds this size, nars are removed
          according to the nar removal criteria.

     ‘storage-nar-removal-criteria’ (default: ‘'()’)
          Criteria used to remove nars from the storage location.  These
          are used in conjunction with the storage limit.

          When the storage location exceeds the storage limit size, nars
          will be checked against the nar removal criteria and if any of
          the criteria match, they will be removed.  This will continue
          until the storage location is below the storage limit size.

          Each criteria is specified by a string, then an equals sign,
          then another string.  Currently, only one criteria is
          supported, checking if a nar is stored on another Nar Herder
          instance.

     ‘ttl’ (default: ‘#f’)
          Produce ‘Cache-Control’ HTTP headers that advertise a
          time-to-live (TTL) of TTL.  TTL must denote a duration: ‘5d’
          means 5 days, ‘1m’ means 1 month, and so on.

          This allows the user’s Guix to keep substitute information in
          cache for TTL.

     ‘negative-ttl’ (default: ‘#f’)
          Similarly produce ‘Cache-Control’ HTTP headers to advertise
          the time-to-live (TTL) of _negative_ lookups—missing store
          items, for which the HTTP 404 code is returned.  By default,
          no negative TTL is advertised.

     ‘log-level’ (default: ‘'DEBUG’)
          Log level to use, specify a log level like ‘'INFO’ to stop
          logging individual requests.


File: guix.info,  Node: Linux Services,  Next: Hurd Services,  Prev: Guix Services,  Up: Services

12.9.34 Linux Services
----------------------

Early OOM Service
.................

Early OOM (https://github.com/rfjakob/earlyoom), also known as Earlyoom,
is a minimalist out of memory (OOM) daemon that runs in user space and
provides a more responsive and configurable alternative to the in-kernel
OOM killer.  It is useful to prevent the system from becoming
unresponsive when it runs out of memory.

 -- Scheme Variable: earlyoom-service-type
     The service type for running ‘earlyoom’, the Early OOM daemon.  Its
     value must be a ‘earlyoom-configuration’ object, described below.
     The service can be instantiated in its default configuration with:

          (service earlyoom-service-type)

 -- Data Type: earlyoom-configuration
     This is the configuration record for the ‘earlyoom-service-type’.

     ‘earlyoom’ (default: EARLYOOM)
          The Earlyoom package to use.

     ‘minimum-available-memory’ (default: ‘10’)
          The threshold for the minimum _available_ memory, in
          percentages.

     ‘minimum-free-swap’ (default: ‘10’)
          The threshold for the minimum free swap memory, in
          percentages.

     ‘prefer-regexp’ (default: ‘#f’)
          A regular expression (as a string) to match the names of the
          processes that should be preferably killed.

     ‘avoid-regexp’ (default: ‘#f’)
          A regular expression (as a string) to match the names of the
          processes that should _not_ be killed.

     ‘memory-report-interval’ (default: ‘0’)
          The interval in seconds at which a memory report is printed.
          It is disabled by default.

     ‘ignore-positive-oom-score-adj?’ (default: ‘#f’)
          A boolean indicating whether the positive adjustments set in
          ‘/proc/*/oom_score_adj’ should be ignored.

     ‘show-debug-messages?’ (default: ‘#f’)
          A boolean indicating whether debug messages should be printed.
          The logs are saved at ‘/var/log/earlyoom.log’.

     ‘send-notification-command’ (default: ‘#f’)
          This can be used to provide a custom command used for sending
          notifications.

Kernel Module Loader Service
............................

The kernel module loader service allows one to load loadable kernel
modules at boot.  This is especially useful for modules that don’t
autoload and need to be manually loaded, as is the case with ‘ddcci’.

 -- Scheme Variable: kernel-module-loader-service-type
     The service type for loading loadable kernel modules at boot with
     ‘modprobe’.  Its value must be a list of strings representing
     module names.  For example loading the drivers provided by
     ‘ddcci-driver-linux’, in debugging mode by passing some module
     parameters, can be done as follow:

          (use-modules (gnu) (gnu services))
          (use-package-modules linux)
          (use-service-modules linux)

          (define ddcci-config
            (plain-file "ddcci.conf"
                        "options ddcci dyndbg delay=120"))

          (operating-system
            ...
            (services (cons* (service kernel-module-loader-service-type
                                      '("ddcci" "ddcci_backlight"))
                             (simple-service 'ddcci-config etc-service-type
                                             (list `("modprobe.d/ddcci.conf"
                                                     ,ddcci-config)))
                             %base-services))
            (kernel-loadable-modules (list ddcci-driver-linux)))

Rasdaemon Service
.................

The Rasdaemon service provides a daemon which monitors platform RAS
(Reliability, Availability, and Serviceability) reports from Linux
kernel trace events, logging them to syslogd.

   Reliability, Availability and Serviceability is a concept used on
servers meant to measure their robustness.

   *Relability* is the probability that a system will produce correct
outputs:

   • Generally measured as Mean Time Between Failures (MTBF), and
   • Enhanced by features that help to avoid, detect and repair hardware
     faults

   *Availability* is the probability that a system is operational at a
given time:

   • Generally measured as a percentage of downtime per a period of
     time, and
   • Often uses mechanisms to detect and correct hardware faults in
     runtime.

   *Serviceability* is the simplicity and speed with which a system can
be repaired or maintained:

   • Generally measured on Mean Time Between Repair (MTBR).

   Among the monitoring measures, the most usual ones include:

   • CPU – detect errors at instruction execution and at L1/L2/L3
     caches;
   • Memory – add error correction logic (ECC) to detect and correct
     errors;
   • I/O – add CRC checksums for transferred data;
   • Storage – RAID, journal file systems, checksums, Self-Monitoring,
     Analysis and Reporting Technology (SMART).

   By monitoring the number of occurrences of error detections, it is
possible to identify if the probability of hardware errors is
increasing, and, on such case, do a preventive maintenance to replace a
degraded component while those errors are correctable.

   For detailed information about the types of error events gathered and
how to make sense of them, see the kernel administrator’s guide at
<https://www.kernel.org/doc/html/latest/admin-guide/ras.html>.

 -- Scheme Variable: rasdaemon-service-type
     Service type for the ‘rasdaemon’ service.  It accepts a
     ‘rasdaemon-configuration’ object.  Instantiating like

          (service rasdaemon-service-type)

     will load with a default configuration, which monitors all events
     and logs to syslogd.

 -- Data Type: rasdaemon-configuration
     The data type representing the configuration of ‘rasdaemon’.

     ‘record?’ (default: ‘#f’)

          A boolean indicating whether to record the events in an SQLite
          database.  This provides a more structured access to the
          information contained in the log file.  The database location
          is hard-coded to ‘/var/lib/rasdaemon/ras-mc_event.db’.

Zram Device Service
...................

The Zram device service provides a compressed swap device in system
memory.  The Linux Kernel documentation has more information about zram
(https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html)
devices.

 -- Scheme Variable: zram-device-service-type
     This service creates the zram block device, formats it as swap and
     enables it as a swap device.  The service’s value is a
     ‘zram-device-configuration’ record.

      -- Data Type: zram-device-configuration
          This is the data type representing the configuration for the
          zram-device service.

          ‘size’ (default ‘"1G"’)
               This is the amount of space you wish to provide for the
               zram device.  It accepts a string and can be a number of
               bytes or use a suffix, eg.: ‘"512M"’ or ‘1024000’.
          ‘compression-algorithm’ (default ‘'lzo’)
               This is the compression algorithm you wish to use.  It is
               difficult to list all the possible compression options,
               but common ones supported by Guix’s Linux Libre Kernel
               include ‘'lzo’, ‘'lz4’ and ‘'zstd’.
          ‘memory-limit’ (default ‘0’)
               This is the maximum amount of memory which the zram
               device can use.  Setting it to ’0’ disables the limit.
               While it is generally expected that compression will be
               2:1, it is possible that uncompressable data can be
               written to swap and this is a method to limit how much
               memory can be used.  It accepts a string and can be a
               number of bytes or use a suffix, eg.: ‘"2G"’.
          ‘priority’ (default ‘#f’)
               This is the priority of the swap device created from the
               zram device.  *Note Swap Space:: for a description of
               swap priorities.  You might want to set a specific
               priority for the zram device, otherwise it could end up
               not being used much for the reasons described there.


File: guix.info,  Node: Hurd Services,  Next: Miscellaneous Services,  Prev: Linux Services,  Up: Services

12.9.35 Hurd Services
---------------------

 -- Scheme Variable: hurd-console-service-type
     This service starts the fancy ‘VGA’ console client on the Hurd.

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

 -- Data Type: hurd-console-configuration
     This is the data type representing the configuration for the
     hurd-console-service.

     ‘hurd’ (default: HURD)
          The Hurd package to use.

 -- Scheme Variable: hurd-getty-service-type
     This service starts a tty using the Hurd ‘getty’ program.

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

 -- Data Type: hurd-getty-configuration
     This is the data type representing the configuration for the
     hurd-getty-service.

     ‘hurd’ (default: HURD)
          The Hurd package to use.

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

     ‘baud-rate’ (default: ‘38400’)
          An integer specifying the baud rate of the tty.


File: guix.info,  Node: Miscellaneous Services,  Prev: Hurd Services,  Up: Services

12.9.36 Miscellaneous Services
------------------------------

Fingerprint Service
...................

The ‘(gnu services authentication)’ module provides a DBus service to
read and identify fingerprints via a fingerprint sensor.

 -- Scheme Variable: fprintd-service-type
     The service type for ‘fprintd’, which provides the fingerprint
     reading capability.

          (service fprintd-service-type)

System Control Service
......................

The ‘(gnu services sysctl)’ provides a service to configure kernel
parameters at boot.

 -- Scheme Variable: sysctl-service-type
     The service type for ‘sysctl’, which modifies kernel parameters
     under ‘/proc/sys/’.  To enable IPv4 forwarding, it can be
     instantiated as:

          (service sysctl-service-type
                   (sysctl-configuration
                     (settings '(("net.ipv4.ip_forward" . "1")))))

     Since ‘sysctl-service-type’ is used in the default lists of
     services, ‘%base-services’ and ‘%desktop-services’, you can use
     ‘modify-services’ to change its configuration and add the kernel
     parameters that you want (*note ‘modify-services’: Service
     Reference.).

          (modify-services %base-services
            (sysctl-service-type config =>
                                 (sysctl-configuration
                                   (settings (append '(("net.ipv4.ip_forward" . "1"))
                                                     %default-sysctl-settings)))))

 -- Data Type: sysctl-configuration
     The data type representing the configuration of ‘sysctl’.

     ‘sysctl’ (default: ‘(file-append procps "/sbin/sysctl"’)
          The ‘sysctl’ executable to use.

     ‘settings’ (default: ‘%default-sysctl-settings’)
          An association list specifies kernel parameters and their
          values.

 -- Scheme Variable: %default-sysctl-settings
     An association list specifying the default ‘sysctl’ parameters on
     Guix System.

PC/SC Smart Card Daemon Service
...............................

The ‘(gnu services security-token)’ module provides the following
service to run ‘pcscd’, the PC/SC Smart Card Daemon.  ‘pcscd’ is the
daemon program for pcsc-lite and the MuscleCard framework.  It is a
resource manager that coordinates communications with smart card
readers, smart cards and cryptographic tokens that are connected to the
system.

 -- Scheme Variable: pcscd-service-type
     Service type for the ‘pcscd’ service.  Its value must be a
     ‘pcscd-configuration’ object.  To run pcscd in the default
     configuration, instantiate it as:

          (service pcscd-service-type)

 -- Data Type: pcscd-configuration
     The data type representing the configuration of ‘pcscd’.

     ‘pcsc-lite’ (default: ‘pcsc-lite’)
          The pcsc-lite package that provides pcscd.
     ‘usb-drivers’ (default: ‘(list ccid)’)
          List of packages that provide USB drivers to pcscd.  Drivers
          are expected to be under ‘pcsc/drivers’ in the store directory
          of the package.

Lirc Service
............

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

 -- Scheme Procedure: lirc-service [#:lirc lirc] [#:device #f] [#:driver
          #f] [#:config-file #f] [#:extra-options '()]
     Return a service that runs LIRC (http://www.lirc.org), a daemon
     that decodes infrared signals from remote controls.

     Optionally, DEVICE, DRIVER and CONFIG-FILE (configuration file
     name) may be specified.  See ‘lircd’ manual for details.

     Finally, EXTRA-OPTIONS is a list of additional command-line options
     passed to ‘lircd’.

Spice Service
.............

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

 -- Scheme Procedure: spice-vdagent-service [#:spice-vdagent]
     Returns a service that runs VDAGENT (https://www.spice-space.org),
     a daemon that enables sharing the clipboard with a vm and setting
     the guest display resolution when the graphical console window
     resizes.

inputattach Service
...................

The inputattach (https://linuxwacom.github.io/) service allows you to
use input devices such as Wacom tablets, touchscreens, or joysticks with
the Xorg display server.

 -- Scheme Variable: inputattach-service-type
     Type of a service that runs ‘inputattach’ on a device and
     dispatches events from it.

 -- Data Type: inputattach-configuration
     ‘device-type’ (default: ‘"wacom"’)
          The type of device to connect to.  Run ‘inputattach --help’,
          from the ‘inputattach’ package, to see the list of supported
          device types.

     ‘device’ (default: ‘"/dev/ttyS0"’)
          The device file to connect to the device.

     ‘baud-rate’ (default: ‘#f’)
          Baud rate to use for the serial connection.  Should be a
          number or ‘#f’.

     ‘log-file’ (default: ‘#f’)
          If true, this must be the name of a file to log messages to.

Dictionary Service
..................

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

 -- Scheme Variable: dicod-service-type
     This is the type of the service that runs the ‘dicod’ daemon, an
     implementation of DICT server (*note (dico)Dicod::).

 -- Scheme Procedure: dicod-service [#:config (dicod-configuration)]
     Return a service that runs the ‘dicod’ daemon, an implementation of
     DICT server (*note (dico)Dicod::).

     The optional CONFIG argument specifies the configuration for
     ‘dicod’, which should be a ‘<dicod-configuration>’ object, by
     default it serves the GNU Collaborative International Dictionary of
     English.

     You can add ‘open localhost’ to your ‘~/.dico’ file to make
     ‘localhost’ the default server for ‘dico’ client (*note
     (dico)Initialization File::).

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

     ‘dico’ (default: DICO)
          Package object of the GNU Dico dictionary server.

     ‘interfaces’ (default: ’("LOCALHOST"))
          This is the list of IP addresses and ports and possibly socket
          file names to listen to (*note ‘listen’ directive:
          (dico)Server Settings.).

     ‘handlers’ (default: ’())
          List of ‘<dicod-handler>’ objects denoting handlers (module
          instances).

     ‘databases’ (default: (LIST %DICOD-DATABASE:GCIDE))
          List of ‘<dicod-database>’ objects denoting dictionaries to be
          served.

 -- Data Type: dicod-handler
     Data type representing a dictionary handler (module instance).

     ‘name’
          Name of the handler (module instance).

     ‘module’ (default: #F)
          Name of the dicod module of the handler (instance).  If it is
          ‘#f’, the module has the same name as the handler.  (*note
          (dico)Modules::).

     ‘options’
          List of strings or gexps representing the arguments for the
          module handler

 -- Data Type: dicod-database
     Data type representing a dictionary database.

     ‘name’
          Name of the database, will be used in DICT commands.

     ‘handler’
          Name of the dicod handler (module instance) used by this
          database (*note (dico)Handlers::).

     ‘complex?’ (default: #F)
          Whether the database configuration complex.  The complex
          configuration will need a corresponding ‘<dicod-handler>’
          object, otherwise not.

     ‘options’
          List of strings or gexps representing the arguments for the
          database (*note (dico)Databases::).

 -- Scheme Variable: %dicod-database:gcide
     A ‘<dicod-database>’ object serving the GNU Collaborative
     International Dictionary of English using the ‘gcide’ package.

   The following is an example ‘dicod-service’ configuration.

     (dicod-service #:config
       (dicod-configuration
        (handlers (list (dicod-handler
                         (name "wordnet")
                         (module "dictorg")
                         (options
                          (list #~(string-append "dbdir=" #$wordnet))))))
        (databases (list (dicod-database
                          (name "wordnet")
                          (complex? #t)
                          (handler "wordnet")
                          (options '("database=wn")))
                         %dicod-database:gcide))))

Docker Service
..............

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

 -- Scheme Variable: docker-service-type

     This is the type of the service that runs Docker
     (https://www.docker.com), a daemon that can execute application
     bundles (sometimes referred to as “containers”) in isolated
     environments.

 -- Data Type: docker-configuration
     This is the data type representing the configuration of Docker and
     Containerd.

     ‘docker’ (default: ‘docker’)
          The Docker daemon package to use.

     ‘docker-cli’ (default: ‘docker-cli’)
          The Docker client package to use.

     ‘containerd’ (default: CONTAINERD)
          The Containerd package to use.

     ‘proxy’ (default DOCKER-LIBNETWORK-CMD-PROXY)
          The Docker user-land networking proxy package to use.

     ‘enable-proxy?’ (default ‘#t’)
          Enable or disable the use of the Docker user-land networking
          proxy.

     ‘debug?’ (default ‘#f’)
          Enable or disable debug output.

     ‘enable-iptables?’ (default ‘#t’)
          Enable or disable the addition of iptables rules.

     ‘environment-variables’ (default: ‘()’)
          List of environment variables to set for ‘dockerd’.

          This must be a list of strings where each string has the form
          ‘KEY=VALUE’ as in this example:

               (list "LANGUAGE=eo:ca:eu"
                     "TMPDIR=/tmp/dockerd")

 -- Scheme Variable: singularity-service-type
     This is the type of the service that allows you to run Singularity
     (https://www.sylabs.io/singularity/), a Docker-style tool to create
     and run application bundles (aka.  “containers”).  The value for
     this service is the Singularity package to use.

     The service does not install a daemon; instead, it installs helper
     programs as setuid-root (*note Setuid Programs::) such that
     unprivileged users can invoke ‘singularity run’ and similar
     commands.

Auditd Service
..............

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

 -- Scheme Variable: auditd-service-type

     This is the type of the service that runs auditd
     (https://people.redhat.com/sgrubb/audit/), a daemon that tracks
     security-relevant information on your system.

     Examples of things that can be tracked:

       1. File accesses
       2. System calls
       3. Invoked commands
       4. Failed login attempts
       5. Firewall filtering
       6. Network access

     ‘auditctl’ from the ‘audit’ package can be used in order to add or
     remove events to be tracked (until the next reboot).  In order to
     permanently track events, put the command line arguments of
     auditctl into a file called ‘audit.rules’ in the configuration
     directory (see below).  ‘aureport’ from the ‘audit’ package can be
     used in order to view a report of all recorded events.  The audit
     daemon by default logs into the file ‘/var/log/audit.log’.

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

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

     ‘configuration-directory’ (default: ‘%default-auditd-configuration-directory’)
          The directory containing the configuration file for the audit
          package, which must be named ‘auditd.conf’, and optionally
          some audit rules to instantiate on startup.

R-Shiny service
...............

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

 -- Scheme Variable: rshiny-service-type

     This is a type of service which is used to run a webapp created
     with ‘r-shiny’.  This service sets the ‘R_LIBS_USER’ environment
     variable and runs the provided script to call ‘runApp’.

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

          ‘package’ (default: ‘r-shiny’)
               The package to use.

          ‘binary’ (default ‘"rshiny"’)
               The name of the binary or shell script located at
               ‘package/bin/’ to run when the service is run.

               The common way to create this file is as follows:

                    ...
                    (let* ((out       (assoc-ref %outputs "out"))
                           (targetdir (string-append out "/share/" ,name))
                           (app       (string-append out "/bin/" ,name))
                           (Rbin      (search-input-file %build-inputs "/bin/Rscript")))
                      ;; ...
                      (mkdir-p (string-append out "/bin"))
                      (call-with-output-file app
                        (lambda (port)
                          (format port
                    "#!~a
                    library(shiny)
                    setwd(\"~a\")
                    runApp(launch.browser=0, port=4202)~%\n"
                          Rbin targetdir))))

Nix service
...........

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

 -- Scheme Variable: nix-service-type

     This is the type of the service that runs build daemon of the Nix
     (https://nixos.org/nix/) package manager.  Here is an example
     showing how to use it:

          (use-modules (gnu))
          (use-service-modules nix)
          (use-package-modules package-management)

          (operating-system
            ;; ...
            (packages (append (list nix)
                              %base-packages))

            (services (append (list (service nix-service-type))
                              %base-services)))

     After ‘guix system reconfigure’ configure Nix for your user:

        • Add a Nix channel and update it.  See Nix Package Manager
          Guide (https://nixos.org/nix/manual/).

        • Create a symlink to your profile and activate Nix profile:

          $ ln -s "/nix/var/nix/profiles/per-user/$USER/profile" ~/.nix-profile
          $ source /run/current-system/profile/etc/profile.d/nix.sh

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

     ‘nix’ (default: ‘nix’)
          The Nix package to use.

     ‘sandbox’ (default: ‘#t’)
          Specifies whether builds are sandboxed by default.

     ‘build-sandbox-items’ (default: ‘'()’)
          This is a list of strings or objects appended to the
          ‘build-sandbox-items’ field of the configuration file.

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

     ‘extra-options’ (default: ‘'()’)
          Extra command line options for ‘nix-service-type’.

Fail2Ban service
................

‘fail2ban’ (http://www.fail2ban.org/) scans log files (e.g.
‘/var/log/apache/error_log’) and bans IP addresses that show malicious
signs – repeated password failures, attempts to make use of exploits,
etc.

   ‘fail2ban-service-type’ service type is provided by the ‘(gnu
services security)’ module.

   This service type runs the ‘fail2ban’ daemon.  It can be configured
in various ways, which are:

Basic configuration
     The basic parameters of the Fail2Ban service can be configured via
     its ‘fail2ban’ configuration, which is documented below.

User-specified jail extensions
     The ‘fail2ban-jail-service’ function can be used to add new
     Fail2Ban jails.

Shepherd extension mechanism
     Service developers can extend the ‘fail2ban-service-type’ service
     type itself via the usual service extension mechanism.

 -- Scheme Variable: fail2ban-service-type

     This is the type of the service that runs ‘fail2ban’ daemon.  Below
     is an example of a basic, explicit configuration:

          (append
           (list
            (service fail2ban-service-type
                     (fail2ban-configuration
                      (extra-jails
                       (list
                        (fail2ban-jail-configuration
                         (name "sshd")
                         (enabled? #t))))))
            ;; There is no implicit dependency on an actual SSH
            ;; service, so you need to provide one.
            (service openssh-service-type))
           %base-services)

 -- Scheme Procedure: fail2ban-jail-service SVC-TYPE JAIL
     Extend SVC-TYPE, a ‘<service-type>’ object with JAIL, a
     ‘fail2ban-jail-configuration’ object.

     For example:

          (append
           (list
            (service
             ;; The 'fail2ban-jail-service' procedure can extend any service type
             ;; with a fail2ban jail.  This removes the requirement to explicitly
             ;; extend services with fail2ban-service-type.
             (fail2ban-jail-service
              openssh-service-type
              (fail2ban-jail-configuration
               (name "sshd")
               (enabled? #t)))
             (openssh-configuration ...))))

   Below is the reference for the different ‘jail-service-type’
configuration records.

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

     ‘fail2ban’ (default: ‘fail2ban’) (type: package)
          The ‘fail2ban’ package to use.  It is used for both binaries
          and as base default configuration that is to be extended with
          ‘<fail2ban-jail-configuration>’ objects.

     ‘run-directory’ (default: ‘"/var/run/fail2ban"’) (type: string)
          The state directory for the ‘fail2ban’ daemon.

     ‘jails’ (default: ‘()’) (type: list-of-fail2ban-jail-configurations)
          Instances of ‘<fail2ban-jail-configuration>’ collected from
          extensions.

     ‘extra-jails’ (default: ‘()’) (type: list-of-fail2ban-jail-configurations)
          Instances of ‘<fail2ban-jail-configuration>’ explicitly
          provided.

     ‘extra-content’ (default: ‘()’) (type: text-config)
          Extra raw content to add to the end of the ‘jail.local’ file,
          provided as a list of file-like objects.

 -- Data Type: fail2ban-ignore-cache-configuration
     Available ‘fail2ban-ignore-cache-configuration’ fields are:

     ‘key’ (type: string)
          Cache key.

     ‘max-count’ (type: integer)
          Cache size.

     ‘max-time’ (type: integer)
          Cache time.

 -- Data Type: fail2ban-jail-action-configuration
     Available ‘fail2ban-jail-action-configuration’ fields are:

     ‘name’ (type: string)
          Action name.

     ‘arguments’ (default: ‘()’) (type: list-of-arguments)
          Action arguments.

 -- Data Type: fail2ban-jail-configuration
     Available ‘fail2ban-jail-configuration’ fields are:

     ‘name’ (type: string)
          Required name of this jail configuration.

     ‘enabled?’ (default: ‘#t’) (type: boolean)
          Whether this jail is enabled.

     ‘backend’ (type: maybe-symbol)
          Backend to use to detect changes in the ‘log-path’.  The
          default is ’auto.  To consult the defaults of the jail
          configuration, refer to the ‘/etc/fail2ban/jail.conf’ file of
          the ‘fail2ban’ package.

     ‘max-retry’ (type: maybe-integer)
          The number of failures before a host get banned (e.g.
          ‘(max-retry 5)’).

     ‘max-matches’ (type: maybe-integer)
          The number of matches stored in ticket (resolvable via tag
          ‘<matches>’) in action.

     ‘find-time’ (type: maybe-string)
          The time window during which the maximum retry count must be
          reached for an IP address to be banned.  A host is banned if
          it has generated ‘max-retry’ during the last ‘find-time’
          seconds (e.g.  ‘(find-time "10m")’).  It can be provided in
          seconds or using Fail2Ban’s "time abbreviation format", as
          described in ‘man 5 jail.conf’.

     ‘ban-time’ (type: maybe-string)
          The duration, in seconds or time abbreviated format, that a
          ban should last.  (e.g.  ‘(ban-time "10m")’).

     ‘ban-time-increment?’ (type: maybe-boolean)
          Whether to consider past bans to compute increases to the
          default ban time of a specific IP address.

     ‘ban-time-factor’ (type: maybe-string)
          The coefficient to use to compute an exponentially growing ban
          time.

     ‘ban-time-formula’ (type: maybe-string)
          This is the formula used to calculate the next value of a ban
          time.

     ‘ban-time-multipliers’ (type: maybe-string)
          Used to calculate next value of ban time instead of formula.

     ‘ban-time-max-time’ (type: maybe-string)
          The maximum number of seconds a ban should last.

     ‘ban-time-rnd-time’ (type: maybe-string)
          The maximum number of seconds a randomized ban time should
          last.  This can be useful to stop “clever” botnets calculating
          the exact time an IP address can be unbanned again.

     ‘ban-time-overall-jails?’ (type: maybe-boolean)
          When true, it specifies the search of an IP address in the
          database should be made across all jails.  Otherwise, only the
          current jail of the ban IP address is considered.

     ‘ignore-self?’ (type: maybe-boolean)
          Never ban the local machine’s own IP address.

     ‘ignore-ip’ (default: ‘()’) (type: list-of-strings)
          A list of IP addresses, CIDR masks or DNS hosts to ignore.
          ‘fail2ban’ will not ban a host which matches an address in
          this list.

     ‘ignore-cache’ (type: maybe-fail2ban-ignore-cache-configuration)
          Provide cache parameters for the ignore failure check.

     ‘filter’ (type: maybe-fail2ban-jail-filter-configuration)
          The filter to use by the jail, specified via a
          ‘<fail2ban-jail-filter-configuration>’ object.  By default,
          jails have names matching their filter name.

     ‘log-time-zone’ (type: maybe-string)
          The default time zone for log lines that do not have one.

     ‘log-encoding’ (type: maybe-symbol)
          The encoding of the log files handled by the jail.  Possible
          values are: ‘'ascii’, ‘'utf-8’ and ‘'auto’.

     ‘log-path’ (default: ‘()’) (type: list-of-strings)
          The file names of the log files to be monitored.

     ‘action’ (default: ‘()’) (type: list-of-fail2ban-jail-actions)
          A list of ‘<fail2ban-jail-action-configuration>’.

     ‘extra-content’ (default: ‘()’) (type: text-config)
          Extra content for the jail configuration, provided as a list
          of file-like objects.

 -- Data Type: fail2ban-jail-filter-configuration
     Available ‘fail2ban-jail-filter-configuration’ fields are:

     ‘name’ (type: string)
          Filter to use.

     ‘mode’ (type: maybe-string)
          Mode for filter.


File: guix.info,  Node: Setuid Programs,  Next: X.509 Certificates,  Prev: Services,  Up: System Configuration

12.10 Setuid Programs
=====================

Some programs need to run with elevated privileges, even when they are
launched by unprivileged users.  A notorious example is the ‘passwd’
program, which users can run to change their password, and which needs
to access the ‘/etc/passwd’ and ‘/etc/shadow’ files—something normally
restricted to root, for obvious security reasons.  To address that,
‘passwd’ should be “setuid-root”, meaning that it always runs with root
privileges (*note (libc)How Change Persona::, for more info about the
setuid mechanism).

   The store itself _cannot_ contain setuid programs: that would be a
security issue since any user on the system can write derivations that
populate the store (*note The Store::).  Thus, a different mechanism is
used: instead of changing the setuid or setgid bits directly on files
that are in the store, we let the system administrator _declare_ which
programs should be entrusted with these additional privileges.

   The ‘setuid-programs’ field of an ‘operating-system’ declaration
contains a list of ‘<setuid-program>’ denoting the names of programs to
have a setuid or setgid bit set (*note Using the Configuration
System::).  For instance, the ‘mount.nfs’ program, which is part of the
nfs-utils package, with a setuid root can be designated like this:

     (setuid-program
       (program (file-append nfs-utils "/sbin/mount.nfs")))

   And then, to make ‘mount.nfs’ setuid on your system, add the previous
example to your operating system declaration by appending it to
‘%setuid-programs’ like this:

     (operating-system
       ;; Some fields omitted...
       (setuid-programs
         (append (list (setuid-program
                         (program (file-append nfs-utils "/sbin/mount.nfs"))))
                 %setuid-programs)))

 -- Data Type: setuid-program
     This data type represents a program with a setuid or setgid bit
     set.

     ‘program’
          A file-like object having its setuid and/or setgid bit set.

     ‘setuid?’ (default: ‘#t’)
          Whether to set user setuid bit.

     ‘setgid?’ (default: ‘#f’)
          Whether to set group setgid bit.

     ‘user’ (default: ‘0’)
          UID (integer) or user name (string) for the user owner of the
          program, defaults to root.

     ‘group’ (default: ‘0’)
          GID (integer) goup name (string) for the group owner of the
          program, defaults to root.

   A default set of setuid programs is defined by the ‘%setuid-programs’
variable of the ‘(gnu system)’ module.

 -- Scheme Variable: %setuid-programs
     A list of ‘<setuid-program>’ denoting common programs that are
     setuid-root.

     The list includes commands such as ‘passwd’, ‘ping’, ‘su’, and
     ‘sudo’.

   Under the hood, the actual setuid programs are created in the
‘/run/setuid-programs’ directory at system activation time.  The files
in this directory refer to the “real” binaries, which are in the store.


File: guix.info,  Node: X.509 Certificates,  Next: Name Service Switch,  Prev: Setuid Programs,  Up: System Configuration

12.11 X.509 Certificates
========================

Web servers available over HTTPS (that is, HTTP over the transport-layer
security mechanism, TLS) send client programs an “X.509 certificate”
that the client can then use to _authenticate_ the server.  To do that,
clients verify that the server’s certificate is signed by a so-called
“certificate authority” (CA). But to verify the CA’s signature, clients
must have first acquired the CA’s certificate.

   Web browsers such as GNU IceCat include their own set of CA
certificates, such that they are able to verify CA signatures
out-of-the-box.

   However, most other programs that can talk HTTPS—‘wget’, ‘git’,
‘w3m’, etc.—need to be told where CA certificates can be found.

   In Guix, this is done by adding a package that provides certificates
to the ‘packages’ field of the ‘operating-system’ declaration (*note
operating-system Reference::).  Guix includes one such package,
‘nss-certs’, which is a set of CA certificates provided as part of
Mozilla’s Network Security Services.

   Note that it is _not_ part of ‘%base-packages’, so you need to
explicitly add it.  The ‘/etc/ssl/certs’ directory, which is where most
applications and libraries look for certificates by default, points to
the certificates installed globally.

   Unprivileged users, including users of Guix on a foreign distro, can
also install their own certificate package in their profile.  A number
of environment variables need to be defined so that applications and
libraries know where to find them.  Namely, the OpenSSL library honors
the ‘SSL_CERT_DIR’ and ‘SSL_CERT_FILE’ variables.  Some applications add
their own environment variables; for instance, the Git version control
system honors the certificate bundle pointed to by the ‘GIT_SSL_CAINFO’
environment variable.  Thus, you would typically run something like:

     guix install nss-certs
     export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs"
     export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
     export GIT_SSL_CAINFO="$SSL_CERT_FILE"

   As another example, R requires the ‘CURL_CA_BUNDLE’ environment
variable to point to a certificate bundle, so you would have to run
something like this:

     guix install nss-certs
     export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"

   For other applications you may want to look up the required
environment variable in the relevant documentation.


File: guix.info,  Node: Name Service Switch,  Next: Initial RAM Disk,  Prev: X.509 Certificates,  Up: System Configuration

12.12 Name Service Switch
=========================

The ‘(gnu system nss)’ module provides bindings to the configuration
file of the libc “name service switch” or “NSS” (*note (libc)NSS
Configuration File::).  In a nutshell, the NSS is a mechanism that
allows libc to be extended with new “name” lookup methods for system
databases, which includes host names, service names, user accounts, and
more (*note System Databases and Name Service Switch: (libc)Name Service
Switch.).

   The NSS configuration specifies, for each system database, which
lookup method is to be used, and how the various methods are chained
together—for instance, under which circumstances NSS should try the next
method in the list.  The NSS configuration is given in the
‘name-service-switch’ field of ‘operating-system’ declarations (*note
‘name-service-switch’: operating-system Reference.).

   As an example, the declaration below configures the NSS to use the
‘nss-mdns’ back-end (https://0pointer.de/lennart/projects/nss-mdns/),
which supports host name lookups over multicast DNS (mDNS) for host
names ending in ‘.local’:

     (name-service-switch
        (hosts (list %files    ;first, check /etc/hosts

                     ;; If the above did not succeed, try
                     ;; with 'mdns_minimal'.
                     (name-service
                       (name "mdns_minimal")

                       ;; 'mdns_minimal' is authoritative for
                       ;; '.local'.  When it returns "not found",
                       ;; no need to try the next methods.
                       (reaction (lookup-specification
                                  (not-found => return))))

                     ;; Then fall back to DNS.
                     (name-service
                       (name "dns"))

                     ;; Finally, try with the "full" 'mdns'.
                     (name-service
                       (name "mdns")))))

   Do not worry: the ‘%mdns-host-lookup-nss’ variable (see below)
contains this configuration, so you will not have to type it if all you
want is to have ‘.local’ host lookup working.

   Note that, in this case, in addition to setting the
‘name-service-switch’ of the ‘operating-system’ declaration, you also
need to use ‘avahi-service-type’ (*note ‘avahi-service-type’: Networking
Services.), or ‘%desktop-services’, which includes it (*note Desktop
Services::).  Doing this makes ‘nss-mdns’ accessible to the name service
cache daemon (*note ‘nscd-service’: Base Services.).

   For convenience, the following variables provide typical NSS
configurations.

 -- Scheme Variable: %default-nss
     This is the default name service switch configuration, a
     ‘name-service-switch’ object.

 -- Scheme Variable: %mdns-host-lookup-nss
     This is the name service switch configuration with support for host
     name lookup over multicast DNS (mDNS) for host names ending in
     ‘.local’.

   The reference for name service switch configuration is given below.
It is a direct mapping of the configuration file format of the C library
, so please refer to the C library manual for more information (*note
(libc)NSS Configuration File::).  Compared to the configuration file
format of libc NSS, it has the advantage not only of adding this warm
parenthetic feel that we like, but also static checks: you will know
about syntax errors and typos as soon as you run ‘guix system’.

 -- Data Type: name-service-switch

     This is the data type representation the configuration of libc’s
     name service switch (NSS). Each field below represents one of the
     supported system databases.

     ‘aliases’
     ‘ethers’
     ‘group’
     ‘gshadow’
     ‘hosts’
     ‘initgroups’
     ‘netgroup’
     ‘networks’
     ‘password’
     ‘public-key’
     ‘rpc’
     ‘services’
     ‘shadow’
          The system databases handled by the NSS.  Each of these fields
          must be a list of ‘<name-service>’ objects (see below).

 -- Data Type: name-service

     This is the data type representing an actual name service and the
     associated lookup action.

     ‘name’
          A string denoting the name service (*note (libc)Services in
          the NSS configuration::).

          Note that name services listed here must be visible to nscd.
          This is achieved by passing the ‘#:name-services’ argument to
          ‘nscd-service’ the list of packages providing the needed name
          services (*note ‘nscd-service’: Base Services.).

     ‘reaction’
          An action specified using the ‘lookup-specification’ macro
          (*note (libc)Actions in the NSS configuration::).  For
          example:

               (lookup-specification (unavailable => continue)
                                     (success => return))


File: guix.info,  Node: Initial RAM Disk,  Next: Bootloader Configuration,  Prev: Name Service Switch,  Up: System Configuration

12.13 Initial RAM Disk
======================

For bootstrapping purposes, the Linux-Libre kernel is passed an “initial
RAM disk”, or “initrd”.  An initrd contains a temporary root file system
as well as an initialization script.  The latter is responsible for
mounting the real root file system, and for loading any kernel modules
that may be needed to achieve that.

   The ‘initrd-modules’ field of an ‘operating-system’ declaration
allows you to specify Linux-libre kernel modules that must be available
in the initrd.  In particular, this is where you would list modules
needed to actually drive the hard disk where your root partition
is—although the default value of ‘initrd-modules’ should cover most use
cases.  For example, assuming you need the ‘megaraid_sas’ module in
addition to the default modules to be able to access your root file
system, you would write:

     (operating-system
       ;; ...
       (initrd-modules (cons "megaraid_sas" %base-initrd-modules)))

 -- Scheme Variable: %base-initrd-modules
     This is the list of kernel modules included in the initrd by
     default.

   Furthermore, if you need lower-level customization, the ‘initrd’
field of an ‘operating-system’ declaration allows you to specify which
initrd you would like to use.  The ‘(gnu system linux-initrd)’ module
provides three ways to build an initrd: the high-level ‘base-initrd’
procedure and the low-level ‘raw-initrd’ and ‘expression->initrd’
procedures.

   The ‘base-initrd’ procedure is intended to cover most common uses.
For example, if you want to add a bunch of kernel modules to be loaded
at boot time, you can define the ‘initrd’ field of the operating system
declaration like this:

     (initrd (lambda (file-systems . rest)
               ;; Create a standard initrd but set up networking
               ;; with the parameters QEMU expects by default.
               (apply base-initrd file-systems
                      #:qemu-networking? #t
                      rest)))

   The ‘base-initrd’ procedure also handles common use cases that
involves using the system as a QEMU guest, or as a “live” system with
volatile root file system.

   The ‘base-initrd’ procedure is built from ‘raw-initrd’ procedure.
Unlike ‘base-initrd’, ‘raw-initrd’ doesn’t do anything high-level, such
as trying to guess which kernel modules and packages should be included
to the initrd.  An example use of ‘raw-initrd’ is when a user has a
custom Linux kernel configuration and default kernel modules included by
‘base-initrd’ are not available.

   The initial RAM disk produced by ‘base-initrd’ or ‘raw-initrd’ honors
several options passed on the Linux kernel command line (that is,
arguments passed via the ‘linux’ command of GRUB, or the ‘-append’
option of QEMU), notably:

‘gnu.load=BOOT’
     Tell the initial RAM disk to load BOOT, a file containing a Scheme
     program, once it has mounted the root file system.

     Guix uses this option to yield control to a boot program that runs
     the service activation programs and then spawns the GNU Shepherd,
     the initialization system.

‘root=ROOT’
     Mount ROOT as the root file system.  ROOT can be a device name like
     ‘/dev/sda1’, a file system label, or a file system UUID. When
     unspecified, the device name from the root file system of the
     operating system declaration is used.

‘rootfstype=TYPE’
     Set the type of the root file system.  It overrides the ‘type’
     field of the root file system specified via the ‘operating-system’
     declaration, if any.

‘rootflags=OPTIONS’
     Set the mount _options_ of the root file system.  It overrides the
     ‘options’ field of the root file system specified via the
     ‘operating-system’ declaration, if any.

‘fsck.mode=MODE’
     Whether to check the ROOT file system for errors before mounting
     it.  MODE is one of ‘skip’ (never check), ‘force’ (always check),
     or ‘auto’ to respect the root ‘<file-system>’ object’s ‘check?’
     setting (*note File Systems::) and run a full scan only if the file
     system was not cleanly shut down.

     ‘auto’ is the default if this option is not present or if MODE is
     not one of the above.

‘fsck.repair=LEVEL’
     The level of repairs to perform automatically if errors are found
     in the ROOT file system.  LEVEL is one of ‘no’ (do not write to
     ROOT at all if possible), ‘yes’ (repair as much as possible), or
     ‘preen’ to repair problems considered safe to repair automatically.

     ‘preen’ is the default if this option is not present or if LEVEL is
     not one of the above.

‘gnu.system=SYSTEM’
     Have ‘/run/booted-system’ and ‘/run/current-system’ point to
     SYSTEM.

‘modprobe.blacklist=MODULES...’
     Instruct the initial RAM disk as well as the ‘modprobe’ command
     (from the kmod package) to refuse to load MODULES.  MODULES must be
     a comma-separated list of module names—e.g., ‘usbkbd,9pnet’.

‘gnu.repl’
     Start a read-eval-print loop (REPL) from the initial RAM disk
     before it tries to load kernel modules and to mount the root file
     system.  Our marketing team calls it “boot-to-Guile”.  The Schemer
     in you will love it.  *Note (guile)Using Guile Interactively::, for
     more information on Guile’s REPL.

   Now that you know all the features that initial RAM disks produced by
‘base-initrd’ and ‘raw-initrd’ provide, here is how to use it and
customize it further.

 -- Scheme Procedure: raw-initrd FILE-SYSTEMS [#:linux-modules '()]
          [#:pre-mount #t] [#:mapped-devices '()] [#:keyboard-layout #f]
          [#:helper-packages '()] [#:qemu-networking? #f]
          [#:volatile-root? #f]
     Return a derivation that builds a raw initrd.  FILE-SYSTEMS is a
     list of file systems to be mounted by the initrd, possibly in
     addition to the root file system specified on the kernel command
     line via ‘root’.  LINUX-MODULES is a list of kernel modules to be
     loaded at boot time.  MAPPED-DEVICES is a list of device mappings
     to realize before FILE-SYSTEMS are mounted (*note Mapped
     Devices::).  PRE-MOUNT is a G-expression to evaluate before
     realizing MAPPED-DEVICES.  HELPER-PACKAGES is a list of packages to
     be copied in the initrd.  It may include ‘e2fsck/static’ or other
     packages needed by the initrd to check the root file system.

     When true, KEYBOARD-LAYOUT is a ‘<keyboard-layout>’ record denoting
     the desired console keyboard layout.  This is done before
     MAPPED-DEVICES are set up and before FILE-SYSTEMS are mounted such
     that, should the user need to enter a passphrase or use the REPL,
     this happens using the intended keyboard layout.

     When QEMU-NETWORKING? is true, set up networking with the standard
     QEMU parameters.  When VIRTIO? is true, load additional modules so
     that the initrd can be used as a QEMU guest with para-virtualized
     I/O drivers.

     When VOLATILE-ROOT? is true, the root file system is writable but
     any changes to it are lost.

 -- Scheme Procedure: base-initrd FILE-SYSTEMS [#:mapped-devices '()]
          [#:keyboard-layout #f] [#:qemu-networking? #f]
          [#:volatile-root? #f] [#:linux-modules '()]
     Return as a file-like object a generic initrd, with kernel modules
     taken from LINUX.  FILE-SYSTEMS is a list of file-systems to be
     mounted by the initrd, possibly in addition to the root file system
     specified on the kernel command line via ‘root’.  MAPPED-DEVICES is
     a list of device mappings to realize before FILE-SYSTEMS are
     mounted.

     When true, KEYBOARD-LAYOUT is a ‘<keyboard-layout>’ record denoting
     the desired console keyboard layout.  This is done before
     MAPPED-DEVICES are set up and before FILE-SYSTEMS are mounted such
     that, should the user need to enter a passphrase or use the REPL,
     this happens using the intended keyboard layout.

     QEMU-NETWORKING? and VOLATILE-ROOT? behaves as in ‘raw-initrd’.

     The initrd is automatically populated with all the kernel modules
     necessary for FILE-SYSTEMS and for the given options.  Additional
     kernel modules can be listed in LINUX-MODULES.  They will be added
     to the initrd, and loaded at boot time in the order in which they
     appear.

   Needless to say, the initrds we produce and use embed a
statically-linked Guile, and the initialization program is a Guile
program.  That gives a lot of flexibility.  The ‘expression->initrd’
procedure builds such an initrd, given the program to run in that
initrd.

 -- Scheme Procedure: expression->initrd EXP [#:guile
          %guile-static-stripped] [#:name "guile-initrd"]
     Return as a file-like object a Linux initrd (a gzipped cpio
     archive) containing GUILE and that evaluates EXP, a G-expression,
     upon booting.  All the derivations referenced by EXP are
     automatically copied to the initrd.


File: guix.info,  Node: Bootloader Configuration,  Next: Invoking guix system,  Prev: Initial RAM Disk,  Up: System Configuration

12.14 Bootloader Configuration
==============================

The operating system supports multiple bootloaders.  The bootloader is
configured using ‘bootloader-configuration’ declaration.  All the fields
of this structure are bootloader agnostic except for one field,
‘bootloader’ that indicates the bootloader to be configured and
installed.

   Some of the bootloaders do not honor every field of
‘bootloader-configuration’.  For instance, the extlinux bootloader does
not support themes and thus ignores the ‘theme’ field.

 -- Data Type: bootloader-configuration
     The type of a bootloader configuration declaration.

     ‘bootloader’
          The bootloader to use, as a ‘bootloader’ object.  For now
          ‘grub-bootloader’, ‘grub-efi-bootloader’,
          ‘grub-efi-netboot-bootloader’,
          ‘grub-efi-removable-bootloader’, ‘extlinux-bootloader’ and
          ‘u-boot-bootloader’ are supported.

          Available bootloaders are described in ‘(gnu bootloader ...)’
          modules.  In particular, ‘(gnu bootloader u-boot)’ contains
          definitions of bootloaders for a wide range of ARM and AArch64
          systems, using the U-Boot bootloader
          (https://www.denx.de/wiki/U-Boot/).

          ‘grub-efi-bootloader’ allows to boot on modern systems using
          the “Unified Extensible Firmware Interface” (UEFI). This is
          what you should use if the installation image contains a
          ‘/sys/firmware/efi’ directory when you boot it on your system.

          ‘grub-bootloader’ allows you to boot in particular Intel-based
          machines in “legacy” BIOS mode.

          ‘grub-efi-netboot-bootloader’ allows you to boot your system
          over network through TFTP.  In combination with an NFS root
          file system this allows you to build a diskless Guix system.

          The installation of the ‘grub-efi-netboot-bootloader’
          generates the content of the TFTP root directory at ‘targets’
          (*note ‘targets’: Bootloader Configuration.), to be served by
          a TFTP server.  You may want to mount your TFTP server
          directories onto the ‘targets’ to move the required files to
          the TFTP server automatically.

          If you plan to use an NFS root file system as well (actually
          if you mount the store from an NFS share), then the TFTP
          server needs to serve the file ‘/boot/grub/grub.cfg’ and other
          files from the store (like GRUBs background image, the kernel
          (*note ‘kernel’: operating-system Reference.) and the initrd
          (*note ‘initrd’: operating-system Reference.)), too.  All
          these files from the store will be accessed by GRUB through
          TFTP with their normal store path, for example as
          ‘tftp://tftp-server/gnu/store/…-initrd/initrd.cpio.gz’.

          Two symlinks are created to make this possible.  For each
          target in the ‘targets’ field, the first symlink is
          ‘target’‘/efi/Guix/boot/grub/grub.cfg’ pointing to
          ‘../../../boot/grub/grub.cfg’, where ‘target’ may be ‘/boot’.
          In this case the link is not leaving the served TFTP root
          directory, but otherwise it does.  The second link is
          ‘target’‘/gnu/store’ and points to ‘../gnu/store’.  This link
          is leaving the served TFTP root directory.

          The assumption behind all this is that you have an NFS server
          exporting the root file system for your Guix system, and
          additionally a TFTP server exporting your ‘targets’
          directories—usually a single ‘/boot’—from that same root file
          system for your Guix system.  In this constellation the
          symlinks will work.

          For other constellations you will have to program your own
          bootloader installer, which then takes care to make necessary
          files from the store accessible through TFTP, for example by
          copying them into the TFTP root directory to your ‘targets’.

          It is important to note that symlinks pointing outside the
          TFTP root directory may need to be allowed in the
          configuration of your TFTP server.  Further the store link
          exposes the whole store through TFTP.  Both points need to be
          considered carefully for security aspects.

          Beside the ‘grub-efi-netboot-bootloader’, the already
          mentioned TFTP and NFS servers, you also need a properly
          configured DHCP server to make the booting over netboot
          possible.  For all this we can currently only recommend you to
          look for instructions about PXE (Preboot eXecution
          Environment).

          ‘grub-efi-removable-bootloader’ allows you to boot your system
          from removable media by writing the GRUB file to the
          UEFI-specification location of ‘/EFI/BOOT/BOOTX64.efi’ of the
          boot directory, usually ‘/boot/efi’.  This is also useful for
          some UEFI firmwares that “forget” their configuration from
          their non-volatile storage.  Like ‘grub-efi-bootloader’, this
          can only be used if the ‘/sys/firmware/efi’ directory is
          available.

               Note: This _will_ overwrite the GRUB file from any other
               operating systems that also place their GRUB file in the
               UEFI-specification location; making them unbootable.

     ‘targets’
          This is a list of strings denoting the targets onto which to
          install the bootloader.

          The interpretation of targets depends on the bootloader in
          question.  For ‘grub-bootloader’, for example, they should be
          device names understood by the bootloader ‘installer’ command,
          such as ‘/dev/sda’ or ‘(hd0)’ (*note (grub)Invoking
          grub-install::).  For ‘grub-efi-bootloader’ and
          ‘grub-efi-removable-bootloader’ they should be mount points of
          the EFI file system, usually ‘/boot/efi’.  For
          ‘grub-efi-netboot-bootloader’, ‘targets’ should be the mount
          points corresponding to TFTP root directories served by your
          TFTP server.

     ‘menu-entries’ (default: ‘()’)
          A possibly empty list of ‘menu-entry’ objects (see below),
          denoting entries to appear in the bootloader menu, in addition
          to the current system entry and the entry pointing to previous
          system generations.

     ‘default-entry’ (default: ‘0’)
          The index of the default boot menu entry.  Index 0 is for the
          entry of the current system.

     ‘timeout’ (default: ‘5’)
          The number of seconds to wait for keyboard input before
          booting.  Set to 0 to boot immediately, and to -1 to wait
          indefinitely.

     ‘keyboard-layout’ (default: ‘#f’)
          If this is ‘#f’, the bootloader’s menu (if any) uses the
          default keyboard layout, usually US English (“qwerty”).

          Otherwise, this must be a ‘keyboard-layout’ object (*note
          Keyboard Layout::).

               Note: This option is currently ignored by bootloaders
               other than ‘grub’ and ‘grub-efi’.

     ‘theme’ (default: #F)
          The bootloader theme object describing the theme to use.  If
          no theme is provided, some bootloaders might use a default
          theme, that’s true for GRUB.

     ‘terminal-outputs’ (default: ‘'(gfxterm)’)
          The output terminals used for the bootloader boot menu, as a
          list of symbols.  GRUB accepts the values: ‘console’,
          ‘serial’, ‘serial_{0-3}’, ‘gfxterm’, ‘vga_text’, ‘mda_text’,
          ‘morse’, and ‘pkmodem’.  This field corresponds to the GRUB
          variable ‘GRUB_TERMINAL_OUTPUT’ (*note (grub)Simple
          configuration::).

     ‘terminal-inputs’ (default: ‘'()’)
          The input terminals used for the bootloader boot menu, as a
          list of symbols.  For GRUB, the default is the native platform
          terminal as determined at run-time.  GRUB accepts the values:
          ‘console’, ‘serial’, ‘serial_{0-3}’, ‘at_keyboard’, and
          ‘usb_keyboard’.  This field corresponds to the GRUB variable
          ‘GRUB_TERMINAL_INPUT’ (*note (grub)Simple configuration::).

     ‘serial-unit’ (default: ‘#f’)
          The serial unit used by the bootloader, as an integer from 0
          to 3.  For GRUB, it is chosen at run-time; currently GRUB
          chooses 0, which corresponds to COM1 (*note (grub)Serial
          terminal::).

     ‘serial-speed’ (default: ‘#f’)
          The speed of the serial interface, as an integer.  For GRUB,
          the default value is chosen at run-time; currently GRUB
          chooses 9600 bps (*note (grub)Serial terminal::).

     ‘device-tree-support?’ (default: ‘#t’)
          Whether to support Linux device tree
          (https://en.wikipedia.org/wiki/Devicetree) files loading.

          This option in enabled by default.  In some cases involving
          the ‘u-boot’ bootloader, where the device tree has already
          been loaded in RAM, it can be handy to disable the option by
          setting it to ‘#f’.

   Should you want to list additional boot menu entries via the
‘menu-entries’ field above, you will need to create them with the
‘menu-entry’ form.  For example, imagine you want to be able to boot
another distro (hard to imagine!), you can define a menu entry along
these lines:

     (menu-entry
       (label "The Other Distro")
       (linux "/boot/old/vmlinux-2.6.32")
       (linux-arguments '("root=/dev/sda2"))
       (initrd "/boot/old/initrd"))

   Details below.

 -- Data Type: menu-entry
     The type of an entry in the bootloader menu.

     ‘label’
          The label to show in the menu—e.g., ‘"GNU"’.

     ‘linux’ (default: ‘#f’)
          The Linux kernel image to boot, for example:

               (file-append linux-libre "/bzImage")

          For GRUB, it is also possible to specify a device explicitly
          in the file path using GRUB’s device naming convention (*note
          (grub)Naming convention::), for example:

               "(hd0,msdos1)/boot/vmlinuz"

          If the device is specified explicitly as above, then the
          ‘device’ field is ignored entirely.

     ‘linux-arguments’ (default: ‘()’)
          The list of extra Linux kernel command-line arguments—e.g.,
          ‘("console=ttyS0")’.

     ‘initrd’ (default: ‘#f’)
          A G-Expression or string denoting the file name of the initial
          RAM disk to use (*note G-Expressions::).

     ‘device’ (default: ‘#f’)
          The device where the kernel and initrd are to be found—i.e.,
          for GRUB, “root” for this menu entry (*note (grub)root::).

          This may be a file system label (a string), a file system UUID
          (a bytevector, *note File Systems::), or ‘#f’, in which case
          the bootloader will search the device containing the file
          specified by the ‘linux’ field (*note (grub)search::).  It
          must _not_ be an OS device name such as ‘/dev/sda1’.

     ‘multiboot-kernel’ (default: ‘#f’)
          The kernel to boot in Multiboot-mode (*note
          (grub)multiboot::).  When this field is set, a Multiboot
          menu-entry is generated.  For example:

               (file-append mach "/boot/gnumach")

     ‘multiboot-arguments’ (default: ‘()’)
          The list of extra command-line arguments for the
          multiboot-kernel.

     ‘multiboot-modules’ (default: ‘()’)
          The list of commands for loading Multiboot modules.  For
          example:

               (list (list (file-append hurd "/hurd/ext2fs.static") "ext2fs"
                            ...)
                     (list (file-append libc "/lib/ld.so.1") "exec"
                            ...))

     ‘chain-loader’ (default: ‘#f’)
          A string that can be accepted by ‘grub’’s ‘chainloader’
          directive.  This has no effect if either ‘linux’ or
          ‘multiboot-kernel’ fields are specified.  The following is an
          example of chainloading a different GNU/Linux system.

               (bootloader
                (bootloader-configuration
                 ;; ...
                 (menu-entries
                  (list
                   (menu-entry
                    (label "GNU/Linux")
                    (device (uuid "1C31-A17C" 'fat))
                    (chain-loader "/EFI/GNULinux/grubx64.efi"))))))

   For now only GRUB has theme support.  GRUB themes are created using
the ‘grub-theme’ form, which is not fully documented yet.

 -- Data Type: grub-theme
     Data type representing the configuration of the GRUB theme.

     ‘gfxmode’ (default: ‘'("auto")’)
          The GRUB ‘gfxmode’ to set (a list of screen resolution
          strings, *note (grub)gfxmode::).

 -- Scheme Procedure: grub-theme
     Return the default GRUB theme used by the operating system if no
     ‘theme’ field is specified in ‘bootloader-configuration’ record.

     It comes with a fancy background image displaying the GNU and Guix
     logos.

   For example, to override the default resolution, you may use
something like

     (bootloader
      (bootloader-configuration
      ;; ...
      (theme (grub-theme
              (inherit (grub-theme))
              (gfxmode '("1024x786x32" "auto"))))))


File: guix.info,  Node: Invoking guix system,  Next: Invoking guix deploy,  Prev: Bootloader Configuration,  Up: System Configuration

12.15 Invoking ‘guix system’
============================

Once you have written an operating system declaration as seen in the
previous section, it can be “instantiated” using the ‘guix system’
command.  The synopsis is:

     guix system OPTIONS... ACTION FILE

   FILE must be the name of a file containing an ‘operating-system’
declaration.  ACTION specifies how the operating system is instantiated.
Currently the following values are supported:

‘search’
     Display available service type definitions that match the given
     regular expressions, sorted by relevance:

          $ guix system search console
          name: console-fonts
          location: gnu/services/base.scm:806:2
          extends: shepherd-root
          description: Install the given fonts on the specified ttys (fonts are per
          + virtual console on GNU/Linux).  The value of this service is a list of
          + tty/font pairs.  The font can be the name of a font provided by the `kbd'
          + package or any valid argument to `setfont', as in this example:
          +
          +      '(("tty1" . "LatGrkCyr-8x16")
          +        ("tty2" . (file-append
          +                      font-tamzen
          +                      "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
          +        ("tty3" . (file-append
          +                      font-terminus
          +                      "/share/consolefonts/ter-132n"))) ; for HDPI
          relevance: 9

          name: mingetty
          location: gnu/services/base.scm:1190:2
          extends: shepherd-root
          description: Provide console login using the `mingetty' program.
          relevance: 2

          name: login
          location: gnu/services/base.scm:860:2
          extends: pam
          description: Provide a console log-in service as specified by its
          + configuration value, a `login-configuration' object.
          relevance: 2

          ...

     As for ‘guix package --search’, the result is written in ‘recutils’
     format, which makes it easy to filter the output (*note GNU
     recutils databases: (recutils)Top.).

‘edit’
     Edit or view the definition of the given service types.

     For example, the command below opens your editor, as specified by
     the ‘EDITOR’ environment variable, on the definition of the
     ‘openssh’ service type:

          guix system edit openssh

‘reconfigure’
     Build the operating system described in FILE, activate it, and
     switch to it(1).

          Note: It is highly recommended to run ‘guix pull’ once before
          you run ‘guix system reconfigure’ for the first time (*note
          Invoking guix pull::).  Failing to do that you would see an
          older version of Guix once ‘reconfigure’ has completed.

     This effects all the configuration specified in FILE: user
     accounts, system services, global package list, setuid programs,
     etc.  The command starts system services specified in FILE that are
     not currently running; if a service is currently running this
     command will arrange for it to be upgraded the next time it is
     stopped (e.g. by ‘herd stop X’ or ‘herd restart X’).

     This command creates a new generation whose number is one greater
     than the current generation (as reported by ‘guix system
     list-generations’).  If that generation already exists, it will be
     overwritten.  This behavior mirrors that of ‘guix package’ (*note
     Invoking guix package::).

     It also adds a bootloader menu entry for the new OS configuration,
     —unless ‘--no-bootloader’ is passed.  For GRUB, it moves entries
     for older configurations to a submenu, allowing you to choose an
     older system generation at boot time should you need it.

     Upon completion, the new system is deployed under
     ‘/run/current-system’.  This directory contains “provenance
     meta-data”: the list of channels in use (*note Channels::) and FILE
     itself, when available.  You can view it by running:

          guix system describe

     This information is useful should you later want to inspect how
     this particular generation was built.  In fact, assuming FILE is
     self-contained, you can later rebuild generation N of your
     operating system with:

          guix time-machine \
            -C /var/guix/profiles/system-N-link/channels.scm -- \
            system reconfigure \
            /var/guix/profiles/system-N-link/configuration.scm

     You can think of it as some sort of built-in version control!  Your
     system is not just a binary artifact: _it carries its own source_.
     *Note ‘provenance-service-type’: Service Reference, for more
     information on provenance tracking.

     By default, ‘reconfigure’ _prevents you from downgrading your
     system_, which could (re)introduce security vulnerabilities and
     also cause problems with “stateful” services such as database
     management systems.  You can override that behavior by passing
     ‘--allow-downgrades’.

‘switch-generation’
     Switch to an existing system generation.  This action atomically
     switches the system profile to the specified system generation.  It
     also rearranges the system’s existing bootloader menu entries.  It
     makes the menu entry for the specified system generation the
     default, and it moves the entries for the other generations to a
     submenu, if supported by the bootloader being used.  The next time
     the system boots, it will use the specified system generation.

     The bootloader itself is not being reinstalled when using this
     command.  Thus, the installed bootloader is used with an updated
     configuration file.

     The target generation can be specified explicitly by its generation
     number.  For example, the following invocation would switch to
     system generation 7:

          guix system switch-generation 7

     The target generation can also be specified relative to the current
     generation with the form ‘+N’ or ‘-N’, where ‘+3’ means “3
     generations ahead of the current generation,” and ‘-1’ means “1
     generation prior to the current generation.” When specifying a
     negative value such as ‘-1’, you must precede it with ‘--’ to
     prevent it from being parsed as an option.  For example:

          guix system switch-generation -- -1

     Currently, the effect of invoking this action is _only_ to switch
     the system profile to an existing generation and rearrange the
     bootloader menu entries.  To actually start using the target system
     generation, you must reboot after running this action.  In the
     future, it will be updated to do the same things as ‘reconfigure’,
     like activating and deactivating services.

     This action will fail if the specified generation does not exist.

‘roll-back’
     Switch to the preceding system generation.  The next time the
     system boots, it will use the preceding system generation.  This is
     the inverse of ‘reconfigure’, and it is exactly the same as
     invoking ‘switch-generation’ with an argument of ‘-1’.

     Currently, as with ‘switch-generation’, you must reboot after
     running this action to actually start using the preceding system
     generation.

‘delete-generations’
     Delete system generations, making them candidates for garbage
     collection (*note Invoking guix gc::, for information on how to run
     the “garbage collector”).

     This works in the same way as ‘guix package --delete-generations’
     (*note ‘--delete-generations’: Invoking guix package.).  With no
     arguments, all system generations but the current one are deleted:

          guix system delete-generations

     You can also select the generations you want to delete.  The
     example below deletes all the system generations that are more than
     two months old:

          guix system delete-generations 2m

     Running this command automatically reinstalls the bootloader with
     an updated list of menu entries—e.g., the “old generations”
     sub-menu in GRUB no longer lists the generations that have been
     deleted.

‘build’
     Build the derivation of the operating system, which includes all
     the configuration files and programs needed to boot and run the
     system.  This action does not actually install anything.

‘init’
     Populate the given directory with all the files necessary to run
     the operating system specified in FILE.  This is useful for
     first-time installations of Guix System.  For instance:

          guix system init my-os-config.scm /mnt

     copies to ‘/mnt’ all the store items required by the configuration
     specified in ‘my-os-config.scm’.  This includes configuration
     files, packages, and so on.  It also creates other essential files
     needed for the system to operate correctly—e.g., the ‘/etc’,
     ‘/var’, and ‘/run’ directories, and the ‘/bin/sh’ file.

     This command also installs bootloader on the targets specified in
     ‘my-os-config’, unless the ‘--no-bootloader’ option was passed.

‘vm’
     Build a virtual machine (VM) that contains the operating system
     declared in FILE, and return a script to run that VM.

          Note: The ‘vm’ action and others below can use KVM support in
          the Linux-libre kernel.  Specifically, if the machine has
          hardware virtualization support, the corresponding KVM kernel
          module should be loaded, and the ‘/dev/kvm’ device node must
          exist and be readable and writable by the user and by the
          build users of the daemon (*note Build Environment Setup::).

     Arguments given to the script are passed to QEMU as in the example
     below, which enables networking and requests 1 GiB of RAM for the
     emulated machine:

          $ /gnu/store/...-run-vm.sh -m 1024 -smp 2 -nic user,model=virtio-net-pci

     It’s possible to combine the two steps into one:

          $ $(guix system vm my-config.scm) -m 1024 -smp 2 -nic user,model=virtio-net-pci

     The VM shares its store with the host system.

     By default, the root file system of the VM is mounted volatile; the
     ‘--persistent’ option can be provided to make it persistent
     instead.  In that case, the VM disk-image file will be copied from
     the store to the ‘TMPDIR’ directory to make it writable.

     Additional file systems can be shared between the host and the VM
     using the ‘--share’ and ‘--expose’ command-line options: the former
     specifies a directory to be shared with write access, while the
     latter provides read-only access to the shared directory.

     The example below creates a VM in which the user’s home directory
     is accessible read-only, and where the ‘/exchange’ directory is a
     read-write mapping of ‘$HOME/tmp’ on the host:

          guix system vm my-config.scm \
             --expose=$HOME --share=$HOME/tmp=/exchange

     On GNU/Linux, the default is to boot directly to the kernel; this
     has the advantage of requiring only a very tiny root disk image
     since the store of the host can then be mounted.

     The ‘--full-boot’ option forces a complete boot sequence, starting
     with the bootloader.  This requires more disk space since a root
     image containing at least the kernel, initrd, and bootloader data
     files must be created.

     The ‘--image-size’ option can be used to specify the size of the
     image.

     The ‘--no-graphic’ option will instruct ‘guix system’ to spawn a
     headless VM that will use the invoking tty for IO. Among other
     things, this enables copy-pasting, and scrollback.  Use the
     ‘ctrl-a’ prefix to issue QEMU commands; e.g.  ‘ctrl-a h’ prints a
     help, ‘ctrl-a x’ quits the VM, and ‘ctrl-a c’ switches between the
     QEMU monitor and the VM.

‘image’
     The ‘image’ command can produce various image types.  The image
     type can be selected using the ‘--image-type’ option.  It defaults
     to ‘efi-raw’.  When its value is ‘iso9660’, the ‘--label’ option
     can be used to specify a volume ID with ‘image’.  By default, the
     root file system of a disk image is mounted non-volatile; the
     ‘--volatile’ option can be provided to make it volatile instead.
     When using ‘image’, the bootloader installed on the generated image
     is taken from the provided ‘operating-system’ definition.  The
     following example demonstrates how to generate an image that uses
     the ‘grub-efi-bootloader’ bootloader and boot it with QEMU:

          image=$(guix system image --image-type=qcow2 \
                  gnu/system/examples/lightweight-desktop.tmpl)
          cp $image /tmp/my-image.qcow2
          chmod +w /tmp/my-image.qcow2
          qemu-system-x86_64 -enable-kvm -hda /tmp/my-image.qcow2 -m 1000 \
                             -bios $(guix build ovmf)/share/firmware/ovmf_x64.bin

     When using the ‘efi-raw’ image type, a raw disk image is produced;
     it can be copied as is to a USB stick, for instance.  Assuming
     ‘/dev/sdc’ is the device corresponding to a USB stick, one can copy
     the image to it using the following command:

          # dd if=$(guix system image my-os.scm) of=/dev/sdc status=progress

     The ‘--list-image-types’ command lists all the available image
     types.

     When using the ‘qcow2’ image type, the returned image is in qcow2
     format, which the QEMU emulator can efficiently use.  *Note Running
     Guix in a VM::, for more information on how to run the image in a
     virtual machine.  The ‘grub-bootloader’ bootloader is always used
     independently of what is declared in the ‘operating-system’ file
     passed as argument.  This is to make it easier to work with QEMU,
     which uses the SeaBIOS BIOS by default, expecting a bootloader to
     be installed in the Master Boot Record (MBR).

     When using the ‘docker’ image type, a Docker image is produced.
     Guix builds the image from scratch, not from a pre-existing Docker
     base image.  As a result, it contains _exactly_ what you define in
     the operating system configuration file.  You can then load the
     image and launch a Docker container using commands like the
     following:

          image_id="$(docker load < guix-system-docker-image.tar.gz)"
          container_id="$(docker create $image_id)"
          docker start $container_id

     This command starts a new Docker container from the specified
     image.  It will boot the Guix system in the usual manner, which
     means it will start any services you have defined in the operating
     system configuration.  You can get an interactive shell running in
     the container using ‘docker exec’:

          docker exec -ti $container_id /run/current-system/profile/bin/bash --login

     Depending on what you run in the Docker container, it may be
     necessary to give the container additional permissions.  For
     example, if you intend to build software using Guix inside of the
     Docker container, you may need to pass the ‘--privileged’ option to
     ‘docker create’.

     Last, the ‘--network’ option applies to ‘guix system docker-image’:
     it produces an image where network is supposedly shared with the
     host, and thus without services like nscd or NetworkManager.

‘container’
     Return a script to run the operating system declared in FILE within
     a container.  Containers are a set of lightweight isolation
     mechanisms provided by the kernel Linux-libre.  Containers are
     substantially less resource-demanding than full virtual machines
     since the kernel, shared objects, and other resources can be shared
     with the host system; this also means they provide thinner
     isolation.

     Currently, the script must be run as root in order to support more
     than a single user and group.  The container shares its store with
     the host system.

     As with the ‘vm’ action (*note guix system vm::), additional file
     systems to be shared between the host and container can be
     specified using the ‘--share’ and ‘--expose’ options:

          guix system container my-config.scm \
             --expose=$HOME --share=$HOME/tmp=/exchange

     The ‘--share’ and ‘--expose’ options can also be passed to the
     generated script to bind-mount additional directories into the
     container.

          Note: This option requires Linux-libre 3.19 or newer.

   OPTIONS can contain any of the common build options (*note Common
Build Options::).  In addition, OPTIONS can contain one of the
following:

‘--expression=EXPR’
‘-e EXPR’
     Consider the operating-system EXPR evaluates to.  This is an
     alternative to specifying a file which evaluates to an operating
     system.  This is used to generate the Guix system installer *note
     Building the Installation Image::).

‘--system=SYSTEM’
‘-s SYSTEM’
     Attempt to build for SYSTEM instead of the host system type.  This
     works as per ‘guix build’ (*note Invoking guix build::).

‘--target=TRIPLET’
     Cross-build for TRIPLET, which must be a valid GNU triplet, such as
     ‘"aarch64-linux-gnu"’ (*note GNU configuration triplets:
     (autoconf)Specifying target triplets.).

‘--derivation’
‘-d’
     Return the derivation file name of the given operating system
     without building anything.

‘--save-provenance’
     As discussed above, ‘guix system init’ and ‘guix system
     reconfigure’ always save provenance information via a dedicated
     service (*note ‘provenance-service-type’: Service Reference.).
     However, other commands don’t do that by default.  If you wish to,
     say, create a virtual machine image that contains provenance
     information, you can run:

          guix system image -t qcow2 --save-provenance config.scm

     That way, the resulting image will effectively “embed its own
     source” in the form of meta-data in ‘/run/current-system’.  With
     that information, one can rebuild the image to make sure it really
     contains what it pretends to contain; or they could use that to
     derive a variant of the image.

‘--image-type=TYPE’
‘-t TYPE’
     For the ‘image’ action, create an image with given TYPE.

     When this option is omitted, ‘guix system’ uses the ‘efi-raw’ image
     type.

     ‘--image-type=iso9660’ produces an ISO-9660 image, suitable for
     burning on CDs and DVDs.

‘--image-size=SIZE’
     For the ‘image’ action, create an image of the given SIZE.  SIZE
     may be a number of bytes, or it may include a unit as a suffix
     (*note size specifications: (coreutils)Block size.).

     When this option is omitted, ‘guix system’ computes an estimate of
     the image size as a function of the size of the system declared in
     FILE.

‘--network’
‘-N’
     For the ‘container’ action, allow containers to access the host
     network, that is, do not create a network namespace.

‘--root=FILE’
‘-r FILE’
     Make FILE a symlink to the result, and register it as a garbage
     collector root.

‘--skip-checks’
     Skip pre-installation safety checks.

     By default, ‘guix system init’ and ‘guix system reconfigure’
     perform safety checks: they make sure the file systems that appear
     in the ‘operating-system’ declaration actually exist (*note File
     Systems::), and that any Linux kernel modules that may be needed at
     boot time are listed in ‘initrd-modules’ (*note Initial RAM
     Disk::).  Passing this option skips these tests altogether.

‘--allow-downgrades’
     Instruct ‘guix system reconfigure’ to allow system downgrades.

     By default, ‘reconfigure’ prevents you from downgrading your
     system.  It achieves that by comparing the provenance info of your
     system (shown by ‘guix system describe’) with that of your ‘guix’
     command (shown by ‘guix describe’).  If the commits for ‘guix’ are
     not descendants of those used for your system, ‘guix system
     reconfigure’ errors out.  Passing ‘--allow-downgrades’ allows you
     to bypass these checks.

          Note: Make sure you understand its security implications
          before using ‘--allow-downgrades’.

‘--on-error=STRATEGY’
     Apply STRATEGY when an error occurs when reading FILE.  STRATEGY
     may be one of the following:

     ‘nothing-special’
          Report the error concisely and exit.  This is the default
          strategy.

     ‘backtrace’
          Likewise, but also display a backtrace.

     ‘debug’
          Report the error and enter Guile’s debugger.  From there, you
          can run commands such as ‘,bt’ to get a backtrace, ‘,locals’
          to display local variable values, and more generally inspect
          the state of the program.  *Note (guile)Debug Commands::, for
          a list of available debugging commands.

   Once you have built, configured, re-configured, and re-re-configured
your Guix installation, you may find it useful to list the operating
system generations available on disk—and that you can choose from the
bootloader boot menu:

‘describe’
     Describe the running system generation: its file name, the kernel
     and bootloader used, etc., as well as provenance information when
     available.

     The ‘--list-installed’ flag is available, with the same syntax that
     is used in ‘guix package --list-installed’ (*note Invoking guix
     package::).  When the flag is used, the description will include a
     list of packages that are currently installed in the system
     profile, with optional filtering based on a regular expression.

          Note: The _running_ system generation—referred to by
          ‘/run/current-system’—is not necessarily the _current_ system
          generation—referred to by ‘/var/guix/profiles/system’: it
          differs when, for instance, you chose from the bootloader menu
          to boot an older generation.

          It can also differ from the _booted_ system
          generation—referred to by ‘/run/booted-system’—for instance
          because you reconfigured the system in the meantime.

‘list-generations’
     List a summary of each generation of the operating system available
     on disk, in a human-readable way.  This is similar to the
     ‘--list-generations’ option of ‘guix package’ (*note Invoking guix
     package::).

     Optionally, one can specify a pattern, with the same syntax that is
     used in ‘guix package --list-generations’, to restrict the list of
     generations displayed.  For instance, the following command
     displays generations that are up to 10 days old:

          $ guix system list-generations 10d

     The ‘--list-installed’ flag may also be specified, with the same
     syntax that is used in ‘guix package --list-installed’.  This may
     be helpful if trying to determine when a package was added to the
     system.

   The ‘guix system’ command has even more to offer!  The following
sub-commands allow you to visualize how your system services relate to
each other:

‘extension-graph’
     Emit to standard output the “service extension graph” of the
     operating system defined in FILE (*note Service Composition::, for
     more information on service extensions).  By default the output is
     in Dot/Graphviz format, but you can choose a different format with
     ‘--graph-backend’, as with ‘guix graph’ (*note ‘--backend’:
     Invoking guix graph.):

     The command:

          $ guix system extension-graph FILE | xdot -

     shows the extension relations among services.

          Note: The ‘dot’ program is provided by the ‘graphviz’ package.

‘shepherd-graph’
     Emit to standard output the “dependency graph” of shepherd services
     of the operating system defined in FILE.  *Note Shepherd
     Services::, for more information and for an example graph.

     Again, the default output format is Dot/Graphviz, but you can pass
     ‘--graph-backend’ to select a different one.

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

   (1) This action (and the related actions ‘switch-generation’ and
‘roll-back’) are usable only on systems already running Guix System.


File: guix.info,  Node: Invoking guix deploy,  Next: Running Guix in a VM,  Prev: Invoking guix system,  Up: System Configuration

12.16 Invoking ‘guix deploy’
============================

We’ve already seen ‘operating-system’ declarations used to manage a
machine’s configuration locally.  Suppose you need to configure multiple
machines, though—perhaps you’re managing a service on the web that’s
comprised of several servers.  ‘guix deploy’ enables you to use those
same ‘operating-system’ declarations to manage multiple remote hosts at
once as a logical “deployment”.

     Note: The functionality described in this section is still under
     development and is subject to change.  Get in touch with us on
     <guix-devel@gnu.org>!

     guix deploy FILE

   Such an invocation will deploy the machines that the code within FILE
evaluates to.  As an example, FILE might contain a definition like this:

     ;; This is a Guix deployment of a "bare bones" setup, with
     ;; no X11 display server, to a machine with an SSH daemon
     ;; listening on localhost:2222. A configuration such as this
     ;; may be appropriate for virtual machine with ports
     ;; forwarded to the host's loopback interface.

     (use-service-modules networking ssh)
     (use-package-modules bootloaders)

     (define %system
       (operating-system
        (host-name "gnu-deployed")
        (timezone "Etc/UTC")
        (bootloader (bootloader-configuration
                     (bootloader grub-bootloader)
                     (targets '("/dev/vda"))
                     (terminal-outputs '(console))))
        (file-systems (cons (file-system
                             (mount-point "/")
                             (device "/dev/vda1")
                             (type "ext4"))
                            %base-file-systems))
        (services
         (append (list (service dhcp-client-service-type)
                       (service openssh-service-type
                                (openssh-configuration
                                 (permit-root-login #t)
                                 (allow-empty-passwords? #t))))
                 %base-services))))

     (list (machine
            (operating-system %system)
            (environment managed-host-environment-type)
            (configuration (machine-ssh-configuration
                            (host-name "localhost")
                            (system "x86_64-linux")
                            (user "alice")
                            (identity "./id_rsa")
                            (port 2222)))))

   The file should evaluate to a list of MACHINE objects.  This example,
upon being deployed, will create a new generation on the remote system
realizing the ‘operating-system’ declaration ‘%system’.  ‘environment’
and ‘configuration’ specify how the machine should be provisioned—that
is, how the computing resources should be created and managed.  The
above example does not create any resources, as a ‘'managed-host’ is a
machine that is already running the Guix system and available over the
network.  This is a particularly simple case; a more complex deployment
may involve, for example, starting virtual machines through a Virtual
Private Server (VPS) provider.  In such a case, a different ENVIRONMENT
type would be used.

   Do note that you first need to generate a key pair on the coordinator
machine to allow the daemon to export signed archives of files from the
store (*note Invoking guix archive::), though this step is automatic on
Guix System:

     # guix archive --generate-key

Each target machine must authorize the key of the master machine so that
it accepts store items it receives from the coordinator:

     # guix archive --authorize < coordinator-public-key.txt

   ‘user’, in this example, specifies the name of the user account to
log in as to perform the deployment.  Its default value is ‘root’, but
root login over SSH may be forbidden in some cases.  To work around
this, ‘guix deploy’ can log in as an unprivileged user and employ ‘sudo’
to escalate privileges.  This will only work if ‘sudo’ is currently
installed on the remote and can be invoked non-interactively as ‘user’.
That is, the line in ‘sudoers’ granting ‘user’ the ability to use ‘sudo’
must contain the ‘NOPASSWD’ tag.  This can be accomplished with the
following operating system configuration snippet:

     (use-modules ...
                  (gnu system))               ;for %sudoers-specification

     (define %user "username")

     (operating-system
       ...
       (sudoers-file
          (plain-file "sudoers"
                      (string-append (plain-file-content %sudoers-specification)
                                     (format #f "~a ALL = NOPASSWD: ALL~%"
                                             %user)))))


   For more information regarding the format of the ‘sudoers’ file,
consult ‘man sudoers’.

   Once you’ve deployed a system on a set of machines, you may find it
useful to run a command on all of them.  The ‘--execute’ or ‘-x’ option
lets you do that; the example below runs ‘uname -a’ on all the machines
listed in the deployment file:

     guix deploy FILE -x -- uname -a

   One thing you may often need to do after deployment is restart
specific services on all the machines, which you can do like so:

     guix deploy FILE -x -- herd restart SERVICE

   The ‘guix deploy -x’ command returns zero if and only if the command
succeeded on all the machines.

   Below are the data types you need to know about when writing a
deployment file.

 -- Data Type: machine
     This is the data type representing a single machine in a
     heterogeneous Guix deployment.

     ‘operating-system’
          The object of the operating system configuration to deploy.

     ‘environment’
          An ‘environment-type’ describing how the machine should be
          provisioned.

     ‘configuration’ (default: ‘#f’)
          An object describing the configuration for the machine’s
          ‘environment’.  If the ‘environment’ has a default
          configuration, ‘#f’ may be used.  If ‘#f’ is used for an
          environment with no default configuration, however, an error
          will be thrown.

 -- Data Type: machine-ssh-configuration
     This is the data type representing the SSH client parameters for a
     machine with an ‘environment’ of ‘managed-host-environment-type’.

     ‘host-name’
     ‘build-locally?’ (default: ‘#t’)
          If false, system derivations will be built on the machine
          being deployed to.
     ‘system’
          The system type describing the architecture of the machine
          being deployed to—e.g., ‘"x86_64-linux"’.
     ‘authorize?’ (default: ‘#t’)
          If true, the coordinator’s signing key will be added to the
          remote’s ACL keyring.
     ‘port’ (default: ‘22’)
     ‘user’ (default: ‘"root"’)
     ‘identity’ (default: ‘#f’)
          If specified, the path to the SSH private key to use to
          authenticate with the remote host.

     ‘host-key’ (default: ‘#f’)
          This should be the SSH host key of the machine, which looks
          like this:

               ssh-ed25519 AAAAC3Nz... root@example.org

          When ‘host-key’ is ‘#f’, the server is authenticated against
          the ‘~/.ssh/known_hosts’ file, just like the OpenSSH ‘ssh’
          client does.

     ‘allow-downgrades?’ (default: ‘#f’)
          Whether to allow potential downgrades.

          Like ‘guix system reconfigure’, ‘guix deploy’ compares the
          channel commits currently deployed on the remote host (as
          returned by ‘guix system describe’) to those currently in use
          (as returned by ‘guix describe’) to determine whether commits
          currently in use are descendants of those deployed.  When this
          is not the case and ‘allow-downgrades?’ is false, it raises an
          error.  This ensures you do not accidentally downgrade remote
          machines.

     ‘safety-checks?’ (default: ‘#t’)
          Whether to perform “safety checks” before deployment.  This
          includes verifying that devices and file systems referred to
          in the operating system configuration actually exist on the
          target machine, and making sure that Linux modules required to
          access storage devices at boot time are listed in the
          ‘initrd-modules’ field of the operating system.

          These safety checks ensure that you do not inadvertently
          deploy a system that would fail to boot.  Be careful before
          turning them off!

 -- Data Type: digital-ocean-configuration
     This is the data type describing the Droplet that should be created
     for a machine with an ‘environment’ of
     ‘digital-ocean-environment-type’.

     ‘ssh-key’
          The path to the SSH private key to use to authenticate with
          the remote host.  In the future, this field may not exist.
     ‘tags’
          A list of string “tags” that uniquely identify the machine.
          Must be given such that no two machines in the deployment have
          the same set of tags.
     ‘region’
          A Digital Ocean region slug, such as ‘"nyc3"’.
     ‘size’
          A Digital Ocean size slug, such as ‘"s-1vcpu-1gb"’
     ‘enable-ipv6?’
          Whether or not the droplet should be created with IPv6
          networking.

