@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
@set KEY-SERVER pool.sks-keyservers.net
+@c Base URL for downloads.
+@set BASE-URL https://ftp.gnu.org/gnu/guix
+
@c The official substitute server used by default.
-@set SUBSTITUTE-SERVER ci.guix.info
+@set SUBSTITUTE-SERVER ci.guix.gnu.org
+@set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER}
@copying
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès@*
Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
-Copyright @copyright{} 2016, 2017, 2018 Efraim Flashner@*
+Copyright @copyright{} 2016, 2017, 2018, 2019 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016, 2017 ng0@*
Copyright @copyright{} 2016, 2017, 2018, 2019 Jan Nieuwenhuizen@*
Copyright @copyright{} 2018 Mike Gerwitz@*
Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
Copyright @copyright{} 2018 Gábor Boskovits@*
-Copyright @copyright{} 2018 Florian Pelz@*
+Copyright @copyright{} 2018, 2019 Florian Pelz@*
Copyright @copyright{} 2018 Laura Lazzati@*
Copyright @copyright{} 2018 Alex Vong@*
+Copyright @copyright{} 2019 Josh Holland@*
+Copyright @copyright{} 2019 Diego Nicola Barbato@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@c TRANSLATORS: You can replace the following paragraph with information on
@c how to join your own translation team and how to report issues with the
@c translation.
-This manual is also available in French (@pxref{Top,,, guix.fr, Manuel de
-référence de GNU Guix}) and German (@pxref{Top,,, guix.de, Referenzhandbuch
-zu GNU Guix}). If you would like to translate it in your native language,
-consider joining the
+This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN,
+GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU
+Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}),
+Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), and
+Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you
+would like to translate it in your native language, consider joining the
@uref{https://translationproject.org/domain/guix-manual.html, Translation
Project}.
* File Systems:: Configuring file system mounts.
* Mapped Devices:: Block device extra processing.
* User Accounts:: Specifying user accounts.
+* Keyboard Layout:: How the system interprets key strokes.
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
@cindex Guix System
Guix comes with a distribution of the GNU system consisting entirely of
free software@footnote{The term ``free'' here refers to the
-@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
+@url{https://www.gnu.org/philosophy/free-sw.html,freedom provided to
users of that software}.}. The
distribution can be installed on its own (@pxref{System Installation}),
but it is also possible to install Guix as a package manager on top of
The distribution provides core GNU packages such as GNU libc, GCC, and
Binutils, as well as many GNU and non-GNU applications. The complete
list of available packages can be browsed
-@url{http://www.gnu.org/software/guix/packages,on-line} or by
+@url{https://www.gnu.org/software/guix/packages,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):
@example
and Linux-Libre kernel.
@item aarch64-linux
-little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is
-currently in an experimental stage, with limited support.
-@xref{Contributing}, for how to help!
+little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.
@item mips64el-linux
little-endian 64-bit MIPS processors, specifically the Loongson series,
-n32 ABI, and Linux-Libre kernel.
+n32 ABI, and Linux-Libre kernel. This configuration is no longer fully
+supported; in particular, the project's build farms no longer provide
+substitutes for this architecture.
@end table
is described in the next sections. The only requirement is to have
GNU@tie{}tar and Xz.
+@c Note duplicated from the ``Installation'' node.
+@quotation Note
+We recommend the use of this
+@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
+shell installer script}. The script automates the download, installation, and
+initial configuration steps described below. It should be run as the root
+user.
+@end quotation
+
Installing goes along these lines:
@enumerate
@item
@cindex downloading Guix binary
Download the binary tarball from
-@indicateurl{https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz},
+@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.@var{system}.tar.xz},
where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine
already running the kernel Linux, and so on.
authenticity of the tarball against it, along these lines:
@example
-$ wget https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
+$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
$ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
@end example
@c files into place.
@c
@c See this thread for more information:
-@c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
+@c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
@example
# cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
the root profile:
@example
-# guix package -i hello
+# guix install hello
@end example
-The @code{guix} package must remain available in @code{root}'s profile,
-or it would become subject to garbage collection---in which case you
-would find yourself badly handicapped by the lack of the @command{guix}
-command. In other words, do not remove @code{guix} by running
-@code{guix package -r guix}.
-
The binary installation tarball can be (re)produced and verified simply
by running the following command in the Guix source tree:
GNU Guix depends on the following packages:
@itemize
-@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.2.x;
+@item @url{https://gnu.org/software/guile/, GNU Guile}, version 2.2.x;
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@item
-@uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings
+@uref{https://gnutls.org/, GnuTLS}, specifically its Guile bindings
(@pxref{Guile Preparations, how to install the GnuTLS bindings for
Guile,, gnutls-guile, GnuTLS-Guile});
@item
@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August
2017 or later;
@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON};
-@item @url{http://zlib.net, zlib};
-@item @url{http://www.gnu.org/software/make/, GNU Make}.
+@item @url{https://zlib.net, zlib};
+@item @url{https://www.gnu.org/software/make/, GNU Make}.
@end itemize
The following dependencies are optional:
following packages are also needed:
@itemize
-@item @url{http://gnupg.org/, GNU libgcrypt};
-@item @url{http://sqlite.org, SQLite 3};
-@item @url{http://gcc.gnu.org, GCC's g++}, with support for the
+@item @url{https://gnupg.org/, GNU libgcrypt};
+@item @url{https://sqlite.org, SQLite 3};
+@item @url{https://gcc.gnu.org, GCC's g++}, with support for the
C++11 standard.
@end itemize
inadvertently corrupt your store (@pxref{The Store}).
@cindex Nix, compatibility
-When a working installation of @url{http://nixos.org/nix/, the Nix package
+When a working installation of @url{https://nixos.org/nix/, the Nix package
manager} is available, you
can instead configure Guix with @code{--disable-daemon}. In that case,
Nix replaces the three dependencies above.
On a GNU/Linux system, a build user pool may be created like this (using
Bash syntax and the @code{shadow} commands):
-@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
+@c See https://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
@c for why `-G' is needed.
@example
# groupadd --system guixbuild
variable:
@example
-$ guix package -i glibc-locales
+$ guix install glibc-locales
$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
@end example
for Chinese languages:
@example
-guix package -i font-adobe-source-han-sans:cn
+guix install font-adobe-source-han-sans:cn
@end example
@cindex @code{xterm}
@node Limitations
@section Limitations
-As of version @value{VERSION}, Guix System is
-not production-ready. It may contain bugs and lack important
-features. Thus, if you are looking for a stable production system that
-respects your freedom as a computer user, a good solution at this point
-is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
-the more established GNU/Linux distributions}. We hope you can soon switch
-to the Guix System without fear, of course. In the meantime, you can
-also keep using your distribution and try out the package manager on top
-of it (@pxref{Installation}).
+We consider Guix System to be ready for a wide range of ``desktop'' and server
+use cases. The reliability guarantees it provides---transactional upgrades
+and rollbacks, reproducibility---make it a solid foundation.
-Before you proceed with the installation, be aware of the following
-noteworthy limitations applicable to version @value{VERSION}:
+Nevertheless, before you proceed with the installation, be aware of the
+following noteworthy limitations applicable to version @value{VERSION}:
@itemize
-@item
-The installation process does not include a graphical user interface and
-requires familiarity with GNU/Linux (see the following subsections to
-get a feel of what that means.)
-
@item
Support for the Logical Volume Manager (LVM) is missing.
More and more system services are provided (@pxref{Services}), but some
may be missing.
-@item
-More than 8,500 packages are available, but you might
-occasionally find that a useful package is missing.
-
@item
GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
-as well as a number of X11 window managers. However, some graphical
-applications may be missing, as well as KDE.
+as well as a number of X11 window managers. However, KDE is currently
+missing.
@end itemize
-You have been warned! But more than a disclaimer, this is an invitation
-to report issues (and success stories!), and to join us in improving it.
-@xref{Contributing}, for more info.
+More than a disclaimer, this is an invitation to report issues (and success
+stories!), and to join us in improving it. @xref{Contributing}, for more
+info.
@node Hardware Considerations
driver, and those using Broadcom/AirForce chips (BCM43xx with
Wireless-Core Revision 5), which corresponds to the @code{b43-open}
Linux-libre driver. Free firmware exists for both and is available
-out-of-the-box on Guix System, as part of @var{%base-firmware}
+out-of-the-box on Guix System, as part of @code{%base-firmware}
(@pxref{operating-system Reference, @code{firmware}}).
@cindex RYF, Respects Your Freedom
An ISO-9660 installation image that can be written to a USB stick or
burnt to a DVD can be downloaded from
-@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz},
+@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.@var{system}.iso.xz},
where @var{system} is one of:
@table @code
authenticity of the image against it, along these lines:
@example
-$ wget https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig
+$ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig
$ gpg --verify guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig
@end example
ip a
@end example
-@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
+@c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
Wired interfaces have a name starting with @samp{e}; for example, the
interface corresponding to the first on-board Ethernet controller is
called @samp{eno1}. Wireless interfaces have a name starting with
virtual private server (VPS) rather than on your beloved machine, this
section is for you.
-To boot a @uref{http://qemu.org/,QEMU} VM for installing Guix System in a
+To boot a @uref{https://qemu.org/,QEMU} VM for installing Guix System in a
disk image, follow these steps:
@enumerate
@section Building the Installation Image for ARM Boards
Many ARM boards require a specific variant of the
-@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
+@uref{https://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
If you build a disk image and the bootloader is not available otherwise
(on another boot drive etc), it's advisable to build an image that
with it):
@example
-guix package -i emacs-guix
+guix install emacs-guix
@end example
@menu
@example
guix package @var{options}
@end example
+
@cindex transactions
Primarily, @var{options} specifies the operations to be performed during
the transaction. Upon completion, a new profile is created, but
guix package -r lua -i guile guile-cairo
@end example
+@cindex aliases, for @command{guix package}
+For your convenience, we also provide the following aliases:
+
+@itemize
+@item
+@command{guix search} is an alias for @command{guix package -s},
+@item
+@command{guix install} is an alias for @command{guix package -i},
+@item
+@command{guix remove} is an alias for @command{guix package -r},
+@item
+and @command{guix upgrade} is an alias for @command{guix package -u}.
+@end itemize
+
+These aliases are less expressive than @command{guix package} and provide
+fewer options, so in some cases you'll probably want to use @command{guix
+package} directly.
+
@command{guix package} also supports a @dfn{declarative approach}
whereby the user specifies the exact set of packages to be available and
passes it @i{via} the @option{--manifest} option
@file{$HOME/.guix-profile/bin} to their @code{PATH} environment
variable, and so on.
@cindex search paths
-If you are not using the Guix System Distribution, consider adding the
+If you are not using Guix System, consider adding the
following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
shells get all the right environment variable definitions:
@dots{}
@end example
-It is also possible to refine search results using several @code{-s}
-flags. For example, the following command returns a list of board
-games:
+It is also possible to refine search results using several @code{-s} flags to
+@command{guix package}, or several arguments to @command{guix search}. For
+example, the following command returns a list of board games (this time using
+the @command{guix search} alias):
@example
-$ guix package -s '\<board\>' -s game | recsel -p name
+$ guix search '\<board\>' game | recsel -p name
name: gnubg
@dots{}
@end example
libraries, and prints the name and synopsis of the matching packages:
@example
-$ guix package -s crypto -s library | \
+$ guix search crypto library | \
recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
@end example
your system has unpatched security vulnerabilities.
Substitutes from the official build farm are enabled by default when
-using the Guix System Distribution (@pxref{GNU Distribution}). However,
+using Guix System (@pxref{GNU Distribution}). However,
they are disabled by default when using Guix on a foreign distribution,
unless you have explicitly enabled them via one of the recommended
installation steps (@pxref{Installation}). The following paragraphs
Often, packages defined in Guix have a single @dfn{output}---i.e., the
source package leads to exactly one directory in the store. When running
-@command{guix package -i glibc}, one installs the default output of the
+@command{guix install glibc}, one installs the default output of the
GNU libc package; the default output is called @code{out}, but its name
can be omitted as shown in this command. In this particular case, the
default output of @code{glibc} contains all the C header files, shared
which contains everything but the documentation, one would run:
@example
-guix package -i glib
+guix install glib
@end example
@cindex documentation
The command to install its documentation is:
@example
-guix package -i glib:doc
+guix install glib:doc
@end example
Some packages install programs with different ``dependency footprints''.
includes default user profiles; by default, the symlinks under
@file{/var/guix/gcroots} represent these GC roots. New GC roots can be
added with @command{guix build --root}, for example (@pxref{Invoking
-guix build}).
+guix build}). The @command{guix gc --list-roots} command lists them.
Prior to running @code{guix gc --collect-garbage} to make space, it is
often useful to remove old generations from user profiles; that way, old
When @var{free} or more is already available in @file{/gnu/store}, do
nothing and exit immediately.
+@item --delete-generations[=@var{duration}]
+@itemx -d [@var{duration}]
+Before starting the garbage collection process, delete all the generations
+older than @var{duration}, for all the user profiles; when run as root, this
+applies to all the profiles @emph{of all the users}.
+
+For example, this command deletes all the generations of all your profiles
+that are older than 2 months (except generations that are current), and then
+proceeds to free space until at least 10 GiB are available:
+
+@example
+guix gc -d 2m -F 10G
+@end example
+
@item --delete
-@itemx -d
+@itemx -D
Attempt to delete all the store files and directories specified as
arguments. This fails if some of the files are not in the store, or if
they are still live.
@option{--cache-failures} (@pxref{Invoking guix-daemon,
@option{--cache-failures}}).
+@item --list-roots
+List the GC roots owned by the user; when run as root, list @emph{all} the GC
+roots.
+
@item --clear-failures
Remove the specified store items from the failed-build cache.
69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{}
@end example
-@ref{Invoking guix describe, @command{guix describe}}, for other ways to
+@xref{Invoking guix describe, @command{guix describe}}, for other ways to
describe the current status of Guix.
This @code{~/.config/guix/current} profile works like any other profile
@item --url=@var{url}
@itemx --commit=@var{commit}
@itemx --branch=@var{branch}
-Download code from the specified @var{url}, at the given @var{commit} (a valid
-Git commit ID represented as a hexadecimal string), or @var{branch}.
+Download code for the @code{guix} channel from the specified @var{url}, at the
+given @var{commit} (a valid Git commit ID represented as a hexadecimal
+string), or @var{branch}.
@cindex @file{channels.scm}, configuration file
@cindex configuration file for channels
evaluates to a list of channel objects. @xref{Channels}, for more
information.
+@item --news
+@itemx -N
+Display the list of packages added or upgraded since the previous generation.
+
+This is the same information as displayed upon @command{guix pull} completion,
+but without ellipses; it is also similar to the output of @command{guix pull
+-l} for the last generation (see below).
+
@item --list-generations[=@var{pattern}]
@itemx -l [@var{pattern}]
List all the generations of @file{~/.config/guix/current} or, if @var{pattern}
The syntax of @var{pattern} is the same as with @code{guix package
--list-generations} (@pxref{Invoking guix package}).
-@ref{Invoking guix describe}, for a way to display information about the
+@xref{Invoking guix describe}, for a way to display information about the
current generation only.
@item --profile=@var{profile}
The list of authorized keys is kept in the human-editable file
@file{/etc/guix/acl}. The file contains
-@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
+@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
s-expressions''} and is structured as an access-control list in the
-@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
+@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
(SPKI)}.
@item --extract=@var{directory}
directory outside the container is mapped inside the container.
Additionally, unless overridden with @code{--user}, a dummy home
directory is created that matches the current user's home directory, and
-@file{/etc/passwd} is configured accordingly. The spawned process runs
-as the current user outside the container, but has root privileges in
-the context of the container.
+@file{/etc/passwd} is configured accordingly.
+
+The spawned process runs as the current user outside the container. Inside
+the container, it has the same UID and GID as the current user, unless
+@option{--user} is passed (see below.)
@item --network
@itemx -N
@itemx -u @var{user}
For containers, use the username @var{user} in place of the current
user. The generated @file{/etc/passwd} entry within the container will
-contain the name @var{user}; the home directory will be
-@file{/home/USER}; and no user GECOS data will be copied. @var{user}
+contain the name @var{user}, the home directory will be
+@file{/home/@var{user}}, and no user GECOS data will be copied. Furthermore,
+the UID and GID inside the container are 1000. @var{user}
need not exist on the system.
Additionally, any shared or exposed path (see @code{--share} and
@noindent
The result is a SquashFS file system image that can either be mounted or
directly be used as a file system container image with the
-@uref{http://singularity.lbl.gov, Singularity container execution
+@uref{https://singularity.lbl.gov, Singularity container execution
environment}, using commands like @command{singularity shell} or
@command{singularity exec}.
Recording such ``silent'' metadata in the output thus potentially breaks the
source-to-binary bitwise reproducibility property.
+@item --root=@var{file}
+@itemx -r @var{file}
+@cindex garbage collector root, for packs
+Make @var{file} a symlink to the resulting pack, and register it as a garbage
+collector root.
+
@item --localstatedir
@itemx --profile-name=@var{name}
Include the ``local state directory'', @file{/var/guix}, in the resulting
The @code{(gnu packages @dots{})} module name space is
automatically scanned for packages by the command-line tools. For
-instance, when running @code{guix package -i emacs}, all the @code{(gnu
+instance, when running @code{guix install emacs}, all the @code{(gnu
packages @dots{})} modules are scanned until one that exports a package
object whose name is @code{emacs} is found. This package search
facility is implemented in the @code{(gnu packages)} module.
(inputs `(("gawk" ,gawk)))
(synopsis "Hello, GNU world: An example GNU package")
(description "Guess what GNU Hello prints!")
- (home-page "http://www.gnu.org/software/hello/")
+ (home-page "https://www.gnu.org/software/hello/")
(license gpl3+)))
@end example
@var{target} must be a valid GNU triplet denoting the target hardware
and operating system, such as @code{"mips64el-linux-gnu"}
-(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
-Configure and Build System}).
+(@pxref{Specifying Target Triplets,,, autoconf, Autoconf}).
@end deffn
@cindex package transformations
library code they depend on at run time, run-time dependencies must be
listed in @code{propagated-inputs} rather than @code{inputs}.
-@item @code{self-native-input?} (default: @code{#f})
-This is a Boolean field telling whether the package should use itself as
-a native input when cross-compiling.
-
@item @code{outputs} (default: @code{'("out")})
The list of output names of the package. @xref{Packages with Multiple
Outputs}, for typical uses of additional outputs.
@end table
@end deftp
+@deffn {Scheme Syntax} this-package
+When used in the @emph{lexical scope} of a package field definition, this
+identifier resolves to the package being defined.
+
+The example below shows how to add a package as a native input of itself when
+cross-compiling:
+
+@example
+(package
+ (name "guile")
+ ;; ...
+
+ ;; When cross-compiled, Guile, for example, depends on
+ ;; a native version of itself. Add it here.
+ (native-inputs (if (%current-target-system)
+ `(("self" ,this-package))
+ '())))
+@end example
+
+It is an error to refer to @code{this-package} outside a package definition.
+@end deffn
@node origin Reference
@subsection @code{origin} Reference
@defvr {Scheme Variable} ant-build-system
This variable is exported by @code{(guix build-system ant)}. It
implements the build procedure for Java packages that can be built with
-@url{http://ant.apache.org/, Ant build tool}.
+@url{https://ant.apache.org/, Ant build tool}.
It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
provided by the @code{icedtea} package to the set of inputs. Different
@uref{https://www.rust-lang.org, Rust programming language}.
In its @code{configure} phase, this build system replaces dependencies
-specified in the @file{Carto.toml} file with inputs to the Guix package.
+specified in the @file{Cargo.toml} file with inputs to the Guix package.
The @code{install} phase installs the binaries, and it also installs the
source code and @file{Cargo.toml} file.
@end defvr
@defvr {Scheme Variable} cmake-build-system
This variable is exported by @code{(guix build-system cmake)}. It
implements the build procedure for packages using the
-@url{http://www.cmake.org, CMake build tool}.
+@url{https://www.cmake.org, CMake build tool}.
It automatically adds the @code{cmake} package to the set of inputs.
Which package is used can be specified with the @code{#:cmake}
The @code{#:jbuild?} parameter can be passed to use the @code{jbuild}
command instead of the more recent @code{dune} command while building
a package. Its default value is @code{#f}.
+
+The @code{#:package} parameter can be passed to specify a package name, which
+is useful when a package contains multiple packages and you want to build
+only one of them. This is equivalent to passing the @code{-p} argument to
+@code{dune}.
@end defvr
@defvr {Scheme Variable} go-build-system
@defvr {Scheme Variable} r-build-system
This variable is exported by @code{(guix build-system r)}. It
-implements the build procedure used by @uref{http://r-project.org, R}
+implements the build procedure used by @uref{https://r-project.org, R}
packages, which essentially is little more than running @code{R CMD
INSTALL --library=/gnu/store/@dots{}} in an environment where
@code{R_LIBS_SITE} contains the paths to all R package inputs. Tests
@code{tools::testInstalledPackage}.
@end defvr
+@defvr {Scheme Variable} rakudo-build-system
+This variable is exported by @code{(guix build-system rakudo)}. It
+implements the build procedure used by @uref{https://rakudo.org/,
+Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the
+package to @code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and
+installs the binaries, library files and the resources, as well as wrap
+the files under the @code{bin/} directory. Tests can be skipped by
+passing @code{#f} to the @code{tests?} parameter.
+
+Which rakudo package is used can be specified with @code{rakudo}.
+Which perl6-tap-harness package used for the tests can be specified with
+@code{#:prove6} or removed by passing @code{#f} to the
+@code{with-prove6?} parameter.
+Which perl6-zef package used for tests and installing can be specified
+with @code{#:zef} or removed by passing @code{#f} to the
+@code{with-zef?} parameter.
+@end defvr
+
@defvr {Scheme Variable} texlive-build-system
This variable is exported by @code{(guix build-system texlive)}. It is
used to build TeX packages in batch mode with a specified engine. The
@defvr {Scheme Variable} meson-build-system
This variable is exported by @code{(guix build-system meson)}. It
implements the build procedure for packages that use
-@url{http://mesonbuild.com, Meson} as their build system.
+@url{https://mesonbuild.com, Meson} as their build system.
It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
of inputs, and they can be changed with the parameters @code{#:meson}
@end table
@end defvr
+@defvr {Scheme Variable} linux-module-build-system
+@var{linux-module-build-system} allows building Linux kernel modules.
+
+@cindex build phases
+This build system is an extension of @var{gnu-build-system}, but with the
+following phases changed:
+
+@table @code
+
+@item configure
+This phase configures the environment so that the Linux kernel's Makefile
+can be used to build the external kernel module.
+
+@item build
+This phase uses the Linux kernel's Makefile in order to build the external
+kernel module.
+
+@item install
+This phase uses the Linux kernel's Makefile in order to install the external
+kernel module.
+@end table
+
+It is possible and useful to specify the Linux kernel to use for building
+the module (in the "arguments" form of a package using the
+linux-module-build-system, use the key #:linux to specify it).
+@end defvr
+
Lastly, for packages that do not need anything as sophisticated, a
``trivial'' build system is provided. It is trivial in the sense that
it provides basically no support: it does not pull any implicit inputs,
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
-the system type of the build host.
+the system type of the build host. The @command{guix build} command allows
+you to repeat this option several times, in which case it builds for all the
+specified systems; other commands ignore extraneous @option{-s} options.
@quotation Note
The @code{--system} flag is for @emph{native} compilation and must not
@item --target=@var{triplet}
@cindex cross-compilation
Cross-build for @var{triplet}, which must be a valid GNU triplet, such
-as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
+as @code{"mips64el-linux-gnu"} (@pxref{Specifying Target Triplets, GNU
configuration triplets,, autoconf, Autoconf}).
@anchor{build-check}
@cindex CRAN
@cindex Bioconductor
Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
-central repository for the @uref{http://r-project.org, GNU@tie{}R
+central repository for the @uref{https://r-project.org, GNU@tie{}R
statistical and graphical environment}.
Information is extracted from the @code{DESCRIPTION} file of the package.
@item texlive
@cindex TeX Live
@cindex CTAN
-Import metadata from @uref{http://www.ctan.org/, CTAN}, the
+Import metadata from @uref{https://www.ctan.org/, CTAN}, the
comprehensive TeX archive network for TeX packages that are part of the
@uref{https://www.tug.org/texlive/, TeX Live distribution}.
@item nix
Import metadata from a local copy of the source of the
-@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
+@uref{https://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
relies on the @command{nix-instantiate} command of
-@uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
+@uref{https://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
typically written in a mixture of Nix-language and Bash code. This
command only imports the high-level package structure that is written in
the Nix language. It normally includes all the basic fields of a
are:
@itemize -
@item
-@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
+@uref{https://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
identifier. This is the default.
Packages from @code{elpa.gnu.org} are signed with one of the keys
signatures,, emacs, The GNU Emacs Manual}).
@item
-@uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the
+@uref{https://stable.melpa.org/packages, MELPA-Stable}, selected by the
@code{melpa-stable} identifier.
@item
-@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa}
+@uref{https://melpa.org/packages, MELPA}, selected by the @code{melpa}
identifier.
@end itemize
@item kernel.org
the updater for packages hosted on kernel.org;
@item elpa
-the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
+the updater for @uref{https://elpa.gnu.org/, ELPA} packages;
@item cran
the updater for @uref{https://cran.r-project.org/, CRAN} packages;
@item bioconductor
the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
@item cpan
-the updater for @uref{http://www.cpan.org/, CPAN} packages;
+the updater for @uref{https://www.cpan.org/, CPAN} packages;
@item pypi
the updater for @uref{https://pypi.python.org, PyPI} packages.
@item gem
(cpe-version . "2.3")))
@end example
-@c See <http://www.openwall.com/lists/oss-security/2017/03/15/3>.
+@c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>.
Some entries in the CVE database do not specify which version of a
package they apply to, and would thus ``stick around'' forever. Package
developers who found CVE alerts and verified they can be ignored can
produced by @command{guix size}}
This option requires that
-@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be
+@uref{https://wingolog.org/software/guile-charting/, Guile-Charting} be
installed and visible in Guile's module search path. When that is not
the case, @command{guix size} fails as it tries to load it.
mental model of the package DAG, so the @command{guix graph} command
provides a visual representation of the DAG. By default,
@command{guix graph} emits a DAG representation in the input format of
-@uref{http://www.graphviz.org/, Graphviz}, so its output can be passed
+@uref{https://www.graphviz.org/, Graphviz}, so its output can be passed
directly to the @command{dot} command of Graphviz. It can also emit an
HTML page with embedded JavaScript code to display a ``chord diagram''
in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
emit Cypher queries to construct a graph in a graph database supporting
-the @uref{http://www.opencypher.org/, openCypher} query language.
+the @uref{https://www.opencypher.org/, openCypher} query language.
The general syntax is:
@example
guix graph --type=reverse-package ocaml
@end example
-...@: yields the graph of packages that depend on OCaml.
+...@: yields the graph of packages that @emph{explicitly} depend on OCaml (if
+you are also interested in cases where OCaml is an implicit dependency, see
+@code{reverse-bag} below.)
Note that for core packages this can yield huge graphs. If all you want
is to know the number of packages that depend on a given package, use
@item bag-with-origins
Similar to @code{bag}, but also showing origins and their dependencies.
+@item reverse-bag
+This shows the @emph{reverse} DAG of packages. Unlike @code{reverse-package},
+it also takes implicit dependencies into account. For example:
+
+@example
+guix graph -t reverse-bag dune
+@end example
+
+@noindent
+...@: yields the graph of all packages that depend on Dune, directly or
+indirectly. Since Dune is an @emph{implicit} dependency of many packages
+@i{via} @code{dune-build-system}, this shows a large number of packages,
+whereas @code{reverse-package} would show very few if any.
+
@item derivation
This is the most detailed representation: It shows the DAG of
derivations (@pxref{Derivations}) and plain store items. Compared to
innocuous since the command only gathers statistics and cannot install
those substitutes.
-Among other things, it is possible to query specific system types and
-specific package sets. The available options are listed below.
+The general syntax is:
+
+@example
+guix weather @var{options}@dots{} [@var{packages}@dots{}]
+@end example
+
+When @var{packages} is omitted, @command{guix weather} checks the availability
+of substitutes for @emph{all} the packages, or for those specified with
+@option{--manifest}; otherwise it only considers the specified packages. It
+is also possible to query specific system types with @option{--system}. The
+available options are listed below.
@table @code
@item --substitute-urls=@var{urls}
@var{b} usually lacks substitutes as well. The result looks like this:
@example
-$ guix weather --substitute-urls=https://ci.guix.info -c 10
+$ guix weather --substitute-urls=@value{SUBSTITUTE-URL} -c 10
computing 8,983 package derivations for x86_64-linux...
-looking for 9,343 store items on https://ci.guix.info...
-updating substitutes from 'https://ci.guix.info'... 100.0%
-https://ci.guix.info
+looking for 9,343 store items on @value{SUBSTITUTE-URL}...
+updating substitutes from '@value{SUBSTITUTE-URL}'... 100.0%
+@value{SUBSTITUTE-URL}
64.7% substitutes available (6,047 out of 9,343)
@dots{}
-2502 packages are missing from 'https://ci.guix.info' for 'x86_64-linux', among which:
+2502 packages are missing from '@value{SUBSTITUTE-URL}' for 'x86_64-linux', among which:
58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0
46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1
37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008
@chapter System Configuration
@cindex system configuration
-The Guix System Distribution supports a consistent whole-system configuration
+Guix System supports a consistent whole-system configuration
mechanism. By that we mean that all aspects of the global system
configuration---such as the available system services, timezone and
locale settings, user accounts---are declared in a single place. Such
* File Systems:: Configuring file system mounts.
* Mapped Devices:: Block device extra processing.
* User Accounts:: Specifying user accounts.
+* Keyboard Layout:: How the system interprets key strokes.
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
only the Linux-libre kernel is supported. In the future, it will be
possible to use the GNU@tie{}Hurd.}.
-@item @code{kernel-arguments} (default: @code{'()})
+@item @code{kernel-arguments} (default: @code{'("quiet")})
List of strings or gexps representing additional arguments to pass on
the command-line of the kernel---e.g., @code{("console=ttyS0")}.
@item @code{bootloader}
The system bootloader configuration object. @xref{Bootloader Configuration}.
+@item @code{label}
+This is the label (a string) as it appears in the bootloader's menu entry.
+The default label includes the kernel name and version.
+
+@item @code{keyboard-layout} (default: @code{#f})
+This field specifies the keyboard layout to use in the console. It can be
+either @code{#f}, in which case the default keyboard layout is used (usually
+US English), or a @code{<keyboard-layout>} record.
+
+This keyboard layout is in effect as soon as the kernel has booted. For
+instance, it is the keyboard layout in effect when you type a passphrase if
+your root file system is on a @code{luks-device-mapping} mapped device
+(@pxref{Mapped Devices}).
+
+@quotation Note
+This does @emph{not} specify the keyboard layout used by the bootloader, nor
+that used by the graphical display server. @xref{Bootloader Configuration},
+for information on how to specify the bootloader's keyboard layout. @xref{X
+Window}, for information on how to specify the keyboard layout used by the X
+Window System.
+@end quotation
+
@item @code{initrd-modules} (default: @code{%base-initrd-modules})
@cindex initrd
@cindex initial RAM disk
@item @code{services} (default: @var{%base-services})
A list of service objects denoting system services. @xref{Services}.
+@cindex essential services
+@item @code{essential-services} (default: ...)
+The list of ``essential services''---i.e., things like instances of
+@code{system-service-type} and @code{host-name-service-type} (@pxref{Service
+Reference}), which are derived from the operating system definition itself.
+As a user you should @emph{never} need to touch this field.
+
@item @code{pam-services} (default: @code{(base-pam-services)})
@cindex PAM
@cindex pluggable authentication modules
@code{sudo}.
@end table
+
+@deffn {Scheme Syntax} this-operating-system
+When used in the @emph{lexical scope} of an operating system field definition,
+this identifier resolves to the operating system being defined.
+
+The example below shows how to refer to the operating system being defined in
+the definition of the @code{label} field:
+
+@example
+(use-modules (gnu) (guix))
+
+(operating-system
+ ;; ...
+ (label (package-full-name
+ (operating-system-kernel this-operating-system))))
+@end example
+
+It is an error to refer to @code{this-operating-system} outside an operating
+system definition.
+@end deffn
+
@end deftp
@node File Systems
This is a list of symbols denoting mount flags. Recognized flags
include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
access to special files), @code{no-suid} (ignore setuid and setgid
-bits), and @code{no-exec} (disallow program execution.)
+bits), @code{no-atime} (do not update file access times), and @code{no-exec}
+(disallow program execution). @xref{Mount-Unmount-Remount,,, libc, The GNU C
+Library Reference Manual}, for more information on these flags.
@item @code{options} (default: @code{#f})
-This is either @code{#f}, or a string denoting mount options.
+This is either @code{#f}, or a string denoting mount options passed to the
+file system driver. @xref{Mount-Unmount-Remount,,, libc, The GNU C Library
+Reference Manual}, for details and run @command{man 8 mount} for options for
+various file systems.
@item @code{mount?} (default: @code{#t})
This value indicates whether to automatically mount the file system when
@example
(user-account
(name "charlie")
- (home-directory "/home/charlie")
(group "users")
;; Specify a SHA-512-hashed initial password.
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
@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
+@uref{https://www.iana.org/assignments/character-sets, as defined by
IANA}.
@end table
* 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.
@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 types
-their login name.
+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
@deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
Run @var{udev}, which populates the @file{/dev} directory dynamically.
udev rules can be provided as a list of files through the @var{rules}
-variable. The procedures @var{udev-rule} and @var{file->udev-rule} from
+variable. The procedures @code{udev-rule} and @code{file->udev-rule} from
@code{(gnu services base)} simplify the creation of such rule files.
@end deffn
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
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}.
+@uref{https://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''
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.
+will listen to each sensor that actually exists and ignore non-existent ones.
See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
information.
@item @code{server} (default: @var{%ntp-servers})
files.
@deffn {Scheme Variable} rsync-service-type
-This is the type for the @uref{https://rsync.samba.org, rsync} rsync daemon,
+This is the service type for the @uref{https://rsync.samba.org, rsync} daemon,
+The value for this service type is a
@command{rsync-configuration} record as in this example:
@example
@defvr {Scheme Variable} avahi-service-type
This is the service that runs @command{avahi-daemon}, a system-wide
mDNS/DNS-SD responder that allows for service discovery and
-``zero-configuration'' host name lookups (see @uref{http://avahi.org/}).
+``zero-configuration'' host name lookups (see @uref{https://avahi.org/}).
Its value must be a @code{zero-configuration} record---see below.
This service extends the name service cache daemon (nscd) so that it can
@end deftp
@deffn {Scheme Variable} openvswitch-service-type
-This is the type of the @uref{http://www.openvswitch.org, Open vSwitch}
+This is the type of the @uref{https://www.openvswitch.org, Open vSwitch}
service, whose value should be an @code{openvswitch-configuration}
object.
@end deffn
Support for the X Window graphical display system---specifically
Xorg---is provided by the @code{(gnu services xorg)} module. Note that
there is no @code{xorg-service} procedure. Instead, the X server is
-started by the @dfn{login manager}, by default SLiM.
+started by the @dfn{login manager}, by default the GNOME Display Manager (GDM).
+
+@cindex GDM
+@cindex GNOME, login manager
+GDM of course allows users to log in into window managers and desktop
+environments other than GNOME; for those using GNOME, GDM is required for
+features such as automatic screen locking.
@cindex window manager
To use X11, you must install at least one @dfn{window manager}---for
by adding it to the @code{packages} field of your operating system
definition (@pxref{operating-system Reference, system-wide packages}).
-@defvr {Scheme Variable} slim-service-type
-This is the type for the SLiM graphical login manager for X11.
+@defvr {Scheme Variable} gdm-service-type
+This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME
+Desktop Manager} (GDM), a program that manages graphical display servers and
+handles graphical user logins. Its value must be a @code{gdm-configuration}
+(see below.)
@cindex session types (X11)
@cindex X11 session types
-SLiM looks for @dfn{session types} described by the @file{.desktop} files in
-@file{/run/current-system/profile/share/xsessions} and allows users to
-choose a session from the log-in screen using @kbd{F1}. Packages such
-as @code{xfce}, @code{sawfish}, and @code{ratpoison} provide
-@file{.desktop} files; adding them to the system-wide set of packages
-automatically makes them available at the log-in screen.
+GDM looks for @dfn{session types} described by the @file{.desktop} files in
+@file{/run/current-system/profile/share/xsessions} and allows users to choose
+a session from the log-in screen. Packages such as @code{gnome}, @code{xfce},
+and @code{i3} provide @file{.desktop} files; adding them to the system-wide
+set of packages automatically makes them available at the log-in screen.
In addition, @file{~/.xsession} files are honored. When available,
@file{~/.xsession} must be an executable that starts a window manager
and/or other X clients.
@end defvr
+@deftp {Data Type} gdm-configuration
+@table @asis
+@item @code{auto-login?} (default: @code{#f})
+@itemx @code{default-user} (default: @code{#f})
+When @code{auto-login?} is false, GDM presents a log-in screen.
+
+When @code{auto-login?} is true, GDM logs in directly as
+@code{default-user}.
+
+@item @code{gnome-shell-assets} (default: ...)
+List of GNOME Shell assets needed by GDM: icon theme, fonts, etc.
+
+@item @code{xorg-configuration} (default: @code{(xorg-configuration)})
+Configuration of the Xorg graphical server.
+
+@item @code{xsession} (default: @code{(xinitrc)})
+Script to run before starting a X session.
+
+@item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper})
+File name of the @code{dbus-daemon} executable.
+
+@item @code{gdm} (default: @code{gdm})
+The GDM package to use.
+@end table
+@end deftp
+
+@defvr {Scheme Variable} slim-service-type
+This is the type for the SLiM graphical login manager for X11.
+
+Like GDM, SLiM looks for session types described by @file{.desktop} files and
+allows users to choose a session from the log-in screen using @kbd{F1}. It
+also honors @file{~/.xsession} files.
+
+Unlike GDM, SLiM does not spawn the user session on a different VT after
+logging in, which means that you can only start one graphical session. If you
+want to be able to run multiple graphical sessions at the same time you have
+to add multiple SLiM services to your system services. The following example
+shows how to replace the default GDM service with two SLiM services on tty7
+and tty8.
+
+@lisp
+(use-modules (gnu services)
+ (gnu services desktop)
+ (gnu services xorg)
+ (srfi srfi-1)) ;for 'remove'
+
+(operating-system
+ ;; ...
+ (services (cons* (service slim-service-type (slim-configuration
+ (display ":0")
+ (vt "vt7")))
+ (service slim-service-type (slim-configuration
+ (display ":1")
+ (vt "vt8")))
+ (remove (lambda (service)
+ (eq? (service-kind service) gdm-service-type))
+ %desktop-services))))
+@end lisp
+
+@end defvr
+
@deftp {Data Type} slim-configuration
Data type representing the configuration of @code{slim-service-type}.
false, you will be unable to log in.
@end quotation
-@item @code{startx} (default: @code{(xorg-start-command)})
-The command used to start the X11 graphical server.
+@item @code{xorg-configuration} (default @code{(xorg-configuration)})
+Configuration of the Xorg graphical server.
+
+@item @code{display} (default @code{":0"})
+The display on which to start the Xorg graphical server.
+
+@item @code{vt} (default @code{"vt7"})
+The VT on which to start the Xorg graphical server.
@item @code{xauth} (default: @code{xauth})
The XAuth package to use.
@item @code{default-path} (default "/run/current-system/profile/bin")
Default PATH to use.
-@item @code{minimum-uid} (default 1000)
-Minimum UID to display in SDDM.
+@item @code{minimum-uid} (default: 1000)
+Minimum UID displayed in SDDM and allowed for log-in.
-@item @code{maximum-uid} (default 2000)
-Maximum UID to display in SDDM
+@item @code{maximum-uid} (default: 2000)
+Maximum UID to display in SDDM.
@item @code{remember-last-user?} (default #t)
Remember last user.
@item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions")
Directory to look for desktop files starting wayland sessions.
-@item @code{xorg-server-path} (default @code{xorg-start-command})
-Path to xorg-server.
+@item @code{xorg-configuration} (default @code{(xorg-configuration)})
+Configuration of the Xorg graphical server.
@item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")})
Path to xauth.
@item @code{minimum-vt} (default: 7)
Minimum VT to use.
-@item @code{xserver-arguments} (default "-nolisten tcp")
-Arguments to pass to xorg-server.
-
@item @code{auto-login-user} (default "")
User to use for auto-login.
@end example
@end deffn
-@deffn {Scheme Procedure} xorg-start-command [#:guile] @
- [#:modules %default-xorg-modules] @
- [#:fonts %default-xorg-fonts] @
- [#:configuration-file (xorg-configuration-file @dots{})] @
- [#:xorg-server @var{xorg-server}]
- [#:xserver-arguments '("-nolisten" "tcp")]
-Return a @code{startx} script in which @var{modules}, a list of X module
-packages, and @var{fonts}, a list of X font directories, are available. See
-@code{xorg-wrapper} for more details on the arguments. The result should be
-used in place of @code{startx}.
+@cindex Xorg, configuration
+@deftp {Data Type} xorg-configuration
+This data type represents the configuration of the Xorg graphical display
+server. Note that there is not Xorg service; instead, the X server is started
+by a ``display manager'' such as GDM, SDDM, and SLiM. Thus, the configuration
+of these display managers aggregates an @code{xorg-configuration} record.
-Usually the X server is started by a login manager.
-@end deffn
+@table @asis
+@item @code{modules} (default: @code{%default-xorg-modules})
+This is a list of @dfn{module packages} loaded by the Xorg
+server---e.g., @code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on.
-@cindex @code{-listen tcp}, for X11.
-This procedure is useful to override command line options for the X server,
-such as having it listen to over TCP:
+@item @code{fonts} (default: @code{%default-xorg-fonts})
+This is a list of font directories to add to the server's @dfn{font path}.
-@example
-(operating-system
- ...
- (services
- (modify-services %desktop-services
- (slim-service-type config =>
- (slim-configuration
- (inherit config)
- (startx (xorg-start-command
- #:xserver-arguments '("-listen" "tcp"))))))))
-@end example
-
-@deffn {Scheme Procedure} xorg-configuration-file @
- [#:modules %default-xorg-modules] @
- [#:fonts %default-xorg-fonts] @
- [#:drivers '()] [#:resolutions '()] [#:extra-config '()]
-Return a configuration file for the Xorg server containing search paths for
-all the common drivers.
-
-@var{modules} must be a list of @dfn{module packages} loaded by the Xorg
-server---e.g., @code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on.
-@var{fonts} must be a list of font directories to add to the server's
-@dfn{font path}.
+@item @code{drivers} (default: @code{'()})
+This must be either the empty list, in which case Xorg chooses a graphics
+driver automatically, or a list of driver names that will be tried in this
+order---e.g., @code{("modesetting" "vesa")}.
-@var{drivers} must be either the empty list, in which case Xorg chooses a
-graphics driver automatically, or a list of driver names that will be tried in
-this order---e.g., @code{("modesetting" "vesa")}.
+@item @code{resolutions} (default: @code{'()})
+When @code{resolutions} is the empty list, Xorg chooses an appropriate screen
+resolution. Otherwise, it must be a list of resolutions---e.g., @code{((1024
+768) (640 480))}.
-Likewise, when @var{resolutions} is the empty list, Xorg chooses an
-appropriate screen resolution; otherwise, it must be a list of
-resolutions---e.g., @code{((1024 768) (640 480))}.
+@cindex keyboard layout, for Xorg
+@cindex keymap, for Xorg
+@item @code{keyboard-layout} (default: @code{#f})
+If this is @code{#f}, Xorg uses the default keyboard layout---usually US
+English (``qwerty'') for a 105-key PC keyboard.
-Last, @var{extra-config} is a list of strings or objects appended to the
-configuration file. It is used to pass extra text to be
-added verbatim to the configuration file.
+Otherwise this must be a @code{keyboard-layout} object specifying the keyboard
+layout in use when Xorg is running. @xref{Keyboard Layout}, for more
+information on how to specify the keyboard layout.
-@cindex keymap
-@cindex keyboard layout
-This procedure is especially useful to configure a different keyboard layout
-than the default US keymap. For instance, to use the ``bépo'' keymap by
-default on the display manager:
+@item @code{extra-config} (default: @code{'()})
+This is a list of strings or objects appended to the configuration file. It
+is used to pass extra text to be added verbatim to the configuration file.
-@example
-(define bepo-evdev
- "Section \"InputClass\"
- Identifier \"evdev keyboard catchall\"
- Driver \"evdev\"
- MatchIsKeyboard \"on\"
- Option \"xkb_layout\" \"fr\"
- Option \"xkb_variant\" \"bepo\"
-EndSection")
+@item @code{server} (default: @code{xorg-server})
+This is the package providing the Xorg server.
-(operating-system
- ...
- (services
- (modify-services %desktop-services
- (slim-service-type config =>
- (slim-configuration
- (inherit config)
- (startx (xorg-start-command
- #:configuration-file
- (xorg-configuration-file
- #:extra-config
- (list bepo-evdev)))))))))
-@end example
-
-The @code{MatchIsKeyboard} line specifies that we only apply the configuration
-to keyboards. Without this line, other devices such as touchpad may not work
-correctly because they will be attached to the wrong driver. In this example,
-the user typically used @code{setxkbmap fr bepo} to set their favorite keymap
-once logged in. The first argument corresponds to the layout, while the second
-argument corresponds to the variant. The @code{xkb_variant} line can be omitted
-to select the default variant.
+@item @code{server-arguments} (default: @code{%default-xorg-server-arguments})
+This is the list of command-line arguments to pass to the X server. The
+default is @code{-nolisten tcp}.
+@end table
+@end deftp
+
+@deffn {Scheme Procedure} set-xorg-configuration @var{config} @
+ [@var{login-manager-service-type}]
+Tell the log-in manager (of type @var{login-manager-service-type}) to use
+@var{config}, an @code{<xorg-configuration>} record.
+
+Since the Xorg configuration is embedded in the log-in manager's
+configuration---e.g., @code{gdm-configuration}---this procedure provides a
+shorthand to set the Xorg configuration.
+@end deffn
+
+@deffn {Scheme Procedure} xorg-start-command [@var{config}]
+Return a @code{startx} script in which the modules, fonts, etc. specified
+in @var{config}, are available. The result should be used in place of
+@code{startx}.
+
+Usually the X server is started by a login manager.
@end deffn
+
@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}]
Add @var{package}, a package for a screen locker or screen saver whose
command is @var{program}, to the set of setuid programs and add a PAM entry
@deftypevr {@code{files-configuration} parameter} log-location error-log
Defines the error log filename. Specifying a blank filename disables
-access log generation. The value @code{stderr} causes log entries to be
+error log generation. The value @code{stderr} causes log entries to be
sent to the standard error file when the scheduler is running in the
foreground, or to the system log daemon when run in the background. The
value @code{syslog} causes log entries to be sent to the system log
@deftypevr {@code{files-configuration} parameter} log-location page-log
Defines the page log filename. Specifying a blank filename disables
-access log generation. The value @code{stderr} causes log entries to be
+page log generation. The value @code{stderr} causes log entries to be
sent to the standard error file when the scheduler is running in the
foreground, or to the system log daemon when run in the background. The
value @code{syslog} causes log entries to be sent to the system log
usually useful in the context of a ``desktop'' setup---that is, on a
machine running a graphical display server, possibly with graphical user
interfaces, etc. It also defines services that provide specific desktop
-environments like GNOME, XFCE or MATE.
+environments like GNOME, Xfce or MATE.
To simplify things, the module defines a variable containing the set of
services that users typically expect on a machine with a graphical
adds or adjusts services for a typical ``desktop'' setup.
In particular, it adds a graphical login manager (@pxref{X Window,
-@code{slim-service}}), screen lockers, a network management tool
-(@pxref{Networking Services, @code{network-manager-service-type}}), energy and color
-management services, the @code{elogind} login and seat manager, the
-Polkit privilege service, the GeoClue location service, the
-AccountsService daemon that allows authorized users change system
-passwords, an NTP client (@pxref{Networking Services}), the Avahi
-daemon, and has the name service switch service configured to be able to
-use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}).
+@code{gdm-service-type}}), screen lockers, a network management tool
+(@pxref{Networking Services, @code{network-manager-service-type}}) with modem
+support (@pxref{Networking Services, @code{modem-manager-service-type}}),
+energy and color management services, the @code{elogind} login and seat
+manager, the Polkit privilege service, the GeoClue location service, the
+AccountsService daemon that allows authorized users change system passwords,
+an NTP client (@pxref{Networking Services}), the Avahi daemon, and has the
+name service switch service configured to be able to use @code{nss-mdns}
+(@pxref{Name Service Switch, mDNS}).
@end defvr
The @var{%desktop-services} variable can be used as the @code{services}
field of an @code{operating-system} declaration (@pxref{operating-system
Reference, @code{services}}).
-Additionally, the @code{gnome-desktop-service},
+Additionally, the @code{gnome-desktop-service-type},
@code{xfce-desktop-service}, @code{mate-desktop-service-type} and
-@code{enlightenment-desktop-service-type} procedures can add GNOME, XFCE, MATE
+@code{enlightenment-desktop-service-type} procedures can add GNOME, Xfce, MATE
and/or Enlightenment to a system. To ``add GNOME'' means that system-level
services like the backlight adjustment helpers and the power management
utilities are added to the system, extending @code{polkit} and @code{dbus}
appropriately, allowing GNOME to operate with elevated privileges on a
limited number of special-purpose system interfaces. Additionally,
-adding a service made by @code{gnome-desktop-service} adds the GNOME
-metapackage to the system profile. Likewise, adding the XFCE service
+adding a service made by @code{gnome-desktop-service-type} adds the GNOME
+metapackage to the system profile. Likewise, adding the Xfce service
not only adds the @code{xfce} metapackage to the system profile, but it
also gives the Thunar file manager the ability to open a ``root-mode''
file management window, if the user authenticates using the
The desktop environments in Guix use the Xorg display server by
default. If you'd like to use the newer display server protocol
-called Wayland, you need to use the @code{sddm-service} instead of the
-@code{slim-service} for the graphical login manager. You should then
+called Wayland, you need to use the @code{sddm-service} instead of
+GDM as the graphical login manager. You should then
select the ``GNOME (Wayland)'' session in SDDM. Alternatively you can
also try starting GNOME on Wayland manually from a TTY with the
command ``XDG_SESSION_TYPE=wayland exec dbus-run-session
gnome-session``. Currently only GNOME has support for Wayland.
-@deffn {Scheme Procedure} gnome-desktop-service
-Return a service that adds the @code{gnome} package to the system
-profile, and extends polkit with the actions from
-@code{gnome-settings-daemon}.
-@end deffn
+@defvr {Scheme Variable} gnome-desktop-service-type
+This is the type of the service that adds the @uref{https://www.gnome.org,
+GNOME} desktop environment. Its value is a @code{gnome-desktop-configuration}
+object (see below.)
-@deffn {Scheme Procedure} xfce-desktop-service
-Return a service that adds the @code{xfce} package to the system profile,
-and extends polkit with the ability for @code{thunar} to manipulate the
-file system as root from within a user session, after the user has
-authenticated with the administrator's password.
-@end deffn
+This service adds the @code{gnome} package to the system profile, and extends
+polkit with the actions from @code{gnome-settings-daemon}.
+@end defvr
+
+@deftp {Data Type} gnome-desktop-configuration
+Configuration record for the GNOME desktop environment.
+
+@table @asis
+@item @code{gnome} (default: @code{gnome})
+The GNOME package to use.
+@end table
+@end deftp
+
+@defvr {Scheme Variable} xfce-desktop-service-type
+This is the type of a service to run the @uref{Xfce, https://xfce.org/}
+desktop environment. Its value is an @code{xfce-desktop-configuration} object
+(see below.)
+
+This service adds the @code{xfce} package to the system profile, and
+extends polkit with the ability for @code{thunar} to manipulate the file
+system as root from within a user session, after the user has authenticated
+with the administrator's password.
+@end defvr
+
+@deftp {Data Type} xfce-desktop-configuration
+Configuration record for the Xfce desktop environment.
+
+@table @asis
+@item @code{xfce} (default: @code{xfce})
+The Xfce package to use.
+@end table
+@end deftp
@deffn {Scheme Variable} mate-desktop-service-type
This is the type of the service that runs the @uref{https://mate-desktop.org/,
Configuration record for the MATE desktop environment.
@table @asis
-@item @code{mate} (default @code{mate})
+@item @code{mate} (default: @code{mate})
The MATE package to use.
@end table
@end deftp
@deftp {Data Type} enlightenment-desktop-service-configuration
@table @asis
-@item @code{enlightenment} (default @code{enlightenment})
+@item @code{enlightenment} (default: @code{enlightenment})
The enlightenment package to use.
@end table
@end deftp
-Because the GNOME, XFCE and MATE desktop services pull in so many packages,
+Because the GNOME, Xfce and MATE desktop services pull in so many packages,
the default @code{%desktop-services} variable doesn't include any of
-them by default. To add GNOME, XFCE or MATE, just @code{cons} them onto
+them by default. To add GNOME, Xfce or MATE, just @code{cons} them onto
@code{%desktop-services} in the @code{services} field of your
@code{operating-system}:
(operating-system
...
;; cons* adds items to the list given as its last argument.
- (services (cons* (gnome-desktop-service)
- (xfce-desktop-service)
+ (services (cons* (service gnome-desktop-service-type)
+ (service xfce-desktop-service)
%desktop-services))
...)
@end example
Return a service that runs the ``system bus'', using @var{dbus}, with
support for @var{services}.
-@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
+@uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process communication
facility. Its system bus is used to allow system services to communicate
and to be notified of system-wide events.
@deffn {Scheme Procedure} polkit-service @
[#:polkit @var{polkit}]
Return a service that runs the
-@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
+@uref{https://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
management service}, which allows system administrators to grant access to
privileged operations in a structured way. By querying the Polkit service, a
privileged system component can know when it should grant additional
@end deffn
@defvr {Scheme Variable} upower-service-type
-Service that runs @uref{http://upower.freedesktop.org/, @command{upowerd}}, a
+Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a
system-wide monitor for power consumption and battery levels, with the given
configuration settings.
@end deftp
@deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
-Return a service for @uref{http://udisks.freedesktop.org/docs/latest/,
+Return a service for @uref{https://udisks.freedesktop.org/docs/latest/,
UDisks}, a @dfn{disk management} daemon that provides user interfaces with
notifications and ways to mount/unmount disks. Programs that talk to UDisks
include the @command{udisksctl} command, part of UDisks, and GNOME Disks.
Return a service that runs @command{colord}, a system service with a D-Bus
interface to manage the color profiles of input and output devices such as
screens and scanners. It is notably used by the GNOME Color Manager graphical
-tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web
+tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web
site} for more information.
@end deffn
Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords?
+@deftypevr {@code{dovecot-configuration} parameter} string auth-verbose-passwords
In case of password mismatches, log the attempted password. Valid
values are no, plain and sha1. sha1 can be useful for detecting brute
force password attempts vs. user simply trying the same password over
and over again. You can also truncate the value to n chars by appending
":n" (e.g.@: sha1:6).
-Defaults to @samp{#f}.
+Defaults to @samp{"no"}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
the @code{postmaster} mail to @code{bob} (which subsequently would
deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}).
+@subsubheading GNU Mailutils IMAP4 Daemon
+@cindex GNU Mailutils IMAP4 Daemon
+
+@deffn {Scheme Variable} imap4d-service-type
+This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,,
+mailutils, GNU Mailutils Manual}), whose value should be an
+@code{imap4d-configuration} object as in this example:
+
+@example
+(service imap4d-service-type
+ (imap4d-configuration
+ (config-file (local-file "imap4d.conf"))))
+@end example
+@end deffn
+
+@deftp {Data Type} imap4d-configuration
+Data type representing the configuration of @command{imap4d}.
+
+@table @asis
+@item @code{package} (default: @code{mailutils})
+The package that provides @command{imap4d}.
+
+@item @code{config-file} (default: @code{%default-imap4d-config-file})
+File-like object of the configuration file to use, by default it will listen
+on TCP port 143 of @code{localhost}. @xref{Conf-imap4d,,, mailutils, GNU
+Mailutils Manual}, for details.
+
+@end table
+@end deftp
+
@node Messaging Services
@subsection Messaging Services
@cindex IRC (Internet Relay Chat)
@cindex IRC gateway
-@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC
+@url{https://bitlbee.org,BitlBee} is a gateway that provides an IRC
interface to a variety of messaging protocols such as XMPP.
@defvr {Scheme Variable} bitlbee-service-type
-This is the service type for the @url{http://bitlbee.org,BitlBee} IRC
+This is the service type for the @url{https://bitlbee.org,BitlBee} IRC
gateway daemon. Its value is a @code{bitlbee-configuration} (see
below).
Maximum size in bytes that a user can send in one image message.
@item @code{cert-required?} (default: @code{#f})
-If it is set to @code{#t} clients that use weak password authentification
+If it is set to @code{#t} clients that use weak password authentication
will not be accepted. Users must have completed the certificate wizard to join.
@item @code{remember-channel?} (default: @code{#f})
The @code{krb5-realm} and @code{krb5-configuration} types have many fields.
Only the most commonly used ones are described here.
For a full list, and more detailed explanation of each, see the MIT
-@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
+@uref{https://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
documentation.
@end defvr
@deftp {Data Type} pam-krb5-configuration
-Data type representing the configuration of the Kerberos 5 PAM module
+Data type representing the configuration of the Kerberos 5 PAM module.
This type has the following parameters:
@table @asis
@item @code{pam-krb5} (default: @code{pam-krb5})
@end deftp
-@node Web Services
-@subsection Web Services
+@node LDAP Services
+@subsection LDAP Services
+@cindex LDAP
+@cindex nslcd, LDAP service
-@cindex web
-@cindex www
+The @code{(gnu services authentication)} module provides the
+@code{nslcd-service-type}, which can be used to authenticate against an LDAP
+server. In addition to configuring the service itself, you may want to add
+@code{ldap} as a name service to the Name Service Switch. @xref{Name Service
+Switch} for detailed information.
+
+Here is a simple operating system declaration with a default configuration of
+the @code{nslcd-service-type} and a Name Service Switch configuration that
+consults the @code{ldap} name service last:
+
+@example
+(use-service-modules authentication)
+(use-modules (gnu system nss))
+...
+(operating-system
+ ...
+ (services
+ (cons*
+ (service nslcd-service-type)
+ (service dhcp-client-service-type)
+ %base-services))
+ (name-service-switch
+ (let ((services (list (name-service (name "db"))
+ (name-service (name "files"))
+ (name-service (name "ldap")))))
+ (name-service-switch
+ (inherit %mdns-host-lookup-nss)
+ (password services)
+ (shadow services)
+ (group services)
+ (netgroup services)
+ (gshadow services)))))
+@end example
+
+@c %start of generated documentation for nslcd-configuration
+
+Available @code{nslcd-configuration} fields are:
+
+@deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd
+The @code{nss-pam-ldapd} package to use.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number threads
+The number of threads to start that can handle requests and perform LDAP
+queries. Each thread opens a separate connection to the LDAP server.
+The default is to start 5 threads.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} string uid
+This specifies the user id with which the daemon should be run.
+
+Defaults to @samp{"nslcd"}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} string gid
+This specifies the group id with which the daemon should be run.
+
+Defaults to @samp{"nslcd"}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} log-option log
+This option controls the way logging is done via a list containing
+SCHEME and LEVEL. The SCHEME argument may either be the symbols "none"
+or "syslog", or an absolute file name. The LEVEL argument is optional
+and specifies the log level. The log level may be one of the following
+symbols: "crit", "error", "warning", "notice", "info" or "debug". All
+messages with the specified log level or higher are logged.
+
+Defaults to @samp{("/var/log/nslcd" info)}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} list uri
+The list of LDAP server URIs. Normally, only the first server will be
+used with the following servers as fall-back.
+
+Defaults to @samp{("ldap://localhost:389/")}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version
+The version of the LDAP protocol to use. The default is to use the
+maximum version supported by the LDAP library.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn
+Specifies the distinguished name with which to bind to the directory
+server for lookups. The default is to bind anonymously.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw
+Specifies the credentials with which to bind. This option is only
+applicable when used with binddn.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn
+Specifies the distinguished name to use when the root user tries to
+modify a user's password using the PAM module.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw
+Specifies the credentials with which to bind if the root user tries to
+change a user's password. This option is only applicable when used with
+rootpwmoddn
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech
+Specifies the SASL mechanism to be used when performing SASL
+authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm
+Specifies the SASL realm to be used when performing SASL authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid
+Specifies the authentication identity to be used when performing SASL
+authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid
+Specifies the authorization identity to be used when performing SASL
+authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize?
+Determines whether the LDAP server host name should be canonicalised. If
+this is enabled the LDAP library will do a reverse host name lookup. By
+default, it is left up to the LDAP library whether this check is
+performed or not.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname
+Set the name for the GSS-API Kerberos credentials cache.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} string base
+The directory search base.
+
+Defaults to @samp{"dc=example,dc=com"}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} scope-option scope
+Specifies the search scope (subtree, onelevel, base or children). The
+default scope is subtree; base scope is almost never useful for name
+service lookups; children scope is not supported on all servers.
+
+Defaults to @samp{(subtree)}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref
+Specifies the policy for dereferencing aliases. The default policy is
+to never dereference aliases.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals
+Specifies whether automatic referral chasing should be enabled. The
+default behaviour is to chase referrals.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps
+This option allows for custom attributes to be looked up instead of the
+default RFC 2307 attributes. It is a list of maps, each consisting of
+the name of a map, the RFC 2307 attribute to match and the query
+expression for the attribute as it is available in the directory.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters
+A list of filters consisting of the name of a map to which the filter
+applies and an LDAP search filter expression.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit
+Specifies the time limit in seconds to use when connecting to the
+directory server. The default value is 10 seconds.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit
+Specifies the time limit (in seconds) to wait for a response from the
+LDAP server. A value of zero, which is the default, is to wait
+indefinitely for searches to be completed.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit
+Specifies the period if inactivity (in seconds) after which the con‐
+nection to the LDAP server will be closed. The default is not to time
+out connections.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime
+Specifies the number of seconds to sleep when connecting to all LDAP
+servers fails. By default one second is waited between the first
+failure and the first retry.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime
+Specifies the time after which the LDAP server is considered to be
+permanently unavailable. Once this time is reached retries will be done
+only once per this time period. The default value is 10 seconds.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl
+Specifies whether to use SSL/TLS or not (the default is not to). If
+'start-tls is specified then StartTLS is used rather than raw LDAP over
+SSL.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert
+Specifies what checks to perform on a server-supplied certificate. The
+meaning of the values is described in the ldap.conf(5) manual page.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir
+Specifies the directory containing X.509 certificates for peer authen‐
+tication. This parameter is ignored when using GnuTLS.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile
+Specifies the path to the X.509 certificate for peer authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile
+Specifies the path to an entropy source. This parameter is ignored when
+using GnuTLS.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers
+Specifies the ciphers to use for TLS as a string.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert
+Specifies the path to the file containing the local certificate for
+client TLS authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key
+Specifies the path to the file containing the private key for client TLS
+authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize
+Set this to a number greater than 0 to request paged results from the
+LDAP server in accordance with RFC2696. The default (0) is to not
+request paged results.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers
+This option prevents group membership lookups through LDAP for the
+specified users. Alternatively, the value 'all-local may be used. With
+that value nslcd builds a full list of non-LDAP users on startup.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid
+This option ensures that LDAP users with a numeric user id lower than
+the specified value are ignored.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset
+This option specifies an offset that is added to all LDAP numeric user
+ids. This can be used to avoid user id collisions with local users.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset
+This option specifies an offset that is added to all LDAP numeric group
+ids. This can be used to avoid user id collisions with local groups.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups
+If this option is set, the member attribute of a group may point to
+another group. Members of nested groups are also returned in the higher
+level group and parent groups are returned when finding groups for a
+specific user. The default is not to perform extra searches for nested
+groups.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers
+If this option is set, the group member list is not retrieved when
+looking up groups. Lookups for finding which groups a user belongs to
+will remain functional so the user will likely still get the correct
+groups assigned on login.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration
+If this option is set, functions which cause all user/group entries to
+be loaded from the directory will not succeed in doing so. This can
+dramatically reduce LDAP server load in situations where there are a
+great number of users and/or groups. This option is not recommended for
+most configurations.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames
+This option can be used to specify how user and group names are verified
+within the system. This pattern is used to check all user and group
+names that are requested and returned from LDAP.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase
+This specifies whether or not to perform searches using case-insensitive
+matching. Enabling this could open up the system to authorization
+bypass vulnerabilities and introduce nscd cache poisoning
+vulnerabilities which allow denial of service.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy
+This option specifies whether password policy controls are requested and
+handled from the LDAP server when performing user authentication.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search
+By default nslcd performs an LDAP search with the user's credentials
+after BIND (authentication) to ensure that the BIND operation was
+successful. The default search is a simple check to see if the user's
+DN exists. A search filter can be specified that will be used instead.
+It should return at least one entry.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search
+This option allows flexible fine tuning of the authorisation check that
+should be performed. The search filter specified is executed and if any
+entries match, access is granted, otherwise access is denied.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message
+If this option is set password modification using pam_ldap will be
+denied and the specified message will be presented to the user instead.
+The message can be used to direct the user to an alternative means of
+changing their password.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} list pam-services
+List of pam service names for which LDAP authentication should suffice.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@c %end of generated documentation for nslcd-configuration
+
+
+@node Web Services
+@subsection Web Services
+
+@cindex web
+@cindex www
@cindex HTTP
The @code{(gnu services web)} module provides the Apache HTTP Server,
the nginx web server, and also a fastcgi wrapper daemon.
The first domain provided will be the subject CN of the certificate, and
all domains will be Subject Alternative Names on the certificate.
+@item @code{challenge} (default: @code{#f})
+The challenge type that has to be run by certbot. If @code{#f} is specified,
+default to the HTTP challenge. If a value is specified, defaults to the
+manual plugin (see @code{authentication-hook}, @code{cleanup-hook} and
+the documentation at @url{https://certbot.eff.org/docs/using.html#hooks}).
+
+@item @code{authentication-hook} (default: @code{#f})
+Command to be run in a shell once for each certificate challenge to be
+answered. For this command, the shell variable @code{$CERTBOT_DOMAIN}
+will contain the domain being authenticated, @code{$CERTBOT_VALIDATION}
+contains the validation string and @code{$CERTBOT_TOKEN} contains the
+file name of the resource requested when performing an HTTP-01 challenge.
+
+@item @code{cleanup-hook} (default: @code{#f})
+Command to be run in a shell once for each certificate challenge that
+have been answered by the @code{auth-hook}. For this command, the shell
+variables available in the @code{auth-hook} script are still available, and
+additionally @code{$CERTBOT_AUTH_OUTPUT} will contain the standard output
+of the @code{auth-hook} script.
+
@item @code{deploy-hook} (default: @code{#f})
Command to be run in a shell once for each successfully issued
certificate. For this command, the shell variable
The delay between a modification in memory and on disk. 0 means immediate
synchronization.
+@item @code{zonefile-load} (default: @code{#f})
+The way the zone file contents are applied during zone load. Possible values
+are:
+
+@itemize
+@item @code{#f} for using the default value from Knot,
+@item @code{'none} for not using the zone file at all,
+@item @code{'difference} for computing the difference between already available
+contents and zone contents and applying it to the current zone contents,
+@item @code{'difference-no-serial} for the same as @code{'difference}, but
+ignoring the SOA serial in the zone file, while the server takes care of it
+automatically.
+@item @code{'whole} for loading zone contents from the zone file.
+@end itemize
+
+@item @code{journal-content} (default: @code{#f})
+The way the journal is used to store zone and its changes. Possible values
+are @code{'none} to not use it at all, @code{'changes} to store changes and
+@code{'all} to store contents. @code{#f} does not set this option, so the
+default value from Knot is used.
+
+@item @code{max-journal-usage} (default: @code{#f})
+The maximum size for the journal on disk. @code{#f} does not set this option,
+so the default value from Knot is used.
+
+@item @code{max-journal-depth} (default: @code{#f})
+The maximum size of the history. @code{#f} does not set this option, so the
+default value from Knot is used.
+
+@item @code{max-zone-size} (default: @code{#f})
+The maximum size of the zone file. This limit is enforced for incoming
+transfer and updates. @code{#f} does not set this option, so the default
+value from Knot is used.
+
+@item @code{dnssec-policy} (default: @code{#f})
+A reference to a @code{knot-policy-configuration} record, or the special
+name @code{"default"}. If the value is @code{#f}, there is no dnssec signing
+on this zone.
+
@item @code{serial-policy} (default: @code{'increment})
A policy between @code{'increment} and @code{'unixtime}.
@item @code{run-directory} (default: @code{"/var/run/knot"})
The run directory. This directory will be used for pid file and sockets.
+@item @code{includes} (default: @code{'()})
+A list of strings or file-like objects denoting other files that must be
+included at the top of the configuration file.
+
+@cindex secrets, Knot service
+This can be used to manage secrets out-of-band. For example, secret
+keys may be stored in an out-of-band file not managed by Guix, and
+thus not visible in @file{/gnu/store}---e.g., you could store secret
+key configuration in @file{/etc/knot/secrets.conf} and add this file
+to the @code{includes} list.
+
+It can also be used to add configuration not supported by this interface.
+
@item @code{listen-v4} (default: @code{"0.0.0.0"})
An ip address on which to listen.
The @code{(gnu services vpn)} module provides services related to
@dfn{virtual private networks} (VPNs). It provides a @emph{client} service for
-your machine to connect to a VPN, and a @emph{servire} service for your machine
+your machine to connect to a VPN, and a @emph{server} service for your machine
to host a VPN. Both services use @uref{https://openvpn.net/, OpenVPN}.
@deffn {Scheme Procedure} openvpn-client-service @
Contrary to @code{upower-service}, it is not a passive,
monitoring tool, as it will apply custom settings each time a new power
source is detected. More information can be found at
-@uref{http://linrunner.de/en/tlp/tlp.html, TLP home page}.
+@uref{https://linrunner.de/en/tlp/tlp.html, TLP home page}.
@deffn {Scheme Variable} tlp-service-type
The service type for the TLP tool. Its value should be a valid
@deftypevr {@code{libvirt-configuration} parameter} string log-outputs
Logging outputs.
-An output is one of the places to save logging information The format
+An output is one of the places to save logging information. The format
for an output can be:
@table @code
@example
(service qemu-binfmt-service-type
(qemu-binfmt-configuration
- (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc"))))
+ (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))))
@end example
In this example, we enable transparent emulation for the ARM and aarch64
@cindex Gitolite service
@cindex Git, hosting
-@uref{http://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git
+@uref{https://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git
repositories on a central server.
Gitolite can handle multiple repositories and users, and supports flexible
@cindex fingerprint
@subsubheading Fingerprint Service
-The @code{(gnu services fingerprint)} module provides a DBus service to
+The @code{(gnu services authentication)} module provides a DBus service to
read and identify fingerprints via a fingerprint sensor.
@defvr {Scheme Variable} fprintd-service-type
The @code{(gnu services spice)} module provides the following service.
@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent]
-Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a daemon
+Returns a service that runs @url{https://www.spice-space.org,VDAGENT}, a daemon
that enables sharing the clipboard with a vm and setting the guest display
resolution when the graphical console window resizes.
@end deffn
@defvr {Scheme Variable} docker-service-type
-This is the type of the service that runs @url{http://www.docker.com,Docker},
+This is the type of the service that runs @url{https://www.docker.com,Docker},
a daemon that can execute application bundles (sometimes referred to as
``containers'') in isolated environments.
would typically run something like:
@example
-$ guix package -i nss-certs
+$ guix install nss-certs
$ export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs"
$ export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
$ export GIT_SSL_CAINFO="$SSL_CERT_FILE"
something like this:
@example
-$ guix package -i nss-certs
+$ guix install nss-certs
$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
@end example
@cindex initial RAM disk
@deffn {Scheme Procedure} raw-initrd @var{file-systems} @
[#:linux-modules '()] [#:mapped-devices '()] @
+ [#:keyboard-layout #f] @
[#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f]
Return a derivation that builds a raw initrd. @var{file-systems} is
a list of file systems to be mounted by the initrd, possibly in addition to
include @code{e2fsck/static} or other packages needed by the initrd to check
the root file system.
+When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
+the desired console keyboard layout. This is done before @var{mapped-devices}
+are set up and before @var{file-systems} are mounted such that, should the
+user need to enter a passphrase or use the REPL, this happens using the
+intended keyboard layout.
+
When @var{qemu-networking?} is true, set up networking with the standard QEMU
parameters. When @var{virtio?} is true, load additional modules so that the
initrd can be used as a QEMU guest with para-virtualized I/O drivers.
@end deffn
@deffn {Scheme Procedure} base-initrd @var{file-systems} @
- [#:mapped-devices '()] [#:qemu-networking? #f] [#:volatile-root? #f]@
+ [#:mapped-devices '()] [#:keyboard-layout #f] @
+ [#:qemu-networking? #f] [#:volatile-root? #f] @
[#:linux-modules '()]
Return as a file-like object a generic initrd, with kernel
modules taken from @var{linux}. @var{file-systems} is a list of file-systems to be
on the kernel command line via @code{--root}. @var{mapped-devices} is a list of device
mappings to realize before @var{file-systems} are mounted.
+When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
+the desired console keyboard layout. This is done before @var{mapped-devices}
+are set up and before @var{file-systems} are mounted such that, should the
+user need to enter a passphrase or use the REPL, this happens using the
+intended keyboard layout.
+
@var{qemu-networking?} and @var{volatile-root?} behaves as in @code{raw-initrd}.
The initrd is automatically populated with all the kernel modules necessary
Available bootloaders are described in @code{(gnu bootloader @dots{})}
modules. In particular, @code{(gnu bootloader u-boot)} contains definitions
of bootloaders for a wide range of ARM and AArch64 systems, using the
-@uref{http://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
+@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
@item @code{target}
This is a string denoting the target onto which to install the
The number of seconds to wait for keyboard input before booting. Set to
0 to boot immediately, and to -1 to wait indefinitely.
+@cindex keyboard layout, for the bootloader
+@item @code{keyboard-layout} (default: @code{#f})
+If this is @code{#f}, the bootloader's menu (if any) uses the default keyboard
+layout, usually US@tie{}English (``qwerty'').
+
+Otherwise, this must be a @code{keyboard-layout} object (@pxref{Keyboard
+Layout}).
+
+@quotation Note
+This option is currently ignored by bootloaders other than @code{grub} and
+@code{grub-efi}.
+@end quotation
+
@item @code{theme} (default: @var{#f})
The bootloader theme object describing the theme to use. If no theme
is provided, some bootloaders might use a default theme, that's true
for GRUB.
-@item @code{terminal-outputs} (default: @code{'gfxterm})
+@item @code{terminal-outputs} (default: @code{'(gfxterm)})
The output terminals used for the bootloader boot menu, as a list of
symbols. GRUB accepts the values: @code{console}, @code{serial},
@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text},
@end deftp
@c FIXME: Write documentation once it's stable.
-Fow now only GRUB has theme support. GRUB themes are created using
+For now only GRUB has theme support. GRUB themes are created using
the @code{grub-theme} form, which is not documented yet.
@defvr {Scheme Variable} %default-theme
@quotation Note
@c The paragraph below refers to the problem discussed at
-@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
+@c <https://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
It is highly recommended to run @command{guix pull} once before you run
@command{guix system reconfigure} for the first time (@pxref{Invoking
guix pull}). Failing to do that you would see an older version of Guix
Docker container using commands like the following:
@example
-image_id="$(docker load < guix-system-docker-image.tar.gz)"
-docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\
- --entrypoint /var/guix/profiles/system/profile/bin/guile \\
- $image_id /var/guix/profiles/system/boot
+image_id="`docker load < guix-system-docker-image.tar.gz`"
+container_id="`docker create $image_id`"
+docker start $container_id
@end example
This command starts a new Docker container from the specified image. It
will boot the Guix system in the usual manner, which means it will
start any services you have defined in the operating system
-configuration. Depending on what you run in the Docker container, it
+configuration. You can get an interactive shell running in the container
+using @command{docker exec}:
+
+@example
+docker exec -ti $container_id /run/current-system/profile/bin/bash --login
+@end example
+
+Depending on what you run in the Docker container, it
may be necessary to give the container additional permissions. For
example, if you intend to build software using Guix inside of the Docker
container, you may need to pass the @option{--privileged} option to
-@code{docker run}.
+@code{docker create}.
@item container
Return a script to run the operating system declared in @var{file}
of the image size as a function of the size of the system declared in
@var{file}.
+@item --network
+@itemx -N
+For the @code{container} action, allow containers to access the host network,
+that is, do not create a network namespace.
+
@item --root=@var{file}
@itemx -r @var{file}
Make @var{file} a symlink to the result, and register it as a garbage
@section Running Guix in a Virtual Machine
@cindex virtual machine
-To run Guix in a virtual machine (VM), one can either use the
-pre-built Guix VM image distributed at
-@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-vm-image-@value{VERSION}.@var{system}.xz}
-, or build their own virtual machine image using @command{guix system
-vm-image} (@pxref{Invoking guix system}). The returned image is in
-qcow2 format, which the @uref{http://qemu.org/, QEMU emulator} can
-efficiently use.
+To run Guix in a virtual machine (VM), one can use the pre-built Guix VM image
+distributed at
+@url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.xz}.
+This image is a compressed image in QCOW format. You will first need to
+decompress with @command{xz -d}, and then you can pass it to an emulator such
+as QEMU (see below for details).
+
+This image boots the Xfce graphical environment and it contains some
+commonly-used tools. You can install more software in the image by running
+@command{guix package} in a terminal (@pxref{Invoking guix package}). You can
+also reconfigure the system based on its initial configuration file available
+as @file{/etc/config.scm} (@pxref{Using the Configuration System}).
+
+Instead of using this pre-built image, one can also build their own virtual
+machine image using @command{guix system vm-image} (@pxref{Invoking guix
+system}). The returned image is in qcow2 format, which the
+@uref{https://qemu.org/, QEMU emulator} can efficiently use.
@cindex QEMU
If you built your own image, you must copy it out of the store
@example
$ qemu-system-x86_64 \
-net user -net nic,model=virtio \
- -enable-kvm -m 256 /tmp/qemu-image
+ -enable-kvm -m 512 \
+ -device virtio-blk,drive=myhd \
+ -drive if=none,file=/tmp/qemu-image,id=myhd
@end example
Here is what each of these options means:
virtual machine support (KVM) of the Linux kernel will make things run
faster.
-@item -m 256
+@c To run Xfce + 'guix pull', we need at least 1G of RAM.
+@item -m 1024
RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB,
which may be insufficient for some operations.
-@item /tmp/qemu-image
-The file name of the qcow2 image.
+@item -device virtio-blk,drive=myhd
+Create a @code{virtio-blk} drive called ``myhd''. @code{virtio-blk} is a
+``paravirtualization'' mechanism for block devices that allows QEMU to achieve
+better performance than if it were emulating a complete disk drive. See the
+QEMU and KVM documentation for more info.
+
+@item -drive if=none,file=/tmp/qemu-image,id=myhd
+Use our QCOW image, the @file{/tmp/qemu-image} file, as the backing store the
+the ``myhd'' drive.
@end table
The default @command{run-vm.sh} script that is returned by an invocation of
@cindex SSH
@cindex SSH server
-To enable SSH inside a VM you need to add a SSH server like @code{(dropbear-service)}
-or @code{(lsh-service)} to your VM. The @code{(lsh-service}) doesn't currently
-boot unsupervised. It requires you to type some characters to initialize the
-randomness generator. In addition you need to forward the SSH port, 22 by
-default, to the host. You can do this with
+To enable SSH inside a VM you need to add an SSH server like
+@code{openssh-service-type} to your VM (@pxref{Networking Services,
+@code{openssh-service-type}}). In addition you need to forward the SSH port,
+22 by default, to the host. You can do this with
@example
`guix system vm config.scm` -net user,hostfwd=tcp::10022-:22
Optionally, a default value for instances of this type.
@end enumerate
-In this example, @var{guix-service-type} extends three services:
+In this example, @code{guix-service-type} extends three services:
-@table @var
+@table @code
@item shepherd-root-service-type
-The @var{guix-shepherd-service} procedure defines how the Shepherd
+The @code{guix-shepherd-service} procedure defines how the Shepherd
service is extended. Namely, it returns a @code{<shepherd-service>}
object that defines how @command{guix-daemon} is started and stopped
(@pxref{Shepherd Services}).
@item account-service-type
-This extension for this service is computed by @var{guix-accounts},
+This extension for this service is computed by @code{guix-accounts},
which returns a list of @code{user-group} and @code{user-account}
objects representing the build user accounts (@pxref{Invoking
guix-daemon}).
@item activation-service-type
-Here @var{guix-activation} is a procedure that returns a gexp, which is
+Here @code{guix-activation} is a procedure that returns a gexp, which is
a code snippet to run at ``activation time''---e.g., when the service is
booted.
@end table
(service guix-service-type)
@end example
-@var{guix-service-type} is quite simple because it extends other
+@code{guix-service-type} is quite simple because it extends other
services but is not extensible itself.
@c @subsubsubsection Extensible Service Types
This is the service type for the
@uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device
management daemon}. Compared to the previous example, in addition to an
-extension of @var{shepherd-root-service-type}, we see two new fields:
+extension of @code{shepherd-root-service-type}, we see two new fields:
@table @code
@item compose
@end table
There can be only one instance of an extensible service type such as
-@var{udev-service-type}. If there were more, the
+@code{udev-service-type}. If there were more, the
@code{service-extension} specifications would be ambiguous.
Still here? The next section provides a reference of the programming
The @code{modify-services} form provides a handy way to change the
parameters of some of the services of a list such as
-@var{%base-services} (@pxref{Base Services, @code{%base-services}}). It
+@code{%base-services} (@pxref{Base Services, @code{%base-services}}). It
evaluates to a list of services. Of course, you could always use
standard list combinators such as @code{map} and @code{fold} to do that
(@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual});
definition using the @command{guix system shepherd-graph} command
(@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}).
-The @var{%shepherd-root-service} is a service object representing
-PID@tie{}1, of type @var{shepherd-root-service-type}; it can be extended
+The @code{%shepherd-root-service} is a service object representing
+PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended
by passing it lists of @code{<shepherd-service>} objects.
@deftp {Data Type} shepherd-service
shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the
@code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details.
-@item @code{requirements} (default: @code{'()})
+@item @code{requirement} (default: @code{'()})
List of symbols denoting the Shepherd services this one depends on.
+@cindex one-shot services, for the Shepherd
+@item @code{one-shot?} (default: @code{#f})
+Whether this service is @dfn{one-shot}. One-shot services stop immediately
+after their @code{start} action has completed. @xref{Slots of services,,,
+shepherd, The GNU Shepherd Manual}, for more info.
+
@item @code{respawn?} (default: @code{#t})
Whether to restart the service when it stops, for instance when the
underlying process dies.
herd @var{action} @var{service} [@var{arguments}@dots{}]
@end example
+@item @code{auto-start?} (default: @code{#t})
+Whether this service should be started automatically by the Shepherd. If it
+is @code{#f} the service has to be started manually with @code{herd start}.
+
@item @code{documentation}
A documentation string, as shown when running:
herd doc @var{service-name}
@end example
-where @var{service-name} is one of the symbols in @var{provision}
+where @var{service-name} is one of the symbols in @code{provision}
(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}).
-@item @code{modules} (default: @var{%default-modules})
+@item @code{modules} (default: @code{%default-modules})
This is the list of modules that must be in scope when @code{start} and
@code{stop} are evaluated.
Guile:
@example
-guix package -i glibc:debug guile:debug
+guix install glibc:debug guile:debug
@end example
GDB must then be told to look for debug files in the user's profile, by
@cindex replacements of packages, for grafts
For instance, suppose a security update needs to be applied to Bash.
Guix developers will provide a package definition for the ``fixed''
-Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining
+Bash, say @code{bash-fixed}, in the usual way (@pxref{Defining
Packages}). Then, the original package definition is augmented with a
@code{replacement} field pointing to the package containing the bug fix:
From there on, any package depending directly or indirectly on Bash---as
reported by @command{guix gc --requisites} (@pxref{Invoking guix
gc})---that is installed is automatically ``rewritten'' to refer to
-@var{bash-fixed} instead of @var{bash}. This grafting process takes
+@code{bash-fixed} instead of @code{bash}. This grafting process takes
time proportional to the size of the package, usually less than a
minute for an ``average'' package on a recent machine. Grafting is
recursive: when an indirect dependency requires grafting, then grafting
``propagates'' up to the package that the user is installing.
Currently, the length of the name and version of the graft and that of
-the package it replaces (@var{bash-fixed} and @var{bash} in the example
+the package it replaces (@code{bash-fixed} and @code{bash} in the example
above) must be equal. This restriction mostly comes from the fact that
grafting works by patching files, including binary files, directly.
Other restrictions may apply: for instance, when adding a graft to a
@image{images/bootstrap-packages,6in,,Dependency graph of the early packages}
-@c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
+@c See <https://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
The first tool that gets built with the bootstrap binaries is
GNU@tie{}Make---noted @code{make-boot0} above---which is a prerequisite
for all the following packages. From there Findutils and Diffutils get
@node Acknowledgments
@chapter Acknowledgments
-Guix is based on the @uref{http://nixos.org/nix/, Nix package manager},
+Guix is based on the @uref{https://nixos.org/nix/, Nix package manager},
which was designed and
implemented by Eelco Dolstra, with contributions from other people (see
the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
HCoop / jackhill / guix / guix.git / blobdiff