guix.texi

@end example

The above command, run as @code{root}, lists the currently defined
services.  The @command{herd doc} command shows a synopsis of the given
service and its associated actions:

@example
# herd doc nscd
Run libc's name service cache daemon (nscd).

# herd doc nscd action invalidate
invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.
@end example

The @command{start}, @command{stop}, and @command{restart} sub-commands
have the effect you would expect.  For instance, the commands below stop
the nscd service and restart the Xorg display server:

@example
# herd stop nscd
Service nscd has been stopped.
# herd restart xorg-server
Service xorg-server has been stopped.
Service xorg-server has been started.
@end example

The following sections document the available services, starting with
the core services, that may be used in an @code{operating-system}
declaration.

@menu
* Base Services::               Essential system services.
* Scheduled Job Execution::     The mcron service.
* Log Rotation::                The rottlog service.
* Networking Services::         Network setup, SSH daemon, etc.
* X Window::                    Graphical display.
* Printing Services::           Local and remote printer support.
* Desktop Services::            D-Bus and desktop services.
* Sound Services::              ALSA and Pulseaudio services.
* Database Services::           SQL databases, key-value stores, etc.
* Mail Services::               IMAP, POP3, SMTP, and all that.
* Messaging Services::          Messaging services.
* Telephony Services::          Telephony services.
* Monitoring Services::         Monitoring services.
* Kerberos Services::           Kerberos services.
* LDAP Services::               LDAP services.
* Web Services::                Web servers.
* Certificate Services::        TLS certificates via Let's Encrypt.
* DNS Services::                DNS daemons.
* VPN Services::                VPN daemons.
* Network File System::         NFS related services.
* Continuous Integration::      The Cuirass service.
* Power Management Services::   Extending battery life.
* Audio Services::              The MPD.
* Virtualization Services::     Virtualization services.
* Version Control Services::    Providing remote access to Git repositories.
* Game Services::               Game servers.
* PAM Mount Service::           Service to mount volumes when logging in.
* Guix Services::               Services relating specifically to Guix.
* Miscellaneous Services::      Other services.
@end menu

@node Base Services
@subsection Base Services

The @code{(gnu services base)} module provides definitions for the basic
services that one expects from the system.  The services exported by
this module are listed below.

@defvr {Scheme Variable} %base-services
This variable contains a list of basic services (@pxref{Service Types
and Services}, for more information on service objects) one would
expect from the system: a login service (mingetty) on each tty, syslogd,
the libc name service cache daemon (nscd), the udev device manager, and
more.

This is the default value of the @code{services} field of
@code{operating-system} declarations.  Usually, when customizing a
system, you will want to append services to @code{%base-services}, like
this:

@lisp
(append (list (service avahi-service-type)
              (service openssh-service-type))
        %base-services)
@end lisp
@end defvr

@defvr {Scheme Variable} special-files-service-type
This is the service that sets up ``special files'' such as
@file{/bin/sh}; an instance of it is part of @code{%base-services}.

The value associated with @code{special-files-service-type} services
must be a list of tuples where the first element is the ``special file''
and the second element is its target.  By default it is:

@cindex @file{/bin/sh}
@cindex @file{sh}, in @file{/bin}
@lisp
`(("/bin/sh" ,(file-append bash "/bin/sh")))
@end lisp

@cindex @file{/usr/bin/env}
@cindex @file{env}, in @file{/usr/bin}
If you want to add, say, @code{/usr/bin/env} to your system, you can
change it to:

@lisp
`(("/bin/sh" ,(file-append bash "/bin/sh"))
  ("/usr/bin/env" ,(file-append coreutils "/bin/env")))
@end lisp

Since this is part of @code{%base-services}, you can use
@code{modify-services} to customize the set of special files
(@pxref{Service Reference, @code{modify-services}}).  But the simple way
to add a special file is @i{via} the @code{extra-special-file} procedure
(see below.)
@end defvr

@deffn {Scheme Procedure} extra-special-file @var{file} @var{target}
Use @var{target} as the ``special file'' @var{file}.

For example, adding the following lines to the @code{services} field of
your operating system declaration leads to a @file{/usr/bin/env}
symlink:

@lisp
(extra-special-file "/usr/bin/env"
                    (file-append coreutils "/bin/env"))
@end lisp
@end deffn

@deffn {Scheme Procedure} host-name-service @var{name}
Return a service that sets the host name to @var{name}.
@end deffn

