Newer
Older
This is either a string specifying the name of the block device to be mapped,
such as @code{"/dev/sda3"}, or a list of such strings when several devices
need to be assembled for creating a new one.
@item target
This string specifies the name of the resulting mapped device. For
kernel mappers such as encrypted devices of type @code{luks-device-mapping},
specifying @code{"my-partition"} leads to the creation of
the @code{"/dev/mapper/my-partition"} device.
For RAID devices of type @code{raid-device-mapping}, the full device name
such as @code{"/dev/md0"} needs to be given.
@item type
This must be a @code{mapped-device-kind} object, which specifies how
@var{source} is mapped to @var{target}.
@end table
@end deftp
@defvr {Scheme Variable} luks-device-mapping
This defines LUKS block device encryption using the @command{cryptsetup}
command from the package with the same name. It relies on the
@code{dm-crypt} Linux kernel module.
@end defvr
7025
7026
7027
7028
7029
7030
7031
7032
7033
7034
7035
7036
7037
7038
7039
7040
7041
7042
7043
7044
7045
7046
7047
7048
7049
7050
7051
7052
7053
7054
7055
7056
7057
7058
7059
7060
7061
7062
7063
7064
7065
7066
7067
7068
7069
7070
7071
7072
7073
7074
7075
7076
7077
7078
7079
7080
7081
7082
@defvr {Scheme Variable} raid-device-mapping
This defines a RAID device, which is assembled using the @code{mdadm}
command from the package with the same name. It requires a Linux kernel
module for the appropriate RAID level to be loaded, such as @code{raid456}
for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
@end defvr
@cindex disk encryption
@cindex LUKS
The following example specifies a mapping from @file{/dev/sda3} to
@file{/dev/mapper/home} using LUKS---the
@url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a
standard mechanism for disk encryption.
The @file{/dev/mapper/home}
device can then be used as the @code{device} of a @code{file-system}
declaration (@pxref{File Systems}).
@example
(mapped-device
(source "/dev/sda3")
(target "home")
(type luks-device-mapping))
@end example
Alternatively, to become independent of device numbering, one may obtain
the LUKS UUID (@dfn{unique identifier}) of the source device by a
command like:
@example
cryptsetup luksUUID /dev/sda3
@end example
and use it as follows:
@example
(mapped-device
(source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
(target "home")
(type luks-device-mapping))
@end example
A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
may be declared as follows:
@example
(mapped-device
(source (list "/dev/sda1" "/dev/sdb1"))
(target "/dev/md0")
(type raid-device-mapping))
@end example
The @file{/dev/md0} device can then be used as the @code{device} of a
@code{file-system} declaration (@pxref{File Systems}).
Note that the RAID level need not be given; it is chosen during the
initial creation and formatting of the RAID device and is determined
automatically later.
@node User Accounts
@subsection User Accounts
User accounts and groups are entirely managed through the
@code{operating-system} declaration. They are specified with the
@code{user-account} and @code{user-group} forms:
@example
(user-account
(name "alice")
(group "users")
(supplementary-groups '("wheel" ;allow use of sudo, etc.
"audio" ;sound card
"video" ;video devices such as webcams
"cdrom")) ;the good ol' CD-ROM
(comment "Bob's sister")
(home-directory "/home/alice"))
@end example
When booting or upon completion of @command{guix system reconfigure},
the system ensures that only the user accounts and groups specified in
the @code{operating-system} declaration exist, and with the specified
properties. Thus, account or group creations or modifications made by
directly invoking commands such as @command{useradd} are lost upon
reconfiguration or reboot. This ensures that the system remains exactly
as declared.
@deftp {Data Type} user-account
Objects of this type represent user accounts. The following members may
be specified:
@table @asis
@item @code{name}
The name of the user account.
@item @code{group}
This is the name (a string) or identifier (a number) of the user group
this account belongs to.
@item @code{supplementary-groups} (default: @code{'()})
Optionally, this can be defined as a list of group names that this
account belongs to.
@item @code{uid} (default: @code{#f})
This is the user ID for this account (a number), or @code{#f}. In the
latter case, a number is automatically chosen by the system when the
account is created.
@item @code{comment} (default: @code{""})
A comment about the account, such as the account owner's full name.
@item @code{home-directory}
This is the name of the home directory for the account.
@item @code{shell} (default: Bash)
This is a G-expression denoting the file name of a program to be used as
the shell (@pxref{G-Expressions}).
@item @code{system?} (default: @code{#f})
This Boolean value indicates whether the account is a ``system''
account. System accounts are sometimes treated specially; for instance,
graphical login managers do not list them.
@anchor{user-account-password}
@item @code{password} (default: @code{#f})
You would normally leave this field to @code{#f}, initialize user
passwords as @code{root} with the @command{passwd} command, and then let
users change it with @command{passwd}. Passwords set with
@command{passwd} are of course preserved across reboot and
reconfiguration.
If you @emph{do} want to have a preset password for an account, then
this field must contain the encrypted password, as a string.
@xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
Manual}, for information on Guile's @code{crypt} procedure.
User group declarations are even simpler:
@example
(user-group (name "students"))
@end example
@deftp {Data Type} user-group
This type is for, well, user groups. There are just a few fields:
@table @asis
@item @code{name}
@item @code{id} (default: @code{#f})
The group identifier (a number). If @code{#f}, a new number is
automatically allocated when the group is created.
@item @code{system?} (default: @code{#f})
This Boolean value indicates whether the group is a ``system'' group.
System groups have low numerical IDs.
@item @code{password} (default: @code{#f})
What, user groups can have a password? Well, apparently yes. Unless
@code{#f}, this field specifies the password of the group.
For convenience, a variable lists all the basic user groups one may
expect:
@defvr {Scheme Variable} %base-groups
This is the list of basic user groups that users and/or packages expect
to be present on the system. This includes groups such as ``root'',
``wheel'', and ``users'', as well as groups used to control access to
specific devices such as ``audio'', ``disk'', and ``cdrom''.
@end defvr
@defvr {Scheme Variable} %base-user-accounts
This is the list of basic system accounts that programs may expect to
find on a GNU/Linux system, such as the ``nobody'' account.
Note that the ``root'' account is not included here. It is a
special-case and is automatically added whether or not it is specified.
@end defvr
@node Locales
@subsection Locales
@cindex locale
A @dfn{locale} defines cultural conventions for a particular language
and region of the world (@pxref{Locales,,, libc, The GNU C Library
Reference Manual}). Each locale has a name that typically has the form
@code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
@code{fr_LU.utf8} designates the locale for the French language, with
cultural conventions from Luxembourg, and using the UTF-8 encoding.
@cindex locale definition
Usually, you will want to specify the default locale for the machine
using the @code{locale} field of the @code{operating-system} declaration
(@pxref{operating-system Reference, @code{locale}}).
The selected locale is automatically added to the @dfn{locale
definitions} known to the system if needed, with its codeset inferred
from its name---e.g., @code{bo_CN.utf8} will be assumed to use the
@code{UTF-8} codeset. Additional locale definitions can be specified in
the @code{locale-definitions} slot of @code{operating-system}---this is
useful, for instance, if the codeset could not be inferred from the
locale name. The default set of locale definitions includes some widely
used locales, but not all the available locales, in order to save space.
For instance, to add the North Frisian locale for Germany, the value of
that field may be:
@example
(cons (locale-definition
(name "fy_DE.utf8") (source "fy_DE"))
%default-locale-definitions)
@end example
Likewise, to save space, one might want @code{locale-definitions} to
list only the locales that are actually used, as in:
@example
(list (locale-definition
(name "ja_JP.eucjp") (source "ja_JP")
(charset "EUC-JP")))
@end example
@vindex LOCPATH
The compiled locale definitions are available at
@file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
version, which is the default location where the GNU@tie{}libc provided
by Guix looks for locale data. This can be overridden using the
@code{LOCPATH} environment variable (@pxref{locales-and-locpath,
@code{LOCPATH} and locale packages}).
7260
7261
7262
7263
7264
7265
7266
7267
7268
7269
7270
7271
7272
7273
7274
7275
7276
7277
7278
7279
7280
7281
7282
7283
7284
The @code{locale-definition} form is provided by the @code{(gnu system
locale)} module. Details are given below.
@deftp {Data Type} locale-definition
This is the data type of a locale definition.
@table @asis
@item @code{name}
The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
Reference Manual}, for more information on locale names.
@item @code{source}
The name of the source for that locale. This is typically the
@code{@var{language}_@var{territory}} part of the locale name.
@item @code{charset} (default: @code{"UTF-8"})
The ``character set'' or ``code set'' for that locale,
@uref{http://www.iana.org/assignments/character-sets, as defined by
IANA}.
@end table
@end deftp
@defvr {Scheme Variable} %default-locale-definitions
A list of commonly used UTF-8 locales, used as the default
value of the @code{locale-definitions} field of @code{operating-system}
@cindex locale name
@cindex normalized codeset in locale names
These locale definitions use the @dfn{normalized codeset} for the part
that follows the dot in the name (@pxref{Using gettextized software,
normalized codeset,, libc, The GNU C Library Reference Manual}). So for
instance it has @code{uk_UA.utf8} but @emph{not}, say,
@code{uk_UA.UTF-8}.
7298
7299
7300
7301
7302
7303
7304
7305
7306
7307
7308
7309
7310
7311
7312
7313
7314
7315
7316
7317
7318
7319
7320
7321
7322
7323
7324
7325
7326
7327
7328
7329
7330
7331
7332
7333
7334
7335
7336
7337
7338
7339
7340
7341
7342
7343
7344
7345
7346
7347
7348
@subsubsection Locale Data Compatibility Considerations
@cindex incompatibility, of locale data
@code{operating-system} declarations provide a @code{locale-libcs} field
to specify the GNU@tie{}libc packages that are used to compile locale
declarations (@pxref{operating-system Reference}). ``Why would I
care?'', you may ask. Well, it turns out that the binary format of
locale data is occasionally incompatible from one libc version to
another.
@c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
For instance, a program linked against libc version 2.21 is unable to
read locale data produced with libc 2.22; worse, that program
@emph{aborts} instead of simply ignoring the incompatible locale
data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
the incompatible locale data, which is already an improvement.}.
Similarly, a program linked against libc 2.22 can read most, but not
all, the locale data from libc 2.21 (specifically, @code{LC_COLLATE}
data is incompatible); thus calls to @code{setlocale} may fail, but
programs will not abort.
The ``problem'' in GuixSD is that users have a lot of freedom: They can
choose whether and when to upgrade software in their profiles, and might
be using a libc version different from the one the system administrator
used to build the system-wide locale data.
Fortunately, unprivileged users can also install their own locale data
and define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
@code{GUIX_LOCPATH} and locale packages}).
Still, it is best if the system-wide locale data at
@file{/run/current-system/locale} is built for all the libc versions
actually in use on the system, so that all the programs can access
it---this is especially crucial on a multi-user system. To do that, the
administrator can specify several libc packages in the
@code{locale-libcs} field of @code{operating-system}:
@example
(use-package-modules base)
(operating-system
;; @dots{}
(locale-libcs (list glibc-2.21 (canonical-package glibc))))
@end example
This example would lead to a system containing locale definitions for
both libc 2.21 and the current version of libc in
@file{/run/current-system/locale}.
@node Services
@subsection Services
@cindex system services
An important part of preparing an @code{operating-system} declaration is
listing @dfn{system services} and their configuration (@pxref{Using the
Configuration System}). System services are typically daemons launched
when the system boots, or other actions needed at that time---e.g.,
Services are managed by the GNU@tie{}Shepherd (@pxref{Introduction,,,
shepherd, The GNU Shepherd Manual}). On a running system, the
@command{herd} command allows you to list the available services, show
their status, start and stop them, or do other specific operations
(@pxref{Jump Start,,, shepherd, The GNU Shepherd Manual}). For example:
@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
Run libc's name service cache daemon (nscd).
@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 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.
* Networking Services:: Network setup, SSH daemon, etc.
* X Window:: Graphical display.
* Desktop Services:: D-Bus and desktop services.
* Mail Services:: IMAP, POP3, SMTP, and all that.
@node Base Services
@subsubsection 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
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 @var{%base-services}, like
this:
@end example
@end defvr
@deffn {Scheme Procedure} host-name-service @var{name}
Return a service that sets the host name to @var{name}.
@end deffn
@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.
@deftp {Data Type} mingetty-configuration
This is the data type representing the configuration of Mingetty, which
implements console log-in.
@table @asis
@item @code{tty}
The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
@item @code{motd}
A file-like object containing the ``message of the day''.
@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
Ludovic Courtès
committed
@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.
Ludovic Courtès
committed
@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
Ludovic Courtès
committed
@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)
Ludovic Courtès
committed
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.
Ludovic Courtès
committed
@item @code{log-file} (default: @code{"/var/log/nscd.log"})
Name of the nscd log file. This is where debugging output goes when
Ludovic Courtès
committed
@code{debug-level} is strictly positive.
@item @code{debug-level} (default: @code{0})
Integer denoting the debugging levels. Higher numbers mean that more
Ludovic Courtès
committed
7507
7508
7509
7510
7511
7512
7513
7514
7515
7516
7517
7518
7519
7520
7521
7522
7523
7524
7525
7526
7527
7528
7529
7530
7531
7532
7533
7534
7535
7536
7537
7538
7539
7540
7541
7542
7543
7544
7545
7546
7547
7548
7549
7550
7551
7552
7553
7554
7555
7556
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).
Ludovic Courtès
committed
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
@deffn {Scheme Procedure} syslog-service @
[#:config-file @var{%default-syslog.conf}]
Return a service that runs @command{syslogd}. If the configuration file
name @var{config-file} is not specified, use some reasonable default
@xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more
information on the configuration file syntax.
@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})
Whether to authorize the substitute key for @code{hydra.gnu.org}
(@pxref{Substitutes}).
@item @code{use-substitutes?} (default: @code{#t})
Whether to use substitutes.
@item @code{substitute-urls} (default: @var{%default-substitute-urls})
The list of URLs where to look for substitutes by default.
@item @code{extra-options} (default: @code{'()})
List of extra command-line options for @command{guix-daemon}.
@item @code{lsof} (default: @var{lsof})
@itemx @code{lsh} (default: @var{lsh})
The lsof and lsh packages to use.
@end table
@end deftp
@deffn {Scheme Procedure} guix-service @var{config}
Return a service that runs the Guix build daemon according to
@var{config}.
@deffn {Scheme Procedure} udev-service [#:udev udev]
Run @var{udev}, which populates the @file{/dev} directory dynamically.
@end deffn
@deffn {Scheme Procedure} urandom-seed-service @var{#f}
Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom}
when rebooting.
@end deffn
@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
@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.
@deffn {Scheme Procedure} gpm-service [#:gpm @var{gpm}] @
[#:options]
Run @var{gpm}, the general-purpose mouse daemon, with the given
command-line @var{options}. GPM allows users to use the mouse in the console,
notably to select, copy, and paste text. The default value of @var{options}
uses the @code{ps2} protocol, which works for both USB and PS/2 mice.
This service is not part of @var{%base-services}.
@end deffn
@anchor{guix-publish-service}
@deffn {Scheme Procedure} guix-publish-service [#:guix @var{guix}] @
[#:port 80] [#:host "localhost"]
Return a service that runs @command{guix publish} listening on @var{host}
and @var{port} (@pxref{Invoking guix publish}).
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
@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
7682
7683
7684
7685
7686
7687
7688
7689
7690
7691
7692
7693
7694
7695
7696
7697
7698
7699
7700
7701
7702
7703
7704
7705
7706
7707
7708
7709
7710
@anchor{pam-limits-service}
@cindex session limits
@cindex ulimit
@cindex priority
@deffn {Scheme Procedure} pam-limits-service [#:limits @var{limits}]
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 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))
;; Run 'updatedb' at 3AM every day. Here we write the
;; job's action as a Scheme procedure.
(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.
#~(job "5 0 * * *" ;Vixie cron syntax
"guix gc -F 1G"))
(define idutils-jobs
;; 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
7762
7763
7764
7765
7766
7767
7768
7769
7770
7771
7772
7773
7774
7775
7776
7777
7778
7779
7780
7781
7782
7783
7784
7785
7786
7787
7788
7789
7790
7791
7792
7793
7794
7795
7796
7797
7798
7799
7800
7801
7802
7803
7804
%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.
@deffn {Scheme Procedure} mcron-service @var{jobs} [#:mcron @var{mcron2}]
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 addition
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{mcron2})
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 Networking Services
@subsubsection Networking Services
The @code{(gnu services networking)} module provides services to configure
@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} static-networking-service @var{interface} @var{ip} @
[#:gateway #f] [#:name-servers @code{'()}]
Return a service that starts @var{interface} with address @var{ip}. If
@var{gateway} is true, it must be a string specifying the default network
gateway.
@end deffn
@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.
@cindex NetworkManager
@deffn {Scheme Procedure} network-manager-service @
[#:network-manager @var{network-manager}]
Return a service that runs NetworkManager, a network connection manager
attempting to keep network connectivity active when available.
@cindex Connman
@deffn {Scheme Procedure} connman-service @
[#:connman @var{connman}]
Return a service that runs @url{https://01.org/connman,Connman}, a network
connection manager.
This service adds the @var{connman} package to the global profile, providing
several the @command{connmanctl} command to interact with the daemon and
configure networking."
@end deffn
@deffn {Scheme Procedure} ntp-service [#:ntp @var{ntp}] @
[#:name-service @var{%ntp-servers}]
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}.
@end deffn
@defvr {Scheme Variable} %ntp-servers
List of host names used as the default NTP servers.
@end defvr
@deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}]
Return a service to run the @uref{https://torproject.org, Tor} anonymous
networking daemon.
The daemon runs as the @code{tor} unprivileged user. It is passed
@var{config-file}, a file-like object, with an additional @code{User tor} line
and lines for hidden services added via @code{tor-hidden-service}. Run
@command{man tor} for information about the configuration file.
@end deffn
@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.
@deffn {Scheme Procedure} bitlbee-service [#:bitlbee bitlbee] @
[#:interface "127.0.0.1"] [#:port 6667] @
[#:extra-settings ""]
Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
acts as a gateway between IRC and chat networks.
The daemon will listen to the interface corresponding to the IP address
specified in @var{interface}, on @var{port}. @code{127.0.0.1} means that only
local clients can connect, whereas @code{0.0.0.0} means that connections can
come from any networking interface.
In addition, @var{extra-settings} specifies a string to append to the
configuration file.
@end deffn
Furthermore, @code{(gnu services ssh)} provides the following services.
@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
The other options should be self-descriptive.
@end deffn
7949
7950
7951
7952
7953
7954
7955
7956
7957
7958
7959
7960
7961
7962
7963
7964
7965
7966
7967
7968
7969
7970
7971
7972
7973
7974
7975
7976
7977
7978
7979
7980
7981
7982
7983
7984
7985
7986
7987
7988
7989
@deffn {Scheme Procedure} dropbear-service [@var{config}]
Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH
daemon} with the given @var{config}, a @code{<dropbear-configuration>}
object.
For example, to specify a Dropbear service listening on port 1234, add
this call to the operating system's @code{services} field:
@example
(dropbear-service (dropbear-configuration
(port-number 1234)))
@end example
@end deffn
@deftp {Data Type} dropbear-configuration
This data type represents the configuration of a Dropbear SSH daemon.
@table @asis
@item @code{dropbear} (default: @var{dropbear})
The Dropbear package to use.
@item @code{port-number} (default: 22)
The TCP port where the daemon waits for incoming connections.
@item @code{syslog-output?} (default: @code{#t})
Whether to enable syslog output.
@item @code{pid-file} (default: @code{"/var/run/dropbear.pid"})
File name of the daemon's PID file.
@item @code{root-login?} (default: @code{#f})
Whether to allow @code{root} logins.
@item @code{allow-empty-passwords?} (default: @code{#f})
Whether to allow empty passwords.
@item @code{password-authentication?} (default: @code{#t})
Whether to enable password-based authentication.
@end table
@end deftp
@defvr {Scheme Variable} %facebook-host-aliases
This variable contains a string for use in @file{/etc/hosts}
(@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
line contains a entry that maps a known server name of the Facebook
on-line service---e.g., @code{www.facebook.com}---to the local
host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
This variable is typically used in the @code{hosts-file} field of an
@code{operating-system} declaration (@pxref{operating-system Reference,
@file{/etc/hosts}}):