guix.texi

@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout
Maximum time to wait for lock (all of them) before aborting.
Defaults to @samp{"5 mins"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout
If dotlock exists but the mailbox isn't modified in any way,
override the lock file after this much time.
Defaults to @samp{"2 mins"}.
@end deftypevr

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

@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs?
Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
EXAMINE, EXPUNGE or CHECK commands.  If this is set,
@samp{mbox-dirty-syncs} is ignored.
Defaults to @samp{#f}.
@end deftypevr

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

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size
If mbox size is smaller than this (e.g. 100k), don't write index
files.  If an index file already exists it's still read, just not
updated.
Defaults to @samp{0}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size
Maximum dbox file size until it's rotated.
Defaults to @samp{2000000}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval
Maximum dbox file age until it's rotated.  Typically in days.  Day
begins from midnight, so 1d = today, 2d = yesterday, etc.  0 = check
disabled.
Defaults to @samp{"1d"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space?
When creating new mdbox files, immediately preallocate their size to
@samp{mdbox-rotate-size}.  This setting currently works only in Linux
with some file systems (ext4, xfs).
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir
sdbox and mdbox support saving mail attachments to external files,
which also allows single instance storage for them.  Other backends
don't support this for now.

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

Directory root where to store mail attachments.  Disabled, if empty.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size
Attachments smaller than this aren't saved externally.  It's also
possible to write a plugin to disable saving specific attachments
externally.
Defaults to @samp{128000}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs
File system backend to use for saving attachments:
@table @code
@item posix
No SiS done by Dovecot (but this might help FS's own deduplication)
@item sis posix
SiS with immediate byte-by-byte comparison during saving
@item sis-queue posix
SiS with delayed comparison and deduplication.
@end table
Defaults to @samp{"sis posix"}.
@end deftypevr

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

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit

Defaults to @samp{100}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit

Defaults to @samp{1000}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit
Default VSZ (virtual memory size) limit for service processes.
This is mainly intended to catch and kill processes that leak memory
before they eat up everything.
Defaults to @samp{256000000}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string default-login-user
Login user is internally used by login processes.  This is the most
untrusted user in Dovecot system.  It shouldn't have access to anything
at all.
Defaults to @samp{"dovenull"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string default-internal-user
Internal user is used by unprivileged processes.  It should be
separate from login user, so that login processes can't disturb other
processes.
Defaults to @samp{"dovecot"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl?
SSL/TLS support: yes, no, required.  <doc/wiki/SSL.txt>.
Defaults to @samp{"required"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert
PEM encoded X.509 SSL/TLS certificate (public key).
Defaults to @samp{"</etc/dovecot/default.pem"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-key
PEM encoded SSL/TLS private key.  The key is opened before
dropping root privileges, so keep the key file unreadable by anyone but
root.
Defaults to @samp{"</etc/dovecot/private/default.pem"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password
If key file is password protected, give the password here.
Alternatively give it when starting dovecot with -p parameter.  Since
this file is often world-readable, you may want to place this setting
instead to a different.
Defaults to @samp{""}.
@end deftypevr

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

@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl?
Require that CRL check succeeds for client certificates.
Defaults to @samp{#t}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert?
Request client to send a certificate.  If you also want to require
it, set @samp{auth-ssl-require-client-cert? #t} in auth section.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field
Which field from certificate to use for username.  commonName and
x500UniqueIdentifier are the usual choices.  You'll also need to set
@samp{auth-ssl-username-from-cert? #t}.
Defaults to @samp{"commonName"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} hours ssl-parameters-regenerate
How often to regenerate the SSL parameters file.  Generation is
quite CPU intensive operation.  The value is in hours, 0 disables
regeneration entirely.
Defaults to @samp{168}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-protocols
SSL protocols to use.
Defaults to @samp{"!SSLv2"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list
SSL ciphers to use.
Defaults to @samp{"ALL:!LOW:!SSLv2:!EXP:!aNULL"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device
SSL crypto device to use, for valid values run "openssl engine".
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string postmaster-address
Address to use when sending rejection mails.
%d expands to recipient domain.
Defaults to @samp{"postmaster@@%d"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string hostname
Hostname to use in various parts of sent mails (e.g. in Message-Id)
and in LMTP replies.  Default is the system's real hostname@@domain.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail?
If user is over quota, return with temporary failure instead of
bouncing the mail.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path
Binary to use for sending mails.
Defaults to @samp{"/usr/sbin/sendmail"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string submission-host
If non-empty, send mails via this SMTP host[:port] instead of
sendmail.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string rejection-subject
Subject: header to use for rejection mails.  You can use the same
variables as for @samp{rejection-reason} below.
Defaults to @samp{"Rejected: %s"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string rejection-reason
Human readable error message for rejection mails.  You can use
variables:

@table @code
@item %n
CRLF
@item %r
reason
@item %s
original subject
@item %t
recipient
@end table
Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter
Delimiter character between local-part and detail in email
address.
Defaults to @samp{"+"}.
@end deftypevr

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

@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate?
Should saving a mail to a nonexistent mailbox automatically create
it?.
Defaults to @samp{#f}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe?
Should automatically created mailboxes be also automatically
subscribed?.
Defaults to @samp{#f}.
@end deftypevr

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

@deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format
IMAP logout format string:
@table @code
@item %i
total number of bytes read from client
@item %o
total number of bytes sent to client.
@end table
Defaults to @samp{"in=%i out=%o"}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string imap-capability
Override the IMAP CAPABILITY response.  If the value begins with '+',
add the given capabilities on top of the defaults (e.g. +XFOO XBAR).
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval
How long to wait between "OK Still here" notifications when client
is IDLEing.
Defaults to @samp{"2 mins"}.
@end deftypevr

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

@deftypevr {@code{dovecot-configuration} parameter} string imap-id-log
ID fields sent by client to log.  * means everything.
Defaults to @samp{""}.
@end deftypevr

@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds
Workarounds for various client bugs:

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

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

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

@deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host
Host allowed in URLAUTH URLs sent by client.  "*" allows all.
Defaults to @samp{""}.
@end deftypevr


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

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

Available @code{opaque-dovecot-configuration} fields are:

@deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot
The dovecot package.
@end deftypevr

@deftypevr {@code{opaque-dovecot-configuration} parameter} string string
The contents of the @code{dovecot.conf}, as a string.
@end deftypevr

For example, if your @code{dovecot.conf} is just the empty string, you
could instantiate a dovecot service like this:

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

@node Web Services
@subsubsection Web Services

The @code{(gnu services web)} module provides the following service:

@deffn {Scheme Procedure} nginx-service [#:nginx nginx] @
       [#:log-directory ``/var/log/nginx''] @
       [#:run-directory ``/var/run/nginx''] @
       [#:vhost-list (list (nginx-vhost-configuration))] @
       [#:config-file]

Return a service that runs @var{nginx}, the nginx web server.

The nginx daemon loads its runtime configuration from @var{config-file}.
Log files are written to @var{log-directory} and temporary runtime data
files are written to @var{run-directory}.  For proper operation, these
arguments should match what is in @var{config-file} to ensure that the
directories are created when the service is activated.

As an alternative to using a @var{config-file}, @var{vhost-list} can be
used to specify the list of @dfn{virtual hosts} required on the host.  For
this to work, use the default value for @var{config-file}.

@end deffn

@deftp {Data Type} nginx-vhost-configuration
Data type representing the configuration of an nginx virtual host.
This type has the following parameters:

@table @asis
@item @code{http-port} (default: @code{80})
Nginx will listen for HTTP connection on this port.  Set it at @code{#f} if
nginx should not listen for HTTP (non secure) connection for this
@dfn{virtual host}.

@item @code{https-port} (default: @code{443})
Nginx will listen for HTTPS connection on this port.  Set it at @code{#f} if
nginx should not listen for HTTPS (secure) connection for this @dfn{virtual host}.

Note that nginx can listen for HTTP and HTTPS connections in the same
@dfn{virtual host}.

@item @code{server-name} (default: @code{(list 'default)})
A list of server names this vhost represents. @code{'default} represents the
default vhost for connections matching no other vhost.

@item @code{root} (default: @code{"/srv/http"})
Root of the website nginx will serve.

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

@item @code{ssl-certificate} (default: @code{"/etc/nginx/cert.pem"})
Where to find the certificate for secure connections.  Set it to @code{#f} if
you don't have a certificate or you don't want to use HTTPS.

@item @code{ssl-certificate-key} (default: @code{"/etc/nginx/key.pem"})
Where to find the private key for secure connections.  Set it to @code{#f} if
you don't have a key or you don't want to use HTTPS.

@item @code{server-tokens?} (default: @code{#f})
Whether the server should add its configuration to response.

@end table
@end deftp

@node Network File System
@subsubsection Network File System
@cindex NFS

The @code{(gnu services nfs)} module provides the following services,
which are most commonly used in relation to mounting or exporting
directory trees as @dfn{network file systems} (NFS).

@subsubheading RPC Bind Service
@cindex rpcbind

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.

@defvr {Scheme Variable} rpcbind-service-type
A service type  for the RPC portmapper daemon.
@end defvr


@deftp {Data Type} rpcbind-configuration
Data type representing the configuration of the RPC Bind Service.
This type has the following parameters:
@table @asis
@item @code{rpcbind} (default: @code{rpcbind})
The rpcbind package to use.

@item @code{warm-start?} (default: @code{#t})
If this parameter is @code{#t}, then the daemon will read a
state file on startup thus reloading state information saved by a previous
instance.
@end table
@end deftp


@subsubheading Pipefs Pseudo File System
@cindex pipefs
@cindex rpc_pipefs

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

@defvr {Scheme Variable} pipefs-service-type
A service type for the pipefs pseudo file system.
@end defvr

@deftp {Data Type} pipefs-configuration
Data type representing the configuration of the pipefs pseudo file system service.
This type has the following parameters:
@table @asis
@item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"})
The directory to which the file system is to be attached.
@end table
@end deftp


@subsubheading GSS Daemon Service
@cindex GSSD
@cindex GSS
@cindex global security system

The @dfn{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 @command{kinit}
or automatically at login time using PAM services.

@defvr {Scheme Variable} gss-service-type
A service type for the Global Security System (GSS) daemon.
@end defvr

@deftp {Data Type} gss-configuration
Data type representing the configuration of the GSS daemon service.
This type has the following parameters:
@table @asis
@item @code{nfs-utils} (default: @code{nfs-utils})
The package in which the @command{rpc.gssd} command is to be found.

@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
The directory where the pipefs file system is mounted.

@end table
@end deftp


@subsubheading IDMAP Daemon Service
@cindex idmapd
@cindex name mapper

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.

@defvr {Scheme Variable} idmap-service-type
A service type for the Identity Mapper (IDMAP) daemon.
@end defvr

@deftp {Data Type} idmap-configuration
Data type representing the configuration of the IDMAP daemon service.
This type has the following parameters:
@table @asis
@item @code{nfs-utils} (default: @code{nfs-utils})
The package in which the @command{rpc.idmapd} command is to be found.

@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
The directory where the pipefs file system is mounted.

@item @code{domain} (default: @code{#f})
The local NFSv4 domain name.
This must be a string or @code{#f}.
If it is @code{#f} then the daemon will use the host's fully qualified domain name.

@end table
@end deftp


@node Miscellaneous Services
@subsubsection Miscellaneous Services


@cindex lirc
@subsubheading Lirc Service

The @code{(gnu services lirc)} module provides the following service.

@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
       [#:device #f] [#:driver #f] [#:config-file #f] @
       [#:extra-options '()]
Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
decodes infrared signals from remote controls.

Optionally, @var{device}, @var{driver} and @var{config-file}
(configuration file name) may be specified.  See @command{lircd} manual
for details.

Finally, @var{extra-options} is a list of additional command-line options
passed to @command{lircd}.
@end deffn

@cindex spice
@subsubheading Spice Service

The @code{(gnu services spice)} module provides the following service.

@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent]
Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a daemon
that enables sharing the clipboard with a vm and setting the guest display
resolution when the graphical console window resizes.
@end deffn

@subsubsection Dictionary Services
The @code{(gnu services dict)} module provides the following service:

@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
Return a service that runs the @command{dicod} daemon, an implementation
of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).

The optional @var{config} argument specifies the configuration for
@command{dicod}, which should be a @code{<dicod-configuration>} object, by
default it serves the GNU Collaborative International Dictonary of English.

You can add @command{open localhost} to your @file{~/.dico} file to make
@code{localhost} the default server for @command{dico} client
(@pxref{Initialization File,,, dico, GNU Dico Manual}).
@end deffn

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

@table @asis
@item @code{dico} (default: @var{dico})
Package object of the GNU Dico dictionary server.

@item @code{interfaces} (default: @var{'("localhost")})
This is the list of IP addresses and ports and possibly socket file
names to listen to (@pxref{Server Settings, @code{listen} directive,,
dico, GNU Dico Manual}).

@item @code{databases} (default: @var{(list %dicod-database:gcide)})
List of @code{<dicod-database>} objects denoting dictionaries to be served.
@end table
@end deftp

@deftp {Data Type} dicod-database
Data type representing a dictionary database.

@table @asis
@item @code{name}
Name of the database, will be used in DICT commands.

@item @code{module}
Name of the dicod module used by this database
(@pxref{Modules,,, dico, GNU Dico Manual}).

@item @code{options}
List of strings or gexps representing the arguments for the module handler
(@pxref{Handlers,,, dico, GNU Dico Manual}).
@end table
@end deftp

@defvr {Scheme Variable} %dicod-database:gcide
A @code{<dicod-database>} object serving the GNU Collaborative International
Dictonary of English using the @code{gcide} package.
@end defvr

@node Setuid Programs
@subsection Setuid Programs

@cindex setuid programs
Some programs need to run with ``root'' privileges, even when they are
launched by unprivileged users.  A notorious example is the
@command{passwd} program, which users can run to change their
password, and which needs to access the @file{/etc/passwd} and
@file{/etc/shadow} files---something normally restricted to root, for
obvious security reasons.  To address that, these executables are
@dfn{setuid-root}, meaning that they always run with root privileges
(@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
for more info about the setuid mechanism.)

The store itself @emph{cannot} contain setuid programs: that would be a
security issue since any user on the system can write derivations that
populate the store (@pxref{The Store}).  Thus, a different mechanism is
used: instead of changing the setuid bit directly on files that are in
the store, we let the system administrator @emph{declare} which programs
should be setuid root.

The @code{setuid-programs} field of an @code{operating-system}
declaration contains a list of G-expressions denoting the names of
programs to be setuid-root (@pxref{Using the Configuration System}).
For instance, the @command{passwd} program, which is part of the Shadow
package, can be designated by this G-expression (@pxref{G-Expressions}):

@example
#~(string-append #$shadow "/bin/passwd")
@end example

A default set of setuid programs is defined by the
@code{%setuid-programs} variable of the @code{(gnu system)} module.

@defvr {Scheme Variable} %setuid-programs
A list of G-expressions denoting common programs that are setuid-root.

The list includes commands such as @command{passwd}, @command{ping},
@command{su}, and @command{sudo}.
@end defvr

Under the hood, the actual setuid programs are created in the
@file{/run/setuid-programs} directory at system activation time.  The
files in this directory refer to the ``real'' binaries, which are in the
store.

@node X.509 Certificates
@subsection X.509 Certificates

@cindex HTTPS, certificates
@cindex X.509 certificates
@cindex TLS
Web servers available over HTTPS (that is, HTTP over the transport-layer
security mechanism, TLS) send client programs an @dfn{X.509 certificate}
that the client can then use to @emph{authenticate} the server.  To do
that, clients verify that the server's certificate is signed by a
so-called @dfn{certificate authority} (CA).  But to verify the CA's
signature, clients must have first acquired the CA's certificate.

Web browsers such as GNU@tie{}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---@command{wget},
@command{git}, @command{w3m}, etc.---need to be told where CA
certificates can be found.

@cindex @code{nss-certs}
In GuixSD, this is done by adding a package that provides certificates
to the @code{packages} field of the @code{operating-system} declaration
(@pxref{operating-system Reference}).  GuixSD includes one such package,
@code{nss-certs}, which is a set of CA certificates provided as part of
Mozilla's Network Security Services.

Note that it is @emph{not} part of @var{%base-packages}, so you need to
explicitly add it.  The @file{/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 @code{SSL_CERT_DIR} and @code{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 @code{GIT_SSL_CAINFO} environment variable.  Thus, you
would typically run something like:

@example
$ guix package -i 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"
@end example

@node Name Service Switch
@subsection Name Service Switch

@cindex name service switch
@cindex NSS
The @code{(gnu system nss)} module provides bindings to the
configuration file of the libc @dfn{name service switch} or @dfn{NSS}
(@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
Manual}).  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 (@pxref{Name
Service Switch, System Databases and Name Service Switch,, libc, The GNU
C Library Reference Manual}).

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
@code{name-service-switch} field of @code{operating-system} declarations
(@pxref{operating-system Reference, @code{name-service-switch}}).

@cindex nss-mdns
@cindex .local, host name lookup
As an example, the declaration below configures the NSS to use the
@uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
back-end}, which supports host name lookups over multicast DNS (mDNS)
for host names ending in @code{.local}:

@example
(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")))))
@end example

Do not worry: the @code{%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 @code{.local} host lookup working.

Note that, in this case, in addition to setting the
@code{name-service-switch} of the @code{operating-system} declaration,
you also need to use @code{avahi-service} (@pxref{Networking Services,
@code{avahi-service}}), or @var{%desktop-services}, which includes it
(@pxref{Desktop Services}).  Doing this makes @code{nss-mdns} accessible
to the name service cache daemon (@pxref{Base Services,
@code{nscd-service}}).

For convenience, the following variables provide typical NSS
configurations.

@defvr {Scheme Variable} %default-nss
This is the default name service switch configuration, a
@code{name-service-switch} object.
@end defvr

@defvr {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 @code{.local}.
@end defvr

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 (@pxref{NSS
Configuration File,,, libc, The GNU C Library Reference Manual}).
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 @command{guix system}.

@deftp {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.

@table @code
@item aliases
@itemx ethers
@itemx group
@itemx gshadow
@itemx hosts
@itemx initgroups
@itemx netgroup
@itemx networks
@itemx password
@itemx public-key
@itemx rpc
@itemx services
@itemx shadow
The system databases handled by the NSS.  Each of these fields must be a
list of @code{<name-service>} objects (see below).
@end table
@end deftp

@deftp {Data Type} name-service

This is the data type representing an actual name service and the
associated lookup action.

@table @code
@item name
A string denoting the name service (@pxref{Services in the NSS
configuration,,, libc, The GNU C Library Reference Manual}).

Note that name services listed here must be visible to nscd.  This is
achieved by passing the @code{#:name-services} argument to
@code{nscd-service} the list of packages providing the needed name
services (@pxref{Base Services, @code{nscd-service}}).

@item reaction
An action specified using the @code{lookup-specification} macro
(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
Reference Manual}).  For example:

@example
(lookup-specification (unavailable => continue)
                      (success => return))
@end example
@end table
@end deftp

@node Initial RAM Disk
@subsection Initial RAM Disk

@cindex initial RAM disk (initrd)
@cindex initrd (initial RAM disk)
For bootstrapping purposes, the Linux-Libre kernel is passed an
@dfn{initial RAM disk}, or @dfn{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 @code{initrd} field of an @code{operating-system} declaration allows
you to specify which initrd you would like to use.  The @code{(gnu
system linux-initrd)} module provides two ways to build an initrd: the
high-level @code{base-initrd} procedure, and the low-level
@code{expression->initrd} procedure.

The @code{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 @code{initrd} field of the operating
system declaration like this:

@example
(initrd (lambda (file-systems . rest)
          ;; Create a standard initrd that has modules "foo.ko"
          ;; and "bar.ko", as well as their dependencies, in
          ;; addition to the modules available by default.
          (apply base-initrd file-systems
                 #:extra-modules '("foo" "bar")
                 rest)))
@end example

The @code{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 initial RAM disk produced by @code{base-initrd} honors several
options passed on the Linux kernel command line (that is, arguments
passed @i{via} the @code{linux} command of GRUB, or the
@code{-append} option of QEMU), notably:

@table @code
@item --load=@var{boot}
Tell the initial RAM disk to load @var{boot}, a file containing a Scheme
program, once it has mounted the root file system.

GuixSD uses this option to yield control to a boot program that runs the
service activation programs and then spawns the GNU@tie{}Shepherd, the
initialization system.

@item --root=@var{root}
Mount @var{root} as the root file system.  @var{root} can be a
device name like @code{/dev/sda1}, a partition label, or a partition
UUID.

@item --system=@var{system}
Have @file{/run/booted-system} and @file{/run/current-system} point to
@var{system}.

@item modprobe.blacklist=@var{modules}@dots{}
@cindex module, black-listing
@cindex black list, of kernel modules
Instruct the initial RAM disk as well as the @command{modprobe} command
(from the kmod package) to refuse to load @var{modules}.  @var{modules}
must be a comma-separated list of module names---e.g.,
@code{usbkbd,9pnet}.

@item --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 @dfn{boot-to-Guile}.  The Schemer in you will
love it.  @xref{Using Guile Interactively,,, guile, GNU Guile Reference
Manual}, for more information on Guile's REPL.

@end table

Now that you know all the features that initial RAM disks produced by
@code{base-initrd} provide, here is how to use it and customize it
further.

@deffn {Monadic Procedure} base-initrd @var{file-systems} @
       [#:qemu-networking? #f] [#:virtio? #t] [#:volatile-root? #f] @
       [#:extra-modules '()] [#:mapped-devices '()]
Return a monadic derivation that builds a generic initrd.  @var{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 @code{--root}.
@var{mapped-devices} is a list of device mappings to realize before
@var{file-systems} are mounted (@pxref{Mapped Devices}).

When @var{qemu-networking?} is true, set up networking with the standard QEMU
parameters.  When @var{virtio?} is true, load additional modules so that the
initrd can be used as a QEMU guest with para-virtualized I/O drivers.

When @var{volatile-root?} is true, the root file system is writable but any changes
to it are lost.

The initrd is automatically populated with all the kernel modules necessary
for @var{file-systems} and for the given options.  However, additional kernel
modules can be listed in @var{extra-modules}.  They will be added to the initrd, and
loaded at boot time in the order in which they appear.