guix.texi

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

@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{https://gitlab.com/cryptsetup/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

@cindex swap encryption
It is also desirable to encrypt swap space, since swap space may contain
sensitive data.  One way to accomplish that is to use a swap file in a
file system on a device mapped via LUKS encryption.  In this way, the
swap file is encrypted because the entire device is encrypted.
@xref{Preparing for Installation,,Disk Partitioning}, for an 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
@section User Accounts

@cindex users
@cindex accounts
@cindex 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}
@cindex groups
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{create-home-directory?} (default: @code{#t})
Indicates whether the home directory of this account should be created
if it does not exist yet.

@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}
@cindex password, for user accounts
@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 set an initial password for an account, then
this field must contain the encrypted password, as a string.  You can use the
@code{crypt} procedure for this purpose:

@example
(user-account
  (name "charlie")
  (group "users")

  ;; Specify a SHA-512-hashed initial password.
  (password (crypt "InitialPassword!" "$6$abc")))
@end example

@quotation Note
The hash of this initial password will be available in a file in
@file{/gnu/store}, readable by all the users, so this method must be used with
care.
@end quotation

@xref{Passphrase Storage,,, 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.

@end table
@end deftp

@cindex groups
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}
The name of the group.

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

@end table
@end deftp

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 Keyboard Layout
@section Keyboard Layout

@cindex keyboard layout
@cindex keymap
To specify what each key of your keyboard does, you need to tell the operating
system what @dfn{keyboard layout} you want to use.  The default, when nothing
is specified, is the US English QWERTY layout for 105-key PC keyboards.
However, German speakers will usually prefer the German QWERTZ layout, French
speakers will want the AZERTY layout, and so on; hackers might prefer Dvorak
or bépo, and they might even want to further customize the effect of some of
the keys.  This section explains how to get that done.

@cindex keyboard layout, definition
There are three components that will want to know about your keyboard layout:

@itemize
@item
The @emph{bootloader} may want to know what keyboard layout you want to use
(@pxref{Bootloader Configuration, @code{keyboard-layout}}).  This is useful if
you want, for instance, to make sure that you can type the passphrase of your
encrypted root partition using the right layout.

@item
The @emph{operating system kernel}, Linux, will need that so that the console
is properly configured (@pxref{operating-system Reference,
@code{keyboard-layout}}).

@item
The @emph{graphical display server}, usually Xorg, also has its own idea of
the keyboard layout (@pxref{X Window, @code{keyboard-layout}}).
@end itemize

Guix allows you to configure all three separately but, fortunately, it allows
you to share the same keyboard layout for all three components.

@cindex XKB, keyboard layouts
Keyboard layouts are represented by records created by the
@code{keyboard-layout} procedure of @code{(gnu system keyboard)}.  Following
the X Keyboard extension (XKB), each layout has four attributes: a name (often
a language code such as ``fi'' for Finnish or ``jp'' for Japanese), an
optional variant name, an optional keyboard model name, and a possibly empty
list of additional options.  In most cases the layout name is all you care
about.  Here are a few example:

@example
;; The German QWERTZ layout.  Here we assume a standard
;; "pc105" keyboard model.
(keyboard-layout "de")

;; The bépo variant of the French layout.
(keyboard-layout "fr" "bepo")

;; The Catalan layout.
(keyboard-layout "es" "cat")

;; The Latin American Spanish layout.  In addition, the
;; "Caps Lock" key is used as an additional "Ctrl" key,
;; and the "Menu" key is used as a "Compose" key to enter
;; accented letters.
(keyboard-layout "latam"
                 #:options '("ctrl:nocaps" "compose:menu"))

;; The Russian layout for a ThinkPad keyboard.
(keyboard-layout "ru" #:model "thinkpad")

;; The "US international" layout, which is the US layout plus
;; dead keys to enter accented characters.  This is for an
;; Apple MacBook keyboard.
(keyboard-layout "us" "intl" #:model "macbook78")
@end example

See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} package
for a complete list of supported layouts, variants, and models.

@cindex keyboard layout, configuration
Let's say you want your system to use the Turkish keyboard layout throughout
your system---bootloader, console, and Xorg.  Here's what your system
configuration would look like:

@findex set-xorg-configuration
@lisp
;; Using the Turkish layout for the bootloader, the console,
;; and for Xorg.

(operating-system
  ;; ...
  (keyboard-layout (keyboard-layout "tr"))  ;for the console
  (bootloader (bootloader-configuration
                (bootloader grub-efi-bootloader)
                (target "/boot/efi")
                (keyboard-layout keyboard-layout))) ;for GRUB
  (services (cons (set-xorg-configuration
                    (xorg-configuration             ;for Xorg
                      (keyboard-layout keyboard-layout)))
                  %desktop-services)))
@end lisp

In the example above, for GRUB and for Xorg, we just refer to the
@code{keyboard-layout} field defined above, but we could just as well refer to
a different layout.  The @code{set-xorg-configuration} procedure communicates
the desired Xorg configuration to the graphical log-in manager, by default
GDM.

We've discussed how to specify the @emph{default} keyboard layout of your
system when it starts, but you can also adjust it at run time:

@itemize
@item
If you're using GNOME, its settings panel has a ``Region & Language'' entry
where you can select one or more keyboard layouts.

@item
Under Xorg, the @command{setxkbmap} command (from the same-named package)
allows you to change the current layout.  For example, this is how you would
change the layout to US Dvorak:

@example
setxkbmap us dvorak
@end example

@item
The @code{loadkeys} command changes the keyboard layout in effect in the Linux
console.  However, note that @code{loadkeys} does @emph{not} use the XKB
keyboard layout categorization described above.  The command below loads the
French bépo layout:

@example
loadkeys fr-bepo
@end example
@end itemize

@node Locales
@section 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}).

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{https://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}
declarations.

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

@subsection 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, of 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'' with Guix 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
@section 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.,
configuring network access.

Guix has a broad definition of ``service'' (@pxref{Service
Composition}), but many services are managed by the GNU@tie{}Shepherd
(@pxref{Shepherd Services}).  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:

@example
# herd status
@end example

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

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

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

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

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

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

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

@node Base Services
@subsection Base Services

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

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

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

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

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

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

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

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

@example
`(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))
  ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env")))
@end example

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

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

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

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

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

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

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

@table @asis

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

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

@end table
@end deftp

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

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

@table @asis

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

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

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

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

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

@end table
@end deftp

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

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

@table @asis

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@end table
@end deftp

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

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

@table @asis

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

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

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

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

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

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

@end table
@end deftp

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

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

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

@example
herd invalidate nscd hosts
@end example

@noindent
invalidates the host name lookup cache of nscd.

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

@end deffn

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

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

@table @asis

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

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

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

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

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

@end table