guix.texi

  ;; @dots{}

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

@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 keymap
@cindex keyboard
@deffn {Scheme Procedure} console-keymap-service @var{files} ...
@cindex keyboard layout
Return a service to load console keymaps from @var{files} using
@command{loadkeys} command.  Most likely, you want to load some default
keymap, which can be done like this:

@example
(console-keymap-service "dvorak")
@end example

Or, for example, for a Swedish keyboard, you may need to combine
the following keymaps:
@example
(console-keymap-service "se-lat6" "se-fi-lat6")
@end example

Also you can specify a full file name (or file names) of your keymap(s).
See @code{man loadkeys} for details.

@end deffn

@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 @var{%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-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-level} (default: @code{3})
The gzip compression level at which substitutes are compressed.  Use
@code{0} to disable compression altogether, and @code{9} to get the best
compression ratio at the expense of increased CPU usage.

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

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

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
@subsubsection 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 (mcron-service (list garbage-collector-job
                                       updatedb-job
                                       idutils-job))
                  %base-services)))
@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

@deffn {Scheme Procedure} mcron-service @var{jobs} [#:mcron @var{mcron}]
Return an mcron service running @var{mcron} that schedules @var{jobs}, a
list of gexps denoting mcron job specifications.

This is a shorthand for:
@example
(service mcron-service-type
         (mcron-configuration (mcron mcron) (jobs jobs)))
@end example
@end deffn

@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
@subsubsection Log Rotation

@cindex rottlog
@cindex log rotation
@cindex logging
Log files such as those found in @file{/var/log} tend to grow endlessly,
so it's a good idea to @dfn{rotate} them once in a while---i.e., archive
their contents in separate files, possibly compressed.  The @code{(gnu
services admin)} module provides an interface to GNU@tie{}Rot[t]log, a
log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).

The example below defines an operating system that provides log rotation
with the default settings, for commonly encountered log files.

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

(operating-system
  ;; @dots{}
  (services (cons (service rottlog-service-type)
                  %base-services)))
@end lisp

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

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

This service type can define mcron jobs (@pxref{Scheduled Job
Execution}) to run the rottlog service.
@end defvr

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

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

@item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")})
The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,,
rottlog, GNU Rot[t]log Manual}).

@item @code{rotations} (default: @code{%default-rotations})
A list of @code{log-rotation} objects as defined below.

@item @code{jobs}
This is a list of gexps where each gexp corresponds to an mcron job
specification (@pxref{Scheduled Job Execution}).
@end table
@end deftp

@deftp {Data Type} log-rotation
Data type representing the rotation of a group of log files.