@deffn {Scheme Procedure} login-service @var{config}
Return a service to run login according to @var{config}, a
@code{<login-configuration>} object, which specifies the message of the day,
among other things.
@end deffn

@deftp {Data Type} login-configuration
This is the data type representing the configuration of login.

@table @asis

@item @code{motd}
@cindex message of the day
A file-like object containing the ``message of the day''.

@item @code{allow-empty-passwords?} (default: @code{#t})
Allow empty passwords by default so that first-time users can log in when
the 'root' account has just been created.

@end table
@end deftp

@deffn {Scheme Procedure} mingetty-service @var{config}
Return a service to run mingetty according to @var{config}, a
@code{<mingetty-configuration>} object, which specifies the tty to run, among
other things.
@end deffn

@deftp {Data Type} mingetty-configuration
This is the data type representing the configuration of Mingetty, which
provides the default implementation of virtual console log-in.

@table @asis

@item @code{tty}
The name of the console this Mingetty runs on---e.g., @code{"tty1"}.

@item @code{auto-login} (default: @code{#f})
When true, this field must be a string denoting the user name under
which the system automatically logs in.  When it is @code{#f}, a
user name and password must be entered to log in.

@item @code{login-program} (default: @code{#f})
This must be either @code{#f}, in which case the default log-in program
is used (@command{login} from the Shadow tool suite), or a gexp denoting
the name of the log-in program.

@item @code{login-pause?} (default: @code{#f})
When set to @code{#t} in conjunction with @var{auto-login}, the user
will have to press a key before the log-in shell is launched.

@item @code{mingetty} (default: @var{mingetty})
The Mingetty package to use.

@end table
@end deftp

@deffn {Scheme Procedure} agetty-service @var{config}
Return a service to run agetty according to @var{config}, an
@code{<agetty-configuration>} object, which specifies the tty to run,
among other things.
@end deffn

@deftp {Data Type} agetty-configuration
This is the data type representing the configuration of agetty, which
implements virtual and serial console log-in.  See the @code{agetty(8)}
man page for more information.

@table @asis

@item @code{tty}
The name of the console this agetty runs on, as a string---e.g.,
@code{"ttyS0"}. This argument is optional, it will default to
a reasonable default serial port used by the kernel Linux.

For this, if there is a value for an option @code{agetty.tty} in the kernel
command line, agetty will extract the device name of the serial port
from it and use that.

If not and if there is a value for an option @code{console} with a tty in
the Linux command line, agetty will extract the device name of the
serial port from it and use that.

In both cases, agetty will leave the other serial device settings
(baud rate etc.)@: alone---in the hope that Linux pinned them to the
correct values.

@item @code{baud-rate} (default: @code{#f})
A string containing a comma-separated list of one or more baud rates, in
descending order.

@item @code{term} (default: @code{#f})
A string containing the value used for the @code{TERM} environment
variable.

@item @code{eight-bits?} (default: @code{#f})
When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection is
disabled.

@item @code{auto-login} (default: @code{#f})
When passed a login name, as a string, the specified user will be logged
in automatically without prompting for their login name or password.

@item @code{no-reset?} (default: @code{#f})
When @code{#t}, don't reset terminal cflags (control modes).

@item @code{host} (default: @code{#f})
This accepts a string containing the "login_host", which will be written
into the @file{/var/run/utmpx} file.

@item @code{remote?} (default: @code{#f})
When set to @code{#t} in conjunction with @var{host}, this will add an
@code{-r} fakehost option to the command line of the login program
specified in @var{login-program}.

@item @code{flow-control?} (default: @code{#f})
When set to @code{#t}, enable hardware (RTS/CTS) flow control.

@item @code{no-issue?} (default: @code{#f})
When set to @code{#t}, the contents of the @file{/etc/issue} file will
not be displayed before presenting the login prompt.

@item @code{init-string} (default: @code{#f})
This accepts a string that will be sent to the tty or modem before
sending anything else.  It can be used to initialize a modem.

@item @code{no-clear?} (default: @code{#f})
When set to @code{#t}, agetty will not clear the screen before showing
the login prompt.

@item @code{login-program} (default: (file-append shadow "/bin/login"))
This must be either a gexp denoting the name of a log-in program, or
unset, in which case the default value is the @command{login} from the
Shadow tool suite.

@item @code{local-line} (default: @code{#f})
Control the CLOCAL line flag.  This accepts one of three symbols as
arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f},
the default value chosen by agetty is @code{'auto}.

@item @code{extract-baud?} (default: @code{#f})
When set to @code{#t}, instruct agetty to try to extract the baud rate
from the status messages produced by certain types of modems.

@item @code{skip-login?} (default: @code{#f})
When set to @code{#t}, do not prompt the user for a login name.  This
can be used with @var{login-program} field to use non-standard login
systems.

@item @code{no-newline?} (default: @code{#f})
When set to @code{#t}, do not print a newline before printing the
@file{/etc/issue} file.

@c Is this dangerous only when used with login-program, or always?
@item @code{login-options} (default: @code{#f})
This option accepts a string containing options that are passed to the
login program.  When used with the @var{login-program}, be aware that a
malicious user could try to enter a login name containing embedded
options that could be parsed by the login program.

@item @code{login-pause} (default: @code{#f})
When set to @code{#t}, wait for any key before showing the login prompt.
This can be used in conjunction with @var{auto-login} to save memory by
lazily spawning shells.

@item @code{chroot} (default: @code{#f})
Change root to the specified directory.  This option accepts a directory
path as a string.

@item @code{hangup?} (default: @code{#f})
Use the Linux system call @code{vhangup} to do a virtual hangup of the
specified terminal.

@item @code{keep-baud?} (default: @code{#f})
When set to @code{#t}, try to keep the existing baud rate.  The baud
rates from @var{baud-rate} are used when agetty receives a @key{BREAK}
character.

@item @code{timeout} (default: @code{#f})
When set to an integer value, terminate if no user name could be read
within @var{timeout} seconds.

@item @code{detect-case?} (default: @code{#f})
When set to @code{#t}, turn on support for detecting an uppercase-only
terminal.  This setting will detect a login name containing only
uppercase letters as indicating an uppercase-only terminal and turn on
some upper-to-lower case conversions.  Note that this will not support
Unicode characters.

@item @code{wait-cr?} (default: @code{#f})
When set to @code{#t}, wait for the user or modem to send a
carriage-return or linefeed character before displaying
@file{/etc/issue} or login prompt.  This is typically used with the
@var{init-string} option.

@item @code{no-hints?} (default: @code{#f})
When set to @code{#t}, do not print hints about Num, Caps, and Scroll
locks.

@item @code{no-hostname?} (default: @code{#f})
By default, the hostname is printed.  When this option is set to
@code{#t}, no hostname will be shown at all.

@item @code{long-hostname?} (default: @code{#f})
By default, the hostname is only printed until the first dot.  When this
option is set to @code{#t}, the fully qualified hostname by
@code{gethostname} or @code{getaddrinfo} is shown.

@item @code{erase-characters} (default: @code{#f})
This option accepts a string of additional characters that should be
interpreted as backspace when the user types their login name.

@item @code{kill-characters} (default: @code{#f})
This option accepts a string that should be interpreted to mean "ignore
all previous characters" (also called a "kill" character) when the user
types their login name.

@item @code{chdir} (default: @code{#f})
This option accepts, as a string, a directory path that will be changed
to before login.

@item @code{delay} (default: @code{#f})
This options accepts, as an integer, the number of seconds to sleep
before opening the tty and displaying the login prompt.

@item @code{nice} (default: @code{#f})
This option accepts, as an integer, the nice value with which to run the
@command{login} program.

@item @code{extra-options} (default: @code{'()})
This option provides an "escape hatch" for the user to provide arbitrary
command-line arguments to @command{agetty} as a list of strings.

@end table
@end deftp

@deffn {Scheme Procedure} kmscon-service-type @var{config}
Return a service to run @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}
according to @var{config}, a @code{<kmscon-configuration>} object, which
specifies the tty to run, among other things.
@end deffn

@deftp {Data Type} kmscon-configuration
This is the data type representing the configuration of Kmscon, which
implements virtual console log-in.

@table @asis

@item @code{virtual-terminal}
The name of the console this Kmscon runs on---e.g., @code{"tty1"}.

@item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
A gexp denoting the name of the log-in program. The default log-in program is
@command{login} from the Shadow tool suite.

@item @code{login-arguments} (default: @code{'("-p")})
A list of arguments to pass to @command{login}.

@item @code{auto-login} (default: @code{#f})
When passed a login name, as a string, the specified user will be logged
in automatically without prompting for their login name or password.

@item @code{hardware-acceleration?} (default: #f)
Whether to use hardware acceleration.

@item @code{kmscon} (default: @var{kmscon})
The Kmscon package to use.

@end table
@end deftp

@cindex name service cache daemon
@cindex nscd
@deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
                [#:name-services '()]
Return a service that runs the libc name service cache daemon (nscd) with the
given @var{config}---an @code{<nscd-configuration>} object.  @xref{Name
Service Switch}, for an example.

For convenience, the Shepherd service for nscd provides the following actions:

@table @code
@item invalidate
@cindex cache invalidation, nscd
@cindex nscd, cache invalidation
This invalidate the given cache.  For instance, running:

@example
herd invalidate nscd hosts
@end example

@noindent
invalidates the host name lookup cache of nscd.

@item statistics
Running @command{herd statistics nscd} displays information about nscd usage
and caches.
@end table

@end deffn

@defvr {Scheme Variable} %nscd-default-configuration
This is the default @code{<nscd-configuration>} value (see below) used
by @code{nscd-service}.  It uses the caches defined by
@var{%nscd-default-caches}; see below.
@end defvr

@deftp {Data Type} nscd-configuration
This is the data type representing the name service cache daemon (nscd)
configuration.

@table @asis

@item @code{name-services} (default: @code{'()})
List of packages denoting @dfn{name services} that must be visible to
the nscd---e.g., @code{(list @var{nss-mdns})}.

@item @code{glibc} (default: @var{glibc})
Package object denoting the GNU C Library providing the @command{nscd}
command.

@item @code{log-file} (default: @code{"/var/log/nscd.log"})
Name of the nscd log file.  This is where debugging output goes when
@code{debug-level} is strictly positive.

@item @code{debug-level} (default: @code{0})
Integer denoting the debugging levels.  Higher numbers mean that more
debugging output is logged.

@item @code{caches} (default: @var{%nscd-default-caches})
List of @code{<nscd-cache>} objects denoting things to be cached; see
below.

@end table
@end deftp

@deftp {Data Type} nscd-cache
Data type representing a cache database of nscd and its parameters.

@table @asis

@item @code{database}
This is a symbol representing the name of the database to be cached.
Valid values are @code{passwd}, @code{group}, @code{hosts}, and
@code{services}, which designate the corresponding NSS database
(@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).

@item @code{positive-time-to-live}
@itemx @code{negative-time-to-live} (default: @code{20})
A number representing the number of seconds during which a positive or
negative lookup result remains in cache.

@item @code{check-files?} (default: @code{#t})
Whether to check for updates of the files corresponding to
@var{database}.

For instance, when @var{database} is @code{hosts}, setting this flag
instructs nscd to check for updates in @file{/etc/hosts} and to take
them into account.

@item @code{persistent?} (default: @code{#t})
Whether the cache should be stored persistently on disk.

@item @code{shared?} (default: @code{#t})
Whether the cache should be shared among users.

@item @code{max-database-size} (default: 32@tie{}MiB)
Maximum size in bytes of the database cache.

@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
@c settings, so leave them out.

@end table
@end deftp

@defvr {Scheme Variable} %nscd-default-caches
List of @code{<nscd-cache>} objects used by default by
@code{nscd-configuration} (see above).

It enables persistent and aggressive caching of service and host name
lookups.  The latter provides better host name lookup performance,
resilience in the face of unreliable name servers, and also better
privacy---often the result of host name lookups is in local cache, so
external name servers do not even need to be queried.
@end defvr

@anchor{syslog-configuration-type}
@cindex syslog
@cindex logging
@deftp {Data Type} syslog-configuration
This data type represents the configuration of the syslog daemon.

@table @asis
@item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")})
The syslog daemon to use.

@item @code{config-file} (default: @code{%default-syslog.conf})
The syslog configuration file to use.

@end table
@end deftp

@anchor{syslog-service}
@cindex syslog
@deffn {Scheme Procedure} syslog-service @var{config}
Return a service that runs a syslog daemon according to @var{config}.

@xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more
information on the configuration file syntax.
@end deffn

@defvr {Scheme Variable} guix-service-type
This is the type of the service that runs the build daemon,
@command{guix-daemon} (@pxref{Invoking guix-daemon}).  Its value must be a
@code{guix-configuration} record as described below.
@end defvr

@anchor{guix-configuration-type}
@deftp {Data Type} guix-configuration
This data type represents the configuration of the Guix build daemon.
@xref{Invoking guix-daemon}, for more information.

@table @asis
@item @code{guix} (default: @var{guix})
The Guix package to use.

@item @code{build-group} (default: @code{"guixbuild"})
Name of the group for build user accounts.

@item @code{build-accounts} (default: @code{10})
Number of build user accounts to create.

@item @code{authorize-key?} (default: @code{#t})
@cindex substitutes, authorization thereof
Whether to authorize the substitute keys listed in
@code{authorized-keys}---by default that of @code{@value{SUBSTITUTE-SERVER}}
(@pxref{Substitutes}).

@vindex %default-authorized-guix-keys
@item @code{authorized-keys} (default: @code{%default-authorized-guix-keys})
The list of authorized key files for archive imports, as a list of
string-valued gexps (@pxref{Invoking guix archive}).  By default, it
contains that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitutes}).

@item @code{use-substitutes?} (default: @code{#t})
Whether to use substitutes.

@item @code{substitute-urls} (default: @code{%default-substitute-urls})
The list of URLs where to look for substitutes by default.

@item @code{max-silent-time} (default: @code{0})
@itemx @code{timeout} (default: @code{0})
The number of seconds of silence and the number of seconds of activity,
respectively, after which a build process times out.  A value of zero
disables the timeout.

@item @code{log-compression} (default: @code{'bzip2})
The type of compression used for build logs---one of @code{gzip},
@code{bzip2}, or @code{none}.

@item @code{extra-options} (default: @code{'()})
List of extra command-line options for @command{guix-daemon}.

@item @code{log-file} (default: @code{"/var/log/guix-daemon.log"})
File where @command{guix-daemon}'s standard output and standard error
are written.

@item @code{http-proxy} (default: @code{#f})
The HTTP proxy used for downloading fixed-output derivations and
substitutes.

@item @code{tmpdir} (default: @code{#f})
A directory path where the @command{guix-daemon} will perform builds.

@end table
@end deftp

@deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
Run @var{udev}, which populates the @file{/dev} directory dynamically.
udev rules can be provided as a list of files through the @var{rules}
variable.  The procedures @code{udev-rule} and @code{file->udev-rule} from
@code{(gnu services base)} simplify the creation of such rule files.
@end deffn

@deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}]
Return a udev-rule file named @var{file-name} containing the rules
defined by the @var{contents} literal.

In the following example, a rule for a USB device is defined to be
stored in the file @file{90-usb-thing.rules}.  The rule runs a script
upon detecting a USB device with a given product identifier.

@lisp
(define %example-udev-rule
  (udev-rule
    "90-usb-thing.rules"
    (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
                   "ATTR@{product@}==\"Example\", "
                   "RUN+=\"/path/to/script\"")))
@end lisp

The @command{herd rules udev} command, as root, returns the name of the
directory containing all the active udev rules.
@end deffn

Here we show how the default @var{udev-service} can be extended with it.

@lisp
(operating-system
 ;; @dots{}
 (services
 (modify-services %desktop-services
   (udev-service-type config =>
     (udev-configuration (inherit config)
      (rules (append (udev-configuration-rules config)
                     (list %example-udev-rule))))))))
@end lisp

@deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}]
Return a udev file named @var{file-name} containing the rules defined
within @var{file}, a file-like object.

The following example showcases how we can use an existing rule file.

@lisp
(use-modules (guix download)     ;for url-fetch
             (guix packages)     ;for origin
             @dots{})

(define %android-udev-rules
  (file->udev-rule
    "51-android-udev.rules"
    (let ((version "20170910"))
      (origin
       (method url-fetch)
       (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
                           "android-udev-rules/" version "/51-android.rules"))
       (sha256
        (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))
@end lisp
@end deffn

Additionally, Guix package definitions can be included in @var{rules} in
order to extend the udev rules with the definitions found under their
@file{lib/udev/rules.d} sub-directory.  In lieu of the previous
@var{file->udev-rule} example, we could have used the
@var{android-udev-rules} package which exists in Guix in the @code{(gnu
packages android)} module.

The following example shows how to use the @var{android-udev-rules}
package so that the Android tool @command{adb} can detect devices
without root privileges.  It also details how to create the
@code{adbusers} group, which is required for the proper functioning of
the rules defined within the @var{android-udev-rules} package.  To
create such a group, we must define it both as part of the
@var{supplementary-groups} of our @var{user-account} declaration, as
well as in the @var{groups} field of the @var{operating-system} record.

@lisp
(use-modules (gnu packages android)  ;for android-udev-rules
             (gnu system shadow)     ;for user-group
             @dots{})

(operating-system
  ;; @dots{}
  (users (cons (user-acount
                ;; @dots{}
                (supplementary-groups
                 '("adbusers"   ;for adb
                   "wheel" "netdev" "audio" "video")))))

  (groups (cons (user-group (system? #t) (name "adbusers"))
                %base-groups))

  ;; @dots{}

  (services
   (modify-services %desktop-services
     (udev-service-type
      config =>
      (udev-configuration (inherit config)
                          (rules (cons android-udev-rules
                                       (udev-configuration-rules config))))))))
@end lisp

@defvr {Scheme Variable} urandom-seed-service-type
Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom}
when rebooting.  It also tries to seed @file{/dev/urandom} from
@file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is
readable.
@end defvr

@defvr {Scheme Variable} %random-seed-file
This is the name of the file where some random bytes are saved by
@var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting.
It defaults to @file{/var/lib/random-seed}.
@end defvr

@cindex mouse
@cindex gpm
@defvr {Scheme Variable} gpm-service-type
This is the type of the service that runs GPM, the @dfn{general-purpose
mouse daemon}, which provides mouse support to the Linux console.  GPM
allows users to use the mouse in the console, notably to select, copy,
and paste text.

The value for services of this type must be a @code{gpm-configuration}
(see below).  This service is not part of @code{%base-services}.
@end defvr

@deftp {Data Type} gpm-configuration
Data type representing the configuration of GPM.

@table @asis
@item @code{options} (default: @code{%default-gpm-options})
Command-line options passed to @command{gpm}.  The default set of
options instruct @command{gpm} to listen to mouse events on
@file{/dev/input/mice}.  @xref{Command Line,,, gpm, gpm manual}, for
more information.

@item @code{gpm} (default: @code{gpm})
The GPM package to use.

@end table
@end deftp

@anchor{guix-publish-service-type}
@deffn {Scheme Variable} guix-publish-service-type
This is the service type for @command{guix publish} (@pxref{Invoking
guix publish}).  Its value must be a @code{guix-publish-configuration}
object, as described below.

This assumes that @file{/etc/guix} already contains a signing key pair as
created by @command{guix archive --generate-key} (@pxref{Invoking guix
archive}).  If that is not the case, the service will fail to start.
@end deffn

@deftp {Data Type} guix-publish-configuration
Data type representing the configuration of the @code{guix publish}
service.

@table @asis
@item @code{guix} (default: @code{guix})
The Guix package to use.

@item @code{port} (default: @code{80})
The TCP port to listen for connections.

@item @code{host} (default: @code{"localhost"})
The host (and thus, network interface) to listen to.  Use
@code{"0.0.0.0"} to listen on all the network interfaces.

@item @code{compression} (default: @code{'(("gzip" 3))})
This is a list of compression method/level tuple used when compressing
substitutes.  For example, to compress all substitutes with @emph{both} lzip
at level 7 and gzip at level 9, write:

@lisp
'(("lzip" 7) ("gzip" 9))
@end lisp

Level 9 achieves the best compression ratio at the expense of increased CPU
usage, whereas level 1 achieves fast compression.

An empty list disables compression altogether.

@item @code{nar-path} (default: @code{"nar"})
The URL path at which ``nars'' can be fetched.  @xref{Invoking guix
publish, @code{--nar-path}}, for details.

@item @code{cache} (default: @code{#f})
When it is @code{#f}, disable caching and instead generate archives on
demand.  Otherwise, this should be the name of a directory---e.g.,
@code{"/var/cache/guix/publish"}---where @command{guix publish} caches
archives and meta-data ready to be sent.  @xref{Invoking guix publish,
@option{--cache}}, for more information on the tradeoffs involved.

@item @code{workers} (default: @code{#f})
When it is an integer, this is the number of worker threads used for
caching; when @code{#f}, the number of processors is used.
@xref{Invoking guix publish, @option{--workers}}, for more information.

@item @code{ttl} (default: @code{#f})
When it is an integer, this denotes the @dfn{time-to-live} in seconds
of the published archives.  @xref{Invoking guix publish, @option{--ttl}},
for more information.
@end table
@end deftp

@anchor{rngd-service}
@deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @
            [#:device "/dev/hwrng"]
Return a service that runs the @command{rngd} program from @var{rng-tools}
to add @var{device} to the kernel's entropy pool.  The service will fail if
@var{device} does not exist.
@end deffn

@anchor{pam-limits-service}
@cindex session limits
@cindex ulimit
@cindex priority
@cindex realtime
@cindex jackd
@deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]

Return a service that installs a configuration file for the
@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,
@code{pam_limits} module}.  The procedure optionally takes a list of
@code{pam-limits-entry} values, which can be used to specify
@code{ulimit} limits and nice priority limits to user sessions.

The following limits definition sets two hard and soft limits for all
login sessions of users in the @code{realtime} group:

@lisp
(pam-limits-service
 (list
  (pam-limits-entry "@@realtime" 'both 'rtprio 99)
  (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited)))
@end lisp

The first entry increases the maximum realtime priority for
non-privileged processes; the second entry lifts any restriction of the
maximum address space that can be locked in memory.  These settings are
commonly used for real-time audio systems.
@end deffn

@node Scheduled Job Execution
@subsection Scheduled Job Execution

@cindex cron
@cindex mcron
@cindex scheduling jobs
The @code{(gnu services mcron)} module provides an interface to
GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
mcron, GNU@tie{}mcron}).  GNU@tie{}mcron is similar to the traditional
Unix @command{cron} daemon; the main difference is that it is
implemented in Guile Scheme, which provides a lot of flexibility when
specifying the scheduling of jobs and their actions.

The example below defines an operating system that runs the
@command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files})
and the @command{guix gc} commands (@pxref{Invoking guix gc}) daily, as
well as the @command{mkid} command on behalf of an unprivileged user
(@pxref{mkid invocation,,, idutils, ID Database Utilities}).  It uses
gexps to introduce job definitions that are passed to mcron
(@pxref{G-Expressions}).

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

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

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

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

(operating-system
  ;; @dots{}
  (services (cons (service mcron-service-type
                           (mcron-configuration
                            (jobs (list garbage-collector-job
                                        updatedb-job
                                        idutils-job))))
                  %base-services)))
@end lisp

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

@lisp
(define %battery-alert-job
  ;; Beep when the battery percentage falls below %MIN-LEVEL.
  #~(job
     '(next-minute (range 0 60 1))
     #$(program-file
        "battery-alert.scm"
        (with-imported-modules (source-module-closure
                                '((guix build utils)))
          #~(begin
              (define %min-level 20)
              (use-modules (guix build utils)
                           (ice-9 popen)
                           (ice-9 regex)
                           (ice-9 textual-ports)
                           (srfi srfi-2))
              (setenv "LC_ALL" "C")     ;ensure English output
              (and-let* ((input-pipe (open-pipe*
                                      OPEN_READ
                                      #$(file-append acpi "/bin/acpi")))
                         (output (get-string-all input-pipe))
                         (m (string-match "Discharging, ([0-9]+)%" output))
                         (level (string->number (match:substring m 1)))
                         ((< level %min-level)))
                (format #t "warning: Battery level is low (~a%)~%" level)
                (invoke #$(file-append beep "/bin/beep") "-r5")))))))
@end lisp

@xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron},
for more information on mcron job specifications.  Below is the
reference of the mcron service.

On a running system, you can use the @code{schedule} action of the service to
visualize the mcron jobs that will be executed next:

@example
# herd schedule mcron
@end example

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

@example
# herd schedule mcron 10
@end example

@defvr {Scheme Variable} mcron-service-type
This is the type of the @code{mcron} service, whose value is an
@code{mcron-configuration} object.

This service type can be the target of a service extension that provides
it additional job specifications (@pxref{Service Composition}).  In
other words, it is possible to define services that provide additional
mcron jobs to run.
@end defvr

@deftp {Data Type} mcron-configuration
Data type representing the configuration of mcron.

@table @asis
@item @code{mcron} (default: @var{mcron})
The mcron package to use.

@item @code{jobs}
This is a list of gexps (@pxref{G-Expressions}), where each gexp
corresponds to an mcron job specification (@pxref{Syntax, mcron job
specifications,, mcron, GNU@tie{}mcron}).
@end table
@end deftp


@node Log Rotation
@subsection Log Rotation