Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari@*
-Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ricardo Wurmus@*
+Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@*
Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021, 2022 Efraim Flashner@*
Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@*
Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@*
-Copyright @copyright{} 2017, 2018, 2020, 2021 Mathieu Othacehe@*
+Copyright @copyright{} 2017, 2018, 2020, 2021, 2022 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
Copyright @copyright{} 2017, 2018, 2019, 2020, 2021, 2022 Marius Bakke@*
-Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
+Copyright @copyright{} 2017, 2019, 2020, 2022 Hartmut Goebel@*
Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@*
Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2020 John Soo@*
Copyright @copyright{} 2020 Jonathan Brielmaier@*
Copyright @copyright{} 2020 Edgar Vincent@*
-Copyright @copyright{} 2021 Maxime Devos@*
+Copyright @copyright{} 2021, 2022 Maxime Devos@*
Copyright @copyright{} 2021 B. Wilson@*
Copyright @copyright{} 2021 Xinglu Chen@*
Copyright @copyright{} 2021 Raghav Gururajan@*
Copyright @copyright{} 2021 Hui Lu@*
Copyright @copyright{} 2021 pukkamustard@*
Copyright @copyright{} 2021 Alice Brenon@*
-Copyright @copyright{} 2021 Josselin Poiret@*
-Copyright @copyright{} 2021 Andrew Tropin@*
+Copyright @copyright{} 2021, 2022 Josselin Poiret@*
+Copyright @copyright{} 2021 muradm@*
+Copyright @copyright{} 2021, 2022 Andrew Tropin@*
Copyright @copyright{} 2021 Sarah Morgensen@*
-Copyright @copyright{} 2021 Josselin Poiret@*
+Copyright @copyright{} 2022 Remco van 't Veer@*
+Copyright @copyright{} 2022 Aleksandr Vityazev@*
+Copyright @copyright{} 2022 Philip M@sup{c}Grath@*
+Copyright @copyright{} 2022 Karl Hallsby@*
+Copyright @copyright{} 2022 Justin Veilleux@*
+Copyright @copyright{} 2022 Reily Siegel@*
+Copyright @copyright{} 2022 Simon Streit@*
+Copyright @copyright{} 2022 (@*
+Copyright @copyright{} 2022 John Kehayias@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
* System Installation:: Installing the whole operating system.
+* System Troubleshooting Tips:: When things don't go as planned.
* Getting Started:: Your first steps.
* Package Management:: Package installation, upgrade, etc.
* Channels:: Customizing the package collection.
* Development:: Guix-aided software development.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
+* Foreign Architectures:: Build for foreign architectures.
* System Configuration:: Configuring the operating system.
* Home Configuration:: Configuring the home environment.
* Documentation:: Browsing software user manuals.
+* Platforms:: Defining platforms.
+* System Images:: Creating system images.
* Installing Debugging Files:: Feeding the debugger.
* Using TeX and LaTeX:: Typesetting.
* Security Updates:: Deploying security fixes quickly.
* Installing Guix in a VM:: Guix System playground.
* Building the Installation Image:: How this comes to be.
+System Troubleshooting Tips
+
+* Chrooting into an existing system:: Fixing things from a chroot
+
Manual Installation
* Keyboard Layout and Networking and Partitioning:: Initial setup.
* Package Modules:: Packages from the programmer's viewpoint.
* Defining Packages:: Defining new packages.
* Defining Package Variants:: Customizing packages.
+* Writing Manifests:: The bill of materials of your environment.
* Build Systems:: Specifying how packages are built.
* Build Phases:: Phases of the build process of a package.
* Build Utilities:: Helpers for your package definitions and more.
* The Store Monad:: Purely functional interface to the store.
* G-Expressions:: Manipulating build expressions.
* Invoking guix repl:: Programming Guix in Guile.
+* Using Guix Interactively:: Fine-grain interaction at the REPL.
Defining Packages
* Additional Build Options:: Options specific to 'guix build'.
* Debugging Build Failures:: Real life packaging experience.
+Foreign Architectures
+* Cross-Compilation:: Cross-compiling for another architecture.
+* Native Builds:: Targeting another architecture through native builds.
+
System Configuration
* Using the Configuration System:: Customizing your GNU system.
* 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.
+* Setuid Programs:: Programs running with elevated privileges.
* X.509 Certificates:: Authenticating HTTPS servers.
* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* DNS Services:: DNS daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
+* Samba Services:: Samba services.
* Continuous Integration:: Cuirass and Laminar services.
* Power Management Services:: Extending battery life.
* Audio Services:: The MPD.
* Shepherd Services:: A particular type of service.
* Complex Configurations:: Defining bindings for complex configurations.
+Platforms
+
+* platform Reference:: Detail of platform declarations.
+* Supported Platforms:: Description of the supported platforms.
+
+System Images
+
+* image Reference:: Detail of image declarations.
+* Instantiate an Image:: How to instantiate an image record.
+* image-type Reference:: Detail of image types declaration.
+* Image Modules:: Definition of image modules.
+
Installing Debugging Files
* Separate Debug Info:: Installing 'debug' outputs.
@item riscv64-linux
little-endian 64-bit RISC-V processors, specifically RV64GC, and
-Linux-Libre kernel. This playform is available as a "technology preview":
+Linux-Libre kernel. This platform is available as a "technology preview":
although it is supported, substitutes are not yet available from the
build farm (@pxref{Substitutes}), and some packages may fail to build
(@pxref{Tracking Bugs and Patches}). That said, the Guix community is
./guix-install.sh
@end example
+If you're running Debian or a derivative such as Ubuntu, you can instead
+install the package (it might be a version older than @value{VERSION}
+but you can update it afterwards by running @samp{guix pull}):
+
+@example
+sudo apt install guix
+@end example
+
+Likewise on openSUSE:
+
+@example
+sudo zypper install guix
+@end example
+
When you're done, @pxref{Application Setup} for extra configuration you
might need, and @ref{Getting Started} for your first steps!
@end quotation
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@item
-@uref{https://gnutls.org/, GnuTLS}, specifically its Guile bindings
-(@pxref{Guile Preparations, how to install the GnuTLS bindings for
-Guile,, gnutls-guile, GnuTLS-Guile});
+@uref{https://gitlab.com/gnutls/guile/, Guile-GnuTLS} (@pxref{Guile
+Preparations, how to install the GnuTLS bindings for Guile,,
+gnutls-guile, GnuTLS-Guile})@footnote{The Guile bindings to
+@uref{https://gnutls.org/, GnuTLS} were distributed as part of GnuTLS
+until version 3.7.8 included.};
@item
@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
or later;
The @code{guix-daemon} program may then be run as @code{root} with the
following command@footnote{If your machine uses the systemd init system,
-dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
-file in @file{/etc/systemd/system} will ensure that
+copying the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
+file to @file{/etc/systemd/system} will ensure that
@command{guix-daemon} is automatically started. Similarly, if your
-machine uses the Upstart init system, drop the
+machine uses the Upstart init system, copy the
@file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
-file in @file{/etc/init}.}:
+file to @file{/etc/init}.}:
@example
# guix-daemon --build-users-group=guixbuild
@node Invoking guix-daemon
@section Invoking @command{guix-daemon}
-
+@cindex @command{guix-daemon}
The @command{guix-daemon} program implements all the functionality to
access the store. This includes launching build processes, running the
garbage collector, querying the availability of a build result, etc. It
# guix-daemon --build-users-group=guixbuild
@end example
-@noindent
+@cindex socket activation, for @command{guix-daemon}
+This daemon can also be started following the systemd ``socket
+activation'' protocol (@pxref{Service De- and Constructors,
+@code{make-systemd-constructor},, shepherd, The GNU Shepherd Manual}).
+
For details on how to set it up, @pxref{Setting Up the Daemon}.
@cindex chroot
can do so by running Emacs with the @option{--no-site-file} option
(@pxref{Init File,,, emacs, The GNU Emacs Manual}).
+@quotation Note
+Emacs can now compile packages natively. Under the default
+configuration, this means that Emacs packages will now be
+just-in-time (JIT) compiled as you use them, and the results
+stored in a subdirectory of your @code{user-emacs-directory}.
+
+Furthermore, the build system for Emacs packages transparently
+supports native compilation, but note, that
+@code{emacs-minimal}---the default Emacs for building
+packages---has been configured without native compilation.
+To natively compile your emacs packages ahead of time, use a
+transformation like @option{--with-input=emacs-minimal=emacs}.
+@end quotation
@node Upgrading Guix
@section Upgrading Guix
The installation system provides root shells on TTYs 3 to 6; press
@kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, and so on to reach them. It includes
-many common tools needed to install the system. But it is also a full-blown
-Guix System, which means that you can install additional packages, should you
+many common tools needed to install the system, but is also a full-blown
+Guix System. This means that you can install additional packages, should you
need it, using @command{guix package} (@pxref{Invoking guix package}).
@menu
a list of available keyboard layouts. Run @command{man loadkeys} for
more information.
+@anchor{manual-installation-networking}
@subsubsection Networking
Run the following command to see what your network interfaces are called:
@code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid
board, a list of possible boards will be printed.
+@c *********************************************************************
+@cindex troubleshooting, guix system
+@cindex guix system troubleshooting
+@node System Troubleshooting Tips
+@chapter System Troubleshooting Tips
+
+Guix System allows rebooting into a previous generation should the last
+one be malfunctioning, which makes it quite robust against being broken
+irreversibly. This feature depends on GRUB being correctly functioning
+though, which means that if for whatever reasons your GRUB installation
+becomes corrupted during a system reconfiguration, you may not be able
+to easily boot into a previous generation. A technique that can be used
+in this case is to @i{chroot} into your broken system and reconfigure it
+from there. Such technique is explained below.
+
+@cindex chroot, guix system
+@cindex chrooting, guix system
+@cindex repairing GRUB, via chroot
+@node Chrooting into an existing system
+@section Chrooting into an existing system
+
+This section details how to @i{chroot} to an already installed Guix
+System with the aim of reconfiguring it, for example to fix a broken
+GRUB installation. The process is similar to how it would be done on
+other GNU/Linux systems, but there are some Guix System particularities
+such as the daemon and profiles that make it worthy of explaining here.
+
+@enumerate
+@item
+Obtain a bootable image of Guix System. It is recommended the latest
+development snapshot so the kernel and the tools used are at least as as
+new as those of your installed system; it can be retrieved from the
+@url{https://ci.guix.gnu.org/search/latest/ISO-9660?query=spec:images+status:success+system:x86_64-linux+image.iso,
+https://ci.guix.gnu.org} URL. Follow the @pxref{USB Stick and DVD
+Installation} section for copying it to a bootable media.
+
+@item
+Boot the image, and proceed with the graphical text-based installer
+until your network is configured. Alternatively, you could configure
+the network manually by following the
+@ref{manual-installation-networking} section. If you get the error
+@samp{RTNETLINK answers: Operation not possible due to RF-kill}, try
+@samp{rfkill list} followed by @samp{rfkill unblock 0}, where @samp{0}
+is your device identifier (ID).
+
+@item
+Switch to a virtual console (tty) if you haven't already by pressing
+simultaneously the @kbd{Control + Alt + F4} keys. Mount your file
+system at @file{/mnt}. Assuming your root partition is
+@file{/dev/sda2}, you would do:
+
+@example sh
+mount /dev/sda2 /mnt
+@end example
+
+@item
+Mount special block devices and Linux-specific directories:
+
+@example sh
+mount --bind /proc /mnt/proc
+mount --bind /sys /mnt/sys
+mount --bind /dev /mnt/dev
+@end example
+
+If your system is EFI-based, you must also mount the ESP partition.
+Assuming it is @file{/dev/sda1}, you can do so with:
+
+@example sh
+mount /dev/sda1 /mnt/boot/efi
+@end example
+
+@item
+Enter your system via chroot:
+
+@example sh
+chroot /mnt /bin/sh
+@end example
+
+@item
+Source the system profile as well as your @var{user} profile to setup
+the environment, where @var{user} is the user name used for the Guix
+System you are attempting to repair:
+
+@example sh
+source /var/guix/profiles/system/profile/etc/profile
+source /home/@var{user}/.guix-profile/etc/profile
+@end example
+
+To ensure you are working with the Guix revision you normally would as
+your normal user, also source your current Guix profile:
+
+@example sh
+source /home/@var{user}/.config/guix/current/etc/profile
+@end example
+
+@item
+Start a minimal @command{guix-daemon} in the background:
+
+@example sh
+guix-daemon --build-users-group=guixbuild --disable-chroot &
+@end example
+
+@item
+Edit your Guix System configuration if needed, then reconfigure with:
+
+@example sh
+guix system reconfigure your-config.scm
+@end example
+
+@item
+Finally, you should be good to reboot the system to test your fix.
+
+@end enumerate
+
@c *********************************************************************
@node Getting Started
@chapter Getting Started
@cindex package installation
@cindex package removal
@cindex profile
+@cindex @command{guix package}
The @command{guix package} command is the tool that allows users to
install, upgrade, and remove packages, as well as rolling back to
previous configurations. These operations work on a user
control, copied to different machines to reproduce the same profile, and
so on.
-@c FIXME: Add reference to (guix profile) documentation when available.
@var{file} must return a @dfn{manifest} object, which is roughly a list
of packages:
(list guile-2.0 "debug")))
@end lisp
-@findex specifications->manifest
-In this example we have to know which modules define the @code{emacs}
-and @code{guile-2.0} variables to provide the right
-@code{use-package-modules} line, which can be cumbersome. We can
-instead provide regular package specifications and let
-@code{specifications->manifest} look up the corresponding package
-objects, like this:
-
-@lisp
-(specifications->manifest
- '("emacs" "guile@@2.2" "guile@@2.2:debug"))
-@end lisp
-
-@findex package->development-manifest
-You might also want to create a manifest for all the dependencies of a
-package, rather than the package itself:
-
-@lisp
-(package->development-manifest (specification->package "emacs"))
-@end lisp
-
-The example above gives you all the software required to develop Emacs,
-similar to what @command{guix environment emacs} provides.
-
+@xref{Writing Manifests}, for information on how to write a manifest.
@xref{export-manifest, @option{--export-manifest}}, to learn how to
obtain a manifest file from an existing profile.
shell:
@example
-$ eval `guix package --search-paths`
+$ eval $(guix package --search-paths)
@end example
@var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
@cindex garbage collector
@cindex disk space
+@cindex @command{guix gc}
Packages that are installed, but not used, may be @dfn{garbage-collected}.
The @command{guix gc} command allows users to explicitly run the garbage
collector to reclaim space from the @file{/gnu/store} directory. It is
@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
+older than @var{duration}, for all the user profiles and home environment
+generations; 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
@itemx --branch=@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}.
+string or the name of a tag), or @var{branch}.
@cindex @file{channels.scm}, configuration file
@cindex configuration file for channels
description file created by @command{guix describe}
(@pxref{Invoking guix describe}).
+Let's assume that you want to travel to those days of November 2020 when
+version 1.2.0 of Guix was released and, once you're there, run the
+@command{guile} of that time:
+
+@example
+guix time-machine --commit=v1.2.0 -- \
+ environment -C --ad-hoc guile -- guile
+@end example
+
+The command above fetches Guix@tie{}1.2.0 and runs its @command{guix
+environment} command to spawn an environment in a container running
+@command{guile} (@command{guix environment} has since been subsumed by
+@command{guix shell}; @pxref{Invoking guix shell}). It's like driving a
+DeLorean@footnote{If you don't know what a DeLorean is, consider
+traveling back to the 1980's.}! The first @command{guix time-machine}
+invocation can be expensive: it may have to download or even build a
+large number of packages; the result is cached though and subsequent
+commands targeting the same commit are almost instantaneous.
+
The general syntax is:
@example
@itemx --branch=@var{branch}
Use 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}.
+string or the name of a tag), or @var{branch}.
@item --channels=@var{file}
@itemx -C @var{file}
the @code{guile-json} as it existed in an older revision of Guix---perhaps
because the newer @code{guile-json} has an incompatible API and you want to
run your code against the old API@. To do that, you could write a manifest for
-use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that
+use by @code{guix package --manifest} (@pxref{Writing Manifests}); in that
manifest, you would create an inferior for that old Guix revision you care
about, and you would look up the @code{guile-json} package in the inferior:
@cindex reproducibility
@cindex replicating Guix
+@cindex @command{guix describe}
Often you may want to answer questions like: ``Which revision of Guix am I
using?'' or ``Which channels am I using?'' This is useful information in many
situations: if you want to @emph{replicate} an environment on a different
@cindex @command{guix archive}
@cindex archive
+@cindex exporting files from the store
+@cindex importing files to the store
The @command{guix archive} command allows users to @dfn{export} files
from the store into a single archive, and to later @dfn{import} them on
a machine that runs Guix.
modules:
@example
-$ guix pull --list-generations
-@dots{}
+$ guix describe
Generation 19 Aug 27 2018 16:20:48
guix d894ab8
repository URL: https://git.savannah.gnu.org/git/guix.git
repository URL: https://example.org/variant-packages.git
branch: master
commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
- 11 new packages: variant-gimp, variant-emacs-with-cool-features, @dots{}
- 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
@end example
@noindent
-The output of @command{guix pull} above shows that Generation@tie{}19 includes
-both Guix and packages from the @code{variant-personal-packages} channel. Among
-the new and upgraded packages that are listed, some like @code{variant-gimp} and
-@code{variant-emacs-with-cool-features} might come from
-@code{variant-packages}, while others come from the Guix default channel.
+The output of @command{guix describe} above shows that we're now running
+Generation@tie{}19 and that it includes
+both Guix and packages from the @code{variant-personal-packages} channel
+(@pxref{Invoking guix describe}).
@node Using a Custom Guix Channel
@section Using a Custom Guix Channel
@noindent
From there on, @command{guix pull} will fetch code from the @code{super-hacks}
branch of the repository at @code{example.org}. The authentication concern is
-addressed below ((@pxref{Channel Authentication}).
+addressed below (@pxref{Channel Authentication}).
@node Replicating Guix
@section Replicating Guix
@cindex pinning, channels
@cindex replicating Guix
@cindex reproducibility, of Guix
-The @command{guix pull --list-generations} output above shows precisely which
-commits were used to build this instance of Guix. We can thus replicate it,
-say, on another machine, by providing a channel specification in
-@file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
+The @command{guix describe} command shows precisely which commits were
+used to build the instance of Guix we're using (@pxref{Invoking guix
+describe}). We can replicate this instance on another machine or at a
+different point in time by providing a channel specification ``pinned''
+to these commits that looks like this:
@lisp
;; Deploy specific commits of my channels of interest.
(commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
@end lisp
-The @command{guix describe --format=channels} command can even generate this
-list of channels directly (@pxref{Invoking guix describe}). The resulting
-file can be used with the -C options of @command{guix pull}
-(@pxref{Invoking guix pull}) or @command{guix time-machine}
-(@pxref{Invoking guix time-machine}).
+To obtain this pinned channel specification, the easiest way is to run
+@command{guix describe} and to save its output in the @code{channels}
+format in a file, like so:
-At this point the two machines run the @emph{exact same Guix}, with access to
-the @emph{exact same packages}. The output of @command{guix build gimp} on
-one machine will be exactly the same, bit for bit, as the output of the same
-command on the other machine. It also means both machines have access to all
-the source code of Guix and, transitively, to all the source code of every
-package it defines.
+@example
+guix describe -f channels > channels.scm
+@end example
+
+The resulting @file{channels.scm} file can be passed to the @option{-C}
+option of @command{guix pull} (@pxref{Invoking guix pull}) or
+@command{guix time-machine} (@pxref{Invoking guix time-machine}), as in
+this example:
+
+@example
+guix time-machine -C channels.scm -- shell python -- python3
+@end example
+
+Given the @file{channels.scm} file, the command above will always fetch
+the @emph{exact same Guix instance}, then use that instance to run the
+exact same Python (@pxref{Invoking guix shell}). On any machine, at any
+time, it ends up running the exact same binaries, bit for bit.
+
+@cindex lock files
+Pinned channels address a problem similar to ``lock files'' as
+implemented by some deployment tools---they let you pin and reproduce a
+set of packages. In the case of Guix though, you are effectively
+pinning the entire package set as defined at the given channel commits;
+in fact, you are pinning all of Guix, including its core modules and
+command-line tools. You're also getting strong guarantees that you are,
+indeed, obtaining the exact same software.
This gives you super powers, allowing you to track the provenance of binary
artifacts with very fine grain, and to reproduce software environments at
@cindex reproducible build environments
@cindex development environments
@cindex @command{guix environment}
+@cindex @command{guix shell}
@cindex environment, package build environment
The purpose of @command{guix shell} is to make it easy to create one-off
software environments, without changing one's profile. It is typically
(@pxref{Invoking guix gc}) may clean up packages that were installed in
the environment and that are no longer used outside of it.
-As an added convenience, when running from a directory that contains a
-@file{manifest.scm} or a @file{guix.scm} file (in this order), possibly
-in a parent directory, @command{guix shell} automatically loads the
-file---provided the directory is listed in
-@file{~/.config/guix/shell-authorized-directories}, and only for
-interactive use:
+As an added convenience, @command{guix shell} will try to do what you
+mean when it is invoked interactively without any other arguments
+as in:
@example
guix shell
@end example
+If it finds a @file{manifest.scm} in the current working directory or
+any of its parents, it uses this manifest as though it was given via @code{--manifest}.
+Likewise, if it finds a @file{guix.scm} in the same directories, it uses
+it to build a development profile as though both @code{--development}
+and @code{--file} were present.
+In either case, the file will only be loaded if the directory it
+resides in is listed in
+@file{~/.config/guix/shell-authorized-directories}.
This provides an easy way to define, share, and enter development
environments.
bash, The GNU Bash Reference Manual}, for details on Bash start-up
files.
+@anchor{shell-development-option}
@item --development
@itemx -D
Cause @command{guix shell} to include in the environment the
guix shell -e '(list (@@ (gnu packages bash) bash) "include")'
@end example
+@xref{package-development-manifest,
+@code{package->development-manifest}}, for information on how to write a
+manifest for the development environment of a package.
+
@item --file=@var{file}
@itemx -f @var{file}
Create an environment containing the package or list of packages that
guix shell -D -f gdb-devel.scm
@end example
+@anchor{shell-manifest}
@item --manifest=@var{file}
@itemx -m @var{file}
Create an environment for the packages contained in the manifest object
(@pxref{profile-manifest, @option{--manifest}}) and uses the same
manifest files.
+@xref{Writing Manifests}, for information on how to write a manifest.
+See @option{--export-manifest} below on how to obtain a first manifest.
+
+@cindex manifest, exporting
+@anchor{shell-export-manifest}
+@item --export-manifest
+Write to standard output a manifest suitable for @option{--manifest}
+corresponding to given command-line options.
+
+This is a way to ``convert'' command-line arguments into a manifest.
+For example, imagine you are tired of typing long lines and would like
+to get a manifest equivalent to this command line:
+
+@example
+guix shell -D guile git emacs emacs-geiser emacs-geiser-guile
+@end example
+
+Just add @option{--export-manifest} to the command line above:
+
+@example
+guix shell --export-manifest \
+ -D guile git emacs emacs-geiser emacs-geiser-guile
+@end example
+
+@noindent
+... and you get a manifest along these lines:
+
+@lisp
+(concatenate-manifests
+ (list (specifications->manifest
+ (list "git"
+ "emacs"
+ "emacs-geiser"
+ "emacs-geiser-guile"))
+ (package->development-manifest
+ (specification->package "guile"))))
+@end lisp
+
+You can store it into a file, say @file{manifest.scm}, and from there
+pass it to @command{guix shell} or indeed pretty much any @command{guix}
+command:
+
+@example
+guix shell -m manifest.scm
+@end example
+
+Voilà, you've converted a long command line into a manifest! That
+conversion process honors package transformation options (@pxref{Package
+Transformation Options}) so it should be lossless.
+
@item --profile=@var{profile}
@itemx -p @var{profile}
Create an environment containing the packages installed in @var{profile}.
guix shell --container --expose=$HOME=/exchange guile -- guile
@end example
+@cindex file system hierarchy standard (FHS)
+@cindex FHS (file system hierarchy standard)
+@item --emulate-fhs
+@itemx -F
+When used with @option{--container}, emulate a
+@uref{https://refspecs.linuxfoundation.org/fhs.shtml, Filesystem
+Hierarchy Standard (FHS)} configuration within the container, providing
+@file{/bin}, @file{/lib}, and other directories and files specified by
+the FHS.
+
+As Guix deviates from the FHS specification, this
+option sets up the container to more closely mimic that of other
+GNU/Linux distributions. This is useful for reproducing other
+development environments, testing, and using programs which expect the
+FHS specification to be followed. With this option, the container will
+include a version of glibc that will read
+@file{/etc/ld.so.cache} within the container for the shared library
+cache (contrary to glibc in regular Guix usage) and set up the
+expected FHS directories: @file{/bin}, @file{/etc}, @file{/lib}, and
+@file{/usr} from the container's profile.
+
@item --rebuild-cache
@cindex caching, of profiles
@cindex caching, in @command{guix shell}
@node Invoking guix environment
@section Invoking @command{guix environment}
+@cindex @command{guix environment}
+
The purpose of @command{guix environment} is to assist in creating
development environments.
(@pxref{profile-manifest, @option{--manifest}}) and uses the same
manifest files.
+@xref{shell-export-manifest, @command{guix shell --export-manifest}},
+for information on how to ``convert'' command-line options into a
+manifest.
+
@item --ad-hoc
Include all specified packages in the resulting environment, as if an
@i{ad hoc} package were defined with them as inputs. This option is
guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
@end example
+@item --emulate-fhs
+@item -F
+For containers, emulate a Filesystem Hierarchy Standard (FHS)
+configuration within the container, see
+@uref{https://refspecs.linuxfoundation.org/fhs.shtml, the official
+specification}. As Guix deviates from the FHS specification, this
+option sets up the container to more closely mimic that of other
+GNU/Linux distributions. This is useful for reproducing other
+development environments, testing, and using programs which expect the
+FHS specification to be followed. With this option, the container will
+include a version of @code{glibc} which will read
+@code{/etc/ld.so.cache} within the container for the shared library
+cache (contrary to @code{glibc} in regular Guix usage) and set up the
+expected FHS directories: @code{/bin}, @code{/etc}, @code{/lib}, and
+@code{/usr} from the container's profile.
+
@end table
@command{guix environment}
@node Invoking guix pack
@section Invoking @command{guix pack}
+@cindex @command{guix pack}
+
Occasionally you want to pass software to people who are not (yet!)
lucky enough to be using Guix. You'd tell them to run @command{guix
package -i @var{something}}, but that's not possible in this case. This
build} (@pxref{Additional Build Options, @option{--expression} in
@command{guix build}}).
+@anchor{pack-manifest}
@item --manifest=@var{file}
@itemx -m @var{file}
Use the packages contained in the manifest object returned by the Scheme
specify @emph{either} a manifest file @emph{or} a list of packages,
but not both.
+@xref{Writing Manifests}, for information on how to write a manifest.
+@xref{shell-export-manifest, @command{guix shell --export-manifest}},
+for information on how to ``convert'' command-line options into a
+manifest.
+
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
@node Invoking guix git authenticate
@section Invoking @command{guix git authenticate}
+@cindex @command{guix git authenticate}
+
The @command{guix git authenticate} command authenticates a Git checkout
following the same rule as for channels (@pxref{channel-authentication,
channel authentication}). That is, starting from a given commit, it
* Package Modules:: Packages from the programmer's viewpoint.
* Defining Packages:: Defining new packages.
* Defining Package Variants:: Customizing packages.
+* Writing Manifests:: The bill of materials of your environment.
* Build Systems:: Specifying how packages are built.
* Build Phases:: Phases of the build process of a package.
* Build Utilities:: Helpers for your package definitions and more.
* The Store Monad:: Purely functional interface to the store.
* G-Expressions:: Manipulating build expressions.
* Invoking guix repl:: Programming Guix in Guile
+* Using Guix Interactively:: Fine-grain interaction at the REPL.
@end menu
@node Package Modules
@xref{package Reference}, for a full description of possible fields.
+@quotation Going further
+@cindex Scheme programming language, getting started
+Intimidated by the Scheme language or curious about it? The Cookbook
+has a short section to get started that recaps some of the things shown
+above and explains the fundamentals. @xref{A Scheme Crash Course,,,
+guix-cookbook, GNU Guix Cookbook}, for more information.
+@end quotation
+
Once a package definition is in place, the
package may actually be built using the @code{guix build} command-line
tool (@pxref{Invoking guix build}), troubleshooting any build failures
Systems}).
@item @code{arguments} (default: @code{'()})
-The arguments that should be passed to the build system. This is a
-list, typically containing sequential keyword-value pairs.
+The arguments that should be passed to the build system (@pxref{Build
+Systems}). This is a list, typically containing sequential
+keyword-value pairs, as in this example:
+
+@lisp
+(package
+ (name "example")
+ ;; several fields omitted
+ (arguments
+ (list #:tests? #f ;skip tests
+ #:make-flags #~'("VERBOSE=1") ;pass flags to 'make'
+ #:configure-flags #~'("--enable-frobbing"))))
+@end lisp
+
+The exact set of supported keywords depends on the build system
+(@pxref{Build Systems}), but you will find that almost all of them honor
+@code{#:configure-flags}, @code{#:make-flags}, @code{#:tests?}, and
+@code{#:phases}. The @code{#:phases} keyword in particular lets you
+modify the set of build phases for your package (@pxref{Build Phases}).
@item @code{inputs} (default: @code{'()})
@itemx @code{native-inputs} (default: @code{'()})
A one-line description of the package.
@item @code{description}
-A more elaborate description of the package.
+A more elaborate description of the package, as a string in Texinfo
+syntax.
@item @code{license}
@cindex license, of packages
Return the list of inputs required by @var{package} for development
purposes on @var{system}. When @var{target} is true, return the inputs
needed to cross-compile @var{package} from @var{system} to
-@var{triplet}, where @var{triplet} is a triplet such as
+@var{target}, where @var{target} is a triplet such as
@code{"aarch64-linux-gnu"}.
Note that the result includes both explicit inputs and implicit
options, and so on. Some of these custom packages can be defined
straight from the command line (@pxref{Package Transformation Options}).
This section describes how to define package variants in code. This can
-be useful in ``manifests'' (@pxref{profile-manifest,
-@option{--manifest}}) and in your own package collection
+be useful in ``manifests'' (@pxref{Writing Manifests})
+and in your own package collection
(@pxref{Creating a Channel}), among others!
@cindex inherit, for package definitions
applied to implicit inputs as well.
@end deffn
+@node Writing Manifests
+@section Writing Manifests
+
+@cindex manifest
+@cindex bill of materials (manifests)
+@command{guix} commands let you specify package lists on the command
+line. This is convenient, but as the command line becomes longer and
+less trivial, it quickly becomes more convenient to have that package
+list in what we call a @dfn{manifest}. A manifest is some sort of a
+``bill of materials'' that defines a package set. You would typically
+come up with a code snippet that builds the manifest, store it in a
+file, say @file{manifest.scm}, and then pass that file to the
+@option{-m} (or @option{--manifest}) option that many @command{guix}
+commands support. For example, here's what a manifest for a simple
+package set might look like:
+
+@lisp
+;; Manifest for three packages.
+(specifications->manifest '("gcc-toolchain" "make" "git"))
+@end lisp
+
+Once you have that manifest, you can pass it, for example, to
+@command{guix package} to install just those three packages to your
+profile (@pxref{profile-manifest, @option{-m} option of @command{guix
+package}}):
+
+@example
+guix package -m manifest.scm
+@end example
+
+@noindent
+... or you can pass it to @command{guix shell} (@pxref{shell-manifest,
+@command{-m} option of @command{guix shell}}) to spawn an ephemeral
+environment:
+
+@example
+guix shell -m manifest.scm
+@end example
+
+@noindent
+... or you can pass it to @command{guix pack} in pretty much the same
+way (@pxref{pack-manifest, @option{-m} option of @command{guix pack}}).
+You can store the manifest under version control, share it with others
+so they can easily get set up, etc.
+
+But how do you write your first manifest? To get started, maybe you'll
+want to write a manifest that mirrors what you already have in a
+profile. Rather than start from a blank page, @command{guix package}
+can generate a manifest for you (@pxref{export-manifest, @command{guix
+package --export-manifest}}):
+
+@example
+# Write to 'manifest.scm' a manifest corresponding to the
+# default profile, ~/.guix-profile.
+guix package --export-manifest > manifest.scm
+@end example
+
+Or maybe you'll want to ``translate'' command-line arguments into a
+manifest. In that case, @command{guix shell} can help
+(@pxref{shell-export-manifest, @command{guix shell --export-manifest}}):
+
+@example
+# Write a manifest for the packages specified on the command line.
+guix shell --export-manifest gcc-toolchain make git > manifest.scm
+@end example
+
+In both cases, the @option{--export-manifest} option tries hard to
+generate a faithful manifest; in particular, it takes package
+transformation options into account (@pxref{Package Transformation
+Options}).
+
+@quotation Note
+Manifests are @emph{symbolic}: they refer to packages of the channels
+@emph{currently in use} (@pxref{Channels}). In the example above,
+@code{gcc-toolchain} might refer to version 11 today, but it might refer
+to version 13 two years from now.
+
+If you want to ``pin'' your software environment to specific package
+versions and variants, you need an additional piece of information: the
+list of channel revisions in use, as returned by @command{guix
+describe}. @xref{Replicating Guix}, for more information.
+@end quotation
+
+Once you've obtained your first manifest, perhaps you'll want to
+customize it. Since your manifest is code, you now have access to all
+the Guix programming interfaces!
+
+Let's assume you want a manifest to deploy a custom variant of GDB, the
+GNU Debugger, that does not depend on Guile, together with another
+package. Building on the example seen in the previous section
+(@pxref{Defining Package Variants}), you can write a manifest along
+these lines:
+
+@lisp
+(use-modules (guix packages)
+ (gnu packages gdb) ;for 'gdb'
+ (gnu packages version-control)) ;for 'git'
+
+;; Define a variant of GDB without a dependency on Guile.
+(define gdb-sans-guile
+ (package
+ (inherit gdb)
+ (inputs (modify-inputs (package-inputs gdb)
+ (delete "guile")))))
+
+;; Return a manifest containing that one package plus Git.
+(packages->manifest (list gdb-sans-guile git))
+@end lisp
+
+Note that in this example, the manifest directly refers to the
+@code{gdb} and @code{git} variables, which are bound to a @code{package}
+object (@pxref{package Reference}), instead of calling
+@code{specifications->manifest} to look up packages by name as we did
+before. The @code{use-modules} form at the top lets us access the core
+package interface (@pxref{Defining Packages}) and the modules that
+define @code{gdb} and @code{git} (@pxref{Package Modules}). Seamlessly,
+we're weaving all this together---the possibilities are endless, unleash
+your creativity!
+
+The data type for manifests as well as supporting procedures are defined
+in the @code{(guix profiles)} module, which is automatically available
+to code passed to @option{-m}. The reference follows.
+
+@deftp {Data Type} manifest
+Data type representing a manifest.
+
+It currently has one field:
+
+@table @code
+@item entries
+This must be a list of @code{manifest-entry} records---see below.
+@end table
+@end deftp
+
+@deftp {Data Type} manifest-entry
+Data type representing a manifest entry. A manifest entry contains
+essential metadata: a name and version string, the object (usually a
+package) for that entry, the desired output (@pxref{Packages with
+Multiple Outputs}), and a number of optional pieces of information
+detailed below.
+
+Most of the time, you won't build a manifest entry directly; instead,
+you will pass a package to @code{package->manifest-entry}, described
+below. In some unusual cases though, you might want to create manifest
+entries for things that are @emph{not} packages, as in this example:
+
+@lisp
+;; Manually build a single manifest entry for a non-package object.
+(let ((hello (program-file "hello" #~(display "Hi!"))))
+ (manifest-entry
+ (name "foo")
+ (version "42")
+ (item
+ (computed-file "hello-directory"
+ #~(let ((bin (string-append #$output "/bin")))
+ (mkdir #$output) (mkdir bin)
+ (symlink #$hello
+ (string-append bin "/hello")))))))
+@end lisp
+
+The available fields are the following:
+
+@table @asis
+@item @code{name}
+@itemx @code{version}
+Name and version string for this entry.
+
+@item @code{item}
+A package or other file-like object (@pxref{G-Expressions, file-like
+objects}).
+
+@item @code{output} (default: @code{"out"})
+Output of @code{item} to use, in case @code{item} has multiple outputs
+(@pxref{Packages with Multiple Outputs}).
+
+@item @code{dependencies} (default: @code{'()})
+List of manifest entries this entry depends on. When building a
+profile, dependencies are added to the profile.
+
+Typically, the propagated inputs of a package (@pxref{package Reference,
+@code{propagated-inputs}}) end up having a corresponding manifest entry
+in among the dependencies of the package's own manifest entry.
+
+@item @code{search-paths} (default: @code{'()})
+The list of search path specifications honored by this entry
+(@pxref{Search Paths}).
+
+@item @code{properties} (default: @code{'()})
+List of symbol/value pairs. When building a profile, those properties
+get serialized.
+
+This can be used to piggyback additional metadata---e.g., the
+transformations applied to a package (@pxref{Package Transformation
+Options}).
+
+@item @code{parent} (default: @code{(delay #f)})
+A promise pointing to the ``parent'' manifest entry.
+
+This is used as a hint to provide context when reporting an error
+related to a manifest entry coming from a @code{dependencies} field.
+@end table
+@end deftp
+
+@deffn {Scheme Procedure} concatenate-manifests @var{lst}
+Concatenate the manifests listed in @var{lst} and return the resulting
+manifest.
+@end deffn
+
+@c TODO: <manifest-pattern>, manifest-lookup, manifest-remove, etc.
+
+@deffn {Scheme Procedure} package->manifest-entry @var{package} @
+ [@var{output}] [#:properties]
+Return a manifest entry for the @var{output} of package @var{package},
+where @var{output} defaults to @code{"out"}, and with the given
+@var{properties}. By default @var{properties} is the empty list or, if
+one or more package transformations were applied to @var{package}, it is
+an association list representing those transformations, suitable as an
+argument to @code{options->transformation} (@pxref{Defining Package
+Variants, @code{options->transformation}}).
+
+The code snippet below builds a manifest with an entry for the default
+output and the @code{send-email} output of the @code{git} package:
+
+@lisp
+(use-modules (gnu packages version-control))
+
+(manifest (list (package->manifest-entry git)
+ (package->manifest-entry git "send-email")))
+@end lisp
+@end deffn
+
+@deffn {Scheme Procedure} packages->manifest @var{packages}
+Return a list of manifest entries, one for each item listed in
+@var{packages}. Elements of @var{packages} can be either package
+objects or package/string tuples denoting a specific output of a
+package.
+
+Using this procedure, the manifest above may be rewritten more
+concisely:
+
+@lisp
+(use-modules (gnu packages version-control))
+
+(packages->manifest (list git `(,git "send-email")))
+@end lisp
+@end deffn
+
+@anchor{package-development-manifest}
+@deffn {Scheme Procedure} package->development-manifest @var{package} @
+ [@var{system}] [#:target]
+Return a manifest for the @dfn{development inputs} of @var{package} for
+@var{system}, optionally when cross-compiling to @var{target}.
+Development inputs include both explicit and implicit inputs of
+@var{package}.
+
+Like the @option{-D} option of @command{guix shell}
+(@pxref{shell-development-option, @command{guix shell -D}}), the
+resulting manifest describes the environment in which one can develop
+@var{package}. For example, suppose you're willing to set up a
+development environment for Inkscape, with the addition of Git for
+version control; you can describe that ``bill of materials'' with the
+following manifest:
+
+@lisp
+(use-modules (gnu packages inkscape) ;for 'inkscape'
+ (gnu packages version-control)) ;for 'git'
+
+(concatenate-manifests
+ (list (package->development-manifest inkscape)
+ (packages->manifest (list git))))
+@end lisp
+
+In this example, the development manifest that
+@code{package->development-manifest} returns includes the compiler
+(GCC), the many supporting libraries (Boost, GLib, GTK, etc.), and a
+couple of additional development tools---these are the dependencies
+@command{guix show inkscape} lists.
+@end deffn
+
+@c TODO: Move (gnu packages) interface to a section of its own.
+
+Last, the @code{(gnu packages)} module provides higher-level facilities
+to build manifests. In particular, it lets you look up packages by
+name---see below.
+
+@deffn {Scheme Procedure} specifications->manifest @var{specs}
+Given @var{specs}, a list of specifications such as @code{"emacs@@25.2"}
+or @code{"guile:debug"}, return a manifest. Specs have the format that
+command-line tools such as @command{guix install} and @command{guix
+package} understand (@pxref{Invoking guix package}).
+
+As an example, it lets you rewrite the Git manifest that we saw earlier
+like this:
+
+@lisp
+(specifications->manifest '("git" "git:send-email"))
+@end lisp
+
+Notice that we do not need to worry about @code{use-modules}, importing
+the right set of modules, and referring to the right variables.
+Instead, we directly refer to packages in the same way as on the command
+line, which can often be more convenient.
+@end deffn
+
+@c TODO: specifications->package, etc.
+
@node Build Systems
@section Build Systems
This Boolean, @code{#t} by default, determines whether to ``validate''
the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well
as executables) previously installed by the @code{install} phase.
-
-This validation step consists in making sure that all the shared
-libraries needed by an ELF binary, which are listed as
-@code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the
-@code{DT_RUNPATH} entry of that binary. In other words, it ensures that
-running or using those binaries will not result in a ``file not found''
-error at run time. @xref{Options, @option{-rpath},, ld, The GNU
-Linker}, for more information on @code{RUNPATH}.
+@xref{phase-validate-runpath, the @code{validate-runpath} phase}, for
+details.
@item #:substitutable?
This Boolean, @code{#t} by default, tells whether the package outputs
@end defvr
+@defvr {Scheme variable} elm-build-system
+This variable is exported by @code{(guix build-system elm)}. It implements a
+build procedure for @url{https://elm-lang.org, Elm} packages similar to
+@samp{elm install}.
+
+The build system adds an Elm compiler package to the set of inputs. The
+default compiler package (currently @code{elm-sans-reactor}) can be overridden
+using the @code{#:elm} argument. Additionally, Elm packages needed by the
+build system itself are added as implicit inputs if they are not already
+present: to suppress this behavior, use the
+@code{#:implicit-elm-package-inputs?} argument, which is primarily useful for
+bootstrapping.
+
+The @code{"dependencies"} and @code{"test-dependencies"} in an Elm package's
+@file{elm.json} file correspond to @code{propagated-inputs} and @code{inputs},
+respectively.
+
+Elm requires a particular structure for package names: @pxref{Elm Packages}
+for more details, including utilities provided by @code{(guix build-system
+elm)}.
+
+There are currently a few noteworthy limitations to @code{elm-build-system}:
+
+@itemize
+@item
+The build system is focused on @dfn{packages} in the Elm sense of the word:
+Elm @dfn{projects} which declare @code{@{ "type": "package" @}} in their
+@file{elm.json} files. Using @code{elm-build-system} to build Elm
+@dfn{applications} (which declare @code{@{ "type": "application" @}}) is
+possible, but requires ad-hoc modifications to the build phases. For
+examples, see the definitions of the @code{elm-todomvc} example application and
+the @code{elm} package itself (because the front-end for the
+@samp{elm reactor} command is an Elm application).
+
+@item
+Elm supports multiple versions of a package coexisting simultaneously under
+@env{ELM_HOME}, but this does not yet work well with @code{elm-build-system}.
+This limitation primarily affects Elm applications, because they specify
+exact versions for their dependencies, whereas Elm packages specify supported
+version ranges. As a workaround, the example applications mentioned above use
+the @code{patch-application-dependencies} procedure provided by
+@code{(guix build elm-build-system)} to rewrite their @file{elm.json} files to
+refer to the package versions actually present in the build environment.
+Alternatively, Guix package transformations (@pxref{Defining Package
+Variants}) could be used to rewrite an application's entire dependency graph.
+
+@item
+We are not yet able to run tests for Elm projects because neither
+@url{https://github.com/mpizenberg/elm-test-rs, @command{elm-test-rs}} nor the
+Node.js-based @url{https://github.com/rtfeldman/node-test-runner,
+@command{elm-test}} runner has been packaged for Guix yet.
+@end itemize
+@end defvr
+
@defvr {Scheme Variable} go-build-system
This variable is exported by @code{(guix build-system go)}. It
implements a build procedure for Go packages using the standard
include a Python package as only a part of the software, and thus want to
combine the phases of @code{python-build-system} with another build system.
Python bindings are a common usecase.
+@end defvr
+
+@defvr {Scheme Variable} pyproject-build-system
+This is a variable exported by @code{guix build-system pyproject}. It
+is based on @var{python-build-system}, and adds support for
+@file{pyproject.toml} and @url{https://peps.python.org/pep-0517/, PEP 517}.
+It also supports a variety of build backends and test frameworks.
+
+The API is slightly different from @var{python-build-system}:
+@itemize
+@item
+@code{#:use-setuptools?} and @code{#:test-target} is removed.
+@item
+@code{#:build-backend} is added. It defaults to @code{#false} and will try
+to guess the appropriate backend based on @file{pyproject.toml}.
+@item
+@code{#:test-backend} is added. It defaults to @code{#false} and will guess
+an appropriate test backend based on what is available in package inputs.
+@item
+@code{#:test-flags} is added. The default is @code{#false}, and varies based
+on the detected @code{#:test-backend}.
+@end itemize
+It is considered ``experimental'' in that the implementation details are
+not set in stone yet, however users are encouraged to try it for new
+Python projects (even those using @file{setup.py}). The API is subject to
+change, but any breaking changes in the Guix channel will be dealt with.
+
+Eventually this build system will be deprecated and merged back into
+@var{python-build-system}, probably some time in 2024.
@end defvr
@defvr {Scheme Variable} perl-build-system
@code{with-zef?} parameter.
@end defvr
+@defvr {Scheme Variable} rebar-build-system
+This variable is exported by @code{(guix build-system rebar)}. It
+implements a build procedure around @uref{https://rebar3.org,rebar3},
+a build system for programs written in the Erlang language.
+
+It adds both @code{rebar3} and the @code{erlang} to the set of inputs.
+Different packages can be specified with the @code{#:rebar} and
+@code{#:erlang} parameters, respectively.
+
+This build system is based on @code{gnu-build-system}, but with the
+following phases changed:
+
+@table @code
+
+@item unpack
+This phase, after unpacking the source like the @code{gnu-build-system}
+does, checks for a file @code{contents.tar.gz} at the top-level of the
+source. If this file exists, it will be unpacked, too. This eases
+handling of package hosted at @uref{https://hex.pm/},
+the Erlang and Elixir package repository.
+
+@item bootstrap
+@item configure
+There are no @code{bootstrap} and @code{configure} phase because erlang
+packages typically don’t need to be configured.
+
+@item build
+This phase runs @code{rebar3 compile}
+with the flags listed in @code{#:rebar-flags}.
+
+@item check
+Unless @code{#:tests? #f} is passed,
+this phase runs @code{rebar3 eunit},
+or some other target specified with @code{#:test-target},
+with the flags listed in @code{#:rebar-flags},
+
+@item install
+This installs the files created in the @i{default} profile, or some
+other profile specified with @code{#:install-profile}.
+
+@end table
+@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
@code{build-expression->derivation}}).
@end defvr
+@defvr {Scheme Variable} channel-build-system
+This variable is exported by @code{(guix build-system channel)}.
+
+This build system is meant primarily for internal use. A package using
+this build system must have a channel specification as its @code{source}
+field (@pxref{Channels}); alternatively, its source can be a directory
+name, in which case an additional @code{#:commit} argument must be
+supplied to specify the commit being built (a hexadecimal string).
+
+The resulting package is a Guix instance of the given channel, similar
+to how @command{guix time-machine} would build it.
+@end defvr
+
@node Build Phases
@section Build Phases
Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
is false), copying them to the @code{debug} output when available
(@pxref{Installing Debugging Files}).
+
+@cindex RUNPATH, validation
+@anchor{phase-validate-runpath}
+@item validate-runpath
+Validate the @code{RUNPATH} of ELF binaries, unless
+@code{#:validate-runpath?} is false (@pxref{Build Systems}).
+
+This validation step consists in making sure that all the shared
+libraries needed by an ELF binary, which are listed as @code{DT_NEEDED}
+entries in its @code{PT_DYNAMIC} segment, appear in the
+@code{DT_RUNPATH} entry of that binary. In other words, it ensures that
+running or using those binaries will not result in a ``file not found''
+error at run time. @xref{Options, @option{-rpath},, ld, The GNU
+Linker}, for more information on @code{RUNPATH}.
+
@end table
Other build systems have similar phases, with some variations. For
(substitute* "Makefile"
(("PREFIX =.*")
(string-append "PREFIX = "
- out "\n")))
- #true))))))))
+ out "\n")))))))))))
@end lisp
The new phase that is inserted is written as an anonymous procedure,
@end table
@end deftp
+Some search paths are not tied by a single package but to many packages.
+To reduce duplications, some of them are pre-defined in @code{(guix
+search-paths)}.
+
+@defvr {Scheme Variable} $SSL_CERT_DIR
+@defvrx {Scheme Variable} $SSL_CERT_FILE
+These two search paths indicate where X.509 certificates can be found
+(@pxref{X.509 Certificates}).
+@end defvr
+
+These pre-defined search paths can be used as in the following example:
+
+@lisp
+(package
+ (name "curl")
+ ;; some fields omitted ...
+ (native-search-paths (list $SSL_CERT_DIR $SSL_CERT_FILE)))
+@end lisp
+
How do you turn search path specifications on one hand and a bunch of
directories on the other hand in a set of environment variable
definitions? That's the job of @code{evaluate-search-paths}.
@end lisp
Note that the @code{(guix monad-repl)} module extends the Guile REPL with
-new ``meta-commands'' to make it easier to deal with monadic procedures:
-@code{run-in-store}, and @code{enter-store-monad}. The former is used
+new ``commands'' to make it easier to deal with monadic procedures:
+@code{run-in-store}, and @code{enter-store-monad} (@pxref{Using Guix
+Interactively}). The former is used
to ``run'' a single monadic value through the store:
@example
Note that non-monadic values cannot be returned in the
@code{store-monad} REPL.
+Other meta-commands are available at the REPL, such as @code{,build} to
+build a file-like object (@pxref{Using Guix Interactively}).
+
The main syntactic forms to deal with monads in general are provided by
the @code{(guix monads)} module and are described below.
@node Invoking guix repl
@section Invoking @command{guix repl}
+@cindex @command{guix repl}
@cindex REPL, read-eval-print loop, script
The @command{guix repl} command makes it easier to program Guix in Guile
by launching a Guile @dfn{read-eval-print loop} (REPL) for interactive
@code{!#}
@end example
-Without a file name argument, a Guile REPL is started:
+Without a file name argument, a Guile REPL is started, allowing for
+interactive use (@pxref{Using Guix Interactively}):
@example
$ guix repl
configuration file is loaded when spawning a @code{guile} REPL.
@end table
+@node Using Guix Interactively
+@section Using Guix Interactively
+
+@cindex interactive use
+@cindex REPL, read-eval-print loop
+The @command{guix repl} command gives you access to a warm and friendly
+@dfn{read-eval-print loop} (REPL) (@pxref{Invoking guix repl}). If
+you're getting into Guix programming---defining your own packages,
+writing manifests, defining services for Guix System or Guix Home,
+etc.---you will surely find it convenient to toy with ideas at the REPL.
+
+If you use Emacs, the most convenient way to do that is with Geiser
+(@pxref{The Perfect Setup}), but you do not have to use Emacs to enjoy
+the REPL@. When using @command{guix repl} or @command{guile} in the
+terminal, we recommend using Readline for completion and Colorized to
+get colorful output. To do that, you can run:
+
+@example
+guix install guile guile-readline guile-colorized
+@end example
+
+@noindent
+... and then create a @file{.guile} file in your home directory containing
+this:
+
+@lisp
+(use-modules (ice-9 readline) (ice-9 colorized))
+
+(activate-readline)
+(activate-colorized)
+@end lisp
+
+The REPL lets you evaluate Scheme code; you type a Scheme expression at
+the prompt, and the REPL prints what it evaluates to:
+
+@example
+$ guix repl
+scheme@@(guix-user)> (+ 2 3)
+$1 = 5
+scheme@@(guix-user)> (string-append "a" "b")
+$2 = "ab"
+@end example
+
+It becomes interesting when you start fiddling with Guix at the REPL.
+The first thing you'll want to do is to ``import'' the @code{(guix)}
+module, which gives access to the main part of the programming
+interface, and perhaps a bunch of useful Guix modules. You could type
+@code{(use-modules (guix))}, which is valid Scheme code to import a
+module (@pxref{Using Guile Modules,,, guile, GNU Guile Reference
+Manual}), but the REPL provides the @code{use} @dfn{command} as a
+shorthand notation (@pxref{REPL Commands,,, guile, GNU Guile Reference
+Manual}):
+
+@example
+scheme@@(guix-user)> ,use (guix)
+scheme@@(guix-user)> ,use (gnu packages base)
+@end example
+
+Notice that REPL commands are introduced by a leading comma. A REPL
+command like @code{use} is not valid Scheme code; it's interpreted
+specially by the REPL.
+
+Guix extends the Guile REPL with additional commands for convenience.
+Among those, the @code{build} command comes in handy: it ensures that
+the given file-like object is built, building it if needed, and returns
+its output file name(s). In the example below, we build the
+@code{coreutils} and @code{grep} packages, as well as a ``computed
+file'' (@pxref{G-Expressions, @code{computed-file}}), and we use the
+@code{scandir} procedure to list the files in Grep's @code{/bin}
+directory:
+
+@example
+scheme@@(guix-user)> ,build coreutils
+$1 = "/gnu/store/@dots{}-coreutils-8.32-debug"
+$2 = "/gnu/store/@dots{}-coreutils-8.32"
+scheme@@(guix-user)> ,build grep
+$3 = "/gnu/store/@dots{}-grep-3.6"
+scheme@@(guix-user)> ,build (computed-file "x" #~(mkdir #$output))
+building /gnu/store/@dots{}-x.drv...
+$4 = "/gnu/store/@dots{}-x"
+scheme@@(guix-user)> ,use(ice-9 ftw)
+scheme@@(guix-user)> (scandir (string-append $3 "/bin"))
+$5 = ("." ".." "egrep" "fgrep" "grep")
+@end example
+
+At a lower-level, a useful command is @code{lower}: it takes a file-like
+object and ``lowers'' it into a derivation (@pxref{Derivations}) or a
+store file:
+
+@example
+scheme@@(guix-user)> ,lower grep
+$6 = #<derivation /gnu/store/@dots{}-grep-3.6.drv => /gnu/store/@dots{}-grep-3.6 7f0e639115f0>
+scheme@@(guix-user)> ,lower (plain-file "x" "Hello!")
+$7 = "/gnu/store/@dots{}-x"
+@end example
+
+The full list of REPL commands can be seen by typing @code{,help guix}
+and is given below for reference.
+
+@deffn {REPL command} build @var{object}
+Lower @var{object} and build it if it's not already built, returning its
+output file name(s).
+@end deffn
+
+@deffn {REPL command} lower @var{object}
+Lower @var{object} into a derivation or store file name and return it.
+@end deffn
+
+@deffn {REPL command} verbosity @var{level}
+Change build verbosity to @var{level}.
+
+This is similar to the @option{--verbosity} command-line option
+(@pxref{Common Build Options}): level 0 means total silence, level 1
+shows build events only, and higher levels print build logs.
+@end deffn
+
+@deffn {REPL command} run-in-store @var{exp}
+Run @var{exp}, a monadic expresssion, through the store monad.
+@xref{The Store Monad}, for more information.
+@end deffn
+
+@deffn {REPL command} enter-store-monad
+Enter a new REPL to evaluate monadic expressions (@pxref{The Store
+Monad}). You can quit this ``inner'' REPL by typing @code{,q}.
+@end deffn
+
@c *********************************************************************
@node Utilities
@chapter Utilities
the @code{ed} package:
@example
-guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
+guix build ed --with-source=mirror://gnu/ed/ed-1.4.tar.gz
@end example
As a developer, @option{--with-source} makes it easy to test release
-candidates:
+candidates, and even to test their impact on packages that depend on
+them:
@example
-guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
+guix build elogind --with-source=@dots{}/shepherd-0.9.0rc1.tar.gz
@end example
@dots{} or to build from a checkout in a pristine environment:
as @code{"aarch64-linux-gnu"} (@pxref{Specifying Target Triplets, GNU
configuration triplets,, autoconf, Autoconf}).
+@item --list-systems
+List all the supported systems, that can be passed as an argument to
+@option{--system}.
+
+@item --list-targets
+List all the supported targets, that can be passed as an argument to
+@option{--target}.
+
@anchor{build-check}
@item --check
@cindex determinism, checking
passed, the command looks for a corresponding log on one of the
substitute servers (as specified with @option{--substitute-urls}).
-So for instance, imagine you want to see the build log of GDB on MIPS,
-but you are actually on an @code{x86_64} machine:
+So for instance, imagine you want to see the build log of GDB on
+@code{aarch64}, but you are actually on an @code{x86_64} machine:
@example
$ guix build --log-file gdb -s aarch64-linux
guix import gem rails
@end example
+You can also ask for a specific version:
+
+@example
+guix import gem rails@@7.0.4
+@end example
+
@table @code
@item --recursive
@itemx -r
in Guix.
@end table
+@item elm
+@cindex elm
+Import metadata from the Elm package repository
+@uref{https://package.elm-lang.org, package.elm-lang.org}, as in this example:
+
+@example
+guix import elm elm-explorations/webgl
+@end example
+
+The Elm importer also allows you to specify a version string:
+
+@example
+guix import elm elm-explorations/webgl@@1.1.3
+@end example
+
+Additional options include:
+
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@end table
+
@item opam
@cindex OPAM
@cindex OCaml
@end example
Additional options include:
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@end table
+
+@item hexpm
+@cindex hexpm
+Import metadata from the hex.pm Erlang and Elixir package repository
+@uref{https://hex.pm, hex.pm}, as in this example:
+
+@example
+guix import hexpm stun
+@end example
+
+The importer tries to determine the build system used by the package.
+
+The hexpm importer also allows you to specify a version string:
+
+@example
+guix import hexpm cf@@0.3.0
+@end example
+
+Additional options include:
+
@table @code
@item --recursive
@itemx -r
@end example
@item --list-updaters
-@itemx -L
List available updaters and exit (see @option{--type} above).
For each updater, display the fraction of packages it covers; at the
Use @var{host} as the OpenPGP key server when importing a public key.
@item --load-path=@var{directory}
+@itemx -L @var{directory}
Add @var{directory} to the front of the package module search path
(@pxref{Package Modules}).
@node Invoking guix style
@section Invoking @command{guix style}
-The @command{guix style} command helps packagers style their package
-definitions according to the latest fashionable trends. The command
-currently provides the following styling rules:
+@cindex @command{guix style}
+@cindex styling rules
+@cindex lint, code style
+@cindex format, code style
+@cindex format conventions
+The @command{guix style} command helps users and packagers alike style
+their package definitions and configuration files according to the
+latest fashionable trends. It can either reformat whole files, with the
+@option{--whole-file} option, or apply specific @dfn{styling rules} to
+individual package definitions. The command currently provides the
+following styling rules:
@itemize
@item
to select the style rule, the default rule being @code{format}---see
below.
+To reformat entire source files, the syntax is:
+
+@example
+guix style --whole-file @var{file}@dots{}
+@end example
+
The available options are listed below.
@table @code
@itemx -n
Show source file locations that would be edited but do not modify them.
+@item --whole-file
+@itemx -f
+Reformat the given files in their entirety. In that case, subsequent
+arguments are interpreted as file names (rather than package names), and
+the @option{--styling} option has no effect.
+
+As an example, here is how you might reformat your operating system
+configuration (you need write permissions for the file):
+
+@example
+guix style -f /etc/config.scm
+@end example
+
@item --styling=@var{rule}
@itemx -S @var{rule}
Apply @var{rule}, one of the following styling rules:
fine-grain control over when inputs should be simplified.
@end table
+@item --list-stylings
+@itemx -l
+List and describe the available styling rules and exit.
+
@item --load-path=@var{directory}
@itemx -L @var{directory}
Add @var{directory} to the front of the package module search path
Only disable the checkers specified in a comma-separated list using the
names returned by @option{--list-checkers}.
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Consider the package @var{expr} evaluates to.
+
+This is useful to unambiguously designate packages, as in this example:
+
+@example
+guix lint -c archival -e '(@@ (gnu packages guile) guile-3.0)'
+@end example
+
@item --no-network
@itemx -n
Only enable the checkers that do not depend on Internet access.
guix publish
@end example
+@cindex socket activation, for @command{guix publish}
+@command{guix publish} can also be started following the systemd
+``socket activation'' protocol (@pxref{Service De- and Constructors,
+@code{make-systemd-constructor},, shepherd, The GNU Shepherd Manual}).
+
Once a publishing server has been authorized, the daemon may download
substitutes from it. @xref{Getting Substitutes from Other Servers}.
The command output looks like this:
@smallexample
-$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
-updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
-updating list of substitutes from 'https://guix.example.org'... 100.0%
+$ guix challenge \
+ --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org" \
+ openssl git pius coreutils grep
+updating substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
+updating substitutes from 'https://guix.example.org'... 100.0%
/gnu/store/@dots{}-openssl-1.0.2d contents differ:
local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
@dots{}
-6,406 store items were analyzed:
- - 4,749 (74.1%) were identical
- - 525 (8.2%) differed
- - 1,132 (17.7%) were inconclusive
+5 store items were analyzed:
+ - 2 (40.0%) were identical
+ - 3 (60.0%) differed
+ - 0 (0.0%) were inconclusive
@end smallexample
@noindent
-In this example, @command{guix challenge} first scans the store to
-determine the set of locally-built derivations---as opposed to store
-items that were downloaded from a substitute server---and then queries
-all the substitute servers. It then reports those store items for which
-the servers obtained a result different from the local build.
+In this example, @command{guix challenge} queries all the substitute
+servers for each of the fives packages specified on the command line.
+It then reports those store items for which the servers obtained a
+result different from the local build (if it exists) and/or different
+from one another; here, the @samp{local hash} lines indicate that a
+local build result was available for each of these packages and shows
+its hash.
@cindex non-determinism, in package builds
As an example, @code{guix.example.org} always gets a different answer.
same build result as you did with:
@example
-$ guix challenge @var{package}
+guix challenge @var{package}
@end example
-@noindent
-where @var{package} is a package specification such as
-@code{guile@@2.0} or @code{glibc:debug}.
-
The general syntax is:
@example
-guix challenge @var{options} [@var{packages}@dots{}]
+guix challenge @var{options} @var{argument}@dots{}
@end example
+@noindent
+where @var{argument} is a package specification such as
+@code{guile@@2.0} or @code{glibc:debug} or, alternatively, a store file
+name as returned, for example, by @command{guix build} or @command{guix
+gc --list-live}.
+
When a difference is found between the hash of a locally-built item and
that of a server-provided substitute, or among substitutes provided by
different servers, the command displays it as in the example above and
@node Invoking guix copy
@section Invoking @command{guix copy}
+@cindex @command{guix copy}
@cindex copy, of store items, over SSH
@cindex SSH, copy of store items
@cindex sharing store items across machines
@node Invoking guix weather
@section Invoking @command{guix weather}
+@cindex @command{guix weather}
Occasionally you're grumpy because substitutes are lacking and you end
up building packages by yourself (@pxref{Substitutes}). The
@command{guix weather} command reports on substitute availability on the
$ guix weather --substitute-urls=https://guix.example.org
computing 5,872 package derivations for x86_64-linux...
looking for 6,128 store items on https://guix.example.org..
-updating list of substitutes from 'https://guix.example.org'... 100.0%
+updating substitutes from 'https://guix.example.org'... 100.0%
https://guix.example.org
43.4% substitutes available (2,658 out of 6,128)
7,032.5 MiB of nars (compressed)
@node Invoking guix processes
@section Invoking @command{guix processes}
+@cindex @command{guix processes}
The @command{guix processes} command can be useful to developers and system
administrators, especially on multi-user machines and on build farms: it lists
the current sessions (connections to the daemon), as well as information about
@end table
@end table
+@node Foreign Architectures
+@chapter Foreign Architectures
+
+You can target computers of different CPU architectures when producing
+packages (@pxref{Invoking guix package}), packs (@pxref{Invoking guix
+pack}) or full systems (@pxref{Invoking guix system}).
+
+GNU Guix supports two distinct mechanisms to target foreign
+architectures:
+
+@enumerate
+@item
+The traditional
+@uref{https://en.wikipedia.org/wiki/Cross_compiler,cross-compilation}
+mechanism.
+@item
+The native building mechanism which consists in building using the CPU
+instruction set of the foreign system you are targeting. It often
+requires emulation, using the QEMU program for instance.
+@end enumerate
+
+@menu
+* Cross-Compilation:: Cross-compiling for another architecture.
+* Native Builds:: Targeting another architecture through native builds.
+@end menu
+
+@node Cross-Compilation
+@section Cross-Compilation
+
+@cindex foreign architectures
+The commands supporting cross-compilation are proposing the
+@option{--list-targets} and @option{--target} options.
+
+The @option{--list-targets} option lists all the supported targets that
+can be passed as an argument to @option{--target}.
+
+@example
+$ guix build --list-targets
+The available targets are:
+
+ - aarch64-linux-gnu
+ - arm-linux-gnueabihf
+ - i586-pc-gnu
+ - i686-linux-gnu
+ - i686-w64-mingw32
+ - mips64el-linux-gnu
+ - powerpc-linux-gnu
+ - powerpc64le-linux-gnu
+ - riscv64-linux-gnu
+ - x86_64-linux-gnu
+ - x86_64-w64-mingw32
+@end example
+
+Targets are specified as GNU triplets (@pxref{Specifying Target
+Triplets, GNU configuration triplets,, autoconf, Autoconf}).
+
+Those triplets are passed to GCC and the other underlying compilers
+possibly involved when building a package, a system image or any other
+GNU Guix output.
+
+@example
+$ guix build --target=aarch64-linux-gnu hello
+/gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12
+
+$ file /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello
+/gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello: ELF
+64-bit LSB executable, ARM aarch64 @dots{}
+@end example
+
+The major benefit of cross-compilation is that there are no performance
+penaly compared to emulation using QEMU. There are however higher risks
+that some packages fail to cross-compile because few users are using
+this mechanism extensively.
+
+@node Native Builds
+@section Native Builds
+
+The commands that support impersonating a specific system have the
+@option{--list-systems} and @option{--system} options.
+
+The @option{--list-systems} option lists all the supported systems that
+can be passed as an argument to @option{--system}.
+
+@example
+$ guix build --list-systems
+The available systems are:
+
+ - x86_64-linux [current]
+ - aarch64-linux
+ - armhf-linux
+ - i586-gnu
+ - i686-linux
+ - mips64el-linux
+ - powerpc-linux
+ - powerpc64le-linux
+ - riscv64-linux
+
+$ guix build --system=i686-linux hello
+/gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12
+
+$ file /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello
+/gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello: ELF
+32-bit LSB executable, Intel 80386 @dots{}
+@end example
+
+In the above example, the current system is @var{x86_64-linux}. The
+@var{hello} package is however built for the @var{i686-linux} system.
+
+This is possible because the @var{i686} CPU instruction set is a subset
+of the @var{x86_64}, hence @var{i686} targeting binaries can be run on
+@var{x86_64}.
+
+Still in the context of the previous example, if picking the
+@var{aarch64-linux} system and the @command{guix build
+--system=aarch64-linux hello} has to build some derivations, an extra
+step might be needed.
+
+The @var{aarch64-linux} targeting binaries cannot directly be run on a
+@var{x86_64-linux} system. An emulation layer is requested. The GNU
+Guix daemon can take advantage of the Linux kernel
+@uref{https://en.wikipedia.org/wiki/Binfmt_misc,binfmt_misc} mechanism
+for that. In short, the Linux kernel can defer the execution of a
+binary targeting a foreign platform, here @var{aarch64-linux}, to a
+userspace program, usually an emulator.
+
+There is a service that registers QEMU as a backend for the
+@code{binfmt_misc} mechanism (@pxref{Virtualization Services,
+@code{qemu-binfmt-service-type}}). On Debian based foreign
+distributions, the alternative would be the @code{qemu-user-static}
+package.
+
+If the @code{binfmt_misc} mechanism is not setup correctly, the building
+will fail this way:
+
+@example
+$ guix build --system=armhf-linux hello --check
+@dots{}
+@ unsupported-platform /gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv aarch64-linux
+while setting up the build environment: a `aarch64-linux' is required to
+build `/gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv', but
+I am a `x86_64-linux'@dots{}
+@end example
+
+whereas, with the @code{binfmt_misc} mechanism correctly linked with
+QEMU, one can expect to see:
+
+@example
+$ guix build --system=armhf-linux hello --check
+/gnu/store/13xz4nghg39wpymivlwghy08yzj97hlj-hello-2.12
+@end example
+
+The main advantage of native building compared to cross-compiling, is
+that more packages are likely to build correctly. However it comes at a
+price: compilation backed by QEMU is @emph{way slower} than
+cross-compilation, because every instruction needs to be emulated.
+
+The availability of substitutes for the architecture targeted by the
+@code{--system} option can mitigate this problem. An other way to work
+around it is to install GNU Guix on a machine whose CPU supports
+the targeted instruction set, and set it up as an offload machine
+(@pxref{Daemon Offload Setup}).
+
@node System Configuration
@chapter System Configuration
* 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.
+* Setuid Programs:: Programs running with elevated privileges.
* X.509 Certificates:: Authenticating HTTPS servers.
* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
instantiates that configuration, and makes it the default GRUB boot
entry (@pxref{Invoking guix system}).
+@quotation Note
+We recommend that you keep this @file{my-system-config.scm} file safe
+and under version control to easily track changes to your configuration.
+@end quotation
+
The normal way to change the system configuration is by updating this
file and re-running @command{guix system reconfigure}. One should never
have to touch files in @file{/etc} or to run commands that modify the
install non-core utilities in user profiles (@pxref{Invoking guix
package}).
-@item @code{timezone}
+@item @code{timezone} (default: @code{"Etc/UTC"})
A timezone identifying string---e.g., @code{"Europe/Paris"}.
You can run the @command{tzselect} command to find out which timezone
include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
access to special files), @code{no-suid} (ignore setuid and setgid
bits), @code{no-atime} (do not update file access times),
+@code{no-diratime} (likewise for directories only),
@code{strict-atime} (update file access time), @code{lazy-time} (only
-update time on the in-memory version of the file inode), and
-@code{no-exec} (disallow program execution).
+update time on the in-memory version of the file inode),
+@code{no-exec} (disallow program execution), and @code{shared} (make the
+mount shared).
@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 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. Note that the
-@code{file-system-options->alist} and @code{alist->file-system-options}
+Library Reference Manual}, for details.
+
+Run @command{man 8 mount} for options for various file systems, but
+beware that what it lists as file-system-independent ``mount options'' are
+in fact flags, and belong in the @code{flags} field described above.
+
+The @code{file-system-options->alist} and @code{alist->file-system-options}
procedures from @code{(gnu system file-systems)} can be used to convert
file system options given as an association list to the string
representation, and vice-versa.
* Web Services:: Web servers.
* Certificate Services:: TLS certificates via Let's Encrypt.
* DNS Services:: DNS daemons.
+* VNC Services:: VNC daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
+* Samba Services:: Samba services.
* Continuous Integration:: Cuirass and Laminar services.
* Power Management Services:: Extending battery life.
* Audio Services:: The MPD.
contains the public key that @code{guix.example.org} uses to sign
substitutes.
+@item @code{generate-substitute-key?} (default: @code{#t})
+Whether to generate a @dfn{substitute key pair} under
+@file{/etc/guix/signing-key.pub} and @file{/etc/guix/signing-key.sec} if
+there is not already one.
+
+This key pair is used when exporting store items, for instance with
+@command{guix publish} (@pxref{Invoking guix publish}) or @command{guix
+archive} (@pxref{Invoking guix archive}). Generating a key pair takes a
+few seconds when enough entropy is available and is only done once; you
+might want to turn it off for instance in a virtual machine that does
+not need it and where the extra boot time is a problem.
+
@item @code{max-silent-time} (default: @code{0})
@itemx @code{timeout} (default: @code{0})
The number of seconds of silence and the number of seconds of activity,
@end table
@end deftp
+@deftp {Data Type} guix-extension
+
+This data type represents the parameters of the Guix build daemon that
+are extendable. This is the type of the object that must be used within
+a guix service extension.
+@xref{Service Composition}, for more information.
+
+@table @asis
+@item @code{authorized-keys} (default: @code{'()})
+A list of file-like objects where each element contains a public key.
+
+@item @code{substitute-urls} (default: @code{'()})
+A list of strings where each element is a substitute URL.
+
+@item @code{chroot-directories} (default: @code{'()})
+A list of file-like objects or strings pointing to additional directories the build daemon can use.
+@end table
+@end deftp
+
@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}
@samp{pam_limits} man page from the @code{linux-pam} package.
@end deffn
+@defvr {Scheme Variable} greetd-service-type
+@uref{https://git.sr.ht/~kennylevinsen/greetd, @code{greetd}} is a minimal and
+flexible login manager daemon, that makes no assumptions about what you
+want to launch.
+
+If you can run it from your shell in a TTY, greetd can start it. If it
+can be taught to speak a simple JSON-based IPC protocol, then it can be
+a geeter.
+
+@code{greetd-service-type} provides necessary infrastructure for logging
+in users, including:
+
+@itemize @bullet
+@item
+@code{greetd} PAM service
+
+@item
+Special variation of @code{pam-mount} to mount @code{XDG_RUNTIME_DIR}
+@end itemize
+
+Here is example of switching from @code{mingetty-service-type} to
+@code{greetd-service-type}, and how different terminals could be:
+
+@lisp
+ (append
+ (modify-services %base-services
+ ;; greetd-service-type provides "greetd" PAM service
+ (delete login-service-type)
+ ;; and can be used in place of mingetty-service-type
+ (delete mingetty-service-type))
+ (list
+ (service greetd-service-type
+ (greetd-configuration
+ (terminals
+ (list
+ ;; we can make any terminal active by default
+ (greetd-terminal-configuration (terminal-vt "1") (terminal-switch #t))
+ ;; we can make environment without XDG_RUNTIME_DIR set
+ ;; even provide our own environment variables
+ (greetd-terminal-configuration
+ (terminal-vt "2")
+ (default-session-command
+ (greetd-agreety-session
+ (extra-env '(("MY_VAR" . "1")))
+ (xdg-env? #f))))
+ ;; we can use different shell instead of default bash
+ (greetd-terminal-configuration
+ (terminal-vt "3")
+ (default-session-command
+ (greetd-agreety-session (command (file-append zsh "/bin/zsh")))))
+ ;; we can use any other executable command as greeter
+ (greetd-terminal-configuration
+ (terminal-vt "4")
+ (default-session-command (program-file "my-noop-greeter" #~(exit))))
+ (greetd-terminal-configuration (terminal-vt "5"))
+ (greetd-terminal-configuration (terminal-vt "6"))))))
+ ;; mingetty-service-type can be used in parallel
+ ;; if needed to do so, do not (delete login-service-type)
+ ;; as illustrated above
+ #| (service mingetty-service-type (mingetty-configuration (tty "tty8"))) |#))
+@end lisp
+@end defvr
+
+@deftp {Data Type} greetd-configuration
+Configuration record for the @code{greetd-service-type}.
+@table @asis
+
+@item @code{motd}
+A file-like object containing the ``message of the day''.
+
+@item @code{allow-empty-passwords?} (default: @code{#t})
+Allow empty passwords by default so that first-time users can log in when
+the 'root' account has just been created.
+
+@item @code{terminals} (default: @code{'()})
+List of @code{greetd-terminal-configuration} per terminal for which
+@code{greetd} should be started.
+
+@item @code{greeter-supplementary-groups} (default: @code{'()})
+List of groups which should be added to @code{greeter} user. For instance:
+@lisp
+(greeter-supplementary-groups '("seat" "video"))
+@end lisp
+Note that this example will fail if @code{seat} group does not exist.
+@end table
+@end deftp
+
+@deftp {Data Type} greetd-terminal-configuration
+Configuration record for per terminal greetd daemon service.
+
+@table @asis
+@item @code{greetd} (default: @code{greetd})
+The greetd package to use.
+
+@item @code{config-file-name}
+Configuration file name to use for greetd daemon. Generally, autogenerated
+derivation based on @code{terminal-vt} value.
+
+@item @code{log-file-name}
+Log file name to use for greetd daemon. Generally, autogenerated
+name based on @code{terminal-vt} value.
+
+@item @code{terminal-vt} (default: @samp{"7"})
+The VT to run on. Use of a specific VT with appropriate conflict avoidance
+is recommended.
+
+@item @code{terminal-switch} (default: @code{#f})
+Make this terminal active on start of @code{greetd}.
+
+@item @code{default-session-user} (default: @samp{"greeter"})
+The user to use for running the greeter.
+
+@item @code{default-session-command} (default: @code{(greetd-agreety-session)})
+Can be either instance of @code{greetd-agreety-session} configuration or
+@code{gexp->script} like object to use as greeter.
+
+@end table
+@end deftp
+
+@deftp {Data Type} greetd-agreety-session
+Configuration record for the agreety greetd greeter.
+
+@table @asis
+@item @code{agreety} (default: @code{greetd})
+The package with @command{/bin/agreety} command.
+
+@item @code{command} (default: @code{(file-append bash "/bin/bash")})
+Command to be started by @command{/bin/agreety} on successful login.
+
+@item @code{command-args} (default: @code{'("-l")})
+Command arguments to pass to command.
+
+@item @code{extra-env} (default: @code{'()})
+Extra environment variables to set on login.
+
+@item @code{xdg-env?} (default: @code{#t})
+If true @code{XDG_RUNTIME_DIR} and @code{XDG_SESSION_TYPE} will be set
+before starting command. One should note that, @code{extra-env} variables
+are set right after mentioned variables, so that they can be overriden.
+
+@end table
+@end deftp
+
+@deftp {Data Type} greetd-wlgreet-session
+Generic configuration record for the wlgreet greetd greeter.
+
+@table @asis
+@item @code{wlgreet} (default: @code{wlgreet})
+The package with the @command{/bin/wlgreet} command.
+
+@item @code{command} (default: @code{(file-append sway "/bin/sway")})
+Command to be started by @command{/bin/wlgreet} on successful login.
+
+@item @code{command-args} (default: @code{'()})
+Command arguments to pass to command.
+
+@item @code{output-mode} (default: @code{"all"})
+Option to use for @code{outputMode} in the TOML configuration file.
+
+@item @code{scale} (default: @code{1})
+Option to use for @code{scale} in the TOML configuration file.
+
+@item @code{background} (default: @code{'(0 0 0 0.9)})
+RGBA list to use as the background colour of the login prompt.
+
+@item @code{headline} (default: @code{'(1 1 1 1)})
+RGBA list to use as the headline colour of the UI popup.
+
+@item @code{prompt} (default: @code{'(1 1 1 1)})
+RGBA list to use as the prompt colour of the UI popup.
+
+@item @code{prompt-error} (default: @code{'(1 1 1 1)})
+RGBA list to use as the error colour of the UI popup.
+
+@item @code{border} (default: @code{'(1 1 1 1)})
+RGBA list to use as the border colour of the UI popup.
+
+@item @code{extra-env} (default: @code{'()})
+Extra environment variables to set on login.
+
+@end table
+@end deftp
+
+@deftp {Data Type} greetd-wlgreet-sway-session
+Sway-specific configuration record for the wlgreet greetd greeter.
+
+@table @asis
+@item @code{wlgreet-session} (default: @code{(greetd-wlgreet-session)})
+A @code{greetd-wlgreet-session} record for generic wlgreet configuration,
+on top of the Sway-specific @code{greetd-wlgreet-sway-session}.
+
+@item @code{sway} (default: @code{sway})
+The package providing the @command{/bin/sway} command.
+
+@item @code{sway-configuration} (default: #f)
+File-like object providing an additional Sway configuration file to be
+prepended to the mandatory part of the configuration.
+
+@end table
+
+Here is an example of a greetd configuration that uses wlgreet and Sway:
+
+@lisp
+ (greetd-configuration
+ ;; We need to give the greeter user these permissions, otherwise
+ ;; Sway will crash on launch.
+ (greeter-supplementary-groups (list "video" "input" "seat"))
+ (terminals
+ (list (greetd-terminal-configuration
+ (terminal-vt "1")
+ (terminal-switch #t)
+ (default-session-command
+ (greetd-wlgreet-sway-session
+ (sway-configuration
+ (local-file "sway-greetd.conf"))))))))
+@end lisp
+@end deftp
+
@node Scheduled Job Execution
@subsection Scheduled Job Execution
@item @code{files}
The list of files or file glob patterns to rotate.
-@item @code{options} (default: @code{'()})
+@vindex %default-log-rotation-options
+@item @code{options} (default: @code{%default-log-rotation-options})
The list of rottlog options for this rotation (@pxref{Configuration
-parameters,,, rottlog, GNU Rot[t]lg Manual}).
+parameters,,, rottlog, GNU Rot[t]log Manual}).
@item @code{post-rotate} (default: @code{#f})
Either @code{#f} or a gexp to execute once the rotation has completed.
"/var/log/maillog")}.
@end defvr
+Some log files just need to be deleted periodically once they are old,
+without any other criterion and without any archival step. This is the
+case of build logs stored by @command{guix-daemon} under
+@file{/var/log/guix/drvs} (@pxref{Invoking guix-daemon}). The
+@code{log-cleanup} service addresses this use case. For example,
+@code{%base-services} (@pxref{Base Services}) includes the following:
+
+@lisp
+;; Periodically delete old build logs.
+(service log-cleanup-service-type
+ (log-cleanup-configuration
+ (directory "/var/log/guix/drvs")))
+@end lisp
+
+That ensures build logs do not accumulate endlessly.
+
+@defvr {Scheme Variable} log-cleanup-service-type
+This is the type of the service to delete old logs. Its value must be a
+@code{log-cleanup-configuration} record as described below.
+@end defvr
+
+@deftp {Data Type} log-cleanup-configuration
+Data type representing the log cleanup configuration
+
+@table @asis
+@item @code{directory}
+Name of the directory containing log files.
+
+@item @code{expiry} (default: @code{(* 6 30 24 3600)})
+Age in seconds after which a file is subject to deletion (six months by
+default).
+
+@item @code{schedule} (default: @code{"30 12 01,08,15,22 * *"})
+String or gexp denoting the corresponding mcron job schedule
+(@pxref{Scheduled Job Execution}).
+@end table
+@end deftp
+
+@cindex logging, anonymization
+@subheading Anonip Service
+
+Anonip is a privacy filter that removes IP address from web server logs.
+This service creates a FIFO and filters any written lines with anonip
+before writing the filtered log to a target file.
+
+The following example sets up the FIFO
+@file{/var/run/anonip/https.access.log} and writes the filtered log file
+@file{/var/log/anonip/https.access.log}.
+
+@lisp
+(service anonip-service-type
+ (anonip-configuration
+ (input "/var/run/anonip/https.access.log")
+ (output "/var/log/anonip/https.access.log")))
+@end lisp
+
+Configure your web server to write its logs to the FIFO at
+@file{/var/run/anonip/https.access.log} and collect the anonymized log
+file at @file{/var/web-logs/https.access.log}.
+
+@deftp {Data Type} anonip-configuration
+This data type represents the configuration of anonip.
+It has the following parameters:
+
+@table @asis
+@item @code{anonip} (default: @code{anonip})
+The anonip package to use.
+
+@item @code{input}
+The file name of the input log file to process. The service creates a
+FIFO of this name. The web server should write its logs to this FIFO.
+
+@item @code{output}
+The file name of the processed log file.
+@end table
+
+The following optional settings may be provided:
+
+@table @asis
+@item @code{skip-private?}
+When @code{#true} do not mask addresses in private ranges.
+
+@item @code{column}
+A 1-based indexed column number. Assume IP address is in the specified
+column (default is 1).
+
+@item @code{replacement}
+Replacement string in case address parsing fails, e.g. @code{"0.0.0.0"}.
+
+@item @code{ipv4mask}
+Number of bits to mask in IPv4 addresses.
+
+@item @code{ipv6mask}
+Number of bits to mask in IPv6 addresses.
+
+@item @code{increment}
+Increment the IP address by the given number. By default this is zero.
+
+@item @code{delimiter}
+Log delimiter string.
+
+@item @code{regex}
+Regular expression for detecting IP addresses. Use this instead of @code{column}.
+@end table
+@end deftp
+
+
@node Networking Setup
@subsection Networking Setup
This is the type for statically-configured network interfaces. Its
value must be a list of @code{static-networking} records. Each of them
declares a set of @dfn{addresses}, @dfn{routes}, and @dfn{links}, as
-show below.
+shown below.
@cindex network interface controller (NIC)
@cindex NIC, networking interface controller
@table @asis
@item @code{destination}
-The route destination (a string), either an IP address or
-@code{"default"} to denote the default route.
+The route destination (a string), either an IP address and network mask
+or @code{"default"} to denote the default route.
@item @code{source} (default: @code{#f})
The route source.
@cindex DHCP, networking service
@defvr {Scheme Variable} dhcp-client-service-type
This is the type of services that run @var{dhcp}, a Dynamic Host Configuration
-Protocol (DHCP) client, on all the non-loopback network interfaces. Its value
-is the DHCP client package to use, @code{isc-dhcp} by default.
+Protocol (DHCP) client.
@end defvr
+@deftp {Data Type} dhcp-client-configuration
+Data type representing the configuration of the DHCP client service.
+
+@table @asis
+@item @code{package} (default: @code{isc-dhcp})
+DHCP client package to use.
+
+@item @code{interfaces} (default: @code{'all})
+Either @code{'all} or the list of interface names that the DHCP client
+should listen on---e.g., @code{'("eno1")}.
+
+When set to @code{'all}, the DHCP client listens on all the available
+non-loopback interfaces that can be activated. Otherwise the DHCP
+client listens only on the specified interfaces.
+@end table
+@end deftp
+
@cindex NetworkManager
@defvr {Scheme Variable} network-manager-service-type
@end table
@end deftp
-@cindex wicd
-@cindex wireless
-@cindex WiFi
-@cindex network management
-@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}]
-Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network
-management daemon that aims to simplify wired and wireless networking.
-
-This service adds the @var{wicd} package to the global profile, providing
-several commands to interact with the daemon and configure networking:
-@command{wicd-client}, a graphical user interface, and the @command{wicd-cli}
-and @command{wicd-curses} user interfaces.
-@end deffn
-
@cindex ModemManager
Some networking devices such as modems require special care, and this is
what the services below focus on.
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{https://www.isc.org/products/DHCP, ISC's DHCP server}.
+@uref{https://www.isc.org/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''
described below.
@end defvr
-@deftp {Data Type} opendht-configuration
-This is the data type for the OpenDHT service configuration.
-
@c The fields documentation has been auto-generated using the
@c configuration->documentation procedure from
@c (gnu services configuration).
+@deftp {Data Type} opendht-configuration
Available @code{opendht-configuration} fields are:
-@deftypevr {@code{opendht-configuration} parameter} package opendht
+@table @asis
+@item @code{opendht} (default: @code{opendht}) (type: file-like)
The @code{opendht} package to use.
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} boolean peer-discovery?
+@item @code{peer-discovery?} (default: @code{#f}) (type: boolean)
Whether to enable the multicast local peer discovery mechanism.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} boolean enable-logging?
+@item @code{enable-logging?} (default: @code{#f}) (type: boolean)
Whether to enable logging messages to syslog. It is disabled by default
as it is rather verbose.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} boolean debug?
+@item @code{debug?} (default: @code{#f}) (type: boolean)
Whether to enable debug-level logging messages. This has no effect if
logging is disabled.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} maybe-string bootstrap-host
+@item @code{bootstrap-host} (default: @code{"bootstrap.jami.net:4222"}) (type: maybe-string)
The node host name that is used to make the first connection to the
network. A specific port value can be provided by appending the
@code{:PORT} suffix. By default, it uses the Jami bootstrap nodes, but
any host can be specified here. It's also possible to disable
-bootsrapping by setting this to the @code{'disabled} symbol.
+bootstrapping by explicitly setting this field to the
+@code{%unset-value} value.
-Defaults to @samp{"bootstrap.jami.net:4222"}.
+@item @code{port} (default: @code{4222}) (type: maybe-number)
+The UDP port to bind to. When left unspecified, an available port is
+automatically selected.
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} maybe-number port
-The UDP port to bind to. When set to @code{'disabled}, an available
-port is automatically selected.
-
-Defaults to @samp{4222}.
-
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port
+@item @code{proxy-server-port} (type: maybe-number)
Spawn a proxy server listening on the specified port.
-Defaults to @samp{disabled}.
-
-@end deftypevr
-
-@deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port-tls
+@item @code{proxy-server-port-tls} (type: maybe-number)
Spawn a proxy server listening to TLS connections on the specified port.
-Defaults to @samp{disabled}.
-
-@end deftypevr
+@end table
@end deftp
@cindex Tor
@table @asis
@item @code{openssh} (default @var{openssh})
-The Openssh package to use.
+The OpenSSH package to use.
@item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
Name of the file where @command{sshd} writes its PID.
@item @code{port-number} (default: @code{22})
TCP port on which @command{sshd} listens for incoming connections.
+@item @code{max-connections} (default: @code{200})
+Hard limit on the maximum number of simultaneous client connections,
+enforced by the inetd-style Shepherd service (@pxref{Service De- and
+Constructors, @code{make-inetd-constructor},, shepherd, The GNU Shepherd
+Manual}).
+
@item @code{permit-root-login} (default: @code{#f})
This field determines whether and when to allow logins as root. If
@code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
Note that this does @emph{not} interfere with the use of
@file{~/.ssh/authorized_keys}.
+@item @code{generate-host-keys?} (default: @code{#t})
+Whether to generate host key pairs with @command{ssh-keygen -A} under
+@file{/etc/ssh} if there are none.
+
+Generating key pairs takes a few seconds when enough entropy is
+available and is only done once. You might want to turn it off for
+instance in a virtual machine that does not need it because host keys
+are provided in some other way, and where the extra boot time is a
+problem.
+
@item @code{log-level} (default: @code{'info})
This is a symbol specifying the logging level: @code{quiet}, @code{fatal},
@code{error}, @code{info}, @code{verbose}, @code{debug}, etc. See the man
@example
# sample content for /etc/yggdrasil-private.conf
@{
- # Your public encryption key. Your peers may ask you for this to put
- # into their AllowedEncryptionPublicKeys configuration.
- EncryptionPublicKey: 378dc5...
-
- # Your private encryption key. DO NOT share this with anyone!
- EncryptionPrivateKey: 0777...
-
- # Your public signing key. You should not ordinarily need to share
- # this with anyone.
- SigningPublicKey: e1664...
+ # Your public key. Your peers may ask you for this to put
+ # into their AllowedPublicKeys configuration.
+ PublicKey: 64277...
- # Your private signing key. DO NOT share this with anyone!
- SigningPrivateKey: 0589d...
+ # Your private key. DO NOT share this with anyone!
+ PrivateKey: 5c750...
@}
@end example
@end defvr
@cindex GDM
@cindex GNOME, login manager
+@anchor{gdm}
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.
When @code{auto-login?} is true, GDM logs in directly as
@code{default-user}.
+@item @code{auto-suspend?} (default @code{#t})
+When true, GDM will automatically suspend to RAM when nobody is
+physically connected. When a machine is used via remote desktop or SSH,
+this should be set to false to avoid GDM interrupting remote sessions or
+rendering the machine unavailable.
+
@item @code{debug?} (default: @code{#f})
When true, GDM writes debug messages to its log.
@item @code{xorg-configuration} (default: @code{(xorg-configuration)})
Configuration of the Xorg graphical server.
-@item @code{xsession} (default: @code{(xinitrc)})
+@item @code{x-session} (default: @code{(xinitrc)})
Script to run before starting a X session.
+@item @code{xdmcp?} (default: @code{#f})
+When true, enable the X Display Manager Control Protocol (XDMCP). This
+should only be enabled in trusted environments, as the protocol is not
+secure. When enabled, GDM listens for XDMCP queries on the UDP port
+177.
+
@item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper})
File name of the @code{dbus-daemon} executable.
@end defvr
+@cindex login manager
+@cindex X11 login
+@defvr {Scheme Variable} sddm-service-type
+This is the type of the service to run the
+@uref{https://github.com/sddm/sddm,SDDM display manager}. Its value
+must be a @code{sddm-configuration} record (see below).
+
+Here's an example use:
+
+@lisp
+(service sddm-service-type
+ (sddm-configuration
+ (auto-login-user "alice")
+ (auto-login-session "xfce.desktop")))
+@end lisp
+@end defvr
+
@deftp {Data Type} sddm-configuration
-This is the data type representing the SDDM service configuration.
+This data type represents the configuration of the SDDM login manager.
+The available fields are:
@table @asis
+@item @code{sddm} (default: @code{sddm})
+The SDDM package to use.
+
@item @code{display-server} (default: "x11")
Select display server to use for the greeter. Valid values are
@samp{"x11"} or @samp{"wayland"}.
@item @code{numlock} (default: "on")
Valid values are @samp{"on"}, @samp{"off"} or @samp{"none"}.
-@item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")})
+@item @code{halt-command} (default @code{#~(string-append #$shepherd "/sbin/halt")})
Command to run when halting.
@item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")})
Minimum VT to use.
@item @code{auto-login-user} (default "")
-User to use for auto-login.
+User account that will be automatically logged in.
+Setting this to the empty string disables auto-login.
@item @code{auto-login-session} (default "")
-Desktop file to use for auto-login.
+The @file{.desktop} file name to use as the auto-login session, or the empty string.
@item @code{relogin?} (default #f)
Relogin after logout.
@end table
@end deftp
-@cindex login manager
-@cindex X11 login
-@defvr {Scheme Variable} sddm-service-type
+@cindex lightdm, graphical login manager
+@cindex display manager, lightdm
+@anchor{lightdm}
+@defvr {Scheme Variable} lightdm-service-type
This is the type of the service to run the
-@uref{https://github.com/sddm/sddm,SDDM display manager}. Its value
-must be a @code{sddm-configuration} record (see below).
+@url{https://github.com/canonical/lightdm,LightDM display manager}. Its
+value must be a @code{lightdm-configuration} record, which is documented
+below. Among its distinguishing features are TigerVNC integration for
+easily remoting your desktop as well as support for the XDMCP protocol,
+which can be used by remote clients to start a session from the login
+manager.
-Here's an example use:
+In its most basic form, it can be used simply as:
@lisp
-(service sddm-service-type
- (sddm-configuration
- (auto-login-user "alice")
- (auto-login-session "xfce.desktop")))
+(service lightdm-service-type)
+@end lisp
+
+A more elaborate example making use of the VNC capabilities and enabling
+more features and verbose logs could look like:
+
+@lisp
+(service lightdm-service-type
+ (lightdm-configuration
+ (allow-empty-passwords? #t)
+ (xdmcp? #t)
+ (vnc-server? #t)
+ (vnc-server-command
+ (file-append tigervnc-server "/bin/Xvnc"
+ " -SecurityTypes None"))
+ (seats
+ (list (lightdm-seat-configuration
+ (name "*")
+ (user-session "ratpoison"))))))
@end lisp
@end defvr
-@deftp {Data Type} sddm-configuration
-This data type represents the configuration of the SDDM login manager.
-The available fields are:
+@c The LightDM service documentation can be auto-generated via the
+@c 'generate-doc' procedure at the bottom of the (gnu services lightdm)
+@c module.
+@c %start of fragment
+@deftp {Data Type} lightdm-configuration
+Available @code{lightdm-configuration} fields are:
@table @asis
-@item @code{sddm} (default: @code{sddm})
-The SDDM package to use.
+@item @code{lightdm} (default: @code{lightdm}) (type: file-like)
+The lightdm package to use.
-@item @code{display-server} (default: @code{"x11"})
-This must be either @code{"x11"} or @code{"wayland"}.
+@item @code{allow-empty-passwords?} (default: @code{#f}) (type: boolean)
+Whether users not having a password set can login.
-@c FIXME: Add more fields.
+@item @code{debug?} (default: @code{#f}) (type: boolean)
+Enable verbose output.
-@item @code{auto-login-user} (default: @code{""})
-If non-empty, this is the user account under which to log in
-automatically.
+@item @code{xorg-configuration} (type: xorg-configuration)
+The default Xorg server configuration to use to generate the Xorg server
+start script. It can be refined per seat via the @code{xserver-command}
+of the @code{<lightdm-seat-configuration>} record, if desired.
+
+@item @code{greeters} (type: list-of-greeter-configurations)
+The LightDM greeter configurations specifying the greeters to use.
+
+@item @code{seats} (type: list-of-seat-configurations)
+The seat configurations to use. A LightDM seat is akin to a user.
+
+@item @code{xdmcp?} (default: @code{#f}) (type: boolean)
+Whether a XDMCP server should listen on port UDP 177.
+
+@item @code{xdmcp-listen-address} (type: maybe-string)
+The host or IP address the XDMCP server listens for incoming
+connections. When unspecified, listen on for any hosts/IP addresses.
+
+@item @code{vnc-server?} (default: @code{#f}) (type: boolean)
+Whether a VNC server is started.
+
+@item @code{vnc-server-command} (type: file-like)
+The Xvnc command to use for the VNC server, it's possible to provide
+extra options not otherwise exposed along the command, for example to
+disable security:
+
+@lisp
+(vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
+ " -SecurityTypes None" ))
+@end lisp
+
+Or to set a PasswordFile for the classic (unsecure) VncAuth
+mecanism:
+
+@lisp
+(vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
+ " -PasswordFile /var/lib/lightdm/.vnc/passwd"))
+@end lisp
+
+The password file should be manually created using the
+@command{vncpasswd} command. Note that LightDM will create new sessions
+for VNC users, which means they need to authenticate in the same way as
+local users would.
+
+@item @code{vnc-server-listen-address} (type: maybe-string)
+The host or IP address the VNC server listens for incoming connections.
+When unspecified, listen for any hosts/IP addresses.
+
+@item @code{vnc-server-port} (default: @code{5900}) (type: number)
+The TCP port the VNC server should listen to.
+
+@item @code{extra-config} (default: @code{()}) (type: list-of-strings)
+Extra configuration values to append to the LightDM configuration file.
-@item @code{auto-login-session} (default: @code{""})
-If non-empty, this is the @file{.desktop} file name to use as the
-auto-login session.
@end table
@end deftp
+
+@c %end of fragment
+@c %start of fragment
+
+@deftp {Data Type} lightdm-gtk-greeter-configuration
+Available @code{lightdm-gtk-greeter-configuration} fields are:
+
+@table @asis
+@item @code{lightdm-gtk-greeter} (default: @code{lightdm-gtk-greeter}) (type: file-like)
+The lightdm-gtk-greeter package to use.
+
+@item @code{assets} @
+(default: @code{(adwaita-icon-theme gnome-themes-extrahicolor-icon-theme)}) @
+(type: list-of-file-likes)
+The list of packages complementing the greeter, such as package
+providing icon themes.
+
+@item @code{theme-name} (default: @code{"Adwaita"}) (type: string)
+The name of the theme to use.
+
+@item @code{icon-theme-name} (default: @code{"Adwaita"}) (type: string)
+The name of the icon theme to use.
+
+@item @code{cursor-theme-name} (default: @code{"Adwaita"}) (type: string)
+The name of the cursor theme to use.
+
+@item @code{cursor-theme-size} (default: @code{16}) (type: number)
+The size to use for the cursor theme.
+
+@item @code{allow-debugging?} (type: maybe-boolean)
+Set to #t to enable debug log level.
+
+@item @code{background} (type: file-like)
+The background image to use.
+
+@item @code{at-spi-enabled?} (default: @code{#f}) (type: boolean)
+Enable accessibility support through the Assistive Technology Service
+Provider Interface (AT-SPI).
+
+@item @code{a11y-states} @
+(default: @code{(contrast font keyboard reader)}) (type: list-of-a11y-states)
+The accessibility features to enable, given as list of symbols.
+
+@item @code{reader} (type: maybe-file-like)
+The command to use to launch a screen reader.
+
+@item @code{extra-config} (default: @code{()}) (type: list-of-strings)
+Extra configuration values to append to the LightDM GTK Greeter
+configuration file.
+
+@end table
+@end deftp
+
+@c %end of fragment
+@c %start of fragment
+
+@deftp {Data Type} lightdm-seat-configuration
+Available @code{lightdm-seat-configuration} fields are:
+
+@table @asis
+@item @code{name} (type: seat-name)
+The name of the seat. An asterisk (*) can be used in the name to apply
+the seat configuration to all the seat names it matches.
+
+@item @code{user-session} (type: maybe-string)
+The session to use by default. The session name must be provided as a
+lowercase string, such as @code{"gnome"}, @code{"ratpoison"}, etc.
+
+@item @code{type} (default: @code{local}) (type: seat-type)
+The type of the seat, either the @code{local} or @code{xremote} symbol.
+
+@item @code{autologin-user} (type: maybe-string)
+The username to automatically log in with by default.
+
+@item @code{greeter-session} @
+(default: @code{lightdm-gtk-greeter}) (type: greeter-session)
+The greeter session to use, specified as a symbol. Currently, only
+@code{lightdm-gtk-greeter} is supported.
+
+@item @code{xserver-command} (type: maybe-file-like)
+The Xorg server command to run.
+
+@item @code{session-wrapper} (type: file-like)
+The xinitrc session wrapper to use.
+
+@item @code{extra-config} (default: @code{()}) (type: list-of-strings)
+Extra configuration values to append to the seat configuration section.
+
+@end table
+@end deftp
+@c %end of fragment
+
+
@cindex Xorg, configuration
@deftp {Data Type} xorg-configuration
-This data type represents the configuration of the Xorg graphical display
-server. Note that there is no 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.
+This data type represents the configuration of the Xorg graphical
+display server. Note that there is no Xorg service; instead, the X
+server is started by a ``display manager'' such as GDM, SDDM, LightDM or
+SLiM@. Thus, the configuration of these display managers aggregates an
+@code{xorg-configuration} record.
@table @asis
@item @code{modules} (default: @code{%default-xorg-modules})
(list cups-filters epson-inkjet-printer-escpr hplip-minimal))))
@end lisp
-Note: If you wish to use the Qt5 based GUI which comes with the hplip
+@quotation Note
+If you wish to use the Qt5 based GUI which comes with the hplip
package then it is suggested that you install the @code{hplip} package,
either in your OS configuration file or as your user.
+@end quotation
The available configuration parameters follow. Each parameter
definition is preceded by its type; for example, @samp{string-list foo}
provided by @code{(gnu services dbus)} and @code{(gnu services desktop)}
are described below.
-@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
+@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()] @
+ [#:verbose?]
Return a service that runs the ``system bus'', using @var{dbus}, with
-support for @var{services}.
+support for @var{services}. When @var{verbose?} is true, it causes the
+@samp{DBUS_VERBOSE} environment variable to be set to @samp{1}; a
+verbose-enabled D-Bus package such as @code{dbus-verbose} should be
+provided as @var{dbus} in this scenario. The verbose output is logged
+to @file{/var/log/dbus-daemon.log}.
@uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process communication
facility. Its system bus is used to allow system services to communicate
@item handle-lid-switch-docked
@code{ignore}
@item handle-lid-switch-external-power
-@code{ignore}
+@code{*unspecified*}
@item power-key-ignore-inhibited?
@code{#f}
@item suspend-key-ignore-inhibited?
@item @code{ignore-lid?} (default: @code{#f})
Ignore the lid state, this can be useful if it's incorrect on a device.
-@item @code{use-percentage-for-policy?} (default: @code{#f})
-Whether battery percentage based policy should be used. The default is to use
-the time left, change to @code{#t} to use the percentage.
+@item @code{use-percentage-for-policy?} (default: @code{#t})
+Whether to use a policy based on battery percentage rather than on
+estimated time left. A policy based on battery percentage is usually
+more reliable.
-@item @code{percentage-low} (default: @code{10})
+@item @code{percentage-low} (default: @code{20})
When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
at which the battery is considered low.
-@item @code{percentage-critical} (default: @code{3})
+@item @code{percentage-critical} (default: @code{5})
When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
at which the battery is considered critical.
LE scanning window used for connection establishment.
@item @code{min-connection-interval} (default: @code{#f})
-LE default minimum connection interval. This value is superceeded by any specific
+LE default minimum connection interval. This value is superseded by any specific
value provided via the Load Connection Parameters interface.
@item @code{max-connection-interval} (default: @code{#f})
-LE default maximum connection interval. This value is superceeded by any specific
+LE default maximum connection interval. This value is superseded by any specific
value provided via the Load Connection Parameters interface.
@item @code{connection-latency} (default: @code{#f})
-LE default connection latency. This value is superceeded by any specific
+LE default connection latency. This value is superseded by any specific
value provided via the Load Connection Parameters interface.
@item @code{connection-supervision-timeout} (default: @code{#f})
-LE default connection supervision timeout. This value is superceeded by any specific
+LE default connection supervision timeout. This value is superseded by any specific
value provided via the Load Connection Parameters interface.
@item @code{autoconnect-timeout} (default: @code{#f})
-LE default autoconnect timeout. This value is superceeded by any specific
+LE default autoconnect timeout. This value is superseded by any specific
value provided via the Load Connection Parameters interface.
@item @code{adv-mon-allowlist-scan-duration} (default: @code{300})
@end table
@end deftp
+@defvr {Scheme Variable} seatd-service-type
+@uref{https://sr.ht/~kennylevinsen/seatd/, seatd} is a minimal seat
+management daemon.
+
+Seat management takes care of mediating access to shared devices (graphics,
+input), without requiring the applications needing access to be root.
+
+@lisp
+(append
+ (list
+ ;; make sure seatd is running
+ (service seatd-service-type))
+
+ ;; normally one would want %base-services
+ %base-services)
+
+@end lisp
+
+@code{seatd} operates over a UNIX domain socket, with @code{libseat}
+providing the client side of the protocol. Applications that acquire
+access to the shared resources via @code{seatd} (e.g. @code{sway})
+need to be able to talk to this socket.
+This can be achieved by adding the user they run under to the group
+owning @code{seatd}'s socket (usually ``seat''), like so:
+
+@lisp
+(user-account
+ (name "alice")
+ (group "users")
+ (supplementary-groups '("wheel" ; allow use of sudo, etc.
+ "seat" ; seat management
+ "audio" ; sound card
+ "video" ; video devices such as webcams
+ "cdrom")) ; the good ol' CD-ROM
+ (comment "Bob's sister"))
+@end lisp
+
+Depending on your setup, you will have to not only add regular users,
+but also system users to this group. For instance, some greetd greeters
+require graphics and therefore also need to negotiate with seatd.
+
+@end defvr
+
+@deftp {Data Type} seatd-configuration
+Configuration record for the seatd daemon service.
+
+@table @asis
+@item @code{seatd} (default: @code{seatd})
+The seatd package to use.
+
+@item @code{group} (default: @samp{"seat"})
+Group to own the seatd socket.
+
+@item @code{socket} (default: @samp{"/run/seatd.sock"})
+Where to create the seatd socket.
+
+@item @code{logfile} (default: @samp{"/var/log/seatd.log"})
+Log file to write to.
+
+@item @code{loglevel} (default: @samp{"error"})
+Log level to output logs. Possible values: @samp{"silent"}, @samp{"error"},
+@samp{"info"} and @samp{"debug"}.
+
+@end table
+@end deftp
+
+
@node Sound Services
@subsection Sound Services
directive pointing to @file{/etc/pulse/default.pa.d} is appended to the
provided script.
-@item @code{extra-script-files} (default: @code{'())})
+@item @code{extra-script-files} (default: @code{'()})
A list of file-like objects defining extra PulseAudio scripts to run at
the initialization of the @command{pulseaudio} daemon, after the main
@code{script-file}. The scripts are deployed to the
@item @code{package} (default: @var{opensmtpd})
Package object of the OpenSMTPD SMTP server.
-@item @code{config-file} (default: @code{%default-opensmtpd-file})
+@item @code{config-file} (default: @code{%default-opensmtpd-config-file})
File-like object of the OpenSMTPD configuration file to use. By default
it listens on the loopback network interface, and allows for mail from
users and daemons on the local machine, as well as permitting email to
remote servers. Run @command{man smtpd.conf} for more information.
+@item @code{setgid-commands?} (default: @code{#t})
+Make the following commands setgid to @code{smtpq} so they can be
+executed: @command{smtpctl}, @command{sendmail}, @command{send-mail},
+@command{makemap}, @command{mailq}, and @command{newaliases}.
+@xref{Setuid Programs}, for more information on setgid programs.
@end table
@end deftp
definition is preceded by its type; for example, @samp{string-list foo}
indicates that the @code{foo} parameter should be specified as a list of
strings. Types starting with @code{maybe-} denote parameters that won't
-show up in @code{prosody.cfg.lua} when their value is @code{'disabled}.
+show up in @code{prosody.cfg.lua} when their value is left unspecified.
There is also a way to specify the configuration as a string, if you
have an old @code{prosody.cfg.lua} file that you want to port over from
@samp{"john.smith@@example.com"} then you need to add a host
@samp{"example.com"}. All options in this list will apply only to this host.
-Note: the name @emph{virtual} host is used in configuration to avoid confusion with
+@quotation Note
+The name @emph{virtual} host is used in configuration to avoid confusion with
the actual physical host that Prosody is installed on. A single Prosody
instance can serve many domains, each one defined as a VirtualHost entry in
Prosody's configuration. Conversely a server that hosts a single domain would
have just one VirtualHost entry.
See @url{https://prosody.im/doc/configure#virtual_host_settings}.
+@end quotation
Available @code{virtualhost-configuration} fields are:
Available @code{jami-configuration} fields are:
@table @asis
-@item @code{jamid} (default: @code{libjami}) (type: package)
+@item @code{libjami} (default: @code{libjami}) (type: package)
The Jami daemon package to use.
-@item @code{dbus} (default: @code{dbus}) (type: package)
+@item @code{dbus} (default: @code{dbus-for-jami}) (type: package)
The D-Bus package to use to start the required D-Bus session.
@item @code{nss-certs} (default: @code{nss-certs}) (type: package)
@item @code{auto-answer?} (default: @code{#f}) (type: boolean)
Whether to force automatic answer to incoming calls.
-@item @code{accounts} (default: @code{disabled}) (type: maybe-jami-account-list)
+@item @code{accounts} (type: maybe-jami-account-list)
A list of Jami accounts to be (re-)provisioned every time the Jami
daemon service starts. When providing this field, the account
directories under @file{/var/lib/jami/} are recreated every time the
readable only to the @samp{root} user (i.e., not in the store), to guard
against leaking the secret key material of the Jami account it contains.
-@item @code{allowed-contacts} (default: @code{disabled}) (type: maybe-account-fingerprint-list)
+@item @code{allowed-contacts} (type: maybe-account-fingerprint-list)
The list of allowed contacts for the account, entered as their 40
characters long fingerprint. Messages or calls from accounts not in
-that list will be rejected. When unspecified, the configuration of the
-account archive is used as-is with respect to contacts and public
+that list will be rejected. When left specified, the configuration of
+the account archive is used as-is with respect to contacts and public
inbound calls/messaging allowance, which typically defaults to allow any
contact to communicate with the account.
-@item @code{moderators} (default: @code{disabled}) (type: maybe-account-fingerprint-list)
+@item @code{moderators} (type: maybe-account-fingerprint-list)
The list of contacts that should have moderation privileges (to ban,
mute, etc. other users) in rendezvous conferences, entered as their 40
-characters long fingerprint. When unspecified, the configuration of the
-account archive is used as-is with respect to moderation, which
+characters long fingerprint. When left unspecified, the configuration
+of the account archive is used as-is with respect to moderation, which
typically defaults to allow anyone to moderate.
-@item @code{rendezvous-point?} (default: @code{disabled}) (type: maybe-boolean)
+@item @code{rendezvous-point?} (type: maybe-boolean)
Whether the account should operate in the rendezvous mode. In this
mode, all the incoming audio/video calls are mixed into a conference.
When left unspecified, the value from the account archive prevails.
-@item @code{peer-discovery?} (default: @code{disabled}) (type: maybe-boolean)
+@item @code{peer-discovery?} (type: maybe-boolean)
Whether peer discovery should be enabled. Peer discovery is used to
discover other OpenDHT nodes on the local network, which can be useful
to maintain communication between devices on such network even when the
-connection to the the Internet has been lost. When left unspecified,
+connection to the Internet has been lost. When left unspecified,
the value from the account archive prevails.
-@item @code{bootstrap-hostnames} (default: @code{disabled}) (type: maybe-string-list)
+@item @code{bootstrap-hostnames} (type: maybe-string-list)
A list of hostnames or IPs pointing to OpenDHT nodes, that should be
used to initially join the OpenDHT network. When left unspecified, the
value from the account archive prevails.
-@item @code{name-server-uri} (default: @code{disabled}) (type: maybe-string)
+@item @code{name-server-uri} (type: maybe-string)
The URI of the name server to use, that can be used to retrieve the
account fingerprint for a registered username.
@end deftp
-@subsubheading Murmur (VoIP server)
+@subsubheading Mumble server
-@cindex Murmur (VoIP server)
+@cindex Mumble
+@cindex Murmur
@cindex VoIP server
-This section describes how to set up and run a Murmur server. Murmur is
-the server of the @uref{https://mumble.info, Mumble} voice-over-IP
-(VoIP) suite.
+This section describes how to set up and run a
+@uref{https://mumble.info, Mumble} server (formerly known as Murmur).
-@deftp {Data Type} murmur-configuration
-The service type for the Murmur server. An example configuration can
+@deftp {Data Type} mumble-server-configuration
+The service type for the Mumble server. An example configuration can
look like this:
@lisp
-(service murmur-service-type
- (murmur-configuration
+(service mumble-server-service-type
+ (mumble-server-configuration
(welcome-text
"Welcome to this Mumble server running on Guix!")
(cert-required? #t) ;disallow text password logins
(ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem")))
@end lisp
-After reconfiguring your system, you can manually set the murmur @code{SuperUser}
+After reconfiguring your system, you can manually set the mumble-server
+@code{SuperUser}
password with the command that is printed during the activation phase.
It is recommended to register a normal Mumble user account
and grant your newly registered mumble user administrator or moderator
rights and create some channels.
-Available @code{murmur-configuration} fields are:
+Available @code{mumble-server-configuration} fields are:
@table @asis
@item @code{package} (default: @code{mumble})
-Package that contains @code{bin/murmurd}.
+Package that contains @code{bin/mumble-server}.
-@item @code{user} (default: @code{"murmur"})
-User who will run the Murmur server.
+@item @code{user} (default: @code{"mumble-server"})
+User who will run the Mumble-Server server.
-@item @code{group} (default: @code{"murmur"})
-Group of the user who will run the murmur server.
+@item @code{group} (default: @code{"mumble-server"})
+Group of the user who will run the mumble-server server.
@item @code{port} (default: @code{64738})
Port on which the server will listen.
@item @code{max-user-bandwidth} (default: @code{#f})
Maximum voice traffic a user can send per second.
-@item @code{database-file} (default: @code{"/var/lib/murmur/db.sqlite"})
+@item @code{database-file} (default: @code{"/var/lib/mumble-server/db.sqlite"})
File name of the sqlite database.
The service's user will become the owner of the directory.
-@item @code{log-file} (default: @code{"/var/log/murmur/murmur.log"})
+@item @code{log-file} (default: @code{"/var/log/mumble-server/mumble-server.log"})
File name of the log file.
The service's user will become the owner of the directory.
will not be accepted. Users must have completed the certificate wizard to join.
@item @code{remember-channel?} (default: @code{#f})
-Should murmur remember the last channel each user was in when they disconnected
-and put them into the remembered channel when they rejoin.
+Should mumble-server remember the last channel each user was in when
+they disconnected and put them into the remembered channel when they
+rejoin.
@item @code{allow-html?} (default: @code{#f})
Should html be allowed in text messages, user comments, and channel descriptions.
Should the server advertise itself in the local network through the bonjour protocol.
@item @code{send-version?} (default: @code{#f})
-Should the murmur server version be exposed in ping requests.
+Should the mumble-server server version be exposed in ping requests.
@item @code{log-days} (default: @code{31})
-Murmur also stores logs in the database, which are accessible via RPC.
+Mumble also stores logs in the database, which are accessible via RPC.
The default is 31 days of months, but you can set this setting to 0 to keep logs forever,
or -1 to disable logging to the database.
@uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT,
OpenSSL cipher list notation}.
-It is recommended that you try your cipher string using 'openssl ciphers <string>'
-before setting it here, to get a feel for which cipher suites you will get.
-After setting this option, it is recommend that you inspect your Murmur log
-to ensure that Murmur is using the cipher suites that you expected it to.
+It is recommended that you try your cipher string using
+'openssl ciphers <string>' before setting it here, to get a feel for
+which cipher suites you will get.
+After setting this option, it is recommend that you inspect your Mumble
+server log to ensure that Mumble is using the cipher suites that you
+expected it to.
-Note: Changing this option may impact the backwards compatibility of your
-Murmur server, and can remove the ability for older Mumble clients to be able
-to connect to it.
+@quotation Note
+Changing this option may impact the backwards compatibility of your
+Mumble-Server server, and can remove the ability for older Mumble clients to be able to connect to it.
+@end quotation
@item @code{public-registration} (default: @code{#f})
-Must be a @code{<murmur-public-registration-configuration>} record or @code{#f}.
+Must be a @code{<mumble-server-public-registration-configuration>}
+record or @code{#f}.
You can optionally register your server in the public server list that the
@code{mumble} client shows on startup.
@end table
@end deftp
-@deftp {Data Type} murmur-public-registration-configuration
-Configuration for public registration of a murmur service.
+@deftp {Data Type} mumble-server-public-registration-configuration
+Configuration for public registration of a mumble-server service.
@table @asis
@item @code{name}
@end table
@end deftp
-
+@quotation Deprecation notice
+Due to historical reasons, all of the above @code{mumble-server-}
+procedures are also exported with the @code{murmur-} prefix.
+It is recommended that you switch to using @code{mumble-server-}
+going forward.
+@end quotation
@node File-Sharing Services
@subsection File-Sharing Services
@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm
The TCP congestion-control algorithm to use for peer connections,
specified using a string recognized by the operating system in calls to
-@code{setsockopt} (or set to @code{disabled}, in which case the
-operating-system default is used).
+@code{setsockopt}. When left unspecified, the operating-system default
+is used.
Note that on GNU/Linux systems, the kernel must be configured to allow
processes to use a congestion-control algorithm not in the default set;
@item @code{nginx} (default: @code{nginx})
The nginx package to use.
+@item @code{shepherd-requirement} (default: @code{'()})
+This is a list of symbols naming Shepherd services the nginx service
+will depend on.
+
+This is useful if you would like @command{nginx} to be started after a
+back-end web server or a logging service such as Anonip has been
+started.
+
@item @code{log-directory} (default: @code{"/var/log/nginx"})
The directory to which NGinx will write log files.
the default port is 80, and a different port can be specified
explicitly.
+@item @code{extra-content}
+A string or list of strings to add to the upstream block.
+
@end table
@end deftp
@item @code{no-resolv?} (default: @code{#f})
When true, don't read @var{resolv-file}.
+@item @code{forward-private-reverse-lookup?} (default: @code{#t})
+When false, all reverse lookups for private IP ranges are answered with
+"no such domain" rather than being forwarded upstream.
+
+@item @code{query-servers-in-order?} (default: @code{#f})
+When true, dnsmasq queries the servers in the same order as they appear
+in @var{servers}.
+
@item @code{servers} (default: @code{'()})
Specify IP address of upstream servers directly.
@item @code{negative-cache?} (default: @code{#t})
When false, disable negative caching.
+@item @code{cpe-id} (default: @code{#f})
+If set, add a CPE (Customer-Premises Equipment) identifier to DNS
+queries which are forwarded upstream.
+
@item @code{tftp-enable?} (default: @code{#f})
Whether to enable the built-in TFTP server.
@c %end of fragment
+@node VNC Services
+@subsection VNC Services
+@cindex VNC (virtual network computing)
+@cindex XDMCP (x display manager control protocol)
+
+The @code{(gnu services vnc)} module provides services related to
+@dfn{Virtual Network Computing} (VNC), which makes it possible to
+locally use graphical Xorg applications running on a remote machine.
+Combined with a graphical manager that supports the @dfn{X Display
+Manager Control Protocol}, such as GDM (@pxref{gdm}) or LightDM
+(@pxref{lightdm}), it is possible to remote an entire desktop for a
+multi-user environment.
+
+@subsubheading Xvnc
+
+Xvnc is a VNC server that spawns its own X window server; which means it
+can run on headless servers. The Xvnc implementations provided by the
+@code{tigervnc-server} and @code{turbovnc} aim to be fast and efficient.
+
+@defvar {Scheme Variable} xvnc-service-type
+
+The @code{xvnc-server-type} service can be configured via the
+@code{xvnc-configuration} record, documented below. A second virtual
+display could be made available on a remote machine via the
+following configuration:
+@end defvar
+
+@lisp
+(service xvnc-service-type (xvnc-configuration (display-number 10)
+@end lisp
+
+As a demonstration, the @command{xclock} command could then be started
+on the remote machine on display number 10, and it could be displayed
+locally via the @command{vncviewer} command:
+@example
+# Start xclock on the remote machine.
+ssh -L5910:localhost:5910 -- guix shell xclock -- env DISPLAY=:10 xclock
+# Access it via VNC.
+guix shell tigervnc-client -- vncviewer localhost:5910
+@end example
+
+The following configuration combines XDMCP and Inetd to allow multiple
+users to concurrently use the remote system, login in graphically via
+the GDM display manager:
+
+@lisp
+(operating-system
+ [...]
+ (services (cons*
+ [...]
+ (service xvnc-service-type (xvnc-configuration
+ (display-number 5)
+ (localhost? #f)
+ (xdmcp? #t)
+ (inetd? #t)))
+ (modify-services %desktop-services
+ (gdm-service-type config => (gdm-configuration
+ (inherit config)
+ (auto-suspend? #f)
+ (xdmcp? #t)))))))
+@end lisp
+
+A remote user could then connect to it by using the @command{vncviewer}
+command or a compatible VNC client and start a desktop session of their
+choosing:
+@example
+vncviewer remote-host:5905
+@end example
+
+@quotation Warning
+Unless your machine is in a controlled environment, for security
+reasons, the @code{localhost?} configuration of the
+@code{xvnc-configuration} record should be left to its default @code{#t}
+value and exposed via a secure means such as an SSH port forward. The
+XDMCP port, UDP 177 should also be blocked from the outside by a
+firewall, as it is not a secure protocol and can expose login
+credentials in clear.
+@end quotation
+
+@c Use (configuration->documentation 'xvnc-configuration) to regenerate
+@c the documentation.
+@c %start of fragment
+@deftp {Data Type} xvnc-configuration
+Available @code{xvnc-configuration} fields are:
+
+@table @asis
+@item @code{xvnc} (default: @code{tigervnc-server}) (type: file-like)
+The package that provides the Xvnc binary.
+
+@item @code{display-number} (default: @code{0}) (type: number)
+The display number used by Xvnc. You should set this to a number not
+already used a Xorg server.
+
+@item @code{geometry} (default: @code{"1024x768"}) (type: string)
+The size of the desktop to be created.
+
+@item @code{depth} (default: @code{24}) (type: color-depth)
+The pixel depth in bits of the desktop to be created. Accepted values
+are 16, 24 or 32.
+
+@item @code{port} (type: maybe-port)
+The port on which to listen for connections from viewers. When left
+unspecified, it defaults to 5900 plus the display number.
+
+@item @code{ipv4?} (default: @code{#t}) (type: boolean)
+Use IPv4 for incoming and outgoing connections.
+
+@item @code{ipv6?} (default: @code{#t}) (type: boolean)
+Use IPv6 for incoming and outgoing connections.
+
+@item @code{password-file} (type: maybe-string)
+The password file to use, if any. Refer to vncpasswd(1) to learn how to
+generate such a file.
+
+@item @code{xdmcp?} (default: @code{#f}) (type: boolean)
+Query the XDMCP server for a session. This enables users to log in a
+desktop session from the login manager screen. For a multiple users
+scenario, you'll want to enable the @code{inetd?} option as well, so
+that each connection to the VNC server is handled separately rather than
+shared.
+
+@item @code{inetd?} (default: @code{#f}) (type: boolean)
+Use an Inetd-style service, which runs the Xvnc server on demand.
+
+@item @code{frame-rate} (default: @code{60}) (type: number)
+The maximum number of updates per second sent to each client.
+
+@item @code{security-types} (default: @code{("None")}) (type: security-types)
+The allowed security schemes to use for incoming connections. The
+default is "None", which is safe given that Xvnc is configured to
+authenticate the user via the display manager, and only for local
+connections. Accepted values are any of the following: ("None"
+"VncAuth" "Plain" "TLSNone" "TLSVnc" "TLSPlain" "X509None" "X509Vnc")
+
+@item @code{localhost?} (default: @code{#t}) (type: boolean)
+Only allow connections from the same machine. It is set to #true by
+default for security, which means SSH or another secure means should be
+used to expose the remote port.
+
+@item @code{log-level} (default: @code{30}) (type: log-level)
+The log level, a number between 0 and 100, 100 meaning most verbose
+output. The log messages are output to syslog.
+
+@item @code{extra-options} (default: @code{()}) (type: strings)
+This can be used to provide extra Xvnc options not exposed via this
+<xvnc-configuration> record.
+
+@end table
+
+@end deftp
+@c %end of fragment
@node VPN Services
@subsection VPN Services
@c %automatically generated documentation
+@deftp {Data Type} openvpn-client-configuration
Available @code{openvpn-client-configuration} fields are:
-@deftypevr {@code{openvpn-client-configuration} parameter} package openvpn
+@table @asis
+@item @code{openvpn} (default: @code{openvpn}) (type: file-like)
The OpenVPN package.
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} string pid-file
+@item @code{pid-file} (default: @code{"/var/run/openvpn/openvpn.pid"}) (type: string)
The OpenVPN pid file.
-Defaults to @samp{"/var/run/openvpn/openvpn.pid"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} proto proto
+@item @code{proto} (default: @code{udp}) (type: proto)
The protocol (UDP or TCP) used to open a channel between clients and
servers.
-Defaults to @samp{udp}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} dev dev
+@item @code{dev} (default: @code{tun}) (type: dev)
The device type used to represent the VPN connection.
-Defaults to @samp{tun}.
-
-@end deftypevr
-
-If you do not have some of these files (eg.@: you use a username and
-password), you can disable any of the following three fields by setting
-it to @code{'disabled}.
-
-@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string ca
+@item @code{ca} (default: @code{"/etc/openvpn/ca.crt"}) (type: maybe-string)
The certificate authority to check connections against.
-Defaults to @samp{"/etc/openvpn/ca.crt"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string cert
+@item @code{cert} (default: @code{"/etc/openvpn/client.crt"}) (type: maybe-string)
The certificate of the machine the daemon is running on. It should be
signed by the authority given in @code{ca}.
-Defaults to @samp{"/etc/openvpn/client.crt"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string key
-The key of the machine the daemon is running on. It must be the key whose
-certificate is @code{cert}.
+@item @code{key} (default: @code{"/etc/openvpn/client.key"}) (type: maybe-string)
+The key of the machine the daemon is running on. It must be the key
+whose certificate is @code{cert}.
-Defaults to @samp{"/etc/openvpn/client.key"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} boolean comp-lzo?
+@item @code{comp-lzo?} (default: @code{#t}) (type: boolean)
Whether to use the lzo compression algorithm.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-key?
+@item @code{persist-key?} (default: @code{#t}) (type: boolean)
Don't re-read key files across SIGUSR1 or --ping-restart.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-tun?
+@item @code{persist-tun?} (default: @code{#t}) (type: boolean)
Don't close and reopen TUN/TAP device or run up/down scripts across
SIGUSR1 or --ping-restart restarts.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} boolean fast-io?
+@item @code{fast-io?} (default: @code{#f}) (type: boolean)
(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
poll/epoll/select prior to the write operation.
-Defaults to @samp{#f}.
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} number verbosity
+@item @code{verbosity} (default: @code{3}) (type: number)
Verbosity level.
-Defaults to @samp{3}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} tls-auth-client tls-auth
+@item @code{tls-auth} (default: @code{#f}) (type: tls-auth-client)
Add an additional layer of HMAC authentication on top of the TLS control
channel to protect against DoS attacks.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string auth-user-pass
+@item @code{auth-user-pass} (type: maybe-string)
Authenticate with server using username/password. The option is a file
-containing username/password on 2 lines. Do not use a file-like object as it
-would be added to the store and readable by any user.
+containing username/password on 2 lines. Do not use a file-like object
+as it would be added to the store and readable by any user.
-Defaults to @samp{'disabled}.
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage?
+@item @code{verify-key-usage?} (default: @code{#t}) (type: key-usage)
Whether to check the server certificate has server usage extension.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} bind bind?
+@item @code{bind?} (default: @code{#f}) (type: bind)
Bind to a specific local port number.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} resolv-retry resolv-retry?
+@item @code{resolv-retry?} (default: @code{#t}) (type: resolv-retry)
Retry resolving server address.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-client-configuration} parameter} openvpn-remote-list remote
+@item @code{remote} (default: @code{()}) (type: openvpn-remote-list)
A list of remote servers to connect to.
-Defaults to @samp{()}.
-
+@deftp {Data Type} openvpn-remote-configuration
Available @code{openvpn-remote-configuration} fields are:
-@deftypevr {@code{openvpn-remote-configuration} parameter} string name
+@table @asis
+@item @code{name} (default: @code{"my-server"}) (type: string)
Server name.
-Defaults to @samp{"my-server"}.
+@item @code{port} (default: @code{1194}) (type: number)
+Port number the server listens to.
-@end deftypevr
+@end table
-@deftypevr {@code{openvpn-remote-configuration} parameter} number port
-Port number the server listens to.
+@end deftp
-Defaults to @samp{1194}.
+@end table
-@end deftypevr
+@end deftp
-@end deftypevr
@c %end of automatic openvpn-client documentation
@c %automatically generated documentation
+@deftp {Data Type} openvpn-server-configuration
Available @code{openvpn-server-configuration} fields are:
-@deftypevr {@code{openvpn-server-configuration} parameter} package openvpn
+@table @asis
+@item @code{openvpn} (default: @code{openvpn}) (type: file-like)
The OpenVPN package.
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} string pid-file
+@item @code{pid-file} (default: @code{"/var/run/openvpn/openvpn.pid"}) (type: string)
The OpenVPN pid file.
-Defaults to @samp{"/var/run/openvpn/openvpn.pid"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} proto proto
+@item @code{proto} (default: @code{udp}) (type: proto)
The protocol (UDP or TCP) used to open a channel between clients and
servers.
-Defaults to @samp{udp}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} dev dev
+@item @code{dev} (default: @code{tun}) (type: dev)
The device type used to represent the VPN connection.
-Defaults to @samp{tun}.
-
-@end deftypevr
-
-If you do not have some of these files (eg.@: you use a username and
-password), you can disable any of the following three fields by setting
-it to @code{'disabled}.
-
-@deftypevr {@code{openvpn-server-configuration} parameter} maybe-string ca
+@item @code{ca} (default: @code{"/etc/openvpn/ca.crt"}) (type: maybe-string)
The certificate authority to check connections against.
-Defaults to @samp{"/etc/openvpn/ca.crt"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} maybe-string cert
+@item @code{cert} (default: @code{"/etc/openvpn/client.crt"}) (type: maybe-string)
The certificate of the machine the daemon is running on. It should be
signed by the authority given in @code{ca}.
-Defaults to @samp{"/etc/openvpn/client.crt"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} maybe-string key
-The key of the machine the daemon is running on. It must be the key whose
-certificate is @code{cert}.
-
-Defaults to @samp{"/etc/openvpn/client.key"}.
-
-@end deftypevr
+@item @code{key} (default: @code{"/etc/openvpn/client.key"}) (type: maybe-string)
+The key of the machine the daemon is running on. It must be the key
+whose certificate is @code{cert}.
-@deftypevr {@code{openvpn-server-configuration} parameter} boolean comp-lzo?
+@item @code{comp-lzo?} (default: @code{#t}) (type: boolean)
Whether to use the lzo compression algorithm.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-key?
+@item @code{persist-key?} (default: @code{#t}) (type: boolean)
Don't re-read key files across SIGUSR1 or --ping-restart.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-tun?
+@item @code{persist-tun?} (default: @code{#t}) (type: boolean)
Don't close and reopen TUN/TAP device or run up/down scripts across
SIGUSR1 or --ping-restart restarts.
-Defaults to @samp{#t}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} boolean fast-io?
+@item @code{fast-io?} (default: @code{#f}) (type: boolean)
(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
poll/epoll/select prior to the write operation.
-Defaults to @samp{#f}.
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} number verbosity
+@item @code{verbosity} (default: @code{3}) (type: number)
Verbosity level.
-Defaults to @samp{3}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} tls-auth-server tls-auth
+@item @code{tls-auth} (default: @code{#f}) (type: tls-auth-server)
Add an additional layer of HMAC authentication on top of the TLS control
channel to protect against DoS attacks.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} number port
+@item @code{port} (default: @code{1194}) (type: number)
Specifies the port number on which the server listens.
-Defaults to @samp{1194}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} ip-mask server
+@item @code{server} (default: @code{"10.8.0.0 255.255.255.0"}) (type: ip-mask)
An ip and mask specifying the subnet inside the virtual network.
-Defaults to @samp{"10.8.0.0 255.255.255.0"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} cidr6 server-ipv6
+@item @code{server-ipv6} (default: @code{#f}) (type: cidr6)
A CIDR notation specifying the IPv6 subnet inside the virtual network.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} string dh
+@item @code{dh} (default: @code{"/etc/openvpn/dh2048.pem"}) (type: string)
The Diffie-Hellman parameters file.
-Defaults to @samp{"/etc/openvpn/dh2048.pem"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} string ifconfig-pool-persist
+@item @code{ifconfig-pool-persist} (default: @code{"/etc/openvpn/ipp.txt"}) (type: string)
The file that records client IPs.
-Defaults to @samp{"/etc/openvpn/ipp.txt"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} gateway redirect-gateway?
+@item @code{redirect-gateway?} (default: @code{#f}) (type: gateway)
When true, the server will act as a gateway for its clients.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} boolean client-to-client?
+@item @code{client-to-client?} (default: @code{#f}) (type: boolean)
When true, clients are allowed to talk to each other inside the VPN.
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} keepalive keepalive
+@item @code{keepalive} (default: @code{(10 120)}) (type: keepalive)
Causes ping-like messages to be sent back and forth over the link so
that each side knows when the other side has gone down. @code{keepalive}
requires a pair. The first element is the period of the ping sending,
and the second element is the timeout before considering the other side
down.
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} number max-clients
+@item @code{max-clients} (default: @code{100}) (type: number)
The maximum number of clients.
-Defaults to @samp{100}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} string status
+@item @code{status} (default: @code{"/var/run/openvpn/status"}) (type: string)
The status file. This file shows a small report on current connection.
It is truncated and rewritten every minute.
-Defaults to @samp{"/var/run/openvpn/status"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-server-configuration} parameter} openvpn-ccd-list client-config-dir
+@item @code{client-config-dir} (default: @code{()}) (type: openvpn-ccd-list)
The list of configuration for some clients.
-Defaults to @samp{()}.
-
-Available @code{openvpn-ccd-configuration} fields are:
-
-@deftypevr {@code{openvpn-ccd-configuration} parameter} string name
-Client name.
-
-Defaults to @samp{"client"}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask iroute
-Client own network
-
-Defaults to @samp{#f}.
-
-@end deftypevr
-
-@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask ifconfig-push
-Client VPN IP.
-
-Defaults to @samp{#f}.
-
-@end deftypevr
+@end table
-@end deftypevr
+@end deftp
@c %end of automatic openvpn-server documentation
The authorized peers on this interface. This is a list of
@var{wireguard-peer} records.
+@item @code{pre-up} (default: @code{'()})
+The script commands to be run before setting up the interface.
+
+@item @code{post-up} (default: @code{'()})
+The script commands to be run after setting up the interface.
+
+@item @code{pre-down} (default: @code{'()})
+The script commands to be run before tearing down the interface.
+
+@item @code{post-down} (default: @code{'()})
+The script commands to be run after tearing down the interface.
+
+@item @code{table} (default: @code{"auto"})
+The routing table to which routes are added, as a string. There are two
+special values: @code{"off"} that disables the creation of routes
+altogether, and @code{"auto"} (the default) that adds routes to the
+default table and enables special handling of default routes.
+
@end table
@end deftp
@end table
@end deftp
+@node Samba Services, Continuous Integration, Network File System, Services
+@subsection Samba Services
+
+@cindex Samba
+@cindex SMB
+The @code{(gnu services samba)} module provides service definitions for
+Samba as well as additional helper services. Currently it provides the
+following services.
+
+@subsubheading Samba
+
+@uref{https://www.samba.org, Samba} provides network shares for folders
+and printers using the SMB/CIFS protocol commonly used on Windows. It
+can also act as an Active Directory Domain Controller (AD DC) for other
+hosts in an heterougenious network with different types of Computer
+systems.
+
+@defvar {Scheme variable} samba-service-type
+
+The service type to enable the samba services @code{samba}, @code{nmbd},
+@code{smbd} and @code{winbindd}. By default this service type does not
+run any of the Samba daemons; they must be enabled individually.
+
+Below is a basic example that configures a simple, anonymous
+(unauthenticated) Samba file share exposing the @file{/public}
+directory.
+
+@quotation Tip
+The @file{/public} directory and its contents must be world
+readable/writable, so you'll want to run @samp{chmod -R 777 /public} on
+it.
+@end quotation
+
+@quotation Caution
+Such a Samba configuration should only be used in controlled
+environments, and you should not share any private files using it, as
+anyone connecting to your network would be able to access them.
+@end quotation
+
+@lisp
+(service samba-service-type (samba-configuration
+ (enable-smbd? #t)
+ (config-file (plain-file "smb.conf" "\
+[global]
+map to guest = Bad User
+logging = syslog@@1
+
+[public]
+browsable = yes
+path = /public
+read only = no
+guest ok = yes
+guest only = yes\n"))))
+@end lisp
+
+@end defvar
+
+@deftp{Data Type} samba-service-configuration
+Configuration record for the Samba suite.
+
+@table @asis
+@item @code{package} (default: @code{samba})
+The samba package to use.
+
+@item @code{config-file} (default: @code{#f})
+The config file to use. To learn about its syntax, run @samp{man
+smb.conf}.
+
+@item @code{enable-samba?} (default: @code{#f})
+Enable the @code{samba} daemon.
+
+@item @code{enable-smbd?} (default: @code{#f})
+Enable the @code{smbd} daemon.
+
+@item @code{enable-nmbd?} (default: @code{#f})
+Enable the @code{nmbd} daemon.
+
+@item @code{enable-winbindd?} (default: @code{#f})
+Enable the @code{winbindd} daemon.
+
+@end table
+@end deftp
+
+@cindex wsdd, Web service discovery daemon
+@subsubheading Web Service Discovery Daemon
+
+The @acronym{WSDD, Web Service Discovery daemon} implements the
+@uref{http://docs.oasis-open.org/ws-dd/discovery/1.1/os/wsdd-discovery-1.1-spec-os.html,
+Web Services Dynamic Discovery} protocol that enables host discovery
+over Multicast DNS, similar to what Avahi does. It is a drop-in
+replacement for SMB hosts that have had SMBv1 disabled for security
+reasons.
+
+@defvr {Scheme Variable} wsdd-service-type
+Service type for the WSD host daemon. The value for
+this service type is a @code{wsdd-configuration} record. The details
+for the @code{wsdd-configuration} record type are given below.
+@end defvr
+
+@deftp {Data Type} wsdd-configuration
+This data type represents the configuration for the wsdd service.
+
+@table @asis
+
+@item @code{package} (default: @code{wsdd})
+The wsdd package to use.
+
+@item @code{ipv4only?} (default: @code{#f})
+Only listen to IPv4 addresses.
+
+@item @code{ipv6only} (default: @code{#f})
+Only listen to IPv6 addresses. Please note: Activating both options is
+not possible, since there would be no IP versions to listen to.
+
+@item @code{chroot} (default: @code{#f})
+Chroot into a separate directory to prevent access to other directories.
+This is to increase security in case there is a vulnerability in
+@command{wsdd}.
+
+@item @code{hop-limit} (default: @code{1})
+Limit to the level of hops for multicast packets. The default is
+@var{1} which should prevent packets from leaving the local network.
+
+@item @code{interface} (default: @code{'()})
+Limit to the given list of interfaces to listen to. By default wsdd
+will listen to all interfaces. Except the loopback interface is never
+used.
+
+@item @code{uuid-device} (default: @code{#f})
+The WSD protocol requires a device to have a UUID. Set this to manually
+assign the service a UUID.
+
+@item @code{domain} (default: @code{#f})
+Notify this host is a member of an Active Directory.
+
+@item @code{host-name} (default: @code{#f})
+Manually set the hostname rather than letting @command{wsdd} inherit
+this host's hostname. Only the host name part of a possible FQDN will
+be used in the default case.
+
+@item @code{preserve-case?} (default: @code{#f})
+By default @command{wsdd} will convert the hostname in workgroup to all
+uppercase. The opposite is true for hostnames in domains. Setting this
+parameter will preserve case.
+
+@item @code{workgroup} (default: @var{"WORKGROUP"})
+Change the name of the workgroup. By default @command{wsdd} reports
+this host being member of a workgroup.
+
+@end table
+@end deftp
+
@node Continuous Integration
@subsection Continuous Integration
@end deffn
Each parameter definition is preceded by its type; for example,
-@samp{boolean foo} indicates that the @code{foo} parameter
-should be specified as a boolean. Types starting with
-@code{maybe-} denote parameters that won't show up in TLP config file
-when their value is @code{'disabled}.
+@samp{boolean foo} indicates that the @code{foo} parameter should be
+specified as a boolean. Types starting with @code{maybe-} denote
+parameters that won't show up in TLP config file when their value is
+left unset, or is explicitly set to the @code{%unset-value} value.
@c The following documentation was initially generated by
@c (generate-tlp-documentation) in (gnu services pm). Manually maintained
Data type representing the configuration of @code{thermald-service-type}.
@table @asis
+@item @code{adaptive?} (default: @code{#f})
+Use @acronym{DPTF, Dynamic Power and Thermal Framework} adaptive tables
+when present.
+
@item @code{ignore-cpuid-check?} (default: @code{#f})
Ignore cpuid check for supported CPU models.
@table @asis
@item @code{package} (default: @var{gitolite})
-Gitolite package to use.
+Gitolite package to use. There are optional Gitolite dependencies that
+are not included in the default package, such as Redis and git-annex.
+These features can be made available by using the @code{make-gitolite}
+procedure in the @code{(gnu packages version-control}) module to produce
+a variant of Gitolite with the desired additional dependencies.
+
+The following code returns a package in which the Redis and git-annex
+programs can be invoked by Gitolite's scripts:
+
+@example
+(use-modules (gnu packages databases)
+ (gnu packages haskell-apps)
+ (gnu packages version-control))
+(make-gitolite (list redis git-annex))
+@end example
@item @code{user} (default: @var{git})
User to use for Gitolite. This will be user that you use when accessing
An association list of hooks. These provide a way to execute arbitrary
code upon certain events, like a build result being processed.
+@item @code{parallel-hooks} (default: @var{'()})
+Hooks can be configured to run in parallel. This parameter is an
+association list of hooks to do in parallel, where the key is the symbol
+for the hook and the value is the number of threads to run.
+
@item @code{guile} (default: @code{guile-3.0-latest})
The Guile package with which to run the Guix Build Coordinator.
@item @code{max-parallel-builds} (default: @code{1})
The number of builds to perform in parallel.
+@item @code{max-allocated-builds} (default: @code{#f})
+The maximum number of builds this agent can be allocated.
+
@item @code{max-1min-load-average} (default: @code{#f})
Load average value to look at when considering starting new builds, if
the 1 minute load average exceeds this value, the agent will wait before
The Guix Data Service instance from which to query to find out about
derivations to build.
+@item @code{guix-data-service-build-server-id} (default: @code{#f})
+The Guix Data Service build server ID corresponding to the builds being
+submitted. Providing this speeds up the submitting of builds as
+derivations that have already been submitted can be skipped before
+asking the coordinator to build them.
+
@item @code{processed-commits-file} (default: @code{"/var/cache/guix-build-coordinator-queue-builds/processed-commits"})
A file to record which commits have been processed, to avoid needlessly
processing them again if the service is restarted.
which the HTTP 404 code is returned. By default, no negative TTL is
advertised.
+@item @code{log-level} (default: @code{'DEBUG})
+Log level to use, specify a log level like @code{'INFO} to stop logging
+individual requests.
+
@end table
@end deftp
can be written to swap and this is a method to limit how much memory can
be used. It accepts a string and can be a number of bytes or use a
suffix, eg.: @code{"2G"}.
-@item @code{priority} (default @code{-1})
+@item @code{priority} (default @code{#f})
This is the priority of the swap device created from the zram device.
-@code{swapon} accepts values between -1 and 32767, with higher values
-indicating higher priority. Higher priority swap will generally be used
-first.
+@xref{Swap Space} for a description of swap priorities. You might want
+to set a specific priority for the zram device, otherwise it could end
+up not being used much for the reasons described there.
@end table
@end deftp
@item @code{package} (default: @code{r-shiny})
The package to use.
-@item @code{binary} (defaunlt @code{"rshiny"})
+@item @code{binary} (default @code{"rshiny"})
The name of the binary or shell script located at @code{package/bin/} to
run when the service is run.
@end table
@end deftp
+@cindex Fail2Ban
+@subsubheading Fail2Ban service
+
+@uref{http://www.fail2ban.org/, @code{fail2ban}} scans log files
+(e.g. @code{/var/log/apache/error_log}) and bans IP addresses that show
+malicious signs -- repeated password failures, attempts to make use of
+exploits, etc.
+
+@code{fail2ban-service-type} service type is provided by the @code{(gnu
+services security)} module.
+
+This service type runs the @code{fail2ban} daemon. It can be configured
+in various ways, which are:
+
+@table @asis
+@item Basic configuration
+The basic parameters of the Fail2Ban service can be configured via its
+@code{fail2ban} configuration, which is documented below.
+
+@item User-specified jail extensions
+The @code{fail2ban-jail-service} function can be used to add new
+Fail2Ban jails.
+
+@item Shepherd extension mechanism
+Service developers can extend the @code{fail2ban-service-type} service
+type itself via the usual service extension mechanism.
+@end table
+
+@defvr {Scheme Variable} fail2ban-service-type
+
+This is the type of the service that runs @code{fail2ban} daemon. Below
+is an example of a basic, explicit configuration:
+
+@lisp
+(append
+ (list
+ (service fail2ban-service-type
+ (fail2ban-configuration
+ (extra-jails
+ (list
+ (fail2ban-jail-configuration
+ (name "sshd")
+ (enabled? #t))))))
+ ;; There is no implicit dependency on an actual SSH
+ ;; service, so you need to provide one.
+ (service openssh-service-type))
+ %base-services)
+@end lisp
+@end defvr
+
+@deffn {Scheme Procedure} fail2ban-jail-service @var{svc-type} @var{jail}
+Extend @var{svc-type}, a @code{<service-type>} object with @var{jail}, a
+@code{fail2ban-jail-configuration} object.
+
+For example:
+
+@lisp
+(append
+ (list
+ (service
+ ;; The 'fail2ban-jail-service' procedure can extend any service type
+ ;; with a fail2ban jail. This removes the requirement to explicitly
+ ;; extend services with fail2ban-service-type.
+ (fail2ban-jail-service
+ openssh-service-type
+ (fail2ban-jail-configuration
+ (name "sshd")
+ (enabled? #t)))
+ (openssh-configuration ...))))
+@end lisp
+@end deffn
+
+Below is the reference for the different @code{jail-service-type}
+configuration records.
+
+@c The documentation is to be auto-generated via
+@c 'generate-documentation'. See at the bottom of (gnu services
+@c security).
+
+@deftp {Data Type} fail2ban-configuration
+Available @code{fail2ban-configuration} fields are:
+
+@table @asis
+@item @code{fail2ban} (default: @code{fail2ban}) (type: package)
+The @code{fail2ban} package to use. It is used for both binaries and as
+base default configuration that is to be extended with
+@code{<fail2ban-jail-configuration>} objects.
+
+@item @code{run-directory} (default: @code{"/var/run/fail2ban"}) (type: string)
+The state directory for the @code{fail2ban} daemon.
+
+@item @code{jails} (default: @code{()}) (type: list-of-fail2ban-jail-configurations)
+Instances of @code{<fail2ban-jail-configuration>} collected from
+extensions.
+
+@item @code{extra-jails} (default: @code{()}) (type: list-of-fail2ban-jail-configurations)
+Instances of @code{<fail2ban-jail-configuration>} explicitly provided.
+
+@item @code{extra-content} (default: @code{()}) (type: text-config)
+Extra raw content to add to the end of the @file{jail.local} file,
+provided as a list of file-like objects.
+
+@end table
+
+@end deftp
+
+@deftp {Data Type} fail2ban-ignore-cache-configuration
+Available @code{fail2ban-ignore-cache-configuration} fields are:
+
+@table @asis
+@item @code{key} (type: string)
+Cache key.
+
+@item @code{max-count} (type: integer)
+Cache size.
+
+@item @code{max-time} (type: integer)
+Cache time.
+
+@end table
+
+@end deftp
+
+@deftp {Data Type} fail2ban-jail-action-configuration
+Available @code{fail2ban-jail-action-configuration} fields are:
+
+@table @asis
+@item @code{name} (type: string)
+Action name.
+
+@item @code{arguments} (default: @code{()}) (type: list-of-arguments)
+Action arguments.
+
+@end table
+
+@end deftp
+
+@deftp {Data Type} fail2ban-jail-configuration
+Available @code{fail2ban-jail-configuration} fields are:
+
+@table @asis
+@item @code{name} (type: string)
+Required name of this jail configuration.
+
+@item @code{enabled?} (default: @code{#t}) (type: boolean)
+Whether this jail is enabled.
+
+@item @code{backend} (type: maybe-symbol)
+Backend to use to detect changes in the @code{log-path}. The default is
+'auto. To consult the defaults of the jail configuration, refer to the
+@file{/etc/fail2ban/jail.conf} file of the @code{fail2ban} package.
+
+@item @code{max-retry} (type: maybe-integer)
+The number of failures before a host get banned (e.g. @code{(max-retry
+5)}).
+
+@item @code{max-matches} (type: maybe-integer)
+The number of matches stored in ticket (resolvable via tag
+@code{<matches>}) in action.
+
+@item @code{find-time} (type: maybe-string)
+The time window during which the maximum retry count must be reached for
+an IP address to be banned. A host is banned if it has generated
+@code{max-retry} during the last @code{find-time} seconds (e.g.
+@code{(find-time "10m")}). It can be provided in seconds or using
+Fail2Ban's "time abbreviation format", as described in @command{man 5
+jail.conf}.
+
+@item @code{ban-time} (type: maybe-string)
+The duration, in seconds or time abbreviated format, that a ban should
+last. (e.g. @code{(ban-time "10m")}).
+
+@item @code{ban-time-increment?} (type: maybe-boolean)
+Whether to consider past bans to compute increases to the default ban
+time of a specific IP address.
+
+@item @code{ban-time-factor} (type: maybe-string)
+The coefficient to use to compute an exponentially growing ban time.
+
+@item @code{ban-time-formula} (type: maybe-string)
+This is the formula used to calculate the next value of a ban time.
+
+@item @code{ban-time-multipliers} (type: maybe-string)
+Used to calculate next value of ban time instead of formula.
+
+@item @code{ban-time-max-time} (type: maybe-string)
+The maximum number of seconds a ban should last.
+
+@item @code{ban-time-rnd-time} (type: maybe-string)
+The maximum number of seconds a randomized ban time should last. This
+can be useful to stop ``clever'' botnets calculating the exact time an
+IP address can be unbanned again.
+
+@item @code{ban-time-overall-jails?} (type: maybe-boolean)
+When true, it specifies the search of an IP address in the database
+should be made across all jails. Otherwise, only the current jail of
+the ban IP address is considered.
+
+@item @code{ignore-self?} (type: maybe-boolean)
+Never ban the local machine's own IP address.
+
+@item @code{ignore-ip} (default: @code{()}) (type: list-of-strings)
+A list of IP addresses, CIDR masks or DNS hosts to ignore.
+@code{fail2ban} will not ban a host which matches an address in this
+list.
+
+@item @code{ignore-cache} (type: maybe-fail2ban-ignore-cache-configuration)
+Provide cache parameters for the ignore failure check.
+
+@item @code{filter} (type: maybe-fail2ban-jail-filter-configuration)
+The filter to use by the jail, specified via a
+@code{<fail2ban-jail-filter-configuration>} object. By default, jails
+have names matching their filter name.
+
+@item @code{log-time-zone} (type: maybe-string)
+The default time zone for log lines that do not have one.
+
+@item @code{log-encoding} (type: maybe-symbol)
+The encoding of the log files handled by the jail. Possible values are:
+@code{'ascii}, @code{'utf-8} and @code{'auto}.
+
+@item @code{log-path} (default: @code{()}) (type: list-of-strings)
+The file names of the log files to be monitored.
+
+@item @code{action} (default: @code{()}) (type: list-of-fail2ban-jail-actions)
+A list of @code{<fail2ban-jail-action-configuration>}.
+
+@item @code{extra-content} (default: @code{()}) (type: text-config)
+Extra content for the jail configuration, provided as a list of file-like
+objects.
+
+@end table
+
+@end deftp
+
+@deftp {Data Type} fail2ban-jail-filter-configuration
+Available @code{fail2ban-jail-filter-configuration} fields are:
+
+@table @asis
+@item @code{name} (type: string)
+Filter to use.
+
+@item @code{mode} (type: maybe-string)
+Mode for filter.
+
+@end table
+
+@end deftp
+
+@c End of auto-generated fail2ban documentation.
+
@node Setuid Programs
@section Setuid Programs
@cindex setuid programs
-Some programs need to run with ``root'' privileges, even when they are
+@cindex setgid programs
+Some programs need to run with elevated privileges, even when they are
launched by unprivileged users. A notorious example is the
@command{passwd} program, which users can run to change their
password, and which needs to access the @file{/etc/passwd} and
@file{/etc/shadow} files---something normally restricted to root, for
-obvious security reasons. To address that, these executables are
-@dfn{setuid-root}, meaning that they always run with root privileges
+obvious security reasons. To address that, @command{passwd} should be
+@dfn{setuid-root}, meaning that it always runs with root privileges
(@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
for more info about the setuid mechanism).
The store itself @emph{cannot} contain setuid programs: that would be a
security issue since any user on the system can write derivations that
populate the store (@pxref{The Store}). Thus, a different mechanism is
-used: instead of changing the setuid bit directly on files that are in
-the store, we let the system administrator @emph{declare} which programs
-should be setuid root.
+used: instead of changing the setuid or setgid bits directly on files that
+are in the store, we let the system administrator @emph{declare} which
+programs should be entrusted with these additional privileges.
The @code{setuid-programs} field of an @code{operating-system}
declaration contains a list of @code{<setuid-program>} denoting the
@item fsck.mode=@var{mode}
Whether to check the @var{root} file system for errors before mounting
it. @var{mode} is one of @code{skip} (never check), @code{force} (always
-check), or @code{auto} to respect the root file-system object's 'check?'
-setting (@pxref{File Systems}) and run a full scan only if the file system
-was not cleanly shut down.
+check), or @code{auto} to respect the root @code{<file-system>} object's
+@code{check?} setting (@pxref{File Systems}) and run a full scan only if
+the file system was not cleanly shut down.
@code{auto} is the default if this option is not present or if @var{mode}
is not one of the above.
@cindex BIOS, bootloader
The bootloader to use, as a @code{bootloader} object. For now
@code{grub-bootloader}, @code{grub-efi-bootloader},
-@code{grub-efi-netboot-bootloader}, @code{extlinux-bootloader} and
-@code{u-boot-bootloader} are supported.
+@code{grub-efi-netboot-bootloader}, @code{grub-efi-removable-bootloader},
+@code{extlinux-bootloader} and @code{u-boot-bootloader} are supported.
@cindex ARM, bootloaders
@cindex AArch64, bootloaders
over netboot possible. For all this we can currently only recommend you to look
for instructions about @acronym{PXE, Preboot eXecution Environment}.
+@vindex grub-efi-removable-bootloader
+@code{grub-efi-removable-bootloader} allows you to boot your system from
+removable media by writing the GRUB file to the UEFI-specification location of
+@file{/EFI/BOOT/BOOTX64.efi} of the boot directory, usually @file{/boot/efi}.
+This is also useful for some UEFI firmwares that ``forget'' their configuration
+from their non-volatile storage. Like @code{grub-efi-bootloader}, this can only
+be used if the @file{/sys/firmware/efi} directory is available.
+
+@quotation Note
+This @emph{will} overwrite the GRUB file from any other operating systems that
+also place their GRUB file in the UEFI-specification location; making them
+unbootable.
+@end quotation
+
@item @code{targets}
This is a list of strings denoting the targets onto which to install the
bootloader.
For @code{grub-bootloader}, for example, they should be device names
understood by the bootloader @command{installer} command, such as
@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
-GNU GRUB Manual}). For @code{grub-efi-bootloader}, they should be mount
+GNU GRUB Manual}). For @code{grub-efi-bootloader} and
+@code{grub-efi-removable-bootloader} they should be mount
points of the EFI file system, usually @file{/boot/efi}. For
@code{grub-efi-netboot-bootloader}, @code{targets} should be the mount
points corresponding to TFTP root directories served by your TFTP
The speed of the serial interface, as an integer. For GRUB, the
default value is chosen at run-time; currently GRUB chooses
9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
+
+@item @code{device-tree-support?} (default: @code{#t})
+Whether to support Linux @uref{https://en.wikipedia.org/wiki/Devicetree,
+device tree} files loading.
+
+This option in enabled by default. In some cases involving the
+@code{u-boot} bootloader, where the device tree has already been loaded
+in RAM, it can be handy to disable the option by setting it to
+@code{#f}.
@end table
@end deftp
@dots{}))
@end lisp
+@item @code{chain-loader} (default: @code{#f})
+A string that can be accepted by @code{grub}'s @code{chainloader}
+directive. This has no effect if either @code{linux} or
+@code{multiboot-kernel} fields are specified. The following is an
+example of chainloading a different GNU/Linux system.
+
+@lisp
+(bootloader
+ (bootloader-configuration
+ ;; @dots{}
+ (menu-entries
+ (list
+ (menu-entry
+ (label "GNU/Linux")
+ (device (uuid "1C31-A17C" 'fat))
+ (chain-loader "/EFI/GNULinux/grubx64.efi"))))))
+@end lisp
+
@end table
@end deftp
@end lisp
@node Invoking guix system
-@section Invoking @code{guix system}
+@section Invoking @command{guix system}
+@cindex @command{guix system}
Once you have written an operating system declaration as seen in the
previous section, it can be @dfn{instantiated} using the @command{guix
system} command. The synopsis is:
@code{recutils} format, which makes it easy to filter the output
(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
+@cindex service type definition, editing
+@cindex editing, service type definition
+@item edit
+Edit or view the definition of the given service types.
+
+For example, the command below opens your editor, as specified by the
+@env{EDITOR} environment variable, on the definition of the
+@code{openssh} service type:
+
+@example
+guix system edit openssh
+@end example
+
@item reconfigure
Build the operating system described in @var{file}, activate it, and
switch to it@footnote{This action (and the related actions
--expose=$HOME --share=$HOME/tmp=/exchange
@end example
+The @option{--share} and @option{--expose} options can also be passed to
+the generated script to bind-mount additional directories into the
+container.
+
@quotation Note
This option requires Linux-libre 3.19 or newer.
@end quotation
Attempt to build for @var{system} instead of the host system type.
This works as per @command{guix build} (@pxref{Invoking guix build}).
+@item --target=@var{triplet}
+Cross-build for @var{triplet}, which must be a valid GNU triplet, such
+as @code{"aarch64-linux-gnu"} (@pxref{Specifying target triplets, GNU
+configuration triplets,, autoconf, Autoconf}).
+
@item --derivation
@itemx -d
Return the derivation file name of the given operating system without
Describe the running system generation: its file name, the kernel and
bootloader used, etc., as well as provenance information when available.
+The @code{--list-installed} flag is available, with the same
+syntax that is used in @command{guix package --list-installed}
+(@pxref{Invoking guix package}). When the flag is used,
+the description will include a list of packages that are currently
+installed in the system profile, with optional filtering based on a
+regular expression.
+
@quotation Note
The @emph{running} system generation---referred to by
@file{/run/current-system}---is not necessarily the @emph{current}
$ guix system list-generations 10d
@end example
+The @code{--list-installed} flag may also be specified, with the same
+syntax that is used in @command{guix package --list-installed}. This
+may be helpful if trying to determine when a package was added to the
+system.
+
@end table
The @command{guix system} command has even more to offer! The following
shows the extension relations among services.
+@quotation Note
+The @command{dot} program is provided by the @code{graphviz} package.
+@end quotation
+
@anchor{system-shepherd-graph}
@item shepherd-graph
Emit to standard output the @dfn{dependency
@end table
@node Invoking guix deploy
-@section Invoking @code{guix deploy}
+@section Invoking @command{guix deploy}
+@cindex @command{guix deploy}
We've already seen @code{operating-system} declarations used to manage a
machine's configuration locally. Suppose you need to configure multiple
machines, though---perhaps you're managing a service on the web that's
@example
$ qemu-system-x86_64 \
-nic user,model=virtio-net-pci \
- -enable-kvm -m 1024 \
+ -enable-kvm -m 2048 \
-device virtio-blk,drive=myhd \
-drive if=none,file=/tmp/qemu-image,id=myhd
@end example
faster.
@c To run Xfce + 'guix pull', we need at least 1G of RAM.
-@item -m 1024
+@item -m 2048
RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB,
which may be insufficient for some operations.
@defvr {Scheme Variable} setuid-program-service-type
Type for the ``setuid-program service''. This service collects lists of
executable file names, passed as gexps, and adds them to the set of
-setuid-root programs on the system (@pxref{Setuid Programs}).
+setuid and setgid programs on the system (@pxref{Setuid Programs}).
@end defvr
@defvr {Scheme Variable} profile-service-type
in the same file, but their serializers for the same type might have to
be different, because they have different configuration formats. For
example, the @code{serialize-boolean} procedure for the Getmail service
-would have to be different for the one for the Transmission service. To
+would have to be different from the one for the Transmission service. To
make it easier to deal with this situation, one can specify a serializer
prefix by using the @code{prefix} literal in the
@code{define-configuration} form. This means that one doesn't have to
@deffn {Scheme Syntax} define-maybe @var{type}
Sometimes a field should not be serialized if the user doesn’t specify a
value. To achieve this, you can use the @code{define-maybe} macro to
-define a ``maybe type''; if the value of a maybe type is set to the
-@code{disabled}, it will not be serialized.
+define a ``maybe type''; if the value of a maybe type is left unset, or
+is set to the @code{%unset-value} value, then it will not be serialized.
When defining a ``maybe type'', the corresponding serializer for the
regular type will be used by default. For example, a field of type
@code{maybe-string} will be serialized using the @code{serialize-string}
procedure by default, you can of course change this by specifying a
custom serializer procedure. Likewise, the type of the value would have
-to be a string, unless it is set to the @code{disabled} symbol.
+to be a string, or left unspecified.
@lisp
(define-maybe string)
(define-configuration baz-configuration
(name
- ;; Nothing will be serialized by default. If set to a string, the
- ;; `serialize-string' procedure will be used to serialize the string.
- (maybe-string 'disabled)
+ ;; If set to a string, the `serialize-string' procedure will be used
+ ;; to serialize the string. Otherwise this field is not serialized.
+ maybe-string
"The name of this module."))
@end lisp
(define-maybe integer
(prefix baz-))
-(define (baz-serialize-interger field-name value)
+(define (baz-serialize-integer field-name value)
@dots{})
@end lisp
There is also the @code{no-serialization} literal, which when set means
that no serializer will be defined for the ``maybe type'', regardless of
-its value is @code{disabled} or not.
+whether its value is set or not.
@code{define-maybe/no-serialization} is a shorthand for specifying the
@code{no-serialization} literal.
(define-configuration/no-serialization test-configuration
(mode
- (maybe-symbol 'disabled)
+ maybe-symbol
"Docstring."))
@end lisp
@end deffn
+@deffn (Scheme Procedure) maybe-value-set? @var{value}
+Predicate to check whether a user explicitly specified the value of a
+maybe field.
+@end deffn
+
@deffn {Scheme Procedure} serialize-configuration @var{configuration} @
@var{fields}
Return a G-expression that contains the values corresponding to the
disk by using something like @code{mixed-text-file}.
@end deffn
-@deffn {Scheme Procedure} validate-configuration @var{configuration}
-@var{fields}
-Type-check @var{fields}, a list of field names of @var{configuration}, a
-configuration record created by @code{define-configuration}.
-@end deffn
-
@deffn {Scheme Procedure} empty-serializer @var{field-name} @var{value}
A serializer that just returns an empty string. The
@code{serialize-package} procedure is an alias for this.
"The name of the contact."
serialize-contact-name)
(phone-number
- (maybe-integer 'disabled)
+ maybe-integer
"The person's phone number.")
(email
- (maybe-string 'disabled)
+ maybe-string
"The person's email address.")
(married?
(boolean)
usually installed system-wide, but with GNU Guix most software packages
can be installed on a per-user basis without needing root privileges,
and are thus considered part of the user’s @dfn{home environment}.
-Packages on their own not very useful in many cases, because often they
+Packages on their own are not very useful in many cases, because often they
require some additional configuration, usually config files that reside
in @env{XDG_CONFIG_HOME} (@file{~/.config} by default) or other
directories. Everything else can be considered state, like media files,
mechanism and some Scheme code that glues things together gives the user
the freedom to declare their own, very custom, home environments.
+@cindex container, for @command{guix home}
+Once the configuration looks good, you can first test it in a throw-away
+``container'':
+
+@example
+guix home container config.scm
+@end example
+
+The command above spawns a shell where your home environment is running.
+The shell runs in a container, meaning it's isolated from the rest of
+the system, so it's a good way to try out your configuration---you can
+see if configuration bits are missing or misbehaving, if daemons get
+started, and so on. Once you exit that shell, you're back to the prompt
+of your original shell ``in the real world''.
+
Once you have a configuration file that suits your needs, you can
reconfigure your home by running:
doesn't exist.
To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or
-@code{source ~/profile} to the startup file for the login shell. In
+@code{source ~/.profile} to the startup file for the login shell. In
case of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is
@file{~/.zprofile}.
@quotation Note
-This step is only required if your shell is NOT managed by Guix Home.
+This step is only required if your shell is @emph{not} managed by Guix Home.
Otherwise, everything will be done automatically.
@end quotation
@menu
* Essential Home Services:: Environment variables, packages, on-* scripts.
-* Shells: Shells Home Services. POSIX shells, Bash, Zsh.
-* Mcron: Mcron Home Service. Scheduled User's Job Execution.
-* Shepherd: Shepherd Home Service. Managing User's Daemons.
-* Desktop: Desktop Home Services. Services for graphical environments.
+* Shells: Shells Home Services. POSIX shells, Bash, Zsh.
+* Mcron: Mcron Home Service. Scheduled User's Job Execution.
+* Power Management: Power Management Home Services. Services for battery power.
+* Shepherd: Shepherd Home Service. Managing User's Daemons.
+* SSH: Secure Shell. Setting up the secure shell client.
+* Desktop: Desktop Home Services. Services for graphical environments.
+* Guix: Guix Home Services. Services for Guix.
@end menu
@c In addition to that Home Services can provide
("ENV_VAR2" . "value2"))
@end lisp
-The easiest way to extend a service type, without defining new service
+The easiest way to extend a service type, without defining a new service
type is to use the @code{simple-service} helper from @code{(gnu
services)}.
@quotation Note
Make sure that module @code{(gnu packages shells)} is imported with
@code{use-modules} or any other way, this namespace contains the
-definition of the @code{zsh} packages, which is used in the example
+definition of the @code{zsh} package, which is used in the example
above.
@end quotation
the required command using the appropriate service type.
@end defvr
+@defvr {Scheme Variable} home-files-service-type
+The service of this type allows to specify a list of files, which will
+go to @file{~/.guix-home/files}, usually this directory contains
+configuration files (to be more precise it contains symlinks to files in
+@file{/gnu/store}), which should be placed in @file{$XDG_CONFIG_DIR} or
+in rare cases in @file{$HOME}. It accepts extension values in the
+following format:
+
+@lisp
+`((".sway/config" ,sway-file-like-object)
+ (".tmux.conf" ,(local-file "./tmux.conf")))
+@end lisp
+
+Each nested list contains two values: a subdirectory and file-like
+object. After building a home environment @file{~/.guix-home/files}
+will be populated with apropiate content and all nested directories will
+be created accordingly, however, those files won't go any further until
+some other service will do it. By default a
+@code{home-symlink-manager-service-type}, which creates necessary
+symlinks in home folder to files from @file{~/.guix-home/files} and
+backs up already existing, but clashing configs and other things, is a
+part of essential home services (enabled by default), but it's possible
+to use alternative services to implement more advanced use cases like
+read-only home. Feel free to experiment and share your results.
+@end defvr
+
+@defvr {Scheme Variable} home-xdg-configuration-files-service-type
+The service is very similiar to @code{home-files-service-type} (and
+actually extends it), but used for defining files, which will go to
+@file{~/.guix-home/files/.config}, which will be symlinked to
+@file{$XDG_CONFIG_DIR} by @code{home-symlink-manager-service-type} (for
+example) during activation. It accepts extension values in the
+following format:
+
+@lisp
+`(("sway/config" ,sway-file-like-object)
+ ;; -> ~/.guix-home/files/.config/sway/config
+ ;; -> $XDG_CONFIG_DIR/sway/config (by symlink-manager)
+ ("tmux/tmux.conf" ,(local-file "./tmux.conf")))
+@end lisp
+@end defvr
+
@defvr {Scheme Variable} home-activation-service-type
The service of this type generates a guile script, which runs on every
@command{guix home reconfigure} invocation or any other action, which
leads to the activation of the home environment.
@end defvr
+@defvr {Scheme Variable} home-symlink-manager-service-type
+The service of this type generates a guile script, which will be
+executed during activation of home environment, and do a few following
+steps:
+
+@enumerate
+@item
+Reads the content of @file{files/} directory of current and pending home
+environments.
+
+@item
+Cleans up all symlinks created by symlink-manager on previous
+activation. Also, sub-directories, which become empty also will be
+cleaned up.
+
+@item
+Creates new symlinks the following way: It looks @file{files/} directory
+(usually defined with @code{home-files-service-type},
+@code{home-xdg-configuration-files-service-type} and maybe some others),
+takes the files from @file{files/.config/} subdirectory and put
+respective links in @env{XDG_CONFIG_DIR}. For example symlink for
+@file{files/.config/sway/config} will end up in
+@file{$XDG_CONFIG_DIR/sway/config}. The rest files in @file{files/}
+outside of @file{files/.config/} subdirectory will be treated slightly
+different: symlink will just go to @file{$HOME}.
+@file{files/.some-program/config} will end up in
+@file{$HOME/.some-program/config}.
+
+@item
+If some sub-directories are missing, they will be created.
+
+@item
+If there is a clashing files on the way, they will be backed up.
+
+@end enumerate
+
+symlink-manager is a part of essential home services and is enabled and
+used by default.
+@end defvr
+
+
@node Shells Home Services
@subsection Shells
@item @code{guix-defaults?} (default: @code{#t}) (type: boolean)
Add sane defaults like reading @file{/etc/bashrc} and coloring the output of
-@command{ls} to the end of the @file{.bashrc} file.
+@command{ls} to the top of the @file{.bashrc} file.
@item @code{environment-variables} (default: @code{()}) (type: alist)
Association list of environment variables to set for the Bash session. The
Association list of aliases to set for the Bash session. The aliases
will be defined after the contents of the @code{bashrc} field has been
put in the @file{.bashrc} file. The alias will automatically be quoted,
-so something line this:
+so something like this:
@lisp
-'((\"ls\" . \"ls -alF\"))
+'(("ls" . "ls -alF"))
@end lisp
turns into
@example
-alias ls=\"ls -alF\"
+alias ls="ls -alF"
@end example
@item @code{bash-profile} (default: @code{()}) (type: text-config)
@end deftp
You can extend the Bash service by using the @code{home-bash-extension}
-configuration record, whose fields most mirror that of
+configuration record, whose fields must mirror that of
@code{home-bash-configuration} (@pxref{home-bash-configuration}). The
contents of the extensions will be added to the end of the corresponding
Bash configuration files (@pxref{Bash Startup Files,,, bash, The GNU
Bash Reference Manual}.
+For example, here is how you would define a service that extends the
+Bash service such that @file{~/.bash_profile} defines an additional
+environment variable, @env{PS1}:
+
+@lisp
+(define bash-fancy-prompt-service
+ (simple-service 'bash-fancy-prompt
+ home-bash-service-type
+ (home-bash-extension
+ (environment-variables
+ '(("PS1" . "\\u \\wλ "))))))
+@end lisp
+
+You would then add @code{bash-fancy-prompt-service} to the list in the
+@code{services} field of your @code{home-environment}. The reference of
+@code{home-bash-extension} follows.
+
@deftp {Data Type} home-bash-extension
Available @code{home-bash-extension} fields are:
mcron, GNU@tie{}mcron}). The information about system's mcron is
applicable here (@pxref{Scheduled Job Execution}), the only difference
for home services is that they have to be declared in a
-@code{home-envirnoment} record instead of an @code{operating-system}
+@code{home-environment} record instead of an @code{operating-system}
record.
@defvr {Scheme Variable} home-mcron-service-type
@end table
@end deftp
+@node Power Management Home Services
+@subsection Power Management Home Services
+
+@cindex power management
+The @code{(gnu home services pm)} module provides home services
+pertaining to battery power.
+
+@defvr {Scheme Variable} home-batsignal-service-type
+Service for @code{batsignal}, a program that monitors battery levels
+and warns the user through desktop notifications when their battery
+is getting low. You can also configure a command to be run when the
+battery level passes a point deemed ``dangerous''. This service is
+configured with the @code{home-batsignal-configuration} record.
+@end defvr
+
+@deftp {Data Type} home-batsignal-configuration
+Data type representing the configuration for batsignal.
+
+@table @asis
+@item @code{warning-level} (default: @code{15})
+The battery level to send a warning message at.
+
+@item @code{warning-message} (default: @code{#f})
+The message to send as a notification when the battery level reaches
+the @code{warning-level}. Setting to @code{#f} uses the default
+message.
+
+@item @code{critical-level} (default: @code{5})
+The battery level to send a critical message at.
+
+@item @code{critical-message} (default: @code{#f})
+The message to send as a notification when the battery level reaches
+the @code{critical-level}. Setting to @code{#f} uses the default
+message.
+
+@item @code{danger-level} (default: @code{2})
+The battery level to run the @code{danger-command} at.
+
+@item @code{danger-command} (default: @code{#f})
+The command to run when the battery level reaches the @code{danger-level}.
+Setting to @code{#f} disables running the command entirely.
+
+@item @code{full-level} (default: @code{#f})
+The battery level to send a full message at. Setting to @code{#f}
+disables sending the full message entirely.
+
+@item @code{full-message} (default: @code{#f})
+The message to send as a notification when the battery level reaches
+the @code{full-level}. Setting to @code{#f} uses the default message.
+
+@item @code{batteries} (default: @code{'()})
+The batteries to monitor. Setting to @code{'()} tries to find batteries
+automatically.
+
+@item @code{poll-delay} (default: @code{60})
+The time in seconds to wait before checking the batteries again.
+
+@item @code{icon} (default: @code{#f})
+A file-like object to use as the icon for battery notifications. Setting
+to @code{#f} disables notification icons entirely.
+
+@item @code{notifications?} (default: @code{#t})
+Whether to send any notifications.
+
+@item @code{notifications-expire?} (default: @code{#f})
+Whether notifications sent expire after a time.
+
+@item @code{notification-command} (default: @code{#f})
+Command to use to send messages. Setting to @code{#f} sends a notification
+through @code{libnotify}.
+
+@item @code{ignore-missing?} (default: @code{#f})
+Whether to ignore missing battery errors.
+@end table
+@end deftp
+
@node Shepherd Home Service
@subsection Managing User Daemons
@end table
@end deftp
+@node Secure Shell
+@subsection Secure Shell
+
+@cindex secure shell client, configuration
+@cindex SSH client, configuration
+The @uref{https://www.openssh.com, OpenSSH package} includes a client,
+the @command{ssh} command, that allows you to connect to remote machines
+using the @acronym{SSH, secure shell} protocol. With the @code{(gnu
+home services ssh)} module, you can set up OpenSSH so that it works in a
+predictable fashion, almost independently of state on the local machine.
+To do that, you instantiate @code{home-openssh-service-type} in your
+Home configuration, as explained below.
+
+@defvr {Scheme Variable} home-openssh-service-type
+This is the type of the service to set up the OpenSSH client. It takes
+care of several things:
+
+@itemize
+@item
+providing a @file{~/.ssh/config} file based on your configuration so
+that @command{ssh} knows about hosts you regularly connect to and their
+associated parameters;
+
+@item
+providing a @file{~/.ssh/authorized_keys}, which lists public keys that
+the local SSH server, @command{sshd}, may accept to connect to this user
+account;
+
+@item
+optionally providing a @file{~/.ssh/known_hosts} file so that @file{ssh}
+can authenticate hosts you connect to.
+@end itemize
+
+Here is an example of a service and its configuration that you could add
+to the @code{services} field of your @code{home-environment}:
+
+@lisp
+(service home-openssh-service-type
+ (home-openssh-configuration
+ (hosts
+ (list (openssh-host (name "ci.guix.gnu.org")
+ (user "charlie"))
+ (openssh-host (name "chbouib")
+ (host-name "chbouib.example.org")
+ (user "supercharlie")
+ (port 10022))))
+ (authorized-keys (list (local-file "alice.pub")))))
+@end lisp
+
+The example above lists two hosts and their parameters. For instance,
+running @command{ssh chbouib} will automatically connect to
+@code{chbouib.example.org} on port 10022, logging in as user
+@samp{supercharlie}. Further, it marks the public key in
+@file{alice.pub} as authorized for incoming connections.
+
+The value associated with a @code{home-openssh-service-type} instance
+must be a @code{home-openssh-configuration} record, as describe below.
+@end defvr
+
+@deftp {Data Type} home-openssh-configuration
+This is the datatype representing the OpenSSH client and server
+configuration in one's home environment. It contains the following
+fields:
+
+@table @asis
+@item @code{hosts} (default: @code{'()})
+A list of @code{openssh-host} records specifying host names and
+associated connection parameters (see below). This host list goes into
+@file{~/.ssh/config}, which @command{ssh} reads at startup.
+
+@item @code{known-hosts} (default: @code{*unspecified*})
+This must be either:
+
+@itemize
+@item
+@code{*unspecified*}, in which case @code{home-openssh-service-type}
+leaves it up to @command{ssh} and to the user to maintain the list of
+known hosts at @file{~/.ssh/known_hosts}, or
+
+@item
+a list of file-like objects, in which case those are concatenated and
+emitted as @file{~/.ssh/known_hosts}.
+@end itemize
+
+The @file{~/.ssh/known_hosts} contains a list of host name/host key
+pairs that allow @command{ssh} to authenticate hosts you connect to and
+to detect possible impersonation attacks. By default, @command{ssh}
+updates it in a @dfn{TOFU, trust-on-first-use} fashion, meaning that it
+records the host's key in that file the first time you connect to it.
+This behavior is preserved when @code{known-hosts} is set to
+@code{*unspecified*}.
+
+If you instead provide a list of host keys upfront in the
+@code{known-hosts} field, your configuration becomes self-contained and
+stateless: it can be replicated elsewhere or at another point in time.
+Preparing this list can be relatively tedious though, which is why
+@code{*unspecified*} is kept as a default.
+
+@item @code{authorized-keys} (default: @code{'()})
+This must be a list of file-like objects, each of which containing an
+SSH public key that should be authorized to connect to this machine.
+
+Concretely, these files are concatenated and made available as
+@file{~/.ssh/authorized_keys}. If an OpenSSH server, @command{sshd}, is
+running on this machine, then it @emph{may} take this file into account:
+this is what @command{sshd} does by default, but be aware that it can
+also be configured to ignore it.
+@end table
+@end deftp
+
+@c %start of fragment
+
+@deftp {Data Type} openssh-host
+Available @code{openssh-host} fields are:
+
+@table @asis
+@item @code{name} (type: string)
+Name of this host declaration.
+
+@item @code{host-name} (type: maybe-string)
+Host name---e.g., @code{"foo.example.org"} or @code{"192.168.1.2"}.
+
+@item @code{address-family} (type: address-family)
+Address family to use when connecting to this host: one of
+@code{AF_INET} (for IPv4 only), @code{AF_INET6} (for IPv6 only), or
+@code{*unspecified*} (allowing any address family).
+
+@item @code{identity-file} (type: maybe-string)
+The identity file to use---e.g., @code{"/home/charlie/.ssh/id_ed25519"}.
+
+@item @code{port} (type: maybe-natural-number)
+TCP port number to connect to.
+
+@item @code{user} (type: maybe-string)
+User name on the remote host.
+
+@item @code{forward-x11?} (default: @code{#f}) (type: boolean)
+Whether to forward remote client connections to the local X11 graphical
+display.
+
+@item @code{forward-x11-trusted?} (default: @code{#f}) (type: boolean)
+Whether remote X11 clients have full access to the original X11
+graphical display.
+
+@item @code{forward-agent?} (default: @code{#f}) (type: boolean)
+Whether the authentication agent (if any) is forwarded to the remote
+machine.
+
+@item @code{compression?} (default: @code{#f}) (type: boolean)
+Whether to compress data in transit.
+
+@item @code{proxy-command} (type: maybe-string)
+The command to use to connect to the server. As an example, a command
+to connect via an HTTP proxy at 192.0.2.0 would be: @code{"nc -X connect
+-x 192.0.2.0:8080 %h %p"}.
+
+@item @code{host-key-algorithms} (type: maybe-string-list)
+The list of accepted host key algorithms---e.g.,
+@code{'("ssh-ed25519")}.
+
+@item @code{accepted-key-types} (type: maybe-string-list)
+The list of accepted user public key types.
+
+@item @code{extra-content} (default: @code{""}) (type: raw-configuration-string)
+Extra content appended as-is to this @code{Host} block in
+@file{~/.ssh/config}.
+
+@end table
+
+@end deftp
+
+
+@c %end of fragment
+
+
@node Desktop Home Services
@subsection Desktop Home Services
@item @code{nighttime-temperature} (default: @code{4500}) (type: integer)
Nighttime color temperature (kelvins).
-@item @code{daytime-brightness} (default: @code{disabled}) (type: maybe-inexact-number)
-Daytime screen brightness, between 0.1 and 1.0.
+@item @code{daytime-brightness} (type: maybe-inexact-number)
+Daytime screen brightness, between 0.1 and 1.0, or left unspecified.
-@item @code{nighttime-brightness} (default: @code{disabled}) (type: maybe-inexact-number)
-Nighttime screen brightness, between 0.1 and 1.0.
+@item @code{nighttime-brightness} (type: maybe-inexact-number)
+Nighttime screen brightness, between 0.1 and 1.0, or left unspecified.
-@item @code{latitude} (default: @code{disabled}) (type: maybe-inexact-number)
+@item @code{latitude} (type: maybe-inexact-number)
Latitude, when @code{location-provider} is @code{'manual}.
-@item @code{longitude} (default: @code{disabled}) (type: maybe-inexact-number)
+@item @code{longitude} (type: maybe-inexact-number)
Longitude, when @code{location-provider} is @code{'manual}.
-@item @code{dawn-time} (default: @code{disabled}) (type: maybe-string)
+@item @code{dawn-time} (type: maybe-string)
Custom time for the transition from night to day in the
morning---@code{"HH:MM"} format. When specified, solar elevation is not
used to determine the daytime/nighttime period.
-@item @code{dusk-time} (default: @code{disabled}) (type: maybe-string)
+@item @code{dusk-time} (type: maybe-string)
Likewise, custom time for the transition from day to night in the
evening.
@end deftp
+@defvr {Scheme Variable} home-dbus-service-type
+This is the service type for running a session-specific D-Bus, for
+unprivileged applications that require D-Bus to be running.
+@end defvr
+
+@deftp {Data Type} home-dbus-configuration
+The configuration record for @code{home-dbus-service-type}.
+
+@table @asis
+@item @code{dbus} (default: @code{dbus})
+The package providing the @code{/bin/dbus-daemon} command.
+@end table
+@end deftp
+
+@node Guix Home Services
+@subsection Guix Home Services
+
+The @code{(gnu home services guix)} module provides services for
+user-specific Guix configuration.
+
+@defvr {Scheme Variable} home-channels-service-type
+This is the service type for managing
+@file{$XDG_CONFIG_HOME/guix/channels.scm}, the file that controls the
+channels received on @command{guix pull} (@pxref{Channels}). Its
+associated value is a list of @code{channel} records, defined in the
+@code{(guix channels)} module.
+
+Generally, it is better to extend this service than to directly
+configure it, as its default value is the default guix channel(s)
+defined by @code{%default-channels}. If you configure this service
+directly, be sure to include a guix channel. @xref{Specifying
+Additional Channels} and @ref{Using a Custom Guix Channel} for more
+details.
+
+A typical extension for adding a channel might look like this:
+
+@lisp
+(simple-service 'variant-packages-service
+ home-channels-service-type
+ (list
+ (channel
+ (name 'variant-packages)
+ (url "https://example.org/variant-packages.git")))
+@end lisp
+@end defvr
@node Invoking guix home
-@section Invoking @code{guix home}
+@section Invoking @command{guix home}
+
+@cindex @command{guix home}
Once you have written a home environment declaration (@pxref{Declaring
the Home Environment,,,,}, it can be @dfn{instantiated} using the
@code{recutils} format, which makes it easy to filter the output
(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
+@cindex container, for @command{guix home}
+@item container
+Spawn a shell in an isolated environment---a
+@dfn{container}---containing your home as specified by @var{file}.
+
+For example, this is how you would start an interactive shell in a
+container with your home:
+
+@example
+guix home container config.scm
+@end example
+
+This is a throw-away container where you can lightheartedly fiddle with
+files; any changes made within the container, any process started---all
+this disappears as soon as you exit that shell.
+
+As with @command{guix shell}, several options control that container:
+
+@table @option
+@item --network
+@itemx -N
+Enable networking within the container (it is disabled by default).
+
+@item --expose=@var{source}[=@var{target}]
+@itemx --share=@var{source}[=@var{target}]
+As with @command{guix shell}, make directory @var{source} of the host
+system available as @var{target} inside the container---read-only if you
+pass @option{--expose}, and writable if you pass @option{--share}
+(@pxref{Invoking guix shell, @option{--expose} and @option{--share}}).
+@end table
+
+Additionally, you can run a command in that container, instead of
+spawning an interactive shell. For instance, here is how you would
+check which Shepherd services are started in a throw-away home
+container:
+
+@example
+guix home container config.scm -- herd status
+@end example
+
+The command to run in the container must come after @code{--} (double
+hyphen).
+
+@cindex service type definition, editing
+@cindex editing, service type definition
+@item edit
+Edit or view the definition of the given Home service types.
+
+For example, the command below opens your editor, as specified by the
+@env{EDITOR} environment variable, on the definition of the
+@code{home-mcron} service type:
+
+@example
+guix home edit home-mcron
+@end example
+
@item reconfigure
Build the home environment described in @var{file}, and switch to it.
Switching means that the activation script will be evaluated and (in
Describe the current home generation: its file name, as well as
provenance information when available.
+To show installed packages in the current home generation's profile, the
+@code{--list-installed} flag is provided, with the same syntax that is
+used in @command{guix package --list-installed} (@pxref{Invoking guix
+package}). For instance, the following command shows a table of all the
+packages with ``emacs'' in their name that are installed in the current
+home generation's profile:
+
+@example
+guix home describe --list-installed=emacs
+@end example
+
@item list-generations
List a summary of each generation of the home environment available on
disk, in a human-readable way. This is similar to the
generations that are up to 10 days old:
@example
-$ guix home list-generations 10d
+guix home list-generations 10d
@end example
+The @code{--list-installed} flag may also be specified, with the same
+syntax that is used in @command{guix home describe}. This may be
+helpful if trying to determine when a package was added to the home
+profile.
+
@item import
Generate a @dfn{home environment} from the packages in the default
profile and configuration files found in the user's home directory. The
$ guix home import ~/guix-config
guix home: '/home/alice/guix-config' populated with all the Home configuration files
@end example
+@end table
+
+And there's more! @command{guix home} also provides the following
+sub-commands to visualize how the services of your home environment
+relate to one another:
+
+@table @code
+@cindex service extension graph, of a home environment
+@item extension-graph
+Emit to standard output the @dfn{service extension graph} of the home
+environment defined in @var{file} (@pxref{Service Composition}, for more
+information on service extensions). By default the output is in
+Dot/Graphviz format, but you can choose a different format with
+@option{--graph-backend}, as with @command{guix graph} (@pxref{Invoking
+guix graph, @option{--backend}}):
+
+The command:
+
+@example
+guix home extension-graph @var{file} | xdot -
+@end example
+shows the extension relations among services.
+
+@cindex Shepherd dependency graph, for a home environment
+@item shepherd-graph
+Emit to standard output the @dfn{dependency graph} of shepherd services
+of the home environment defined in @var{file}. @xref{Shepherd
+Services}, for more information and for an example graph.
+
+Again, the default output format is Dot/Graphviz, but you can pass
+@option{--graph-backend} to select a different one.
@end table
@var{options} can contain any of the common build options (@pxref{Common
bindings to navigate manuals. @xref{Getting Started,,, info, Info: An
Introduction}, for an introduction to Info navigation.
+@node Platforms
+@chapter Platforms
+
+The packages and systems built by Guix are intended, like most computer
+programs, to run on a CPU with a specific instruction set, and under a
+specific operating system. Those programs are often also targeting a
+specific kernel and system library. Those constraints are captured by
+Guix in @code{platform} records.
+
+@menu
+* platform Reference:: Detail of platform declarations.
+* Supported Platforms:: Description of the supported platforms.
+@end menu
+
+@node platform Reference
+@section @code{platform} Reference
+
+The @code{platform} data type describes a @dfn{platform}: an
+@acronym{ISA, instruction set architecture}, combined with an operating
+system and possibly additional system-wide settings such as the
+@acronym{ABI, application binary interface}.
+
+@deftp {Data Type} platform
+This is the data type representing a platform.
+
+@table @asis
+@item @code{target}
+This field specifies the platform's GNU triplet as a string
+(@pxref{Specifying Target Triplets, GNU configuration triplets,,
+autoconf, Autoconf}).
+
+@item @code{system}
+This string is the system type as it is known to Guix and passed,
+for instance, to the @option{--system} option of most commands.
+
+It usually has the form @code{"@var{cpu}-@var{kernel}"}, where
+@var{cpu} is the target CPU and @var{kernel} the target operating
+system kernel.
+
+It can be for instance @code{"aarch64-linux"} or @code{"armhf-linux"}.
+You will encounter system types when you perform native builds
+(@pxref{Native Builds}).
+
+@item @code{linux-architecture} (default: @code{#false})
+This optional string field is only relevant if the kernel is Linux. In
+that case, it corresponds to the ARCH variable used when building Linux,
+@code{"mips"} for instance.
+
+@item @code{glibc-dynamic-linker}
+This field is the name of the GNU C Library dynamic linker for the
+corresponding system, as a string. It can be
+@code{"/lib/ld-linux-armhf.so.3"}.
+
+@end table
+@end deftp
+
+@node Supported Platforms
+@section Supported Platforms
+
+The @code{(guix platforms @dots{})} modules export the following
+variables, each of which is bound to a @code{platform} record.
+
+@defvr {Scheme Variable} armv7-linux
+Platform targeting ARM v7 CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} aarch64-linux
+Platform targeting ARM v8 CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} mips64-linux
+Platform targeting MIPS little-endian 64-bit CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} powerpc-linux
+Platform targeting PowerPC big-endian 32-bit CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} powerpc64le-linux
+Platform targeting PowerPC little-endian 64-bit CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} riscv64-linux
+Platform targeting RISC-V 64-bit CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} i686-linux
+Platform targeting x86 CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} x86_64-linux
+Platform targeting x86 64-bit CPU running GNU/Linux.
+@end defvr
+
+@defvr {Scheme Variable} i686-mingw
+Platform targeting x86 CPU running Windows, with run-time support from
+MinGW.
+@end defvr
+
+@defvr {Scheme Variable} x86_64-mingw
+Platform targeting x86 64-bit CPU running Windows, with run-time support
+from MinGW.
+@end defvr
+
+@defvr {Scheme Variable} i586-gnu
+Platform targeting x86 CPU running GNU/Hurd (also referred to as
+``GNU'').
+@end defvr
+
+@node System Images
+@chapter Creating System Images
+
+@cindex system images
+When it comes to installing Guix System for the first time on a new
+machine, you can basically proceed in three different ways. The first
+one is to use an existing operating system on the machine to run the
+@command{guix system init} command (@pxref{Invoking guix system}). The
+second one, is to produce an installation image (@pxref{Building the
+Installation Image}). This is a bootable system which role is to
+eventually run @command{guix system init}. Finally, the third option
+would be to produce an image that is a direct instantiation of the
+system you wish to run. That image can then be copied on a bootable
+device such as an USB drive or a memory card. The target machine would
+then directly boot from it, without any kind of installation procedure.
+
+The @command{guix system image} command is able to turn an operating
+system definition into a bootable image. This command supports
+different image types, such as @code{efi-raw}, @code{iso9660} and
+@code{docker}. Any modern @code{x86_64} machine will probably be able
+to boot from an @code{iso9660} image. However, there are a few machines
+out there that require specific image types. Those machines, in general
+using @code{ARM} processors, may expect specific partitions at specific
+offsets.
+
+This chapter explains how to define customized system images and how to
+turn them into actual bootable images.
+
+@menu
+* image Reference:: Detail of image declarations.
+* Instantiate an Image:: How to instantiate an image record.
+* image-type Reference:: Detail of image types declaration.
+* Image Modules:: Definition of image modules.
+@end menu
+
+@node image Reference
+@section @code{image} Reference
+
+The @code{image} record, described right after, allows you to define a
+customized bootable system image.
+
+@deftp {Data Type} image
+This is the data type representing a system image.
+
+@table @asis
+@item @code{name} (default: @code{#false})
+The image name as a symbol, @code{'my-iso9660} for instance. The name
+is optional and it defaults to @code{#false}.
+
+@item @code{format}
+The image format as a symbol. The following formats are supported:
+
+@itemize
+@item @code{disk-image}, a raw disk image composed of one or multiple
+partitions.
+
+@item @code{compressed-qcow2}, a compressed qcow2 image composed of
+one or multiple partitions.
+
+@item @code{docker}, a Docker image.
+
+@item @code{iso9660}, an ISO-9660 image.
+
+@item @code{tarball}, a tar.gz image archive.
+
+@item @code{wsl2}, a WSL2 image.
+
+@end itemize
+
+@item @code{platform} (default: @code{#false})
+The @code{platform} record the image is targeting (@pxref{Platforms}),
+@code{aarch64-linux} for instance. By default, this field is set to
+@code{#false} and the image will target the host platform.
+
+@item @code{size} (default: @code{'guess})
+The image size in bytes or @code{'guess}. The @code{'guess} symbol,
+which is the default, means that the image size will be inferred based
+on the image content.
+
+@item @code{operating-system}
+The image's @code{operating-system} record that is instanciated.
+
+@item @code{partition-table-type} (default: @code{'mbr})
+The image partition table type as a symbol. Possible values are
+@code{'mbr} and @code{'gpt}. It default to @code{'mbr}.
+
+@item @code{partitions} (default: @code{'()})
+The image partitions as a list of @code{partition} records
+(@pxref{partition Reference}).
+
+@item @code{compression?} (default: @code{#true})
+Whether the image content should be compressed, as a boolean. It
+defaults to @code{#true} and only applies to @code{'iso9660} image
+formats.
+
+@item @code{volatile-root?} (default: @code{#true})
+Whether the image root partition should be made volatile, as a boolean.
+
+This is achieved by using a RAM backed file system (overlayfs) that is
+mounted on top of the root partition by the initrd. It defaults to
+@code{#true}. When set to @code{#false}, the image root partition is
+mounted as read-write partition by the initrd.
+
+@item @code{shared-store?} (default: @code{#false})
+Whether the image's store should be shared with the host system, as a
+boolean. This can be useful when creating images dedicated to virtual
+machines. When set to @code{#false}, which is the default, the image's
+@code{operating-system} closure is copied to the image. Otherwise, when
+set to @code{#true}, it is assumed that the host store will be made
+available at boot, using a @code{9p} mount for instance.
+
+@item @code{shared-network?} (default: @code{#false})
+Whether to use the host network interfaces within the image, as a
+boolean. This is only used for the @code{'docker} image format. It
+defaults to @code{#false}.
+
+@item @code{substitutable?} (default: @code{#true})
+Whether the image derivation should be substitutable, as a boolean. It
+defaults to @code{true}.
+
+@end table
+@end deftp
+
+@node partition Reference
+@subsection @code{partition} Reference
+
+In @code{image} record may contain some partitions.
+
+@deftp {Data Type} partition
+This is the data type representing an image partition.
+
+@table @asis
+@item @code{size} (default: @code{'guess})
+The partition size in bytes or @code{'guess}. The @code{'guess} symbol,
+which is the default, means that the partition size will be inferred
+based on the partition content.
+
+@item @code{offset} (default: @code{0})
+The partition's start offset in bytes, relative to the image start or
+the previous partition end. It defaults to @code{0} which means that
+there is no offset applied.
+
+@item @code{file-system} (default: @code{"ext4"})
+The partition file system as a string, defaulting to @code{"ext4"}. The
+supported values are @code{"vfat"}, @code{"fat16"}, @code{"fat32"} and
+@code{"ext4"}.
+
+@item @code{file-system-options} (default: @code{'()})
+The partition file system creation options that should be passed to the
+partition creation tool, as a list of strings. This is only supported
+when creating @code{"ext4"} partitions.
+
+See the @code{"extended-options"} man page section of the
+@code{"mke2fs"} tool for a more complete reference.
+
+@item @code{label}
+The partition label as a mandatory string, @code{"my-root"} for
+instance.
+
+@item @code{uuid} (default: @code{#false})
+The partition UUID as an @code{uuid} record (@pxref{File Systems}). By
+default it is @code{#false}, which means that the partition creation
+tool will attribute a random UUID to the partition.
+
+@item @code{flags} (default: @code{'()})
+The partition flags as a list of symbols. Possible values are
+@code{'boot} and @code{'esp}. The @code{'boot} flags should be set if
+you want to boot from this partition. Exactly one partition should have
+this flag set, usually the root one. The @code{'esp} flag identifies a
+UEFI System Partition.
+
+@item @code{initializer} (default: @code{#false})
+The partition initializer procedure as a gexp. This procedure is called
+to populate a partition. If no initializer is passed, the
+@code{initialize-root-partition} procedure from the @code{(gnu build
+image)} module is used.
+
+@end table
+@end deftp
+
+@node Instantiate an Image
+@section Instantiate an Image
+
+Let's say you would like to create an MBR image with three distinct
+partitions:
+
+@itemize
+@item The @acronym{ESP, EFI System Partition}, a partition of
+40@tie{}MiB at offset 1024@tie{}KiB with a vfat file system.
+
+@item an ext4 partition of 50@tie{}MiB data file, and labeled ``data''.
+
+@item an ext4 bootable partition containing the @code{%simple-os}
+operating-system.
+@end itemize
+
+You would then write the following image definition in a
+@code{my-image.scm} file for instance.
+
+@lisp
+(use-modules (gnu)
+ (gnu image)
+ (gnu tests)
+ (gnu system image)
+ (guix gexp))
+
+(define MiB (expt 2 20))
+
+(image
+ (format 'disk-image)
+ (operating-system %simple-os)
+ (partitions
+ (list
+ (partition
+ (size (* 40 MiB))
+ (offset (* 1024 1024))
+ (label "GNU-ESP")
+ (file-system "vfat")
+ (flags '(esp))
+ (initializer (gexp initialize-efi-partition)))
+ (partition
+ (size (* 50 MiB))
+ (label "DATA")
+ (file-system "ext4")
+ (initializer #~(lambda* (root . rest)
+ (mkdir root)
+ (call-with-output-file
+ (string-append root "/data")
+ (lambda (port)
+ (format port "my-data"))))))
+ (partition
+ (size 'guess)
+ (label root-label)
+ (file-system "ext4")
+ (flags '(boot))
+ (initializer (gexp initialize-root-partition))))))
+@end lisp
+
+Note that the first and third partitions use generic initializers
+procedures, initialize-efi-partition and initialize-root-partition
+respectively. The initialize-efi-partition installs a GRUB EFI loader
+that is loading the GRUB bootloader located in the root partition. The
+initialize-root-partition instantiates a complete system as defined by
+the @code{%simple-os} operating-system.
+
+You can now run:
+
+@example
+guix system image my-image.scm
+@end example
+
+to instantiate the @code{image} definition. That produces a disk image
+which has the expected structure:
+
+@example
+$ parted $(guix system image my-image.scm) print
+@dots{}
+Model: (file)
+Disk /gnu/store/yhylv1bp5b2ypb97pd3bbhz6jk5nbhxw-disk-image: 1714MB
+Sector size (logical/physical): 512B/512B
+Partition Table: msdos
+Disk Flags:
+
+Number Start End Size Type File system Flags
+ 1 1049kB 43.0MB 41.9MB primary fat16 esp
+ 2 43.0MB 95.4MB 52.4MB primary ext4
+ 3 95.4MB 1714MB 1619MB primary ext4 boot
+@end example
+
+The size of the @code{boot} partition has been inferred to @code{1619MB}
+so that it is large enough to host the @code{%simple-os}
+operating-system.
+
+You can also use existing @code{image} record definitions and inherit
+from them to simplify the @code{image} definition. The @code{(gnu
+system image)} module provides the following @code{image} definition
+variables.
+
+@defvr {Scheme Variable} efi-disk-image
+A MBR disk-image composed of two partitions: a 64 bits ESP partition and
+a ROOT boot partition. This image can be used on most @code{x86_64} and
+@code{i686} machines, supporting BIOS or UEFI booting.
+@end defvr
+
+@defvr {Scheme Variable} efi32-disk-image
+Same as @code{efi-disk-image} but with a 32 bits EFI partition.
+@end defvr
+
+@defvr {Scheme Variable} iso9660-image
+An ISO-9660 image composed of a single bootable partition. This image
+can also be used on most @code{x86_64} and @code{i686} machines.
+@end defvr
+
+@defvr {Scheme Variable} docker-image
+A Docker image that can be used to spawn a Docker container.
+@end defvr
+
+Using the @code{efi-disk-image} we can simplify our previous
+@code{image} declaration this way:
+
+@lisp
+(use-modules (gnu)
+ (gnu image)
+ (gnu tests)
+ (gnu system image)
+ (guix gexp)
+ (ice-9 match))
+
+(define MiB (expt 2 20))
+
+(define data
+ (partition
+ (size (* 50 MiB))
+ (label "DATA")
+ (file-system "ext4")
+ (initializer #~(lambda* (root . rest)
+ (mkdir root)
+ (call-with-output-file
+ (string-append root "/data")
+ (lambda (port)
+ (format port "my-data")))))))
+
+(image
+ (inherit efi-disk-image)
+ (operating-system %simple-os)
+ (partitions
+ (match (image-partitions efi-disk-image)
+ ((esp root)
+ (list esp data root)))))
+@end lisp
+
+This will give the exact same @code{image} instantiation but the
+@code{image} declaration is simpler.
+
+@node image-type Reference
+@section image-type Reference
+
+The @command{guix system image} command can, as we saw above, take a
+file containing an @code{image} declaration as argument and produce an
+actual disk image from it. The same command can also handle a file
+containing an @code{operating-system} declaration as argument. In that
+case, how is the @code{operating-system} turned into an image?
+
+That's where the @code{image-type} record intervenes. This record
+defines how to transform an @code{operating-system} record into an
+@code{image} record.
+
+@deftp {Data Type} image-type
+This is the data type representing an image-type.
+
+@table @asis
+@item @code{name}
+The image-type name as a mandatory symbol, @code{'efi32-raw} for
+instance.
+
+@item @code{constructor}
+The image-type constructor, as a mandatory procedure that takes an
+@code{operating-system} record as argument and returns an @code{image}
+record.
+
+@end table
+@end deftp
+
+There are several @code{image-type} records provided by the @code{(gnu
+system image)} and the @code{(gnu system images @dots{})} modules.
+
+@defvr {Scheme Variable} efi-raw-image-type
+Build an image based on the @code{efi-disk-image} image.
+@end defvr
+
+@defvr {Scheme Variable} efi32-raw-image-type
+Build an image based on the @code{efi32-disk-image} image.
+@end defvr
+
+@defvr {Scheme Variable} qcow2-image-type
+Build an image based on the @code{efi-disk-image} image but with the
+@code{compressed-qcow2} image format.
+@end defvr
+
+@defvr {Scheme Variable} iso-image-type
+Build a compressed image based on the @code{iso9660-image} image.
+@end defvr
+
+@defvr {Scheme Variable} uncompressed-iso-image-type
+Build an image based on the @code{iso9660-image} image but with the
+@code{compression?} field set to @code{#false}.
+@end defvr
+
+@defvr {Scheme Variable} docker-image-type
+Build an image based on the @code{docker-image} image.
+@end defvr
+
+@defvr {Scheme Variable} raw-with-offset-image-type
+Build an MBR image with a single partition starting at a @code{1024KiB}
+offset. This is useful to leave some room to install a bootloader in
+the post-MBR gap.
+@end defvr
+
+@defvr {Scheme Variable} pinebook-pro-image-type
+Build an image that is targeting the Pinebook Pro machine. The MBR
+image contains a single partition starting at a @code{9MiB} offset. The
+@code{u-boot-pinebook-pro-rk3399-bootloader} bootloader will be
+installed in this gap.
+@end defvr
+
+@defvr {Scheme Variable} rock64-image-type
+Build an image that is targeting the Rock64 machine. The MBR image
+contains a single partition starting at a @code{16MiB} offset. The
+@code{u-boot-rock64-rk3328-bootloader} bootloader will be installed in
+this gap.
+@end defvr
+
+@defvr {Scheme Variable} novena-image-type
+Build an image that is targeting the Novena machine. It has the same
+characteristics as @code{raw-with-offset-image-type}.
+@end defvr
+
+@defvr {Scheme Variable} pine64-image-type
+Build an image that is targeting the Pine64 machine. It has the same
+characteristics as @code{raw-with-offset-image-type}.
+@end defvr
+
+@defvr {Scheme Variable} hurd-image-type
+Build an image that is targeting a @code{i386} machine running the Hurd
+kernel. The MBR image contains a single ext2 partitions with specific
+@code{file-system-options} flags.
+@end defvr
+
+@defvr {Scheme Variable} hurd-qcow2-image-type
+Build an image similar to the one built by the @code{hurd-image-type}
+but with the @code{format} set to @code{'compressed-qcow2}.
+@end defvr
+
+@defvr {Scheme Variable} wsl2-image-type
+Build an image for the @acronym{WSL2, Windows Subsystem for Linux 2}.
+It can be imported by running:
+
+@example
+wsl --import Guix ./guix ./wsl2-image.tar.gz
+wsl -d Guix
+@end example
+
+@end defvr
+
+So, if we get back to the @code{guix system image} command taking an
+@code{operating-system} declaration as argument. By default, the
+@code{efi-raw-image-type} is used to turn the provided
+@code{operating-system} into an actual bootable image.
+
+To use a different @code{image-type}, the @code{--image-type} option can
+be used. The @code{--list-image-types} option will list all the
+supported image types. It turns out to be a textual listing of all the
+@code{image-types} variables described just above (@pxref{Invoking guix
+system}).
+
+@node Image Modules
+@section Image Modules
+
+Let's take the example of the Pine64, an ARM based machine. To be able
+to produce an image targeting this board, we need the following
+elements:
+
+@itemize
+@item An @code{operating-system} record containing at least
+an appropriate kernel (@code{linux-libre-arm64-generic}) and bootloader
+@code{u-boot-pine64-lts-bootloader}) for the Pine64.
+
+@item Possibly, an @code{image-type} record providing a way to
+turn an @code{operating-system} record to an @code{image} record
+suitable for the Pine64.
+
+@item An actual @code{image} that can be instantiated with the
+@command{guix system image} command.
+
+@end itemize
+
+The @code{(gnu system images pine64)} module provides all those
+elements: @code{pine64-barebones-os}, @code{pine64-image-type} and
+@code{pine64-barebones-raw-image} respectively.
+
+The module returns the @code{pine64-barebones-raw-image} in order for
+users to be able to run:
+
+@example
+guix system image gnu/system/images/pine64.scm
+@end example
+
+Now, thanks to the @code{pine64-image-type} record declaring the
+@code{'pine64-raw} @code{image-type}, one could also prepare a
+@code{my-pine.scm} file with the following content:
+
+@lisp
+(use-modules (gnu system images pine64))
+(operating-system
+ (inherit pine64-barebones-os)
+ (timezone "Europe/Athens"))
+@end lisp
+
+to customize the @code{pine64-barebones-os}, and run:
+
+@example
+$ guix system image --image-type=pine64-raw my-pine.scm
+@end example
+
+Note that there are other modules in the @code{gnu/system/images}
+directory targeting @code{Novena}, @code{Pine64}, @code{PinebookPro} and
+@code{Rock64} machines.
+
@node Installing Debugging Files
@chapter Installing Debugging Files
guix shell -m manifest.scm -- pdflatex doc.tex
@end example
-@xref{Invoking guix package, @option{--manifest}}, for more on
+@xref{Writing Manifests}, for more on
manifests. In the future, we plan to provide packages for @TeX{} Live
@dfn{collections}---``meta-packages'' such as @code{fontsrecommended},
@code{humanities}, or @code{langarabic} that provide the set of packages
guix import texlive @var{package}
@end example
+Additional options include:
+
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@end table
+
@quotation Note
@TeX{} Live packaging is still very much work in progress, but you can
help! @xref{Contributing}, for more information.
guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
@end example
-For this to work, the @code{glibc-dynamic-linker} procedure in
-@code{(gnu packages bootstrap)} must be augmented to return the right
-file name for libc's dynamic linker on that platform; likewise,
-@code{system->linux-architecture} in @code{(gnu packages linux)} must be
-taught about the new platform.
-
-Once these are built, the @code{(gnu packages bootstrap)} module needs
-to be updated to refer to these binaries on the target platform. That
-is, the hashes and URLs of the bootstrap tarballs for the new platform
-must be added alongside those of the currently supported platforms. The
-bootstrap Guile tarball is treated specially: it is expected to be
-available locally, and @file{gnu/local.mk} has rules to download it for
-the supported architectures; a rule for the new platform must be added
-as well.
+For this to work, it is first required to register a new platform as
+defined in the @code{(guix platform)} module. A platform is making the
+connection between a GNU triplet (@pxref{Specifying Target Triplets, GNU
+configuration triplets,, autoconf, Autoconf}), the equivalent
+@var{system} in Nix notation, the name of the
+@var{glibc-dynamic-linker}, and the corresponding Linux architecture
+name if applicable (@pxref{Platforms}).
+
+Once the bootstrap tarball are built, the @code{(gnu packages
+bootstrap)} module needs to be updated to refer to these binaries on the
+target platform. That is, the hashes and URLs of the bootstrap tarballs
+for the new platform must be added alongside those of the currently
+supported platforms. The bootstrap Guile tarball is treated specially:
+it is expected to be available locally, and @file{gnu/local.mk} has
+rules to download it for the supported architectures; a rule for the new
+platform must be added as well.
In practice, there may be some complications. First, it may be that the
extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
HCoop / jackhill / guix / guix.git / blobdiff