Taking an example from the Rottlog manual (@pxref{Period Related File
Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be
defined like this:

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

The list of fields is as follows:

@table @asis
@item @code{frequency} (default: @code{'weekly})
The log rotation frequency, a symbol.

@item @code{files}
The list of files or file glob patterns to rotate.

@item @code{options} (default: @code{'()})
The list of rottlog options for this rotation (@pxref{Configuration
parameters,,, rottlog, GNU Rot[t]lg Manual}).

@item @code{post-rotate} (default: @code{#f})
Either @code{#f} or a gexp to execute once the rotation has completed.
@end table
@end deftp

@defvr {Scheme Variable} %default-rotations
Specifies weekly rotation of @var{%rotated-files} and
a couple of other files.
@end defvr

@defvr {Scheme Variable} %rotated-files
The list of syslog-controlled files to be rotated.  By default it is:
@code{'("/var/log/messages" "/var/log/secure")}.
@end defvr

@node Networking Services
@subsubsection Networking Services

The @code{(gnu services networking)} module provides services to configure
the network interface.

@cindex DHCP, networking service
@deffn {Scheme Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
Return a service that runs @var{dhcp}, a Dynamic Host Configuration
Protocol (DHCP) client, on all the non-loopback network interfaces.
@end deffn

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

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

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

@defvr {Scheme Variable} static-networking-service-type
This is the type for statically-configured network interfaces.
@c TODO Document <static-networking> data structures.
@end defvr

@deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @
       [#:netmask #f] [#:gateway #f] [#:name-servers @code{'()}] @
       [#:requirement @code{'(udev)}]
Return a service that starts @var{interface} with address @var{ip}.  If
@var{netmask} is true, use it as the network mask.  If @var{gateway} is true,
it must be a string specifying the default network gateway.  @var{requirement}
can be used to declare a dependency on another service before configuring the
interface.

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

@cindex wicd
@cindex wireless
@cindex WiFi
@cindex network management
@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}]
Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network
management daemon that aims to simplify wired and wireless networking.

This service adds the @var{wicd} package to the global profile, providing
several commands to interact with the daemon and configure networking:
@command{wicd-client}, a graphical user interface, and the @command{wicd-cli}
and @command{wicd-curses} user interfaces.
@end deffn

@cindex ModemManager

@defvr {Scheme Variable} modem-manager-service-type
This is the service type for the
@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager}
service. The value for this service type is a
@code{modem-manager-configuration} record.

This service is part of @code{%desktop-services} (@pxref{Desktop
Services}).
@end defvr

@deftp {Data Type} modem-manager-configuration
Data type representing the configuration of ModemManager.

@table @asis
@item @code{modem-manager} (default: @code{modem-manager})
The ModemManager package to use.

@end table
@end deftp

@cindex NetworkManager

@defvr {Scheme Variable} network-manager-service-type
This is the service type for the
@uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager}
service. The value for this service type is a
@code{network-manager-configuration} record.

This service is part of @code{%desktop-services} (@pxref{Desktop
Services}).
@end defvr

@deftp {Data Type} network-manager-configuration
Data type representing the configuration of NetworkManager.

@table @asis
@item @code{network-manager} (default: @code{network-manager})
The NetworkManager package to use.

@item @code{dns} (default: @code{"default"})
Processing mode for DNS, which affects how NetworkManager uses the
@code{resolv.conf} configuration file.

@table @samp
@item default
NetworkManager will update @code{resolv.conf} to reflect the nameservers
provided by currently active connections.

@item dnsmasq
NetworkManager will run @code{dnsmasq} as a local caching nameserver,
using a "split DNS" configuration if you are connected to a VPN, and
then update @code{resolv.conf} to point to the local nameserver.

@item none
NetworkManager will not modify @code{resolv.conf}.
@end table

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

@end table
@end deftp

@cindex Connman
@deffn {Scheme Variable} connman-service-type
This is the service type to run @url{https://01.org/connman,Connman},
a network connection manager.

Its value must be an
@code{connman-configuration} record as in this example:

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

See below for details about @code{connman-configuration}.
@end deffn

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

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

@item @code{disable-vpn?} (default: @code{#f})
When true, enable connman's vpn plugin.
@end table
@end deftp

@cindex WPA Supplicant
@defvr {Scheme Variable} wpa-supplicant-service-type
This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA
supplicant}, an authentication daemon required to authenticate against
encrypted WiFi or ethernet networks.  It is configured to listen for
requests on D-Bus.

The value of this service is the @code{wpa-supplicant} package to use.
Thus, it can be instantiated like this:

@lisp
(use-modules (gnu services networking))

(service wpa-supplicant-service-type)
@end lisp
@end defvr

@cindex NTP
@cindex real time clock
@deffn {Scheme Procedure} ntp-service [#:ntp @var{ntp}] @
  [#:servers @var{%ntp-servers}] @
  [#:allow-large-adjustment? #f]
Return a service that runs the daemon from @var{ntp}, the
@uref{http://www.ntp.org, Network Time Protocol package}.  The daemon will
keep the system clock synchronized with that of @var{servers}.
@var{allow-large-adjustment?} determines whether @command{ntpd} is allowed to
make an initial adjustment of more than 1,000 seconds.
@end deffn

@defvr {Scheme Variable} %ntp-servers
List of host names used as the default NTP servers.
@end defvr

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

@example
(service
 openntpd-service-type
 (openntpd-configuration
  (listen-on '("127.0.0.1" "::1"))
  (sensor '("udcf0 correction 70000"))
  (constraint-from '("www.gnu.org"))
  (constraints-from '("https://www.google.com/"))
  (allow-large-adjustment? #t)))

@end example
@end deffn

@deftp {Data Type} openntpd-configuration
@table @asis
@item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")})
The openntpd executable to use.
@item @code{listen-on} (default: @code{'("127.0.0.1" "::1")})
A list of local IP addresses or hostnames the ntpd daemon should listen on.
@item @code{query-from} (default: @code{'()})
A list of local IP address the ntpd daemon should use for outgoing queries.
@item @code{sensor} (default: @code{'()})
Specify a list of timedelta sensor devices ntpd should use.  @code{ntpd}
will listen to each sensor that acutally exists and ignore non-existant ones.
See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
information.
@item @code{server} (default: @var{%ntp-servers})
Specify a list of IP addresses or hostnames of NTP servers to synchronize to.
@item @code{servers} (default: @code{'()})
Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
@item @code{constraint-from} (default: @code{'()})
@code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers via TLS.
This time information is not used for precision but acts as an authenticated
constraint, thereby reducing the impact of unauthenticated NTP
man-in-the-middle attacks.
Specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide
a constraint.
@item @code{constraints-from} (default: @code{'()})
As with constraint from, specify a list of URLs, IP addresses or hostnames of
HTTPS servers to provide a constraint.  Should the hostname resolve to multiple
IP addresses, @code{ntpd} will calculate a median constraint from all of them.
@item @code{allow-large-adjustment?} (default: @code{#f})
Determines if @code{ntpd} is allowed to make an initial adjustment of more
than 180 seconds.
@end table
@end deftp

@cindex inetd
@deffn {Scheme variable} inetd-service-type
This service runs the @command{inetd} (@pxref{inetd invocation,,,
inetutils, GNU Inetutils}) daemon.  @command{inetd} listens for
connections on internet sockets, and lazily starts the specified server
program when a connection is made on one of these sockets.

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

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

See below for more details about @code{inetd-configuration}.
@end deffn

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

@table @asis
@item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")})
The @command{inetd} executable to use.

@item @code{entries} (default: @code{'()})
A list of @command{inetd} service entries.  Each entry should be created
by the @code{inetd-entry} constructor.
@end table
@end deftp

@deftp {Data Type} inetd-entry
Data type representing an entry in the @command{inetd} configuration.
Each entry corresponds to a socket where @command{inetd} will listen for
requests.

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

@xref{Configuration file,,, inetutils, GNU Inetutils} for a more
detailed discussion of each configuration field.
@end deftp

@cindex Tor
@defvr {Scheme Variable} tor-service-type
This is the type for a service that runs the @uref{https://torproject.org,
Tor} anonymous networking daemon.  The service is configured using a
@code{<tor-configuration>} record.  By default, the Tor daemon runs as the
@code{tor} unprivileged user, which is a member of the @code{tor} group.

@end defvr

@deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}]
This procedure is deprecated and will be removed in a future release.  Return
a service of the @code{tor-service-type} type.  @var{config-file} and
@var{tor} have the same meaning as in @code{<tor-configuration>}.
@end deffn

@deftp {Data Type} tor-configuration
@table @asis
@item @code{tor} (default: @code{tor})
The package that provides the Tor daemon.  This package is expected to provide
the daemon at @file{bin/tor} relative to its output directory.  The default
package is the @uref{https://www.torproject.org, Tor Project's}
implementation.

@item @code{config-file} (default: @code{(plain-file "empty" "")})
The configuration file to use.  It will be appended to a default configuration
file, and the final configuration file will be passed to @code{tor} via its
@code{-f} option.  This may be any ``file-like'' object (@pxref{G-Expressions,
file-like objects}).  See @code{man tor} for details on the configuration file
syntax.

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

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

If you want to customize the SOCKS socket in more detail, leave
@code{socks-socket-type} at its default value of @code{'tcp} and use
@code{config-file} to override the default by providing your own
@code{SocksPort} option.
@end table
@end deftp

@cindex hidden service
@deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
Define a new Tor @dfn{hidden service} called @var{name} and implementing
@var{mapping}.  @var{mapping} is a list of port/host tuples, such as:

@example
 '((22 "127.0.0.1:22")
   (80 "127.0.0.1:8080"))
@end example

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

This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, where
the @file{hostname} file contains the @code{.onion} host name for the hidden
service.

See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
project's documentation} for more information.
@end deffn

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

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

@deffn {Scheme Variable} rsync-service-type
This is the type for the @uref{https://rsync.samba.org, rsync} rsync daemon,
@command{rsync-configuration} record as in this example:

@example
(service rsync-service-type)
@end example

See below for details about @code{rsync-configuration}.
@end deffn

@deftp {Data Type} rsync-configuration
Data type representing the configuration for @code{rsync-service}.

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

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

@item @code{pid-file} (default: @code{"/var/run/rsyncd/rsyncd.pid"})
Name of the file where @command{rsync} writes its PID.

@item @code{lock-file} (default: @code{"/var/run/rsyncd/rsyncd.lock"})
Name of the file where @command{rsync} writes its lock file.

@item @code{log-file} (default: @code{"/var/log/rsyncd.log"})
Name of the file where @command{rsync} writes its log file.

@item @code{use-chroot?} (default: @var{#t})
Whether to use chroot for @command{rsync} shared directory.

@item @code{share-path} (default: @file{/srv/rsync})
Location of the @command{rsync} shared directory.

@item @code{share-comment} (default: @code{"Rsync share"})
Comment of the @command{rsync} shared directory.

@item @code{read-only?} (default: @var{#f})
Read-write permissions to shared directory.

@item @code{timeout} (default: @code{300})
I/O timeout in seconds.

@item @code{user} (default: @var{"root"})
Owner of the @code{rsync} process.

@item @code{group} (default: @var{"root"})
Group of the @code{rsync} process.

@item @code{uid} (default: @var{"rsyncd"})
User name or user ID that file transfers to and from that module should take
place as when the daemon was run as @code{root}.

@item @code{gid} (default: @var{"rsyncd"})
Group name or group ID that will be used when accessing the module.

@end table
@end deftp

Furthermore, @code{(gnu services ssh)} provides the following services.
@cindex SSH
@cindex SSH server

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

When @var{daemonic?} is true, @command{lshd} will detach from the
controlling terminal and log its output to syslogd, unless one sets
@var{syslog-output?} to false.  Obviously, it also makes lsh-service
depend on existence of syslogd service.  When @var{pid-file?} is true,
@command{lshd} writes its PID to the file called @var{pid-file}.

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

When @var{initialize?} is false, it is up to the user to initialize the
randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
a key pair with the private key stored in file @var{host-key} (@pxref{lshd
basics,,, lsh, LSH Manual}).

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

@var{allow-empty-passwords?} specifies whether to accept log-ins with empty
passwords, and @var{root-login?} specifies whether to accept log-ins as
root.

The other options should be self-descriptive.
@end deffn

@cindex SSH
@cindex SSH server
@deffn {Scheme Variable} openssh-service-type
This is the type for the @uref{http://www.openssh.org, OpenSSH} secure
shell daemon, @command{sshd}.  Its value must be an
@code{openssh-configuration} record as in this example:

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

See below for details about @code{openssh-configuration}.

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

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

@deftp {Data Type} openssh-configuration
This is the configuration record for OpenSSH's @command{sshd}.

@table @asis
@item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
Name of the file where @command{sshd} writes its PID.

@item @code{port-number} (default: @code{22})
TCP port on which @command{sshd} listens for incoming connections.

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

@item @code{allow-empty-passwords?} (default: @code{#f})
When true, users with empty passwords may log in.  When false, they may
not.

@item @code{password-authentication?} (default: @code{#t})
When true, users may log in with their password.  When false, they have
other authentication methods.

@item @code{public-key-authentication?} (default: @code{#t})
When true, users may log in using public key authentication.  When
false, users have to use other authentication method.

Authorized public keys are stored in @file{~/.ssh/authorized_keys}.
This is used only by protocol version 2.

@item @code{x11-forwarding?} (default: @code{#f})
When true, forwarding of X11 graphical client connections is
enabled---in other words, @command{ssh} options @option{-X} and
@option{-Y} will work.

@item @code{allow-agent-forwarding?} (default: @code{#t})
Whether to allow agent forwarding.

@item @code{allow-tcp-forwarding?} (default: @code{#t})
Whether to allow TCP forwarding.

@item @code{gateway-ports?} (default: @code{#f})