Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
-Copyright @copyright{} 2016, 2017, 2018 Efraim Flashner@*
+Copyright @copyright{} 2016, 2017, 2018, 2019 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
-Copyright @copyright{} 2016, 2017 Nils Gillmann@*
-Copyright @copyright{} 2016, 2017, 2018 Jan Nieuwenhuizen@*
+Copyright @copyright{} 2016, 2017 ng0@*
+Copyright @copyright{} 2016, 2017, 2018, 2019 Jan Nieuwenhuizen@*
Copyright @copyright{} 2016 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
+Copyright @copyright{} 2016, 2017, 2018, 2019 Christopher Baines@*
Copyright @copyright{} 2017, 2018 Clément Lassieur@*
Copyright @copyright{} 2017, 2018 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
Copyright @copyright{} 2017, 2018 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
-Copyright @copyright{} 2017, 2018 Arun Isaac@*
+Copyright @copyright{} 2017, 2018, 2019 Arun Isaac@*
Copyright @copyright{} 2017 nee@*
Copyright @copyright{} 2018 Rutger Helling@*
Copyright @copyright{} 2018 Oleg Pykhalov@*
@menu
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
+* System Installation:: Installing the whole operating system.
* Package Management:: Package installation, upgrade, etc.
+* Development:: Guix-aided software development.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
-* GNU Distribution:: Software for your friendly GNU system.
+* System Configuration:: Configuring the operating system.
+* Documentation:: Browsing software user manuals.
+* Installing Debugging Files:: Feeding the debugger.
+* Security Updates:: Deploying security fixes quickly.
+* Bootstrapping:: GNU/Linux built from scratch.
+* Porting:: Targeting another platform or kernel.
* Contributing:: Your help needed!
* Acknowledgments:: Thanks!
@detailmenu
--- The Detailed Node Listing ---
+Introduction
+
+* Managing Software the Guix Way:: What's special.
+* GNU Distribution:: The packages and tools.
+
Installation
* Binary Installation:: Getting Guix running in no time!
* Daemon Offload Setup:: Offloading builds to remote machines.
* SELinux Support:: Using an SELinux policy for the daemon.
+System Installation
+
+* Limitations:: What you can expect.
+* Hardware Considerations:: Supported hardware.
+* USB Stick and DVD Installation:: Preparing the installation medium.
+* Preparing for Installation:: Networking, partitioning, etc.
+* Guided Graphical Installation:: Easy graphical installation.
+* Manual Installation:: Manual installation for wizards.
+* After System Installation:: When installation succeeded.
+* Installing Guix in a VM:: Guix System playground.
+* Building the Installation Image:: How this comes to be.
+
+Manual Installation
+
+* Keyboard Layout and Networking and Partitioning:: Initial setup.
+* Proceeding with the Installation:: Installing.
+
Package Management
* Features:: How Guix will make your life brighter.
* Channels:: Customizing the package collection.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
-* Invoking guix pack:: Creating software bundles.
* Invoking guix archive:: Exporting and importing store files.
Substitutes
* Substitution Failure:: What happens when substitution fails.
* On Trusting Binaries:: How can you trust that binary blob?
+Development
+
+* Invoking guix environment:: Setting up development environments.
+* Invoking guix pack:: Creating software bundles.
+
Programming Interface
+* Package Modules:: Packages from the programmer's viewpoint.
* Defining Packages:: Defining new packages.
* Build Systems:: Specifying how packages are built.
* The Store:: Manipulating the package store.
* Invoking guix lint:: Finding errors in package definitions.
* Invoking guix size:: Profiling disk usage.
* Invoking guix graph:: Visualizing the graph of packages.
-* Invoking guix environment:: Setting up development environments.
* Invoking guix publish:: Sharing substitutes.
* Invoking guix challenge:: Challenging substitute servers.
* Invoking guix copy:: Copying to and from a remote store.
* Additional Build Options:: Options specific to 'guix build'.
* Debugging Build Failures:: Real life packaging experience.
-GNU Distribution
-
-* System Installation:: Installing the whole operating system.
-* System Configuration:: Configuring the operating system.
-* Documentation:: Browsing software user manuals.
-* Installing Debugging Files:: Feeding the debugger.
-* Security Updates:: Deploying security fixes quickly.
-* Package Modules:: Packages from the programmer's viewpoint.
-* Packaging Guidelines:: Growing the distribution.
-* Bootstrapping:: GNU/Linux built from scratch.
-* Porting:: Targeting another platform or kernel.
-
-System Installation
-
-* Limitations:: What you can expect.
-* Hardware Considerations:: Supported hardware.
-* USB Stick and DVD Installation:: Preparing the installation medium.
-* Preparing for Installation:: Networking, partitioning, etc.
-* Proceeding with the Installation:: The real thing.
-* Installing GuixSD in a VM:: GuixSD playground.
-* Building the Installation Image:: How this comes to be.
-
System Configuration
* Using the Configuration System:: Customizing your GNU system.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* Bootloader Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
-* Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
+* Running Guix in a VM:: How to run Guix System in a virtual machine.
* Defining Services:: Adding new service definitions.
Services
* Service Reference:: API reference.
* Shepherd Services:: A particular type of service.
-Packaging Guidelines
-
-* Software Freedom:: What may go into the distribution.
-* Package Naming:: What's in a name?
-* Version Numbers:: When the name is not enough.
-* Synopses and Descriptions:: Helping users find the right package.
-* Python Modules:: A touch of British comedy.
-* Perl Modules:: Little pearls.
-* Java Packages:: Coffee break.
-* Fonts:: Fond of fonts.
-
-Contributing
-
-* Building from Git:: The latest and greatest.
-* Running Guix Before It Is Installed:: Hacker tricks.
-* The Perfect Setup:: The right tools.
-* Coding Style:: Hygiene of the contributor.
-* Submitting Patches:: Share your work.
-
-Coding Style
-
-* Programming Paradigm:: How to compose your elements.
-* Modules:: Where to store your code?
-* Data Types and Pattern Matching:: Implementing data structures.
-* Formatting Code:: Writing conventions.
-
@end detailmenu
@end menu
@cindex purpose
GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
using the international phonetic alphabet (IPA).} is a package
-management tool for the GNU system. Guix makes it easy for unprivileged
-users to install, upgrade, or remove packages, to roll back to a
+management tool for and distribution of the GNU system.
+Guix makes it easy for unprivileged
+users to install, upgrade, or remove software packages, to roll back to a
previous package set, to build packages from source, and generally
assists with the creation and maintenance of software environments.
+@cindex Guix System
+@cindex GuixSD, now Guix System
+@cindex Guix System Distribution, now Guix System
+You can install GNU@tie{}Guix on top of an existing GNU/Linux system where it
+complements the available tools without interference (@pxref{Installation}),
+or you can use it as a standalone operating system distribution,
+@dfn{Guix@tie{}System}@footnote{We used to refer to Guix System as ``Guix
+System Distribution'' or ``GuixSD''. We now consider it makes more sense to
+group everything under the ``Guix'' banner since, after all, Guix System is
+readily available through the @command{guix system} command, even if you're
+using a different distro underneath!}. @xref{GNU Distribution}.
+
+@menu
+* Managing Software the Guix Way:: What's special.
+* GNU Distribution:: The packages and tools.
+@end menu
+
+@node Managing Software the Guix Way
+@section Managing Software the Guix Way
+
@cindex user interfaces
Guix provides a command-line package management interface
-(@pxref{Invoking guix package}), a set of command-line utilities
+(@pxref{Package Management}), tools to help with software development
+(@pxref{Development}), command-line utilities for more advanced usage,
(@pxref{Utilities}), as well as Scheme programming interfaces
(@pxref{Programming Interface}).
@cindex build daemon
definitions from existing ones, including from the command line
(@pxref{Package Transformation Options}).
-@cindex Guix System Distribution
-@cindex GuixSD
-You can install GNU@tie{}Guix on top of an existing GNU/Linux system
-where it complements the available tools without interference
-(@pxref{Installation}), or you can use it as part of the standalone
-@dfn{Guix System Distribution} or GuixSD (@pxref{GNU Distribution}).
-With GNU@tie{}GuixSD, you @emph{declare} all aspects of the operating
-system configuration and Guix takes care of instantiating the
-configuration in a transactional, reproducible, and stateless fashion
-(@pxref{System Configuration}).
-
@cindex functional package management
@cindex isolation
Under the hood, Guix implements the @dfn{functional package management}
garbage collection of packages (@pxref{Features}).
+@node GNU Distribution
+@section GNU Distribution
+
+@cindex Guix System
+Guix comes with a distribution of the GNU system consisting entirely of
+free software@footnote{The term ``free'' here refers to the
+@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
+users of that software}.}. The
+distribution can be installed on its own (@pxref{System Installation}),
+but it is also possible to install Guix as a package manager on top of
+an installed GNU/Linux system (@pxref{Installation}). When we need to
+distinguish between the two, we refer to the standalone distribution as
+Guix@tie{}System.
+
+The distribution provides core GNU packages such as GNU libc, GCC, and
+Binutils, as well as many GNU and non-GNU applications. The complete
+list of available packages can be browsed
+@url{http://www.gnu.org/software/guix/packages,on-line} or by
+running @command{guix package} (@pxref{Invoking guix package}):
+
+@example
+guix package --list-available
+@end example
+
+Our goal is to provide a practical 100% free software distribution of
+Linux-based and other variants of GNU, with a focus on the promotion and
+tight integration of GNU components, and an emphasis on programs and
+tools that help users exert that freedom.
+
+Packages are currently available on the following platforms:
+
+@table @code
+
+@item x86_64-linux
+Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
+
+@item i686-linux
+Intel 32-bit architecture (IA32), Linux-Libre kernel;
+
+@item armhf-linux
+ARMv7-A architecture with hard float, Thumb-2 and NEON,
+using the EABI hard-float application binary interface (ABI),
+and Linux-Libre kernel.
+
+@item aarch64-linux
+little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is
+currently in an experimental stage, with limited support.
+@xref{Contributing}, for how to help!
+
+@item mips64el-linux
+little-endian 64-bit MIPS processors, specifically the Loongson series,
+n32 ABI, and Linux-Libre kernel.
+
+@end table
+
+With Guix@tie{}System, you @emph{declare} all aspects of the operating system
+configuration and Guix takes care of instantiating the configuration in a
+transactional, reproducible, and stateless fashion (@pxref{System
+Configuration}). Guix System uses the Linux-libre kernel, the Shepherd
+initialization system (@pxref{Introduction,,, shepherd, The GNU Shepherd
+Manual}), the well-known GNU utilities and tool chain, as well as the
+graphical environment or system services of your choice.
+
+Guix System is available on all the above platforms except
+@code{mips64el-linux}.
+
+@noindent
+For information on porting to other architectures or kernels,
+@pxref{Porting}.
+
+Building this distribution is a cooperative effort, and you are invited
+to join! @xref{Contributing}, for information about how you can help.
+
+
@c *********************************************************************
@node Installation
@chapter Installation
your message.
Guix also comes with a whole-system test suite that tests complete
-GuixSD operating system instances. It can only run on systems where
+Guix System instances. It can only run on systems where
Guix is already installed, using:
@example
Guix includes an SELinux policy file at @file{etc/guix-daemon.cil} that
can be installed on a system where SELinux is enabled, in order to label
Guix files and to specify the expected behavior of the daemon. Since
-GuixSD does not provide an SELinux base policy, the daemon policy cannot
-be used on GuixSD.
+Guix System does not provide an SELinux base policy, the daemon policy cannot
+be used on Guix System.
@subsubsection Installing the SELinux policy
@cindex SELinux, policy installation
@section Application Setup
@cindex foreign distro
-When using Guix on top of GNU/Linux distribution other than GuixSD---a
+When using Guix on top of GNU/Linux distribution other than Guix System---a
so-called @dfn{foreign distro}---a few additional steps are needed to
get everything in place. Here are some of them.
@subsection Locales
@anchor{locales-and-locpath}
-@cindex locales, when not on GuixSD
+@cindex locales, when not on Guix System
@vindex LOCPATH
@vindex GUIX_LOCPATH
Packages installed @i{via} Guix will not use the locale data of the
debugging symbols in the @code{debug} output), Binutils, and a linker
wrapper.
-@cindex attempt to use impure library, error message
-
The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
passed to the linker, add corresponding @code{-rpath} arguments, and
-invoke the actual linker with this new set of arguments. By default,
-the linker wrapper refuses to link to libraries outside the store to
-ensure ``purity''. This can be annoying when using the toolchain to
-link with local libraries. To allow references to libraries outside the
-store you need to define the environment variable
-@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES}.
+invoke the actual linker with this new set of arguments. You can instruct the
+wrapper to refuse to link against libraries not in the store by setting the
+@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}.
@c TODO What else?
@c *********************************************************************
-@node Package Management
-@chapter Package Management
+@node System Installation
+@chapter System Installation
-@cindex packages
-The purpose of GNU Guix is to allow users to easily install, upgrade, and
-remove software packages, without having to know about their build
-procedures or dependencies. Guix also goes beyond this obvious set of
-features.
+@cindex installing Guix System
+@cindex Guix System, installation
+This section explains how to install Guix System
+on a machine. Guix, as a package manager, can
+also be installed on top of a running GNU/Linux system,
+@pxref{Installation}.
-This chapter describes the main features of Guix, as well as the
-package management tools it provides. Along with the command-line
-interface described below (@pxref{Invoking guix package, @code{guix
-package}}), you may also use the Emacs-Guix interface (@pxref{Top,,,
-emacs-guix, The Emacs-Guix Reference Manual}), after installing
-@code{emacs-guix} package (run @kbd{M-x guix-help} command to start
-with it):
+@ifinfo
+@quotation Note
+@c This paragraph is for people reading this from tty2 of the
+@c installation image.
+You are reading this documentation with an Info reader. For details on
+how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
+link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU
+Info}. Hit @kbd{l} afterwards to come back here.
-@example
-guix package -i emacs-guix
-@end example
+Alternately, run @command{info info} in another tty to keep the manual
+available.
+@end quotation
+@end ifinfo
@menu
-* Features:: How Guix will make your life brighter.
-* Invoking guix package:: Package installation, removal, etc.
-* Substitutes:: Downloading pre-built binaries.
-* Packages with Multiple Outputs:: Single source package, multiple outputs.
-* Invoking guix gc:: Running the garbage collector.
-* Invoking guix pull:: Fetching the latest Guix and distribution.
-* Channels:: Customizing the package collection.
-* Inferiors:: Interacting with another revision of Guix.
-* Invoking guix describe:: Display information about your Guix revision.
-* Invoking guix pack:: Creating software bundles.
-* Invoking guix archive:: Exporting and importing store files.
+* Limitations:: What you can expect.
+* Hardware Considerations:: Supported hardware.
+* USB Stick and DVD Installation:: Preparing the installation medium.
+* Preparing for Installation:: Networking, partitioning, etc.
+* Guided Graphical Installation:: Easy graphical installation.
+* Manual Installation:: Manual installation for wizards.
+* After System Installation:: When installation succeeded.
+* Installing Guix in a VM:: Guix System playground.
+* Building the Installation Image:: How this comes to be.
@end menu
-@node Features
-@section Features
+@node Limitations
+@section Limitations
-When using Guix, each package ends up in the @dfn{package store}, in its
-own directory---something that resembles
-@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
+As of version @value{VERSION}, Guix System is
+not production-ready. It may contain bugs and lack important
+features. Thus, if you are looking for a stable production system that
+respects your freedom as a computer user, a good solution at this point
+is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
+the more established GNU/Linux distributions}. We hope you can soon switch
+to the Guix System without fear, of course. In the meantime, you can
+also keep using your distribution and try out the package manager on top
+of it (@pxref{Installation}).
-Instead of referring to these directories, users have their own
-@dfn{profile}, which points to the packages that they actually want to
-use. These profiles are stored within each user's home directory, at
-@code{$HOME/.guix-profile}.
+Before you proceed with the installation, be aware of the following
+noteworthy limitations applicable to version @value{VERSION}:
-For example, @code{alice} installs GCC 4.7.2. As a result,
-@file{/home/alice/.guix-profile/bin/gcc} points to
-@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
-@code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
-simply continues to point to
-@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
-coexist on the same system without any interference.
+@itemize
+@item
+The installation process does not include a graphical user interface and
+requires familiarity with GNU/Linux (see the following subsections to
+get a feel of what that means.)
-The @command{guix package} command is the central tool to manage
-packages (@pxref{Invoking guix package}). It operates on the per-user
-profiles, and can be used @emph{with normal user privileges}.
+@item
+Support for the Logical Volume Manager (LVM) is missing.
-@cindex transactions
-The command provides the obvious install, remove, and upgrade
-operations. Each invocation is actually a @emph{transaction}: either
-the specified operation succeeds, or nothing happens. Thus, if the
-@command{guix package} process is terminated during the transaction,
-or if a power outage occurs during the transaction, then the user's
-profile remains in its previous state, and remains usable.
+@item
+More and more system services are provided (@pxref{Services}), but some
+may be missing.
-In addition, any package transaction may be @emph{rolled back}. So, if,
-for example, an upgrade installs a new version of a package that turns
-out to have a serious bug, users may roll back to the previous instance
-of their profile, which was known to work well. Similarly, the global
-system configuration on GuixSD is subject to
-transactional upgrades and roll-back
-(@pxref{Using the Configuration System}).
+@item
+More than 8,500 packages are available, but you might
+occasionally find that a useful package is missing.
-All packages in the package store may be @emph{garbage-collected}.
-Guix can determine which packages are still referenced by user
-profiles, and remove those that are provably no longer referenced
-(@pxref{Invoking guix gc}). Users may also explicitly remove old
-generations of their profile so that the packages they refer to can be
-collected.
+@item
+GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
+as well as a number of X11 window managers. However, some graphical
+applications may be missing, as well as KDE.
+@end itemize
-@cindex reproducibility
-@cindex reproducible builds
-Guix takes a @dfn{purely functional} approach to package
-management, as described in the introduction (@pxref{Introduction}).
-Each @file{/gnu/store} package directory name contains a hash of all the
-inputs that were used to build that package---compiler, libraries, build
-scripts, etc. This direct correspondence allows users to make sure a
-given package installation matches the current state of their
-distribution. It also helps maximize @dfn{build reproducibility}:
-thanks to the isolated build environments that are used, a given build
-is likely to yield bit-identical files when performed on different
-machines (@pxref{Invoking guix-daemon, container}).
+You have been warned! But more than a disclaimer, this is an invitation
+to report issues (and success stories!), and to join us in improving it.
+@xref{Contributing}, for more info.
-@cindex substitutes
-This foundation allows Guix to support @dfn{transparent binary/source
-deployment}. When a pre-built binary for a @file{/gnu/store} item is
-available from an external source---a @dfn{substitute}, Guix just
-downloads it and unpacks it;
-otherwise, it builds the package from source, locally
-(@pxref{Substitutes}). Because build results are usually bit-for-bit
-reproducible, users do not have to trust servers that provide
-substitutes: they can force a local build and @emph{challenge} providers
-(@pxref{Invoking guix challenge}).
-Control over the build environment is a feature that is also useful for
-developers. The @command{guix environment} command allows developers of
-a package to quickly set up the right development environment for their
-package, without having to manually install the dependencies of the
-package into their profile (@pxref{Invoking guix environment}).
+@node Hardware Considerations
+@section Hardware Considerations
-@cindex replication, of software environments
-@cindex provenance tracking, of software artifacts
-All of Guix and its package definitions is version-controlled, and
-@command{guix pull} allows you to ``travel in time'' on the history of Guix
-itself (@pxref{Invoking guix pull}). This makes it possible to replicate a
-Guix instance on a different machine or at a later point in time, which in
-turn allows you to @emph{replicate complete software environments}, while
-retaining precise @dfn{provenance tracking} of the software.
+@cindex hardware support on Guix System
+GNU@tie{}Guix focuses on respecting the user's computing freedom. It
+builds around the kernel Linux-libre, which means that only hardware for
+which free software drivers and firmware exist is supported. Nowadays,
+a wide range of off-the-shelf hardware is supported on
+GNU/Linux-libre---from keyboards to graphics cards to scanners and
+Ethernet controllers. Unfortunately, there are still areas where
+hardware vendors deny users control over their own computing, and such
+hardware is not supported on Guix System.
-@node Invoking guix package
-@section Invoking @command{guix package}
+@cindex WiFi, hardware support
+One of the main areas where free drivers or firmware are lacking is WiFi
+devices. WiFi devices known to work include those using Atheros chips
+(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
+driver, and those using Broadcom/AirForce chips (BCM43xx with
+Wireless-Core Revision 5), which corresponds to the @code{b43-open}
+Linux-libre driver. Free firmware exists for both and is available
+out-of-the-box on Guix System, as part of @var{%base-firmware}
+(@pxref{operating-system Reference, @code{firmware}}).
-@cindex installing packages
-@cindex removing packages
-@cindex package installation
-@cindex package removal
-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. It operates only on the user's own profile,
-and works with normal user privileges (@pxref{Features}). Its syntax
-is:
+@cindex RYF, Respects Your Freedom
+The @uref{https://www.fsf.org/, Free Software Foundation} runs
+@uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a
+certification program for hardware products that respect your freedom
+and your privacy and ensure that you have control over your device. We
+encourage you to check the list of RYF-certified devices.
-@example
-guix package @var{options}
-@end example
-@cindex transactions
-Primarily, @var{options} specifies the operations to be performed during
-the transaction. Upon completion, a new profile is created, but
-previous @dfn{generations} of the profile remain available, should the user
-want to roll back.
+Another useful resource is the @uref{https://www.h-node.org/, H-Node}
+web site. It contains a catalog of hardware devices with information
+about their support in GNU/Linux.
-For example, to remove @code{lua} and install @code{guile} and
-@code{guile-cairo} in a single transaction:
+
+@node USB Stick and DVD Installation
+@section USB Stick and DVD Installation
+
+An ISO-9660 installation image that can be written to a USB stick or
+burnt to a DVD can be downloaded from
+@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz},
+where @var{system} is one of:
+
+@table @code
+@item x86_64-linux
+for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
+
+@item i686-linux
+for a 32-bit GNU/Linux system on Intel-compatible CPUs.
+@end table
+
+@c start duplication of authentication part from ``Binary Installation''
+Make sure to download the associated @file{.sig} file and to verify the
+authenticity of the image against it, along these lines:
@example
-guix package -r lua -i guile guile-cairo
+$ wget https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig
+$ gpg --verify guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig
@end example
-@command{guix package} also supports a @dfn{declarative approach}
-whereby the user specifies the exact set of packages to be available and
-passes it @i{via} the @option{--manifest} option
-(@pxref{profile-manifest, @option{--manifest}}).
-
-@cindex profile
-For each user, a symlink to the user's default profile is automatically
-created in @file{$HOME/.guix-profile}. This symlink always points to the
-current generation of the user's default profile. Thus, users can add
-@file{$HOME/.guix-profile/bin} to their @code{PATH} environment
-variable, and so on.
-@cindex search paths
-If you are not using the Guix System Distribution, consider adding the
-following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
-Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
-shells get all the right environment variable definitions:
+If that command fails because you do not have the required public key,
+then run this command to import it:
@example
-GUIX_PROFILE="$HOME/.guix-profile" ; \
-source "$HOME/.guix-profile/etc/profile"
+$ gpg --keyserver @value{KEY-SERVER} \
+ --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example
-In a multi-user setup, user profiles are stored in a place registered as
-a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
-to (@pxref{Invoking guix gc}). That directory is normally
-@code{@var{localstatedir}/guix/profiles/per-user/@var{user}}, where
-@var{localstatedir} is the value passed to @code{configure} as
-@code{--localstatedir}, and @var{user} is the user name. The
-@file{per-user} directory is created when @command{guix-daemon} is
-started, and the @var{user} sub-directory is created by @command{guix
-package}.
+@noindent
+and rerun the @code{gpg --verify} command.
+@c end duplication
-The @var{options} can be among the following:
+This image contains the tools necessary for an installation.
+It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
-@table @code
+@unnumberedsubsec Copying to a USB Stick
-@item --install=@var{package} @dots{}
-@itemx -i @var{package} @dots{}
-Install the specified @var{package}s.
+To copy the image to a USB stick, follow these steps:
-Each @var{package} may specify either a simple package name, such as
-@code{guile}, or a package name followed by an at-sign and version number,
-such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter
-case, the newest version prefixed by @code{1.8} is selected.)
+@enumerate
+@item
+Decompress the image using the @command{xz} command:
-If no version number is specified, the
-newest available version will be selected. In addition, @var{package}
-may contain a colon, followed by the name of one of the outputs of the
-package, as in @code{gcc:doc} or @code{binutils@@2.22:lib}
-(@pxref{Packages with Multiple Outputs}). Packages with a corresponding
-name (and optionally version) are searched for among the GNU
-distribution modules (@pxref{Package Modules}).
+@example
+xz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz
+@end example
-@cindex propagated inputs
-Sometimes packages have @dfn{propagated inputs}: these are dependencies
-that automatically get installed along with the required package
-(@pxref{package-propagated-inputs, @code{propagated-inputs} in
-@code{package} objects}, for information about propagated inputs in
-package definitions).
+@item
+Insert a USB stick of 1@tie{}GiB or more into your machine, and determine
+its device name. Assuming that the USB stick is known as @file{/dev/sdX},
+copy the image with:
-@anchor{package-cmd-propagated-inputs}
-An example is the GNU MPC library: its C header files refer to those of
-the GNU MPFR library, which in turn refer to those of the GMP library.
-Thus, when installing MPC, the MPFR and GMP libraries also get installed
-in the profile; removing MPC also removes MPFR and GMP---unless they had
-also been explicitly installed by the user.
+@example
+dd if=guix-system-install-@value{VERSION}.@var{system}.iso of=/dev/sdX
+sync
+@end example
-Besides, packages sometimes rely on the definition of environment
-variables for their search paths (see explanation of
-@code{--search-paths} below). Any missing or possibly incorrect
-environment variable definitions are reported here.
+Access to @file{/dev/sdX} usually requires root privileges.
+@end enumerate
-@item --install-from-expression=@var{exp}
-@itemx -e @var{exp}
-Install the package @var{exp} evaluates to.
+@unnumberedsubsec Burning on a DVD
-@var{exp} must be a Scheme expression that evaluates to a
-@code{<package>} object. This option is notably useful to disambiguate
-between same-named variants of a package, with expressions such as
-@code{(@@ (gnu packages base) guile-final)}.
+To copy the image to a DVD, follow these steps:
-Note that this option installs the first output of the specified
-package, which may be insufficient when needing a specific output of a
-multiple-output package.
+@enumerate
+@item
+Decompress the image using the @command{xz} command:
-@item --install-from-file=@var{file}
-@itemx -f @var{file}
-Install the package that the code within @var{file} evaluates to.
+@example
+xz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz
+@end example
-As an example, @var{file} might contain a definition like this
-(@pxref{Defining Packages}):
+@item
+Insert a blank DVD into your machine, and determine
+its device name. Assuming that the DVD drive is known as @file{/dev/srX},
+copy the image with:
@example
-@verbatiminclude package-hello.scm
+growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.@var{system}.iso
@end example
-Developers may find it useful to include such a @file{guix.scm} file
-in the root of their project source tree that can be used to test
-development snapshots and create reproducible development environments
-(@pxref{Invoking guix environment}).
+Access to @file{/dev/srX} usually requires root privileges.
+@end enumerate
-@item --remove=@var{package} @dots{}
-@itemx -r @var{package} @dots{}
-Remove the specified @var{package}s.
+@unnumberedsubsec Booting
-As for @code{--install}, each @var{package} may specify a version number
-and/or output name in addition to the package name. For instance,
-@code{-r glibc:debug} would remove the @code{debug} output of
-@code{glibc}.
+Once this is done, you should be able to reboot the system and boot from
+the USB stick or DVD. The latter usually requires you to get in the
+BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
-@item --upgrade[=@var{regexp} @dots{}]
-@itemx -u [@var{regexp} @dots{}]
-@cindex upgrading packages
-Upgrade all the installed packages. If one or more @var{regexp}s are
-specified, upgrade only installed packages whose name matches a
-@var{regexp}. Also see the @code{--do-not-upgrade} option below.
+@xref{Installing Guix in a VM}, if, instead, you would like to install
+Guix System in a virtual machine (VM).
-Note that this upgrades package to the latest version of packages found
-in the distribution currently installed. To update your distribution,
-you should regularly run @command{guix pull} (@pxref{Invoking guix
-pull}).
-@item --do-not-upgrade[=@var{regexp} @dots{}]
-When used together with the @code{--upgrade} option, do @emph{not}
-upgrade any packages whose name matches a @var{regexp}. For example, to
-upgrade all packages in the current profile except those containing the
-substring ``emacs'':
+@node Preparing for Installation
+@section Preparing for Installation
+
+Once you have booted, you can use the guided graphical installer, which makes
+it easy to get started (@pxref{Guided Graphical Installation}). Alternately,
+if you are already familiar with GNU/Linux and if you want more control than
+what the graphical installer provides, you can choose the ``manual''
+installation process (@pxref{Manual Installation}).
+
+The graphical installer is available on TTY1. You can obtain root shells on
+TTYs 3 to 6 by hitting @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, etc. TTY2 shows
+this documentation and you can reach it with @kbd{ctrl-alt-f2}. Documentation
+is browsable using the Info reader commands (@pxref{Top,,, info-stnd,
+Stand-alone GNU Info}). The installation system runs the GPM mouse daemon,
+which allows you to select text with the left mouse button and to paste it
+with the middle button.
-@example
-$ guix package --upgrade . --do-not-upgrade emacs
-@end example
+@quotation Note
+Installation requires access to the Internet so that any missing
+dependencies of your system configuration can be downloaded. See the
+``Networking'' section below.
+@end quotation
-@item @anchor{profile-manifest}--manifest=@var{file}
-@itemx -m @var{file}
-@cindex profile declaration
-@cindex profile manifest
-Create a new generation of the profile from the manifest object
-returned by the Scheme code in @var{file}.
+@node Guided Graphical Installation
+@section Guided Graphical Installation
-This allows you to @emph{declare} the profile's contents rather than
-constructing it through a sequence of @code{--install} and similar
-commands. The advantage is that @var{file} can be put under version
-control, copied to different machines to reproduce the same profile, and
-so on.
+The graphical installer is a text-based user interface. It will guide you,
+with dialog boxes, through the steps needed to install GNU@tie{}Guix System.
-@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:
+The first dialog boxes allow you to set up the system as you use it during the
+installation: you can choose the language, keyboard layout, and set up
+networking, which will be used during the installation. The image below shows
+the networking dialog.
-@findex packages->manifest
-@example
-(use-package-modules guile emacs)
+@image{images/installer-network,5in,, networking setup with the graphical installer}
-(packages->manifest
- (list emacs
- guile-2.0
- ;; Use a specific package output.
- (list guile-2.0 "debug")))
-@end example
+Later steps allow you to partition your hard disk, as shown in the image
+below, to choose whether or not to use encrypted file systems, to enter the
+host name and root password, and to create an additional account, among other
+things.
-@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:
+@image{images/installer-partitions,5in,, partitioning with the graphical installer}
-@example
-(specifications->manifest
- '("emacs" "guile@@2.2" "guile@@2.2:debug"))
-@end example
+Note that, at any time, the installer allows you to exit the current
+installation step and resume at a previous step, as show in the image below.
-@item --roll-back
-@cindex rolling back
-@cindex undoing transactions
-@cindex transactions, undoing
-Roll back to the previous @dfn{generation} of the profile---i.e., undo
-the last transaction.
+@image{images/installer-resume,5in,, resuming the installation process}
-When combined with options such as @code{--install}, roll back occurs
-before any other actions.
+Once you're done, the installer produces an operating system configuration and
+displays it (@pxref{Using the Configuration System}). At that point you can
+hit ``OK'' and installation will proceed. On success, you can reboot into the
+new system and enjoy. @xref{After System Installation}, for what's next!
-When rolling back from the first generation that actually contains
-installed packages, the profile is made to point to the @dfn{zeroth
-generation}, which contains no files apart from its own metadata.
-After having rolled back, installing, removing, or upgrading packages
-overwrites previous future generations. Thus, the history of the
-generations in a profile is always linear.
+@node Manual Installation
+@section Manual Installation
-@item --switch-generation=@var{pattern}
-@itemx -S @var{pattern}
-@cindex generations
-Switch to a particular generation defined by @var{pattern}.
+This section describes how you would ``manually'' install GNU@tie{}Guix System
+on your machine. This option requires familiarity with GNU/Linux, with the
+shell, and with common administration tools. If you think this is not for
+you, consider using the guided graphical installer (@pxref{Guided Graphical
+Installation}).
-@var{pattern} may be either a generation number or a number prefixed
-with ``+'' or ``-''. The latter means: move forward/backward by a
-specified number of generations. For example, if you want to return to
-the latest generation after @code{--roll-back}, use
-@code{--switch-generation=+1}.
+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
+need it, using @command{guix package} (@pxref{Invoking guix package}).
-The difference between @code{--roll-back} and
-@code{--switch-generation=-1} is that @code{--switch-generation} will
-not make a zeroth generation, so if a specified generation does not
-exist, the current generation will not be changed.
+@menu
+* Keyboard Layout and Networking and Partitioning:: Initial setup.
+* Proceeding with the Installation:: Installing.
+@end menu
-@item --search-paths[=@var{kind}]
-@cindex search paths
-Report environment variable definitions, in Bash syntax, that may be
-needed in order to use the set of installed packages. These environment
-variables are used to specify @dfn{search paths} for files used by some
-of the installed packages.
+@node Keyboard Layout and Networking and Partitioning
+@subsection Keyboard Layout, Networking, and Partitioning
-For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
-environment variables to be defined so it can look for headers and
-libraries in the user's profile (@pxref{Environment Variables,,, gcc,
-Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
-library are installed in the profile, then @code{--search-paths} will
-suggest setting these variables to @code{@var{profile}/include} and
-@code{@var{profile}/lib}, respectively.
+Before you can install the system, you may want to adjust the keyboard layout,
+set up networking, and partition your target hard disk. This section will
+guide you through this.
-The typical use case is to define these environment variables in the
-shell:
+@subsubsection Keyboard Layout
+
+@cindex keyboard layout
+The installation image uses the US qwerty keyboard layout. If you want
+to change it, you can use the @command{loadkeys} command. For example,
+the following command selects the Dvorak keyboard layout:
@example
-$ eval `guix package --search-paths`
+loadkeys dvorak
@end example
-@var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
-meaning that the returned environment variable definitions will either
-be exact settings, or prefixes or suffixes of the current value of these
-variables. When omitted, @var{kind} defaults to @code{exact}.
+See the files under @file{/run/current-system/profile/share/keymaps} for
+a list of available keyboard layouts. Run @command{man loadkeys} for
+more information.
-This option can also be used to compute the @emph{combined} search paths
-of several profiles. Consider this example:
+@subsubsection Networking
+
+Run the following command to see what your network interfaces are called:
@example
-$ guix package -p foo -i guile
-$ guix package -p bar -i guile-json
-$ guix package -p foo -p bar --search-paths
+ifconfig -a
@end example
-The last command above reports about the @code{GUILE_LOAD_PATH}
-variable, even though, taken individually, neither @file{foo} nor
-@file{bar} would lead to that recommendation.
-
-
-@item --profile=@var{profile}
-@itemx -p @var{profile}
-Use @var{profile} instead of the user's default profile.
-
-@cindex collisions, in a profile
-@cindex colliding packages in profiles
-@cindex profile collisions
-@item --allow-collisions
-Allow colliding packages in the new profile. Use at your own risk!
+@noindent
+@dots{} or, using the GNU/Linux-specific @command{ip} command:
-By default, @command{guix package} reports as an error @dfn{collisions}
-in the profile. Collisions happen when two or more different versions
-or variants of a given package end up in the profile.
+@example
+ip a
+@end example
-@item --bootstrap
-Use the bootstrap Guile to build the profile. This option is only
-useful to distribution developers.
+@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
+Wired interfaces have a name starting with @samp{e}; for example, the
+interface corresponding to the first on-board Ethernet controller is
+called @samp{eno1}. Wireless interfaces have a name starting with
+@samp{w}, like @samp{w1p2s0}.
-@end table
+@table @asis
+@item Wired connection
+To configure a wired network run the following command, substituting
+@var{interface} with the name of the wired interface you want to use.
-In addition to these actions, @command{guix package} supports the
-following options to query the current state of a profile, or the
-availability of packages:
+@example
+ifconfig @var{interface} up
+@end example
-@table @option
+@item Wireless connection
+@cindex wireless
+@cindex WiFi
+To configure wireless networking, you can create a configuration file
+for the @command{wpa_supplicant} configuration tool (its location is not
+important) using one of the available text editors such as
+@command{nano}:
-@item --search=@var{regexp}
-@itemx -s @var{regexp}
-@cindex searching for packages
-List the available packages whose name, synopsis, or description matches
-@var{regexp} (in a case-insensitive fashion), sorted by relevance.
-Print all the metadata of matching packages in
-@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
-GNU recutils manual}).
+@example
+nano wpa_supplicant.conf
+@end example
-This allows specific fields to be extracted using the @command{recsel}
-command, for instance:
+As an example, the following stanza can go to this file and will work
+for many wireless networks, provided you give the actual SSID and
+passphrase for the network you are connecting to:
@example
-$ guix package -s malloc | recsel -p name,version,relevance
-name: jemalloc
-version: 4.5.0
-relevance: 6
+network=@{
+ ssid="@var{my-ssid}"
+ key_mgmt=WPA-PSK
+ psk="the network's secret passphrase"
+@}
+@end example
-name: glibc
-version: 2.25
-relevance: 1
+Start the wireless service and run it in the background with the
+following command (substitute @var{interface} with the name of the
+network interface you want to use):
-name: libgc
-version: 7.6.0
-relevance: 1
+@example
+wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
@end example
-Similarly, to show the name of all the packages available under the
-terms of the GNU@tie{}LGPL version 3:
+Run @command{man wpa_supplicant} for more information.
+@end table
-@example
-$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
-name: elfutils
+@cindex DHCP
+At this point, you need to acquire an IP address. On a network where IP
+addresses are automatically assigned @i{via} DHCP, you can run:
-name: gmp
-@dots{}
+@example
+dhclient -v @var{interface}
@end example
-It is also possible to refine search results using several @code{-s}
-flags. For example, the following command returns a list of board
-games:
+Try to ping a server to see if networking is up and running:
@example
-$ guix package -s '\<board\>' -s game | recsel -p name
-name: gnubg
-@dots{}
+ping -c 3 gnu.org
@end example
-If we were to omit @code{-s game}, we would also get software packages
-that deal with printed circuit boards; removing the angle brackets
-around @code{board} would further add packages that have to do with
-keyboards.
+Setting up network access is almost always a requirement because the
+image does not contain all the software and tools that may be needed.
-And now for a more elaborate example. The following command searches
-for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
-libraries, and prints the name and synopsis of the matching packages:
+@cindex installing over SSH
+If you want to, you can continue the installation remotely by starting
+an SSH server:
@example
-$ guix package -s crypto -s library | \
- recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
+herd start ssh-daemon
@end example
-@noindent
-@xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
-information on @dfn{selection expressions} for @code{recsel -e}.
+Make sure to either set a password with @command{passwd}, or configure
+OpenSSH public key authentication before logging in.
-@item --show=@var{package}
-Show details about @var{package}, taken from the list of available packages, in
-@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
-recutils manual}).
+@subsubsection Disk Partitioning
-@example
-$ guix package --show=python | recsel -p name,version
-name: python
-version: 2.7.6
+Unless this has already been done, the next step is to partition, and
+then format the target partition(s).
-name: python
-version: 3.3.5
-@end example
+The installation image includes several partitioning tools, including
+Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
+@command{fdisk}, and @command{cfdisk}. Run it and set up your disk with
+the partition layout you want:
-You may also specify the full name of a package to only get details about a
-specific version of it:
@example
-$ guix package --show=python@@3.4 | recsel -p name,version
-name: python
-version: 3.4.3
+cfdisk
@end example
+If your disk uses the GUID Partition Table (GPT) format and you plan to
+install BIOS-based GRUB (which is the default), make sure a BIOS Boot
+Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB
+manual}).
+@cindex EFI, installation
+@cindex UEFI, installation
+@cindex ESP, EFI system partition
+If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition}
+(ESP) is required. This partition can be mounted at @file{/boot/efi} for
+instance and must have the @code{esp} flag set. E.g., for @command{parted}:
-@item --list-installed[=@var{regexp}]
-@itemx -I [@var{regexp}]
-List the currently installed packages in the specified profile, with the
-most recently installed packages shown last. When @var{regexp} is
-specified, list only installed packages whose name matches @var{regexp}.
+@example
+parted /dev/sda set 1 esp on
+@end example
-For each installed package, print the following items, separated by
-tabs: the package name, its version string, the part of the package that
-is installed (for instance, @code{out} for the default output,
-@code{include} for its headers, etc.), and the path of this package in
-the store.
+@quotation Note
+@vindex grub-bootloader
+@vindex grub-efi-bootloader
+Unsure whether to use EFI- or BIOS-based GRUB? If the directory
+@file{/sys/firmware/efi} exists in the installation image, then you should
+probably perform an EFI installation, using @code{grub-efi-bootloader}.
+Otherwise you should use the BIOS-based GRUB, known as
+@code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on
+bootloaders.
+@end quotation
-@item --list-available[=@var{regexp}]
-@itemx -A [@var{regexp}]
-List packages currently available in the distribution for this system
-(@pxref{GNU Distribution}). When @var{regexp} is specified, list only
-installed packages whose name matches @var{regexp}.
-
-For each package, print the following items separated by tabs: its name,
-its version string, the parts of the package (@pxref{Packages with
-Multiple Outputs}), and the source location of its definition.
+Once you are done partitioning the target hard disk drive, you have to
+create a file system on the relevant partition(s)@footnote{Currently
+Guix System only supports ext4 and btrfs file systems. In particular, code
+that reads file system UUIDs and labels only works for these file system
+types.}. For the ESP, if you have one and assuming it is
+@file{/dev/sda1}, run:
-@item --list-generations[=@var{pattern}]
-@itemx -l [@var{pattern}]
-@cindex generations
-Return a list of generations along with their creation dates; for each
-generation, show the installed packages, with the most recently
-installed packages shown last. Note that the zeroth generation is never
-shown.
+@example
+mkfs.fat -F32 /dev/sda1
+@end example
-For each installed package, print the following items, separated by
-tabs: the name of a package, its version string, the part of the package
-that is installed (@pxref{Packages with Multiple Outputs}), and the
-location of this package in the store.
+Preferably, assign file systems a label so that you can easily and
+reliably refer to them in @code{file-system} declarations (@pxref{File
+Systems}). This is typically done using the @code{-L} option of
+@command{mkfs.ext4} and related commands. So, assuming the target root
+partition lives at @file{/dev/sda2}, a file system with the label
+@code{my-root} can be created with:
-When @var{pattern} is used, the command returns only matching
-generations. Valid patterns include:
+@example
+mkfs.ext4 -L my-root /dev/sda2
+@end example
-@itemize
-@item @emph{Integers and comma-separated integers}. Both patterns denote
-generation numbers. For instance, @code{--list-generations=1} returns
-the first one.
+@cindex encrypted disk
+If you are instead planning to encrypt the root partition, you can use
+the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
+@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
+@code{man cryptsetup}} for more information.) Assuming you want to
+store the root partition on @file{/dev/sda2}, the command sequence would
+be along these lines:
-And @code{--list-generations=1,8,2} outputs three generations in the
-specified order. Neither spaces nor trailing commas are allowed.
+@example
+cryptsetup luksFormat /dev/sda2
+cryptsetup open --type luks /dev/sda2 my-partition
+mkfs.ext4 -L my-root /dev/mapper/my-partition
+@end example
-@item @emph{Ranges}. @code{--list-generations=2..9} prints the
-specified generations and everything in between. Note that the start of
-a range must be smaller than its end.
+Once that is done, mount the target file system under @file{/mnt}
+with a command like (again, assuming @code{my-root} is the label of the
+root file system):
-It is also possible to omit the endpoint. For example,
-@code{--list-generations=2..}, returns all generations starting from the
-second one.
+@example
+mount LABEL=my-root /mnt
+@end example
-@item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
-or months by passing an integer along with the first letter of the
-duration. For example, @code{--list-generations=20d} lists generations
-that are up to 20 days old.
-@end itemize
+Also mount any other file systems you would like to use on the target
+system relative to this path. If you have opted for @file{/boot/efi} as an
+EFI mount point for example, mount it at @file{/mnt/boot/efi} now so it is
+found by @code{guix system init} afterwards.
-@item --delete-generations[=@var{pattern}]
-@itemx -d [@var{pattern}]
-When @var{pattern} is omitted, delete all generations except the current
-one.
+Finally, if you plan to use one or more swap partitions (@pxref{Memory
+Concepts, swap space,, libc, The GNU C Library Reference Manual}), make
+sure to initialize them with @command{mkswap}. Assuming you have one
+swap partition on @file{/dev/sda3}, you would run:
-This command accepts the same patterns as @option{--list-generations}.
-When @var{pattern} is specified, delete the matching generations. When
-@var{pattern} specifies a duration, generations @emph{older} than the
-specified duration match. For instance, @code{--delete-generations=1m}
-deletes generations that are more than one month old.
+@example
+mkswap /dev/sda3
+swapon /dev/sda3
+@end example
-If the current generation matches, it is @emph{not} deleted. Also, the
-zeroth generation is never deleted.
+Alternatively, you may use a swap file. For example, assuming that in
+the new system you want to use the file @file{/swapfile} as a swap file,
+you would run@footnote{This example will work for many types of file
+systems (e.g., ext4). However, for copy-on-write file systems (e.g.,
+btrfs), the required steps may be different. For details, see the
+manual pages for @command{mkswap} and @command{swapon}.}:
-Note that deleting generations prevents rolling back to them.
-Consequently, this command must be used with care.
+@example
+# This is 10 GiB of swap space. Adjust "count" to change the size.
+dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
+# For security, make the file readable and writable only by root.
+chmod 600 /mnt/swapfile
+mkswap /mnt/swapfile
+swapon /mnt/swapfile
+@end example
-@end table
+Note that if you have encrypted the root partition and created a swap
+file in its file system as described above, then the encryption also
+protects the swap file, just like any other file in that file system.
-Finally, since @command{guix package} may actually start build
-processes, it supports all the common build options (@pxref{Common Build
-Options}). It also supports package transformation options, such as
-@option{--with-source} (@pxref{Package Transformation Options}).
-However, note that package transformations are lost when upgrading; to
-preserve transformations across upgrades, you should define your own
-package variant in a Guile module and add it to @code{GUIX_PACKAGE_PATH}
-(@pxref{Defining Packages}).
+@node Proceeding with the Installation
+@subsection Proceeding with the Installation
-@node Substitutes
-@section Substitutes
+With the target partitions ready and the target root mounted on
+@file{/mnt}, we're ready to go. First, run:
-@cindex substitutes
-@cindex pre-built binaries
-Guix supports transparent source/binary deployment, which means that it
-can either build things locally, or download pre-built items from a
-server, or both. We call these pre-built items @dfn{substitutes}---they
-are substitutes for local build results. In many cases, downloading a
-substitute is much faster than building things locally.
+@example
+herd start cow-store /mnt
+@end example
-Substitutes can be anything resulting from a derivation build
-(@pxref{Derivations}). Of course, in the common case, they are
-pre-built package binaries, but source tarballs, for instance, which
-also result from derivation builds, can be available as substitutes.
+This makes @file{/gnu/store} copy-on-write, such that packages added to it
+during the installation phase are written to the target disk on @file{/mnt}
+rather than kept in memory. This is necessary because the first phase of
+the @command{guix system init} command (see below) entails downloads or
+builds to @file{/gnu/store} which, initially, is an in-memory file system.
-@menu
-* Official Substitute Server:: One particular source of substitutes.
-* Substitute Server Authorization:: How to enable or disable substitutes.
-* Substitute Authentication:: How Guix verifies substitutes.
-* Proxy Settings:: How to get substitutes via proxy.
-* Substitution Failure:: What happens when substitution fails.
-* On Trusting Binaries:: How can you trust that binary blob?
-@end menu
+Next, you have to edit a file and
+provide the declaration of the operating system to be installed. To
+that end, the installation system comes with three text editors. We
+recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
+supports syntax highlighting and parentheses matching; other editors
+include GNU Zile (an Emacs clone), and
+nvi (a clone of the original BSD @command{vi} editor).
+We strongly recommend storing that file on the target root file system, say,
+as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
+configuration file once you have rebooted into the newly-installed system.
-@node Official Substitute Server
-@subsection Official Substitute Server
+@xref{Using the Configuration System}, for an overview of the
+configuration file. The example configurations discussed in that
+section are available under @file{/etc/configuration} in the
+installation image. Thus, to get started with a system configuration
+providing a graphical display server (a ``desktop'' system), you can run
+something along these lines:
-@cindex hydra
-@cindex build farm
-The @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an official build farm
-that builds packages from Guix continuously for some
-architectures, and makes them available as substitutes. This is the
-default source of substitutes; it can be overridden by passing the
-@option{--substitute-urls} option either to @command{guix-daemon}
-(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
-or to client tools such as @command{guix package}
-(@pxref{client-substitute-urls,, client @option{--substitute-urls}
-option}).
+@example
+# mkdir /mnt/etc
+# cp /etc/configuration/desktop.scm /mnt/etc/config.scm
+# nano /mnt/etc/config.scm
+@end example
-Substitute URLs can be either HTTP or HTTPS.
-HTTPS is recommended because communications are encrypted; conversely,
-using HTTP makes all communications visible to an eavesdropper, who
-could use the information gathered to determine, for instance, whether
-your system has unpatched security vulnerabilities.
+You should pay attention to what your configuration file contains, and
+in particular:
-Substitutes from the official build farm are enabled by default when
-using the Guix System Distribution (@pxref{GNU Distribution}). However,
-they are disabled by default when using Guix on a foreign distribution,
-unless you have explicitly enabled them via one of the recommended
-installation steps (@pxref{Installation}). The following paragraphs
-describe how to enable or disable substitutes for the official build
-farm; the same procedure can also be used to enable substitutes for any
-other substitute server.
+@itemize
+@item
+Make sure the @code{bootloader-configuration} form refers to the target
+you want to install GRUB on. It should mention @code{grub-bootloader} if
+you are installing GRUB in the legacy way, or @code{grub-efi-bootloader}
+for newer UEFI systems. For legacy systems, the @code{target} field
+names a device, like @code{/dev/sda}; for UEFI systems it names a path
+to a mounted EFI partition, like @code{/boot/efi}; do make sure the path is
+currently mounted and a @code{file-system} entry is specified in your
+configuration.
-@node Substitute Server Authorization
-@subsection Substitute Server Authorization
+@item
+Be sure that your file system labels match the value of their respective
+@code{device} fields in your @code{file-system} configuration, assuming
+your @code{file-system} configuration uses the @code{file-system-label}
+procedure in its @code{device} field.
-@cindex security
-@cindex substitutes, authorization thereof
-@cindex access control list (ACL), for substitutes
-@cindex ACL (access control list), for substitutes
-To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER}} or a
-mirror thereof, you
-must add its public key to the access control list (ACL) of archive
-imports, using the @command{guix archive} command (@pxref{Invoking guix
-archive}). Doing so implies that you trust @code{@value{SUBSTITUTE-SERVER}} to not
-be compromised and to serve genuine substitutes.
+@item
+If there are encrypted or RAID partitions, make sure to add a
+@code{mapped-devices} field to describe them (@pxref{Mapped Devices}).
+@end itemize
-The public key for @code{@value{SUBSTITUTE-SERVER}} is installed along with Guix, in
-@code{@var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, where @var{prefix} is
-the installation prefix of Guix. If you installed Guix from source,
-make sure you checked the GPG signature of
-@file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
-Then, you can run something like this:
+Once you are done preparing the configuration file, the new system must
+be initialized (remember that the target root file system is mounted
+under @file{/mnt}):
@example
-# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub
+guix system init /mnt/etc/config.scm /mnt
@end example
-@quotation Note
-Similarly, the @file{hydra.gnu.org.pub} file contains the public key
-of an independent build farm also run by the project, reachable at
-@indicateurl{https://mirror.hydra.gnu.org}.
-@end quotation
-
-Once this is in place, the output of a command like @code{guix build}
-should change from something like:
+@noindent
+This copies all the necessary files and installs GRUB on
+@file{/dev/sdX}, unless you pass the @option{--no-bootloader} option. For
+more information, @pxref{Invoking guix system}. This command may trigger
+downloads or builds of missing packages, which can take some time.
-@example
-$ guix build emacs --dry-run
-The following derivations would be built:
- /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
- /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
- /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
- /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
-@dots{}
-@end example
+Once that command has completed---and hopefully succeeded!---you can run
+@command{reboot} and boot into the new system. The @code{root} password
+in the new system is initially empty; other users' passwords need to be
+initialized by running the @command{passwd} command as @code{root},
+unless your configuration specifies otherwise
+(@pxref{user-account-password, user account passwords}).
+@xref{After System Installation}, for what's next!
-@noindent
-to something like:
+
+@node After System Installation
+@section After System Installation
+
+Success, you've now booted into Guix System! From then on, you can update the
+system whenever you want by running, say:
@example
-$ guix build emacs --dry-run
-112.3 MB would be downloaded:
- /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
- /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
- /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
- /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
-@dots{}
+guix pull
+sudo guix system reconfigure /etc/config.scm
@end example
@noindent
-This indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} are usable and
-will be downloaded, when possible, for future builds.
+This builds a new system generation with the latest packages and services
+(@pxref{Invoking guix system}). We recommend doing that regularly so that
+your system includes the latest security updates (@pxref{Security Updates}).
-@cindex substitutes, how to disable
-The substitute mechanism can be disabled globally by running
-@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
-guix-daemon}). It can also be disabled temporarily by passing the
-@code{--no-substitutes} option to @command{guix package}, @command{guix
-build}, and other command-line tools.
+@c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>.
+@quotation Note
+@cindex sudo vs. @command{guix pull}
+Note that @command{sudo guix} runs your user's @command{guix} command and
+@emph{not} root's, because @command{sudo} leaves @code{PATH} unchanged. To
+explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.
+@end quotation
-@node Substitute Authentication
-@subsection Substitute Authentication
+Join us on @code{#guix} on the Freenode IRC network or on
+@email{guix-devel@@gnu.org} to share your experience!
-@cindex digital signatures
-Guix detects and raises an error when attempting to use a substitute
-that has been tampered with. Likewise, it ignores substitutes that are
-not signed, or that are not signed by one of the keys listed in the ACL.
-There is one exception though: if an unauthorized server provides
-substitutes that are @emph{bit-for-bit identical} to those provided by
-an authorized server, then the unauthorized server becomes eligible for
-downloads. For example, assume we have chosen two substitute servers
-with this option:
+@node Installing Guix in a VM
+@section Installing Guix in a Virtual Machine
-@example
---substitute-urls="https://a.example.org https://b.example.org"
-@end example
+@cindex virtual machine, Guix System installation
+@cindex virtual private server (VPS)
+@cindex VPS (virtual private server)
+If you'd like to install Guix System in a virtual machine (VM) or on a
+virtual private server (VPS) rather than on your beloved machine, this
+section is for you.
-@noindent
-@cindex reproducible builds
-If the ACL contains only the key for @code{b.example.org}, and if
-@code{a.example.org} happens to serve the @emph{exact same} substitutes,
-then Guix will download substitutes from @code{a.example.org} because it
-comes first in the list and can be considered a mirror of
-@code{b.example.org}. In practice, independent build machines usually
-produce the same binaries, thanks to bit-reproducible builds (see
-below).
+To boot a @uref{http://qemu.org/,QEMU} VM for installing Guix System in a
+disk image, follow these steps:
-When using HTTPS, the server's X.509 certificate is @emph{not} validated
-(in other words, the server is not authenticated), contrary to what
-HTTPS clients such as Web browsers usually do. This is because Guix
-authenticates substitute information itself, as explained above, which
-is what we care about (whereas X.509 certificates are about
-authenticating bindings between domain names and public keys.)
+@enumerate
+@item
+First, retrieve and decompress the Guix system installation image as
+described previously (@pxref{USB Stick and DVD Installation}).
-@node Proxy Settings
-@subsection Proxy Settings
+@item
+Create a disk image that will hold the installed system. To make a
+qcow2-formatted disk image, use the @command{qemu-img} command:
-@vindex http_proxy
-Substitutes are downloaded over HTTP or HTTPS.
-The @code{http_proxy} environment
-variable can be set in the environment of @command{guix-daemon} and is
-honored for downloads of substitutes. Note that the value of
-@code{http_proxy} in the environment where @command{guix build},
-@command{guix package}, and other client commands are run has
-@emph{absolutely no effect}.
+@example
+qemu-img create -f qcow2 guixsd.img 50G
+@end example
-@node Substitution Failure
-@subsection Substitution Failure
+The resulting file will be much smaller than 50 GB (typically less than
+1 MB), but it will grow as the virtualized storage device is filled up.
-Even when a substitute for a derivation is available, sometimes the
-substitution attempt will fail. This can happen for a variety of
-reasons: the substitute server might be offline, the substitute may
-recently have been deleted, the connection might have been interrupted,
-etc.
+@item
+Boot the USB installation image in an VM:
-When substitutes are enabled and a substitute for a derivation is
-available, but the substitution attempt fails, Guix will attempt to
-build the derivation locally depending on whether or not
-@code{--fallback} was given (@pxref{fallback-option,, common build
-option @code{--fallback}}). Specifically, if @code{--fallback} was
-omitted, then no local build will be performed, and the derivation is
-considered to have failed. However, if @code{--fallback} was given,
-then Guix will attempt to build the derivation locally, and the success
-or failure of the derivation depends on the success or failure of the
-local build. Note that when substitutes are disabled or no substitute
-is available for the derivation in question, a local build will
-@emph{always} be performed, regardless of whether or not
-@code{--fallback} was given.
+@example
+qemu-system-x86_64 -m 1024 -smp 1 \
+ -net user -net nic,model=virtio -boot menu=on \
+ -drive file=guix-system-install-@value{VERSION}.@var{system}.iso \
+ -drive file=guixsd.img
+@end example
-To get an idea of how many substitutes are available right now, you can
-try running the @command{guix weather} command (@pxref{Invoking guix
-weather}). This command provides statistics on the substitutes provided
-by a server.
+The ordering of the drives matters.
-@node On Trusting Binaries
-@subsection On Trusting Binaries
+In the VM console, quickly press the @kbd{F12} key to enter the boot
+menu. Then press the @kbd{2} key and the @kbd{RET} key to validate your
+selection.
-@cindex trust, of pre-built binaries
-Today, each individual's control over their own computing is at the
-mercy of institutions, corporations, and groups with enough power and
-determination to subvert the computing infrastructure and exploit its
-weaknesses. While using @code{@value{SUBSTITUTE-SERVER}} substitutes can be
-convenient, we encourage users to also build on their own, or even run
-their own build farm, such that @code{@value{SUBSTITUTE-SERVER}} is less of an
-interesting target. One way to help is by publishing the software you
-build using @command{guix publish} so that others have one more choice
-of server to download substitutes from (@pxref{Invoking guix publish}).
+@item
+You're now root in the VM, proceed with the installation process.
+@xref{Preparing for Installation}, and follow the instructions.
+@end enumerate
-Guix has the foundations to maximize build reproducibility
-(@pxref{Features}). In most cases, independent builds of a given
-package or derivation should yield bit-identical results. Thus, through
-a diverse set of independent package builds, we can strengthen the
-integrity of our systems. The @command{guix challenge} command aims to
-help users assess substitute servers, and to assist developers in
-finding out about non-deterministic package builds (@pxref{Invoking guix
-challenge}). Similarly, the @option{--check} option of @command{guix
-build} allows users to check whether previously-installed substitutes
-are genuine by rebuilding them locally (@pxref{build-check,
-@command{guix build --check}}).
+Once installation is complete, you can boot the system that's on your
+@file{guixsd.img} image. @xref{Running Guix in a VM}, for how to do
+that.
-In the future, we want Guix to have support to publish and retrieve
-binaries to/from other users, in a peer-to-peer fashion. If you would
-like to discuss this project, join us on @email{guix-devel@@gnu.org}.
+@node Building the Installation Image
+@section Building the Installation Image
-@node Packages with Multiple Outputs
-@section Packages with Multiple Outputs
+@cindex installation image
+The installation image described above was built using the @command{guix
+system} command, specifically:
-@cindex multiple-output packages
-@cindex package outputs
-@cindex outputs
+@example
+guix system disk-image --file-system-type=iso9660 \
+ gnu/system/install.scm
+@end example
-Often, packages defined in Guix have a single @dfn{output}---i.e., the
-source package leads to exactly one directory in the store. When running
-@command{guix package -i glibc}, one installs the default output of the
-GNU libc package; the default output is called @code{out}, but its name
-can be omitted as shown in this command. In this particular case, the
-default output of @code{glibc} contains all the C header files, shared
-libraries, static libraries, Info documentation, and other supporting
-files.
+Have a look at @file{gnu/system/install.scm} in the source tree,
+and see also @ref{Invoking guix system} for more information
+about the installation image.
-Sometimes it is more appropriate to separate the various types of files
-produced from a single source package into separate outputs. For
-instance, the GLib C library (used by GTK+ and related packages)
-installs more than 20 MiB of reference documentation as HTML pages.
-To save space for users who do not need it, the documentation goes to a
-separate output, called @code{doc}. To install the main GLib output,
-which contains everything but the documentation, one would run:
+@section Building the Installation Image for ARM Boards
-@example
-guix package -i glib
-@end example
+Many ARM boards require a specific variant of the
+@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
-@cindex documentation
-The command to install its documentation is:
+If you build a disk image and the bootloader is not available otherwise
+(on another boot drive etc), it's advisable to build an image that
+includes the bootloader, specifically:
@example
-guix package -i glib:doc
+guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
@end example
-Some packages install programs with different ``dependency footprints''.
-For instance, the WordNet package installs both command-line tools and
-graphical user interfaces (GUIs). The former depend solely on the C
-library, whereas the latter depend on Tcl/Tk and the underlying X
-libraries. In this case, we leave the command-line tools in the default
-output, whereas the GUIs are in a separate output. This allows users
-who do not need the GUIs to save space. The @command{guix size} command
-can help find out about such situations (@pxref{Invoking guix size}).
-@command{guix graph} can also be helpful (@pxref{Invoking guix graph}).
-
-There are several such multiple-output packages in the GNU distribution.
-Other conventional output names include @code{lib} for libraries and
-possibly header files, @code{bin} for stand-alone programs, and
-@code{debug} for debugging information (@pxref{Installing Debugging
-Files}). The outputs of a packages are listed in the third column of
-the output of @command{guix package --list-available} (@pxref{Invoking
-guix package}).
+@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 *********************************************************************
+@node Package Management
+@chapter Package Management
-@node Invoking guix gc
-@section Invoking @command{guix gc}
+@cindex packages
+The purpose of GNU Guix is to allow users to easily install, upgrade, and
+remove software packages, without having to know about their build
+procedures or dependencies. Guix also goes beyond this obvious set of
+features.
-@cindex garbage collector
-@cindex disk space
-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
-the @emph{only} way to remove files from @file{/gnu/store}---removing
-files or directories manually may break it beyond repair!
+This chapter describes the main features of Guix, as well as the
+package management tools it provides. Along with the command-line
+interface described below (@pxref{Invoking guix package, @code{guix
+package}}), you may also use the Emacs-Guix interface (@pxref{Top,,,
+emacs-guix, The Emacs-Guix Reference Manual}), after installing
+@code{emacs-guix} package (run @kbd{M-x guix-help} command to start
+with it):
-@cindex GC roots
-@cindex garbage collector roots
-The garbage collector has a set of known @dfn{roots}: any file under
-@file{/gnu/store} reachable from a root is considered @dfn{live} and
-cannot be deleted; any other file is considered @dfn{dead} and may be
-deleted. The set of garbage collector roots (``GC roots'' for short)
-includes default user profiles; by default, the symlinks under
-@file{/var/guix/gcroots} represent these GC roots. New GC roots can be
-added with @command{guix build --root}, for example (@pxref{Invoking
-guix build}).
+@example
+guix package -i emacs-guix
+@end example
-Prior to running @code{guix gc --collect-garbage} to make space, it is
-often useful to remove old generations from user profiles; that way, old
-package builds referenced by those generations can be reclaimed. This
-is achieved by running @code{guix package --delete-generations}
-(@pxref{Invoking guix package}).
-
-Our recommendation is to run a garbage collection periodically, or when
-you are short on disk space. For instance, to guarantee that at least
-5@tie{}GB are available on your disk, simply run:
-
-@example
-guix gc -F 5G
-@end example
-
-It is perfectly safe to run as a non-interactive periodic job
-(@pxref{Scheduled Job Execution}, for how to set up such a job on
-GuixSD). Running @command{guix gc} with no arguments will collect as
-much garbage as it can, but that is often inconvenient: you may find
-yourself having to rebuild or re-download software that is ``dead'' from
-the GC viewpoint but that is necessary to build other pieces of
-software---e.g., the compiler tool chain.
-
-The @command{guix gc} command has three modes of operation: it can be
-used to garbage-collect any dead files (the default), to delete specific
-files (the @code{--delete} option), to print garbage-collector
-information, or for more advanced queries. The garbage collection
-options are as follows:
-
-@table @code
-@item --collect-garbage[=@var{min}]
-@itemx -C [@var{min}]
-Collect garbage---i.e., unreachable @file{/gnu/store} files and
-sub-directories. This is the default operation when no option is
-specified.
+@menu
+* Features:: How Guix will make your life brighter.
+* Invoking guix package:: Package installation, removal, etc.
+* Substitutes:: Downloading pre-built binaries.
+* Packages with Multiple Outputs:: Single source package, multiple outputs.
+* Invoking guix gc:: Running the garbage collector.
+* Invoking guix pull:: Fetching the latest Guix and distribution.
+* Channels:: Customizing the package collection.
+* Inferiors:: Interacting with another revision of Guix.
+* Invoking guix describe:: Display information about your Guix revision.
+* Invoking guix archive:: Exporting and importing store files.
+@end menu
-When @var{min} is given, stop once @var{min} bytes have been collected.
-@var{min} may be a number of bytes, or it may include a unit as a
-suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
-(@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
+@node Features
+@section Features
-When @var{min} is omitted, collect all the garbage.
+When using Guix, each package ends up in the @dfn{package store}, in its
+own directory---something that resembles
+@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
-@item --free-space=@var{free}
-@itemx -F @var{free}
-Collect garbage until @var{free} space is available under
-@file{/gnu/store}, if possible; @var{free} denotes storage space, such
-as @code{500MiB}, as described above.
+Instead of referring to these directories, users have their own
+@dfn{profile}, which points to the packages that they actually want to
+use. These profiles are stored within each user's home directory, at
+@code{$HOME/.guix-profile}.
-When @var{free} or more is already available in @file{/gnu/store}, do
-nothing and exit immediately.
+For example, @code{alice} installs GCC 4.7.2. As a result,
+@file{/home/alice/.guix-profile/bin/gcc} points to
+@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
+@code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
+simply continues to point to
+@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
+coexist on the same system without any interference.
-@item --delete
-@itemx -d
-Attempt to delete all the store files and directories specified as
-arguments. This fails if some of the files are not in the store, or if
-they are still live.
+The @command{guix package} command is the central tool to manage
+packages (@pxref{Invoking guix package}). It operates on the per-user
+profiles, and can be used @emph{with normal user privileges}.
-@item --list-failures
-List store items corresponding to cached build failures.
+@cindex transactions
+The command provides the obvious install, remove, and upgrade
+operations. Each invocation is actually a @emph{transaction}: either
+the specified operation succeeds, or nothing happens. Thus, if the
+@command{guix package} process is terminated during the transaction,
+or if a power outage occurs during the transaction, then the user's
+profile remains in its previous state, and remains usable.
-This prints nothing unless the daemon was started with
-@option{--cache-failures} (@pxref{Invoking guix-daemon,
-@option{--cache-failures}}).
+In addition, any package transaction may be @emph{rolled back}. So, if,
+for example, an upgrade installs a new version of a package that turns
+out to have a serious bug, users may roll back to the previous instance
+of their profile, which was known to work well. Similarly, the global
+system configuration on Guix is subject to
+transactional upgrades and roll-back
+(@pxref{Using the Configuration System}).
-@item --clear-failures
-Remove the specified store items from the failed-build cache.
+All packages in the package store may be @emph{garbage-collected}.
+Guix can determine which packages are still referenced by user
+profiles, and remove those that are provably no longer referenced
+(@pxref{Invoking guix gc}). Users may also explicitly remove old
+generations of their profile so that the packages they refer to can be
+collected.
-Again, this option only makes sense when the daemon is started with
-@option{--cache-failures}. Otherwise, it does nothing.
+@cindex reproducibility
+@cindex reproducible builds
+Guix takes a @dfn{purely functional} approach to package
+management, as described in the introduction (@pxref{Introduction}).
+Each @file{/gnu/store} package directory name contains a hash of all the
+inputs that were used to build that package---compiler, libraries, build
+scripts, etc. This direct correspondence allows users to make sure a
+given package installation matches the current state of their
+distribution. It also helps maximize @dfn{build reproducibility}:
+thanks to the isolated build environments that are used, a given build
+is likely to yield bit-identical files when performed on different
+machines (@pxref{Invoking guix-daemon, container}).
-@item --list-dead
-Show the list of dead files and directories still present in the
-store---i.e., files and directories no longer reachable from any root.
+@cindex substitutes
+This foundation allows Guix to support @dfn{transparent binary/source
+deployment}. When a pre-built binary for a @file{/gnu/store} item is
+available from an external source---a @dfn{substitute}, Guix just
+downloads it and unpacks it;
+otherwise, it builds the package from source, locally
+(@pxref{Substitutes}). Because build results are usually bit-for-bit
+reproducible, users do not have to trust servers that provide
+substitutes: they can force a local build and @emph{challenge} providers
+(@pxref{Invoking guix challenge}).
-@item --list-live
-Show the list of live store files and directories.
+Control over the build environment is a feature that is also useful for
+developers. The @command{guix environment} command allows developers of
+a package to quickly set up the right development environment for their
+package, without having to manually install the dependencies of the
+package into their profile (@pxref{Invoking guix environment}).
-@end table
+@cindex replication, of software environments
+@cindex provenance tracking, of software artifacts
+All of Guix and its package definitions is version-controlled, and
+@command{guix pull} allows you to ``travel in time'' on the history of Guix
+itself (@pxref{Invoking guix pull}). This makes it possible to replicate a
+Guix instance on a different machine or at a later point in time, which in
+turn allows you to @emph{replicate complete software environments}, while
+retaining precise @dfn{provenance tracking} of the software.
-In addition, the references among existing store files can be queried:
+@node Invoking guix package
+@section Invoking @command{guix package}
-@table @code
+@cindex installing packages
+@cindex removing packages
+@cindex package installation
+@cindex package removal
+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. It operates only on the user's own profile,
+and works with normal user privileges (@pxref{Features}). Its syntax
+is:
-@item --references
-@itemx --referrers
-@cindex package dependencies
-List the references (respectively, the referrers) of store files given
-as arguments.
+@example
+guix package @var{options}
+@end example
+@cindex transactions
+Primarily, @var{options} specifies the operations to be performed during
+the transaction. Upon completion, a new profile is created, but
+previous @dfn{generations} of the profile remain available, should the user
+want to roll back.
-@item --requisites
-@itemx -R
-@cindex closure
-List the requisites of the store files passed as arguments. Requisites
-include the store files themselves, their references, and the references
-of these, recursively. In other words, the returned list is the
-@dfn{transitive closure} of the store files.
+For example, to remove @code{lua} and install @code{guile} and
+@code{guile-cairo} in a single transaction:
-@xref{Invoking guix size}, for a tool to profile the size of the closure
-of an element. @xref{Invoking guix graph}, for a tool to visualize
-the graph of references.
+@example
+guix package -r lua -i guile guile-cairo
+@end example
-@item --derivers
-@cindex derivation
-Return the derivation(s) leading to the given store items
-(@pxref{Derivations}).
+@command{guix package} also supports a @dfn{declarative approach}
+whereby the user specifies the exact set of packages to be available and
+passes it @i{via} the @option{--manifest} option
+(@pxref{profile-manifest, @option{--manifest}}).
-For example, this command:
+@cindex profile
+For each user, a symlink to the user's default profile is automatically
+created in @file{$HOME/.guix-profile}. This symlink always points to the
+current generation of the user's default profile. Thus, users can add
+@file{$HOME/.guix-profile/bin} to their @code{PATH} environment
+variable, and so on.
+@cindex search paths
+If you are not using the Guix System Distribution, consider adding the
+following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
+Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
+shells get all the right environment variable definitions:
@example
-guix gc --derivers `guix package -I ^emacs$ | cut -f4`
+GUIX_PROFILE="$HOME/.guix-profile" ; \
+source "$HOME/.guix-profile/etc/profile"
@end example
-@noindent
-returns the @file{.drv} file(s) leading to the @code{emacs} package
-installed in your profile.
+In a multi-user setup, user profiles are stored in a place registered as
+a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
+to (@pxref{Invoking guix gc}). That directory is normally
+@code{@var{localstatedir}/guix/profiles/per-user/@var{user}}, where
+@var{localstatedir} is the value passed to @code{configure} as
+@code{--localstatedir}, and @var{user} is the user name. The
+@file{per-user} directory is created when @command{guix-daemon} is
+started, and the @var{user} sub-directory is created by @command{guix
+package}.
-Note that there may be zero matching @file{.drv} files, for instance
-because these files have been garbage-collected. There can also be more
-than one matching @file{.drv} due to fixed-output derivations.
-@end table
+The @var{options} can be among the following:
-Lastly, the following options allow you to check the integrity of the
-store and to control disk usage.
+@table @code
-@table @option
+@item --install=@var{package} @dots{}
+@itemx -i @var{package} @dots{}
+Install the specified @var{package}s.
-@item --verify[=@var{options}]
-@cindex integrity, of the store
-@cindex integrity checking
-Verify the integrity of the store.
+Each @var{package} may specify either a simple package name, such as
+@code{guile}, or a package name followed by an at-sign and version number,
+such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter
+case, the newest version prefixed by @code{1.8} is selected.)
-By default, make sure that all the store items marked as valid in the
-database of the daemon actually exist in @file{/gnu/store}.
+If no version number is specified, the
+newest available version will be selected. In addition, @var{package}
+may contain a colon, followed by the name of one of the outputs of the
+package, as in @code{gcc:doc} or @code{binutils@@2.22:lib}
+(@pxref{Packages with Multiple Outputs}). Packages with a corresponding
+name (and optionally version) are searched for among the GNU
+distribution modules (@pxref{Package Modules}).
-When provided, @var{options} must be a comma-separated list containing one
-or more of @code{contents} and @code{repair}.
-
-When passing @option{--verify=contents}, the daemon computes the
-content hash of each store item and compares it against its hash in the
-database. Hash mismatches are reported as data corruptions. Because it
-traverses @emph{all the files in the store}, this command can take a
-long time, especially on systems with a slow disk drive.
-
-@cindex repairing the store
-@cindex corruption, recovering from
-Using @option{--verify=repair} or @option{--verify=contents,repair}
-causes the daemon to try to repair corrupt store items by fetching
-substitutes for them (@pxref{Substitutes}). Because repairing is not
-atomic, and thus potentially dangerous, it is available only to the
-system administrator. A lightweight alternative, when you know exactly
-which items in the store are corrupt, is @command{guix build --repair}
-(@pxref{Invoking guix build}).
-
-@item --optimize
-@cindex deduplication
-Optimize the store by hard-linking identical files---this is
-@dfn{deduplication}.
+@cindex propagated inputs
+Sometimes packages have @dfn{propagated inputs}: these are dependencies
+that automatically get installed along with the required package
+(@pxref{package-propagated-inputs, @code{propagated-inputs} in
+@code{package} objects}, for information about propagated inputs in
+package definitions).
-The daemon performs deduplication after each successful build or archive
-import, unless it was started with @code{--disable-deduplication}
-(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus,
-this option is primarily useful when the daemon was running with
-@code{--disable-deduplication}.
+@anchor{package-cmd-propagated-inputs}
+An example is the GNU MPC library: its C header files refer to those of
+the GNU MPFR library, which in turn refer to those of the GMP library.
+Thus, when installing MPC, the MPFR and GMP libraries also get installed
+in the profile; removing MPC also removes MPFR and GMP---unless they had
+also been explicitly installed by the user.
-@end table
+Besides, packages sometimes rely on the definition of environment
+variables for their search paths (see explanation of
+@code{--search-paths} below). Any missing or possibly incorrect
+environment variable definitions are reported here.
-@node Invoking guix pull
-@section Invoking @command{guix pull}
+@item --install-from-expression=@var{exp}
+@itemx -e @var{exp}
+Install the package @var{exp} evaluates to.
-@cindex upgrading Guix
-@cindex updating Guix
-@cindex @command{guix pull}
-@cindex pull
-Packages are installed or upgraded to the latest version available in
-the distribution currently available on your local machine. To update
-that distribution, along with the Guix tools, you must run @command{guix
-pull}: the command downloads the latest Guix source code and package
-descriptions, and deploys it. Source code is downloaded from a
-@uref{https://git-scm.com, Git} repository, by default the official
-GNU@tie{}Guix repository, though this can be customized.
+@var{exp} must be a Scheme expression that evaluates to a
+@code{<package>} object. This option is notably useful to disambiguate
+between same-named variants of a package, with expressions such as
+@code{(@@ (gnu packages base) guile-final)}.
-On completion, @command{guix package} will use packages and package
-versions from this just-retrieved copy of Guix. Not only that, but all
-the Guix commands and Scheme modules will also be taken from that latest
-version. New @command{guix} sub-commands added by the update also
-become available.
+Note that this option installs the first output of the specified
+package, which may be insufficient when needing a specific output of a
+multiple-output package.
-Any user can update their Guix copy using @command{guix pull}, and the
-effect is limited to the user who run @command{guix pull}. For
-instance, when user @code{root} runs @command{guix pull}, this has no
-effect on the version of Guix that user @code{alice} sees, and vice
-versa.
+@item --install-from-file=@var{file}
+@itemx -f @var{file}
+Install the package that the code within @var{file} evaluates to.
-The result of running @command{guix pull} is a @dfn{profile} available
-under @file{~/.config/guix/current} containing the latest Guix. Thus,
-make sure to add it to the beginning of your search path so that you use
-the latest version, and similarly for the Info manual
-(@pxref{Documentation}):
+As an example, @var{file} might contain a definition like this
+(@pxref{Defining Packages}):
@example
-export PATH="$HOME/.config/guix/current/bin:$PATH"
-export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
+@verbatiminclude package-hello.scm
@end example
-The @code{--list-generations} or @code{-l} option lists past generations
-produced by @command{guix pull}, along with details about their provenance:
+Developers may find it useful to include such a @file{guix.scm} file
+in the root of their project source tree that can be used to test
+development snapshots and create reproducible development environments
+(@pxref{Invoking guix environment}).
-@example
-$ guix pull -l
-Generation 1 Jun 10 2018 00:18:18
- guix 65956ad
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: origin/master
- commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe
+@item --remove=@var{package} @dots{}
+@itemx -r @var{package} @dots{}
+Remove the specified @var{package}s.
-Generation 2 Jun 11 2018 11:02:49
- guix e0cc7f6
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: origin/master
- commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
- 2 new packages: keepalived, libnfnetlink
- 6 packages upgraded: emacs-nix-mode@@2.0.4,
- guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac,
- heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4
+As for @code{--install}, each @var{package} may specify a version number
+and/or output name in addition to the package name. For instance,
+@code{-r glibc:debug} would remove the @code{debug} output of
+@code{glibc}.
-Generation 3 Jun 13 2018 23:31:07 (current)
- guix 844cc1c
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: origin/master
- commit: 844cc1c8f394f03b404c5bb3aee086922373490c
- 28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{}
- 69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{}
-@end example
+@item --upgrade[=@var{regexp} @dots{}]
+@itemx -u [@var{regexp} @dots{}]
+@cindex upgrading packages
+Upgrade all the installed packages. If one or more @var{regexp}s are
+specified, upgrade only installed packages whose name matches a
+@var{regexp}. Also see the @code{--do-not-upgrade} option below.
-@ref{Invoking guix describe, @command{guix describe}}, for other ways to
-describe the current status of Guix.
+Note that this upgrades package to the latest version of packages found
+in the distribution currently installed. To update your distribution,
+you should regularly run @command{guix pull} (@pxref{Invoking guix
+pull}).
-This @code{~/.config/guix/current} profile works like any other profile
-created by @command{guix package} (@pxref{Invoking guix package}). That
-is, you can list generations, roll back to the previous
-generation---i.e., the previous Guix---and so on:
+@item --do-not-upgrade[=@var{regexp} @dots{}]
+When used together with the @code{--upgrade} option, do @emph{not}
+upgrade any packages whose name matches a @var{regexp}. For example, to
+upgrade all packages in the current profile except those containing the
+substring ``emacs'':
@example
-$ guix package -p ~/.config/guix/current --roll-back
-switched from generation 3 to 2
-$ guix package -p ~/.config/guix/current --delete-generations=1
-deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
+$ guix package --upgrade . --do-not-upgrade emacs
@end example
-The @command{guix pull} command is usually invoked with no arguments,
-but it supports the following options:
-
-@table @code
-@item --url=@var{url}
-@itemx --commit=@var{commit}
-@itemx --branch=@var{branch}
-Download code from the specified @var{url}, at the given @var{commit} (a valid
-Git commit ID represented as a hexadecimal string), or @var{branch}.
+@item @anchor{profile-manifest}--manifest=@var{file}
+@itemx -m @var{file}
+@cindex profile declaration
+@cindex profile manifest
+Create a new generation of the profile from the manifest object
+returned by the Scheme code in @var{file}.
-@cindex @file{channels.scm}, configuration file
-@cindex configuration file for channels
-These options are provided for convenience, but you can also specify your
-configuration in the @file{~/.config/guix/channels.scm} file or using the
-@option{--channels} option (see below).
+This allows you to @emph{declare} the profile's contents rather than
+constructing it through a sequence of @code{--install} and similar
+commands. The advantage is that @var{file} can be put under version
+control, copied to different machines to reproduce the same profile, and
+so on.
-@item --channels=@var{file}
-@itemx -C @var{file}
-Read the list of channels from @var{file} instead of
-@file{~/.config/guix/channels.scm}. @var{file} must contain Scheme code that
-evaluates to a list of channel objects. @xref{Channels}, for more
-information.
+@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:
-@item --list-generations[=@var{pattern}]
-@itemx -l [@var{pattern}]
-List all the generations of @file{~/.config/guix/current} or, if @var{pattern}
-is provided, the subset of generations that match @var{pattern}.
-The syntax of @var{pattern} is the same as with @code{guix package
---list-generations} (@pxref{Invoking guix package}).
+@findex packages->manifest
+@example
+(use-package-modules guile emacs)
-@ref{Invoking guix describe}, for a way to display information about the
-current generation only.
+(packages->manifest
+ (list emacs
+ guile-2.0
+ ;; Use a specific package output.
+ (list guile-2.0 "debug")))
+@end example
-@item --profile=@var{profile}
-@itemx -p @var{profile}
-Use @var{profile} instead of @file{~/.config/guix/current}.
+@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:
-@item --dry-run
-@itemx -n
-Show which channel commit(s) would be used and what would be built or
-substituted but do not actually do it.
+@example
+(specifications->manifest
+ '("emacs" "guile@@2.2" "guile@@2.2:debug"))
+@end example
-@item --system=@var{system}
-@itemx -s @var{system}
-Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
-the system type of the build host.
+@item --roll-back
+@cindex rolling back
+@cindex undoing transactions
+@cindex transactions, undoing
+Roll back to the previous @dfn{generation} of the profile---i.e., undo
+the last transaction.
-@item --verbose
-Produce verbose output, writing build logs to the standard error output.
+When combined with options such as @code{--install}, roll back occurs
+before any other actions.
-@item --bootstrap
-Use the bootstrap Guile to build the latest Guix. This option is only
-useful to Guix developers.
-@end table
+When rolling back from the first generation that actually contains
+installed packages, the profile is made to point to the @dfn{zeroth
+generation}, which contains no files apart from its own metadata.
-The @dfn{channel} mechanism allows you to instruct @command{guix pull} which
-repository and branch to pull from, as well as @emph{additional} repositories
-containing package modules that should be deployed. @xref{Channels}, for more
-information.
+After having rolled back, installing, removing, or upgrading packages
+overwrites previous future generations. Thus, the history of the
+generations in a profile is always linear.
-In addition, @command{guix pull} supports all the common build options
-(@pxref{Common Build Options}).
+@item --switch-generation=@var{pattern}
+@itemx -S @var{pattern}
+@cindex generations
+Switch to a particular generation defined by @var{pattern}.
-@node Channels
-@section Channels
-
-@cindex channels
-@cindex @file{channels.scm}, configuration file
-@cindex configuration file for channels
-@cindex @command{guix pull}, configuration file
-@cindex configuration of @command{guix pull}
-Guix and its package collection are updated by running @command{guix pull}
-(@pxref{Invoking guix pull}). By default @command{guix pull} downloads and
-deploys Guix itself from the official GNU@tie{}Guix repository. This can be
-customized by defining @dfn{channels} in the
-@file{~/.config/guix/channels.scm} file. A channel specifies a URL and branch
-of a Git repository to be deployed, and @command{guix pull} can be instructed
-to pull from one or more channels. In other words, channels can be used to
-@emph{customize} and to @emph{extend} Guix, as we will see below.
+@var{pattern} may be either a generation number or a number prefixed
+with ``+'' or ``-''. The latter means: move forward/backward by a
+specified number of generations. For example, if you want to return to
+the latest generation after @code{--roll-back}, use
+@code{--switch-generation=+1}.
-@subsection Using a Custom Guix Channel
+The difference between @code{--roll-back} and
+@code{--switch-generation=-1} is that @code{--switch-generation} will
+not make a zeroth generation, so if a specified generation does not
+exist, the current generation will not be changed.
-The channel called @code{guix} specifies where Guix itself---its command-line
-tools as well as its package collection---should be downloaded. For instance,
-suppose you want to update from your own copy of the Guix repository at
-@code{example.org}, and specifically the @code{super-hacks} branch, you can
-write in @code{~/.config/guix/channels.scm} this specification:
+@item --search-paths[=@var{kind}]
+@cindex search paths
+Report environment variable definitions, in Bash syntax, that may be
+needed in order to use the set of installed packages. These environment
+variables are used to specify @dfn{search paths} for files used by some
+of the installed packages.
-@lisp
-;; Tell 'guix pull' to use my own repo.
-(list (channel
- (name 'guix)
- (url "https://example.org/my-guix.git")
- (branch "super-hacks")))
-@end lisp
+For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
+environment variables to be defined so it can look for headers and
+libraries in the user's profile (@pxref{Environment Variables,,, gcc,
+Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
+library are installed in the profile, then @code{--search-paths} will
+suggest setting these variables to @code{@var{profile}/include} and
+@code{@var{profile}/lib}, respectively.
-@noindent
-From there on, @command{guix pull} will fetch code from the @code{super-hacks}
-branch of the repository at @code{example.org}.
+The typical use case is to define these environment variables in the
+shell:
-@subsection Specifying Additional Channels
+@example
+$ eval `guix package --search-paths`
+@end example
-@cindex extending the package collection (channels)
-@cindex personal packages (channels)
-@cindex channels, for personal packages
-You can also specify @emph{additional channels} to pull from. Let's say you
-have a bunch of custom package variants or personal packages that you think
-would make little sense to contribute to the Guix project, but would like to
-have these packages transparently available to you at the command line. You
-would first write modules containing those package definitions (@pxref{Package
-Modules}), maintain them in a Git repository, and then you and anyone else can
-use it as an additional channel to get packages from. Neat, no?
+@var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
+meaning that the returned environment variable definitions will either
+be exact settings, or prefixes or suffixes of the current value of these
+variables. When omitted, @var{kind} defaults to @code{exact}.
-@c What follows stems from discussions at
-@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
-@c earlier discussions on guix-devel@gnu.org.
-@quotation Warning
-Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
-publish your personal channel to the world, we would like to share a few words
-of caution:
+This option can also be used to compute the @emph{combined} search paths
+of several profiles. Consider this example:
-@itemize
-@item
-Before publishing a channel, please consider contributing your package
-definitions to Guix proper (@pxref{Contributing}). Guix as a project is open
-to free software of all sorts, and packages in Guix proper are readily
-available to all Guix users and benefit from the project's quality assurance
-process.
+@example
+$ guix package -p foo -i guile
+$ guix package -p bar -i guile-json
+$ guix package -p foo -p bar --search-paths
+@end example
-@item
-When you maintain package definitions outside Guix, we, Guix developers,
-consider that @emph{the compatibility burden is on you}. Remember that
-package modules and package definitions are just Scheme code that uses various
-programming interfaces (APIs). We want to remain free to change these APIs to
-keep improving Guix, possibly in ways that break your channel. We never
-change APIs gratuitously, but we will @emph{not} commit to freezing APIs
-either.
+The last command above reports about the @code{GUILE_LOAD_PATH}
+variable, even though, taken individually, neither @file{foo} nor
+@file{bar} would lead to that recommendation.
-@item
-Corollary: if you're using an external channel and that channel breaks, please
-@emph{report the issue to the channel authors}, not to the Guix project.
-@end itemize
-You've been warned! Having said this, we believe external channels are a
-practical way to exert your freedom to augment Guix' package collection and to
-share your improvements, which are basic tenets of
-@uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please
-email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
-@end quotation
+@item --profile=@var{profile}
+@itemx -p @var{profile}
+Use @var{profile} instead of the user's default profile.
-Once you have a Git repository containing your own package modules, you can
-write @code{~/.config/guix/channels.scm} to instruct @command{guix pull} to
-pull from your personal channel @emph{in addition} to the default Guix
-channel(s):
+@cindex collisions, in a profile
+@cindex colliding packages in profiles
+@cindex profile collisions
+@item --allow-collisions
+Allow colliding packages in the new profile. Use at your own risk!
-@vindex %default-channels
-@lisp
-;; Add my personal packages to those Guix provides.
-(cons (channel
- (name 'my-personal-packages)
- (url "https://example.org/personal-packages.git"))
- %default-channels)
-@end lisp
+By default, @command{guix package} reports as an error @dfn{collisions}
+in the profile. Collisions happen when two or more different versions
+or variants of a given package end up in the profile.
-@noindent
-Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
-add a channel the list of channels that the variable @code{%default-channels}
-is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
-Manual}). With this file in place, @command{guix pull} builds not only Guix
-but also the package modules from your own repository. The result in
-@file{~/.config/guix/current} is the union of Guix with your own package
-modules:
+@item --bootstrap
+Use the bootstrap Guile to build the profile. This option is only
+useful to distribution developers.
-@example
-$ guix pull --list-generations
-@dots{}
-Generation 19 Aug 27 2018 16:20:48
- guix d894ab8
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: master
- commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
- my-personal-packages dd3df5e
- repository URL: https://example.org/personal-packages.git
- branch: master
- commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
- 11 new packages: my-gimp, my-emacs-with-cool-features, @dots{}
- 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
-@end example
+@end table
-@noindent
-The output of @command{guix pull} above shows that Generation@tie{}19 includes
-both Guix and packages from the @code{my-personal-packages} channel. Among
-the new and upgraded packages that are listed, some like @code{my-gimp} and
-@code{my-emacs-with-cool-features} might come from
-@code{my-personal-packages}, while others come from the Guix default channel.
+In addition to these actions, @command{guix package} supports the
+following options to query the current state of a profile, or the
+availability of packages:
-@cindex dependencies, channels
-@cindex meta-data, channels
-@subsection Declaring Channel Dependencies
+@table @option
-Channel authors may decide to augment a package collection provided by other
-channels. They can declare their channel to be dependent on other channels in
-a meta-data file @file{.guix-channel}, which is to be placed in the root of
-the channel repository.
+@item --search=@var{regexp}
+@itemx -s @var{regexp}
+@cindex searching for packages
+List the available packages whose name, synopsis, or description matches
+@var{regexp} (in a case-insensitive fashion), sorted by relevance.
+Print all the metadata of matching packages in
+@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
+GNU recutils manual}).
-The meta-data file should contain a simple S-expression like this:
+This allows specific fields to be extracted using the @command{recsel}
+command, for instance:
-@lisp
-(channel
- (version 0)
- (dependencies
- (channel
- (name some-collection)
- (url "https://example.org/first-collection.git"))
- (channel
- (name some-other-collection)
- (url "https://example.org/second-collection.git")
- (branch "testing"))))
-@end lisp
+@example
+$ guix package -s malloc | recsel -p name,version,relevance
+name: jemalloc
+version: 4.5.0
+relevance: 6
-In the above example this channel is declared to depend on two other channels,
-which will both be fetched automatically. The modules provided by the channel
-will be compiled in an environment where the modules of all these declared
-channels are available.
+name: glibc
+version: 2.25
+relevance: 1
-For the sake of reliability and maintainability, you should avoid dependencies
-on channels that you don't control, and you should aim to keep the number of
-dependencies to a minimum.
+name: libgc
+version: 7.6.0
+relevance: 1
+@end example
-@subsection Replicating Guix
+Similarly, to show the name of all the packages available under the
+terms of the GNU@tie{}LGPL version 3:
-@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:
+@example
+$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
+name: elfutils
-@lisp
-;; Deploy specific commits of my channels of interest.
-(list (channel
- (name 'guix)
- (url "https://git.savannah.gnu.org/git/guix.git")
- (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300"))
- (channel
- (name 'my-personal-packages)
- (url "https://example.org/personal-packages.git")
- (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
-@end lisp
+name: gmp
+@dots{}
+@end example
-The @command{guix describe --format=channels} command can even generate this
-list of channels directly (@pxref{Invoking guix describe}).
+It is also possible to refine search results using several @code{-s}
+flags. For example, the following command returns a list of board
+games:
-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.
-
-This gives you super powers, allowing you to track the provenance of binary
-artifacts with very fine grain, and to reproduce software environments at
-will---some sort of ``meta reproducibility'' capabilities, if you will.
-@xref{Inferiors}, for another way to take advantage of these super powers.
+@example
+$ guix package -s '\<board\>' -s game | recsel -p name
+name: gnubg
+@dots{}
+@end example
-@node Inferiors
-@section Inferiors
+If we were to omit @code{-s game}, we would also get software packages
+that deal with printed circuit boards; removing the angle brackets
+around @code{board} would further add packages that have to do with
+keyboards.
-@c TODO: Remove this once we're more confident about API stability.
-@quotation Note
-The functionality described here is a ``technology preview'' as of version
-@value{VERSION}. As such, the interface is subject to change.
-@end quotation
+And now for a more elaborate example. The following command searches
+for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
+libraries, and prints the name and synopsis of the matching packages:
-@cindex inferiors
-@cindex composition of Guix revisions
-Sometimes you might need to mix packages from the revision of Guix you're
-currently running with packages available in a different revision of Guix.
-Guix @dfn{inferiors} allow you to achieve that by composing different Guix
-revisions in arbitrary ways.
+@example
+$ guix package -s crypto -s library | \
+ recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
+@end example
-@cindex inferior packages
-Technically, an ``inferior'' is essentially a separate Guix process connected
-to your main Guix process through a REPL (@pxref{Invoking guix repl}). The
-@code{(guix inferior)} module allows you to create inferiors and to
-communicate with them. It also provides a high-level interface to browse and
-manipulate the packages that an inferior provides---@dfn{inferior packages}.
+@noindent
+@xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
+information on @dfn{selection expressions} for @code{recsel -e}.
-When combined with channels (@pxref{Channels}), inferiors provide a simple way
-to interact with a separate revision of Guix. For example, let's assume you
-want to install in your profile the current @code{guile} package, along with
-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
-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:
+@item --show=@var{package}
+Show details about @var{package}, taken from the list of available packages, in
+@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
+recutils manual}).
-@lisp
-(use-modules (guix inferior) (guix channels)
- (srfi srfi-1)) ;for 'first'
+@example
+$ guix package --show=python | recsel -p name,version
+name: python
+version: 2.7.6
-(define channels
- ;; This is the old revision from which we want to
- ;; extract guile-json.
- (list (channel
- (name 'guix)
- (url "https://git.savannah.gnu.org/git/guix.git")
- (commit
- "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))
+name: python
+version: 3.3.5
+@end example
-(define inferior
- ;; An inferior representing the above revision.
- (inferior-for-channels channels))
+You may also specify the full name of a package to only get details about a
+specific version of it:
+@example
+$ guix package --show=python@@3.4 | recsel -p name,version
+name: python
+version: 3.4.3
+@end example
-;; Now create a manifest with the current "guile" package
-;; and the old "guile-json" package.
-(packages->manifest
- (list (first (lookup-inferior-packages inferior "guile-json"))
- (specification->package "guile")))
-@end lisp
-On its first run, @command{guix package --manifest} might have to build the
-channel you specified before it can create the inferior; subsequent runs will
-be much faster because the Guix revision will be cached.
-The @code{(guix inferior)} module provides the following procedures to open an
-inferior:
+@item --list-installed[=@var{regexp}]
+@itemx -I [@var{regexp}]
+List the currently installed packages in the specified profile, with the
+most recently installed packages shown last. When @var{regexp} is
+specified, list only installed packages whose name matches @var{regexp}.
-@deffn {Scheme Procedure} inferior-for-channels @var{channels} @
- [#:cache-directory] [#:ttl]
-Return an inferior for @var{channels}, a list of channels. Use the cache at
-@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
-This procedure opens a new connection to the build daemon.
+For each installed package, print the following items, separated by
+tabs: the package name, its version string, the part of the package that
+is installed (for instance, @code{out} for the default output,
+@code{include} for its headers, etc.), and the path of this package in
+the store.
-As a side effect, this procedure may build or substitute binaries for
-@var{channels}, which can take time.
-@end deffn
+@item --list-available[=@var{regexp}]
+@itemx -A [@var{regexp}]
+List packages currently available in the distribution for this system
+(@pxref{GNU Distribution}). When @var{regexp} is specified, list only
+installed packages whose name matches @var{regexp}.
-@deffn {Scheme Procedure} open-inferior @var{directory} @
- [#:command "bin/guix"]
-Open the inferior Guix in @var{directory}, running
-@code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if
-the inferior could not be launched.
-@end deffn
+For each package, print the following items separated by tabs: its name,
+its version string, the parts of the package (@pxref{Packages with
+Multiple Outputs}), and the source location of its definition.
-@cindex inferior packages
-The procedures listed below allow you to obtain and manipulate inferior
-packages.
+@item --list-generations[=@var{pattern}]
+@itemx -l [@var{pattern}]
+@cindex generations
+Return a list of generations along with their creation dates; for each
+generation, show the installed packages, with the most recently
+installed packages shown last. Note that the zeroth generation is never
+shown.
-@deffn {Scheme Procedure} inferior-packages @var{inferior}
-Return the list of packages known to @var{inferior}.
-@end deffn
+For each installed package, print the following items, separated by
+tabs: the name of a package, its version string, the part of the package
+that is installed (@pxref{Packages with Multiple Outputs}), and the
+location of this package in the store.
-@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
- [@var{version}]
-Return the sorted list of inferior packages matching @var{name} in
-@var{inferior}, with highest version numbers first. If @var{version} is true,
-return only packages with a version number prefixed by @var{version}.
-@end deffn
+When @var{pattern} is used, the command returns only matching
+generations. Valid patterns include:
-@deffn {Scheme Procedure} inferior-package? @var{obj}
-Return true if @var{obj} is an inferior package.
-@end deffn
+@itemize
+@item @emph{Integers and comma-separated integers}. Both patterns denote
+generation numbers. For instance, @code{--list-generations=1} returns
+the first one.
-@deffn {Scheme Procedure} inferior-package-name @var{package}
-@deffnx {Scheme Procedure} inferior-package-version @var{package}
-@deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
-@deffnx {Scheme Procedure} inferior-package-description @var{package}
-@deffnx {Scheme Procedure} inferior-package-home-page @var{package}
-@deffnx {Scheme Procedure} inferior-package-location @var{package}
-@deffnx {Scheme Procedure} inferior-package-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
-@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
-@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
-@deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
-These procedures are the counterpart of package record accessors
-(@pxref{package Reference}). Most of them work by querying the inferior
-@var{package} comes from, so the inferior must still be live when you call
-these procedures.
-@end deffn
+And @code{--list-generations=1,8,2} outputs three generations in the
+specified order. Neither spaces nor trailing commas are allowed.
-Inferior packages can be used transparently like any other package or
-file-like object in G-expressions (@pxref{G-Expressions}). They are also
-transparently handled by the @code{packages->manifest} procedure, which is
-commonly use in manifests (@pxref{Invoking guix package, the
-@option{--manifest} option of @command{guix package}}). Thus you can insert
-an inferior package pretty much anywhere you would insert a regular package:
-in manifests, in the @code{packages} field of your @code{operating-system}
-declaration, and so on.
+@item @emph{Ranges}. @code{--list-generations=2..9} prints the
+specified generations and everything in between. Note that the start of
+a range must be smaller than its end.
-@node Invoking guix describe
-@section Invoking @command{guix describe}
+It is also possible to omit the endpoint. For example,
+@code{--list-generations=2..}, returns all generations starting from the
+second one.
-@cindex reproducibility
-@cindex replicating Guix
-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
-machine or user account, if you want to report a bug or to determine what
-change in the channels you are using caused it, or if you want to record your
-system state for reproducibility purposes. The @command{guix describe}
-command answers these questions.
+@item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
+or months by passing an integer along with the first letter of the
+duration. For example, @code{--list-generations=20d} lists generations
+that are up to 20 days old.
+@end itemize
-When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
-displays the channel(s) that it was built from, including their repository URL
-and commit IDs (@pxref{Channels}):
+@item --delete-generations[=@var{pattern}]
+@itemx -d [@var{pattern}]
+When @var{pattern} is omitted, delete all generations except the current
+one.
-@example
-$ guix describe
-Generation 10 Sep 03 2018 17:32:44 (current)
- guix e0fa68c
- repository URL: https://git.savannah.gnu.org/git/guix.git
- branch: master
- commit: e0fa68c7718fffd33d81af415279d6ddb518f727
-@end example
+This command accepts the same patterns as @option{--list-generations}.
+When @var{pattern} is specified, delete the matching generations. When
+@var{pattern} specifies a duration, generations @emph{older} than the
+specified duration match. For instance, @code{--delete-generations=1m}
+deletes generations that are more than one month old.
-If you're familiar with the Git version control system, this is similar in
-spirit to @command{git describe}; the output is also similar to that of
-@command{guix pull --list-generations}, but limited to the current generation
-(@pxref{Invoking guix pull, the @option{--list-generations} option}). Because
-the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
-information is all it takes to describe the revision of Guix you're using, and
-also to replicate it.
+If the current generation matches, it is @emph{not} deleted. Also, the
+zeroth generation is never deleted.
-To make it easier to replicate Guix, @command{guix describe} can also be asked
-to return a list of channels instead of the human-readable description above:
+Note that deleting generations prevents rolling back to them.
+Consequently, this command must be used with care.
-@example
-$ guix describe -f channels
-(list (channel
- (name 'guix)
- (url "https://git.savannah.gnu.org/git/guix.git")
- (commit
- "e0fa68c7718fffd33d81af415279d6ddb518f727")))
-@end example
+@end table
-@noindent
-You can save this to a file and feed it to @command{guix pull -C} on some
-other machine or at a later point in time, which will instantiate @emph{this
-exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
-From there on, since you're able to deploy the same revision of Guix, you can
-just as well @emph{replicate a complete software environment}. We humbly
-think that this is @emph{awesome}, and we hope you'll like it too!
-
-The details of the options supported by @command{guix describe} are as
-follows:
+Finally, since @command{guix package} may actually start build
+processes, it supports all the common build options (@pxref{Common Build
+Options}). It also supports package transformation options, such as
+@option{--with-source} (@pxref{Package Transformation Options}).
+However, note that package transformations are lost when upgrading; to
+preserve transformations across upgrades, you should define your own
+package variant in a Guile module and add it to @code{GUIX_PACKAGE_PATH}
+(@pxref{Defining Packages}).
-@table @code
-@item --format=@var{format}
-@itemx -f @var{format}
-Produce output in the specified @var{format}, one of:
+@node Substitutes
+@section Substitutes
-@table @code
-@item human
-produce human-readable output;
-@item channels
-produce a list of channel specifications that can be passed to @command{guix
-pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
-guix pull});
-@item json
-@cindex JSON
-produce a list of channel specifications in JSON format;
-@item recutils
-produce a list of channel specifications in Recutils format.
-@end table
+@cindex substitutes
+@cindex pre-built binaries
+Guix supports transparent source/binary deployment, which means that it
+can either build things locally, or download pre-built items from a
+server, or both. We call these pre-built items @dfn{substitutes}---they
+are substitutes for local build results. In many cases, downloading a
+substitute is much faster than building things locally.
-@item --profile=@var{profile}
-@itemx -p @var{profile}
-Display information about @var{profile}.
-@end table
+Substitutes can be anything resulting from a derivation build
+(@pxref{Derivations}). Of course, in the common case, they are
+pre-built package binaries, but source tarballs, for instance, which
+also result from derivation builds, can be available as substitutes.
-@node Invoking guix pack
-@section Invoking @command{guix pack}
+@menu
+* Official Substitute Server:: One particular source of substitutes.
+* Substitute Server Authorization:: How to enable or disable substitutes.
+* Substitute Authentication:: How Guix verifies substitutes.
+* Proxy Settings:: How to get substitutes via proxy.
+* Substitution Failure:: What happens when substitution fails.
+* On Trusting Binaries:: How can you trust that binary blob?
+@end menu
-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
-is where @command{guix pack} comes in.
+@node Official Substitute Server
+@subsection Official Substitute Server
-@quotation Note
-If you are looking for ways to exchange binaries among machines that
-already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix
-publish}, and @ref{Invoking guix archive}.
-@end quotation
+@cindex hydra
+@cindex build farm
+The @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an official build farm
+that builds packages from Guix continuously for some
+architectures, and makes them available as substitutes. This is the
+default source of substitutes; it can be overridden by passing the
+@option{--substitute-urls} option either to @command{guix-daemon}
+(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
+or to client tools such as @command{guix package}
+(@pxref{client-substitute-urls,, client @option{--substitute-urls}
+option}).
-@cindex pack
-@cindex bundle
-@cindex application bundle
-@cindex software bundle
-The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or
-@dfn{software bundle}: it creates a tarball or some other archive
-containing the binaries of the software you're interested in, and all
-its dependencies. The resulting archive can be used on any machine that
-does not have Guix, and people can run the exact same binaries as those
-you have with Guix. The pack itself is created in a bit-reproducible
-fashion, so anyone can verify that it really contains the build results
-that you pretend to be shipping.
+Substitute URLs can be either HTTP or HTTPS.
+HTTPS is recommended because communications are encrypted; conversely,
+using HTTP makes all communications visible to an eavesdropper, who
+could use the information gathered to determine, for instance, whether
+your system has unpatched security vulnerabilities.
-For example, to create a bundle containing Guile, Emacs, Geiser, and all
-their dependencies, you can run:
+Substitutes from the official build farm are enabled by default when
+using the Guix System Distribution (@pxref{GNU Distribution}). However,
+they are disabled by default when using Guix on a foreign distribution,
+unless you have explicitly enabled them via one of the recommended
+installation steps (@pxref{Installation}). The following paragraphs
+describe how to enable or disable substitutes for the official build
+farm; the same procedure can also be used to enable substitutes for any
+other substitute server.
-@example
-$ guix pack guile emacs geiser
-@dots{}
-/gnu/store/@dots{}-pack.tar.gz
-@end example
+@node Substitute Server Authorization
+@subsection Substitute Server Authorization
-The result here is a tarball containing a @file{/gnu/store} directory
-with all the relevant packages. The resulting tarball contains a
-@dfn{profile} with the three packages of interest; the profile is the
-same as would be created by @command{guix package -i}. It is this
-mechanism that is used to create Guix's own standalone binary tarball
-(@pxref{Binary Installation}).
+@cindex security
+@cindex substitutes, authorization thereof
+@cindex access control list (ACL), for substitutes
+@cindex ACL (access control list), for substitutes
+To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER}} or a
+mirror thereof, you
+must add its public key to the access control list (ACL) of archive
+imports, using the @command{guix archive} command (@pxref{Invoking guix
+archive}). Doing so implies that you trust @code{@value{SUBSTITUTE-SERVER}} to not
+be compromised and to serve genuine substitutes.
-Users of this pack would have to run
-@file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may
-find inconvenient. To work around it, you can create, say, a
-@file{/opt/gnu/bin} symlink to the profile:
+The public key for @code{@value{SUBSTITUTE-SERVER}} is installed along with Guix, in
+@code{@var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, where @var{prefix} is
+the installation prefix of Guix. If you installed Guix from source,
+make sure you checked the GPG signature of
+@file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
+Then, you can run something like this:
@example
-guix pack -S /opt/gnu/bin=bin guile emacs geiser
+# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub
@end example
-@noindent
-That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
-
-@cindex relocatable binaries, with @command{guix pack}
-What if the recipient of your pack does not have root privileges on
-their machine, and thus cannot unpack it in the root file system? In
-that case, you will want to use the @code{--relocatable} option (see
-below). This option produces @dfn{relocatable binaries}, meaning they
-they can be placed anywhere in the file system hierarchy: in the example
-above, users can unpack your tarball in their home directory and
-directly run @file{./opt/gnu/bin/guile}.
+@quotation Note
+Similarly, the @file{hydra.gnu.org.pub} file contains the public key
+of an independent build farm also run by the project, reachable at
+@indicateurl{https://mirror.hydra.gnu.org}.
+@end quotation
-@cindex Docker, build an image with guix pack
-Alternatively, you can produce a pack in the Docker image format using
-the following command:
+Once this is in place, the output of a command like @code{guix build}
+should change from something like:
@example
-guix pack -f docker guile emacs geiser
+$ guix build emacs --dry-run
+The following derivations would be built:
+ /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
+ /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
+ /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
+ /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
+@dots{}
@end example
@noindent
-The result is a tarball that can be passed to the @command{docker load}
-command. See the
-@uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
-documentation} for more information.
-
-@cindex Singularity, build an image with guix pack
-@cindex SquashFS, build an image with guix pack
-Yet another option is to produce a SquashFS image with the following
-command:
+to something like:
@example
-guix pack -f squashfs guile emacs geiser
+$ guix build emacs --dry-run
+112.3 MB would be downloaded:
+ /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
+ /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
+ /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
+ /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
+@dots{}
@end example
@noindent
-The result is a SquashFS file system image that can either be mounted or
-directly be used as a file system container image with the
-@uref{http://singularity.lbl.gov, Singularity container execution
-environment}, using commands like @command{singularity shell} or
-@command{singularity exec}.
-
-Several command-line options allow you to customize your pack:
-
-@table @code
-@item --format=@var{format}
-@itemx -f @var{format}
-Produce a pack in the given @var{format}.
-
-The available formats are:
+This indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} are usable and
+will be downloaded, when possible, for future builds.
-@table @code
-@item tarball
-This is the default format. It produces a tarball containing all the
-specified binaries and symlinks.
+@cindex substitutes, how to disable
+The substitute mechanism can be disabled globally by running
+@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
+guix-daemon}). It can also be disabled temporarily by passing the
+@code{--no-substitutes} option to @command{guix package}, @command{guix
+build}, and other command-line tools.
-@item docker
-This produces a tarball that follows the
-@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
-Docker Image Specification}.
+@node Substitute Authentication
+@subsection Substitute Authentication
-@item squashfs
-This produces a SquashFS image containing all the specified binaries and
-symlinks, as well as empty mount points for virtual file systems like
-procfs.
-@end table
+@cindex digital signatures
+Guix detects and raises an error when attempting to use a substitute
+that has been tampered with. Likewise, it ignores substitutes that are
+not signed, or that are not signed by one of the keys listed in the ACL.
-@item --relocatable
-@itemx -R
-Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
-anywhere in the file system hierarchy and run from there. For example,
-if you create a pack containing Bash with:
+There is one exception though: if an unauthorized server provides
+substitutes that are @emph{bit-for-bit identical} to those provided by
+an authorized server, then the unauthorized server becomes eligible for
+downloads. For example, assume we have chosen two substitute servers
+with this option:
@example
-guix pack -R -S /mybin=bin bash
+--substitute-urls="https://a.example.org https://b.example.org"
@end example
@noindent
-...@: you can copy that pack to a machine that lacks Guix, and from your
-home directory as a normal user, run:
-
-@example
-tar xf pack.tar.gz
-./mybin/sh
-@end example
+@cindex reproducible builds
+If the ACL contains only the key for @code{b.example.org}, and if
+@code{a.example.org} happens to serve the @emph{exact same} substitutes,
+then Guix will download substitutes from @code{a.example.org} because it
+comes first in the list and can be considered a mirror of
+@code{b.example.org}. In practice, independent build machines usually
+produce the same binaries, thanks to bit-reproducible builds (see
+below).
-@noindent
-In that shell, if you type @code{ls /gnu/store}, you'll notice that
-@file{/gnu/store} shows up and contains all the dependencies of
-@code{bash}, even though the machine actually lacks @file{/gnu/store}
-altogether! That is probably the simplest way to deploy Guix-built
-software on a non-Guix machine.
-
-There's a gotcha though: this technique relies on the @dfn{user
-namespace} feature of the kernel Linux, which allows unprivileged users
-to mount or change root. Old versions of Linux did not support it, and
-some GNU/Linux distributions turn it off; on these systems, programs
-from the pack @emph{will fail to run}, unless they are unpacked in the
-root file system.
+When using HTTPS, the server's X.509 certificate is @emph{not} validated
+(in other words, the server is not authenticated), contrary to what
+HTTPS clients such as Web browsers usually do. This is because Guix
+authenticates substitute information itself, as explained above, which
+is what we care about (whereas X.509 certificates are about
+authenticating bindings between domain names and public keys.)
-@item --expression=@var{expr}
-@itemx -e @var{expr}
-Consider the package @var{expr} evaluates to.
+@node Proxy Settings
+@subsection Proxy Settings
-This has the same purpose as the same-named option in @command{guix
-build} (@pxref{Additional Build Options, @code{--expression} in
-@command{guix build}}).
+@vindex http_proxy
+Substitutes are downloaded over HTTP or HTTPS.
+The @code{http_proxy} environment
+variable can be set in the environment of @command{guix-daemon} and is
+honored for downloads of substitutes. Note that the value of
+@code{http_proxy} in the environment where @command{guix build},
+@command{guix package}, and other client commands are run has
+@emph{absolutely no effect}.
-@item --manifest=@var{file}
-@itemx -m @var{file}
-Use the packages contained in the manifest object returned by the Scheme
-code in @var{file}.
+@node Substitution Failure
+@subsection Substitution Failure
-This has a similar purpose as the same-named option in @command{guix
-package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
-same manifest files. It allows you to define a collection of packages
-once and use it both for creating profiles and for creating archives
-for use on machines that do not have Guix installed. Note that you can
-specify @emph{either} a manifest file @emph{or} a list of packages,
-but not both.
+Even when a substitute for a derivation is available, sometimes the
+substitution attempt will fail. This can happen for a variety of
+reasons: the substitute server might be offline, the substitute may
+recently have been deleted, the connection might have been interrupted,
+etc.
-@item --system=@var{system}
-@itemx -s @var{system}
-Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
-the system type of the build host.
+When substitutes are enabled and a substitute for a derivation is
+available, but the substitution attempt fails, Guix will attempt to
+build the derivation locally depending on whether or not
+@code{--fallback} was given (@pxref{fallback-option,, common build
+option @code{--fallback}}). Specifically, if @code{--fallback} was
+omitted, then no local build will be performed, and the derivation is
+considered to have failed. However, if @code{--fallback} was given,
+then Guix will attempt to build the derivation locally, and the success
+or failure of the derivation depends on the success or failure of the
+local build. Note that when substitutes are disabled or no substitute
+is available for the derivation in question, a local build will
+@emph{always} be performed, regardless of whether or not
+@code{--fallback} was given.
-@item --target=@var{triplet}
-@cindex cross-compilation
-Cross-build for @var{triplet}, which must be a valid GNU triplet, such
-as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
-configuration triplets,, autoconf, Autoconf}).
+To get an idea of how many substitutes are available right now, you can
+try running the @command{guix weather} command (@pxref{Invoking guix
+weather}). This command provides statistics on the substitutes provided
+by a server.
-@item --compression=@var{tool}
-@itemx -C @var{tool}
-Compress the resulting tarball using @var{tool}---one of @code{gzip},
-@code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no compression.
+@node On Trusting Binaries
+@subsection On Trusting Binaries
-@item --symlink=@var{spec}
-@itemx -S @var{spec}
-Add the symlinks specified by @var{spec} to the pack. This option can
-appear several times.
+@cindex trust, of pre-built binaries
+Today, each individual's control over their own computing is at the
+mercy of institutions, corporations, and groups with enough power and
+determination to subvert the computing infrastructure and exploit its
+weaknesses. While using @code{@value{SUBSTITUTE-SERVER}} substitutes can be
+convenient, we encourage users to also build on their own, or even run
+their own build farm, such that @code{@value{SUBSTITUTE-SERVER}} is less of an
+interesting target. One way to help is by publishing the software you
+build using @command{guix publish} so that others have one more choice
+of server to download substitutes from (@pxref{Invoking guix publish}).
-@var{spec} has the form @code{@var{source}=@var{target}}, where
-@var{source} is the symlink that will be created and @var{target} is the
-symlink target.
+Guix has the foundations to maximize build reproducibility
+(@pxref{Features}). In most cases, independent builds of a given
+package or derivation should yield bit-identical results. Thus, through
+a diverse set of independent package builds, we can strengthen the
+integrity of our systems. The @command{guix challenge} command aims to
+help users assess substitute servers, and to assist developers in
+finding out about non-deterministic package builds (@pxref{Invoking guix
+challenge}). Similarly, the @option{--check} option of @command{guix
+build} allows users to check whether previously-installed substitutes
+are genuine by rebuilding them locally (@pxref{build-check,
+@command{guix build --check}}).
-For instance, @code{-S /opt/gnu/bin=bin} creates a @file{/opt/gnu/bin}
-symlink pointing to the @file{bin} sub-directory of the profile.
+In the future, we want Guix to have support to publish and retrieve
+binaries to/from other users, in a peer-to-peer fashion. If you would
+like to discuss this project, join us on @email{guix-devel@@gnu.org}.
-@item --localstatedir
-@itemx --profile-name=@var{name}
-Include the ``local state directory'', @file{/var/guix}, in the resulting
-pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}}
-profile---by default @var{name} is @code{guix-profile}, which corresponds to
-@file{~root/.guix-profile}.
+@node Packages with Multiple Outputs
+@section Packages with Multiple Outputs
-@file{/var/guix} contains the store database (@pxref{The Store}) as well
-as garbage-collector roots (@pxref{Invoking guix gc}). Providing it in
-the pack means that the store is ``complete'' and manageable by Guix;
-not providing it pack means that the store is ``dead'': items cannot be
-added to it or removed from it after extraction of the pack.
+@cindex multiple-output packages
+@cindex package outputs
+@cindex outputs
-One use case for this is the Guix self-contained binary tarball
-(@pxref{Binary Installation}).
+Often, packages defined in Guix have a single @dfn{output}---i.e., the
+source package leads to exactly one directory in the store. When running
+@command{guix package -i glibc}, one installs the default output of the
+GNU libc package; the default output is called @code{out}, but its name
+can be omitted as shown in this command. In this particular case, the
+default output of @code{glibc} contains all the C header files, shared
+libraries, static libraries, Info documentation, and other supporting
+files.
-@item --bootstrap
-Use the bootstrap binaries to build the pack. This option is only
-useful to Guix developers.
-@end table
+Sometimes it is more appropriate to separate the various types of files
+produced from a single source package into separate outputs. For
+instance, the GLib C library (used by GTK+ and related packages)
+installs more than 20 MiB of reference documentation as HTML pages.
+To save space for users who do not need it, the documentation goes to a
+separate output, called @code{doc}. To install the main GLib output,
+which contains everything but the documentation, one would run:
-In addition, @command{guix pack} supports all the common build options
-(@pxref{Common Build Options}) and all the package transformation
-options (@pxref{Package Transformation Options}).
+@example
+guix package -i glib
+@end example
+@cindex documentation
+The command to install its documentation is:
-@node Invoking guix archive
-@section Invoking @command{guix archive}
+@example
+guix package -i glib:doc
+@end example
-@cindex @command{guix archive}
-@cindex archive
-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.
-In particular, it allows store files to be transferred from one machine
-to the store on another machine.
+Some packages install programs with different ``dependency footprints''.
+For instance, the WordNet package installs both command-line tools and
+graphical user interfaces (GUIs). The former depend solely on the C
+library, whereas the latter depend on Tcl/Tk and the underlying X
+libraries. In this case, we leave the command-line tools in the default
+output, whereas the GUIs are in a separate output. This allows users
+who do not need the GUIs to save space. The @command{guix size} command
+can help find out about such situations (@pxref{Invoking guix size}).
+@command{guix graph} can also be helpful (@pxref{Invoking guix graph}).
-@quotation Note
-If you're looking for a way to produce archives in a format suitable for
-tools other than Guix, @pxref{Invoking guix pack}.
-@end quotation
+There are several such multiple-output packages in the GNU distribution.
+Other conventional output names include @code{lib} for libraries and
+possibly header files, @code{bin} for stand-alone programs, and
+@code{debug} for debugging information (@pxref{Installing Debugging
+Files}). The outputs of a packages are listed in the third column of
+the output of @command{guix package --list-available} (@pxref{Invoking
+guix package}).
-@cindex exporting store items
-To export store files as an archive to standard output, run:
-@example
-guix archive --export @var{options} @var{specifications}...
-@end example
+@node Invoking guix gc
+@section Invoking @command{guix gc}
-@var{specifications} may be either store file names or package
-specifications, as for @command{guix package} (@pxref{Invoking guix
-package}). For instance, the following command creates an archive
-containing the @code{gui} output of the @code{git} package and the main
-output of @code{emacs}:
+@cindex garbage collector
+@cindex disk space
+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
+the @emph{only} way to remove files from @file{/gnu/store}---removing
+files or directories manually may break it beyond repair!
-@example
-guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
-@end example
+@cindex GC roots
+@cindex garbage collector roots
+The garbage collector has a set of known @dfn{roots}: any file under
+@file{/gnu/store} reachable from a root is considered @dfn{live} and
+cannot be deleted; any other file is considered @dfn{dead} and may be
+deleted. The set of garbage collector roots (``GC roots'' for short)
+includes default user profiles; by default, the symlinks under
+@file{/var/guix/gcroots} represent these GC roots. New GC roots can be
+added with @command{guix build --root}, for example (@pxref{Invoking
+guix build}).
-If the specified packages are not built yet, @command{guix archive}
-automatically builds them. The build process may be controlled with the
-common build options (@pxref{Common Build Options}).
+Prior to running @code{guix gc --collect-garbage} to make space, it is
+often useful to remove old generations from user profiles; that way, old
+package builds referenced by those generations can be reclaimed. This
+is achieved by running @code{guix package --delete-generations}
+(@pxref{Invoking guix package}).
-To transfer the @code{emacs} package to a machine connected over SSH,
-one would run:
+Our recommendation is to run a garbage collection periodically, or when
+you are short on disk space. For instance, to guarantee that at least
+5@tie{}GB are available on your disk, simply run:
@example
-guix archive --export -r emacs | ssh the-machine guix archive --import
+guix gc -F 5G
@end example
-@noindent
-Similarly, a complete user profile may be transferred from one machine
-to another like this:
+It is perfectly safe to run as a non-interactive periodic job
+(@pxref{Scheduled Job Execution}, for how to set up such a job).
+Running @command{guix gc} with no arguments will collect as
+much garbage as it can, but that is often inconvenient: you may find
+yourself having to rebuild or re-download software that is ``dead'' from
+the GC viewpoint but that is necessary to build other pieces of
+software---e.g., the compiler tool chain.
-@example
-guix archive --export -r $(readlink -f ~/.guix-profile) | \
- ssh the-machine guix-archive --import
-@end example
-
-@noindent
-However, note that, in both examples, all of @code{emacs} and the
-profile as well as all of their dependencies are transferred (due to
-@code{-r}), regardless of what is already available in the store on the
-target machine. The @code{--missing} option can help figure out which
-items are missing from the target store. The @command{guix copy}
-command simplifies and optimizes this whole process, so this is probably
-what you should use in this case (@pxref{Invoking guix copy}).
-
-@cindex nar, archive format
-@cindex normalized archive (nar)
-Archives are stored in the ``normalized archive'' or ``nar'' format, which is
-comparable in spirit to `tar', but with differences
-that make it more appropriate for our purposes. First, rather than
-recording all Unix metadata for each file, the nar format only mentions
-the file type (regular, directory, or symbolic link); Unix permissions
-and owner/group are dismissed. Second, the order in which directory
-entries are stored always follows the order of file names according to
-the C locale collation order. This makes archive production fully
-deterministic.
-
-When exporting, the daemon digitally signs the contents of the archive,
-and that digital signature is appended. When importing, the daemon
-verifies the signature and rejects the import in case of an invalid
-signature or if the signing key is not authorized.
-@c FIXME: Add xref to daemon doc about signatures.
-
-The main options are:
+The @command{guix gc} command has three modes of operation: it can be
+used to garbage-collect any dead files (the default), to delete specific
+files (the @code{--delete} option), to print garbage-collector
+information, or for more advanced queries. The garbage collection
+options are as follows:
@table @code
-@item --export
-Export the specified store files or packages (see below.) Write the
-resulting archive to the standard output.
-
-Dependencies are @emph{not} included in the output, unless
-@code{--recursive} is passed.
-
-@item -r
-@itemx --recursive
-When combined with @code{--export}, this instructs @command{guix
-archive} to include dependencies of the given items in the archive.
-Thus, the resulting archive is self-contained: it contains the closure
-of the exported store items.
+@item --collect-garbage[=@var{min}]
+@itemx -C [@var{min}]
+Collect garbage---i.e., unreachable @file{/gnu/store} files and
+sub-directories. This is the default operation when no option is
+specified.
-@item --import
-Read an archive from the standard input, and import the files listed
-therein into the store. Abort if the archive has an invalid digital
-signature, or if it is signed by a public key not among the authorized
-keys (see @code{--authorize} below.)
+When @var{min} is given, stop once @var{min} bytes have been collected.
+@var{min} may be a number of bytes, or it may include a unit as a
+suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
+(@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
-@item --missing
-Read a list of store file names from the standard input, one per line,
-and write on the standard output the subset of these files missing from
-the store.
+When @var{min} is omitted, collect all the garbage.
-@item --generate-key[=@var{parameters}]
-@cindex signing, archives
-Generate a new key pair for the daemon. This is a prerequisite before
-archives can be exported with @code{--export}. Note that this operation
-usually takes time, because it needs to gather enough entropy to
-generate the key pair.
+@item --free-space=@var{free}
+@itemx -F @var{free}
+Collect garbage until @var{free} space is available under
+@file{/gnu/store}, if possible; @var{free} denotes storage space, such
+as @code{500MiB}, as described above.
-The generated key pair is typically stored under @file{/etc/guix}, in
-@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
-key, which must be kept secret.) When @var{parameters} is omitted,
-an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
-versions before 1.6.0, it is a 4096-bit RSA key.
-Alternatively, @var{parameters} can specify
-@code{genkey} parameters suitable for Libgcrypt (@pxref{General
-public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
-Libgcrypt Reference Manual}).
+When @var{free} or more is already available in @file{/gnu/store}, do
+nothing and exit immediately.
-@item --authorize
-@cindex authorizing, archives
-Authorize imports signed by the public key passed on standard input.
-The public key must be in ``s-expression advanced format''---i.e., the
-same format as the @file{signing-key.pub} file.
+@item --delete
+@itemx -d
+Attempt to delete all the store files and directories specified as
+arguments. This fails if some of the files are not in the store, or if
+they are still live.
-The list of authorized keys is kept in the human-editable file
-@file{/etc/guix/acl}. The file contains
-@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
-s-expressions''} and is structured as an access-control list in the
-@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
-(SPKI)}.
+@item --list-failures
+List store items corresponding to cached build failures.
-@item --extract=@var{directory}
-@itemx -x @var{directory}
-Read a single-item archive as served by substitute servers
-(@pxref{Substitutes}) and extract it to @var{directory}. This is a
-low-level operation needed in only very narrow use cases; see below.
+This prints nothing unless the daemon was started with
+@option{--cache-failures} (@pxref{Invoking guix-daemon,
+@option{--cache-failures}}).
-For example, the following command extracts the substitute for Emacs
-served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:
+@item --clear-failures
+Remove the specified store items from the failed-build cache.
-@example
-$ wget -O - \
- https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \
- | bunzip2 | guix archive -x /tmp/emacs
-@end example
+Again, this option only makes sense when the daemon is started with
+@option{--cache-failures}. Otherwise, it does nothing.
-Single-item archives are different from multiple-item archives produced
-by @command{guix archive --export}; they contain a single store item,
-and they do @emph{not} embed a signature. Thus this operation does
-@emph{no} signature verification and its output should be considered
-unsafe.
+@item --list-dead
+Show the list of dead files and directories still present in the
+store---i.e., files and directories no longer reachable from any root.
-The primary purpose of this operation is to facilitate inspection of
-archive contents coming from possibly untrusted substitute servers.
+@item --list-live
+Show the list of live store files and directories.
@end table
-@c *********************************************************************
-@node Programming Interface
-@chapter Programming Interface
-
-GNU Guix provides several Scheme programming interfaces (APIs) to
-define, build, and query packages. The first interface allows users to
-write high-level package definitions. These definitions refer to
-familiar packaging concepts, such as the name and version of a package,
-its build system, and its dependencies. These definitions can then be
-turned into concrete build actions.
+In addition, the references among existing store files can be queried:
-Build actions are performed by the Guix daemon, on behalf of users. In a
-standard setup, the daemon has write access to the store---the
-@file{/gnu/store} directory---whereas users do not. The recommended
-setup also has the daemon perform builds in chroots, under a specific
-build users, to minimize interference with the rest of the system.
+@table @code
-@cindex derivation
-Lower-level APIs are available to interact with the daemon and the
-store. To instruct the daemon to perform a build action, users actually
-provide it with a @dfn{derivation}. A derivation is a low-level
-representation of the build actions to be taken, and the environment in
-which they should occur---derivations are to package definitions what
-assembly is to C programs. The term ``derivation'' comes from the fact
-that build results @emph{derive} from them.
+@item --references
+@itemx --referrers
+@cindex package dependencies
+List the references (respectively, the referrers) of store files given
+as arguments.
-This chapter describes all these APIs in turn, starting from high-level
-package definitions.
+@item --requisites
+@itemx -R
+@cindex closure
+List the requisites of the store files passed as arguments. Requisites
+include the store files themselves, their references, and the references
+of these, recursively. In other words, the returned list is the
+@dfn{transitive closure} of the store files.
-@menu
-* Defining Packages:: Defining new packages.
-* Build Systems:: Specifying how packages are built.
-* The Store:: Manipulating the package store.
-* Derivations:: Low-level interface to package derivations.
-* The Store Monad:: Purely functional interface to the store.
-* G-Expressions:: Manipulating build expressions.
-* Invoking guix repl:: Fiddling with Guix interactively.
-@end menu
+@xref{Invoking guix size}, for a tool to profile the size of the closure
+of an element. @xref{Invoking guix graph}, for a tool to visualize
+the graph of references.
-@node Defining Packages
-@section Defining Packages
+@item --derivers
+@cindex derivation
+Return the derivation(s) leading to the given store items
+(@pxref{Derivations}).
-The high-level interface to package definitions is implemented in the
-@code{(guix packages)} and @code{(guix build-system)} modules. As an
-example, the package definition, or @dfn{recipe}, for the GNU Hello
-package looks like this:
+For example, this command:
@example
-(define-module (gnu packages hello)
- #:use-module (guix packages)
- #:use-module (guix download)
- #:use-module (guix build-system gnu)
- #:use-module (guix licenses)
- #:use-module (gnu packages gawk))
-
-(define-public hello
- (package
- (name "hello")
- (version "2.10")
- (source (origin
- (method url-fetch)
- (uri (string-append "mirror://gnu/hello/hello-" version
- ".tar.gz"))
- (sha256
- (base32
- "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
- (build-system gnu-build-system)
- (arguments '(#:configure-flags '("--enable-silent-rules")))
- (inputs `(("gawk" ,gawk)))
- (synopsis "Hello, GNU world: An example GNU package")
- (description "Guess what GNU Hello prints!")
- (home-page "http://www.gnu.org/software/hello/")
- (license gpl3+)))
+guix gc --derivers `guix package -I ^emacs$ | cut -f4`
@end example
@noindent
-Without being a Scheme expert, the reader may have guessed the meaning
-of the various fields here. This expression binds the variable
-@code{hello} to a @code{<package>} object, which is essentially a record
-(@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
-This package object can be inspected using procedures found in the
-@code{(guix packages)} module; for instance, @code{(package-name hello)}
-returns---surprise!---@code{"hello"}.
+returns the @file{.drv} file(s) leading to the @code{emacs} package
+installed in your profile.
-With luck, you may be able to import part or all of the definition of
-the package you are interested in from another repository, using the
-@code{guix import} command (@pxref{Invoking guix import}).
+Note that there may be zero matching @file{.drv} files, for instance
+because these files have been garbage-collected. There can also be more
+than one matching @file{.drv} due to fixed-output derivations.
+@end table
-In the example above, @var{hello} is defined in a module of its own,
-@code{(gnu packages hello)}. Technically, this is not strictly
-necessary, but it is convenient to do so: all the packages defined in
-modules under @code{(gnu packages @dots{})} are automatically known to
-the command-line tools (@pxref{Package Modules}).
+Lastly, the following options allow you to check the integrity of the
+store and to control disk usage.
-There are a few points worth noting in the above package definition:
+@table @option
-@itemize
-@item
-The @code{source} field of the package is an @code{<origin>} object
-(@pxref{origin Reference}, for the complete reference).
-Here, the @code{url-fetch} method from @code{(guix download)} is used,
-meaning that the source is a file to be downloaded over FTP or HTTP.
+@item --verify[=@var{options}]
+@cindex integrity, of the store
+@cindex integrity checking
+Verify the integrity of the store.
-The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
-the GNU mirrors defined in @code{(guix download)}.
+By default, make sure that all the store items marked as valid in the
+database of the daemon actually exist in @file{/gnu/store}.
-The @code{sha256} field specifies the expected SHA256 hash of the file
-being downloaded. It is mandatory, and allows Guix to check the
-integrity of the file. The @code{(base32 @dots{})} form introduces the
-base32 representation of the hash. You can obtain this information with
-@code{guix download} (@pxref{Invoking guix download}) and @code{guix
-hash} (@pxref{Invoking guix hash}).
-
-@cindex patches
-When needed, the @code{origin} form can also have a @code{patches} field
-listing patches to be applied, and a @code{snippet} field giving a
-Scheme expression to modify the source code.
+When provided, @var{options} must be a comma-separated list containing one
+or more of @code{contents} and @code{repair}.
-@item
-@cindex GNU Build System
-The @code{build-system} field specifies the procedure to build the
-package (@pxref{Build Systems}). Here, @var{gnu-build-system}
-represents the familiar GNU Build System, where packages may be
-configured, built, and installed with the usual @code{./configure &&
-make && make check && make install} command sequence.
+When passing @option{--verify=contents}, the daemon computes the
+content hash of each store item and compares it against its hash in the
+database. Hash mismatches are reported as data corruptions. Because it
+traverses @emph{all the files in the store}, this command can take a
+long time, especially on systems with a slow disk drive.
-@item
-The @code{arguments} field specifies options for the build system
-(@pxref{Build Systems}). Here it is interpreted by
-@var{gnu-build-system} as a request run @file{configure} with the
-@code{--enable-silent-rules} flag.
+@cindex repairing the store
+@cindex corruption, recovering from
+Using @option{--verify=repair} or @option{--verify=contents,repair}
+causes the daemon to try to repair corrupt store items by fetching
+substitutes for them (@pxref{Substitutes}). Because repairing is not
+atomic, and thus potentially dangerous, it is available only to the
+system administrator. A lightweight alternative, when you know exactly
+which items in the store are corrupt, is @command{guix build --repair}
+(@pxref{Invoking guix build}).
-@cindex quote
-@cindex quoting
-@findex '
-@findex quote
-What about these quote (@code{'}) characters? They are Scheme syntax to
-introduce a literal list; @code{'} is synonymous with @code{quote}.
-@xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual},
-for details. Here the value of the @code{arguments} field is a list of
-arguments passed to the build system down the road, as with @code{apply}
-(@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference
-Manual}).
+@item --optimize
+@cindex deduplication
+Optimize the store by hard-linking identical files---this is
+@dfn{deduplication}.
-The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
-(@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
-@code{#:configure-flags} is a keyword used to pass a keyword argument
-to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
-Reference Manual}).
+The daemon performs deduplication after each successful build or archive
+import, unless it was started with @code{--disable-deduplication}
+(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus,
+this option is primarily useful when the daemon was running with
+@code{--disable-deduplication}.
-@item
-The @code{inputs} field specifies inputs to the build process---i.e.,
-build-time or run-time dependencies of the package. Here, we define an
-input called @code{"gawk"} whose value is that of the @var{gawk}
-variable; @var{gawk} is itself bound to a @code{<package>} object.
+@end table
-@cindex backquote (quasiquote)
-@findex `
-@findex quasiquote
-@cindex comma (unquote)
-@findex ,
-@findex unquote
-@findex ,@@
-@findex unquote-splicing
-Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows
-us to introduce a literal list in the @code{inputs} field, while
-@code{,} (a comma, synonymous with @code{unquote}) allows us to insert a
-value in that list (@pxref{Expression Syntax, unquote,, guile, GNU Guile
-Reference Manual}).
+@node Invoking guix pull
+@section Invoking @command{guix pull}
-Note that GCC, Coreutils, Bash, and other essential tools do not need to
-be specified as inputs here. Instead, @var{gnu-build-system} takes care
-of ensuring that they are present (@pxref{Build Systems}).
+@cindex upgrading Guix
+@cindex updating Guix
+@cindex @command{guix pull}
+@cindex pull
+Packages are installed or upgraded to the latest version available in
+the distribution currently available on your local machine. To update
+that distribution, along with the Guix tools, you must run @command{guix
+pull}: the command downloads the latest Guix source code and package
+descriptions, and deploys it. Source code is downloaded from a
+@uref{https://git-scm.com, Git} repository, by default the official
+GNU@tie{}Guix repository, though this can be customized.
-However, any other dependencies need to be specified in the
-@code{inputs} field. Any dependency not specified here will simply be
-unavailable to the build process, possibly leading to a build failure.
-@end itemize
+On completion, @command{guix package} will use packages and package
+versions from this just-retrieved copy of Guix. Not only that, but all
+the Guix commands and Scheme modules will also be taken from that latest
+version. New @command{guix} sub-commands added by the update also
+become available.
-@xref{package Reference}, for a full description of possible fields.
+Any user can update their Guix copy using @command{guix pull}, and the
+effect is limited to the user who run @command{guix pull}. For
+instance, when user @code{root} runs @command{guix pull}, this has no
+effect on the version of Guix that user @code{alice} sees, and vice
+versa.
-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
-you encounter (@pxref{Debugging Build Failures}). You can easily jump back to the
-package definition using the @command{guix edit} command
-(@pxref{Invoking guix edit}).
-@xref{Packaging Guidelines}, for
-more information on how to test package definitions, and
-@ref{Invoking guix lint}, for information on how to check a definition
-for style conformance.
-@vindex GUIX_PACKAGE_PATH
-Lastly, @pxref{Channels}, for information
-on how to extend the distribution by adding your own package definitions
-in a ``channel''.
+The result of running @command{guix pull} is a @dfn{profile} available
+under @file{~/.config/guix/current} containing the latest Guix. Thus,
+make sure to add it to the beginning of your search path so that you use
+the latest version, and similarly for the Info manual
+(@pxref{Documentation}):
-Finally, updating the package definition to a new upstream version
-can be partly automated by the @command{guix refresh} command
-(@pxref{Invoking guix refresh}).
+@example
+export PATH="$HOME/.config/guix/current/bin:$PATH"
+export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
+@end example
-Behind the scenes, a derivation corresponding to the @code{<package>}
-object is first computed by the @code{package-derivation} procedure.
-That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
-The build actions it prescribes may then be realized by using the
-@code{build-derivations} procedure (@pxref{The Store}).
+The @code{--list-generations} or @code{-l} option lists past generations
+produced by @command{guix pull}, along with details about their provenance:
-@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
-Return the @code{<derivation>} object of @var{package} for @var{system}
-(@pxref{Derivations}).
+@example
+$ guix pull -l
+Generation 1 Jun 10 2018 00:18:18
+ guix 65956ad
+ repository URL: https://git.savannah.gnu.org/git/guix.git
+ branch: origin/master
+ commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe
-@var{package} must be a valid @code{<package>} object, and @var{system}
-must be a string denoting the target system type---e.g.,
-@code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
-must be a connection to the daemon, which operates on the store
-(@pxref{The Store}).
-@end deffn
+Generation 2 Jun 11 2018 11:02:49
+ guix e0cc7f6
+ repository URL: https://git.savannah.gnu.org/git/guix.git
+ branch: origin/master
+ commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
+ 2 new packages: keepalived, libnfnetlink
+ 6 packages upgraded: emacs-nix-mode@@2.0.4,
+ guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac,
+ heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4
-@noindent
-@cindex cross-compilation
-Similarly, it is possible to compute a derivation that cross-builds a
-package for some other system:
+Generation 3 Jun 13 2018 23:31:07 (current)
+ guix 844cc1c
+ repository URL: https://git.savannah.gnu.org/git/guix.git
+ branch: origin/master
+ commit: 844cc1c8f394f03b404c5bb3aee086922373490c
+ 28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{}
+ 69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{}
+@end example
-@deffn {Scheme Procedure} package-cross-derivation @var{store} @
- @var{package} @var{target} [@var{system}]
-Return the @code{<derivation>} object of @var{package} cross-built from
-@var{system} to @var{target}.
+@ref{Invoking guix describe, @command{guix describe}}, for other ways to
+describe the current status of Guix.
-@var{target} must be a valid GNU triplet denoting the target hardware
-and operating system, such as @code{"mips64el-linux-gnu"}
-(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
-Configure and Build System}).
-@end deffn
+This @code{~/.config/guix/current} profile works like any other profile
+created by @command{guix package} (@pxref{Invoking guix package}). That
+is, you can list generations, roll back to the previous
+generation---i.e., the previous Guix---and so on:
-@cindex package transformations
-@cindex input rewriting
-@cindex dependency tree rewriting
-Packages can be manipulated in arbitrary ways. An example of a useful
-transformation is @dfn{input rewriting}, whereby the dependency tree of
-a package is rewritten by replacing specific inputs by others:
+@example
+$ guix package -p ~/.config/guix/current --roll-back
+switched from generation 3 to 2
+$ guix package -p ~/.config/guix/current --delete-generations=1
+deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
+@end example
-@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
- [@var{rewrite-name}]
-Return a procedure that, when passed a package, replaces its direct and
-indirect dependencies (but not its implicit inputs) according to
-@var{replacements}. @var{replacements} is a list of package pairs; the
-first element of each pair is the package to replace, and the second one
-is the replacement.
+The @command{guix pull} command is usually invoked with no arguments,
+but it supports the following options:
-Optionally, @var{rewrite-name} is a one-argument procedure that takes
-the name of a package and returns its new name after rewrite.
-@end deffn
+@table @code
+@item --url=@var{url}
+@itemx --commit=@var{commit}
+@itemx --branch=@var{branch}
+Download code from the specified @var{url}, at the given @var{commit} (a valid
+Git commit ID represented as a hexadecimal string), or @var{branch}.
-@noindent
-Consider this example:
+@cindex @file{channels.scm}, configuration file
+@cindex configuration file for channels
+These options are provided for convenience, but you can also specify your
+configuration in the @file{~/.config/guix/channels.scm} file or using the
+@option{--channels} option (see below).
-@example
-(define libressl-instead-of-openssl
- ;; This is a procedure to replace OPENSSL by LIBRESSL,
- ;; recursively.
- (package-input-rewriting `((,openssl . ,libressl))))
+@item --channels=@var{file}
+@itemx -C @var{file}
+Read the list of channels from @var{file} instead of
+@file{~/.config/guix/channels.scm}. @var{file} must contain Scheme code that
+evaluates to a list of channel objects. @xref{Channels}, for more
+information.
-(define git-with-libressl
- (libressl-instead-of-openssl git))
-@end example
+@item --list-generations[=@var{pattern}]
+@itemx -l [@var{pattern}]
+List all the generations of @file{~/.config/guix/current} or, if @var{pattern}
+is provided, the subset of generations that match @var{pattern}.
+The syntax of @var{pattern} is the same as with @code{guix package
+--list-generations} (@pxref{Invoking guix package}).
-@noindent
-Here we first define a rewriting procedure that replaces @var{openssl}
-with @var{libressl}. Then we use it to define a @dfn{variant} of the
-@var{git} package that uses @var{libressl} instead of @var{openssl}.
-This is exactly what the @option{--with-input} command-line option does
-(@pxref{Package Transformation Options, @option{--with-input}}).
+@ref{Invoking guix describe}, for a way to display information about the
+current generation only.
-A more generic procedure to rewrite a package dependency graph is
-@code{package-mapping}: it supports arbitrary changes to nodes in the
-graph.
+@item --profile=@var{profile}
+@itemx -p @var{profile}
+Use @var{profile} instead of @file{~/.config/guix/current}.
-@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}]
-Return a procedure that, given a package, applies @var{proc} to all the packages
-depended on and returns the resulting package. The procedure stops recursion
-when @var{cut?} returns true for a given package.
-@end deffn
+@item --dry-run
+@itemx -n
+Show which channel commit(s) would be used and what would be built or
+substituted but do not actually do it.
-@menu
-* package Reference:: The package data type.
-* origin Reference:: The origin data type.
-@end menu
+@item --system=@var{system}
+@itemx -s @var{system}
+Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
+the system type of the build host.
+@item --verbose
+Produce verbose output, writing build logs to the standard error output.
-@node package Reference
-@subsection @code{package} Reference
+@item --bootstrap
+Use the bootstrap Guile to build the latest Guix. This option is only
+useful to Guix developers.
+@end table
-This section summarizes all the options available in @code{package}
-declarations (@pxref{Defining Packages}).
+The @dfn{channel} mechanism allows you to instruct @command{guix pull} which
+repository and branch to pull from, as well as @emph{additional} repositories
+containing package modules that should be deployed. @xref{Channels}, for more
+information.
-@deftp {Data Type} package
-This is the data type representing a package recipe.
+In addition, @command{guix pull} supports all the common build options
+(@pxref{Common Build Options}).
-@table @asis
-@item @code{name}
-The name of the package, as a string.
+@node Channels
+@section Channels
-@item @code{version}
-The version of the package, as a string.
+@cindex channels
+@cindex @file{channels.scm}, configuration file
+@cindex configuration file for channels
+@cindex @command{guix pull}, configuration file
+@cindex configuration of @command{guix pull}
+Guix and its package collection are updated by running @command{guix pull}
+(@pxref{Invoking guix pull}). By default @command{guix pull} downloads and
+deploys Guix itself from the official GNU@tie{}Guix repository. This can be
+customized by defining @dfn{channels} in the
+@file{~/.config/guix/channels.scm} file. A channel specifies a URL and branch
+of a Git repository to be deployed, and @command{guix pull} can be instructed
+to pull from one or more channels. In other words, channels can be used to
+@emph{customize} and to @emph{extend} Guix, as we will see below.
-@item @code{source}
-An object telling how the source code for the package should be
-acquired. Most of the time, this is an @code{origin} object, which
-denotes a file fetched from the Internet (@pxref{origin Reference}). It
-can also be any other ``file-like'' object such as a @code{local-file},
-which denotes a file from the local file system (@pxref{G-Expressions,
-@code{local-file}}).
+@subsection Using a Custom Guix Channel
-@item @code{build-system}
-The build system that should be used to build the package (@pxref{Build
-Systems}).
+The channel called @code{guix} specifies where Guix itself---its command-line
+tools as well as its package collection---should be downloaded. For instance,
+suppose you want to update from your own copy of the Guix repository at
+@code{example.org}, and specifically the @code{super-hacks} branch, you can
+write in @code{~/.config/guix/channels.scm} this specification:
-@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.
+@lisp
+;; Tell 'guix pull' to use my own repo.
+(list (channel
+ (name 'guix)
+ (url "https://example.org/my-guix.git")
+ (branch "super-hacks")))
+@end lisp
-@item @code{inputs} (default: @code{'()})
-@itemx @code{native-inputs} (default: @code{'()})
-@itemx @code{propagated-inputs} (default: @code{'()})
-@cindex inputs, of packages
-These fields list dependencies of the package. Each one is a list of
-tuples, where each tuple has a label for the input (a string) as its
-first element, a package, origin, or derivation as its second element,
-and optionally the name of the output thereof that should be used, which
-defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for
-more on package outputs). For example, the list below specifies three
-inputs:
+@noindent
+From there on, @command{guix pull} will fetch code from the @code{super-hacks}
+branch of the repository at @code{example.org}.
-@example
-`(("libffi" ,libffi)
- ("libunistring" ,libunistring)
- ("glib:bin" ,glib "bin")) ;the "bin" output of Glib
-@end example
+@subsection Specifying Additional Channels
-@cindex cross compilation, package dependencies
-The distinction between @code{native-inputs} and @code{inputs} is
-necessary when considering cross-compilation. When cross-compiling,
-dependencies listed in @code{inputs} are built for the @emph{target}
-architecture; conversely, dependencies listed in @code{native-inputs}
-are built for the architecture of the @emph{build} machine.
+@cindex extending the package collection (channels)
+@cindex personal packages (channels)
+@cindex channels, for personal packages
+You can also specify @emph{additional channels} to pull from. Let's say you
+have a bunch of custom package variants or personal packages that you think
+would make little sense to contribute to the Guix project, but would like to
+have these packages transparently available to you at the command line. You
+would first write modules containing those package definitions (@pxref{Package
+Modules}), maintain them in a Git repository, and then you and anyone else can
+use it as an additional channel to get packages from. Neat, no?
-@code{native-inputs} is typically used to list tools needed at
-build time, but not at run time, such as Autoconf, Automake, pkg-config,
-Gettext, or Bison. @command{guix lint} can report likely mistakes in
-this area (@pxref{Invoking guix lint}).
+@c What follows stems from discussions at
+@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
+@c earlier discussions on guix-devel@gnu.org.
+@quotation Warning
+Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
+publish your personal channel to the world, we would like to share a few words
+of caution:
-@anchor{package-propagated-inputs}
-Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
-specified packages will be automatically installed alongside the package
-they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
-package}}, for information on how @command{guix package} deals with
-propagated inputs.)
+@itemize
+@item
+Before publishing a channel, please consider contributing your package
+definitions to Guix proper (@pxref{Contributing}). Guix as a project is open
+to free software of all sorts, and packages in Guix proper are readily
+available to all Guix users and benefit from the project's quality assurance
+process.
-For example this is necessary when a C/C++ library needs headers of
-another library to compile, or when a pkg-config file refers to another
-one @i{via} its @code{Requires} field.
+@item
+When you maintain package definitions outside Guix, we, Guix developers,
+consider that @emph{the compatibility burden is on you}. Remember that
+package modules and package definitions are just Scheme code that uses various
+programming interfaces (APIs). We want to remain free to change these APIs to
+keep improving Guix, possibly in ways that break your channel. We never
+change APIs gratuitously, but we will @emph{not} commit to freezing APIs
+either.
-Another example where @code{propagated-inputs} is useful is for languages
-that lack a facility to record the run-time search path akin to the
-@code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
-more. To ensure that libraries written in those languages can find
-library code they depend on at run time, run-time dependencies must be
-listed in @code{propagated-inputs} rather than @code{inputs}.
+@item
+Corollary: if you're using an external channel and that channel breaks, please
+@emph{report the issue to the channel authors}, not to the Guix project.
+@end itemize
-@item @code{self-native-input?} (default: @code{#f})
-This is a Boolean field telling whether the package should use itself as
-a native input when cross-compiling.
+You've been warned! Having said this, we believe external channels are a
+practical way to exert your freedom to augment Guix' package collection and to
+share your improvements, which are basic tenets of
+@uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please
+email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
+@end quotation
-@item @code{outputs} (default: @code{'("out")})
-The list of output names of the package. @xref{Packages with Multiple
-Outputs}, for typical uses of additional outputs.
+To use a channel, write @code{~/.config/guix/channels.scm} to instruct
+@command{guix pull} to pull from it @emph{in addition} to the default Guix
+channel(s):
-@item @code{native-search-paths} (default: @code{'()})
-@itemx @code{search-paths} (default: @code{'()})
-A list of @code{search-path-specification} objects describing
-search-path environment variables honored by the package.
+@vindex %default-channels
+@lisp
+;; Add my personal packages to those Guix provides.
+(cons (channel
+ (name 'my-personal-packages)
+ (url "https://example.org/personal-packages.git"))
+ %default-channels)
+@end lisp
-@item @code{replacement} (default: @code{#f})
-This must be either @code{#f} or a package object that will be used as a
-@dfn{replacement} for this package. @xref{Security Updates, grafts},
-for details.
+@noindent
+Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
+add a channel the list of channels that the variable @code{%default-channels}
+is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
+Manual}). With this file in place, @command{guix pull} builds not only Guix
+but also the package modules from your own repository. The result in
+@file{~/.config/guix/current} is the union of Guix with your own package
+modules:
-@item @code{synopsis}
-A one-line description of the package.
+@example
+$ guix pull --list-generations
+@dots{}
+Generation 19 Aug 27 2018 16:20:48
+ guix d894ab8
+ repository URL: https://git.savannah.gnu.org/git/guix.git
+ branch: master
+ commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
+ my-personal-packages dd3df5e
+ repository URL: https://example.org/personal-packages.git
+ branch: master
+ commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
+ 11 new packages: my-gimp, my-emacs-with-cool-features, @dots{}
+ 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
+@end example
-@item @code{description}
-A more elaborate description of the package.
+@noindent
+The output of @command{guix pull} above shows that Generation@tie{}19 includes
+both Guix and packages from the @code{my-personal-packages} channel. Among
+the new and upgraded packages that are listed, some like @code{my-gimp} and
+@code{my-emacs-with-cool-features} might come from
+@code{my-personal-packages}, while others come from the Guix default channel.
-@item @code{license}
-@cindex license, of packages
-The license of the package; a value from @code{(guix licenses)},
-or a list of such values.
+To create a channel, create a Git repository containing your own package
+modules and make it available. The repository can contain anything, but a
+useful channel will contain Guile modules that export packages. Once you
+start using a channel, Guix will behave as if the root directory of that
+channel's Git repository has been added to the Guile load path (@pxref{Load
+Paths,,, guile, GNU Guile Reference Manual}). For example, if your channel
+contains a file at @file{my-packages/my-tools.scm} that defines a Guile
+module, then the module will be available under the name @code{(my-packages
+my-tools)}, and you will be able to use it like any other module
+(@pxref{Modules,,, guile, GNU Guile Reference Manual}).
-@item @code{home-page}
-The URL to the home-page of the package, as a string.
+@cindex dependencies, channels
+@cindex meta-data, channels
+@subsection Declaring Channel Dependencies
-@item @code{supported-systems} (default: @var{%supported-systems})
-The list of systems supported by the package, as strings of the form
-@code{architecture-kernel}, for example @code{"x86_64-linux"}.
+Channel authors may decide to augment a package collection provided by other
+channels. They can declare their channel to be dependent on other channels in
+a meta-data file @file{.guix-channel}, which is to be placed in the root of
+the channel repository.
-@item @code{maintainers} (default: @code{'()})
-The list of maintainers of the package, as @code{maintainer} objects.
+The meta-data file should contain a simple S-expression like this:
-@item @code{location} (default: source location of the @code{package} form)
-The source location of the package. It is useful to override this when
-inheriting from another package, in which case this field is not
-automatically corrected.
-@end table
-@end deftp
+@lisp
+(channel
+ (version 0)
+ (dependencies
+ (channel
+ (name some-collection)
+ (url "https://example.org/first-collection.git"))
+ (channel
+ (name some-other-collection)
+ (url "https://example.org/second-collection.git")
+ (branch "testing"))))
+@end lisp
+In the above example this channel is declared to depend on two other channels,
+which will both be fetched automatically. The modules provided by the channel
+will be compiled in an environment where the modules of all these declared
+channels are available.
-@node origin Reference
-@subsection @code{origin} Reference
+For the sake of reliability and maintainability, you should avoid dependencies
+on channels that you don't control, and you should aim to keep the number of
+dependencies to a minimum.
-This section summarizes all the options available in @code{origin}
-declarations (@pxref{Defining Packages}).
+@subsection Replicating Guix
-@deftp {Data Type} origin
-This is the data type representing a source code origin.
+@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:
-@table @asis
-@item @code{uri}
-An object containing the URI of the source. The object type depends on
-the @code{method} (see below). For example, when using the
-@var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
-values are: a URL represented as a string, or a list thereof.
+@lisp
+;; Deploy specific commits of my channels of interest.
+(list (channel
+ (name 'guix)
+ (url "https://git.savannah.gnu.org/git/guix.git")
+ (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300"))
+ (channel
+ (name 'my-personal-packages)
+ (url "https://example.org/personal-packages.git")
+ (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
+@end lisp
-@item @code{method}
-A procedure that handles the URI.
+The @command{guix describe --format=channels} command can even generate this
+list of channels directly (@pxref{Invoking guix describe}).
-Examples include:
+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.
-@table @asis
-@item @var{url-fetch} from @code{(guix download)}
-download a file from the HTTP, HTTPS, or FTP URL specified in the
-@code{uri} field;
+This gives you super powers, allowing you to track the provenance of binary
+artifacts with very fine grain, and to reproduce software environments at
+will---some sort of ``meta reproducibility'' capabilities, if you will.
+@xref{Inferiors}, for another way to take advantage of these super powers.
-@vindex git-fetch
-@item @var{git-fetch} from @code{(guix git-download)}
-clone the Git version control repository, and check out the revision
-specified in the @code{uri} field as a @code{git-reference} object; a
-@code{git-reference} looks like this:
+@node Inferiors
+@section Inferiors
-@example
-(git-reference
- (url "git://git.debian.org/git/pkg-shadow/shadow")
- (commit "v4.1.5.1"))
-@end example
-@end table
+@c TODO: Remove this once we're more confident about API stability.
+@quotation Note
+The functionality described here is a ``technology preview'' as of version
+@value{VERSION}. As such, the interface is subject to change.
+@end quotation
-@item @code{sha256}
-A bytevector containing the SHA-256 hash of the source. Typically the
-@code{base32} form is used here to generate the bytevector from a
-base-32 string.
+@cindex inferiors
+@cindex composition of Guix revisions
+Sometimes you might need to mix packages from the revision of Guix you're
+currently running with packages available in a different revision of Guix.
+Guix @dfn{inferiors} allow you to achieve that by composing different Guix
+revisions in arbitrary ways.
-You can obtain this information using @code{guix download}
-(@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
-guix hash}).
+@cindex inferior packages
+Technically, an ``inferior'' is essentially a separate Guix process connected
+to your main Guix process through a REPL (@pxref{Invoking guix repl}). The
+@code{(guix inferior)} module allows you to create inferiors and to
+communicate with them. It also provides a high-level interface to browse and
+manipulate the packages that an inferior provides---@dfn{inferior packages}.
-@item @code{file-name} (default: @code{#f})
-The file name under which the source code should be saved. When this is
-@code{#f}, a sensible default value will be used in most cases. In case
-the source is fetched from a URL, the file name from the URL will be
-used. For version control checkouts, it is recommended to provide the
-file name explicitly because the default is not very descriptive.
+When combined with channels (@pxref{Channels}), inferiors provide a simple way
+to interact with a separate revision of Guix. For example, let's assume you
+want to install in your profile the current @code{guile} package, along with
+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
+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:
-@item @code{patches} (default: @code{'()})
-A list of file names, origins, or file-like objects (@pxref{G-Expressions,
-file-like objects}) pointing to patches to be applied to the source.
+@lisp
+(use-modules (guix inferior) (guix channels)
+ (srfi srfi-1)) ;for 'first'
-This list of patches must be unconditional. In particular, it cannot
-depend on the value of @code{%current-system} or
-@code{%current-target-system}.
+(define channels
+ ;; This is the old revision from which we want to
+ ;; extract guile-json.
+ (list (channel
+ (name 'guix)
+ (url "https://git.savannah.gnu.org/git/guix.git")
+ (commit
+ "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))
-@item @code{snippet} (default: @code{#f})
-A G-expression (@pxref{G-Expressions}) or S-expression that will be run
-in the source directory. This is a convenient way to modify the source,
-sometimes more convenient than a patch.
+(define inferior
+ ;; An inferior representing the above revision.
+ (inferior-for-channels channels))
-@item @code{patch-flags} (default: @code{'("-p1")})
-A list of command-line flags that should be passed to the @code{patch}
-command.
+;; Now create a manifest with the current "guile" package
+;; and the old "guile-json" package.
+(packages->manifest
+ (list (first (lookup-inferior-packages inferior "guile-json"))
+ (specification->package "guile")))
+@end lisp
-@item @code{patch-inputs} (default: @code{#f})
-Input packages or derivations to the patching process. When this is
-@code{#f}, the usual set of inputs necessary for patching are provided,
-such as GNU@tie{}Patch.
+On its first run, @command{guix package --manifest} might have to build the
+channel you specified before it can create the inferior; subsequent runs will
+be much faster because the Guix revision will be cached.
-@item @code{modules} (default: @code{'()})
-A list of Guile modules that should be loaded during the patching
-process and while running the code in the @code{snippet} field.
+The @code{(guix inferior)} module provides the following procedures to open an
+inferior:
-@item @code{patch-guile} (default: @code{#f})
-The Guile package that should be used in the patching process. When
-this is @code{#f}, a sensible default is used.
-@end table
-@end deftp
+@deffn {Scheme Procedure} inferior-for-channels @var{channels} @
+ [#:cache-directory] [#:ttl]
+Return an inferior for @var{channels}, a list of channels. Use the cache at
+@var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
+This procedure opens a new connection to the build daemon.
+As a side effect, this procedure may build or substitute binaries for
+@var{channels}, which can take time.
+@end deffn
-@node Build Systems
-@section Build Systems
+@deffn {Scheme Procedure} open-inferior @var{directory} @
+ [#:command "bin/guix"]
+Open the inferior Guix in @var{directory}, running
+@code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if
+the inferior could not be launched.
+@end deffn
-@cindex build system
-Each package definition specifies a @dfn{build system} and arguments for
-that build system (@pxref{Defining Packages}). This @code{build-system}
-field represents the build procedure of the package, as well as implicit
-dependencies of that build procedure.
+@cindex inferior packages
+The procedures listed below allow you to obtain and manipulate inferior
+packages.
-Build systems are @code{<build-system>} objects. The interface to
-create and manipulate them is provided by the @code{(guix build-system)}
-module, and actual build systems are exported by specific modules.
+@deffn {Scheme Procedure} inferior-packages @var{inferior}
+Return the list of packages known to @var{inferior}.
+@end deffn
-@cindex bag (low-level package representation)
-Under the hood, build systems first compile package objects to
-@dfn{bags}. A @dfn{bag} is like a package, but with less
-ornamentation---in other words, a bag is a lower-level representation of
-a package, which includes all the inputs of that package, including some
-that were implicitly added by the build system. This intermediate
-representation is then compiled to a derivation (@pxref{Derivations}).
+@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
+ [@var{version}]
+Return the sorted list of inferior packages matching @var{name} in
+@var{inferior}, with highest version numbers first. If @var{version} is true,
+return only packages with a version number prefixed by @var{version}.
+@end deffn
-Build systems accept an optional list of @dfn{arguments}. In package
-definitions, these are passed @i{via} the @code{arguments} field
-(@pxref{Defining Packages}). They are typically keyword arguments
-(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
-Guile Reference Manual}). The value of these arguments is usually
-evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
-by the daemon (@pxref{Derivations}).
+@deffn {Scheme Procedure} inferior-package? @var{obj}
+Return true if @var{obj} is an inferior package.
+@end deffn
-The main build system is @var{gnu-build-system}, which implements the
-standard build procedure for GNU and many other packages. It
-is provided by the @code{(guix build-system gnu)} module.
+@deffn {Scheme Procedure} inferior-package-name @var{package}
+@deffnx {Scheme Procedure} inferior-package-version @var{package}
+@deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
+@deffnx {Scheme Procedure} inferior-package-description @var{package}
+@deffnx {Scheme Procedure} inferior-package-home-page @var{package}
+@deffnx {Scheme Procedure} inferior-package-location @var{package}
+@deffnx {Scheme Procedure} inferior-package-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
+@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
+@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
+@deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
+These procedures are the counterpart of package record accessors
+(@pxref{package Reference}). Most of them work by querying the inferior
+@var{package} comes from, so the inferior must still be live when you call
+these procedures.
+@end deffn
-@defvr {Scheme Variable} gnu-build-system
-@var{gnu-build-system} represents the GNU Build System, and variants
-thereof (@pxref{Configuration, configuration and makefile conventions,,
-standards, GNU Coding Standards}).
+Inferior packages can be used transparently like any other package or
+file-like object in G-expressions (@pxref{G-Expressions}). They are also
+transparently handled by the @code{packages->manifest} procedure, which is
+commonly use in manifests (@pxref{Invoking guix package, the
+@option{--manifest} option of @command{guix package}}). Thus you can insert
+an inferior package pretty much anywhere you would insert a regular package:
+in manifests, in the @code{packages} field of your @code{operating-system}
+declaration, and so on.
-@cindex build phases
-In a nutshell, packages using it are configured, built, and installed with
-the usual @code{./configure && make && make check && make install}
-command sequence. In practice, a few additional steps are often needed.
-All these steps are split up in separate @dfn{phases},
-notably@footnote{Please see the @code{(guix build gnu-build-system)}
-modules for more details about the build phases.}:
+@node Invoking guix describe
+@section Invoking @command{guix describe}
-@table @code
-@item unpack
-Unpack the source tarball, and change the current directory to the
-extracted source tree. If the source is actually a directory, copy it
-to the build tree, and enter that directory.
+@cindex reproducibility
+@cindex replicating Guix
+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
+machine or user account, if you want to report a bug or to determine what
+change in the channels you are using caused it, or if you want to record your
+system state for reproducibility purposes. The @command{guix describe}
+command answers these questions.
-@item patch-source-shebangs
-Patch shebangs encountered in source files so they refer to the right
-store file names. For instance, this changes @code{#!/bin/sh} to
-@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
+When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
+displays the channel(s) that it was built from, including their repository URL
+and commit IDs (@pxref{Channels}):
-@item configure
-Run the @file{configure} script with a number of default options, such
-as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
-by the @code{#:configure-flags} argument.
+@example
+$ guix describe
+Generation 10 Sep 03 2018 17:32:44 (current)
+ guix e0fa68c
+ repository URL: https://git.savannah.gnu.org/git/guix.git
+ branch: master
+ commit: e0fa68c7718fffd33d81af415279d6ddb518f727
+@end example
-@item build
-Run @code{make} with the list of flags specified with
-@code{#:make-flags}. If the @code{#:parallel-build?} argument is true
-(the default), build with @code{make -j}.
+If you're familiar with the Git version control system, this is similar in
+spirit to @command{git describe}; the output is also similar to that of
+@command{guix pull --list-generations}, but limited to the current generation
+(@pxref{Invoking guix pull, the @option{--list-generations} option}). Because
+the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
+information is all it takes to describe the revision of Guix you're using, and
+also to replicate it.
-@item check
-Run @code{make check}, or some other target specified with
-@code{#:test-target}, unless @code{#:tests? #f} is passed. If the
-@code{#:parallel-tests?} argument is true (the default), run @code{make
-check -j}.
+To make it easier to replicate Guix, @command{guix describe} can also be asked
+to return a list of channels instead of the human-readable description above:
-@item install
-Run @code{make install} with the flags listed in @code{#:make-flags}.
+@example
+$ guix describe -f channels
+(list (channel
+ (name 'guix)
+ (url "https://git.savannah.gnu.org/git/guix.git")
+ (commit
+ "e0fa68c7718fffd33d81af415279d6ddb518f727")))
+@end example
-@item patch-shebangs
-Patch shebangs on the installed executable files.
+@noindent
+You can save this to a file and feed it to @command{guix pull -C} on some
+other machine or at a later point in time, which will instantiate @emph{this
+exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
+From there on, since you're able to deploy the same revision of Guix, you can
+just as well @emph{replicate a complete software environment}. We humbly
+think that this is @emph{awesome}, and we hope you'll like it too!
-@item strip
-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}).
+The details of the options supported by @command{guix describe} are as
+follows:
+
+@table @code
+@item --format=@var{format}
+@itemx -f @var{format}
+Produce output in the specified @var{format}, one of:
+
+@table @code
+@item human
+produce human-readable output;
+@item channels
+produce a list of channel specifications that can be passed to @command{guix
+pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
+guix pull});
+@item json
+@cindex JSON
+produce a list of channel specifications in JSON format;
+@item recutils
+produce a list of channel specifications in Recutils format.
@end table
-@vindex %standard-phases
-The build-side module @code{(guix build gnu-build-system)} defines
-@var{%standard-phases} as the default list of build phases.
-@var{%standard-phases} is a list of symbol/procedure pairs, where the
-procedure implements the actual phase.
+@item --profile=@var{profile}
+@itemx -p @var{profile}
+Display information about @var{profile}.
+@end table
-The list of phases used for a particular package can be changed with the
-@code{#:phases} parameter. For instance, passing:
+@node Invoking guix archive
+@section Invoking @command{guix archive}
-@example
-#:phases (modify-phases %standard-phases (delete 'configure))
-@end example
+@cindex @command{guix archive}
+@cindex archive
+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.
+In particular, it allows store files to be transferred from one machine
+to the store on another machine.
-means that all the phases described above will be used, except the
-@code{configure} phase.
+@quotation Note
+If you're looking for a way to produce archives in a format suitable for
+tools other than Guix, @pxref{Invoking guix pack}.
+@end quotation
-In addition, this build system ensures that the ``standard'' environment
-for GNU packages is available. This includes tools such as GCC, libc,
-Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
-build-system gnu)} module for a complete list). We call these the
-@dfn{implicit inputs} of a package, because package definitions do not
-have to mention them.
-@end defvr
+@cindex exporting store items
+To export store files as an archive to standard output, run:
-Other @code{<build-system>} objects are defined to support other
-conventions and tools used by free software packages. They inherit most
-of @var{gnu-build-system}, and differ mainly in the set of inputs
-implicitly added to the build process, and in the list of phases
-executed. Some of these build systems are listed below.
+@example
+guix archive --export @var{options} @var{specifications}...
+@end example
-@defvr {Scheme Variable} ant-build-system
-This variable is exported by @code{(guix build-system ant)}. It
-implements the build procedure for Java packages that can be built with
-@url{http://ant.apache.org/, Ant build tool}.
+@var{specifications} may be either store file names or package
+specifications, as for @command{guix package} (@pxref{Invoking guix
+package}). For instance, the following command creates an archive
+containing the @code{gui} output of the @code{git} package and the main
+output of @code{emacs}:
-It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
-provided by the @code{icedtea} package to the set of inputs. Different
-packages can be specified with the @code{#:ant} and @code{#:jdk}
-parameters, respectively.
+@example
+guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
+@end example
-When the original package does not provide a suitable Ant build file,
-the parameter @code{#:jar-name} can be used to generate a minimal Ant
-build file @file{build.xml} with tasks to build the specified jar
-archive. In this case the parameter @code{#:source-dir} can be used to
-specify the source sub-directory, defaulting to ``src''.
+If the specified packages are not built yet, @command{guix archive}
+automatically builds them. The build process may be controlled with the
+common build options (@pxref{Common Build Options}).
-The @code{#:main-class} parameter can be used with the minimal ant
-buildfile to specify the main class of the resulting jar. This makes the
-jar file executable. The @code{#:test-include} parameter can be used to
-specify the list of junit tests to run. It defaults to
-@code{(list "**/*Test.java")}. The @code{#:test-exclude} can be used to
-disable some tests. It defaults to @code{(list "**/Abstract*.java")},
-because abstract classes cannot be run as tests.
+To transfer the @code{emacs} package to a machine connected over SSH,
+one would run:
-The parameter @code{#:build-target} can be used to specify the Ant task
-that should be run during the @code{build} phase. By default the
-``jar'' task will be run.
+@example
+guix archive --export -r emacs | ssh the-machine guix archive --import
+@end example
-@end defvr
+@noindent
+Similarly, a complete user profile may be transferred from one machine
+to another like this:
-@defvr {Scheme Variable} android-ndk-build-system
-@cindex Android distribution
-@cindex Android NDK build system
-This variable is exported by @code{(guix build-system android-ndk)}. It
-implements a build procedure for Android NDK (native development kit)
-packages using a Guix-specific build process.
+@example
+guix archive --export -r $(readlink -f ~/.guix-profile) | \
+ ssh the-machine guix-archive --import
+@end example
-The build system assumes that packages install their public interface
-(header) files to the subdirectory "include" of the "out" output and
-their libraries to the subdirectory "lib" of the "out" output.
+@noindent
+However, note that, in both examples, all of @code{emacs} and the
+profile as well as all of their dependencies are transferred (due to
+@code{-r}), regardless of what is already available in the store on the
+target machine. The @code{--missing} option can help figure out which
+items are missing from the target store. The @command{guix copy}
+command simplifies and optimizes this whole process, so this is probably
+what you should use in this case (@pxref{Invoking guix copy}).
-It's also assumed that the union of all the dependencies of a package
-has no conflicting files.
+@cindex nar, archive format
+@cindex normalized archive (nar)
+Archives are stored in the ``normalized archive'' or ``nar'' format, which is
+comparable in spirit to `tar', but with differences
+that make it more appropriate for our purposes. First, rather than
+recording all Unix metadata for each file, the nar format only mentions
+the file type (regular, directory, or symbolic link); Unix permissions
+and owner/group are dismissed. Second, the order in which directory
+entries are stored always follows the order of file names according to
+the C locale collation order. This makes archive production fully
+deterministic.
-For the time being, cross-compilation is not supported - so right now
-the libraries and header files are assumed to be host tools.
+When exporting, the daemon digitally signs the contents of the archive,
+and that digital signature is appended. When importing, the daemon
+verifies the signature and rejects the import in case of an invalid
+signature or if the signing key is not authorized.
+@c FIXME: Add xref to daemon doc about signatures.
-@end defvr
+The main options are:
-@defvr {Scheme Variable} asdf-build-system/source
-@defvrx {Scheme Variable} asdf-build-system/sbcl
-@defvrx {Scheme Variable} asdf-build-system/ecl
+@table @code
+@item --export
+Export the specified store files or packages (see below.) Write the
+resulting archive to the standard output.
-These variables, exported by @code{(guix build-system asdf)}, implement
-build procedures for Common Lisp packages using
-@url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
-definition facility for Common Lisp programs and libraries.
+Dependencies are @emph{not} included in the output, unless
+@code{--recursive} is passed.
-The @code{asdf-build-system/source} system installs the packages in
-source form, and can be loaded using any common lisp implementation, via
-ASDF. The others, such as @code{asdf-build-system/sbcl}, install binary
-systems in the format which a particular implementation understands.
-These build systems can also be used to produce executable programs, or
-lisp images which contain a set of packages pre-loaded.
-
-The build system uses naming conventions. For binary packages, the
-package name should be prefixed with the lisp implementation, such as
-@code{sbcl-} for @code{asdf-build-system/sbcl}.
+@item -r
+@itemx --recursive
+When combined with @code{--export}, this instructs @command{guix
+archive} to include dependencies of the given items in the archive.
+Thus, the resulting archive is self-contained: it contains the closure
+of the exported store items.
-Additionally, the corresponding source package should be labeled using
-the same convention as python packages (see @ref{Python Modules}), using
-the @code{cl-} prefix.
+@item --import
+Read an archive from the standard input, and import the files listed
+therein into the store. Abort if the archive has an invalid digital
+signature, or if it is signed by a public key not among the authorized
+keys (see @code{--authorize} below.)
-For binary packages, each system should be defined as a Guix package.
-If one package @code{origin} contains several systems, package variants
-can be created in order to build all the systems. Source packages,
-which use @code{asdf-build-system/source}, may contain several systems.
+@item --missing
+Read a list of store file names from the standard input, one per line,
+and write on the standard output the subset of these files missing from
+the store.
-In order to create executable programs and images, the build-side
-procedures @code{build-program} and @code{build-image} can be used.
-They should be called in a build phase after the @code{create-symlinks}
-phase, so that the system which was just built can be used within the
-resulting image. @code{build-program} requires a list of Common Lisp
-expressions to be passed as the @code{#:entry-program} argument.
+@item --generate-key[=@var{parameters}]
+@cindex signing, archives
+Generate a new key pair for the daemon. This is a prerequisite before
+archives can be exported with @code{--export}. Note that this operation
+usually takes time, because it needs to gather enough entropy to
+generate the key pair.
-If the system is not defined within its own @code{.asd} file of the same
-name, then the @code{#:asd-file} parameter should be used to specify
-which file the system is defined in. Furthermore, if the package
-defines a system for its tests in a separate file, it will be loaded
-before the tests are run if it is specified by the
-@code{#:test-asd-file} parameter. If it is not set, the files
-@code{<system>-tests.asd}, @code{<system>-test.asd}, @code{tests.asd},
-and @code{test.asd} will be tried if they exist.
+The generated key pair is typically stored under @file{/etc/guix}, in
+@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
+key, which must be kept secret.) When @var{parameters} is omitted,
+an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
+versions before 1.6.0, it is a 4096-bit RSA key.
+Alternatively, @var{parameters} can specify
+@code{genkey} parameters suitable for Libgcrypt (@pxref{General
+public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
+Libgcrypt Reference Manual}).
-If for some reason the package must be named in a different way than the
-naming conventions suggest, the @code{#:asd-system-name} parameter can
-be used to specify the name of the system.
+@item --authorize
+@cindex authorizing, archives
+Authorize imports signed by the public key passed on standard input.
+The public key must be in ``s-expression advanced format''---i.e., the
+same format as the @file{signing-key.pub} file.
-@end defvr
+The list of authorized keys is kept in the human-editable file
+@file{/etc/guix/acl}. The file contains
+@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
+s-expressions''} and is structured as an access-control list in the
+@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
+(SPKI)}.
-@defvr {Scheme Variable} cargo-build-system
-@cindex Rust programming language
-@cindex Cargo (Rust build system)
-This variable is exported by @code{(guix build-system cargo)}. It
-supports builds of packages using Cargo, the build tool of the
-@uref{https://www.rust-lang.org, Rust programming language}.
+@item --extract=@var{directory}
+@itemx -x @var{directory}
+Read a single-item archive as served by substitute servers
+(@pxref{Substitutes}) and extract it to @var{directory}. This is a
+low-level operation needed in only very narrow use cases; see below.
-In its @code{configure} phase, this build system replaces dependencies
-specified in the @file{Carto.toml} file with inputs to the Guix package.
-The @code{install} phase installs the binaries, and it also installs the
-source code and @file{Cargo.toml} file.
-@end defvr
+For example, the following command extracts the substitute for Emacs
+served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:
-@cindex Clojure (programming language)
-@cindex simple Clojure build system
-@defvr {Scheme Variable} clojure-build-system
-This variable is exported by @code{(guix build-system clojure)}. It implements
-a simple build procedure for @uref{https://clojure.org/, Clojure} packages
-using plain old @code{compile} in Clojure. Cross-compilation is not supported
-yet.
+@example
+$ wget -O - \
+ https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \
+ | bunzip2 | guix archive -x /tmp/emacs
+@end example
-It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs.
-Different packages can be specified with the @code{#:clojure}, @code{#:jdk} and
-@code{#:zip} parameters, respectively.
+Single-item archives are different from multiple-item archives produced
+by @command{guix archive --export}; they contain a single store item,
+and they do @emph{not} embed a signature. Thus this operation does
+@emph{no} signature verification and its output should be considered
+unsafe.
-A list of source directories, test directories and jar names can be specified
-with the @code{#:source-dirs}, @code{#:test-dirs} and @code{#:jar-names}
-parameters, respectively. Compile directory and main class can be specified
-with the @code{#:compile-dir} and @code{#:main-class} parameters, respectively.
-Other parameters are documented below.
+The primary purpose of this operation is to facilitate inspection of
+archive contents coming from possibly untrusted substitute servers.
-This build system is an extension of @var{ant-build-system}, but with the
-following phases changed:
+@end table
-@table @code
-@item build
-This phase calls @code{compile} in Clojure to compile source files and runs
-@command{jar} to create jars from both source files and compiled files
-according to the include list and exclude list specified in
-@code{#:aot-include} and @code{#:aot-exclude}, respectively. The exclude list
-has priority over the include list. These lists consist of symbols
-representing Clojure libraries or the special keyword @code{#:all} representing
-all Clojure libraries found under the source directories. The parameter
-@code{#:omit-source?} decides if source should be included into the jars.
+@c *********************************************************************
+@node Development
+@chapter Development
-@item check
-This phase runs tests according to the include list and exclude list specified
-in @code{#:test-include} and @code{#:test-exclude}, respectively. Their
-meanings are analogous to that of @code{#:aot-include} and
-@code{#:aot-exclude}, except that the special keyword @code{#:all} now
-stands for all Clojure libraries found under the test directories. The
-parameter @code{#:tests?} decides if tests should be run.
+@cindex software development
+If you are a software developer, Guix provides tools that you should find
+helpful---independently of the language you're developing in. This is what
+this chapter is about.
-@item install
-This phase installs all jars built previously.
-@end table
+The @command{guix environment} command provides a convenient way to set up
+@dfn{development environments} containing all the dependencies and tools
+necessary to work on the software package of your choice. The @command{guix
+pack} command allows you to create @dfn{application bundles} that can be
+easily distributed to users who do not run Guix.
-Apart from the above, this build system also contains an additional phase:
+@menu
+* Invoking guix environment:: Setting up development environments.
+* Invoking guix pack:: Creating software bundles.
+@end menu
-@table @code
+@node Invoking guix environment
+@section Invoking @command{guix environment}
-@item install-doc
-This phase installs all top-level files with base name matching
-@var{%doc-regex}. A different regex can be specified with the
-@code{#:doc-regex} parameter. All files (recursively) inside the documentation
-directories specified in @code{#:doc-dirs} are installed as well.
-@end table
-@end defvr
+@cindex reproducible build environments
+@cindex development environments
+@cindex @command{guix environment}
+@cindex environment, package build environment
+The purpose of @command{guix environment} is to assist hackers in
+creating reproducible development environments without polluting their
+package profile. The @command{guix environment} tool takes one or more
+packages, builds all of their inputs, and creates a shell
+environment to use them.
-@defvr {Scheme Variable} cmake-build-system
-This variable is exported by @code{(guix build-system cmake)}. It
-implements the build procedure for packages using the
-@url{http://www.cmake.org, CMake build tool}.
+The general syntax is:
-It automatically adds the @code{cmake} package to the set of inputs.
-Which package is used can be specified with the @code{#:cmake}
-parameter.
+@example
+guix environment @var{options} @var{package}@dots{}
+@end example
-The @code{#:configure-flags} parameter is taken as a list of flags
-passed to the @command{cmake} command. The @code{#:build-type}
-parameter specifies in abstract terms the flags passed to the compiler;
-it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
-debugging information''), which roughly means that code is compiled with
-@code{-O2 -g}, as is the case for Autoconf-based packages by default.
-@end defvr
+The following example spawns a new shell set up for the development of
+GNU@tie{}Guile:
-@defvr {Scheme Variable} dune-build-system
-This variable is exported by @code{(guix build-system dune)}. It
-supports builds of packages using @uref{https://dune.build/, Dune}, a build
-tool for the OCaml programming language. It is implemented as an extension
-of the @code{ocaml-build-system} which is described below. As such, the
-@code{#:ocaml} and @code{#:findlib} parameters can be passed to this build
-system.
+@example
+guix environment guile
+@end example
-It automatically adds the @code{dune} package to the set of inputs.
-Which package is used can be specified with the @code{#:dune}
-parameter.
+If the needed dependencies are not built yet, @command{guix environment}
+automatically builds them. The environment of the new shell is an augmented
+version of the environment that @command{guix environment} was run in.
+It contains the necessary search paths for building the given package
+added to the existing environment variables. To create a ``pure''
+environment, in which the original environment variables have been unset,
+use the @code{--pure} option@footnote{Users sometimes wrongfully augment
+environment variables such as @code{PATH} in their @file{~/.bashrc}
+file. As a consequence, when @code{guix environment} launches it, Bash
+may read @file{~/.bashrc}, thereby introducing ``impurities'' in these
+environment variables. It is an error to define such environment
+variables in @file{.bashrc}; instead, they should be defined in
+@file{.bash_profile}, which is sourced only by log-in shells.
+@xref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}, for
+details on Bash start-up files.}.
-There is no @code{configure} phase because dune packages typically don't
-need to be configured. The @code{#:build-flags} parameter is taken as a
-list of flags passed to the @code{dune} command during the build.
+@vindex GUIX_ENVIRONMENT
+@command{guix environment} defines the @code{GUIX_ENVIRONMENT}
+variable in the shell it spawns; its value is the file name of the
+profile of this environment. This allows users to, say, define a
+specific prompt for development environments in their @file{.bashrc}
+(@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
-The @code{#:jbuild?} parameter can be passed to use the @code{jbuild}
-command instead of the more recent @code{dune} command while building
-a package. Its default value is @code{#f}.
-@end defvr
+@example
+if [ -n "$GUIX_ENVIRONMENT" ]
+then
+ export PS1="\u@@\h \w [dev]\$ "
+fi
+@end example
-@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
-@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies,
-Go build mechanisms}.
+@noindent
+...@: or to browse the profile:
-The user is expected to provide a value for the key @code{#:import-path}
-and, in some cases, @code{#:unpack-path}. The
-@url{https://golang.org/doc/code.html#ImportPaths, import path}
-corresponds to the file system path expected by the package's build
-scripts and any referring packages, and provides a unique way to
-refer to a Go package. It is typically based on a combination of the
-package source code's remote URI and file system hierarchy structure. In
-some cases, you will need to unpack the package's source code to a
-different directory structure than the one indicated by the import path,
-and @code{#:unpack-path} should be used in such cases.
+@example
+$ ls "$GUIX_ENVIRONMENT/bin"
+@end example
-Packages that provide Go libraries should be installed along with their
-source code. The key @code{#:install-source?}, which defaults to
-@code{#t}, controls whether or not the source code is installed. It can
-be set to @code{#f} for packages that only provide executable files.
-@end defvr
+Additionally, more than one package may be specified, in which case the
+union of the inputs for the given packages are used. For example, the
+command below spawns a shell where all of the dependencies of both Guile
+and Emacs are available:
-@defvr {Scheme Variable} glib-or-gtk-build-system
-This variable is exported by @code{(guix build-system glib-or-gtk)}. It
-is intended for use with packages making use of GLib or GTK+.
+@example
+guix environment guile emacs
+@end example
-This build system adds the following two phases to the ones defined by
-@var{gnu-build-system}:
+Sometimes an interactive shell session is not desired. An arbitrary
+command may be invoked by placing the @code{--} token to separate the
+command from the rest of the arguments:
-@table @code
-@item glib-or-gtk-wrap
-The phase @code{glib-or-gtk-wrap} ensures that programs in
-@file{bin/} are able to find GLib ``schemas'' and
-@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
-modules}. This is achieved by wrapping the programs in launch scripts
-that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
-environment variables.
+@example
+guix environment guile -- make -j4
+@end example
-It is possible to exclude specific package outputs from that wrapping
-process by listing their names in the
-@code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
-when an output is known not to contain any GLib or GTK+ binaries, and
-where wrapping would gratuitously add a dependency of that output on
-GLib and GTK+.
+In other situations, it is more convenient to specify the list of
+packages needed in the environment. For example, the following command
+runs @command{python} from an environment containing Python@tie{}2.7 and
+NumPy:
-@item glib-or-gtk-compile-schemas
-The phase @code{glib-or-gtk-compile-schemas} makes sure that all
-@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
-GSettings schemas} of GLib are compiled. Compilation is performed by the
-@command{glib-compile-schemas} program. It is provided by the package
-@code{glib:bin} which is automatically imported by the build system.
-The @code{glib} package providing @command{glib-compile-schemas} can be
-specified with the @code{#:glib} parameter.
-@end table
+@example
+guix environment --ad-hoc python2-numpy python-2.7 -- python
+@end example
-Both phases are executed after the @code{install} phase.
-@end defvr
+Furthermore, one might want the dependencies of a package and also some
+additional packages that are not build-time or runtime dependencies, but
+are useful when developing nonetheless. Because of this, the
+@code{--ad-hoc} flag is positional. Packages appearing before
+@code{--ad-hoc} are interpreted as packages whose dependencies will be
+added to the environment. Packages appearing after are interpreted as
+packages that will be added to the environment directly. For example,
+the following command creates a Guix development environment that
+additionally includes Git and strace:
-@defvr {Scheme Variable} guile-build-system
-This build system is for Guile packages that consist exclusively of Scheme
-code and that are so lean that they don't even have a makefile, let alone a
-@file{configure} script. It compiles Scheme code using @command{guild
-compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and
-installs the @file{.scm} and @file{.go} files in the right place. It also
-installs documentation.
+@example
+guix environment guix --ad-hoc git strace
+@end example
-This build system supports cross-compilation by using the @code{--target}
-option of @command{guild compile}.
+Sometimes it is desirable to isolate the environment as much as
+possible, for maximal purity and reproducibility. In particular, when
+using Guix on a host distro that is not Guix System, it is desirable to
+prevent access to @file{/usr/bin} and other system-wide resources from
+the development environment. For example, the following command spawns
+a Guile REPL in a ``container'' where only the store and the current
+working directory are mounted:
-Packages built with @code{guile-build-system} must provide a Guile package in
-their @code{native-inputs} field.
-@end defvr
+@example
+guix environment --ad-hoc --container guile -- guile
+@end example
-@defvr {Scheme Variable} minify-build-system
-This variable is exported by @code{(guix build-system minify)}. It
-implements a minification procedure for simple JavaScript packages.
+@quotation Note
+The @code{--container} option requires Linux-libre 3.19 or newer.
+@end quotation
-It adds @code{uglify-js} to the set of inputs and uses it to compress
-all JavaScript files in the @file{src} directory. A different minifier
-package can be specified with the @code{#:uglify-js} parameter, but it
-is expected that the package writes the minified code to the standard
-output.
+The available options are summarized below.
-When the input JavaScript files are not all located in the @file{src}
-directory, the parameter @code{#:javascript-files} can be used to
-specify a list of file names to feed to the minifier.
-@end defvr
+@table @code
+@item --root=@var{file}
+@itemx -r @var{file}
+@cindex persistent environment
+@cindex garbage collector root, for environments
+Make @var{file} a symlink to the profile for this environment, and
+register it as a garbage collector root.
-@defvr {Scheme Variable} ocaml-build-system
-This variable is exported by @code{(guix build-system ocaml)}. It implements
-a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists
-of choosing the correct set of commands to run for each package. OCaml
-packages can expect many different commands to be run. This build system will
-try some of them.
+This is useful if you want to protect your environment from garbage
+collection, to make it ``persistent''.
-When the package has a @file{setup.ml} file present at the top-level, it will
-run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and
-@code{ocaml setup.ml -install}. The build system will assume that this file
-was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will take
-care of setting the prefix and enabling tests if they are not disabled. You
-can pass configure and build flags with the @code{#:configure-flags} and
-@code{#:build-flags}. The @code{#:test-flags} key can be passed to change the
-set of flags used to enable tests. The @code{#:use-make?} key can be used to
-bypass this system in the build and install phases.
+When this option is omitted, the environment is protected from garbage
+collection only for the duration of the @command{guix environment}
+session. This means that next time you recreate the same environment,
+you could have to rebuild or re-download packages. @xref{Invoking guix
+gc}, for more on GC roots.
-When the package has a @file{configure} file, it is assumed that it is a
-hand-made configure script that requires a different argument format than
-in the @code{gnu-build-system}. You can add more flags with the
-@code{#:configure-flags} key.
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Create an environment for the package or list of packages that
+@var{expr} evaluates to.
-When the package has a @file{Makefile} file (or @code{#:use-make?} is
-@code{#t}), it will be used and more flags can be passed to the build and
-install phases with the @code{#:make-flags} key.
+For example, running:
-Finally, some packages do not have these files and use a somewhat standard
-location for its build system. In that case, the build system will run
-@code{ocaml pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of
-providing the path to the required findlib module. Additional flags can
-be passed via the @code{#:build-flags} key. Install is taken care of by
-@command{opam-installer}. In this case, the @code{opam} package must
-be added to the @code{native-inputs} field of the package definition.
+@example
+guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
+@end example
-Note that most OCaml packages assume they will be installed in the same
-directory as OCaml, which is not what we want in guix. In particular, they
-will install @file{.so} files in their module's directory, which is usually
-fine because it is in the OCaml compiler directory. In guix though, these
-libraries cannot be found and we use @code{CAML_LD_LIBRARY_PATH}. This
-variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
-@file{.so} libraries should be installed.
-@end defvr
+starts a shell with the environment for this specific variant of the
+PETSc package.
-@defvr {Scheme Variable} python-build-system
-This variable is exported by @code{(guix build-system python)}. It
-implements the more or less standard build procedure used by Python
-packages, which consists in running @code{python setup.py build} and
-then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
+Running:
-For packages that install stand-alone Python programs under @code{bin/},
-it takes care of wrapping these programs so that their @code{PYTHONPATH}
-environment variable points to all the Python libraries they depend on.
+@example
+guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
+@end example
-Which Python package is used to perform the build can be specified with
-the @code{#:python} parameter. This is a useful way to force a package
-to be built for a specific version of the Python interpreter, which
-might be necessary if the package is only compatible with a single
-interpreter version.
+starts a shell with all the base system packages available.
-By default guix calls @code{setup.py} under control of
-@code{setuptools}, much like @command{pip} does. Some packages are not
-compatible with setuptools (and pip), thus you can disable this by
-setting the @code{#:use-setuptools} parameter to @code{#f}.
-@end defvr
+The above commands only use the default output of the given packages.
+To select other outputs, two element tuples can be specified:
-@defvr {Scheme Variable} perl-build-system
-This variable is exported by @code{(guix build-system perl)}. It
-implements the standard build procedure for Perl packages, which either
-consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
-followed by @code{Build} and @code{Build install}; or in running
-@code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
-@code{make} and @code{make install}, depending on which of
-@code{Build.PL} or @code{Makefile.PL} is present in the package
-distribution. Preference is given to the former if both @code{Build.PL}
-and @code{Makefile.PL} exist in the package distribution. This
-preference can be reversed by specifying @code{#t} for the
-@code{#:make-maker?} parameter.
+@example
+guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")'
+@end example
-The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
-passes flags specified by the @code{#:make-maker-flags} or
-@code{#:module-build-flags} parameter, respectively.
+@item --load=@var{file}
+@itemx -l @var{file}
+Create an environment for the package or list of packages that the code
+within @var{file} evaluates to.
-Which Perl package is used can be specified with @code{#:perl}.
-@end defvr
+As an example, @var{file} might contain a definition like this
+(@pxref{Defining Packages}):
-@defvr {Scheme Variable} r-build-system
-This variable is exported by @code{(guix build-system r)}. It
-implements the build procedure used by @uref{http://r-project.org, R}
-packages, which essentially is little more than running @code{R CMD
-INSTALL --library=/gnu/store/@dots{}} in an environment where
-@code{R_LIBS_SITE} contains the paths to all R package inputs. Tests
-are run after installation using the R function
-@code{tools::testInstalledPackage}.
-@end defvr
+@example
+@verbatiminclude environment-gdb.scm
+@end example
-@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
-build system sets the @code{TEXINPUTS} variable to find all TeX source
-files in the inputs.
+@item --manifest=@var{file}
+@itemx -m @var{file}
+Create an environment for the packages contained in the manifest object
+returned by the Scheme code in @var{file}.
-By default it runs @code{luatex} on all files ending on @code{ins}. A
-different engine and format can be specified with the
-@code{#:tex-format} argument. Different build targets can be specified
-with the @code{#:build-targets} argument, which expects a list of file
-names. The build system adds only @code{texlive-bin} and
-@code{texlive-latex-base} (both from @code{(gnu packages tex}) to the
-inputs. Both can be overridden with the arguments @code{#:texlive-bin}
-and @code{#:texlive-latex-base}, respectively.
+This is similar to the same-named option in @command{guix package}
+(@pxref{profile-manifest, @option{--manifest}}) and uses the same
+manifest files.
-The @code{#:tex-directory} parameter tells the build system where to
-install the built files under the texmf tree.
-@end defvr
+@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
+useful for quickly creating an environment without having to write a
+package expression to contain the desired inputs.
-@defvr {Scheme Variable} ruby-build-system
-This variable is exported by @code{(guix build-system ruby)}. It
-implements the RubyGems build procedure used by Ruby packages, which
-involves running @code{gem build} followed by @code{gem install}.
-
-The @code{source} field of a package that uses this build system
-typically references a gem archive, since this is the format that Ruby
-developers use when releasing their software. The build system unpacks
-the gem archive, potentially patches the source, runs the test suite,
-repackages the gem, and installs it. Additionally, directories and
-tarballs may be referenced to allow building unreleased gems from Git or
-a traditional source release tarball.
-
-Which Ruby package is used can be specified with the @code{#:ruby}
-parameter. A list of additional flags to be passed to the @command{gem}
-command can be specified with the @code{#:gem-flags} parameter.
-@end defvr
+For instance, the command:
-@defvr {Scheme Variable} waf-build-system
-This variable is exported by @code{(guix build-system waf)}. It
-implements a build procedure around the @code{waf} script. The common
-phases---@code{configure}, @code{build}, and @code{install}---are
-implemented by passing their names as arguments to the @code{waf}
-script.
+@example
+guix environment --ad-hoc guile guile-sdl -- guile
+@end example
-The @code{waf} script is executed by the Python interpreter. Which
-Python package is used to run the script can be specified with the
-@code{#:python} parameter.
-@end defvr
+runs @command{guile} in an environment where Guile and Guile-SDL are
+available.
-@defvr {Scheme Variable} scons-build-system
-This variable is exported by @code{(guix build-system scons)}. It
-implements the build procedure used by the SCons software construction
-tool. This build system runs @code{scons} to build the package,
-@code{scons test} to run tests, and then @code{scons install} to install
-the package.
+Note that this example implicitly asks for the default output of
+@code{guile} and @code{guile-sdl}, but it is possible to ask for a
+specific output---e.g., @code{glib:bin} asks for the @code{bin} output
+of @code{glib} (@pxref{Packages with Multiple Outputs}).
-Additional flags to be passed to @code{scons} can be specified with the
-@code{#:scons-flags} parameter. The version of Python used to run SCons
-can be specified by selecting the appropriate SCons package with the
-@code{#:scons} parameter.
-@end defvr
+This option may be composed with the default behavior of @command{guix
+environment}. Packages appearing before @code{--ad-hoc} are interpreted
+as packages whose dependencies will be added to the environment, the
+default behavior. Packages appearing after are interpreted as packages
+that will be added to the environment directly.
-@defvr {Scheme Variable} haskell-build-system
-This variable is exported by @code{(guix build-system haskell)}. It
-implements the Cabal build procedure used by Haskell packages, which
-involves running @code{runhaskell Setup.hs configure
---prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
-Instead of installing the package by running @code{runhaskell Setup.hs
-install}, to avoid trying to register libraries in the read-only
-compiler store directory, the build system uses @code{runhaskell
-Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
-addition, the build system generates the package documentation by
-running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
-is passed. Optional Haddock parameters can be passed with the help of
-the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
-not found, the build system looks for @code{Setup.lhs} instead.
+@item --pure
+Unset existing environment variables when building the new environment, except
+those specified with @option{--preserve} (see below.) This has the effect of
+creating an environment in which search paths only contain package inputs.
-Which Haskell compiler is used can be specified with the @code{#:haskell}
-parameter which defaults to @code{ghc}.
-@end defvr
+@item --preserve=@var{regexp}
+@itemx -E @var{regexp}
+When used alongside @option{--pure}, preserve the environment variables
+matching @var{regexp}---in other words, put them on a ``white list'' of
+environment variables that must be preserved. This option can be repeated
+several times.
-@defvr {Scheme Variable} dub-build-system
-This variable is exported by @code{(guix build-system dub)}. It
-implements the Dub build procedure used by D packages, which
-involves running @code{dub build} and @code{dub run}.
-Installation is done by copying the files manually.
+@example
+guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \
+ -- mpirun @dots{}
+@end example
-Which D compiler is used can be specified with the @code{#:ldc}
-parameter which defaults to @code{ldc}.
-@end defvr
+This example runs @command{mpirun} in a context where the only environment
+variables defined are @code{PATH}, environment variables whose name starts
+with @code{SLURM}, as well as the usual ``precious'' variables (@code{HOME},
+@code{USER}, etc.)
-@defvr {Scheme Variable} emacs-build-system
-This variable is exported by @code{(guix build-system emacs)}. It
-implements an installation procedure similar to the packaging system
-of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
+@item --search-paths
+Display the environment variable definitions that make up the
+environment.
-It first creates the @code{@var{package}-autoloads.el} file, then it
-byte compiles all Emacs Lisp files. Differently from the Emacs
-packaging system, the Info documentation files are moved to the standard
-documentation directory and the @file{dir} file is deleted. Each
-package is installed in its own directory under
-@file{share/emacs/site-lisp/guix.d}.
-@end defvr
+@item --system=@var{system}
+@itemx -s @var{system}
+Attempt to build for @var{system}---e.g., @code{i686-linux}.
-@defvr {Scheme Variable} font-build-system
-This variable is exported by @code{(guix build-system font)}. It
-implements an installation procedure for font packages where upstream
-provides pre-compiled TrueType, OpenType, etc.@: font files that merely
-need to be copied into place. It copies font files to standard
-locations in the output directory.
-@end defvr
+@item --container
+@itemx -C
+@cindex container
+Run @var{command} within an isolated container. The current working
+directory outside the container is mapped inside the container.
+Additionally, unless overridden with @code{--user}, a dummy home
+directory is created that matches the current user's home directory, and
+@file{/etc/passwd} is configured accordingly. The spawned process runs
+as the current user outside the container, but has root privileges in
+the context of the container.
-@defvr {Scheme Variable} meson-build-system
-This variable is exported by @code{(guix build-system meson)}. It
-implements the build procedure for packages that use
-@url{http://mesonbuild.com, Meson} as their build system.
+@item --network
+@itemx -N
+For containers, share the network namespace with the host system.
+Containers created without this flag only have access to the loopback
+device.
-It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
-of inputs, and they can be changed with the parameters @code{#:meson}
-and @code{#:ninja} if needed. The default Meson is
-@code{meson-for-build}, which is special because it doesn't clear the
-@code{RUNPATH} of binaries and libraries when they are installed.
+@item --link-profile
+@itemx -P
+For containers, link the environment profile to
+@file{~/.guix-profile} within the container. This is equivalent to
+running the command @command{ln -s $GUIX_ENVIRONMENT ~/.guix-profile}
+within the container. Linking will fail and abort the environment if
+the directory already exists, which will certainly be the case if
+@command{guix environment} was invoked in the user's home directory.
-This build system is an extension of @var{gnu-build-system}, but with the
-following phases changed to some specific for Meson:
+Certain packages are configured to look in
+@code{~/.guix-profile} for configuration files and data;@footnote{For
+example, the @code{fontconfig} package inspects
+@file{~/.guix-profile/share/fonts} for additional fonts.}
+@code{--link-profile} allows these programs to behave as expected within
+the environment.
-@table @code
+@item --user=@var{user}
+@itemx -u @var{user}
+For containers, use the username @var{user} in place of the current
+user. The generated @file{/etc/passwd} entry within the container will
+contain the name @var{user}; the home directory will be
+@file{/home/USER}; and no user GECOS data will be copied. @var{user}
+need not exist on the system.
-@item configure
-The phase runs @code{meson} with the flags specified in
-@code{#:configure-flags}. The flag @code{--build-type} is always set to
-@code{plain} unless something else is specified in @code{#:build-type}.
+Additionally, any shared or exposed path (see @code{--share} and
+@code{--expose} respectively) whose target is within the current user's
+home directory will be remapped relative to @file{/home/USER}; this
+includes the automatic mapping of the current working directory.
-@item build
-The phase runs @code{ninja} to build the package in parallel by default, but
-this can be changed with @code{#:parallel-build?}.
+@example
+# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
+cd $HOME/wd
+guix environment --container --user=foo \
+ --expose=$HOME/test \
+ --expose=/tmp/target=$HOME/target
+@end example
-@item check
-The phase runs @code{ninja} with the target specified in @code{#:test-target},
-which is @code{"test"} by default.
+While this will limit the leaking of user identity through home paths
+and each of the user fields, this is only one useful component of a
+broader privacy/anonymity solution---not one in and of itself.
-@item install
-The phase runs @code{ninja install} and can not be changed.
-@end table
+@item --expose=@var{source}[=@var{target}]
+For containers, expose the file system @var{source} from the host system
+as the read-only file system @var{target} within the container. If
+@var{target} is not specified, @var{source} is used as the target mount
+point in the container.
-Apart from that, the build system also adds the following phases:
+The example below spawns a Guile REPL in a container in which the user's
+home directory is accessible read-only via the @file{/exchange}
+directory:
-@table @code
+@example
+guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
+@end example
-@item fix-runpath
-This phase ensures that all binaries can find the libraries they need.
-It searches for required libraries in subdirectories of the package being
-built, and adds those to @code{RUNPATH} where needed. It also removes
-references to libraries left over from the build phase by
-@code{meson-for-build}, such as test dependencies, that aren't actually
-required for the program to run.
+@item --share=@var{source}[=@var{target}]
+For containers, share the file system @var{source} from the host system
+as the writable file system @var{target} within the container. If
+@var{target} is not specified, @var{source} is used as the target mount
+point in the container.
-@item glib-or-gtk-wrap
-This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
-is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
+The example below spawns a Guile REPL in a container in which the user's
+home directory is accessible for both reading and writing via the
+@file{/exchange} directory:
-@item glib-or-gtk-compile-schemas
-This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
-is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
+@example
+guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile
+@end example
@end table
-@end defvr
-
-Lastly, for packages that do not need anything as sophisticated, a
-``trivial'' build system is provided. It is trivial in the sense that
-it provides basically no support: it does not pull any implicit inputs,
-and does not have a notion of build phases.
-@defvr {Scheme Variable} trivial-build-system
-This variable is exported by @code{(guix build-system trivial)}.
+@command{guix environment}
+also supports all of the common build options that @command{guix
+build} supports (@pxref{Common Build Options}) as well as package
+transformation options (@pxref{Package Transformation Options}).
-This build system requires a @code{#:builder} argument. This argument
-must be a Scheme expression that builds the package output(s)---as
-with @code{build-expression->derivation} (@pxref{Derivations,
-@code{build-expression->derivation}}).
-@end defvr
+@node Invoking guix pack
+@section Invoking @command{guix pack}
-@node The Store
-@section The Store
+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
+is where @command{guix pack} comes in.
-@cindex store
-@cindex store items
-@cindex store paths
+@quotation Note
+If you are looking for ways to exchange binaries among machines that
+already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix
+publish}, and @ref{Invoking guix archive}.
+@end quotation
-Conceptually, the @dfn{store} is the place where derivations that have
-been built successfully are stored---by default, @file{/gnu/store}.
-Sub-directories in the store are referred to as @dfn{store items} or
-sometimes @dfn{store paths}. The store has an associated database that
-contains information such as the store paths referred to by each store
-path, and the list of @emph{valid} store items---results of successful
-builds. This database resides in @file{@var{localstatedir}/guix/db},
-where @var{localstatedir} is the state directory specified @i{via}
-@option{--localstatedir} at configure time, usually @file{/var}.
+@cindex pack
+@cindex bundle
+@cindex application bundle
+@cindex software bundle
+The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or
+@dfn{software bundle}: it creates a tarball or some other archive
+containing the binaries of the software you're interested in, and all
+its dependencies. The resulting archive can be used on any machine that
+does not have Guix, and people can run the exact same binaries as those
+you have with Guix. The pack itself is created in a bit-reproducible
+fashion, so anyone can verify that it really contains the build results
+that you pretend to be shipping.
-The store is @emph{always} accessed by the daemon on behalf of its clients
-(@pxref{Invoking guix-daemon}). To manipulate the store, clients
-connect to the daemon over a Unix-domain socket, send requests to it,
-and read the result---these are remote procedure calls, or RPCs.
+For example, to create a bundle containing Guile, Emacs, Geiser, and all
+their dependencies, you can run:
-@quotation Note
-Users must @emph{never} modify files under @file{/gnu/store} directly.
-This would lead to inconsistencies and break the immutability
-assumptions of Guix's functional model (@pxref{Introduction}).
+@example
+$ guix pack guile emacs geiser
+@dots{}
+/gnu/store/@dots{}-pack.tar.gz
+@end example
-@xref{Invoking guix gc, @command{guix gc --verify}}, for information on
-how to check the integrity of the store and attempt recovery from
-accidental modifications.
-@end quotation
+The result here is a tarball containing a @file{/gnu/store} directory
+with all the relevant packages. The resulting tarball contains a
+@dfn{profile} with the three packages of interest; the profile is the
+same as would be created by @command{guix package -i}. It is this
+mechanism that is used to create Guix's own standalone binary tarball
+(@pxref{Binary Installation}).
-The @code{(guix store)} module provides procedures to connect to the
-daemon, and to perform RPCs. These are described below. By default,
-@code{open-connection}, and thus all the @command{guix} commands,
-connect to the local daemon or to the URI specified by the
-@code{GUIX_DAEMON_SOCKET} environment variable.
+Users of this pack would have to run
+@file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may
+find inconvenient. To work around it, you can create, say, a
+@file{/opt/gnu/bin} symlink to the profile:
-@defvr {Environment Variable} GUIX_DAEMON_SOCKET
-When set, the value of this variable should be a file name or a URI
-designating the daemon endpoint. When it is a file name, it denotes a
-Unix-domain socket to connect to. In addition to file names, the
-supported URI schemes are:
+@example
+guix pack -S /opt/gnu/bin=bin guile emacs geiser
+@end example
-@table @code
-@item file
-@itemx unix
-These are for Unix-domain sockets.
-@code{file:///var/guix/daemon-socket/socket} is equivalent to
-@file{/var/guix/daemon-socket/socket}.
+@noindent
+That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
-@item guix
-@cindex daemon, remote access
-@cindex remote access to the daemon
-@cindex daemon, cluster setup
-@cindex clusters, daemon setup
-These URIs denote connections over TCP/IP, without encryption nor
-authentication of the remote host. The URI must specify the host name
-and optionally a port number (by default port 44146 is used):
+@cindex relocatable binaries, with @command{guix pack}
+What if the recipient of your pack does not have root privileges on
+their machine, and thus cannot unpack it in the root file system? In
+that case, you will want to use the @code{--relocatable} option (see
+below). This option produces @dfn{relocatable binaries}, meaning they
+they can be placed anywhere in the file system hierarchy: in the example
+above, users can unpack your tarball in their home directory and
+directly run @file{./opt/gnu/bin/guile}.
+
+@cindex Docker, build an image with guix pack
+Alternatively, you can produce a pack in the Docker image format using
+the following command:
@example
-guix://master.guix.example.org:1234
+guix pack -f docker guile emacs geiser
@end example
-This setup is suitable on local networks, such as clusters, where only
-trusted nodes may connect to the build daemon at
-@code{master.guix.example.org}.
-
-The @code{--listen} option of @command{guix-daemon} can be used to
-instruct it to listen for TCP connections (@pxref{Invoking guix-daemon,
-@code{--listen}}).
+@noindent
+The result is a tarball that can be passed to the @command{docker load}
+command. See the
+@uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
+documentation} for more information.
-@item ssh
-@cindex SSH access to build daemons
-These URIs allow you to connect to a remote daemon over
-SSH@footnote{This feature requires Guile-SSH (@pxref{Requirements}).}.
-A typical URL might look like this:
+@cindex Singularity, build an image with guix pack
+@cindex SquashFS, build an image with guix pack
+Yet another option is to produce a SquashFS image with the following
+command:
@example
-ssh://charlie@@guix.example.org:22
+guix pack -f squashfs guile emacs geiser
@end example
-As for @command{guix copy}, the usual OpenSSH client configuration files
-are honored (@pxref{Invoking guix copy}).
-@end table
+@noindent
+The result is a SquashFS file system image that can either be mounted or
+directly be used as a file system container image with the
+@uref{http://singularity.lbl.gov, Singularity container execution
+environment}, using commands like @command{singularity shell} or
+@command{singularity exec}.
-Additional URI schemes may be supported in the future.
+Several command-line options allow you to customize your pack:
-@c XXX: Remove this note when the protocol incurs fewer round trips
-@c and when (guix derivations) no longer relies on file system access.
-@quotation Note
-The ability to connect to remote build daemons is considered
-experimental as of @value{VERSION}. Please get in touch with us to
-share any problems or suggestions you may have (@pxref{Contributing}).
-@end quotation
-@end defvr
+@table @code
+@item --format=@var{format}
+@itemx -f @var{format}
+Produce a pack in the given @var{format}.
-@deffn {Scheme Procedure} open-connection [@var{uri}] [#:reserve-space? #t]
-Connect to the daemon over the Unix-domain socket at @var{uri} (a string). When
-@var{reserve-space?} is true, instruct it to reserve a little bit of
-extra space on the file system so that the garbage collector can still
-operate should the disk become full. Return a server object.
+The available formats are:
-@var{file} defaults to @var{%default-socket-path}, which is the normal
-location given the options that were passed to @command{configure}.
-@end deffn
+@table @code
+@item tarball
+This is the default format. It produces a tarball containing all the
+specified binaries and symlinks.
-@deffn {Scheme Procedure} close-connection @var{server}
-Close the connection to @var{server}.
-@end deffn
+@item docker
+This produces a tarball that follows the
+@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
+Docker Image Specification}.
-@defvr {Scheme Variable} current-build-output-port
-This variable is bound to a SRFI-39 parameter, which refers to the port
-where build and error logs sent by the daemon should be written.
-@end defvr
+@item squashfs
+This produces a SquashFS image containing all the specified binaries and
+symlinks, as well as empty mount points for virtual file systems like
+procfs.
+@end table
-Procedures that make RPCs all take a server object as their first
-argument.
+@cindex relocatable binaries
+@item --relocatable
+@itemx -R
+Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
+anywhere in the file system hierarchy and run from there.
-@deffn {Scheme Procedure} valid-path? @var{server} @var{path}
-@cindex invalid store items
-Return @code{#t} when @var{path} designates a valid store item and
-@code{#f} otherwise (an invalid item may exist on disk but still be
-invalid, for instance because it is the result of an aborted or failed
-build.)
+When this option is passed once, the resulting binaries require support for
+@dfn{user namespaces} in the kernel Linux; when passed
+@emph{twice}@footnote{Here's a trick to memorize it: @code{-RR}, which adds
+PRoot support, can be thought of as the abbreviation of ``Really
+Relocatable''. Neat, isn't it?}, relocatable binaries fall to back to PRoot
+if user namespaces are unavailable, and essentially work anywhere---see below
+for the implications.
-A @code{&nix-protocol-error} condition is raised if @var{path} is not
-prefixed by the store directory (@file{/gnu/store}).
-@end deffn
+For example, if you create a pack containing Bash with:
-@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
-Add @var{text} under file @var{name} in the store, and return its store
-path. @var{references} is the list of store paths referred to by the
-resulting store path.
-@end deffn
+@example
+guix pack -RR -S /mybin=bin bash
+@end example
-@deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
-Build @var{derivations} (a list of @code{<derivation>} objects or
-derivation paths), and return when the worker is done building them.
-Return @code{#t} on success.
-@end deffn
+@noindent
+...@: you can copy that pack to a machine that lacks Guix, and from your
+home directory as a normal user, run:
-Note that the @code{(guix monads)} module provides a monad as well as
-monadic versions of the above procedures, with the goal of making it
-more convenient to work with code that accesses the store (@pxref{The
-Store Monad}).
+@example
+tar xf pack.tar.gz
+./mybin/sh
+@end example
-@c FIXME
-@i{This section is currently incomplete.}
+@noindent
+In that shell, if you type @code{ls /gnu/store}, you'll notice that
+@file{/gnu/store} shows up and contains all the dependencies of
+@code{bash}, even though the machine actually lacks @file{/gnu/store}
+altogether! That is probably the simplest way to deploy Guix-built
+software on a non-Guix machine.
-@node Derivations
-@section Derivations
+@quotation Note
+By default, relocatable binaries rely on the @dfn{user namespace} feature of
+the kernel Linux, which allows unprivileged users to mount or change root.
+Old versions of Linux did not support it, and some GNU/Linux distributions
+turn it off.
+
+To produce relocatable binaries that work even in the absence of user
+namespaces, pass @option{--relocatable} or @option{-R} @emph{twice}. In that
+case, binaries will try user namespace support and fall back to PRoot if user
+namespaces are not supported.
+
+The @uref{https://proot-me.github.io/, PRoot} program provides the necessary
+support for file system virtualization. It achieves that by using the
+@code{ptrace} system call on the running program. This approach has the
+advantage to work without requiring special kernel support, but it incurs
+run-time overhead every time a system call is made.
+@end quotation
-@cindex derivations
-Low-level build actions and the environment in which they are performed
-are represented by @dfn{derivations}. A derivation contains the
-following pieces of information:
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Consider the package @var{expr} evaluates to.
-@itemize
-@item
-The outputs of the derivation---derivations produce at least one file or
-directory in the store, but may produce more.
+This has the same purpose as the same-named option in @command{guix
+build} (@pxref{Additional Build Options, @code{--expression} in
+@command{guix build}}).
-@item
-The inputs of the derivations, which may be other derivations or plain
-files in the store (patches, build scripts, etc.)
+@item --manifest=@var{file}
+@itemx -m @var{file}
+Use the packages contained in the manifest object returned by the Scheme
+code in @var{file}.
-@item
-The system type targeted by the derivation---e.g., @code{x86_64-linux}.
+This has a similar purpose as the same-named option in @command{guix
+package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
+same manifest files. It allows you to define a collection of packages
+once and use it both for creating profiles and for creating archives
+for use on machines that do not have Guix installed. Note that you can
+specify @emph{either} a manifest file @emph{or} a list of packages,
+but not both.
-@item
-The file name of a build script in the store, along with the arguments
-to be passed.
+@item --system=@var{system}
+@itemx -s @var{system}
+Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
+the system type of the build host.
-@item
-A list of environment variables to be defined.
+@item --target=@var{triplet}
+@cindex cross-compilation
+Cross-build for @var{triplet}, which must be a valid GNU triplet, such
+as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
+configuration triplets,, autoconf, Autoconf}).
-@end itemize
+@item --compression=@var{tool}
+@itemx -C @var{tool}
+Compress the resulting tarball using @var{tool}---one of @code{gzip},
+@code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no compression.
-@cindex derivation path
-Derivations allow clients of the daemon to communicate build actions to
-the store. They exist in two forms: as an in-memory representation,
-both on the client- and daemon-side, and as files in the store whose
-name end in @code{.drv}---these files are referred to as @dfn{derivation
-paths}. Derivations paths can be passed to the @code{build-derivations}
-procedure to perform the build actions they prescribe (@pxref{The
-Store}).
+@item --symlink=@var{spec}
+@itemx -S @var{spec}
+Add the symlinks specified by @var{spec} to the pack. This option can
+appear several times.
-@cindex fixed-output derivations
-Operations such as file downloads and version-control checkouts for
-which the expected content hash is known in advance are modeled as
-@dfn{fixed-output derivations}. Unlike regular derivations, the outputs
-of a fixed-output derivation are independent of its inputs---e.g., a
-source code download produces the same result regardless of the download
-method and tools being used.
+@var{spec} has the form @code{@var{source}=@var{target}}, where
+@var{source} is the symlink that will be created and @var{target} is the
+symlink target.
-The @code{(guix derivations)} module provides a representation of
-derivations as Scheme objects, along with procedures to create and
-otherwise manipulate derivations. The lowest-level primitive to create
-a derivation is the @code{derivation} procedure:
+For instance, @code{-S /opt/gnu/bin=bin} creates a @file{/opt/gnu/bin}
+symlink pointing to the @file{bin} sub-directory of the profile.
-@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
- @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
- [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
- [#:system (%current-system)] [#:references-graphs #f] @
- [#:allowed-references #f] [#:disallowed-references #f] @
- [#:leaked-env-vars #f] [#:local-build? #f] @
- [#:substitutable? #t] [#:properties '()]
-Build a derivation with the given arguments, and return the resulting
-@code{<derivation>} object.
+@item --save-provenance
+Save provenance information for the packages passed on the command line.
+Provenance information includes the URL and commit of the channels in use
+(@pxref{Channels}).
-When @var{hash} and @var{hash-algo} are given, a
-@dfn{fixed-output derivation} is created---i.e., one whose result is
-known in advance, such as a file download. If, in addition,
-@var{recursive?} is true, then that fixed output may be an executable
-file or a directory and @var{hash} must be the hash of an archive
-containing this output.
+Provenance information is saved in the
+@file{/gnu/store/@dots{}-profile/manifest} file in the pack, along with the
+usual package metadata---the name and version of each package, their
+propagated inputs, and so on. It is useful information to the recipient of
+the pack, who then knows how the pack was (supposedly) obtained.
-When @var{references-graphs} is true, it must be a list of file
-name/store path pairs. In that case, the reference graph of each store
-path is exported in the build environment in the corresponding file, in
-a simple text format.
+This option is not enabled by default because, like timestamps, provenance
+information contributes nothing to the build process. In other words, there
+is an infinity of channel URLs and commit IDs that can lead to the same pack.
+Recording such ``silent'' metadata in the output thus potentially breaks the
+source-to-binary bitwise reproducibility property.
-When @var{allowed-references} is true, it must be a list of store items
-or outputs that the derivation's output may refer to. Likewise,
-@var{disallowed-references}, if true, must be a list of things the
-outputs may @emph{not} refer to.
+@item --localstatedir
+@itemx --profile-name=@var{name}
+Include the ``local state directory'', @file{/var/guix}, in the resulting
+pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}}
+profile---by default @var{name} is @code{guix-profile}, which corresponds to
+@file{~root/.guix-profile}.
-When @var{leaked-env-vars} is true, it must be a list of strings
-denoting environment variables that are allowed to ``leak'' from the
-daemon's environment to the build environment. This is only applicable
-to fixed-output derivations---i.e., when @var{hash} is true. The main
-use is to allow variables such as @code{http_proxy} to be passed to
-derivations that download files.
+@file{/var/guix} contains the store database (@pxref{The Store}) as well
+as garbage-collector roots (@pxref{Invoking guix gc}). Providing it in
+the pack means that the store is ``complete'' and manageable by Guix;
+not providing it pack means that the store is ``dead'': items cannot be
+added to it or removed from it after extraction of the pack.
-When @var{local-build?} is true, declare that the derivation is not a
-good candidate for offloading and should rather be built locally
-(@pxref{Daemon Offload Setup}). This is the case for small derivations
-where the costs of data transfers would outweigh the benefits.
+One use case for this is the Guix self-contained binary tarball
+(@pxref{Binary Installation}).
-When @var{substitutable?} is false, declare that substitutes of the
-derivation's output should not be used (@pxref{Substitutes}). This is
-useful, for instance, when building packages that capture details of the
-host CPU instruction set.
+@item --bootstrap
+Use the bootstrap binaries to build the pack. This option is only
+useful to Guix developers.
+@end table
-@var{properties} must be an association list describing ``properties'' of the
-derivation. It is kept as-is, uninterpreted, in the derivation.
-@end deffn
+In addition, @command{guix pack} supports all the common build options
+(@pxref{Common Build Options}) and all the package transformation
+options (@pxref{Package Transformation Options}).
-@noindent
-Here's an example with a shell script as its builder, assuming
-@var{store} is an open connection to the daemon, and @var{bash} points
-to a Bash executable in the store:
-@lisp
-(use-modules (guix utils)
- (guix store)
- (guix derivations))
+@c *********************************************************************
+@node Programming Interface
+@chapter Programming Interface
-(let ((builder ; add the Bash script to the store
- (add-text-to-store store "my-builder.sh"
- "echo hello world > $out\n" '())))
- (derivation store "foo"
- bash `("-e" ,builder)
- #:inputs `((,bash) (,builder))
- #:env-vars '(("HOME" . "/homeless"))))
-@result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
-@end lisp
+GNU Guix provides several Scheme programming interfaces (APIs) to
+define, build, and query packages. The first interface allows users to
+write high-level package definitions. These definitions refer to
+familiar packaging concepts, such as the name and version of a package,
+its build system, and its dependencies. These definitions can then be
+turned into concrete build actions.
-As can be guessed, this primitive is cumbersome to use directly. A
-better approach is to write build scripts in Scheme, of course! The
-best course of action for that is to write the build code as a
-``G-expression'', and to pass it to @code{gexp->derivation}. For more
-information, @pxref{G-Expressions}.
+Build actions are performed by the Guix daemon, on behalf of users. In a
+standard setup, the daemon has write access to the store---the
+@file{/gnu/store} directory---whereas users do not. The recommended
+setup also has the daemon perform builds in chroots, under a specific
+build users, to minimize interference with the rest of the system.
-Once upon a time, @code{gexp->derivation} did not exist and constructing
-derivations with build code written in Scheme was achieved with
-@code{build-expression->derivation}, documented below. This procedure
-is now deprecated in favor of the much nicer @code{gexp->derivation}.
+@cindex derivation
+Lower-level APIs are available to interact with the daemon and the
+store. To instruct the daemon to perform a build action, users actually
+provide it with a @dfn{derivation}. A derivation is a low-level
+representation of the build actions to be taken, and the environment in
+which they should occur---derivations are to package definitions what
+assembly is to C programs. The term ``derivation'' comes from the fact
+that build results @emph{derive} from them.
-@deffn {Scheme Procedure} build-expression->derivation @var{store} @
- @var{name} @var{exp} @
- [#:system (%current-system)] [#:inputs '()] @
- [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
- [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
- [#:references-graphs #f] [#:allowed-references #f] @
- [#:disallowed-references #f] @
- [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
-Return a derivation that executes Scheme expression @var{exp} as a
-builder for derivation @var{name}. @var{inputs} must be a list of
-@code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
-@code{"out"} is assumed. @var{modules} is a list of names of Guile
-modules from the current search path to be copied in the store,
-compiled, and made available in the load path during the execution of
-@var{exp}---e.g., @code{((guix build utils) (guix build
-gnu-build-system))}.
+This chapter describes all these APIs in turn, starting from high-level
+package definitions.
-@var{exp} is evaluated in an environment where @code{%outputs} is bound
-to a list of output/path pairs, and where @code{%build-inputs} is bound
-to a list of string/output-path pairs made from @var{inputs}.
-Optionally, @var{env-vars} is a list of string pairs specifying the name
-and value of environment variables visible to the builder. The builder
-terminates by passing the result of @var{exp} to @code{exit}; thus, when
-@var{exp} returns @code{#f}, the build is considered to have failed.
+@menu
+* Package Modules:: Packages from the programmer's viewpoint.
+* Defining Packages:: Defining new packages.
+* Build Systems:: Specifying how packages are built.
+* The Store:: Manipulating the package store.
+* Derivations:: Low-level interface to package derivations.
+* The Store Monad:: Purely functional interface to the store.
+* G-Expressions:: Manipulating build expressions.
+* Invoking guix repl:: Fiddling with Guix interactively.
+@end menu
-@var{exp} is built using @var{guile-for-build} (a derivation). When
-@var{guile-for-build} is omitted or is @code{#f}, the value of the
-@code{%guile-for-build} fluid is used instead.
+@node Package Modules
+@section Package Modules
-See the @code{derivation} procedure for the meaning of
-@var{references-graphs}, @var{allowed-references},
-@var{disallowed-references}, @var{local-build?}, and
-@var{substitutable?}.
-@end deffn
+From a programming viewpoint, the package definitions of the
+GNU distribution are provided by Guile modules in the @code{(gnu packages
+@dots{})} name space@footnote{Note that packages under the @code{(gnu
+packages @dots{})} module name space are not necessarily ``GNU
+packages''. This module naming scheme follows the usual Guile module
+naming convention: @code{gnu} means that these modules are distributed
+as part of the GNU system, and @code{packages} identifies modules that
+define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
+Reference Manual}). For instance, the @code{(gnu packages emacs)}
+module exports a variable named @code{emacs}, which is bound to a
+@code{<package>} object (@pxref{Defining Packages}).
-@noindent
-Here's an example of a single-output derivation that creates a directory
-containing one file:
+The @code{(gnu packages @dots{})} module name space is
+automatically scanned for packages by the command-line tools. For
+instance, when running @code{guix package -i emacs}, all the @code{(gnu
+packages @dots{})} modules are scanned until one that exports a package
+object whose name is @code{emacs} is found. This package search
+facility is implemented in the @code{(gnu packages)} module.
-@lisp
-(let ((builder '(let ((out (assoc-ref %outputs "out")))
- (mkdir out) ; create /gnu/store/@dots{}-goo
- (call-with-output-file (string-append out "/test")
- (lambda (p)
- (display '(hello guix) p))))))
- (build-expression->derivation store "goo" builder))
+@cindex customization, of packages
+@cindex package module search path
+Users can store package definitions in modules with different
+names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
+name and module name must match. For instance, the @code{(my-packages
+emacs)} module must be stored in a @file{my-packages/emacs.scm} file
+relative to the load path specified with @option{--load-path} or
+@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
+guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
+these package definitions visible to the user interfaces:
-@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
-@end lisp
+@enumerate
+@item
+By adding the directory containing your package modules to the search path
+with the @code{-L} flag of @command{guix package} and other commands
+(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH}
+environment variable described below.
+@item
+By defining a @dfn{channel} and configuring @command{guix pull} so that it
+pulls from it. A channel is essentially a Git repository containing package
+modules. @xref{Channels}, for more information on how to define and use
+channels.
+@end enumerate
-@node The Store Monad
-@section The Store Monad
+@code{GUIX_PACKAGE_PATH} works similarly to other search path variables:
-@cindex monad
+@defvr {Environment Variable} GUIX_PACKAGE_PATH
+This is a colon-separated list of directories to search for additional
+package modules. Directories listed in this variable take precedence
+over the own modules of the distribution.
+@end defvr
-The procedures that operate on the store described in the previous
-sections all take an open connection to the build daemon as their first
-argument. Although the underlying model is functional, they either have
-side effects or depend on the current state of the store.
+The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
+each package is built based solely on other packages in the
+distribution. The root of this dependency graph is a small set of
+@dfn{bootstrap binaries}, provided by the @code{(gnu packages
+bootstrap)} module. For more information on bootstrapping,
+@pxref{Bootstrapping}.
-The former is inconvenient: the connection to the build daemon has to be
-carried around in all those functions, making it impossible to compose
-functions that do not take that parameter with functions that do. The
-latter can be problematic: since store operations have side effects
-and/or depend on external state, they have to be properly sequenced.
+@node Defining Packages
+@section Defining Packages
-@cindex monadic values
-@cindex monadic functions
-This is where the @code{(guix monads)} module comes in. This module
-provides a framework for working with @dfn{monads}, and a particularly
-useful monad for our uses, the @dfn{store monad}. Monads are a
-construct that allows two things: associating ``context'' with values
-(in our case, the context is the store), and building sequences of
-computations (here computations include accesses to the store). Values
-in a monad---values that carry this additional context---are called
-@dfn{monadic values}; procedures that return such values are called
-@dfn{monadic procedures}.
+The high-level interface to package definitions is implemented in the
+@code{(guix packages)} and @code{(guix build-system)} modules. As an
+example, the package definition, or @dfn{recipe}, for the GNU Hello
+package looks like this:
+
+@example
+(define-module (gnu packages hello)
+ #:use-module (guix packages)
+ #:use-module (guix download)
+ #:use-module (guix build-system gnu)
+ #:use-module (guix licenses)
+ #:use-module (gnu packages gawk))
+
+(define-public hello
+ (package
+ (name "hello")
+ (version "2.10")
+ (source (origin
+ (method url-fetch)
+ (uri (string-append "mirror://gnu/hello/hello-" version
+ ".tar.gz"))
+ (sha256
+ (base32
+ "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
+ (build-system gnu-build-system)
+ (arguments '(#:configure-flags '("--enable-silent-rules")))
+ (inputs `(("gawk" ,gawk)))
+ (synopsis "Hello, GNU world: An example GNU package")
+ (description "Guess what GNU Hello prints!")
+ (home-page "http://www.gnu.org/software/hello/")
+ (license gpl3+)))
+@end example
+
+@noindent
+Without being a Scheme expert, the reader may have guessed the meaning
+of the various fields here. This expression binds the variable
+@code{hello} to a @code{<package>} object, which is essentially a record
+(@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
+This package object can be inspected using procedures found in the
+@code{(guix packages)} module; for instance, @code{(package-name hello)}
+returns---surprise!---@code{"hello"}.
+
+With luck, you may be able to import part or all of the definition of
+the package you are interested in from another repository, using the
+@code{guix import} command (@pxref{Invoking guix import}).
+
+In the example above, @var{hello} is defined in a module of its own,
+@code{(gnu packages hello)}. Technically, this is not strictly
+necessary, but it is convenient to do so: all the packages defined in
+modules under @code{(gnu packages @dots{})} are automatically known to
+the command-line tools (@pxref{Package Modules}).
+
+There are a few points worth noting in the above package definition:
+
+@itemize
+@item
+The @code{source} field of the package is an @code{<origin>} object
+(@pxref{origin Reference}, for the complete reference).
+Here, the @code{url-fetch} method from @code{(guix download)} is used,
+meaning that the source is a file to be downloaded over FTP or HTTP.
+
+The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
+the GNU mirrors defined in @code{(guix download)}.
+
+The @code{sha256} field specifies the expected SHA256 hash of the file
+being downloaded. It is mandatory, and allows Guix to check the
+integrity of the file. The @code{(base32 @dots{})} form introduces the
+base32 representation of the hash. You can obtain this information with
+@code{guix download} (@pxref{Invoking guix download}) and @code{guix
+hash} (@pxref{Invoking guix hash}).
+
+@cindex patches
+When needed, the @code{origin} form can also have a @code{patches} field
+listing patches to be applied, and a @code{snippet} field giving a
+Scheme expression to modify the source code.
+
+@item
+@cindex GNU Build System
+The @code{build-system} field specifies the procedure to build the
+package (@pxref{Build Systems}). Here, @var{gnu-build-system}
+represents the familiar GNU Build System, where packages may be
+configured, built, and installed with the usual @code{./configure &&
+make && make check && make install} command sequence.
+
+@item
+The @code{arguments} field specifies options for the build system
+(@pxref{Build Systems}). Here it is interpreted by
+@var{gnu-build-system} as a request run @file{configure} with the
+@code{--enable-silent-rules} flag.
+
+@cindex quote
+@cindex quoting
+@findex '
+@findex quote
+What about these quote (@code{'}) characters? They are Scheme syntax to
+introduce a literal list; @code{'} is synonymous with @code{quote}.
+@xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual},
+for details. Here the value of the @code{arguments} field is a list of
+arguments passed to the build system down the road, as with @code{apply}
+(@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference
+Manual}).
+
+The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
+(@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
+@code{#:configure-flags} is a keyword used to pass a keyword argument
+to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
+Reference Manual}).
+
+@item
+The @code{inputs} field specifies inputs to the build process---i.e.,
+build-time or run-time dependencies of the package. Here, we define an
+input called @code{"gawk"} whose value is that of the @var{gawk}
+variable; @var{gawk} is itself bound to a @code{<package>} object.
+
+@cindex backquote (quasiquote)
+@findex `
+@findex quasiquote
+@cindex comma (unquote)
+@findex ,
+@findex unquote
+@findex ,@@
+@findex unquote-splicing
+Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows
+us to introduce a literal list in the @code{inputs} field, while
+@code{,} (a comma, synonymous with @code{unquote}) allows us to insert a
+value in that list (@pxref{Expression Syntax, unquote,, guile, GNU Guile
+Reference Manual}).
+
+Note that GCC, Coreutils, Bash, and other essential tools do not need to
+be specified as inputs here. Instead, @var{gnu-build-system} takes care
+of ensuring that they are present (@pxref{Build Systems}).
+
+However, any other dependencies need to be specified in the
+@code{inputs} field. Any dependency not specified here will simply be
+unavailable to the build process, possibly leading to a build failure.
+@end itemize
+
+@xref{package Reference}, for a full description of possible fields.
+
+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
+you encounter (@pxref{Debugging Build Failures}). You can easily jump back to the
+package definition using the @command{guix edit} command
+(@pxref{Invoking guix edit}).
+@xref{Packaging Guidelines}, for
+more information on how to test package definitions, and
+@ref{Invoking guix lint}, for information on how to check a definition
+for style conformance.
+@vindex GUIX_PACKAGE_PATH
+Lastly, @pxref{Channels}, for information
+on how to extend the distribution by adding your own package definitions
+in a ``channel''.
+
+Finally, updating the package definition to a new upstream version
+can be partly automated by the @command{guix refresh} command
+(@pxref{Invoking guix refresh}).
+
+Behind the scenes, a derivation corresponding to the @code{<package>}
+object is first computed by the @code{package-derivation} procedure.
+That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
+The build actions it prescribes may then be realized by using the
+@code{build-derivations} procedure (@pxref{The Store}).
+
+@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
+Return the @code{<derivation>} object of @var{package} for @var{system}
+(@pxref{Derivations}).
+
+@var{package} must be a valid @code{<package>} object, and @var{system}
+must be a string denoting the target system type---e.g.,
+@code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
+must be a connection to the daemon, which operates on the store
+(@pxref{The Store}).
+@end deffn
+
+@noindent
+@cindex cross-compilation
+Similarly, it is possible to compute a derivation that cross-builds a
+package for some other system:
+
+@deffn {Scheme Procedure} package-cross-derivation @var{store} @
+ @var{package} @var{target} [@var{system}]
+Return the @code{<derivation>} object of @var{package} cross-built from
+@var{system} to @var{target}.
+
+@var{target} must be a valid GNU triplet denoting the target hardware
+and operating system, such as @code{"mips64el-linux-gnu"}
+(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
+Configure and Build System}).
+@end deffn
+
+@cindex package transformations
+@cindex input rewriting
+@cindex dependency tree rewriting
+Packages can be manipulated in arbitrary ways. An example of a useful
+transformation is @dfn{input rewriting}, whereby the dependency tree of
+a package is rewritten by replacing specific inputs by others:
+
+@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
+ [@var{rewrite-name}]
+Return a procedure that, when passed a package, replaces its direct and
+indirect dependencies (but not its implicit inputs) according to
+@var{replacements}. @var{replacements} is a list of package pairs; the
+first element of each pair is the package to replace, and the second one
+is the replacement.
+
+Optionally, @var{rewrite-name} is a one-argument procedure that takes
+the name of a package and returns its new name after rewrite.
+@end deffn
+
+@noindent
+Consider this example:
+
+@example
+(define libressl-instead-of-openssl
+ ;; This is a procedure to replace OPENSSL by LIBRESSL,
+ ;; recursively.
+ (package-input-rewriting `((,openssl . ,libressl))))
+
+(define git-with-libressl
+ (libressl-instead-of-openssl git))
+@end example
+
+@noindent
+Here we first define a rewriting procedure that replaces @var{openssl}
+with @var{libressl}. Then we use it to define a @dfn{variant} of the
+@var{git} package that uses @var{libressl} instead of @var{openssl}.
+This is exactly what the @option{--with-input} command-line option does
+(@pxref{Package Transformation Options, @option{--with-input}}).
+
+The following variant of @code{package-input-rewriting} can match packages to
+be replaced by name rather than by identity.
+
+@deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements}
+Return a procedure that, given a package, applies the given @var{replacements} to
+all the package graph (excluding implicit inputs). @var{replacements} is a list of
+spec/procedures pair; each spec is a package specification such as @code{"gcc"} or
+@code{"guile@@2"}, and each procedure takes a matching package and returns a
+replacement for that package.
+@end deffn
+
+The example above could be rewritten this way:
+
+@example
+(define libressl-instead-of-openssl
+ ;; Replace all the packages called "openssl" with LibreSSL.
+ (package-input-rewriting/spec `(("openssl" . ,(const libressl)))))
+@end example
+
+The key difference here is that, this time, packages are matched by spec and
+not by identity. In other words, any package in the graph that is called
+@code{openssl} will be replaced.
+
+A more generic procedure to rewrite a package dependency graph is
+@code{package-mapping}: it supports arbitrary changes to nodes in the
+graph.
+
+@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}]
+Return a procedure that, given a package, applies @var{proc} to all the packages
+depended on and returns the resulting package. The procedure stops recursion
+when @var{cut?} returns true for a given package.
+@end deffn
+
+@menu
+* package Reference:: The package data type.
+* origin Reference:: The origin data type.
+@end menu
+
+
+@node package Reference
+@subsection @code{package} Reference
+
+This section summarizes all the options available in @code{package}
+declarations (@pxref{Defining Packages}).
+
+@deftp {Data Type} package
+This is the data type representing a package recipe.
+
+@table @asis
+@item @code{name}
+The name of the package, as a string.
+
+@item @code{version}
+The version of the package, as a string.
+
+@item @code{source}
+An object telling how the source code for the package should be
+acquired. Most of the time, this is an @code{origin} object, which
+denotes a file fetched from the Internet (@pxref{origin Reference}). It
+can also be any other ``file-like'' object such as a @code{local-file},
+which denotes a file from the local file system (@pxref{G-Expressions,
+@code{local-file}}).
+
+@item @code{build-system}
+The build system that should be used to build the package (@pxref{Build
+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.
+
+@item @code{inputs} (default: @code{'()})
+@itemx @code{native-inputs} (default: @code{'()})
+@itemx @code{propagated-inputs} (default: @code{'()})
+@cindex inputs, of packages
+These fields list dependencies of the package. Each one is a list of
+tuples, where each tuple has a label for the input (a string) as its
+first element, a package, origin, or derivation as its second element,
+and optionally the name of the output thereof that should be used, which
+defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for
+more on package outputs). For example, the list below specifies three
+inputs:
+
+@example
+`(("libffi" ,libffi)
+ ("libunistring" ,libunistring)
+ ("glib:bin" ,glib "bin")) ;the "bin" output of Glib
+@end example
+
+@cindex cross compilation, package dependencies
+The distinction between @code{native-inputs} and @code{inputs} is
+necessary when considering cross-compilation. When cross-compiling,
+dependencies listed in @code{inputs} are built for the @emph{target}
+architecture; conversely, dependencies listed in @code{native-inputs}
+are built for the architecture of the @emph{build} machine.
+
+@code{native-inputs} is typically used to list tools needed at
+build time, but not at run time, such as Autoconf, Automake, pkg-config,
+Gettext, or Bison. @command{guix lint} can report likely mistakes in
+this area (@pxref{Invoking guix lint}).
+
+@anchor{package-propagated-inputs}
+Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
+specified packages will be automatically installed alongside the package
+they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
+package}}, for information on how @command{guix package} deals with
+propagated inputs.)
+
+For example this is necessary when a C/C++ library needs headers of
+another library to compile, or when a pkg-config file refers to another
+one @i{via} its @code{Requires} field.
+
+Another example where @code{propagated-inputs} is useful is for languages
+that lack a facility to record the run-time search path akin to the
+@code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
+more. To ensure that libraries written in those languages can find
+library code they depend on at run time, run-time dependencies must be
+listed in @code{propagated-inputs} rather than @code{inputs}.
+
+@item @code{self-native-input?} (default: @code{#f})
+This is a Boolean field telling whether the package should use itself as
+a native input when cross-compiling.
+
+@item @code{outputs} (default: @code{'("out")})
+The list of output names of the package. @xref{Packages with Multiple
+Outputs}, for typical uses of additional outputs.
+
+@item @code{native-search-paths} (default: @code{'()})
+@itemx @code{search-paths} (default: @code{'()})
+A list of @code{search-path-specification} objects describing
+search-path environment variables honored by the package.
+
+@item @code{replacement} (default: @code{#f})
+This must be either @code{#f} or a package object that will be used as a
+@dfn{replacement} for this package. @xref{Security Updates, grafts},
+for details.
+
+@item @code{synopsis}
+A one-line description of the package.
+
+@item @code{description}
+A more elaborate description of the package.
+
+@item @code{license}
+@cindex license, of packages
+The license of the package; a value from @code{(guix licenses)},
+or a list of such values.
+
+@item @code{home-page}
+The URL to the home-page of the package, as a string.
+
+@item @code{supported-systems} (default: @var{%supported-systems})
+The list of systems supported by the package, as strings of the form
+@code{architecture-kernel}, for example @code{"x86_64-linux"}.
+
+@item @code{maintainers} (default: @code{'()})
+The list of maintainers of the package, as @code{maintainer} objects.
+
+@item @code{location} (default: source location of the @code{package} form)
+The source location of the package. It is useful to override this when
+inheriting from another package, in which case this field is not
+automatically corrected.
+@end table
+@end deftp
+
+
+@node origin Reference
+@subsection @code{origin} Reference
+
+This section summarizes all the options available in @code{origin}
+declarations (@pxref{Defining Packages}).
+
+@deftp {Data Type} origin
+This is the data type representing a source code origin.
+
+@table @asis
+@item @code{uri}
+An object containing the URI of the source. The object type depends on
+the @code{method} (see below). For example, when using the
+@var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
+values are: a URL represented as a string, or a list thereof.
+
+@item @code{method}
+A procedure that handles the URI.
+
+Examples include:
+
+@table @asis
+@item @var{url-fetch} from @code{(guix download)}
+download a file from the HTTP, HTTPS, or FTP URL specified in the
+@code{uri} field;
+
+@vindex git-fetch
+@item @var{git-fetch} from @code{(guix git-download)}
+clone the Git version control repository, and check out the revision
+specified in the @code{uri} field as a @code{git-reference} object; a
+@code{git-reference} looks like this:
+
+@example
+(git-reference
+ (url "git://git.debian.org/git/pkg-shadow/shadow")
+ (commit "v4.1.5.1"))
+@end example
+@end table
+
+@item @code{sha256}
+A bytevector containing the SHA-256 hash of the source. Typically the
+@code{base32} form is used here to generate the bytevector from a
+base-32 string.
+
+You can obtain this information using @code{guix download}
+(@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
+guix hash}).
+
+@item @code{file-name} (default: @code{#f})
+The file name under which the source code should be saved. When this is
+@code{#f}, a sensible default value will be used in most cases. In case
+the source is fetched from a URL, the file name from the URL will be
+used. For version control checkouts, it is recommended to provide the
+file name explicitly because the default is not very descriptive.
+
+@item @code{patches} (default: @code{'()})
+A list of file names, origins, or file-like objects (@pxref{G-Expressions,
+file-like objects}) pointing to patches to be applied to the source.
+
+This list of patches must be unconditional. In particular, it cannot
+depend on the value of @code{%current-system} or
+@code{%current-target-system}.
+
+@item @code{snippet} (default: @code{#f})
+A G-expression (@pxref{G-Expressions}) or S-expression that will be run
+in the source directory. This is a convenient way to modify the source,
+sometimes more convenient than a patch.
+
+@item @code{patch-flags} (default: @code{'("-p1")})
+A list of command-line flags that should be passed to the @code{patch}
+command.
+
+@item @code{patch-inputs} (default: @code{#f})
+Input packages or derivations to the patching process. When this is
+@code{#f}, the usual set of inputs necessary for patching are provided,
+such as GNU@tie{}Patch.
+
+@item @code{modules} (default: @code{'()})
+A list of Guile modules that should be loaded during the patching
+process and while running the code in the @code{snippet} field.
+
+@item @code{patch-guile} (default: @code{#f})
+The Guile package that should be used in the patching process. When
+this is @code{#f}, a sensible default is used.
+@end table
+@end deftp
-Consider this ``normal'' procedure:
-@example
-(define (sh-symlink store)
- ;; Return a derivation that symlinks the 'bash' executable.
- (let* ((drv (package-derivation store bash))
- (out (derivation->output-path drv))
- (sh (string-append out "/bin/bash")))
- (build-expression->derivation store "sh"
- `(symlink ,sh %output))))
-@end example
+@node Build Systems
+@section Build Systems
-Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
-as a monadic function:
+@cindex build system
+Each package definition specifies a @dfn{build system} and arguments for
+that build system (@pxref{Defining Packages}). This @code{build-system}
+field represents the build procedure of the package, as well as implicit
+dependencies of that build procedure.
-@example
-(define (sh-symlink)
- ;; Same, but return a monadic value.
- (mlet %store-monad ((drv (package->derivation bash)))
- (gexp->derivation "sh"
- #~(symlink (string-append #$drv "/bin/bash")
- #$output))))
-@end example
+Build systems are @code{<build-system>} objects. The interface to
+create and manipulate them is provided by the @code{(guix build-system)}
+module, and actual build systems are exported by specific modules.
-There are several things to note in the second version: the @code{store}
-parameter is now implicit and is ``threaded'' in the calls to the
-@code{package->derivation} and @code{gexp->derivation} monadic
-procedures, and the monadic value returned by @code{package->derivation}
-is @dfn{bound} using @code{mlet} instead of plain @code{let}.
+@cindex bag (low-level package representation)
+Under the hood, build systems first compile package objects to
+@dfn{bags}. A @dfn{bag} is like a package, but with less
+ornamentation---in other words, a bag is a lower-level representation of
+a package, which includes all the inputs of that package, including some
+that were implicitly added by the build system. This intermediate
+representation is then compiled to a derivation (@pxref{Derivations}).
-As it turns out, the call to @code{package->derivation} can even be
-omitted since it will take place implicitly, as we will see later
-(@pxref{G-Expressions}):
+Build systems accept an optional list of @dfn{arguments}. In package
+definitions, these are passed @i{via} the @code{arguments} field
+(@pxref{Defining Packages}). They are typically keyword arguments
+(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
+Guile Reference Manual}). The value of these arguments is usually
+evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
+by the daemon (@pxref{Derivations}).
-@example
-(define (sh-symlink)
- (gexp->derivation "sh"
- #~(symlink (string-append #$bash "/bin/bash")
- #$output)))
-@end example
+The main build system is @var{gnu-build-system}, which implements the
+standard build procedure for GNU and many other packages. It
+is provided by the @code{(guix build-system gnu)} module.
-@c See
-@c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
-@c for the funny quote.
-Calling the monadic @code{sh-symlink} has no effect. As someone once
-said, ``you exit a monad like you exit a building on fire: by running''.
-So, to exit the monad and get the desired effect, one must use
-@code{run-with-store}:
+@defvr {Scheme Variable} gnu-build-system
+@var{gnu-build-system} represents the GNU Build System, and variants
+thereof (@pxref{Configuration, configuration and makefile conventions,,
+standards, GNU Coding Standards}).
-@example
-(run-with-store (open-connection) (sh-symlink))
-@result{} /gnu/store/...-sh-symlink
-@end example
+@cindex build phases
+In a nutshell, packages using it are configured, built, and installed with
+the usual @code{./configure && make && make check && make install}
+command sequence. In practice, a few additional steps are often needed.
+All these steps are split up in separate @dfn{phases},
+notably@footnote{Please see the @code{(guix build gnu-build-system)}
+modules for more details about the build phases.}:
-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
-to ``run'' a single monadic value through the store:
+@table @code
+@item unpack
+Unpack the source tarball, and change the current directory to the
+extracted source tree. If the source is actually a directory, copy it
+to the build tree, and enter that directory.
-@example
-scheme@@(guile-user)> ,run-in-store (package->derivation hello)
-$1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
-@end example
+@item patch-source-shebangs
+Patch shebangs encountered in source files so they refer to the right
+store file names. For instance, this changes @code{#!/bin/sh} to
+@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
-The latter enters a recursive REPL, where all the return values are
-automatically run through the store:
+@item configure
+Run the @file{configure} script with a number of default options, such
+as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
+by the @code{#:configure-flags} argument.
+
+@item build
+Run @code{make} with the list of flags specified with
+@code{#:make-flags}. If the @code{#:parallel-build?} argument is true
+(the default), build with @code{make -j}.
+
+@item check
+Run @code{make check}, or some other target specified with
+@code{#:test-target}, unless @code{#:tests? #f} is passed. If the
+@code{#:parallel-tests?} argument is true (the default), run @code{make
+check -j}.
+
+@item install
+Run @code{make install} with the flags listed in @code{#:make-flags}.
+
+@item patch-shebangs
+Patch shebangs on the installed executable files.
+
+@item strip
+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}).
+@end table
+
+@vindex %standard-phases
+The build-side module @code{(guix build gnu-build-system)} defines
+@var{%standard-phases} as the default list of build phases.
+@var{%standard-phases} is a list of symbol/procedure pairs, where the
+procedure implements the actual phase.
+
+The list of phases used for a particular package can be changed with the
+@code{#:phases} parameter. For instance, passing:
@example
-scheme@@(guile-user)> ,enter-store-monad
-store-monad@@(guile-user) [1]> (package->derivation hello)
-$2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
-store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
-$3 = "/gnu/store/@dots{}-foo"
-store-monad@@(guile-user) [1]> ,q
-scheme@@(guile-user)>
+#:phases (modify-phases %standard-phases (delete 'configure))
@end example
-@noindent
-Note that non-monadic values cannot be returned in the
-@code{store-monad} REPL.
+means that all the phases described above will be used, except the
+@code{configure} phase.
-The main syntactic forms to deal with monads in general are provided by
-the @code{(guix monads)} module and are described below.
+In addition, this build system ensures that the ``standard'' environment
+for GNU packages is available. This includes tools such as GCC, libc,
+Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
+build-system gnu)} module for a complete list). We call these the
+@dfn{implicit inputs} of a package, because package definitions do not
+have to mention them.
+@end defvr
-@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
-Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
-in @var{monad}.
-@end deffn
+Other @code{<build-system>} objects are defined to support other
+conventions and tools used by free software packages. They inherit most
+of @var{gnu-build-system}, and differ mainly in the set of inputs
+implicitly added to the build process, and in the list of phases
+executed. Some of these build systems are listed below.
-@deffn {Scheme Syntax} return @var{val}
-Return a monadic value that encapsulates @var{val}.
-@end deffn
+@defvr {Scheme Variable} ant-build-system
+This variable is exported by @code{(guix build-system ant)}. It
+implements the build procedure for Java packages that can be built with
+@url{http://ant.apache.org/, Ant build tool}.
-@deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ...
-@dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
-procedures @var{mproc}@dots{}@footnote{This operation is commonly
-referred to as ``bind'', but that name denotes an unrelated procedure in
-Guile. Thus we use this somewhat cryptic symbol inherited from the
-Haskell language.}. There can be one @var{mproc} or several of them, as
-in this example:
+It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
+provided by the @code{icedtea} package to the set of inputs. Different
+packages can be specified with the @code{#:ant} and @code{#:jdk}
+parameters, respectively.
-@example
-(run-with-state
- (with-monad %state-monad
- (>>= (return 1)
- (lambda (x) (return (+ 1 x)))
- (lambda (x) (return (* 2 x)))))
- 'some-state)
+When the original package does not provide a suitable Ant build file,
+the parameter @code{#:jar-name} can be used to generate a minimal Ant
+build file @file{build.xml} with tasks to build the specified jar
+archive. In this case the parameter @code{#:source-dir} can be used to
+specify the source sub-directory, defaulting to ``src''.
-@result{} 4
-@result{} some-state
-@end example
-@end deffn
+The @code{#:main-class} parameter can be used with the minimal ant
+buildfile to specify the main class of the resulting jar. This makes the
+jar file executable. The @code{#:test-include} parameter can be used to
+specify the list of junit tests to run. It defaults to
+@code{(list "**/*Test.java")}. The @code{#:test-exclude} can be used to
+disable some tests. It defaults to @code{(list "**/Abstract*.java")},
+because abstract classes cannot be run as tests.
-@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
- @var{body} ...
-@deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
- @var{body} ...
-Bind the variables @var{var} to the monadic values @var{mval} in
-@var{body}, which is a sequence of expressions. As with the bind
-operator, this can be thought of as ``unpacking'' the raw, non-monadic
-value ``contained'' in @var{mval} and making @var{var} refer to that
-raw, non-monadic value within the scope of the @var{body}. The form
-(@var{var} -> @var{val}) binds @var{var} to the ``normal'' value
-@var{val}, as per @code{let}. The binding operations occur in sequence
-from left to right. The last expression of @var{body} must be a monadic
-expression, and its result will become the result of the @code{mlet} or
-@code{mlet*} when run in the @var{monad}.
+The parameter @code{#:build-target} can be used to specify the Ant task
+that should be run during the @code{build} phase. By default the
+``jar'' task will be run.
-@code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
-(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
-@end deffn
+@end defvr
-@deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
-Bind @var{mexp} and the following monadic expressions in sequence,
-returning the result of the last expression. Every expression in the
-sequence must be a monadic expression.
+@defvr {Scheme Variable} android-ndk-build-system
+@cindex Android distribution
+@cindex Android NDK build system
+This variable is exported by @code{(guix build-system android-ndk)}. It
+implements a build procedure for Android NDK (native development kit)
+packages using a Guix-specific build process.
+
+The build system assumes that packages install their public interface
+(header) files to the subdirectory "include" of the "out" output and
+their libraries to the subdirectory "lib" of the "out" output.
+
+It's also assumed that the union of all the dependencies of a package
+has no conflicting files.
+
+For the time being, cross-compilation is not supported - so right now
+the libraries and header files are assumed to be host tools.
-This is akin to @code{mlet}, except that the return values of the
-monadic expressions are ignored. In that sense, it is analogous to
-@code{begin}, but applied to monadic expressions.
-@end deffn
+@end defvr
-@deffn {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ...
-When @var{condition} is true, evaluate the sequence of monadic
-expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
-@var{condition} is false, return @code{*unspecified*} in the current
-monad. Every expression in the sequence must be a monadic expression.
-@end deffn
+@defvr {Scheme Variable} asdf-build-system/source
+@defvrx {Scheme Variable} asdf-build-system/sbcl
+@defvrx {Scheme Variable} asdf-build-system/ecl
-@deffn {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} ...
-When @var{condition} is false, evaluate the sequence of monadic
-expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
-@var{condition} is true, return @code{*unspecified*} in the current
-monad. Every expression in the sequence must be a monadic expression.
-@end deffn
+These variables, exported by @code{(guix build-system asdf)}, implement
+build procedures for Common Lisp packages using
+@url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
+definition facility for Common Lisp programs and libraries.
-@cindex state monad
-The @code{(guix monads)} module provides the @dfn{state monad}, which
-allows an additional value---the state---to be @emph{threaded} through
-monadic procedure calls.
+The @code{asdf-build-system/source} system installs the packages in
+source form, and can be loaded using any common lisp implementation, via
+ASDF. The others, such as @code{asdf-build-system/sbcl}, install binary
+systems in the format which a particular implementation understands.
+These build systems can also be used to produce executable programs, or
+lisp images which contain a set of packages pre-loaded.
-@defvr {Scheme Variable} %state-monad
-The state monad. Procedures in the state monad can access and change
-the state that is threaded.
+The build system uses naming conventions. For binary packages, the
+package name should be prefixed with the lisp implementation, such as
+@code{sbcl-} for @code{asdf-build-system/sbcl}.
-Consider the example below. The @code{square} procedure returns a value
-in the state monad. It returns the square of its argument, but also
-increments the current state value:
+Additionally, the corresponding source package should be labeled using
+the same convention as python packages (see @ref{Python Modules}), using
+the @code{cl-} prefix.
-@example
-(define (square x)
- (mlet %state-monad ((count (current-state)))
- (mbegin %state-monad
- (set-current-state (+ 1 count))
- (return (* x x)))))
+For binary packages, each system should be defined as a Guix package.
+If one package @code{origin} contains several systems, package variants
+can be created in order to build all the systems. Source packages,
+which use @code{asdf-build-system/source}, may contain several systems.
-(run-with-state (sequence %state-monad (map square (iota 3))) 0)
-@result{} (0 1 4)
-@result{} 3
-@end example
+In order to create executable programs and images, the build-side
+procedures @code{build-program} and @code{build-image} can be used.
+They should be called in a build phase after the @code{create-symlinks}
+phase, so that the system which was just built can be used within the
+resulting image. @code{build-program} requires a list of Common Lisp
+expressions to be passed as the @code{#:entry-program} argument.
-When ``run'' through @var{%state-monad}, we obtain that additional state
-value, which is the number of @code{square} calls.
-@end defvr
+If the system is not defined within its own @code{.asd} file of the same
+name, then the @code{#:asd-file} parameter should be used to specify
+which file the system is defined in. Furthermore, if the package
+defines a system for its tests in a separate file, it will be loaded
+before the tests are run if it is specified by the
+@code{#:test-asd-file} parameter. If it is not set, the files
+@code{<system>-tests.asd}, @code{<system>-test.asd}, @code{tests.asd},
+and @code{test.asd} will be tried if they exist.
-@deffn {Monadic Procedure} current-state
-Return the current state as a monadic value.
-@end deffn
+If for some reason the package must be named in a different way than the
+naming conventions suggest, the @code{#:asd-system-name} parameter can
+be used to specify the name of the system.
-@deffn {Monadic Procedure} set-current-state @var{value}
-Set the current state to @var{value} and return the previous state as a
-monadic value.
-@end deffn
+@end defvr
-@deffn {Monadic Procedure} state-push @var{value}
-Push @var{value} to the current state, which is assumed to be a list,
-and return the previous state as a monadic value.
-@end deffn
+@defvr {Scheme Variable} cargo-build-system
+@cindex Rust programming language
+@cindex Cargo (Rust build system)
+This variable is exported by @code{(guix build-system cargo)}. It
+supports builds of packages using Cargo, the build tool of the
+@uref{https://www.rust-lang.org, Rust programming language}.
-@deffn {Monadic Procedure} state-pop
-Pop a value from the current state and return it as a monadic value.
-The state is assumed to be a list.
-@end deffn
+In its @code{configure} phase, this build system replaces dependencies
+specified in the @file{Carto.toml} file with inputs to the Guix package.
+The @code{install} phase installs the binaries, and it also installs the
+source code and @file{Cargo.toml} file.
+@end defvr
-@deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
-Run monadic value @var{mval} starting with @var{state} as the initial
-state. Return two values: the resulting value, and the resulting state.
-@end deffn
+@cindex Clojure (programming language)
+@cindex simple Clojure build system
+@defvr {Scheme Variable} clojure-build-system
+This variable is exported by @code{(guix build-system clojure)}. It implements
+a simple build procedure for @uref{https://clojure.org/, Clojure} packages
+using plain old @code{compile} in Clojure. Cross-compilation is not supported
+yet.
-The main interface to the store monad, provided by the @code{(guix
-store)} module, is as follows.
+It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs.
+Different packages can be specified with the @code{#:clojure}, @code{#:jdk} and
+@code{#:zip} parameters, respectively.
-@defvr {Scheme Variable} %store-monad
-The store monad---an alias for @var{%state-monad}.
+A list of source directories, test directories and jar names can be specified
+with the @code{#:source-dirs}, @code{#:test-dirs} and @code{#:jar-names}
+parameters, respectively. Compile directory and main class can be specified
+with the @code{#:compile-dir} and @code{#:main-class} parameters, respectively.
+Other parameters are documented below.
-Values in the store monad encapsulate accesses to the store. When its
-effect is needed, a value of the store monad must be ``evaluated'' by
-passing it to the @code{run-with-store} procedure (see below.)
-@end defvr
+This build system is an extension of @var{ant-build-system}, but with the
+following phases changed:
-@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
-Run @var{mval}, a monadic value in the store monad, in @var{store}, an
-open store connection.
-@end deffn
+@table @code
-@deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
-Return as a monadic value the absolute file name in the store of the file
-containing @var{text}, a string. @var{references} is a list of store items that the
-resulting text file refers to; it defaults to the empty list.
-@end deffn
+@item build
+This phase calls @code{compile} in Clojure to compile source files and runs
+@command{jar} to create jars from both source files and compiled files
+according to the include list and exclude list specified in
+@code{#:aot-include} and @code{#:aot-exclude}, respectively. The exclude list
+has priority over the include list. These lists consist of symbols
+representing Clojure libraries or the special keyword @code{#:all} representing
+all Clojure libraries found under the source directories. The parameter
+@code{#:omit-source?} decides if source should be included into the jars.
-@deffn {Monadic Procedure} binary-file @var{name} @var{data} [@var{references}]
-Return as a monadic value the absolute file name in the store of the file
-containing @var{data}, a bytevector. @var{references} is a list of store
-items that the resulting binary file refers to; it defaults to the empty list.
-@end deffn
+@item check
+This phase runs tests according to the include list and exclude list specified
+in @code{#:test-include} and @code{#:test-exclude}, respectively. Their
+meanings are analogous to that of @code{#:aot-include} and
+@code{#:aot-exclude}, except that the special keyword @code{#:all} now
+stands for all Clojure libraries found under the test directories. The
+parameter @code{#:tests?} decides if tests should be run.
-@deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
- [#:recursive? #t] [#:select? (const #t)]
-Return the name of @var{file} once interned in the store. Use
-@var{name} as its store name, or the basename of @var{file} if
-@var{name} is omitted.
+@item install
+This phase installs all jars built previously.
+@end table
-When @var{recursive?} is true, the contents of @var{file} are added
-recursively; if @var{file} designates a flat file and @var{recursive?}
-is true, its contents are added, and its permission bits are kept.
+Apart from the above, this build system also contains an additional phase:
-When @var{recursive?} is true, call @code{(@var{select?} @var{file}
-@var{stat})} for each directory entry, where @var{file} is the entry's
-absolute file name and @var{stat} is the result of @code{lstat}; exclude
-entries for which @var{select?} does not return true.
+@table @code
-The example below adds a file to the store, under two different names:
+@item install-doc
+This phase installs all top-level files with base name matching
+@var{%doc-regex}. A different regex can be specified with the
+@code{#:doc-regex} parameter. All files (recursively) inside the documentation
+directories specified in @code{#:doc-dirs} are installed as well.
+@end table
+@end defvr
-@example
-(run-with-store (open-connection)
- (mlet %store-monad ((a (interned-file "README"))
- (b (interned-file "README" "LEGU-MIN")))
- (return (list a b))))
+@defvr {Scheme Variable} cmake-build-system
+This variable is exported by @code{(guix build-system cmake)}. It
+implements the build procedure for packages using the
+@url{http://www.cmake.org, CMake build tool}.
-@result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
-@end example
+It automatically adds the @code{cmake} package to the set of inputs.
+Which package is used can be specified with the @code{#:cmake}
+parameter.
-@end deffn
+The @code{#:configure-flags} parameter is taken as a list of flags
+passed to the @command{cmake} command. The @code{#:build-type}
+parameter specifies in abstract terms the flags passed to the compiler;
+it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
+debugging information''), which roughly means that code is compiled with
+@code{-O2 -g}, as is the case for Autoconf-based packages by default.
+@end defvr
-The @code{(guix packages)} module exports the following package-related
-monadic procedures:
+@defvr {Scheme Variable} dune-build-system
+This variable is exported by @code{(guix build-system dune)}. It
+supports builds of packages using @uref{https://dune.build/, Dune}, a build
+tool for the OCaml programming language. It is implemented as an extension
+of the @code{ocaml-build-system} which is described below. As such, the
+@code{#:ocaml} and @code{#:findlib} parameters can be passed to this build
+system.
-@deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
- [#:system (%current-system)] [#:target #f] @
- [#:output "out"]
-Return as a monadic
-value in the absolute file name of @var{file} within the @var{output}
-directory of @var{package}. When @var{file} is omitted, return the name
-of the @var{output} directory of @var{package}. When @var{target} is
-true, use it as a cross-compilation target triplet.
-@end deffn
+It automatically adds the @code{dune} package to the set of inputs.
+Which package is used can be specified with the @code{#:dune}
+parameter.
-@deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
-@deffnx {Monadic Procedure} package->cross-derivation @var{package} @
- @var{target} [@var{system}]
-Monadic version of @code{package-derivation} and
-@code{package-cross-derivation} (@pxref{Defining Packages}).
-@end deffn
+There is no @code{configure} phase because dune packages typically don't
+need to be configured. The @code{#:build-flags} parameter is taken as a
+list of flags passed to the @code{dune} command during the build.
+The @code{#:jbuild?} parameter can be passed to use the @code{jbuild}
+command instead of the more recent @code{dune} command while building
+a package. Its default value is @code{#f}.
-@node G-Expressions
-@section G-Expressions
+The @code{#:package} parameter can be passed to specify a package name, which
+is useful when a package contains multiple packages and you want to build
+only one of them. This is equivalent to passing the @code{-p} argument to
+@code{dune}.
+@end defvr
+
+@defvr {Scheme Variable} go-build-system
+This variable is exported by @code{(guix build-system go)}. It
+implements a build procedure for Go packages using the standard
+@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies,
+Go build mechanisms}.
-@cindex G-expression
-@cindex build code quoting
-So we have ``derivations'', which represent a sequence of build actions
-to be performed to produce an item in the store (@pxref{Derivations}).
-These build actions are performed when asking the daemon to actually
-build the derivations; they are run by the daemon in a container
-(@pxref{Invoking guix-daemon}).
+The user is expected to provide a value for the key @code{#:import-path}
+and, in some cases, @code{#:unpack-path}. The
+@url{https://golang.org/doc/code.html#ImportPaths, import path}
+corresponds to the file system path expected by the package's build
+scripts and any referring packages, and provides a unique way to
+refer to a Go package. It is typically based on a combination of the
+package source code's remote URI and file system hierarchy structure. In
+some cases, you will need to unpack the package's source code to a
+different directory structure than the one indicated by the import path,
+and @code{#:unpack-path} should be used in such cases.
-@cindex strata of code
-It should come as no surprise that we like to write these build actions
-in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
-code@footnote{The term @dfn{stratum} in this context was coined by
-Manuel Serrano et al.@: in the context of their work on Hop. Oleg
-Kiselyov, who has written insightful
-@url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
-on this topic}, refers to this kind of code generation as
-@dfn{staging}.}: the ``host code''---code that defines packages, talks
-to the daemon, etc.---and the ``build code''---code that actually
-performs build actions, such as making directories, invoking
-@command{make}, etc.
+Packages that provide Go libraries should install their source code into
+the built output. The key @code{#:install-source?}, which defaults to
+@code{#t}, controls whether or not the source code is installed. It can
+be set to @code{#f} for packages that only provide executable files.
+@end defvr
-To describe a derivation and its build actions, one typically needs to
-embed build code inside host code. It boils down to manipulating build
-code as data, and the homoiconicity of Scheme---code has a direct
-representation as data---comes in handy for that. But we need more than
-the normal @code{quasiquote} mechanism in Scheme to construct build
-expressions.
+@defvr {Scheme Variable} glib-or-gtk-build-system
+This variable is exported by @code{(guix build-system glib-or-gtk)}. It
+is intended for use with packages making use of GLib or GTK+.
-The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
-S-expressions adapted to build expressions. G-expressions, or
-@dfn{gexps}, consist essentially of three syntactic forms: @code{gexp},
-@code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
-@code{#$}, and @code{#$@@}), which are comparable to
-@code{quasiquote}, @code{unquote}, and @code{unquote-splicing},
-respectively (@pxref{Expression Syntax, @code{quasiquote},, guile,
-GNU Guile Reference Manual}). However, there are major differences:
+This build system adds the following two phases to the ones defined by
+@var{gnu-build-system}:
-@itemize
-@item
-Gexps are meant to be written to a file and run or manipulated by other
-processes.
+@table @code
+@item glib-or-gtk-wrap
+The phase @code{glib-or-gtk-wrap} ensures that programs in
+@file{bin/} are able to find GLib ``schemas'' and
+@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
+modules}. This is achieved by wrapping the programs in launch scripts
+that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
+environment variables.
-@item
-When a high-level object such as a package or derivation is unquoted
-inside a gexp, the result is as if its output file name had been
-introduced.
+It is possible to exclude specific package outputs from that wrapping
+process by listing their names in the
+@code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
+when an output is known not to contain any GLib or GTK+ binaries, and
+where wrapping would gratuitously add a dependency of that output on
+GLib and GTK+.
-@item
-Gexps carry information about the packages or derivations they refer to,
-and these dependencies are automatically added as inputs to the build
-processes that use them.
-@end itemize
+@item glib-or-gtk-compile-schemas
+The phase @code{glib-or-gtk-compile-schemas} makes sure that all
+@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
+GSettings schemas} of GLib are compiled. Compilation is performed by the
+@command{glib-compile-schemas} program. It is provided by the package
+@code{glib:bin} which is automatically imported by the build system.
+The @code{glib} package providing @command{glib-compile-schemas} can be
+specified with the @code{#:glib} parameter.
+@end table
-@cindex lowering, of high-level objects in gexps
-This mechanism is not limited to package and derivation
-objects: @dfn{compilers} able to ``lower'' other high-level objects to
-derivations or files in the store can be defined,
-such that these objects can also be inserted
-into gexps. For example, a useful type of high-level objects that can be
-inserted in a gexp is ``file-like objects'', which make it easy to
-add files to the store and to refer to them in
-derivations and such (see @code{local-file} and @code{plain-file}
-below.)
+Both phases are executed after the @code{install} phase.
+@end defvr
-To illustrate the idea, here is an example of a gexp:
+@defvr {Scheme Variable} guile-build-system
+This build system is for Guile packages that consist exclusively of Scheme
+code and that are so lean that they don't even have a makefile, let alone a
+@file{configure} script. It compiles Scheme code using @command{guild
+compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and
+installs the @file{.scm} and @file{.go} files in the right place. It also
+installs documentation.
-@example
-(define build-exp
- #~(begin
- (mkdir #$output)
- (chdir #$output)
- (symlink (string-append #$coreutils "/bin/ls")
- "list-files")))
-@end example
+This build system supports cross-compilation by using the @code{--target}
+option of @command{guild compile}.
-This gexp can be passed to @code{gexp->derivation}; we obtain a
-derivation that builds a directory containing exactly one symlink to
-@file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
+Packages built with @code{guile-build-system} must provide a Guile package in
+their @code{native-inputs} field.
+@end defvr
-@example
-(gexp->derivation "the-thing" build-exp)
-@end example
+@defvr {Scheme Variable} minify-build-system
+This variable is exported by @code{(guix build-system minify)}. It
+implements a minification procedure for simple JavaScript packages.
-As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
-substituted to the reference to the @var{coreutils} package in the
-actual build code, and @var{coreutils} is automatically made an input to
-the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
-output)}) is replaced by a string containing the directory name of the
-output of the derivation.
+It adds @code{uglify-js} to the set of inputs and uses it to compress
+all JavaScript files in the @file{src} directory. A different minifier
+package can be specified with the @code{#:uglify-js} parameter, but it
+is expected that the package writes the minified code to the standard
+output.
-@cindex cross compilation
-In a cross-compilation context, it is useful to distinguish between
-references to the @emph{native} build of a package---that can run on the
-host---versus references to cross builds of a package. To that end, the
-@code{#+} plays the same role as @code{#$}, but is a reference to a
-native package build:
+When the input JavaScript files are not all located in the @file{src}
+directory, the parameter @code{#:javascript-files} can be used to
+specify a list of file names to feed to the minifier.
+@end defvr
-@example
-(gexp->derivation "vi"
- #~(begin
- (mkdir #$output)
- (system* (string-append #+coreutils "/bin/ln")
- "-s"
- (string-append #$emacs "/bin/emacs")
- (string-append #$output "/bin/vi")))
- #:target "mips64el-linux-gnu")
-@end example
+@defvr {Scheme Variable} ocaml-build-system
+This variable is exported by @code{(guix build-system ocaml)}. It implements
+a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists
+of choosing the correct set of commands to run for each package. OCaml
+packages can expect many different commands to be run. This build system will
+try some of them.
-@noindent
-In the example above, the native build of @var{coreutils} is used, so
-that @command{ln} can actually run on the host; but then the
-cross-compiled build of @var{emacs} is referenced.
+When the package has a @file{setup.ml} file present at the top-level, it will
+run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and
+@code{ocaml setup.ml -install}. The build system will assume that this file
+was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will take
+care of setting the prefix and enabling tests if they are not disabled. You
+can pass configure and build flags with the @code{#:configure-flags} and
+@code{#:build-flags}. The @code{#:test-flags} key can be passed to change the
+set of flags used to enable tests. The @code{#:use-make?} key can be used to
+bypass this system in the build and install phases.
-@cindex imported modules, for gexps
-@findex with-imported-modules
-Another gexp feature is @dfn{imported modules}: sometimes you want to be
-able to use certain Guile modules from the ``host environment'' in the
-gexp, so those modules should be imported in the ``build environment''.
-The @code{with-imported-modules} form allows you to express that:
+When the package has a @file{configure} file, it is assumed that it is a
+hand-made configure script that requires a different argument format than
+in the @code{gnu-build-system}. You can add more flags with the
+@code{#:configure-flags} key.
-@example
-(let ((build (with-imported-modules '((guix build utils))
- #~(begin
- (use-modules (guix build utils))
- (mkdir-p (string-append #$output "/bin"))))))
- (gexp->derivation "empty-dir"
- #~(begin
- #$build
- (display "success!\n")
- #t)))
-@end example
+When the package has a @file{Makefile} file (or @code{#:use-make?} is
+@code{#t}), it will be used and more flags can be passed to the build and
+install phases with the @code{#:make-flags} key.
-@noindent
-In this example, the @code{(guix build utils)} module is automatically
-pulled into the isolated build environment of our gexp, such that
-@code{(use-modules (guix build utils))} works as expected.
+Finally, some packages do not have these files and use a somewhat standard
+location for its build system. In that case, the build system will run
+@code{ocaml pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of
+providing the path to the required findlib module. Additional flags can
+be passed via the @code{#:build-flags} key. Install is taken care of by
+@command{opam-installer}. In this case, the @code{opam} package must
+be added to the @code{native-inputs} field of the package definition.
-@cindex module closure
-@findex source-module-closure
-Usually you want the @emph{closure} of the module to be imported---i.e.,
-the module itself and all the modules it depends on---rather than just
-the module; failing to do that, attempts to use the module will fail
-because of missing dependent modules. The @code{source-module-closure}
-procedure computes the closure of a module by looking at its source file
-headers, which comes in handy in this case:
+Note that most OCaml packages assume they will be installed in the same
+directory as OCaml, which is not what we want in guix. In particular, they
+will install @file{.so} files in their module's directory, which is usually
+fine because it is in the OCaml compiler directory. In guix though, these
+libraries cannot be found and we use @code{CAML_LD_LIBRARY_PATH}. This
+variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
+@file{.so} libraries should be installed.
+@end defvr
-@example
-(use-modules (guix modules)) ;for 'source-module-closure'
+@defvr {Scheme Variable} python-build-system
+This variable is exported by @code{(guix build-system python)}. It
+implements the more or less standard build procedure used by Python
+packages, which consists in running @code{python setup.py build} and
+then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
-(with-imported-modules (source-module-closure
- '((guix build utils)
- (gnu build vm)))
- (gexp->derivation "something-with-vms"
- #~(begin
- (use-modules (guix build utils)
- (gnu build vm))
- @dots{})))
-@end example
+For packages that install stand-alone Python programs under @code{bin/},
+it takes care of wrapping these programs so that their @code{PYTHONPATH}
+environment variable points to all the Python libraries they depend on.
-@cindex extensions, for gexps
-@findex with-extensions
-In the same vein, sometimes you want to import not just pure-Scheme
-modules, but also ``extensions'' such as Guile bindings to C libraries
-or other ``full-blown'' packages. Say you need the @code{guile-json}
-package available on the build side, here's how you would do it:
+Which Python package is used to perform the build can be specified with
+the @code{#:python} parameter. This is a useful way to force a package
+to be built for a specific version of the Python interpreter, which
+might be necessary if the package is only compatible with a single
+interpreter version.
-@example
-(use-modules (gnu packages guile)) ;for 'guile-json'
+By default guix calls @code{setup.py} under control of
+@code{setuptools}, much like @command{pip} does. Some packages are not
+compatible with setuptools (and pip), thus you can disable this by
+setting the @code{#:use-setuptools} parameter to @code{#f}.
+@end defvr
-(with-extensions (list guile-json)
- (gexp->derivation "something-with-json"
- #~(begin
- (use-modules (json))
- @dots{})))
-@end example
+@defvr {Scheme Variable} perl-build-system
+This variable is exported by @code{(guix build-system perl)}. It
+implements the standard build procedure for Perl packages, which either
+consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
+followed by @code{Build} and @code{Build install}; or in running
+@code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
+@code{make} and @code{make install}, depending on which of
+@code{Build.PL} or @code{Makefile.PL} is present in the package
+distribution. Preference is given to the former if both @code{Build.PL}
+and @code{Makefile.PL} exist in the package distribution. This
+preference can be reversed by specifying @code{#t} for the
+@code{#:make-maker?} parameter.
-The syntactic form to construct gexps is summarized below.
+The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
+passes flags specified by the @code{#:make-maker-flags} or
+@code{#:module-build-flags} parameter, respectively.
-@deffn {Scheme Syntax} #~@var{exp}
-@deffnx {Scheme Syntax} (gexp @var{exp})
-Return a G-expression containing @var{exp}. @var{exp} may contain one
-or more of the following forms:
+Which Perl package is used can be specified with @code{#:perl}.
+@end defvr
-@table @code
-@item #$@var{obj}
-@itemx (ungexp @var{obj})
-Introduce a reference to @var{obj}. @var{obj} may have one of the
-supported types, for example a package or a
-derivation, in which case the @code{ungexp} form is replaced by its
-output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
+@defvr {Scheme Variable} r-build-system
+This variable is exported by @code{(guix build-system r)}. It
+implements the build procedure used by @uref{http://r-project.org, R}
+packages, which essentially is little more than running @code{R CMD
+INSTALL --library=/gnu/store/@dots{}} in an environment where
+@code{R_LIBS_SITE} contains the paths to all R package inputs. Tests
+are run after installation using the R function
+@code{tools::testInstalledPackage}.
+@end defvr
-If @var{obj} is a list, it is traversed and references to supported
-objects are substituted similarly.
+@defvr {Scheme Variable} rakudo-build-system
+This variable is exported by @code{(guix build-system rakudo)} It
+implements the build procedure used by @uref{https://rakudo.org/,
+Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the
+package to @code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and
+installs the binaries, library files and the resources, as well as wrap
+the files under the @code{bin/} directory. Tests can be skipped by
+passing @code{#f} to the @code{tests?} parameter.
+
+Which rakudo package is used can be specified with @code{rakudo}.
+Which perl6-tap-harness package used for the tests can be specified with
+@code{#:prove6} or removed by passing @code{#f} to the
+@code{with-prove6?} parameter.
+Which perl6-zef package used for tests and installing can be specified
+with @code{#:zef} or removed by passing @code{#f} to the
+@code{with-zef?} parameter.
+@end defvr
-If @var{obj} is another gexp, its contents are inserted and its
-dependencies are added to those of the containing gexp.
+@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
+build system sets the @code{TEXINPUTS} variable to find all TeX source
+files in the inputs.
-If @var{obj} is another kind of object, it is inserted as is.
+By default it runs @code{luatex} on all files ending on @code{ins}. A
+different engine and format can be specified with the
+@code{#:tex-format} argument. Different build targets can be specified
+with the @code{#:build-targets} argument, which expects a list of file
+names. The build system adds only @code{texlive-bin} and
+@code{texlive-latex-base} (both from @code{(gnu packages tex}) to the
+inputs. Both can be overridden with the arguments @code{#:texlive-bin}
+and @code{#:texlive-latex-base}, respectively.
-@item #$@var{obj}:@var{output}
-@itemx (ungexp @var{obj} @var{output})
-This is like the form above, but referring explicitly to the
-@var{output} of @var{obj}---this is useful when @var{obj} produces
-multiple outputs (@pxref{Packages with Multiple Outputs}).
+The @code{#:tex-directory} parameter tells the build system where to
+install the built files under the texmf tree.
+@end defvr
-@item #+@var{obj}
-@itemx #+@var{obj}:output
-@itemx (ungexp-native @var{obj})
-@itemx (ungexp-native @var{obj} @var{output})
-Same as @code{ungexp}, but produces a reference to the @emph{native}
-build of @var{obj} when used in a cross compilation context.
+@defvr {Scheme Variable} ruby-build-system
+This variable is exported by @code{(guix build-system ruby)}. It
+implements the RubyGems build procedure used by Ruby packages, which
+involves running @code{gem build} followed by @code{gem install}.
-@item #$output[:@var{output}]
-@itemx (ungexp output [@var{output}])
-Insert a reference to derivation output @var{output}, or to the main
-output when @var{output} is omitted.
+The @code{source} field of a package that uses this build system
+typically references a gem archive, since this is the format that Ruby
+developers use when releasing their software. The build system unpacks
+the gem archive, potentially patches the source, runs the test suite,
+repackages the gem, and installs it. Additionally, directories and
+tarballs may be referenced to allow building unreleased gems from Git or
+a traditional source release tarball.
-This only makes sense for gexps passed to @code{gexp->derivation}.
+Which Ruby package is used can be specified with the @code{#:ruby}
+parameter. A list of additional flags to be passed to the @command{gem}
+command can be specified with the @code{#:gem-flags} parameter.
+@end defvr
-@item #$@@@var{lst}
-@itemx (ungexp-splicing @var{lst})
-Like the above, but splices the contents of @var{lst} inside the
-containing list.
+@defvr {Scheme Variable} waf-build-system
+This variable is exported by @code{(guix build-system waf)}. It
+implements a build procedure around the @code{waf} script. The common
+phases---@code{configure}, @code{build}, and @code{install}---are
+implemented by passing their names as arguments to the @code{waf}
+script.
-@item #+@@@var{lst}
-@itemx (ungexp-native-splicing @var{lst})
-Like the above, but refers to native builds of the objects listed in
-@var{lst}.
+The @code{waf} script is executed by the Python interpreter. Which
+Python package is used to run the script can be specified with the
+@code{#:python} parameter.
+@end defvr
-@end table
+@defvr {Scheme Variable} scons-build-system
+This variable is exported by @code{(guix build-system scons)}. It
+implements the build procedure used by the SCons software construction
+tool. This build system runs @code{scons} to build the package,
+@code{scons test} to run tests, and then @code{scons install} to install
+the package.
-G-expressions created by @code{gexp} or @code{#~} are run-time objects
-of the @code{gexp?} type (see below.)
-@end deffn
+Additional flags to be passed to @code{scons} can be specified with the
+@code{#:scons-flags} parameter. The version of Python used to run SCons
+can be specified by selecting the appropriate SCons package with the
+@code{#:scons} parameter.
+@end defvr
-@deffn {Scheme Syntax} with-imported-modules @var{modules} @var{body}@dots{}
-Mark the gexps defined in @var{body}@dots{} as requiring @var{modules}
-in their execution environment.
+@defvr {Scheme Variable} haskell-build-system
+This variable is exported by @code{(guix build-system haskell)}. It
+implements the Cabal build procedure used by Haskell packages, which
+involves running @code{runhaskell Setup.hs configure
+--prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
+Instead of installing the package by running @code{runhaskell Setup.hs
+install}, to avoid trying to register libraries in the read-only
+compiler store directory, the build system uses @code{runhaskell
+Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
+addition, the build system generates the package documentation by
+running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
+is passed. Optional Haddock parameters can be passed with the help of
+the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
+not found, the build system looks for @code{Setup.lhs} instead.
-Each item in @var{modules} can be the name of a module, such as
-@code{(guix build utils)}, or it can be a module name, followed by an
-arrow, followed by a file-like object:
+Which Haskell compiler is used can be specified with the @code{#:haskell}
+parameter which defaults to @code{ghc}.
+@end defvr
-@example
-`((guix build utils)
- (guix gcrypt)
- ((guix config) => ,(scheme-file "config.scm"
- #~(define-module @dots{}))))
-@end example
+@defvr {Scheme Variable} dub-build-system
+This variable is exported by @code{(guix build-system dub)}. It
+implements the Dub build procedure used by D packages, which
+involves running @code{dub build} and @code{dub run}.
+Installation is done by copying the files manually.
-@noindent
-In the example above, the first two modules are taken from the search
-path, and the last one is created from the given file-like object.
+Which D compiler is used can be specified with the @code{#:ldc}
+parameter which defaults to @code{ldc}.
+@end defvr
-This form has @emph{lexical} scope: it has an effect on the gexps
-directly defined in @var{body}@dots{}, but not on those defined, say, in
-procedures called from @var{body}@dots{}.
-@end deffn
+@defvr {Scheme Variable} emacs-build-system
+This variable is exported by @code{(guix build-system emacs)}. It
+implements an installation procedure similar to the packaging system
+of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
-@deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{}
-Mark the gexps defined in @var{body}@dots{} as requiring
-@var{extensions} in their build and execution environment.
-@var{extensions} is typically a list of package objects such as those
-defined in the @code{(gnu packages guile)} module.
+It first creates the @code{@var{package}-autoloads.el} file, then it
+byte compiles all Emacs Lisp files. Differently from the Emacs
+packaging system, the Info documentation files are moved to the standard
+documentation directory and the @file{dir} file is deleted. Each
+package is installed in its own directory under
+@file{share/emacs/site-lisp/guix.d}.
+@end defvr
-Concretely, the packages listed in @var{extensions} are added to the
-load path while compiling imported modules in @var{body}@dots{}; they
-are also added to the load path of the gexp returned by
-@var{body}@dots{}.
-@end deffn
+@defvr {Scheme Variable} font-build-system
+This variable is exported by @code{(guix build-system font)}. It
+implements an installation procedure for font packages where upstream
+provides pre-compiled TrueType, OpenType, etc.@: font files that merely
+need to be copied into place. It copies font files to standard
+locations in the output directory.
+@end defvr
-@deffn {Scheme Procedure} gexp? @var{obj}
-Return @code{#t} if @var{obj} is a G-expression.
-@end deffn
+@defvr {Scheme Variable} meson-build-system
+This variable is exported by @code{(guix build-system meson)}. It
+implements the build procedure for packages that use
+@url{http://mesonbuild.com, Meson} as their build system.
-G-expressions are meant to be written to disk, either as code building
-some derivation, or as plain files in the store. The monadic procedures
-below allow you to do that (@pxref{The Store Monad}, for more
-information about monads.)
+It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
+of inputs, and they can be changed with the parameters @code{#:meson}
+and @code{#:ninja} if needed. The default Meson is
+@code{meson-for-build}, which is special because it doesn't clear the
+@code{RUNPATH} of binaries and libraries when they are installed.
-@deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
- [#:system (%current-system)] [#:target #f] [#:graft? #t] @
- [#:hash #f] [#:hash-algo #f] @
- [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
- [#:module-path @var{%load-path}] @
- [#:effective-version "2.2"] @
- [#:references-graphs #f] [#:allowed-references #f] @
- [#:disallowed-references #f] @
- [#:leaked-env-vars #f] @
- [#:script-name (string-append @var{name} "-builder")] @
- [#:deprecation-warnings #f] @
- [#:local-build? #f] [#:substitutable? #t] @
- [#:properties '()] [#:guile-for-build #f]
-Return a derivation @var{name} that runs @var{exp} (a gexp) with
-@var{guile-for-build} (a derivation) on @var{system}; @var{exp} is
-stored in a file called @var{script-name}. When @var{target} is true,
-it is used as the cross-compilation target triplet for packages referred
-to by @var{exp}.
+This build system is an extension of @var{gnu-build-system}, but with the
+following phases changed to some specific for Meson:
-@var{modules} is deprecated in favor of @code{with-imported-modules}.
-Its meaning is to
-make @var{modules} available in the evaluation context of @var{exp};
-@var{modules} is a list of names of Guile modules searched in
-@var{module-path} to be copied in the store, compiled, and made available in
-the load path during the execution of @var{exp}---e.g., @code{((guix
-build utils) (guix build gnu-build-system))}.
+@table @code
-@var{effective-version} determines the string to use when adding extensions of
-@var{exp} (see @code{with-extensions}) to the search path---e.g., @code{"2.2"}.
+@item configure
+The phase runs @code{meson} with the flags specified in
+@code{#:configure-flags}. The flag @code{--build-type} is always set to
+@code{plain} unless something else is specified in @code{#:build-type}.
-@var{graft?} determines whether packages referred to by @var{exp} should be grafted when
-applicable.
+@item build
+The phase runs @code{ninja} to build the package in parallel by default, but
+this can be changed with @code{#:parallel-build?}.
-When @var{references-graphs} is true, it must be a list of tuples of one of the
-following forms:
+@item check
+The phase runs @code{ninja} with the target specified in @code{#:test-target},
+which is @code{"test"} by default.
-@example
-(@var{file-name} @var{package})
-(@var{file-name} @var{package} @var{output})
-(@var{file-name} @var{derivation})
-(@var{file-name} @var{derivation} @var{output})
-(@var{file-name} @var{store-item})
-@end example
+@item install
+The phase runs @code{ninja install} and can not be changed.
+@end table
-The right-hand-side of each element of @var{references-graphs} is automatically made
-an input of the build process of @var{exp}. In the build environment, each
-@var{file-name} contains the reference graph of the corresponding item, in a simple
-text format.
+Apart from that, the build system also adds the following phases:
-@var{allowed-references} must be either @code{#f} or a list of output names and packages.
-In the latter case, the list denotes store items that the result is allowed to
-refer to. Any reference to another store item will lead to a build error.
-Similarly for @var{disallowed-references}, which can list items that must not be
-referenced by the outputs.
+@table @code
-@var{deprecation-warnings} determines whether to show deprecation warnings while
-compiling modules. It can be @code{#f}, @code{#t}, or @code{'detailed}.
+@item fix-runpath
+This phase ensures that all binaries can find the libraries they need.
+It searches for required libraries in subdirectories of the package being
+built, and adds those to @code{RUNPATH} where needed. It also removes
+references to libraries left over from the build phase by
+@code{meson-for-build}, such as test dependencies, that aren't actually
+required for the program to run.
-The other arguments are as for @code{derivation} (@pxref{Derivations}).
-@end deffn
+@item glib-or-gtk-wrap
+This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
+is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
-@cindex file-like objects
-The @code{local-file}, @code{plain-file}, @code{computed-file},
-@code{program-file}, and @code{scheme-file} procedures below return
-@dfn{file-like objects}. That is, when unquoted in a G-expression,
-these objects lead to a file in the store. Consider this G-expression:
+@item glib-or-gtk-compile-schemas
+This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
+is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
+@end table
+@end defvr
-@example
-#~(system* #$(file-append glibc "/sbin/nscd") "-f"
- #$(local-file "/tmp/my-nscd.conf"))
-@end example
+Lastly, for packages that do not need anything as sophisticated, a
+``trivial'' build system is provided. It is trivial in the sense that
+it provides basically no support: it does not pull any implicit inputs,
+and does not have a notion of build phases.
-The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
-to the store. Once expanded, for instance @i{via}
-@code{gexp->derivation}, the G-expression refers to that copy under
-@file{/gnu/store}; thus, modifying or removing the file in @file{/tmp}
-does not have any effect on what the G-expression does.
-@code{plain-file} can be used similarly; it differs in that the file
-content is directly passed as a string.
+@defvr {Scheme Variable} trivial-build-system
+This variable is exported by @code{(guix build-system trivial)}.
-@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
- [#:recursive? #f] [#:select? (const #t)]
-Return an object representing local file @var{file} to add to the store; this
-object can be used in a gexp. If @var{file} is a relative file name, it is looked
-up relative to the source file where this form appears. @var{file} will be added to
-the store under @var{name}--by default the base name of @var{file}.
+This build system requires a @code{#:builder} argument. This argument
+must be a Scheme expression that builds the package output(s)---as
+with @code{build-expression->derivation} (@pxref{Derivations,
+@code{build-expression->derivation}}).
+@end defvr
-When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
-designates a flat file and @var{recursive?} is true, its contents are added, and its
-permission bits are kept.
+@node The Store
+@section The Store
-When @var{recursive?} is true, call @code{(@var{select?} @var{file}
-@var{stat})} for each directory entry, where @var{file} is the entry's
-absolute file name and @var{stat} is the result of @code{lstat}; exclude
-entries for which @var{select?} does not return true.
+@cindex store
+@cindex store items
+@cindex store paths
-This is the declarative counterpart of the @code{interned-file} monadic
-procedure (@pxref{The Store Monad, @code{interned-file}}).
-@end deffn
+Conceptually, the @dfn{store} is the place where derivations that have
+been built successfully are stored---by default, @file{/gnu/store}.
+Sub-directories in the store are referred to as @dfn{store items} or
+sometimes @dfn{store paths}. The store has an associated database that
+contains information such as the store paths referred to by each store
+path, and the list of @emph{valid} store items---results of successful
+builds. This database resides in @file{@var{localstatedir}/guix/db},
+where @var{localstatedir} is the state directory specified @i{via}
+@option{--localstatedir} at configure time, usually @file{/var}.
-@deffn {Scheme Procedure} plain-file @var{name} @var{content}
-Return an object representing a text file called @var{name} with the given
-@var{content} (a string or a bytevector) to be added to the store.
+The store is @emph{always} accessed by the daemon on behalf of its clients
+(@pxref{Invoking guix-daemon}). To manipulate the store, clients
+connect to the daemon over a Unix-domain socket, send requests to it,
+and read the result---these are remote procedure calls, or RPCs.
-This is the declarative counterpart of @code{text-file}.
-@end deffn
+@quotation Note
+Users must @emph{never} modify files under @file{/gnu/store} directly.
+This would lead to inconsistencies and break the immutability
+assumptions of Guix's functional model (@pxref{Introduction}).
-@deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
- [#:options '(#:local-build? #t)]
-Return an object representing the store item @var{name}, a file or
-directory computed by @var{gexp}. @var{options}
-is a list of additional arguments to pass to @code{gexp->derivation}.
+@xref{Invoking guix gc, @command{guix gc --verify}}, for information on
+how to check the integrity of the store and attempt recovery from
+accidental modifications.
+@end quotation
-This is the declarative counterpart of @code{gexp->derivation}.
-@end deffn
+The @code{(guix store)} module provides procedures to connect to the
+daemon, and to perform RPCs. These are described below. By default,
+@code{open-connection}, and thus all the @command{guix} commands,
+connect to the local daemon or to the URI specified by the
+@code{GUIX_DAEMON_SOCKET} environment variable.
-@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
- [#:guile (default-guile)] [#:module-path %load-path]
-Return an executable script @var{name} that runs @var{exp} using
-@var{guile}, with @var{exp}'s imported modules in its search path.
-Look up @var{exp}'s modules in @var{module-path}.
+@defvr {Environment Variable} GUIX_DAEMON_SOCKET
+When set, the value of this variable should be a file name or a URI
+designating the daemon endpoint. When it is a file name, it denotes a
+Unix-domain socket to connect to. In addition to file names, the
+supported URI schemes are:
-The example below builds a script that simply invokes the @command{ls}
-command:
+@table @code
+@item file
+@itemx unix
+These are for Unix-domain sockets.
+@code{file:///var/guix/daemon-socket/socket} is equivalent to
+@file{/var/guix/daemon-socket/socket}.
-@example
-(use-modules (guix gexp) (gnu packages base))
+@item guix
+@cindex daemon, remote access
+@cindex remote access to the daemon
+@cindex daemon, cluster setup
+@cindex clusters, daemon setup
+These URIs denote connections over TCP/IP, without encryption nor
+authentication of the remote host. The URI must specify the host name
+and optionally a port number (by default port 44146 is used):
-(gexp->script "list-files"
- #~(execl #$(file-append coreutils "/bin/ls")
- "ls"))
+@example
+guix://master.guix.example.org:1234
@end example
-When ``running'' it through the store (@pxref{The Store Monad,
-@code{run-with-store}}), we obtain a derivation that produces an
-executable file @file{/gnu/store/@dots{}-list-files} along these lines:
+This setup is suitable on local networks, such as clusters, where only
+trusted nodes may connect to the build daemon at
+@code{master.guix.example.org}.
+
+The @code{--listen} option of @command{guix-daemon} can be used to
+instruct it to listen for TCP connections (@pxref{Invoking guix-daemon,
+@code{--listen}}).
+
+@item ssh
+@cindex SSH access to build daemons
+These URIs allow you to connect to a remote daemon over
+SSH@footnote{This feature requires Guile-SSH (@pxref{Requirements}).}.
+A typical URL might look like this:
@example
-#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
-!#
-(execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
+ssh://charlie@@guix.example.org:22
@end example
-@end deffn
-@deffn {Scheme Procedure} program-file @var{name} @var{exp} @
- [#:guile #f] [#:module-path %load-path]
-Return an object representing the executable store item @var{name} that
-runs @var{gexp}. @var{guile} is the Guile package used to execute that
-script. Imported modules of @var{gexp} are looked up in @var{module-path}.
+As for @command{guix copy}, the usual OpenSSH client configuration files
+are honored (@pxref{Invoking guix copy}).
+@end table
-This is the declarative counterpart of @code{gexp->script}.
+Additional URI schemes may be supported in the future.
+
+@c XXX: Remove this note when the protocol incurs fewer round trips
+@c and when (guix derivations) no longer relies on file system access.
+@quotation Note
+The ability to connect to remote build daemons is considered
+experimental as of @value{VERSION}. Please get in touch with us to
+share any problems or suggestions you may have (@pxref{Contributing}).
+@end quotation
+@end defvr
+
+@deffn {Scheme Procedure} open-connection [@var{uri}] [#:reserve-space? #t]
+Connect to the daemon over the Unix-domain socket at @var{uri} (a string). When
+@var{reserve-space?} is true, instruct it to reserve a little bit of
+extra space on the file system so that the garbage collector can still
+operate should the disk become full. Return a server object.
+
+@var{file} defaults to @var{%default-socket-path}, which is the normal
+location given the options that were passed to @command{configure}.
@end deffn
-@deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @
- [#:set-load-path? #t] [#:module-path %load-path] @
- [#:splice? #f] @
- [#:guile (default-guile)]
-Return a derivation that builds a file @var{name} containing @var{exp}.
-When @var{splice?} is true, @var{exp} is considered to be a list of
-expressions that will be spliced in the resulting file.
+@deffn {Scheme Procedure} close-connection @var{server}
+Close the connection to @var{server}.
+@end deffn
-When @var{set-load-path?} is true, emit code in the resulting file to
-set @code{%load-path} and @code{%load-compiled-path} to honor
-@var{exp}'s imported modules. Look up @var{exp}'s modules in
-@var{module-path}.
+@defvr {Scheme Variable} current-build-output-port
+This variable is bound to a SRFI-39 parameter, which refers to the port
+where build and error logs sent by the daemon should be written.
+@end defvr
-The resulting file holds references to all the dependencies of @var{exp}
-or a subset thereof.
+Procedures that make RPCs all take a server object as their first
+argument.
+
+@deffn {Scheme Procedure} valid-path? @var{server} @var{path}
+@cindex invalid store items
+Return @code{#t} when @var{path} designates a valid store item and
+@code{#f} otherwise (an invalid item may exist on disk but still be
+invalid, for instance because it is the result of an aborted or failed
+build.)
+
+A @code{&store-protocol-error} condition is raised if @var{path} is not
+prefixed by the store directory (@file{/gnu/store}).
@end deffn
-@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} [#:splice? #f]
-Return an object representing the Scheme file @var{name} that contains
-@var{exp}.
-
-This is the declarative counterpart of @code{gexp->file}.
+@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
+Add @var{text} under file @var{name} in the store, and return its store
+path. @var{references} is the list of store paths referred to by the
+resulting store path.
@end deffn
-@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
-Return as a monadic value a derivation that builds a text file
-containing all of @var{text}. @var{text} may list, in addition to
-strings, objects of any type that can be used in a gexp: packages,
-derivations, local file objects, etc. The resulting store file holds
-references to all these.
+@deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
+Build @var{derivations} (a list of @code{<derivation>} objects or
+derivation paths), and return when the worker is done building them.
+Return @code{#t} on success.
+@end deffn
-This variant should be preferred over @code{text-file} anytime the file
-to create will reference items from the store. This is typically the
-case when building a configuration file that embeds store file names,
-like this:
+Note that the @code{(guix monads)} module provides a monad as well as
+monadic versions of the above procedures, with the goal of making it
+more convenient to work with code that accesses the store (@pxref{The
+Store Monad}).
-@example
-(define (profile.sh)
- ;; Return the name of a shell script in the store that
- ;; initializes the 'PATH' environment variable.
- (text-file* "profile.sh"
- "export PATH=" coreutils "/bin:"
- grep "/bin:" sed "/bin\n"))
-@end example
+@c FIXME
+@i{This section is currently incomplete.}
-In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
-will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby
-preventing them from being garbage-collected during its lifetime.
-@end deffn
+@node Derivations
+@section Derivations
-@deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
-Return an object representing store file @var{name} containing
-@var{text}. @var{text} is a sequence of strings and file-like objects,
-as in:
+@cindex derivations
+Low-level build actions and the environment in which they are performed
+are represented by @dfn{derivations}. A derivation contains the
+following pieces of information:
-@example
-(mixed-text-file "profile"
- "export PATH=" coreutils "/bin:" grep "/bin")
-@end example
+@itemize
+@item
+The outputs of the derivation---derivations produce at least one file or
+directory in the store, but may produce more.
-This is the declarative counterpart of @code{text-file*}.
-@end deffn
+@item
+@cindex build-time dependencies
+@cindex dependencies, build-time
+The inputs of the derivations---i.e., its build-time dependencies---which may
+be other derivations or plain files in the store (patches, build scripts,
+etc.)
-@deffn {Scheme Procedure} file-union @var{name} @var{files}
-Return a @code{<computed-file>} that builds a directory containing all of @var{files}.
-Each item in @var{files} must be a two-element list where the first element is the
-file name to use in the new directory, and the second element is a gexp
-denoting the target file. Here's an example:
+@item
+The system type targeted by the derivation---e.g., @code{x86_64-linux}.
-@example
-(file-union "etc"
- `(("hosts" ,(plain-file "hosts"
- "127.0.0.1 localhost"))
- ("bashrc" ,(plain-file "bashrc"
- "alias ls='ls --color=auto'"))))
-@end example
+@item
+The file name of a build script in the store, along with the arguments
+to be passed.
-This yields an @code{etc} directory containing these two files.
-@end deffn
+@item
+A list of environment variables to be defined.
-@deffn {Scheme Procedure} directory-union @var{name} @var{things}
-Return a directory that is the union of @var{things}, where @var{things} is a list of
-file-like objects denoting directories. For example:
+@end itemize
-@example
-(directory-union "guile+emacs" (list guile emacs))
-@end example
+@cindex derivation path
+Derivations allow clients of the daemon to communicate build actions to
+the store. They exist in two forms: as an in-memory representation,
+both on the client- and daemon-side, and as files in the store whose
+name end in @code{.drv}---these files are referred to as @dfn{derivation
+paths}. Derivations paths can be passed to the @code{build-derivations}
+procedure to perform the build actions they prescribe (@pxref{The
+Store}).
-yields a directory that is the union of the @code{guile} and @code{emacs} packages.
-@end deffn
+@cindex fixed-output derivations
+Operations such as file downloads and version-control checkouts for
+which the expected content hash is known in advance are modeled as
+@dfn{fixed-output derivations}. Unlike regular derivations, the outputs
+of a fixed-output derivation are independent of its inputs---e.g., a
+source code download produces the same result regardless of the download
+method and tools being used.
-@deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
-Return a file-like object that expands to the concatenation of @var{obj}
-and @var{suffix}, where @var{obj} is a lowerable object and each
-@var{suffix} is a string.
+@cindex references
+@cindex run-time dependencies
+@cindex dependencies, run-time
+The outputs of derivations---i.e., the build results---have a set of
+@dfn{references}, as reported by the @code{references} RPC or the
+@command{guix gc --references} command (@pxref{Invoking guix gc}). References
+are the set of run-time dependencies of the build results. References are a
+subset of the inputs of the derivation; this subset is automatically computed
+by the build daemon by scanning all the files in the outputs.
-As an example, consider this gexp:
+The @code{(guix derivations)} module provides a representation of
+derivations as Scheme objects, along with procedures to create and
+otherwise manipulate derivations. The lowest-level primitive to create
+a derivation is the @code{derivation} procedure:
-@example
-(gexp->script "run-uname"
- #~(system* #$(file-append coreutils
- "/bin/uname")))
-@end example
+@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
+ @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
+ [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
+ [#:system (%current-system)] [#:references-graphs #f] @
+ [#:allowed-references #f] [#:disallowed-references #f] @
+ [#:leaked-env-vars #f] [#:local-build? #f] @
+ [#:substitutable? #t] [#:properties '()]
+Build a derivation with the given arguments, and return the resulting
+@code{<derivation>} object.
-The same effect could be achieved with:
+When @var{hash} and @var{hash-algo} are given, a
+@dfn{fixed-output derivation} is created---i.e., one whose result is
+known in advance, such as a file download. If, in addition,
+@var{recursive?} is true, then that fixed output may be an executable
+file or a directory and @var{hash} must be the hash of an archive
+containing this output.
-@example
-(gexp->script "run-uname"
- #~(system* (string-append #$coreutils
- "/bin/uname")))
-@end example
+When @var{references-graphs} is true, it must be a list of file
+name/store path pairs. In that case, the reference graph of each store
+path is exported in the build environment in the corresponding file, in
+a simple text format.
-There is one difference though: in the @code{file-append} case, the
-resulting script contains the absolute file name as a string, whereas in
-the second case, the resulting script contains a @code{(string-append
-@dots{})} expression to construct the file name @emph{at run time}.
-@end deffn
+When @var{allowed-references} is true, it must be a list of store items
+or outputs that the derivation's output may refer to. Likewise,
+@var{disallowed-references}, if true, must be a list of things the
+outputs may @emph{not} refer to.
+When @var{leaked-env-vars} is true, it must be a list of strings
+denoting environment variables that are allowed to ``leak'' from the
+daemon's environment to the build environment. This is only applicable
+to fixed-output derivations---i.e., when @var{hash} is true. The main
+use is to allow variables such as @code{http_proxy} to be passed to
+derivations that download files.
-Of course, in addition to gexps embedded in ``host'' code, there are
-also modules containing build tools. To make it clear that they are
-meant to be used in the build stratum, these modules are kept in the
-@code{(guix build @dots{})} name space.
+When @var{local-build?} is true, declare that the derivation is not a
+good candidate for offloading and should rather be built locally
+(@pxref{Daemon Offload Setup}). This is the case for small derivations
+where the costs of data transfers would outweigh the benefits.
-@cindex lowering, of high-level objects in gexps
-Internally, high-level objects are @dfn{lowered}, using their compiler,
-to either derivations or store items. For instance, lowering a package
-yields a derivation, and lowering a @code{plain-file} yields a store
-item. This is achieved using the @code{lower-object} monadic procedure.
+When @var{substitutable?} is false, declare that substitutes of the
+derivation's output should not be used (@pxref{Substitutes}). This is
+useful, for instance, when building packages that capture details of the
+host CPU instruction set.
-@deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
- [#:target #f]
-Return as a value in @var{%store-monad} the derivation or store item
-corresponding to @var{obj} for @var{system}, cross-compiling for
-@var{target} if @var{target} is true. @var{obj} must be an object that
-has an associated gexp compiler, such as a @code{<package>}.
+@var{properties} must be an association list describing ``properties'' of the
+derivation. It is kept as-is, uninterpreted, in the derivation.
@end deffn
-@node Invoking guix repl
-@section Invoking @command{guix repl}
+@noindent
+Here's an example with a shell script as its builder, assuming
+@var{store} is an open connection to the daemon, and @var{bash} points
+to a Bash executable in the store:
-@cindex REPL, read-eval-print loop
-The @command{guix repl} command spawns a Guile @dfn{read-eval-print loop}
-(REPL) for interactive programming (@pxref{Using Guile Interactively,,, guile,
-GNU Guile Reference Manual}). Compared to just launching the @command{guile}
-command, @command{guix repl} guarantees that all the Guix modules and all its
-dependencies are available in the search path. You can use it this way:
+@lisp
+(use-modules (guix utils)
+ (guix store)
+ (guix derivations))
-@example
-$ guix repl
-scheme@@(guile-user)> ,use (gnu packages base)
-scheme@@(guile-user)> coreutils
-$1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300>
-@end example
+(let ((builder ; add the Bash script to the store
+ (add-text-to-store store "my-builder.sh"
+ "echo hello world > $out\n" '())))
+ (derivation store "foo"
+ bash `("-e" ,builder)
+ #:inputs `((,bash) (,builder))
+ #:env-vars '(("HOME" . "/homeless"))))
+@result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
+@end lisp
-@cindex inferiors
-In addition, @command{guix repl} implements a simple machine-readable REPL
-protocol for use by @code{(guix inferior)}, a facility to interact with
-@dfn{inferiors}, separate processes running a potentially different revision
-of Guix.
+As can be guessed, this primitive is cumbersome to use directly. A
+better approach is to write build scripts in Scheme, of course! The
+best course of action for that is to write the build code as a
+``G-expression'', and to pass it to @code{gexp->derivation}. For more
+information, @pxref{G-Expressions}.
+
+Once upon a time, @code{gexp->derivation} did not exist and constructing
+derivations with build code written in Scheme was achieved with
+@code{build-expression->derivation}, documented below. This procedure
+is now deprecated in favor of the much nicer @code{gexp->derivation}.
+
+@deffn {Scheme Procedure} build-expression->derivation @var{store} @
+ @var{name} @var{exp} @
+ [#:system (%current-system)] [#:inputs '()] @
+ [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
+ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
+ [#:references-graphs #f] [#:allowed-references #f] @
+ [#:disallowed-references #f] @
+ [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
+Return a derivation that executes Scheme expression @var{exp} as a
+builder for derivation @var{name}. @var{inputs} must be a list of
+@code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
+@code{"out"} is assumed. @var{modules} is a list of names of Guile
+modules from the current search path to be copied in the store,
+compiled, and made available in the load path during the execution of
+@var{exp}---e.g., @code{((guix build utils) (guix build
+gnu-build-system))}.
+
+@var{exp} is evaluated in an environment where @code{%outputs} is bound
+to a list of output/path pairs, and where @code{%build-inputs} is bound
+to a list of string/output-path pairs made from @var{inputs}.
+Optionally, @var{env-vars} is a list of string pairs specifying the name
+and value of environment variables visible to the builder. The builder
+terminates by passing the result of @var{exp} to @code{exit}; thus, when
+@var{exp} returns @code{#f}, the build is considered to have failed.
-The available options are as follows:
+@var{exp} is built using @var{guile-for-build} (a derivation). When
+@var{guile-for-build} is omitted or is @code{#f}, the value of the
+@code{%guile-for-build} fluid is used instead.
-@table @code
-@item --type=@var{type}
-@itemx -t @var{type}
-Start a REPL of the given @var{TYPE}, which can be one of the following:
+See the @code{derivation} procedure for the meaning of
+@var{references-graphs}, @var{allowed-references},
+@var{disallowed-references}, @var{local-build?}, and
+@var{substitutable?}.
+@end deffn
-@table @code
-@item guile
-This is default, and it spawns a standard full-featured Guile REPL.
-@item machine
-Spawn a REPL that uses the machine-readable protocol. This is the protocol
-that the @code{(guix inferior)} module speaks.
-@end table
+@noindent
+Here's an example of a single-output derivation that creates a directory
+containing one file:
-@item --listen=@var{endpoint}
-By default, @command{guix repl} reads from standard input and writes to
-standard output. When this option is passed, it will instead listen for
-connections on @var{endpoint}. Here are examples of valid options:
+@lisp
+(let ((builder '(let ((out (assoc-ref %outputs "out")))
+ (mkdir out) ; create /gnu/store/@dots{}-goo
+ (call-with-output-file (string-append out "/test")
+ (lambda (p)
+ (display '(hello guix) p))))))
+ (build-expression->derivation store "goo" builder))
-@table @code
-@item --listen=tcp:37146
-Accept connections on localhost on port 37146.
+@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
+@end lisp
-@item --listen=unix:/tmp/socket
-Accept connections on the Unix-domain socket @file{/tmp/socket}.
-@end table
-@end table
-@c *********************************************************************
-@node Utilities
-@chapter Utilities
+@node The Store Monad
+@section The Store Monad
-This section describes Guix command-line utilities. Some of them are
-primarily targeted at developers and users who write new package
-definitions, while others are more generally useful. They complement
-the Scheme programming interface of Guix in a convenient way.
+@cindex monad
-@menu
-* Invoking guix build:: Building packages from the command line.
-* Invoking guix edit:: Editing package definitions.
-* Invoking guix download:: Downloading a file and printing its hash.
-* Invoking guix hash:: Computing the cryptographic hash of a file.
-* Invoking guix import:: Importing package definitions.
-* Invoking guix refresh:: Updating package definitions.
-* Invoking guix lint:: Finding errors in package definitions.
-* Invoking guix size:: Profiling disk usage.
-* Invoking guix graph:: Visualizing the graph of packages.
-* Invoking guix environment:: Setting up development environments.
-* Invoking guix publish:: Sharing substitutes.
-* Invoking guix challenge:: Challenging substitute servers.
-* Invoking guix copy:: Copying to and from a remote store.
-* Invoking guix container:: Process isolation.
-* Invoking guix weather:: Assessing substitute availability.
-* Invoking guix processes:: Listing client processes.
-@end menu
+The procedures that operate on the store described in the previous
+sections all take an open connection to the build daemon as their first
+argument. Although the underlying model is functional, they either have
+side effects or depend on the current state of the store.
-@node Invoking guix build
-@section Invoking @command{guix build}
+The former is inconvenient: the connection to the build daemon has to be
+carried around in all those functions, making it impossible to compose
+functions that do not take that parameter with functions that do. The
+latter can be problematic: since store operations have side effects
+and/or depend on external state, they have to be properly sequenced.
-@cindex package building
-@cindex @command{guix build}
-The @command{guix build} command builds packages or derivations and
-their dependencies, and prints the resulting store paths. Note that it
-does not modify the user's profile---this is the job of the
-@command{guix package} command (@pxref{Invoking guix package}). Thus,
-it is mainly useful for distribution developers.
+@cindex monadic values
+@cindex monadic functions
+This is where the @code{(guix monads)} module comes in. This module
+provides a framework for working with @dfn{monads}, and a particularly
+useful monad for our uses, the @dfn{store monad}. Monads are a
+construct that allows two things: associating ``context'' with values
+(in our case, the context is the store), and building sequences of
+computations (here computations include accesses to the store). Values
+in a monad---values that carry this additional context---are called
+@dfn{monadic values}; procedures that return such values are called
+@dfn{monadic procedures}.
-The general syntax is:
+Consider this ``normal'' procedure:
@example
-guix build @var{options} @var{package-or-derivation}@dots{}
+(define (sh-symlink store)
+ ;; Return a derivation that symlinks the 'bash' executable.
+ (let* ((drv (package-derivation store bash))
+ (out (derivation->output-path drv))
+ (sh (string-append out "/bin/bash")))
+ (build-expression->derivation store "sh"
+ `(symlink ,sh %output))))
@end example
-As an example, the following command builds the latest versions of Emacs
-and of Guile, displays their build logs, and finally displays the
-resulting directories:
+Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
+as a monadic function:
@example
-guix build emacs guile
+(define (sh-symlink)
+ ;; Same, but return a monadic value.
+ (mlet %store-monad ((drv (package->derivation bash)))
+ (gexp->derivation "sh"
+ #~(symlink (string-append #$drv "/bin/bash")
+ #$output))))
@end example
-Similarly, the following command builds all the available packages:
+There are several things to note in the second version: the @code{store}
+parameter is now implicit and is ``threaded'' in the calls to the
+@code{package->derivation} and @code{gexp->derivation} monadic
+procedures, and the monadic value returned by @code{package->derivation}
+is @dfn{bound} using @code{mlet} instead of plain @code{let}.
+
+As it turns out, the call to @code{package->derivation} can even be
+omitted since it will take place implicitly, as we will see later
+(@pxref{G-Expressions}):
@example
-guix build --quiet --keep-going \
- `guix package -A | cut -f1,2 --output-delimiter=@@`
+(define (sh-symlink)
+ (gexp->derivation "sh"
+ #~(symlink (string-append #$bash "/bin/bash")
+ #$output)))
@end example
-@var{package-or-derivation} may be either the name of a package found in
-the software distribution such as @code{coreutils} or
-@code{coreutils@@8.20}, or a derivation such as
-@file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
-package with the corresponding name (and optionally version) is searched
-for among the GNU distribution modules (@pxref{Package Modules}).
-
-Alternatively, the @code{--expression} option may be used to specify a
-Scheme expression that evaluates to a package; this is useful when
-disambiguating among several same-named packages or package variants is
-needed.
-
-There may be zero or more @var{options}. The available options are
-described in the subsections below.
-
-@menu
-* Common Build Options:: Build options for most commands.
-* Package Transformation Options:: Creating variants of packages.
-* Additional Build Options:: Options specific to 'guix build'.
-* Debugging Build Failures:: Real life packaging experience.
-@end menu
-
-@node Common Build Options
-@subsection Common Build Options
-
-A number of options that control the build process are common to
-@command{guix build} and other commands that can spawn builds, such as
-@command{guix package} or @command{guix archive}. These are the
-following:
-
-@table @code
-
-@item --load-path=@var{directory}
-@itemx -L @var{directory}
-Add @var{directory} to the front of the package module search path
-(@pxref{Package Modules}).
-
-This allows users to define their own packages and make them visible to
-the command-line tools.
-
-@item --keep-failed
-@itemx -K
-Keep the build tree of failed builds. Thus, if a build fails, its build
-tree is kept under @file{/tmp}, in a directory whose name is shown at
-the end of the build log. This is useful when debugging build issues.
-@xref{Debugging Build Failures}, for tips and tricks on how to debug
-build issues.
-
-This option has no effect when connecting to a remote daemon with a
-@code{guix://} URI (@pxref{The Store, the @code{GUIX_DAEMON_SOCKET}
-variable}).
-
-@item --keep-going
-@itemx -k
-Keep going when some of the derivations fail to build; return only once
-all the builds have either completed or failed.
-
-The default behavior is to stop as soon as one of the specified
-derivations has failed.
-
-@item --dry-run
-@itemx -n
-Do not build the derivations.
-
-@anchor{fallback-option}
-@item --fallback
-When substituting a pre-built binary fails, fall back to building
-packages locally (@pxref{Substitution Failure}).
+@c See
+@c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
+@c for the funny quote.
+Calling the monadic @code{sh-symlink} has no effect. As someone once
+said, ``you exit a monad like you exit a building on fire: by running''.
+So, to exit the monad and get the desired effect, one must use
+@code{run-with-store}:
-@item --substitute-urls=@var{urls}
-@anchor{client-substitute-urls}
-Consider @var{urls} the whitespace-separated list of substitute source
-URLs, overriding the default list of URLs of @command{guix-daemon}
-(@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).
+@example
+(run-with-store (open-connection) (sh-symlink))
+@result{} /gnu/store/...-sh-symlink
+@end example
-This means that substitutes may be downloaded from @var{urls}, provided
-they are signed by a key authorized by the system administrator
-(@pxref{Substitutes}).
+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
+to ``run'' a single monadic value through the store:
-When @var{urls} is the empty string, substitutes are effectively
-disabled.
+@example
+scheme@@(guile-user)> ,run-in-store (package->derivation hello)
+$1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
+@end example
-@item --no-substitutes
-Do not use substitutes for build products. That is, always build things
-locally instead of allowing downloads of pre-built binaries
-(@pxref{Substitutes}).
+The latter enters a recursive REPL, where all the return values are
+automatically run through the store:
-@item --no-grafts
-Do not ``graft'' packages. In practice, this means that package updates
-available as grafts are not applied. @xref{Security Updates}, for more
-information on grafts.
+@example
+scheme@@(guile-user)> ,enter-store-monad
+store-monad@@(guile-user) [1]> (package->derivation hello)
+$2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
+store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
+$3 = "/gnu/store/@dots{}-foo"
+store-monad@@(guile-user) [1]> ,q
+scheme@@(guile-user)>
+@end example
-@item --rounds=@var{n}
-Build each derivation @var{n} times in a row, and raise an error if
-consecutive build results are not bit-for-bit identical.
+@noindent
+Note that non-monadic values cannot be returned in the
+@code{store-monad} REPL.
-This is a useful way to detect non-deterministic builds processes.
-Non-deterministic build processes are a problem because they make it
-practically impossible for users to @emph{verify} whether third-party
-binaries are genuine. @xref{Invoking guix challenge}, for more.
+The main syntactic forms to deal with monads in general are provided by
+the @code{(guix monads)} module and are described below.
-Note that, currently, the differing build results are not kept around,
-so you will have to manually investigate in case of an error---e.g., by
-stashing one of the build results with @code{guix archive --export}
-(@pxref{Invoking guix archive}), then rebuilding, and finally comparing
-the two results.
+@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
+Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
+in @var{monad}.
+@end deffn
-@item --no-build-hook
-Do not attempt to offload builds @i{via} the ``build hook'' of the daemon
-(@pxref{Daemon Offload Setup}). That is, always build things locally
-instead of offloading builds to remote machines.
+@deffn {Scheme Syntax} return @var{val}
+Return a monadic value that encapsulates @var{val}.
+@end deffn
-@item --max-silent-time=@var{seconds}
-When the build or substitution process remains silent for more than
-@var{seconds}, terminate it and report a build failure.
+@deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ...
+@dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
+procedures @var{mproc}@dots{}@footnote{This operation is commonly
+referred to as ``bind'', but that name denotes an unrelated procedure in
+Guile. Thus we use this somewhat cryptic symbol inherited from the
+Haskell language.}. There can be one @var{mproc} or several of them, as
+in this example:
-By default, the daemon's setting is honored (@pxref{Invoking
-guix-daemon, @code{--max-silent-time}}).
+@example
+(run-with-state
+ (with-monad %state-monad
+ (>>= (return 1)
+ (lambda (x) (return (+ 1 x)))
+ (lambda (x) (return (* 2 x)))))
+ 'some-state)
-@item --timeout=@var{seconds}
-Likewise, when the build or substitution process lasts for more than
-@var{seconds}, terminate it and report a build failure.
+@result{} 4
+@result{} some-state
+@end example
+@end deffn
-By default, the daemon's setting is honored (@pxref{Invoking
-guix-daemon, @code{--timeout}}).
+@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
+ @var{body} ...
+@deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
+ @var{body} ...
+Bind the variables @var{var} to the monadic values @var{mval} in
+@var{body}, which is a sequence of expressions. As with the bind
+operator, this can be thought of as ``unpacking'' the raw, non-monadic
+value ``contained'' in @var{mval} and making @var{var} refer to that
+raw, non-monadic value within the scope of the @var{body}. The form
+(@var{var} -> @var{val}) binds @var{var} to the ``normal'' value
+@var{val}, as per @code{let}. The binding operations occur in sequence
+from left to right. The last expression of @var{body} must be a monadic
+expression, and its result will become the result of the @code{mlet} or
+@code{mlet*} when run in the @var{monad}.
-@c Note: This option is actually not part of %standard-build-options but
-@c most programs honor it.
-@cindex verbosity, of the command-line tools
-@cindex build logs, verbosity
-@item -v @var{level}
-@itemx --verbosity=@var{level}
-Use the given verbosity @var{level}, an integer. Choosing 0 means that no
-output is produced, 1 is for quiet output, and 2 shows all the build log
-output on standard error.
+@code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
+(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
+@end deffn
-@item --cores=@var{n}
-@itemx -c @var{n}
-Allow the use of up to @var{n} CPU cores for the build. The special
-value @code{0} means to use as many CPU cores as available.
+@deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
+Bind @var{mexp} and the following monadic expressions in sequence,
+returning the result of the last expression. Every expression in the
+sequence must be a monadic expression.
-@item --max-jobs=@var{n}
-@itemx -M @var{n}
-Allow at most @var{n} build jobs in parallel. @xref{Invoking
-guix-daemon, @code{--max-jobs}}, for details about this option and the
-equivalent @command{guix-daemon} option.
+This is akin to @code{mlet}, except that the return values of the
+monadic expressions are ignored. In that sense, it is analogous to
+@code{begin}, but applied to monadic expressions.
+@end deffn
-@item --debug=@var{level}
-Produce debugging output coming from the build daemon. @var{level} must be an
-integer between 0 and 5; higher means more verbose output. Setting a level of
-4 or more may be helpful when debugging setup issues with the build daemon.
+@deffn {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ...
+When @var{condition} is true, evaluate the sequence of monadic
+expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
+@var{condition} is false, return @code{*unspecified*} in the current
+monad. Every expression in the sequence must be a monadic expression.
+@end deffn
-@end table
+@deffn {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} ...
+When @var{condition} is false, evaluate the sequence of monadic
+expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
+@var{condition} is true, return @code{*unspecified*} in the current
+monad. Every expression in the sequence must be a monadic expression.
+@end deffn
-Behind the scenes, @command{guix build} is essentially an interface to
-the @code{package-derivation} procedure of the @code{(guix packages)}
-module, and to the @code{build-derivations} procedure of the @code{(guix
-derivations)} module.
+@cindex state monad
+The @code{(guix monads)} module provides the @dfn{state monad}, which
+allows an additional value---the state---to be @emph{threaded} through
+monadic procedure calls.
-In addition to options explicitly passed on the command line,
-@command{guix build} and other @command{guix} commands that support
-building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
+@defvr {Scheme Variable} %state-monad
+The state monad. Procedures in the state monad can access and change
+the state that is threaded.
-@defvr {Environment Variable} GUIX_BUILD_OPTIONS
-Users can define this variable to a list of command line options that
-will automatically be used by @command{guix build} and other
-@command{guix} commands that can perform builds, as in the example
-below:
+Consider the example below. The @code{square} procedure returns a value
+in the state monad. It returns the square of its argument, but also
+increments the current state value:
@example
-$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
+(define (square x)
+ (mlet %state-monad ((count (current-state)))
+ (mbegin %state-monad
+ (set-current-state (+ 1 count))
+ (return (* x x)))))
+
+(run-with-state (sequence %state-monad (map square (iota 3))) 0)
+@result{} (0 1 4)
+@result{} 3
@end example
-These options are parsed independently, and the result is appended to
-the parsed command-line options.
+When ``run'' through @var{%state-monad}, we obtain that additional state
+value, which is the number of @code{square} calls.
@end defvr
+@deffn {Monadic Procedure} current-state
+Return the current state as a monadic value.
+@end deffn
-@node Package Transformation Options
-@subsection Package Transformation Options
-
-@cindex package variants
-Another set of command-line options supported by @command{guix build}
-and also @command{guix package} are @dfn{package transformation
-options}. These are options that make it possible to define @dfn{package
-variants}---for instance, packages built from different source code.
-This is a convenient way to create customized packages on the fly
-without having to type in the definitions of package variants
-(@pxref{Defining Packages}).
-
-@table @code
-
-@item --with-source=@var{source}
-@itemx --with-source=@var{package}=@var{source}
-@itemx --with-source=@var{package}@@@var{version}=@var{source}
-Use @var{source} as the source of @var{package}, and @var{version} as
-its version number.
-@var{source} must be a file name or a URL, as for @command{guix
-download} (@pxref{Invoking guix download}).
-
-When @var{package} is omitted,
-it is taken to be the package name specified on the
-command line that matches the base of @var{source}---e.g.,
-if @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
-package is @code{guile}.
-
-Likewise, when @var{version} is omitted, the version string is inferred from
-@var{source}; in the previous example, it is @code{2.0.10}.
+@deffn {Monadic Procedure} set-current-state @var{value}
+Set the current state to @var{value} and return the previous state as a
+monadic value.
+@end deffn
-This option allows users to try out versions of packages other than the
-one provided by the distribution. The example below downloads
-@file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
-the @code{ed} package:
+@deffn {Monadic Procedure} state-push @var{value}
+Push @var{value} to the current state, which is assumed to be a list,
+and return the previous state as a monadic value.
+@end deffn
-@example
-guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
-@end example
+@deffn {Monadic Procedure} state-pop
+Pop a value from the current state and return it as a monadic value.
+The state is assumed to be a list.
+@end deffn
-As a developer, @code{--with-source} makes it easy to test release
-candidates:
+@deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
+Run monadic value @var{mval} starting with @var{state} as the initial
+state. Return two values: the resulting value, and the resulting state.
+@end deffn
-@example
-guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
-@end example
+The main interface to the store monad, provided by the @code{(guix
+store)} module, is as follows.
-@dots{} or to build from a checkout in a pristine environment:
+@defvr {Scheme Variable} %store-monad
+The store monad---an alias for @var{%state-monad}.
-@example
-$ git clone git://git.sv.gnu.org/guix.git
-$ guix build guix --with-source=guix@@1.0=./guix
-@end example
+Values in the store monad encapsulate accesses to the store. When its
+effect is needed, a value of the store monad must be ``evaluated'' by
+passing it to the @code{run-with-store} procedure (see below.)
+@end defvr
-@item --with-input=@var{package}=@var{replacement}
-Replace dependency on @var{package} by a dependency on
-@var{replacement}. @var{package} must be a package name, and
-@var{replacement} must be a package specification such as @code{guile}
-or @code{guile@@1.8}.
+@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
+Run @var{mval}, a monadic value in the store monad, in @var{store}, an
+open store connection.
+@end deffn
-For instance, the following command builds Guix, but replaces its
-dependency on the current stable version of Guile with a dependency on
-the legacy version of Guile, @code{guile@@2.0}:
+@deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
+Return as a monadic value the absolute file name in the store of the file
+containing @var{text}, a string. @var{references} is a list of store items that the
+resulting text file refers to; it defaults to the empty list.
+@end deffn
-@example
-guix build --with-input=guile=guile@@2.0 guix
-@end example
+@deffn {Monadic Procedure} binary-file @var{name} @var{data} [@var{references}]
+Return as a monadic value the absolute file name in the store of the file
+containing @var{data}, a bytevector. @var{references} is a list of store
+items that the resulting binary file refers to; it defaults to the empty list.
+@end deffn
-This is a recursive, deep replacement. So in this example, both
-@code{guix} and its dependency @code{guile-json} (which also depends on
-@code{guile}) get rebuilt against @code{guile@@2.0}.
+@deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
+ [#:recursive? #t] [#:select? (const #t)]
+Return the name of @var{file} once interned in the store. Use
+@var{name} as its store name, or the basename of @var{file} if
+@var{name} is omitted.
-This is implemented using the @code{package-input-rewriting} Scheme
-procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).
+When @var{recursive?} is true, the contents of @var{file} are added
+recursively; if @var{file} designates a flat file and @var{recursive?}
+is true, its contents are added, and its permission bits are kept.
-@item --with-graft=@var{package}=@var{replacement}
-This is similar to @code{--with-input} but with an important difference:
-instead of rebuilding the whole dependency chain, @var{replacement} is
-built and then @dfn{grafted} onto the binaries that were initially
-referring to @var{package}. @xref{Security Updates}, for more
-information on grafts.
+When @var{recursive?} is true, call @code{(@var{select?} @var{file}
+@var{stat})} for each directory entry, where @var{file} is the entry's
+absolute file name and @var{stat} is the result of @code{lstat}; exclude
+entries for which @var{select?} does not return true.
-For example, the command below grafts version 3.5.4 of GnuTLS onto Wget
-and all its dependencies, replacing references to the version of GnuTLS
-they currently refer to:
+The example below adds a file to the store, under two different names:
@example
-guix build --with-graft=gnutls=gnutls@@3.5.4 wget
+(run-with-store (open-connection)
+ (mlet %store-monad ((a (interned-file "README"))
+ (b (interned-file "README" "LEGU-MIN")))
+ (return (list a b))))
+
+@result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
@end example
-This has the advantage of being much faster than rebuilding everything.
-But there is a caveat: it works if and only if @var{package} and
-@var{replacement} are strictly compatible---for example, if they provide
-a library, the application binary interface (ABI) of those libraries
-must be compatible. If @var{replacement} is somehow incompatible with
-@var{package}, then the resulting package may be unusable. Use with
-care!
+@end deffn
-@item --with-branch=@var{package}=@var{branch}
-@cindex Git, using the latest commit
-@cindex latest commit, building
-Build @var{package} from the latest commit of @var{branch}. The @code{source}
-field of @var{package} must be an origin with the @code{git-fetch} method
-(@pxref{origin Reference}) or a @code{git-checkout} object; the repository URL
-is taken from that @code{source}.
+The @code{(guix packages)} module exports the following package-related
+monadic procedures:
-For instance, the following command builds @code{guile-sqlite3} from the
-latest commit of its @code{master} branch, and then builds @code{guix} (which
-depends on it) and @code{cuirass} (which depends on @code{guix}) against this
-specific @code{guile-sqlite3} build:
+@deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
+ [#:system (%current-system)] [#:target #f] @
+ [#:output "out"]
+Return as a monadic
+value in the absolute file name of @var{file} within the @var{output}
+directory of @var{package}. When @var{file} is omitted, return the name
+of the @var{output} directory of @var{package}. When @var{target} is
+true, use it as a cross-compilation target triplet.
+@end deffn
-@example
-guix build --with-branch=guile-sqlite3=master cuirass
-@end example
+@deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
+@deffnx {Monadic Procedure} package->cross-derivation @var{package} @
+ @var{target} [@var{system}]
+Monadic version of @code{package-derivation} and
+@code{package-cross-derivation} (@pxref{Defining Packages}).
+@end deffn
-@cindex continuous integration
-Obviously, since it uses the latest commit of the given branch, the result of
-such a command varies over time. Nevertheless it is a convenient way to
-rebuild entire software stacks against the latest commit of one or more
-packages. This is particularly useful in the context of continuous
-integration (CI).
-Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed up
-consecutive accesses to the same repository. You may want to clean it up once
-in a while to save disk space.
+@node G-Expressions
+@section G-Expressions
-@item --with-commit=@var{package}=@var{commit}
-This is similar to @code{--with-branch}, except that it builds from
-@var{commit} rather than the tip of a branch. @var{commit} must be a valid
-Git commit SHA1 identifier.
-@end table
+@cindex G-expression
+@cindex build code quoting
+So we have ``derivations'', which represent a sequence of build actions
+to be performed to produce an item in the store (@pxref{Derivations}).
+These build actions are performed when asking the daemon to actually
+build the derivations; they are run by the daemon in a container
+(@pxref{Invoking guix-daemon}).
-@node Additional Build Options
-@subsection Additional Build Options
+@cindex strata of code
+It should come as no surprise that we like to write these build actions
+in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
+code@footnote{The term @dfn{stratum} in this context was coined by
+Manuel Serrano et al.@: in the context of their work on Hop. Oleg
+Kiselyov, who has written insightful
+@url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
+on this topic}, refers to this kind of code generation as
+@dfn{staging}.}: the ``host code''---code that defines packages, talks
+to the daemon, etc.---and the ``build code''---code that actually
+performs build actions, such as making directories, invoking
+@command{make}, etc.
-The command-line options presented below are specific to @command{guix
-build}.
+To describe a derivation and its build actions, one typically needs to
+embed build code inside host code. It boils down to manipulating build
+code as data, and the homoiconicity of Scheme---code has a direct
+representation as data---comes in handy for that. But we need more than
+the normal @code{quasiquote} mechanism in Scheme to construct build
+expressions.
-@table @code
+The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
+S-expressions adapted to build expressions. G-expressions, or
+@dfn{gexps}, consist essentially of three syntactic forms: @code{gexp},
+@code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
+@code{#$}, and @code{#$@@}), which are comparable to
+@code{quasiquote}, @code{unquote}, and @code{unquote-splicing},
+respectively (@pxref{Expression Syntax, @code{quasiquote},, guile,
+GNU Guile Reference Manual}). However, there are major differences:
-@item --quiet
-@itemx -q
-Build quietly, without displaying the build log; this is equivalent to
-@code{--verbosity=0}. Upon completion, the build log is kept in @file{/var}
-(or similar) and can always be retrieved using the @option{--log-file} option.
+@itemize
+@item
+Gexps are meant to be written to a file and run or manipulated by other
+processes.
-@item --file=@var{file}
-@itemx -f @var{file}
-Build the package, derivation, or other file-like object that the code within
-@var{file} evaluates to (@pxref{G-Expressions, file-like objects}).
+@item
+When a high-level object such as a package or derivation is unquoted
+inside a gexp, the result is as if its output file name had been
+introduced.
-As an example, @var{file} might contain a package definition like this
-(@pxref{Defining Packages}):
+@item
+Gexps carry information about the packages or derivations they refer to,
+and these dependencies are automatically added as inputs to the build
+processes that use them.
+@end itemize
+
+@cindex lowering, of high-level objects in gexps
+This mechanism is not limited to package and derivation
+objects: @dfn{compilers} able to ``lower'' other high-level objects to
+derivations or files in the store can be defined,
+such that these objects can also be inserted
+into gexps. For example, a useful type of high-level objects that can be
+inserted in a gexp is ``file-like objects'', which make it easy to
+add files to the store and to refer to them in
+derivations and such (see @code{local-file} and @code{plain-file}
+below.)
+
+To illustrate the idea, here is an example of a gexp:
@example
-@verbatiminclude package-hello.scm
+(define build-exp
+ #~(begin
+ (mkdir #$output)
+ (chdir #$output)
+ (symlink (string-append #$coreutils "/bin/ls")
+ "list-files")))
@end example
-@item --expression=@var{expr}
-@itemx -e @var{expr}
-Build the package or derivation @var{expr} evaluates to.
+This gexp can be passed to @code{gexp->derivation}; we obtain a
+derivation that builds a directory containing exactly one symlink to
+@file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
-For example, @var{expr} may be @code{(@@ (gnu packages guile)
-guile-1.8)}, which unambiguously designates this specific variant of
-version 1.8 of Guile.
+@example
+(gexp->derivation "the-thing" build-exp)
+@end example
-Alternatively, @var{expr} may be a G-expression, in which case it is used
-as a build program passed to @code{gexp->derivation}
-(@pxref{G-Expressions}).
+As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
+substituted to the reference to the @var{coreutils} package in the
+actual build code, and @var{coreutils} is automatically made an input to
+the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
+output)}) is replaced by a string containing the directory name of the
+output of the derivation.
-Lastly, @var{expr} may refer to a zero-argument monadic procedure
-(@pxref{The Store Monad}). The procedure must return a derivation as a
-monadic value, which is then passed through @code{run-with-store}.
+@cindex cross compilation
+In a cross-compilation context, it is useful to distinguish between
+references to the @emph{native} build of a package---that can run on the
+host---versus references to cross builds of a package. To that end, the
+@code{#+} plays the same role as @code{#$}, but is a reference to a
+native package build:
-@item --source
-@itemx -S
-Build the source derivations of the packages, rather than the packages
-themselves.
+@example
+(gexp->derivation "vi"
+ #~(begin
+ (mkdir #$output)
+ (system* (string-append #+coreutils "/bin/ln")
+ "-s"
+ (string-append #$emacs "/bin/emacs")
+ (string-append #$output "/bin/vi")))
+ #:target "mips64el-linux-gnu")
+@end example
-For instance, @code{guix build -S gcc} returns something like
-@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC
-source tarball.
+@noindent
+In the example above, the native build of @var{coreutils} is used, so
+that @command{ln} can actually run on the host; but then the
+cross-compiled build of @var{emacs} is referenced.
-The returned source tarball is the result of applying any patches and
-code snippets specified in the package @code{origin} (@pxref{Defining
-Packages}).
+@cindex imported modules, for gexps
+@findex with-imported-modules
+Another gexp feature is @dfn{imported modules}: sometimes you want to be
+able to use certain Guile modules from the ``host environment'' in the
+gexp, so those modules should be imported in the ``build environment''.
+The @code{with-imported-modules} form allows you to express that:
-@item --sources
-Fetch and return the source of @var{package-or-derivation} and all their
-dependencies, recursively. This is a handy way to obtain a local copy
-of all the source code needed to build @var{packages}, allowing you to
-eventually build them even without network access. It is an extension
-of the @code{--source} option and can accept one of the following
-optional argument values:
+@example
+(let ((build (with-imported-modules '((guix build utils))
+ #~(begin
+ (use-modules (guix build utils))
+ (mkdir-p (string-append #$output "/bin"))))))
+ (gexp->derivation "empty-dir"
+ #~(begin
+ #$build
+ (display "success!\n")
+ #t)))
+@end example
-@table @code
-@item package
-This value causes the @code{--sources} option to behave in the same way
-as the @code{--source} option.
+@noindent
+In this example, the @code{(guix build utils)} module is automatically
+pulled into the isolated build environment of our gexp, such that
+@code{(use-modules (guix build utils))} works as expected.
-@item all
-Build the source derivations of all packages, including any source that
-might be listed as @code{inputs}. This is the default value.
+@cindex module closure
+@findex source-module-closure
+Usually you want the @emph{closure} of the module to be imported---i.e.,
+the module itself and all the modules it depends on---rather than just
+the module; failing to do that, attempts to use the module will fail
+because of missing dependent modules. The @code{source-module-closure}
+procedure computes the closure of a module by looking at its source file
+headers, which comes in handy in this case:
@example
-$ guix build --sources tzdata
-The following derivations will be built:
- /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
- /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
+(use-modules (guix modules)) ;for 'source-module-closure'
+
+(with-imported-modules (source-module-closure
+ '((guix build utils)
+ (gnu build vm)))
+ (gexp->derivation "something-with-vms"
+ #~(begin
+ (use-modules (guix build utils)
+ (gnu build vm))
+ @dots{})))
@end example
-@item transitive
-Build the source derivations of all packages, as well of all transitive
-inputs to the packages. This can be used e.g.@: to
-prefetch package source for later offline building.
+@cindex extensions, for gexps
+@findex with-extensions
+In the same vein, sometimes you want to import not just pure-Scheme
+modules, but also ``extensions'' such as Guile bindings to C libraries
+or other ``full-blown'' packages. Say you need the @code{guile-json}
+package available on the build side, here's how you would do it:
@example
-$ guix build --sources=transitive tzdata
-The following derivations will be built:
- /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
- /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
- /gnu/store/@dots{}-grep-2.21.tar.xz.drv
- /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
- /gnu/store/@dots{}-make-4.1.tar.xz.drv
- /gnu/store/@dots{}-bash-4.3.tar.xz.drv
-@dots{}
-@end example
-
-@end table
+(use-modules (gnu packages guile)) ;for 'guile-json'
-@item --system=@var{system}
-@itemx -s @var{system}
-Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
-the system type of the build host.
+(with-extensions (list guile-json)
+ (gexp->derivation "something-with-json"
+ #~(begin
+ (use-modules (json))
+ @dots{})))
+@end example
-@quotation Note
-The @code{--system} flag is for @emph{native} compilation and must not
-be confused with cross-compilation. See @code{--target} below for
-information on cross-compilation.
-@end quotation
+The syntactic form to construct gexps is summarized below.
-An example use of this is on Linux-based systems, which can emulate
-different personalities. For instance, passing
-@code{--system=i686-linux} on an @code{x86_64-linux} system or
-@code{--system=armhf-linux} on an @code{aarch64-linux} system allows you
-to build packages in a complete 32-bit environment.
+@deffn {Scheme Syntax} #~@var{exp}
+@deffnx {Scheme Syntax} (gexp @var{exp})
+Return a G-expression containing @var{exp}. @var{exp} may contain one
+or more of the following forms:
-@quotation Note
-Building for an @code{armhf-linux} system is unconditionally enabled on
-@code{aarch64-linux} machines, although certain aarch64 chipsets do not
-allow for this functionality, notably the ThunderX.
-@end quotation
+@table @code
+@item #$@var{obj}
+@itemx (ungexp @var{obj})
+Introduce a reference to @var{obj}. @var{obj} may have one of the
+supported types, for example a package or a
+derivation, in which case the @code{ungexp} form is replaced by its
+output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
-Similarly, when transparent emulation with QEMU and @code{binfmt_misc}
-is enabled (@pxref{Virtualization Services,
-@code{qemu-binfmt-service-type}}), you can build for any system for
-which a QEMU @code{binfmt_misc} handler is installed.
+If @var{obj} is a list, it is traversed and references to supported
+objects are substituted similarly.
-Builds for a system other than that of the machine you are using can
-also be offloaded to a remote machine of the right architecture.
-@xref{Daemon Offload Setup}, for more information on offloading.
+If @var{obj} is another gexp, its contents are inserted and its
+dependencies are added to those of the containing gexp.
-@item --target=@var{triplet}
-@cindex cross-compilation
-Cross-build for @var{triplet}, which must be a valid GNU triplet, such
-as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
-configuration triplets,, autoconf, Autoconf}).
+If @var{obj} is another kind of object, it is inserted as is.
-@anchor{build-check}
-@item --check
-@cindex determinism, checking
-@cindex reproducibility, checking
-Rebuild @var{package-or-derivation}, which are already available in the
-store, and raise an error if the build results are not bit-for-bit
-identical.
+@item #$@var{obj}:@var{output}
+@itemx (ungexp @var{obj} @var{output})
+This is like the form above, but referring explicitly to the
+@var{output} of @var{obj}---this is useful when @var{obj} produces
+multiple outputs (@pxref{Packages with Multiple Outputs}).
-This mechanism allows you to check whether previously installed
-substitutes are genuine (@pxref{Substitutes}), or whether the build result
-of a package is deterministic. @xref{Invoking guix challenge}, for more
-background information and tools.
+@item #+@var{obj}
+@itemx #+@var{obj}:output
+@itemx (ungexp-native @var{obj})
+@itemx (ungexp-native @var{obj} @var{output})
+Same as @code{ungexp}, but produces a reference to the @emph{native}
+build of @var{obj} when used in a cross compilation context.
-When used in conjunction with @option{--keep-failed}, the differing
-output is kept in the store, under @file{/gnu/store/@dots{}-check}.
-This makes it easy to look for differences between the two results.
+@item #$output[:@var{output}]
+@itemx (ungexp output [@var{output}])
+Insert a reference to derivation output @var{output}, or to the main
+output when @var{output} is omitted.
-@item --repair
-@cindex repairing store items
-@cindex corruption, recovering from
-Attempt to repair the specified store items, if they are corrupt, by
-re-downloading or rebuilding them.
+This only makes sense for gexps passed to @code{gexp->derivation}.
-This operation is not atomic and thus restricted to @code{root}.
+@item #$@@@var{lst}
+@itemx (ungexp-splicing @var{lst})
+Like the above, but splices the contents of @var{lst} inside the
+containing list.
-@item --derivations
-@itemx -d
-Return the derivation paths, not the output paths, of the given
-packages.
+@item #+@@@var{lst}
+@itemx (ungexp-native-splicing @var{lst})
+Like the above, but refers to native builds of the objects listed in
+@var{lst}.
-@item --root=@var{file}
-@itemx -r @var{file}
-@cindex GC roots, adding
-@cindex garbage collector roots, adding
-Make @var{file} a symlink to the result, and register it as a garbage
-collector root.
+@end table
-Consequently, the results of this @command{guix build} invocation are
-protected from garbage collection until @var{file} is removed. When
-that option is omitted, build results are eligible for garbage
-collection as soon as the build completes. @xref{Invoking guix gc}, for
-more on GC roots.
+G-expressions created by @code{gexp} or @code{#~} are run-time objects
+of the @code{gexp?} type (see below.)
+@end deffn
-@item --log-file
-@cindex build logs, access
-Return the build log file names or URLs for the given
-@var{package-or-derivation}, or raise an error if build logs are
-missing.
+@deffn {Scheme Syntax} with-imported-modules @var{modules} @var{body}@dots{}
+Mark the gexps defined in @var{body}@dots{} as requiring @var{modules}
+in their execution environment.
-This works regardless of how packages or derivations are specified. For
-instance, the following invocations are equivalent:
+Each item in @var{modules} can be the name of a module, such as
+@code{(guix build utils)}, or it can be a module name, followed by an
+arrow, followed by a file-like object:
@example
-guix build --log-file `guix build -d guile`
-guix build --log-file `guix build guile`
-guix build --log-file guile
-guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
+`((guix build utils)
+ (guix gcrypt)
+ ((guix config) => ,(scheme-file "config.scm"
+ #~(define-module @dots{}))))
@end example
-If a log is unavailable locally, and unless @code{--no-substitutes} is
-passed, the command looks for a corresponding log on one of the
-substitute servers (as specified with @code{--substitute-urls}.)
+@noindent
+In the example above, the first two modules are taken from the search
+path, and the last one is created from the given file-like object.
-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:
+This form has @emph{lexical} scope: it has an effect on the gexps
+directly defined in @var{body}@dots{}, but not on those defined, say, in
+procedures called from @var{body}@dots{}.
+@end deffn
-@example
-$ guix build --log-file gdb -s mips64el-linux
-https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10
-@end example
+@deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{}
+Mark the gexps defined in @var{body}@dots{} as requiring
+@var{extensions} in their build and execution environment.
+@var{extensions} is typically a list of package objects such as those
+defined in the @code{(gnu packages guile)} module.
-You can freely access a huge library of build logs!
-@end table
+Concretely, the packages listed in @var{extensions} are added to the
+load path while compiling imported modules in @var{body}@dots{}; they
+are also added to the load path of the gexp returned by
+@var{body}@dots{}.
+@end deffn
-@node Debugging Build Failures
-@subsection Debugging Build Failures
+@deffn {Scheme Procedure} gexp? @var{obj}
+Return @code{#t} if @var{obj} is a G-expression.
+@end deffn
-@cindex build failures, debugging
-When defining a new package (@pxref{Defining Packages}), you will
-probably find yourself spending some time debugging and tweaking the
-build until it succeeds. To do that, you need to operate the build
-commands yourself in an environment as close as possible to the one the
-build daemon uses.
+G-expressions are meant to be written to disk, either as code building
+some derivation, or as plain files in the store. The monadic procedures
+below allow you to do that (@pxref{The Store Monad}, for more
+information about monads.)
-To that end, the first thing to do is to use the @option{--keep-failed}
-or @option{-K} option of @command{guix build}, which will keep the
-failed build tree in @file{/tmp} or whatever directory you specified as
-@code{TMPDIR} (@pxref{Invoking guix build, @code{--keep-failed}}).
+@deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
+ [#:system (%current-system)] [#:target #f] [#:graft? #t] @
+ [#:hash #f] [#:hash-algo #f] @
+ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
+ [#:module-path @var{%load-path}] @
+ [#:effective-version "2.2"] @
+ [#:references-graphs #f] [#:allowed-references #f] @
+ [#:disallowed-references #f] @
+ [#:leaked-env-vars #f] @
+ [#:script-name (string-append @var{name} "-builder")] @
+ [#:deprecation-warnings #f] @
+ [#:local-build? #f] [#:substitutable? #t] @
+ [#:properties '()] [#:guile-for-build #f]
+Return a derivation @var{name} that runs @var{exp} (a gexp) with
+@var{guile-for-build} (a derivation) on @var{system}; @var{exp} is
+stored in a file called @var{script-name}. When @var{target} is true,
+it is used as the cross-compilation target triplet for packages referred
+to by @var{exp}.
+
+@var{modules} is deprecated in favor of @code{with-imported-modules}.
+Its meaning is to
+make @var{modules} available in the evaluation context of @var{exp};
+@var{modules} is a list of names of Guile modules searched in
+@var{module-path} to be copied in the store, compiled, and made available in
+the load path during the execution of @var{exp}---e.g., @code{((guix
+build utils) (guix build gnu-build-system))}.
+
+@var{effective-version} determines the string to use when adding extensions of
+@var{exp} (see @code{with-extensions}) to the search path---e.g., @code{"2.2"}.
+
+@var{graft?} determines whether packages referred to by @var{exp} should be grafted when
+applicable.
-From there on, you can @command{cd} to the failed build tree and source
-the @file{environment-variables} file, which contains all the
-environment variable definitions that were in place when the build
-failed. So let's say you're debugging a build failure in package
-@code{foo}; a typical session would look like this:
+When @var{references-graphs} is true, it must be a list of tuples of one of the
+following forms:
@example
-$ guix build foo -K
-@dots{} @i{build fails}
-$ cd /tmp/guix-build-foo.drv-0
-$ source ./environment-variables
-$ cd foo-1.2
+(@var{file-name} @var{package})
+(@var{file-name} @var{package} @var{output})
+(@var{file-name} @var{derivation})
+(@var{file-name} @var{derivation} @var{output})
+(@var{file-name} @var{store-item})
@end example
-Now, you can invoke commands as if you were the daemon (almost) and
-troubleshoot your build process.
+The right-hand-side of each element of @var{references-graphs} is automatically made
+an input of the build process of @var{exp}. In the build environment, each
+@var{file-name} contains the reference graph of the corresponding item, in a simple
+text format.
-Sometimes it happens that, for example, a package's tests pass when you
-run them manually but they fail when the daemon runs them. This can
-happen because the daemon runs builds in containers where, unlike in our
-environment above, network access is missing, @file{/bin/sh} does not
-exist, etc. (@pxref{Build Environment Setup}).
+@var{allowed-references} must be either @code{#f} or a list of output names and packages.
+In the latter case, the list denotes store items that the result is allowed to
+refer to. Any reference to another store item will lead to a build error.
+Similarly for @var{disallowed-references}, which can list items that must not be
+referenced by the outputs.
-In such cases, you may need to run inspect the build process from within
-a container similar to the one the build daemon creates:
+@var{deprecation-warnings} determines whether to show deprecation warnings while
+compiling modules. It can be @code{#f}, @code{#t}, or @code{'detailed}.
+
+The other arguments are as for @code{derivation} (@pxref{Derivations}).
+@end deffn
+
+@cindex file-like objects
+The @code{local-file}, @code{plain-file}, @code{computed-file},
+@code{program-file}, and @code{scheme-file} procedures below return
+@dfn{file-like objects}. That is, when unquoted in a G-expression,
+these objects lead to a file in the store. Consider this G-expression:
@example
-$ guix build -K foo
-@dots{}
-$ cd /tmp/guix-build-foo.drv-0
-$ guix environment --no-grafts -C foo --ad-hoc strace gdb
-[env]# source ./environment-variables
-[env]# cd foo-1.2
+#~(system* #$(file-append glibc "/sbin/nscd") "-f"
+ #$(local-file "/tmp/my-nscd.conf"))
@end example
-Here, @command{guix environment -C} creates a container and spawns a new
-shell in it (@pxref{Invoking guix environment}). The @command{--ad-hoc
-strace gdb} part adds the @command{strace} and @command{gdb} commands to
-the container, which would may find handy while debugging. The
-@option{--no-grafts} option makes sure we get the exact same
-environment, with ungrafted packages (@pxref{Security Updates}, for more
-info on grafts).
+The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
+to the store. Once expanded, for instance @i{via}
+@code{gexp->derivation}, the G-expression refers to that copy under
+@file{/gnu/store}; thus, modifying or removing the file in @file{/tmp}
+does not have any effect on what the G-expression does.
+@code{plain-file} can be used similarly; it differs in that the file
+content is directly passed as a string.
-To get closer to a container like that used by the build daemon, we can
-remove @file{/bin/sh}:
+@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
+ [#:recursive? #f] [#:select? (const #t)]
+Return an object representing local file @var{file} to add to the store; this
+object can be used in a gexp. If @var{file} is a relative file name, it is looked
+up relative to the source file where this form appears. @var{file} will be added to
+the store under @var{name}--by default the base name of @var{file}.
-@example
-[env]# rm /bin/sh
-@end example
+When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
+designates a flat file and @var{recursive?} is true, its contents are added, and its
+permission bits are kept.
-(Don't worry, this is harmless: this is all happening in the throw-away
-container created by @command{guix environment}.)
+When @var{recursive?} is true, call @code{(@var{select?} @var{file}
+@var{stat})} for each directory entry, where @var{file} is the entry's
+absolute file name and @var{stat} is the result of @code{lstat}; exclude
+entries for which @var{select?} does not return true.
-The @command{strace} command is probably not in the search path, but we
-can run:
+This is the declarative counterpart of the @code{interned-file} monadic
+procedure (@pxref{The Store Monad, @code{interned-file}}).
+@end deffn
-@example
-[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
-@end example
+@deffn {Scheme Procedure} plain-file @var{name} @var{content}
+Return an object representing a text file called @var{name} with the given
+@var{content} (a string or a bytevector) to be added to the store.
-In this way, not only you will have reproduced the environment variables
-the daemon uses, you will also be running the build process in a container
-similar to the one the daemon uses.
+This is the declarative counterpart of @code{text-file}.
+@end deffn
+@deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
+ [#:options '(#:local-build? #t)]
+Return an object representing the store item @var{name}, a file or
+directory computed by @var{gexp}. @var{options}
+is a list of additional arguments to pass to @code{gexp->derivation}.
-@node Invoking guix edit
-@section Invoking @command{guix edit}
+This is the declarative counterpart of @code{gexp->derivation}.
+@end deffn
-@cindex @command{guix edit}
-@cindex package definition, editing
-So many packages, so many source files! The @command{guix edit} command
-facilitates the life of users and packagers by pointing their editor at
-the source file containing the definition of the specified packages.
-For instance:
+@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
+ [#:guile (default-guile)] [#:module-path %load-path]
+Return an executable script @var{name} that runs @var{exp} using
+@var{guile}, with @var{exp}'s imported modules in its search path.
+Look up @var{exp}'s modules in @var{module-path}.
-@example
-guix edit gcc@@4.9 vim
-@end example
+The example below builds a script that simply invokes the @command{ls}
+command:
-@noindent
-launches the program specified in the @code{VISUAL} or in the
-@code{EDITOR} environment variable to view the recipe of GCC@tie{}4.9.3
-and that of Vim.
+@example
+(use-modules (guix gexp) (gnu packages base))
-If you are using a Guix Git checkout (@pxref{Building from Git}), or
-have created your own packages on @code{GUIX_PACKAGE_PATH}
-(@pxref{Package Modules}), you will be able to edit the package
-recipes. In other cases, you will be able to examine the read-only recipes
-for packages currently in the store.
+(gexp->script "list-files"
+ #~(execl #$(file-append coreutils "/bin/ls")
+ "ls"))
+@end example
+When ``running'' it through the store (@pxref{The Store Monad,
+@code{run-with-store}}), we obtain a derivation that produces an
+executable file @file{/gnu/store/@dots{}-list-files} along these lines:
-@node Invoking guix download
-@section Invoking @command{guix download}
+@example
+#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
+!#
+(execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
+@end example
+@end deffn
-@cindex @command{guix download}
-@cindex downloading package sources
-When writing a package definition, developers typically need to download
-a source tarball, compute its SHA256 hash, and write that
-hash in the package definition (@pxref{Defining Packages}). The
-@command{guix download} tool helps with this task: it downloads a file
-from the given URI, adds it to the store, and prints both its file name
-in the store and its SHA256 hash.
+@deffn {Scheme Procedure} program-file @var{name} @var{exp} @
+ [#:guile #f] [#:module-path %load-path]
+Return an object representing the executable store item @var{name} that
+runs @var{gexp}. @var{guile} is the Guile package used to execute that
+script. Imported modules of @var{gexp} are looked up in @var{module-path}.
-The fact that the downloaded file is added to the store saves bandwidth:
-when the developer eventually tries to build the newly defined package
-with @command{guix build}, the source tarball will not have to be
-downloaded again because it is already in the store. It is also a
-convenient way to temporarily stash files, which may be deleted
-eventually (@pxref{Invoking guix gc}).
+This is the declarative counterpart of @code{gexp->script}.
+@end deffn
-The @command{guix download} command supports the same URIs as used in
-package definitions. In particular, it supports @code{mirror://} URIs.
-@code{https} URIs (HTTP over TLS) are supported @emph{provided} the
-Guile bindings for GnuTLS are available in the user's environment; when
-they are not available, an error is raised. @xref{Guile Preparations,
-how to install the GnuTLS bindings for Guile,, gnutls-guile,
-GnuTLS-Guile}, for more information.
+@deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @
+ [#:set-load-path? #t] [#:module-path %load-path] @
+ [#:splice? #f] @
+ [#:guile (default-guile)]
+Return a derivation that builds a file @var{name} containing @var{exp}.
+When @var{splice?} is true, @var{exp} is considered to be a list of
+expressions that will be spliced in the resulting file.
-@command{guix download} verifies HTTPS server certificates by loading
-the certificates of X.509 authorities from the directory pointed to by
-the @code{SSL_CERT_DIR} environment variable (@pxref{X.509
-Certificates}), unless @option{--no-check-certificate} is used.
+When @var{set-load-path?} is true, emit code in the resulting file to
+set @code{%load-path} and @code{%load-compiled-path} to honor
+@var{exp}'s imported modules. Look up @var{exp}'s modules in
+@var{module-path}.
-The following options are available:
+The resulting file holds references to all the dependencies of @var{exp}
+or a subset thereof.
+@end deffn
-@table @code
-@item --format=@var{fmt}
-@itemx -f @var{fmt}
-Write the hash in the format specified by @var{fmt}. For more
-information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
+@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} [#:splice? #f]
+Return an object representing the Scheme file @var{name} that contains
+@var{exp}.
-@item --no-check-certificate
-Do not validate the X.509 certificates of HTTPS servers.
+This is the declarative counterpart of @code{gexp->file}.
+@end deffn
-When using this option, you have @emph{absolutely no guarantee} that you
-are communicating with the authentic server responsible for the given
-URL, which makes you vulnerable to ``man-in-the-middle'' attacks.
+@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
+Return as a monadic value a derivation that builds a text file
+containing all of @var{text}. @var{text} may list, in addition to
+strings, objects of any type that can be used in a gexp: packages,
+derivations, local file objects, etc. The resulting store file holds
+references to all these.
-@item --output=@var{file}
-@itemx -o @var{file}
-Save the downloaded file to @var{file} instead of adding it to the
-store.
-@end table
+This variant should be preferred over @code{text-file} anytime the file
+to create will reference items from the store. This is typically the
+case when building a configuration file that embeds store file names,
+like this:
-@node Invoking guix hash
-@section Invoking @command{guix hash}
+@example
+(define (profile.sh)
+ ;; Return the name of a shell script in the store that
+ ;; initializes the 'PATH' environment variable.
+ (text-file* "profile.sh"
+ "export PATH=" coreutils "/bin:"
+ grep "/bin:" sed "/bin\n"))
+@end example
-@cindex @command{guix hash}
-The @command{guix hash} command computes the SHA256 hash of a file.
-It is primarily a convenience tool for anyone contributing to the
-distribution: it computes the cryptographic hash of a file, which can be
-used in the definition of a package (@pxref{Defining Packages}).
+In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
+will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby
+preventing them from being garbage-collected during its lifetime.
+@end deffn
-The general syntax is:
+@deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
+Return an object representing store file @var{name} containing
+@var{text}. @var{text} is a sequence of strings and file-like objects,
+as in:
@example
-guix hash @var{option} @var{file}
+(mixed-text-file "profile"
+ "export PATH=" coreutils "/bin:" grep "/bin")
@end example
-When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the
-hash of data read from standard input. @command{guix hash} has the
-following options:
+This is the declarative counterpart of @code{text-file*}.
+@end deffn
-@table @code
+@deffn {Scheme Procedure} file-union @var{name} @var{files}
+Return a @code{<computed-file>} that builds a directory containing all of @var{files}.
+Each item in @var{files} must be a two-element list where the first element is the
+file name to use in the new directory, and the second element is a gexp
+denoting the target file. Here's an example:
-@item --format=@var{fmt}
-@itemx -f @var{fmt}
-Write the hash in the format specified by @var{fmt}.
+@example
+(file-union "etc"
+ `(("hosts" ,(plain-file "hosts"
+ "127.0.0.1 localhost"))
+ ("bashrc" ,(plain-file "bashrc"
+ "alias ls='ls --color=auto'"))))
+@end example
-Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
-(@code{hex} and @code{hexadecimal} can be used as well).
+This yields an @code{etc} directory containing these two files.
+@end deffn
-If the @option{--format} option is not specified, @command{guix hash}
-will output the hash in @code{nix-base32}. This representation is used
-in the definitions of packages.
+@deffn {Scheme Procedure} directory-union @var{name} @var{things}
+Return a directory that is the union of @var{things}, where @var{things} is a list of
+file-like objects denoting directories. For example:
-@item --recursive
-@itemx -r
-Compute the hash on @var{file} recursively.
+@example
+(directory-union "guile+emacs" (list guile emacs))
+@end example
-In this case, the hash is computed on an archive containing @var{file},
-including its children if it is a directory. Some of the metadata of
-@var{file} is part of the archive; for instance, when @var{file} is a
-regular file, the hash is different depending on whether @var{file} is
-executable or not. Metadata such as time stamps has no impact on the
-hash (@pxref{Invoking guix archive}).
-@c FIXME: Replace xref above with xref to an ``Archive'' section when
-@c it exists.
+yields a directory that is the union of the @code{guile} and @code{emacs} packages.
+@end deffn
-@item --exclude-vcs
-@itemx -x
-When combined with @option{--recursive}, exclude version control system
-directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.)
+@deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
+Return a file-like object that expands to the concatenation of @var{obj}
+and @var{suffix}, where @var{obj} is a lowerable object and each
+@var{suffix} is a string.
-@vindex git-fetch
-As an example, here is how you would compute the hash of a Git checkout,
-which is useful when using the @code{git-fetch} method (@pxref{origin
-Reference}):
+As an example, consider this gexp:
@example
-$ git clone http://example.org/foo.git
-$ cd foo
-$ guix hash -rx .
+(gexp->script "run-uname"
+ #~(system* #$(file-append coreutils
+ "/bin/uname")))
@end example
-@end table
-
-@node Invoking guix import
-@section Invoking @command{guix import}
-
-@cindex importing packages
-@cindex package import
-@cindex package conversion
-@cindex Invoking @command{guix import}
-The @command{guix import} command is useful for people who would like to
-add a package to the distribution with as little work as
-possible---a legitimate demand. The command knows of a few
-repositories from which it can ``import'' package metadata. The result
-is a package definition, or a template thereof, in the format we know
-(@pxref{Defining Packages}).
-The general syntax is:
+The same effect could be achieved with:
@example
-guix import @var{importer} @var{options}@dots{}
+(gexp->script "run-uname"
+ #~(system* (string-append #$coreutils
+ "/bin/uname")))
@end example
-@var{importer} specifies the source from which to import package
-metadata, and @var{options} specifies a package identifier and other
-options specific to @var{importer}. Currently, the available
-``importers'' are:
+There is one difference though: in the @code{file-append} case, the
+resulting script contains the absolute file name as a string, whereas in
+the second case, the resulting script contains a @code{(string-append
+@dots{})} expression to construct the file name @emph{at run time}.
+@end deffn
-@table @code
-@item gnu
-Import metadata for the given GNU package. This provides a template
-for the latest version of that GNU package, including the hash of its
-source tarball, and its canonical synopsis and description.
-Additional information such as the package dependencies and its
-license needs to be figured out manually.
+Of course, in addition to gexps embedded in ``host'' code, there are
+also modules containing build tools. To make it clear that they are
+meant to be used in the build stratum, these modules are kept in the
+@code{(guix build @dots{})} name space.
-For example, the following command returns a package definition for
-GNU@tie{}Hello:
+@cindex lowering, of high-level objects in gexps
+Internally, high-level objects are @dfn{lowered}, using their compiler,
+to either derivations or store items. For instance, lowering a package
+yields a derivation, and lowering a @code{plain-file} yields a store
+item. This is achieved using the @code{lower-object} monadic procedure.
+
+@deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
+ [#:target #f]
+Return as a value in @var{%store-monad} the derivation or store item
+corresponding to @var{obj} for @var{system}, cross-compiling for
+@var{target} if @var{target} is true. @var{obj} must be an object that
+has an associated gexp compiler, such as a @code{<package>}.
+@end deffn
+
+@node Invoking guix repl
+@section Invoking @command{guix repl}
+
+@cindex REPL, read-eval-print loop
+The @command{guix repl} command spawns a Guile @dfn{read-eval-print loop}
+(REPL) for interactive programming (@pxref{Using Guile Interactively,,, guile,
+GNU Guile Reference Manual}). Compared to just launching the @command{guile}
+command, @command{guix repl} guarantees that all the Guix modules and all its
+dependencies are available in the search path. You can use it this way:
@example
-guix import gnu hello
+$ guix repl
+scheme@@(guile-user)> ,use (gnu packages base)
+scheme@@(guile-user)> coreutils
+$1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300>
@end example
-Specific command-line options are:
+@cindex inferiors
+In addition, @command{guix repl} implements a simple machine-readable REPL
+protocol for use by @code{(guix inferior)}, a facility to interact with
+@dfn{inferiors}, separate processes running a potentially different revision
+of Guix.
-@table @code
-@item --key-download=@var{policy}
-As for @code{guix refresh}, specify the policy to handle missing OpenPGP
-keys when verifying the package signature. @xref{Invoking guix
-refresh, @code{--key-download}}.
-@end table
+The available options are as follows:
-@item pypi
-@cindex pypi
-Import metadata from the @uref{https://pypi.python.org/, Python Package
-Index}. Information is taken from the JSON-formatted description
-available at @code{pypi.python.org} and usually includes all the relevant
-information, including package dependencies. For maximum efficiency, it
-is recommended to install the @command{unzip} utility, so that the
-importer can unzip Python wheels and gather data from them.
+@table @code
+@item --type=@var{type}
+@itemx -t @var{type}
+Start a REPL of the given @var{TYPE}, which can be one of the following:
-The command below imports metadata for the @code{itsdangerous} Python
-package:
+@table @code
+@item guile
+This is default, and it spawns a standard full-featured Guile REPL.
+@item machine
+Spawn a REPL that uses the machine-readable protocol. This is the protocol
+that the @code{(guix inferior)} module speaks.
+@end table
-@example
-guix import pypi itsdangerous
-@end example
+@item --listen=@var{endpoint}
+By default, @command{guix repl} reads from standard input and writes to
+standard output. When this option is passed, it will instead listen for
+connections on @var{endpoint}. Here are examples of valid options:
@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.
+@item --listen=tcp:37146
+Accept connections on localhost on port 37146.
+
+@item --listen=unix:/tmp/socket
+Accept connections on the Unix-domain socket @file{/tmp/socket}.
+@end table
@end table
-@item gem
-@cindex gem
-Import metadata from @uref{https://rubygems.org/, RubyGems}. Information
-is taken from the JSON-formatted description available at
-@code{rubygems.org} and includes most relevant information, including
-runtime dependencies. There are some caveats, however. The metadata
-doesn't distinguish between synopses and descriptions, so the same string
-is used for both fields. Additionally, the details of non-Ruby
-dependencies required to build native extensions is unavailable and left
-as an exercise to the packager.
+@c *********************************************************************
+@node Utilities
+@chapter Utilities
-The command below imports metadata for the @code{rails} Ruby package:
+This section describes Guix command-line utilities. Some of them are
+primarily targeted at developers and users who write new package
+definitions, while others are more generally useful. They complement
+the Scheme programming interface of Guix in a convenient way.
-@example
-guix import gem rails
-@end example
+@menu
+* Invoking guix build:: Building packages from the command line.
+* Invoking guix edit:: Editing package definitions.
+* Invoking guix download:: Downloading a file and printing its hash.
+* Invoking guix hash:: Computing the cryptographic hash of a file.
+* Invoking guix import:: Importing package definitions.
+* Invoking guix refresh:: Updating package definitions.
+* Invoking guix lint:: Finding errors in package definitions.
+* Invoking guix size:: Profiling disk usage.
+* Invoking guix graph:: Visualizing the graph of packages.
+* Invoking guix publish:: Sharing substitutes.
+* Invoking guix challenge:: Challenging substitute servers.
+* Invoking guix copy:: Copying to and from a remote store.
+* Invoking guix container:: Process isolation.
+* Invoking guix weather:: Assessing substitute availability.
+* Invoking guix processes:: Listing client processes.
+@end menu
-@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
+@node Invoking guix build
+@section Invoking @command{guix build}
-@item cpan
-@cindex CPAN
-Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
-Information is taken from the JSON-formatted metadata provided through
-@uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most
-relevant information, such as module dependencies. License information
-should be checked closely. If Perl is available in the store, then the
-@code{corelist} utility will be used to filter core modules out of the
-list of dependencies.
+@cindex package building
+@cindex @command{guix build}
+The @command{guix build} command builds packages or derivations and
+their dependencies, and prints the resulting store paths. Note that it
+does not modify the user's profile---this is the job of the
+@command{guix package} command (@pxref{Invoking guix package}). Thus,
+it is mainly useful for distribution developers.
-The command command below imports metadata for the @code{Acme::Boolean}
-Perl module:
+The general syntax is:
@example
-guix import cpan Acme::Boolean
+guix build @var{options} @var{package-or-derivation}@dots{}
@end example
-@item cran
-@cindex CRAN
-@cindex Bioconductor
-Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
-central repository for the @uref{http://r-project.org, GNU@tie{}R
-statistical and graphical environment}.
-
-Information is extracted from the @code{DESCRIPTION} file of the package.
-
-The command command below imports metadata for the @code{Cairo}
-R package:
+As an example, the following command builds the latest versions of Emacs
+and of Guile, displays their build logs, and finally displays the
+resulting directories:
@example
-guix import cran Cairo
+guix build emacs guile
@end example
-When @code{--recursive} is added, the importer will traverse the
-dependency graph of the given upstream package recursively and generate
-package expressions for all those packages that are not yet in Guix.
-
-When @code{--archive=bioconductor} is added, metadata is imported from
-@uref{https://www.bioconductor.org/, Bioconductor}, a repository of R
-packages for for the analysis and comprehension of high-throughput
-genomic data in bioinformatics.
-
-Information is extracted from the @code{DESCRIPTION} file of a package
-published on the web interface of the Bioconductor SVN repository.
-
-The command below imports metadata for the @code{GenomicRanges}
-R package:
+Similarly, the following command builds all the available packages:
@example
-guix import cran --archive=bioconductor GenomicRanges
+guix build --quiet --keep-going \
+ `guix package -A | cut -f1,2 --output-delimiter=@@`
@end example
-@item texlive
-@cindex TeX Live
-@cindex CTAN
-Import metadata from @uref{http://www.ctan.org/, CTAN}, the
-comprehensive TeX archive network for TeX packages that are part of the
-@uref{https://www.tug.org/texlive/, TeX Live distribution}.
+@var{package-or-derivation} may be either the name of a package found in
+the software distribution such as @code{coreutils} or
+@code{coreutils@@8.20}, or a derivation such as
+@file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
+package with the corresponding name (and optionally version) is searched
+for among the GNU distribution modules (@pxref{Package Modules}).
-Information about the package is obtained through the XML API provided
-by CTAN, while the source code is downloaded from the SVN repository of
-the Tex Live project. This is done because the CTAN does not keep
-versioned archives.
+Alternatively, the @code{--expression} option may be used to specify a
+Scheme expression that evaluates to a package; this is useful when
+disambiguating among several same-named packages or package variants is
+needed.
-The command command below imports metadata for the @code{fontspec}
-TeX package:
+There may be zero or more @var{options}. The available options are
+described in the subsections below.
-@example
-guix import texlive fontspec
-@end example
+@menu
+* Common Build Options:: Build options for most commands.
+* Package Transformation Options:: Creating variants of packages.
+* Additional Build Options:: Options specific to 'guix build'.
+* Debugging Build Failures:: Real life packaging experience.
+@end menu
-When @code{--archive=DIRECTORY} is added, the source code is downloaded
-not from the @file{latex} sub-directory of the @file{texmf-dist/source}
-tree in the TeX Live SVN repository, but from the specified sibling
-directory under the same root.
+@node Common Build Options
+@subsection Common Build Options
-The command below imports metadata for the @code{ifxetex} package from
-CTAN while fetching the sources from the directory
-@file{texmf/source/generic}:
+A number of options that control the build process are common to
+@command{guix build} and other commands that can spawn builds, such as
+@command{guix package} or @command{guix archive}. These are the
+following:
-@example
-guix import texlive --archive=generic ifxetex
-@end example
+@table @code
-@item json
-@cindex JSON, import
-Import package metadata from a local JSON file. Consider the following
-example package definition in JSON format:
+@item --load-path=@var{directory}
+@itemx -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
-@example
-@{
- "name": "hello",
- "version": "2.10",
- "source": "mirror://gnu/hello/hello-2.10.tar.gz",
- "build-system": "gnu",
- "home-page": "https://www.gnu.org/software/hello/",
- "synopsis": "Hello, GNU world: An example GNU package",
- "description": "GNU Hello prints a greeting.",
- "license": "GPL-3.0+",
- "native-inputs": ["gcc@@6"]
-@}
-@end example
+This allows users to define their own packages and make them visible to
+the command-line tools.
-The field names are the same as for the @code{<package>} record
-(@xref{Defining Packages}). References to other packages are provided
-as JSON lists of quoted package specification strings such as
-@code{guile} or @code{guile@@2.0}.
+@item --keep-failed
+@itemx -K
+Keep the build tree of failed builds. Thus, if a build fails, its build
+tree is kept under @file{/tmp}, in a directory whose name is shown at
+the end of the build log. This is useful when debugging build issues.
+@xref{Debugging Build Failures}, for tips and tricks on how to debug
+build issues.
-The importer also supports a more explicit source definition using the
-common fields for @code{<origin>} records:
+This option has no effect when connecting to a remote daemon with a
+@code{guix://} URI (@pxref{The Store, the @code{GUIX_DAEMON_SOCKET}
+variable}).
-@example
-@{
- @dots{}
- "source": @{
- "method": "url-fetch",
- "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
- "sha256": @{
- "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
- @}
- @}
- @dots{}
-@}
-@end example
+@item --keep-going
+@itemx -k
+Keep going when some of the derivations fail to build; return only once
+all the builds have either completed or failed.
-The command below reads metadata from the JSON file @code{hello.json}
-and outputs a package expression:
+The default behavior is to stop as soon as one of the specified
+derivations has failed.
-@example
-guix import json hello.json
-@end example
+@item --dry-run
+@itemx -n
+Do not build the derivations.
-@item nix
-Import metadata from a local copy of the source of the
-@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
-relies on the @command{nix-instantiate} command of
-@uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
-typically written in a mixture of Nix-language and Bash code. This
-command only imports the high-level package structure that is written in
-the Nix language. It normally includes all the basic fields of a
-package definition.
+@anchor{fallback-option}
+@item --fallback
+When substituting a pre-built binary fails, fall back to building
+packages locally (@pxref{Substitution Failure}).
-When importing a GNU package, the synopsis and descriptions are replaced
-by their canonical upstream variant.
+@item --substitute-urls=@var{urls}
+@anchor{client-substitute-urls}
+Consider @var{urls} the whitespace-separated list of substitute source
+URLs, overriding the default list of URLs of @command{guix-daemon}
+(@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).
-Usually, you will first need to do:
+This means that substitutes may be downloaded from @var{urls}, provided
+they are signed by a key authorized by the system administrator
+(@pxref{Substitutes}).
-@example
-export NIX_REMOTE=daemon
-@end example
+When @var{urls} is the empty string, substitutes are effectively
+disabled.
-@noindent
-so that @command{nix-instantiate} does not try to open the Nix database.
+@item --no-substitutes
+Do not use substitutes for build products. That is, always build things
+locally instead of allowing downloads of pre-built binaries
+(@pxref{Substitutes}).
-As an example, the command below imports the package definition of
-LibreOffice (more precisely, it imports the definition of the package
-bound to the @code{libreoffice} top-level attribute):
+@item --no-grafts
+Do not ``graft'' packages. In practice, this means that package updates
+available as grafts are not applied. @xref{Security Updates}, for more
+information on grafts.
-@example
-guix import nix ~/path/to/nixpkgs libreoffice
-@end example
+@item --rounds=@var{n}
+Build each derivation @var{n} times in a row, and raise an error if
+consecutive build results are not bit-for-bit identical.
-@item hackage
-@cindex hackage
-Import metadata from the Haskell community's central package archive
-@uref{https://hackage.haskell.org/, Hackage}. Information is taken from
-Cabal files and includes all the relevant information, including package
-dependencies.
+This is a useful way to detect non-deterministic builds processes.
+Non-deterministic build processes are a problem because they make it
+practically impossible for users to @emph{verify} whether third-party
+binaries are genuine. @xref{Invoking guix challenge}, for more.
-Specific command-line options are:
+Note that, currently, the differing build results are not kept around,
+so you will have to manually investigate in case of an error---e.g., by
+stashing one of the build results with @code{guix archive --export}
+(@pxref{Invoking guix archive}), then rebuilding, and finally comparing
+the two results.
-@table @code
-@item --stdin
-@itemx -s
-Read a Cabal file from standard input.
-@item --no-test-dependencies
-@itemx -t
-Do not include dependencies required only by the test suites.
-@item --cabal-environment=@var{alist}
-@itemx -e @var{alist}
-@var{alist} is a Scheme alist defining the environment in which the
-Cabal conditionals are evaluated. The accepted keys are: @code{os},
-@code{arch}, @code{impl} and a string representing the name of a flag.
-The value associated with a flag has to be either the symbol
-@code{true} or @code{false}. The value associated with other keys
-has to conform to the Cabal file format definition. The default value
-associated with the keys @code{os}, @code{arch} and @code{impl} is
-@samp{linux}, @samp{x86_64} and @samp{ghc}, respectively.
-@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 --no-build-hook
+Do not attempt to offload builds @i{via} the ``build hook'' of the daemon
+(@pxref{Daemon Offload Setup}). That is, always build things locally
+instead of offloading builds to remote machines.
-The command below imports metadata for the latest version of the
-@code{HTTP} Haskell package without including test dependencies and
-specifying the value of the flag @samp{network-uri} as @code{false}:
+@item --max-silent-time=@var{seconds}
+When the build or substitution process remains silent for more than
+@var{seconds}, terminate it and report a build failure.
+
+By default, the daemon's setting is honored (@pxref{Invoking
+guix-daemon, @code{--max-silent-time}}).
+
+@item --timeout=@var{seconds}
+Likewise, when the build or substitution process lasts for more than
+@var{seconds}, terminate it and report a build failure.
-@example
-guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
-@end example
+By default, the daemon's setting is honored (@pxref{Invoking
+guix-daemon, @code{--timeout}}).
-A specific package version may optionally be specified by following the
-package name by an at-sign and a version number as in the following example:
+@c Note: This option is actually not part of %standard-build-options but
+@c most programs honor it.
+@cindex verbosity, of the command-line tools
+@cindex build logs, verbosity
+@item -v @var{level}
+@itemx --verbosity=@var{level}
+Use the given verbosity @var{level}, an integer. Choosing 0 means that no
+output is produced, 1 is for quiet output, and 2 shows all the build log
+output on standard error.
-@example
-guix import hackage mtl@@2.1.3.1
-@end example
+@item --cores=@var{n}
+@itemx -c @var{n}
+Allow the use of up to @var{n} CPU cores for the build. The special
+value @code{0} means to use as many CPU cores as available.
-@item stackage
-@cindex stackage
-The @code{stackage} importer is a wrapper around the @code{hackage} one.
-It takes a package name, looks up the package version included in a
-long-term support (LTS) @uref{https://www.stackage.org, Stackage}
-release and uses the @code{hackage} importer to retrieve its metadata.
-Note that it is up to you to select an LTS release compatible with the
-GHC compiler used by Guix.
+@item --max-jobs=@var{n}
+@itemx -M @var{n}
+Allow at most @var{n} build jobs in parallel. @xref{Invoking
+guix-daemon, @code{--max-jobs}}, for details about this option and the
+equivalent @command{guix-daemon} option.
-Specific command-line options are:
+@item --debug=@var{level}
+Produce debugging output coming from the build daemon. @var{level} must be an
+integer between 0 and 5; higher means more verbose output. Setting a level of
+4 or more may be helpful when debugging setup issues with the build daemon.
-@table @code
-@item --no-test-dependencies
-@itemx -t
-Do not include dependencies required only by the test suites.
-@item --lts-version=@var{version}
-@itemx -l @var{version}
-@var{version} is the desired LTS release version. If omitted the latest
-release is used.
-@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
-The command below imports metadata for the @code{HTTP} Haskell package
-included in the LTS Stackage release version 7.18:
+Behind the scenes, @command{guix build} is essentially an interface to
+the @code{package-derivation} procedure of the @code{(guix packages)}
+module, and to the @code{build-derivations} procedure of the @code{(guix
+derivations)} module.
+
+In addition to options explicitly passed on the command line,
+@command{guix build} and other @command{guix} commands that support
+building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
+
+@defvr {Environment Variable} GUIX_BUILD_OPTIONS
+Users can define this variable to a list of command line options that
+will automatically be used by @command{guix build} and other
+@command{guix} commands that can perform builds, as in the example
+below:
@example
-guix import stackage --lts-version=7.18 HTTP
+$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
@end example
-@item elpa
-@cindex elpa
-Import metadata from an Emacs Lisp Package Archive (ELPA) package
-repository (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
+These options are parsed independently, and the result is appended to
+the parsed command-line options.
+@end defvr
-Specific command-line options are:
+
+@node Package Transformation Options
+@subsection Package Transformation Options
+
+@cindex package variants
+Another set of command-line options supported by @command{guix build}
+and also @command{guix package} are @dfn{package transformation
+options}. These are options that make it possible to define @dfn{package
+variants}---for instance, packages built from different source code.
+This is a convenient way to create customized packages on the fly
+without having to type in the definitions of package variants
+(@pxref{Defining Packages}).
@table @code
-@item --archive=@var{repo}
-@itemx -a @var{repo}
-@var{repo} identifies the archive repository from which to retrieve the
-information. Currently the supported repositories and their identifiers
-are:
-@itemize -
-@item
-@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
-identifier. This is the default.
-Packages from @code{elpa.gnu.org} are signed with one of the keys
-contained in the GnuPG keyring at
-@file{share/emacs/25.1/etc/package-keyring.gpg} (or similar) in the
-@code{emacs} package (@pxref{Package Installation, ELPA package
-signatures,, emacs, The GNU Emacs Manual}).
+@item --with-source=@var{source}
+@itemx --with-source=@var{package}=@var{source}
+@itemx --with-source=@var{package}@@@var{version}=@var{source}
+Use @var{source} as the source of @var{package}, and @var{version} as
+its version number.
+@var{source} must be a file name or a URL, as for @command{guix
+download} (@pxref{Invoking guix download}).
-@item
-@uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the
-@code{melpa-stable} identifier.
+When @var{package} is omitted,
+it is taken to be the package name specified on the
+command line that matches the base of @var{source}---e.g.,
+if @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
+package is @code{guile}.
-@item
-@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa}
-identifier.
-@end itemize
+Likewise, when @var{version} is omitted, the version string is inferred from
+@var{source}; in the previous example, it is @code{2.0.10}.
-@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
+This option allows users to try out versions of packages other than the
+one provided by the distribution. The example below downloads
+@file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
+the @code{ed} package:
-@item crate
-@cindex crate
-Import metadata from the crates.io Rust package repository
-@uref{https://crates.io, crates.io}.
+@example
+guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
+@end example
-@item opam
-@cindex OPAM
-@cindex OCaml
-Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package
-repository used by the OCaml community.
-@end table
+As a developer, @code{--with-source} makes it easy to test release
+candidates:
-The structure of the @command{guix import} code is modular. It would be
-useful to have more importers for other package formats, and your help
-is welcome here (@pxref{Contributing}).
+@example
+guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
+@end example
-@node Invoking guix refresh
-@section Invoking @command{guix refresh}
+@dots{} or to build from a checkout in a pristine environment:
-@cindex @command {guix refresh}
-The primary audience of the @command{guix refresh} command is developers
-of the GNU software distribution. By default, it reports any packages
-provided by the distribution that are outdated compared to the latest
-upstream version, like this:
+@example
+$ git clone git://git.sv.gnu.org/guix.git
+$ guix build guix --with-source=guix@@1.0=./guix
+@end example
+
+@item --with-input=@var{package}=@var{replacement}
+Replace dependency on @var{package} by a dependency on
+@var{replacement}. @var{package} must be a package name, and
+@var{replacement} must be a package specification such as @code{guile}
+or @code{guile@@1.8}.
+
+For instance, the following command builds Guix, but replaces its
+dependency on the current stable version of Guile with a dependency on
+the legacy version of Guile, @code{guile@@2.0}:
@example
-$ guix refresh
-gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
-gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
+guix build --with-input=guile=guile@@2.0 guix
@end example
-Alternately, one can specify packages to consider, in which case a
-warning is emitted for packages that lack an updater:
+This is a recursive, deep replacement. So in this example, both
+@code{guix} and its dependency @code{guile-json} (which also depends on
+@code{guile}) get rebuilt against @code{guile@@2.0}.
+
+This is implemented using the @code{package-input-rewriting} Scheme
+procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).
+
+@item --with-graft=@var{package}=@var{replacement}
+This is similar to @code{--with-input} but with an important difference:
+instead of rebuilding the whole dependency chain, @var{replacement} is
+built and then @dfn{grafted} onto the binaries that were initially
+referring to @var{package}. @xref{Security Updates}, for more
+information on grafts.
+
+For example, the command below grafts version 3.5.4 of GnuTLS onto Wget
+and all its dependencies, replacing references to the version of GnuTLS
+they currently refer to:
@example
-$ guix refresh coreutils guile guile-ssh
-gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
-gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13
+guix build --with-graft=gnutls=gnutls@@3.5.4 wget
@end example
-@command{guix refresh} browses the upstream repository of each package and determines
-the highest version number of the releases therein. The command
-knows how to update specific types of packages: GNU packages, ELPA
-packages, etc.---see the documentation for @option{--type} below. There
-are many packages, though, for which it lacks a method to determine
-whether a new upstream release is available. However, the mechanism is
-extensible, so feel free to get in touch with us to add a new method!
+This has the advantage of being much faster than rebuilding everything.
+But there is a caveat: it works if and only if @var{package} and
+@var{replacement} are strictly compatible---for example, if they provide
+a library, the application binary interface (ABI) of those libraries
+must be compatible. If @var{replacement} is somehow incompatible with
+@var{package}, then the resulting package may be unusable. Use with
+care!
-@table @code
+@item --with-git-url=@var{package}=@var{url}
+@cindex Git, using the latest commit
+@cindex latest commit, building
+Build @var{package} from the latest commit of the @code{master} branch of the
+Git repository at @var{url}. Git sub-modules of the repository are fetched,
+recursively.
-@item --recursive
-Consider the packages specified, and all the packages upon which they depend.
+For example, the following command builds the NumPy Python library against the
+latest commit of the master branch of Python itself:
@example
-$ guix refresh --recursive coreutils
-gnu/packages/acl.scm:35:2: warning: no updater for acl
-gnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4
-gnu/packages/xml.scm:68:2: warning: no updater for expat
-gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest version of gmp
-@dots{}
+guix build python-numpy \
+ --with-git-url=python=https://github.com/python/cpython
@end example
-@end table
+This option can also be combined with @code{--with-branch} or
+@code{--with-commit} (see below).
-Sometimes the upstream name differs from the package name used in Guix,
-and @command{guix refresh} needs a little help. Most updaters honor the
-@code{upstream-name} property in package definitions, which can be used
-to that effect:
+@cindex continuous integration
+Obviously, since it uses the latest commit of the given branch, the result of
+such a command varies over time. Nevertheless it is a convenient way to
+rebuild entire software stacks against the latest commit of one or more
+packages. This is particularly useful in the context of continuous
+integration (CI).
+
+Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed up
+consecutive accesses to the same repository. You may want to clean it up once
+in a while to save disk space.
+
+@item --with-branch=@var{package}=@var{branch}
+Build @var{package} from the latest commit of @var{branch}. If the
+@code{source} field of @var{package} is an origin with the @code{git-fetch}
+method (@pxref{origin Reference}) or a @code{git-checkout} object, the
+repository URL is taken from that @code{source}. Otherwise you have to use
+@code{--with-git-url} to specify the URL of the Git repository.
+
+For instance, the following command builds @code{guile-sqlite3} from the
+latest commit of its @code{master} branch, and then builds @code{guix} (which
+depends on it) and @code{cuirass} (which depends on @code{guix}) against this
+specific @code{guile-sqlite3} build:
@example
-(define-public network-manager
- (package
- (name "network-manager")
- ;; @dots{}
- (properties '((upstream-name . "NetworkManager")))))
+guix build --with-branch=guile-sqlite3=master cuirass
@end example
-When passed @code{--update}, it modifies distribution source files to
-update the version numbers and source tarball hashes of those package
-recipes (@pxref{Defining Packages}). This is achieved by downloading
-each package's latest source tarball and its associated OpenPGP
-signature, authenticating the downloaded tarball against its signature
-using @command{gpg}, and finally computing its hash. When the public
-key used to sign the tarball is missing from the user's keyring, an
-attempt is made to automatically retrieve it from a public key server;
-when this is successful, the key is added to the user's keyring; otherwise,
-@command{guix refresh} reports an error.
+@item --with-commit=@var{package}=@var{commit}
+This is similar to @code{--with-branch}, except that it builds from
+@var{commit} rather than the tip of a branch. @var{commit} must be a valid
+Git commit SHA1 identifier.
+@end table
-The following options are supported:
+@node Additional Build Options
+@subsection Additional Build Options
+
+The command-line options presented below are specific to @command{guix
+build}.
@table @code
-@item --expression=@var{expr}
-@itemx -e @var{expr}
-Consider the package @var{expr} evaluates to.
+@item --quiet
+@itemx -q
+Build quietly, without displaying the build log; this is equivalent to
+@code{--verbosity=0}. Upon completion, the build log is kept in @file{/var}
+(or similar) and can always be retrieved using the @option{--log-file} option.
-This is useful to precisely refer to a package, as in this example:
+@item --file=@var{file}
+@itemx -f @var{file}
+Build the package, derivation, or other file-like object that the code within
+@var{file} evaluates to (@pxref{G-Expressions, file-like objects}).
+
+As an example, @var{file} might contain a package definition like this
+(@pxref{Defining Packages}):
@example
-guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
+@verbatiminclude package-hello.scm
@end example
-This command lists the dependents of the ``final'' libc (essentially all
-the packages.)
-
-@item --update
-@itemx -u
-Update distribution source files (package recipes) in place. This is
-usually run from a checkout of the Guix source tree (@pxref{Running
-Guix Before It Is Installed}):
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Build the package or derivation @var{expr} evaluates to.
-@example
-$ ./pre-inst-env guix refresh -s non-core -u
-@end example
+For example, @var{expr} may be @code{(@@ (gnu packages guile)
+guile-1.8)}, which unambiguously designates this specific variant of
+version 1.8 of Guile.
-@xref{Defining Packages}, for more information on package definitions.
+Alternatively, @var{expr} may be a G-expression, in which case it is used
+as a build program passed to @code{gexp->derivation}
+(@pxref{G-Expressions}).
-@item --select=[@var{subset}]
-@itemx -s @var{subset}
-Select all the packages in @var{subset}, one of @code{core} or
-@code{non-core}.
+Lastly, @var{expr} may refer to a zero-argument monadic procedure
+(@pxref{The Store Monad}). The procedure must return a derivation as a
+monadic value, which is then passed through @code{run-with-store}.
-The @code{core} subset refers to all the packages at the core of the
-distribution---i.e., packages that are used to build ``everything
-else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
-changing one of these packages in the distribution entails a rebuild of
-all the others. Thus, such updates are an inconvenience to users in
-terms of build time or bandwidth used to achieve the upgrade.
+@item --source
+@itemx -S
+Build the source derivations of the packages, rather than the packages
+themselves.
-The @code{non-core} subset refers to the remaining packages. It is
-typically useful in cases where an update of the core packages would be
-inconvenient.
+For instance, @code{guix build -S gcc} returns something like
+@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC
+source tarball.
-@item --manifest=@var{file}
-@itemx -m @var{file}
-Select all the packages from the manifest in @var{file}. This is useful to
-check if any packages of the user manifest can be updated.
+The returned source tarball is the result of applying any patches and
+code snippets specified in the package @code{origin} (@pxref{Defining
+Packages}).
-@item --type=@var{updater}
-@itemx -t @var{updater}
-Select only packages handled by @var{updater} (may be a comma-separated
-list of updaters). Currently, @var{updater} may be one of:
+@item --sources
+Fetch and return the source of @var{package-or-derivation} and all their
+dependencies, recursively. This is a handy way to obtain a local copy
+of all the source code needed to build @var{packages}, allowing you to
+eventually build them even without network access. It is an extension
+of the @code{--source} option and can accept one of the following
+optional argument values:
@table @code
-@item gnu
-the updater for GNU packages;
-@item gnome
-the updater for GNOME packages;
-@item kde
-the updater for KDE packages;
-@item xorg
-the updater for X.org packages;
-@item kernel.org
-the updater for packages hosted on kernel.org;
-@item elpa
-the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
-@item cran
-the updater for @uref{https://cran.r-project.org/, CRAN} packages;
-@item bioconductor
-the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
-@item cpan
-the updater for @uref{http://www.cpan.org/, CPAN} packages;
-@item pypi
-the updater for @uref{https://pypi.python.org, PyPI} packages.
-@item gem
-the updater for @uref{https://rubygems.org, RubyGems} packages.
-@item github
-the updater for @uref{https://github.com, GitHub} packages.
-@item hackage
-the updater for @uref{https://hackage.haskell.org, Hackage} packages.
-@item stackage
-the updater for @uref{https://www.stackage.org, Stackage} packages.
-@item crate
-the updater for @uref{https://crates.io, Crates} packages.
-@end table
+@item package
+This value causes the @code{--sources} option to behave in the same way
+as the @code{--source} option.
-For instance, the following command only checks for updates of Emacs
-packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:
+@item all
+Build the source derivations of all packages, including any source that
+might be listed as @code{inputs}. This is the default value.
@example
-$ guix refresh --type=elpa,cran
-gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
-gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
+$ guix build --sources tzdata
+The following derivations will be built:
+ /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
+ /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
@end example
-@end table
-
-In addition, @command{guix refresh} can be passed one or more package
-names, as in this example:
+@item transitive
+Build the source derivations of all packages, as well of all transitive
+inputs to the packages. This can be used e.g.@: to
+prefetch package source for later offline building.
@example
-$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8
+$ guix build --sources=transitive tzdata
+The following derivations will be built:
+ /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
+ /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
+ /gnu/store/@dots{}-grep-2.21.tar.xz.drv
+ /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
+ /gnu/store/@dots{}-make-4.1.tar.xz.drv
+ /gnu/store/@dots{}-bash-4.3.tar.xz.drv
+@dots{}
@end example
-@noindent
-The command above specifically updates the @code{emacs} and
-@code{idutils} packages. The @code{--select} option would have no
-effect in this case.
+@end table
-When considering whether to upgrade a package, it is sometimes
-convenient to know which packages would be affected by the upgrade and
-should be checked for compatibility. For this the following option may
-be used when passing @command{guix refresh} one or more package names:
+@item --system=@var{system}
+@itemx -s @var{system}
+Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
+the system type of the build host.
-@table @code
+@quotation Note
+The @code{--system} flag is for @emph{native} compilation and must not
+be confused with cross-compilation. See @code{--target} below for
+information on cross-compilation.
+@end quotation
-@item --list-updaters
-@itemx -L
-List available updaters and exit (see @option{--type} above.)
+An example use of this is on Linux-based systems, which can emulate
+different personalities. For instance, passing
+@code{--system=i686-linux} on an @code{x86_64-linux} system or
+@code{--system=armhf-linux} on an @code{aarch64-linux} system allows you
+to build packages in a complete 32-bit environment.
-For each updater, display the fraction of packages it covers; at the
-end, display the fraction of packages covered by all these updaters.
+@quotation Note
+Building for an @code{armhf-linux} system is unconditionally enabled on
+@code{aarch64-linux} machines, although certain aarch64 chipsets do not
+allow for this functionality, notably the ThunderX.
+@end quotation
-@item --list-dependent
-@itemx -l
-List top-level dependent packages that would need to be rebuilt as a
-result of upgrading one or more packages.
+Similarly, when transparent emulation with QEMU and @code{binfmt_misc}
+is enabled (@pxref{Virtualization Services,
+@code{qemu-binfmt-service-type}}), you can build for any system for
+which a QEMU @code{binfmt_misc} handler is installed.
+
+Builds for a system other than that of the machine you are using can
+also be offloaded to a remote machine of the right architecture.
+@xref{Daemon Offload Setup}, for more information on offloading.
+
+@item --target=@var{triplet}
+@cindex cross-compilation
+Cross-build for @var{triplet}, which must be a valid GNU triplet, such
+as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
+configuration triplets,, autoconf, Autoconf}).
+
+@anchor{build-check}
+@item --check
+@cindex determinism, checking
+@cindex reproducibility, checking
+Rebuild @var{package-or-derivation}, which are already available in the
+store, and raise an error if the build results are not bit-for-bit
+identical.
+
+This mechanism allows you to check whether previously installed
+substitutes are genuine (@pxref{Substitutes}), or whether the build result
+of a package is deterministic. @xref{Invoking guix challenge}, for more
+background information and tools.
+
+When used in conjunction with @option{--keep-failed}, the differing
+output is kept in the store, under @file{/gnu/store/@dots{}-check}.
+This makes it easy to look for differences between the two results.
+
+@item --repair
+@cindex repairing store items
+@cindex corruption, recovering from
+Attempt to repair the specified store items, if they are corrupt, by
+re-downloading or rebuilding them.
+
+This operation is not atomic and thus restricted to @code{root}.
+
+@item --derivations
+@itemx -d
+Return the derivation paths, not the output paths, of the given
+packages.
+
+@item --root=@var{file}
+@itemx -r @var{file}
+@cindex GC roots, adding
+@cindex garbage collector roots, adding
+Make @var{file} a symlink to the result, and register it as a garbage
+collector root.
-@xref{Invoking guix graph, the @code{reverse-package} type of
-@command{guix graph}}, for information on how to visualize the list of
-dependents of a package.
+Consequently, the results of this @command{guix build} invocation are
+protected from garbage collection until @var{file} is removed. When
+that option is omitted, build results are eligible for garbage
+collection as soon as the build completes. @xref{Invoking guix gc}, for
+more on GC roots.
-@end table
+@item --log-file
+@cindex build logs, access
+Return the build log file names or URLs for the given
+@var{package-or-derivation}, or raise an error if build logs are
+missing.
-Be aware that the @code{--list-dependent} option only
-@emph{approximates} the rebuilds that would be required as a result of
-an upgrade. More rebuilds might be required under some circumstances.
+This works regardless of how packages or derivations are specified. For
+instance, the following invocations are equivalent:
@example
-$ guix refresh --list-dependent flex
-Building the following 120 packages would ensure 213 dependent packages are rebuilt:
-hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
+guix build --log-file `guix build -d guile`
+guix build --log-file `guix build guile`
+guix build --log-file guile
+guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
@end example
-The command above lists a set of packages that could be built to check
-for compatibility with an upgraded @code{flex} package.
-
-@table @code
+If a log is unavailable locally, and unless @code{--no-substitutes} is
+passed, the command looks for a corresponding log on one of the
+substitute servers (as specified with @code{--substitute-urls}.)
-@item --list-transitive
-List all the packages which one or more packages depend upon.
+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:
@example
-$ guix refresh --list-transitive flex
-flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6
-bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4 file@@5.33 @dots{}
+$ guix build --log-file gdb -s mips64el-linux
+https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10
@end example
+You can freely access a huge library of build logs!
@end table
-The command above lists a set of packages which, when changed, would cause
-@code{flex} to be rebuilt.
-
-The following options can be used to customize GnuPG operation:
-
-@table @code
-
-@item --gpg=@var{command}
-Use @var{command} as the GnuPG 2.x command. @var{command} is searched
-for in @code{$PATH}.
+@node Debugging Build Failures
+@subsection Debugging Build Failures
-@item --keyring=@var{file}
-Use @var{file} as the keyring for upstream keys. @var{file} must be in the
-@dfn{keybox format}. Keybox files usually have a name ending in @file{.kbx}
-and the GNU@tie{}Privacy Guard (GPG) can manipulate these files
-(@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, for
-information on a tool to manipulate keybox files).
+@cindex build failures, debugging
+When defining a new package (@pxref{Defining Packages}), you will
+probably find yourself spending some time debugging and tweaking the
+build until it succeeds. To do that, you need to operate the build
+commands yourself in an environment as close as possible to the one the
+build daemon uses.
-When this option is omitted, @command{guix refresh} uses
-@file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream
-signing keys. OpenPGP signatures are checked against keys from this keyring;
-missing keys are downloaded to this keyring as well (see
-@option{--key-download} below.)
+To that end, the first thing to do is to use the @option{--keep-failed}
+or @option{-K} option of @command{guix build}, which will keep the
+failed build tree in @file{/tmp} or whatever directory you specified as
+@code{TMPDIR} (@pxref{Invoking guix build, @code{--keep-failed}}).
-You can export keys from your default GPG keyring into a keybox file using
-commands like this one:
+From there on, you can @command{cd} to the failed build tree and source
+the @file{environment-variables} file, which contains all the
+environment variable definitions that were in place when the build
+failed. So let's say you're debugging a build failure in package
+@code{foo}; a typical session would look like this:
@example
-gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx
+$ guix build foo -K
+@dots{} @i{build fails}
+$ cd /tmp/guix-build-foo.drv-0
+$ source ./environment-variables
+$ cd foo-1.2
@end example
-Likewise, you can fetch keys to a specific keybox file like this:
+Now, you can invoke commands as if you were the daemon (almost) and
+troubleshoot your build process.
+
+Sometimes it happens that, for example, a package's tests pass when you
+run them manually but they fail when the daemon runs them. This can
+happen because the daemon runs builds in containers where, unlike in our
+environment above, network access is missing, @file{/bin/sh} does not
+exist, etc. (@pxref{Build Environment Setup}).
+
+In such cases, you may need to run inspect the build process from within
+a container similar to the one the build daemon creates:
@example
-gpg --no-default-keyring --keyring mykeyring.kbx \
- --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+$ guix build -K foo
+@dots{}
+$ cd /tmp/guix-build-foo.drv-0
+$ guix environment --no-grafts -C foo --ad-hoc strace gdb
+[env]# source ./environment-variables
+[env]# cd foo-1.2
@end example
-@ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
-Privacy Guard}, for more information on GPG's @option{--keyring} option.
+Here, @command{guix environment -C} creates a container and spawns a new
+shell in it (@pxref{Invoking guix environment}). The @command{--ad-hoc
+strace gdb} part adds the @command{strace} and @command{gdb} commands to
+the container, which would may find handy while debugging. The
+@option{--no-grafts} option makes sure we get the exact same
+environment, with ungrafted packages (@pxref{Security Updates}, for more
+info on grafts).
-@item --key-download=@var{policy}
-Handle missing OpenPGP keys according to @var{policy}, which may be one
-of:
+To get closer to a container like that used by the build daemon, we can
+remove @file{/bin/sh}:
-@table @code
-@item always
-Always download missing OpenPGP keys from the key server, and add them
-to the user's GnuPG keyring.
+@example
+[env]# rm /bin/sh
+@end example
-@item never
-Never try to download missing OpenPGP keys. Instead just bail out.
+(Don't worry, this is harmless: this is all happening in the throw-away
+container created by @command{guix environment}.)
-@item interactive
-When a package signed with an unknown OpenPGP key is encountered, ask
-the user whether to download it or not. This is the default behavior.
-@end table
+The @command{strace} command is probably not in the search path, but we
+can run:
-@item --key-server=@var{host}
-Use @var{host} as the OpenPGP key server when importing a public key.
+@example
+[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
+@end example
-@end table
+In this way, not only you will have reproduced the environment variables
+the daemon uses, you will also be running the build process in a container
+similar to the one the daemon uses.
-The @code{github} updater uses the
-@uref{https://developer.github.com/v3/, GitHub API} to query for new
-releases. When used repeatedly e.g.@: when refreshing all packages,
-GitHub will eventually refuse to answer any further API requests. By
-default 60 API requests per hour are allowed, and a full refresh on all
-GitHub packages in Guix requires more than this. Authentication with
-GitHub through the use of an API token alleviates these limits. To use
-an API token, set the environment variable @code{GUIX_GITHUB_TOKEN} to a
-token procured from @uref{https://github.com/settings/tokens} or
-otherwise.
+@node Invoking guix edit
+@section Invoking @command{guix edit}
-@node Invoking guix lint
-@section Invoking @command{guix lint}
+@cindex @command{guix edit}
+@cindex package definition, editing
+So many packages, so many source files! The @command{guix edit} command
+facilitates the life of users and packagers by pointing their editor at
+the source file containing the definition of the specified packages.
+For instance:
-@cindex @command{guix lint}
-@cindex package, checking for errors
-The @command{guix lint} command is meant to help package developers avoid
-common errors and use a consistent style. It runs a number of checks on
-a given set of packages in order to find common mistakes in their
-definitions. Available @dfn{checkers} include (see
-@code{--list-checkers} for a complete list):
+@example
+guix edit gcc@@4.9 vim
+@end example
-@table @code
-@item synopsis
-@itemx description
-Validate certain typographical and stylistic rules about package
-descriptions and synopses.
+@noindent
+launches the program specified in the @code{VISUAL} or in the
+@code{EDITOR} environment variable to view the recipe of GCC@tie{}4.9.3
+and that of Vim.
-@item inputs-should-be-native
-Identify inputs that should most likely be native inputs.
+If you are using a Guix Git checkout (@pxref{Building from Git}), or
+have created your own packages on @code{GUIX_PACKAGE_PATH}
+(@pxref{Package Modules}), you will be able to edit the package
+recipes. In other cases, you will be able to examine the read-only recipes
+for packages currently in the store.
-@item source
-@itemx home-page
-@itemx mirror-url
-@itemx github-url
-@itemx source-file-name
-Probe @code{home-page} and @code{source} URLs and report those that are
-invalid. Suggest a @code{mirror://} URL when applicable. If the
-@code{source} URL redirects to a GitHub URL, recommend usage of the GitHub
-URL. Check that the source file name is meaningful, e.g.@: is not just a
-version number or ``git-checkout'', without a declared @code{file-name}
-(@pxref{origin Reference}).
-@item source-unstable-tarball
-Parse the @code{source} URL to determine if a tarball from GitHub is
-autogenerated or if it is a release tarball. Unfortunately GitHub's
-autogenerated tarballs are sometimes regenerated.
+@node Invoking guix download
+@section Invoking @command{guix download}
-@item cve
-@cindex security vulnerabilities
-@cindex CVE, Common Vulnerabilities and Exposures
-Report known vulnerabilities found in the Common Vulnerabilities and
-Exposures (CVE) databases of the current and past year
-@uref{https://nvd.nist.gov/download.cfm#CVE_FEED, published by the US
-NIST}.
+@cindex @command{guix download}
+@cindex downloading package sources
+When writing a package definition, developers typically need to download
+a source tarball, compute its SHA256 hash, and write that
+hash in the package definition (@pxref{Defining Packages}). The
+@command{guix download} tool helps with this task: it downloads a file
+from the given URI, adds it to the store, and prints both its file name
+in the store and its SHA256 hash.
-To view information about a particular vulnerability, visit pages such as:
+The fact that the downloaded file is added to the store saves bandwidth:
+when the developer eventually tries to build the newly defined package
+with @command{guix build}, the source tarball will not have to be
+downloaded again because it is already in the store. It is also a
+convenient way to temporarily stash files, which may be deleted
+eventually (@pxref{Invoking guix gc}).
-@itemize
-@item
-@indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
-@item
-@indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
-@end itemize
+The @command{guix download} command supports the same URIs as used in
+package definitions. In particular, it supports @code{mirror://} URIs.
+@code{https} URIs (HTTP over TLS) are supported @emph{provided} the
+Guile bindings for GnuTLS are available in the user's environment; when
+they are not available, an error is raised. @xref{Guile Preparations,
+how to install the GnuTLS bindings for Guile,, gnutls-guile,
+GnuTLS-Guile}, for more information.
-@noindent
-where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
-@code{CVE-2015-7554}.
+@command{guix download} verifies HTTPS server certificates by loading
+the certificates of X.509 authorities from the directory pointed to by
+the @code{SSL_CERT_DIR} environment variable (@pxref{X.509
+Certificates}), unless @option{--no-check-certificate} is used.
-Package developers can specify in package recipes the
-@uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)}
-name and version of the package when they differ from the name or version
-that Guix uses, as in this example:
+The following options are available:
-@example
-(package
- (name "grub")
- ;; @dots{}
- ;; CPE calls this package "grub2".
- (properties '((cpe-name . "grub2")
- (cpe-version . "2.3")))
-@end example
+@table @code
+@item --format=@var{fmt}
+@itemx -f @var{fmt}
+Write the hash in the format specified by @var{fmt}. For more
+information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
-@c See <http://www.openwall.com/lists/oss-security/2017/03/15/3>.
-Some entries in the CVE database do not specify which version of a
-package they apply to, and would thus ``stick around'' forever. Package
-developers who found CVE alerts and verified they can be ignored can
-declare them as in this example:
+@item --no-check-certificate
+Do not validate the X.509 certificates of HTTPS servers.
-@example
-(package
- (name "t1lib")
- ;; @dots{}
- ;; These CVEs no longer apply and can be safely ignored.
- (properties `((lint-hidden-cve . ("CVE-2011-0433"
- "CVE-2011-1553"
- "CVE-2011-1554"
- "CVE-2011-5244")))))
-@end example
+When using this option, you have @emph{absolutely no guarantee} that you
+are communicating with the authentic server responsible for the given
+URL, which makes you vulnerable to ``man-in-the-middle'' attacks.
-@item formatting
-Warn about obvious source code formatting issues: trailing white space,
-use of tabulations, etc.
+@item --output=@var{file}
+@itemx -o @var{file}
+Save the downloaded file to @var{file} instead of adding it to the
+store.
@end table
+@node Invoking guix hash
+@section Invoking @command{guix hash}
+
+@cindex @command{guix hash}
+The @command{guix hash} command computes the SHA256 hash of a file.
+It is primarily a convenience tool for anyone contributing to the
+distribution: it computes the cryptographic hash of a file, which can be
+used in the definition of a package (@pxref{Defining Packages}).
+
The general syntax is:
@example
-guix lint @var{options} @var{package}@dots{}
+guix hash @var{option} @var{file}
@end example
-If no package is given on the command line, then all packages are checked.
-The @var{options} may be zero or more of the following:
+When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the
+hash of data read from standard input. @command{guix hash} has the
+following options:
@table @code
-@item --list-checkers
-@itemx -l
-List and describe all the available checkers that will be run on packages
-and exit.
-@item --checkers
-@itemx -c
-Only enable the checkers specified in a comma-separated list using the
-names returned by @code{--list-checkers}.
+@item --format=@var{fmt}
+@itemx -f @var{fmt}
+Write the hash in the format specified by @var{fmt}.
-@end table
+Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
+(@code{hex} and @code{hexadecimal} can be used as well).
-@node Invoking guix size
-@section Invoking @command{guix size}
+If the @option{--format} option is not specified, @command{guix hash}
+will output the hash in @code{nix-base32}. This representation is used
+in the definitions of packages.
-@cindex size
-@cindex package size
-@cindex closure
-@cindex @command{guix size}
-The @command{guix size} command helps package developers profile the
-disk usage of packages. It is easy to overlook the impact of an
-additional dependency added to a package, or the impact of using a
-single output for a package that could easily be split (@pxref{Packages
-with Multiple Outputs}). Such are the typical issues that
-@command{guix size} can highlight.
+@item --recursive
+@itemx -r
+Compute the hash on @var{file} recursively.
-The command can be passed one or more package specifications
-such as @code{gcc@@4.8}
-or @code{guile:debug}, or a file name in the store. Consider this
-example:
+In this case, the hash is computed on an archive containing @var{file},
+including its children if it is a directory. Some of the metadata of
+@var{file} is part of the archive; for instance, when @var{file} is a
+regular file, the hash is different depending on whether @var{file} is
+executable or not. Metadata such as time stamps has no impact on the
+hash (@pxref{Invoking guix archive}).
+@c FIXME: Replace xref above with xref to an ``Archive'' section when
+@c it exists.
+
+@item --exclude-vcs
+@itemx -x
+When combined with @option{--recursive}, exclude version control system
+directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.)
+
+@vindex git-fetch
+As an example, here is how you would compute the hash of a Git checkout,
+which is useful when using the @code{git-fetch} method (@pxref{origin
+Reference}):
@example
-$ guix size coreutils
-store item total self
-/gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
-/gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
-/gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
-/gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
-/gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
-/gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
-/gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
-/gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
-total: 78.9 MiB
+$ git clone http://example.org/foo.git
+$ cd foo
+$ guix hash -rx .
@end example
+@end table
-@cindex closure
-The store items listed here constitute the @dfn{transitive closure} of
-Coreutils---i.e., Coreutils and all its dependencies, recursively---as
-would be returned by:
+@node Invoking guix import
+@section Invoking @command{guix import}
+
+@cindex importing packages
+@cindex package import
+@cindex package conversion
+@cindex Invoking @command{guix import}
+The @command{guix import} command is useful for people who would like to
+add a package to the distribution with as little work as
+possible---a legitimate demand. The command knows of a few
+repositories from which it can ``import'' package metadata. The result
+is a package definition, or a template thereof, in the format we know
+(@pxref{Defining Packages}).
+
+The general syntax is:
@example
-$ guix gc -R /gnu/store/@dots{}-coreutils-8.23
+guix import @var{importer} @var{options}@dots{}
@end example
-Here the output shows three columns next to store items. The first column,
-labeled ``total'', shows the size in mebibytes (MiB) of the closure of
-the store item---that is, its own size plus the size of all its
-dependencies. The next column, labeled ``self'', shows the size of the
-item itself. The last column shows the ratio of the size of the item
-itself to the space occupied by all the items listed here.
-
-In this example, we see that the closure of Coreutils weighs in at
-79@tie{}MiB, most of which is taken by libc and GCC's run-time support
-libraries. (That libc and GCC's libraries represent a large fraction of
-the closure is not a problem @i{per se} because they are always available
-on the system anyway.)
+@var{importer} specifies the source from which to import package
+metadata, and @var{options} specifies a package identifier and other
+options specific to @var{importer}. Currently, the available
+``importers'' are:
-When the package(s) passed to @command{guix size} are available in the
-store@footnote{More precisely, @command{guix size} looks for the
-@emph{ungrafted} variant of the given package(s), as returned by
-@code{guix build @var{package} --no-grafts}. @xref{Security Updates},
-for information on grafts.}, @command{guix size} queries the daemon to determine its
-dependencies, and measures its size in the store, similar to @command{du
--ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
-Coreutils}).
+@table @code
+@item gnu
+Import metadata for the given GNU package. This provides a template
+for the latest version of that GNU package, including the hash of its
+source tarball, and its canonical synopsis and description.
-When the given packages are @emph{not} in the store, @command{guix size}
-reports information based on the available substitutes
-(@pxref{Substitutes}). This makes it possible it to profile disk usage of
-store items that are not even on disk, only available remotely.
+Additional information such as the package dependencies and its
+license needs to be figured out manually.
-You can also specify several package names:
+For example, the following command returns a package definition for
+GNU@tie{}Hello:
@example
-$ guix size coreutils grep sed bash
-store item total self
-/gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4%
-/gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8%
-/gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6%
-/gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2%
-@dots{}
-total: 102.3 MiB
+guix import gnu hello
@end example
-@noindent
-In this example we see that the combination of the four packages takes
-102.3@tie{}MiB in total, which is much less than the sum of each closure
-since they have a lot of dependencies in common.
+Specific command-line options are:
-The available options are:
+@table @code
+@item --key-download=@var{policy}
+As for @code{guix refresh}, specify the policy to handle missing OpenPGP
+keys when verifying the package signature. @xref{Invoking guix
+refresh, @code{--key-download}}.
+@end table
-@table @option
+@item pypi
+@cindex pypi
+Import metadata from the @uref{https://pypi.python.org/, Python Package
+Index}. Information is taken from the JSON-formatted description
+available at @code{pypi.python.org} and usually includes all the relevant
+information, including package dependencies. For maximum efficiency, it
+is recommended to install the @command{unzip} utility, so that the
+importer can unzip Python wheels and gather data from them.
-@item --substitute-urls=@var{urls}
-Use substitute information from @var{urls}.
-@xref{client-substitute-urls, the same option for @code{guix build}}.
+The command below imports metadata for the @code{itsdangerous} Python
+package:
-@item --sort=@var{key}
-Sort lines according to @var{key}, one of the following options:
+@example
+guix import pypi itsdangerous
+@end example
@table @code
-@item self
-the size of each item (the default);
-@item closure
-the total size of the item's closure.
+@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 --map-file=@var{file}
-Write a graphical map of disk usage in PNG format to @var{file}.
-
-For the example above, the map looks like this:
-
-@image{images/coreutils-size-map,5in,, map of Coreutils disk usage
-produced by @command{guix size}}
+@item gem
+@cindex gem
+Import metadata from @uref{https://rubygems.org/, RubyGems}. Information
+is taken from the JSON-formatted description available at
+@code{rubygems.org} and includes most relevant information, including
+runtime dependencies. There are some caveats, however. The metadata
+doesn't distinguish between synopses and descriptions, so the same string
+is used for both fields. Additionally, the details of non-Ruby
+dependencies required to build native extensions is unavailable and left
+as an exercise to the packager.
-This option requires that
-@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be
-installed and visible in Guile's module search path. When that is not
-the case, @command{guix size} fails as it tries to load it.
+The command below imports metadata for the @code{rails} Ruby package:
-@item --system=@var{system}
-@itemx -s @var{system}
-Consider packages for @var{system}---e.g., @code{x86_64-linux}.
+@example
+guix import gem rails
+@end example
+@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
-@node Invoking guix graph
-@section Invoking @command{guix graph}
+@item cpan
+@cindex CPAN
+Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
+Information is taken from the JSON-formatted metadata provided through
+@uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most
+relevant information, such as module dependencies. License information
+should be checked closely. If Perl is available in the store, then the
+@code{corelist} utility will be used to filter core modules out of the
+list of dependencies.
-@cindex DAG
-@cindex @command{guix graph}
-@cindex package dependencies
-Packages and their dependencies form a @dfn{graph}, specifically a
-directed acyclic graph (DAG). It can quickly become difficult to have a
-mental model of the package DAG, so the @command{guix graph} command
-provides a visual representation of the DAG. By default,
-@command{guix graph} emits a DAG representation in the input format of
-@uref{http://www.graphviz.org/, Graphviz}, so its output can be passed
-directly to the @command{dot} command of Graphviz. It can also emit an
-HTML page with embedded JavaScript code to display a ``chord diagram''
-in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
-emit Cypher queries to construct a graph in a graph database supporting
-the @uref{http://www.opencypher.org/, openCypher} query language.
-The general syntax is:
+The command command below imports metadata for the @code{Acme::Boolean}
+Perl module:
@example
-guix graph @var{options} @var{package}@dots{}
+guix import cpan Acme::Boolean
@end example
-For example, the following command generates a PDF file representing the
-package DAG for the GNU@tie{}Core Utilities, showing its build-time
-dependencies:
+@item cran
+@cindex CRAN
+@cindex Bioconductor
+Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
+central repository for the @uref{http://r-project.org, GNU@tie{}R
+statistical and graphical environment}.
-@example
-guix graph coreutils | dot -Tpdf > dag.pdf
-@end example
+Information is extracted from the @code{DESCRIPTION} file of the package.
-The output looks like this:
+The command command below imports metadata for the @code{Cairo}
+R package:
-@image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
+@example
+guix import cran Cairo
+@end example
-Nice little graph, no?
+When @code{--recursive} is added, the importer will traverse the
+dependency graph of the given upstream package recursively and generate
+package expressions for all those packages that are not yet in Guix.
-But there is more than one graph! The one above is concise: it is the
-graph of package objects, omitting implicit inputs such as GCC, libc,
-grep, etc. It is often useful to have such a concise graph, but
-sometimes one may want to see more details. @command{guix graph} supports
-several types of graphs, allowing you to choose the level of detail:
+When @code{--archive=bioconductor} is added, metadata is imported from
+@uref{https://www.bioconductor.org/, Bioconductor}, a repository of R
+packages for for the analysis and comprehension of high-throughput
+genomic data in bioinformatics.
-@table @code
-@item package
-This is the default type used in the example above. It shows the DAG of
-package objects, excluding implicit dependencies. It is concise, but
-filters out many details.
+Information is extracted from the @code{DESCRIPTION} file of a package
+published on the web interface of the Bioconductor SVN repository.
-@item reverse-package
-This shows the @emph{reverse} DAG of packages. For example:
+The command below imports metadata for the @code{GenomicRanges}
+R package:
@example
-guix graph --type=reverse-package ocaml
+guix import cran --archive=bioconductor GenomicRanges
@end example
-...@: yields the graph of packages that depend on OCaml.
-
-Note that for core packages this can yield huge graphs. If all you want
-is to know the number of packages that depend on a given package, use
-@command{guix refresh --list-dependent} (@pxref{Invoking guix refresh,
-@option{--list-dependent}}).
+@item texlive
+@cindex TeX Live
+@cindex CTAN
+Import metadata from @uref{http://www.ctan.org/, CTAN}, the
+comprehensive TeX archive network for TeX packages that are part of the
+@uref{https://www.tug.org/texlive/, TeX Live distribution}.
-@item bag-emerged
-This is the package DAG, @emph{including} implicit inputs.
+Information about the package is obtained through the XML API provided
+by CTAN, while the source code is downloaded from the SVN repository of
+the Tex Live project. This is done because the CTAN does not keep
+versioned archives.
-For instance, the following command:
+The command command below imports metadata for the @code{fontspec}
+TeX package:
@example
-guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf
+guix import texlive fontspec
@end example
-...@: yields this bigger graph:
-
-@image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils}
+When @code{--archive=DIRECTORY} is added, the source code is downloaded
+not from the @file{latex} sub-directory of the @file{texmf-dist/source}
+tree in the TeX Live SVN repository, but from the specified sibling
+directory under the same root.
-At the bottom of the graph, we see all the implicit inputs of
-@var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}).
+The command below imports metadata for the @code{ifxetex} package from
+CTAN while fetching the sources from the directory
+@file{texmf/source/generic}:
-Now, note that the dependencies of these implicit inputs---that is, the
-@dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown
-here, for conciseness.
+@example
+guix import texlive --archive=generic ifxetex
+@end example
-@item bag
-Similar to @code{bag-emerged}, but this time including all the bootstrap
-dependencies.
+@item json
+@cindex JSON, import
+Import package metadata from a local JSON file. Consider the following
+example package definition in JSON format:
-@item bag-with-origins
-Similar to @code{bag}, but also showing origins and their dependencies.
+@example
+@{
+ "name": "hello",
+ "version": "2.10",
+ "source": "mirror://gnu/hello/hello-2.10.tar.gz",
+ "build-system": "gnu",
+ "home-page": "https://www.gnu.org/software/hello/",
+ "synopsis": "Hello, GNU world: An example GNU package",
+ "description": "GNU Hello prints a greeting.",
+ "license": "GPL-3.0+",
+ "native-inputs": ["gcc@@6"]
+@}
+@end example
-@item derivation
-This is the most detailed representation: It shows the DAG of
-derivations (@pxref{Derivations}) and plain store items. Compared to
-the above representation, many additional nodes are visible, including
-build scripts, patches, Guile modules, etc.
+The field names are the same as for the @code{<package>} record
+(@xref{Defining Packages}). References to other packages are provided
+as JSON lists of quoted package specification strings such as
+@code{guile} or @code{guile@@2.0}.
-For this type of graph, it is also possible to pass a @file{.drv} file
-name instead of a package name, as in:
+The importer also supports a more explicit source definition using the
+common fields for @code{<origin>} records:
@example
-guix graph -t derivation `guix system build -d my-config.scm`
+@{
+ @dots{}
+ "source": @{
+ "method": "url-fetch",
+ "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
+ "sha256": @{
+ "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
+ @}
+ @}
+ @dots{}
+@}
@end example
-@item module
-This is the graph of @dfn{package modules} (@pxref{Package Modules}).
-For example, the following command shows the graph for the package
-module that defines the @code{guile} package:
+The command below reads metadata from the JSON file @code{hello.json}
+and outputs a package expression:
@example
-guix graph -t module guile | dot -Tpdf > module-graph.pdf
+guix import json hello.json
@end example
-@end table
-
-All the types above correspond to @emph{build-time dependencies}. The
-following graph type represents the @emph{run-time dependencies}:
-@table @code
-@item references
-This is the graph of @dfn{references} of a package output, as returned
-by @command{guix gc --references} (@pxref{Invoking guix gc}).
+@item nix
+Import metadata from a local copy of the source of the
+@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
+relies on the @command{nix-instantiate} command of
+@uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
+typically written in a mixture of Nix-language and Bash code. This
+command only imports the high-level package structure that is written in
+the Nix language. It normally includes all the basic fields of a
+package definition.
-If the given package output is not available in the store, @command{guix
-graph} attempts to obtain dependency information from substitutes.
+When importing a GNU package, the synopsis and descriptions are replaced
+by their canonical upstream variant.
-Here you can also pass a store file name instead of a package name. For
-example, the command below produces the reference graph of your profile
-(which can be big!):
+Usually, you will first need to do:
@example
-guix graph -t references `readlink -f ~/.guix-profile`
+export NIX_REMOTE=daemon
@end example
-@item referrers
-This is the graph of the @dfn{referrers} of a store item, as returned by
-@command{guix gc --referrers} (@pxref{Invoking guix gc}).
+@noindent
+so that @command{nix-instantiate} does not try to open the Nix database.
-This relies exclusively on local information from your store. For
-instance, let us suppose that the current Inkscape is available in 10
-profiles on your machine; @command{guix graph -t referrers inkscape}
-will show a graph rooted at Inkscape and with those 10 profiles linked
-to it.
+As an example, the command below imports the package definition of
+LibreOffice (more precisely, it imports the definition of the package
+bound to the @code{libreoffice} top-level attribute):
-It can help determine what is preventing a store item from being garbage
-collected.
+@example
+guix import nix ~/path/to/nixpkgs libreoffice
+@end example
+
+@item hackage
+@cindex hackage
+Import metadata from the Haskell community's central package archive
+@uref{https://hackage.haskell.org/, Hackage}. Information is taken from
+Cabal files and includes all the relevant information, including package
+dependencies.
+
+Specific command-line options are:
+@table @code
+@item --stdin
+@itemx -s
+Read a Cabal file from standard input.
+@item --no-test-dependencies
+@itemx -t
+Do not include dependencies required only by the test suites.
+@item --cabal-environment=@var{alist}
+@itemx -e @var{alist}
+@var{alist} is a Scheme alist defining the environment in which the
+Cabal conditionals are evaluated. The accepted keys are: @code{os},
+@code{arch}, @code{impl} and a string representing the name of a flag.
+The value associated with a flag has to be either the symbol
+@code{true} or @code{false}. The value associated with other keys
+has to conform to the Cabal file format definition. The default value
+associated with the keys @code{os}, @code{arch} and @code{impl} is
+@samp{linux}, @samp{x86_64} and @samp{ghc}, respectively.
+@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
-The available options are the following:
+The command below imports metadata for the latest version of the
+@code{HTTP} Haskell package without including test dependencies and
+specifying the value of the flag @samp{network-uri} as @code{false}:
-@table @option
-@item --type=@var{type}
-@itemx -t @var{type}
-Produce a graph output of @var{type}, where @var{type} must be one of
-the values listed above.
+@example
+guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
+@end example
-@item --list-types
-List the supported graph types.
+A specific package version may optionally be specified by following the
+package name by an at-sign and a version number as in the following example:
-@item --backend=@var{backend}
-@itemx -b @var{backend}
-Produce a graph using the selected @var{backend}.
+@example
+guix import hackage mtl@@2.1.3.1
+@end example
-@item --list-backends
-List the supported graph backends.
+@item stackage
+@cindex stackage
+The @code{stackage} importer is a wrapper around the @code{hackage} one.
+It takes a package name, looks up the package version included in a
+long-term support (LTS) @uref{https://www.stackage.org, Stackage}
+release and uses the @code{hackage} importer to retrieve its metadata.
+Note that it is up to you to select an LTS release compatible with the
+GHC compiler used by Guix.
-Currently, the available backends are Graphviz and d3.js.
+Specific command-line options are:
-@item --expression=@var{expr}
-@itemx -e @var{expr}
-Consider the package @var{expr} evaluates to.
+@table @code
+@item --no-test-dependencies
+@itemx -t
+Do not include dependencies required only by the test suites.
+@item --lts-version=@var{version}
+@itemx -l @var{version}
+@var{version} is the desired LTS release version. If omitted the latest
+release is used.
+@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
-This is useful to precisely refer to a package, as in this example:
+The command below imports metadata for the @code{HTTP} Haskell package
+included in the LTS Stackage release version 7.18:
@example
-guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
+guix import stackage --lts-version=7.18 HTTP
@end example
-@item --system=@var{system}
-@itemx -s @var{system}
-Display the graph for @var{system}---e.g., @code{i686-linux}.
-
-The package dependency graph is largely architecture-independent, but there
-are some architecture-dependent bits that this option allows you to visualize.
-@end table
+@item elpa
+@cindex elpa
+Import metadata from an Emacs Lisp Package Archive (ELPA) package
+repository (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
+Specific command-line options are:
-@node Invoking guix environment
-@section Invoking @command{guix environment}
+@table @code
+@item --archive=@var{repo}
+@itemx -a @var{repo}
+@var{repo} identifies the archive repository from which to retrieve the
+information. Currently the supported repositories and their identifiers
+are:
+@itemize -
+@item
+@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
+identifier. This is the default.
-@cindex reproducible build environments
-@cindex development environments
-@cindex @command{guix environment}
-@cindex environment, package build environment
-The purpose of @command{guix environment} is to assist hackers in
-creating reproducible development environments without polluting their
-package profile. The @command{guix environment} tool takes one or more
-packages, builds all of their inputs, and creates a shell
-environment to use them.
+Packages from @code{elpa.gnu.org} are signed with one of the keys
+contained in the GnuPG keyring at
+@file{share/emacs/25.1/etc/package-keyring.gpg} (or similar) in the
+@code{emacs} package (@pxref{Package Installation, ELPA package
+signatures,, emacs, The GNU Emacs Manual}).
-The general syntax is:
+@item
+@uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the
+@code{melpa-stable} identifier.
-@example
-guix environment @var{options} @var{package}@dots{}
-@end example
+@item
+@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa}
+identifier.
+@end itemize
-The following example spawns a new shell set up for the development of
-GNU@tie{}Guile:
+@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
-@example
-guix environment guile
-@end example
+@item crate
+@cindex crate
+Import metadata from the crates.io Rust package repository
+@uref{https://crates.io, crates.io}.
-If the needed dependencies are not built yet, @command{guix environment}
-automatically builds them. The environment of the new shell is an augmented
-version of the environment that @command{guix environment} was run in.
-It contains the necessary search paths for building the given package
-added to the existing environment variables. To create a ``pure''
-environment, in which the original environment variables have been unset,
-use the @code{--pure} option@footnote{Users sometimes wrongfully augment
-environment variables such as @code{PATH} in their @file{~/.bashrc}
-file. As a consequence, when @code{guix environment} launches it, Bash
-may read @file{~/.bashrc}, thereby introducing ``impurities'' in these
-environment variables. It is an error to define such environment
-variables in @file{.bashrc}; instead, they should be defined in
-@file{.bash_profile}, which is sourced only by log-in shells.
-@xref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}, for
-details on Bash start-up files.}.
+@item opam
+@cindex OPAM
+@cindex OCaml
+Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package
+repository used by the OCaml community.
+@end table
-@vindex GUIX_ENVIRONMENT
-@command{guix environment} defines the @code{GUIX_ENVIRONMENT}
-variable in the shell it spawns; its value is the file name of the
-profile of this environment. This allows users to, say, define a
-specific prompt for development environments in their @file{.bashrc}
-(@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
+The structure of the @command{guix import} code is modular. It would be
+useful to have more importers for other package formats, and your help
+is welcome here (@pxref{Contributing}).
-@example
-if [ -n "$GUIX_ENVIRONMENT" ]
-then
- export PS1="\u@@\h \w [dev]\$ "
-fi
-@end example
+@node Invoking guix refresh
+@section Invoking @command{guix refresh}
-@noindent
-...@: or to browse the profile:
+@cindex @command {guix refresh}
+The primary audience of the @command{guix refresh} command is developers
+of the GNU software distribution. By default, it reports any packages
+provided by the distribution that are outdated compared to the latest
+upstream version, like this:
@example
-$ ls "$GUIX_ENVIRONMENT/bin"
+$ guix refresh
+gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
+gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
@end example
-Additionally, more than one package may be specified, in which case the
-union of the inputs for the given packages are used. For example, the
-command below spawns a shell where all of the dependencies of both Guile
-and Emacs are available:
+Alternately, one can specify packages to consider, in which case a
+warning is emitted for packages that lack an updater:
@example
-guix environment guile emacs
+$ guix refresh coreutils guile guile-ssh
+gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
+gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13
@end example
-Sometimes an interactive shell session is not desired. An arbitrary
-command may be invoked by placing the @code{--} token to separate the
-command from the rest of the arguments:
+@command{guix refresh} browses the upstream repository of each package and determines
+the highest version number of the releases therein. The command
+knows how to update specific types of packages: GNU packages, ELPA
+packages, etc.---see the documentation for @option{--type} below. There
+are many packages, though, for which it lacks a method to determine
+whether a new upstream release is available. However, the mechanism is
+extensible, so feel free to get in touch with us to add a new method!
-@example
-guix environment guile -- make -j4
-@end example
+@table @code
-In other situations, it is more convenient to specify the list of
-packages needed in the environment. For example, the following command
-runs @command{python} from an environment containing Python@tie{}2.7 and
-NumPy:
+@item --recursive
+Consider the packages specified, and all the packages upon which they depend.
@example
-guix environment --ad-hoc python2-numpy python-2.7 -- python
+$ guix refresh --recursive coreutils
+gnu/packages/acl.scm:35:2: warning: no updater for acl
+gnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4
+gnu/packages/xml.scm:68:2: warning: no updater for expat
+gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest version of gmp
+@dots{}
@end example
-Furthermore, one might want the dependencies of a package and also some
-additional packages that are not build-time or runtime dependencies, but
-are useful when developing nonetheless. Because of this, the
-@code{--ad-hoc} flag is positional. Packages appearing before
-@code{--ad-hoc} are interpreted as packages whose dependencies will be
-added to the environment. Packages appearing after are interpreted as
-packages that will be added to the environment directly. For example,
-the following command creates a Guix development environment that
-additionally includes Git and strace:
-
-@example
-guix environment guix --ad-hoc git strace
-@end example
+@end table
-Sometimes it is desirable to isolate the environment as much as
-possible, for maximal purity and reproducibility. In particular, when
-using Guix on a host distro that is not GuixSD, it is desirable to
-prevent access to @file{/usr/bin} and other system-wide resources from
-the development environment. For example, the following command spawns
-a Guile REPL in a ``container'' where only the store and the current
-working directory are mounted:
+Sometimes the upstream name differs from the package name used in Guix,
+and @command{guix refresh} needs a little help. Most updaters honor the
+@code{upstream-name} property in package definitions, which can be used
+to that effect:
@example
-guix environment --ad-hoc --container guile -- guile
+(define-public network-manager
+ (package
+ (name "network-manager")
+ ;; @dots{}
+ (properties '((upstream-name . "NetworkManager")))))
@end example
-@quotation Note
-The @code{--container} option requires Linux-libre 3.19 or newer.
-@end quotation
+When passed @code{--update}, it modifies distribution source files to
+update the version numbers and source tarball hashes of those package
+recipes (@pxref{Defining Packages}). This is achieved by downloading
+each package's latest source tarball and its associated OpenPGP
+signature, authenticating the downloaded tarball against its signature
+using @command{gpg}, and finally computing its hash. When the public
+key used to sign the tarball is missing from the user's keyring, an
+attempt is made to automatically retrieve it from a public key server;
+when this is successful, the key is added to the user's keyring; otherwise,
+@command{guix refresh} reports an error.
-The available options are summarized below.
+The following options are supported:
@table @code
-@item --root=@var{file}
-@itemx -r @var{file}
-@cindex persistent environment
-@cindex garbage collector root, for environments
-Make @var{file} a symlink to the profile for this environment, and
-register it as a garbage collector root.
-
-This is useful if you want to protect your environment from garbage
-collection, to make it ``persistent''.
-
-When this option is omitted, the environment is protected from garbage
-collection only for the duration of the @command{guix environment}
-session. This means that next time you recreate the same environment,
-you could have to rebuild or re-download packages. @xref{Invoking guix
-gc}, for more on GC roots.
@item --expression=@var{expr}
@itemx -e @var{expr}
-Create an environment for the package or list of packages that
-@var{expr} evaluates to.
+Consider the package @var{expr} evaluates to.
-For example, running:
+This is useful to precisely refer to a package, as in this example:
@example
-guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
+guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
@end example
-starts a shell with the environment for this specific variant of the
-PETSc package.
+This command lists the dependents of the ``final'' libc (essentially all
+the packages.)
-Running:
+@item --update
+@itemx -u
+Update distribution source files (package recipes) in place. This is
+usually run from a checkout of the Guix source tree (@pxref{Running
+Guix Before It Is Installed}):
@example
-guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
+$ ./pre-inst-env guix refresh -s non-core -u
@end example
-starts a shell with all the GuixSD base packages available.
+@xref{Defining Packages}, for more information on package definitions.
+
+@item --select=[@var{subset}]
+@itemx -s @var{subset}
+Select all the packages in @var{subset}, one of @code{core} or
+@code{non-core}.
-The above commands only use the default output of the given packages.
-To select other outputs, two element tuples can be specified:
+The @code{core} subset refers to all the packages at the core of the
+distribution---i.e., packages that are used to build ``everything
+else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
+changing one of these packages in the distribution entails a rebuild of
+all the others. Thus, such updates are an inconvenience to users in
+terms of build time or bandwidth used to achieve the upgrade.
+
+The @code{non-core} subset refers to the remaining packages. It is
+typically useful in cases where an update of the core packages would be
+inconvenient.
+
+@item --manifest=@var{file}
+@itemx -m @var{file}
+Select all the packages from the manifest in @var{file}. This is useful to
+check if any packages of the user manifest can be updated.
+
+@item --type=@var{updater}
+@itemx -t @var{updater}
+Select only packages handled by @var{updater} (may be a comma-separated
+list of updaters). Currently, @var{updater} may be one of:
+
+@table @code
+@item gnu
+the updater for GNU packages;
+@item gnome
+the updater for GNOME packages;
+@item kde
+the updater for KDE packages;
+@item xorg
+the updater for X.org packages;
+@item kernel.org
+the updater for packages hosted on kernel.org;
+@item elpa
+the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
+@item cran
+the updater for @uref{https://cran.r-project.org/, CRAN} packages;
+@item bioconductor
+the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
+@item cpan
+the updater for @uref{http://www.cpan.org/, CPAN} packages;
+@item pypi
+the updater for @uref{https://pypi.python.org, PyPI} packages.
+@item gem
+the updater for @uref{https://rubygems.org, RubyGems} packages.
+@item github
+the updater for @uref{https://github.com, GitHub} packages.
+@item hackage
+the updater for @uref{https://hackage.haskell.org, Hackage} packages.
+@item stackage
+the updater for @uref{https://www.stackage.org, Stackage} packages.
+@item crate
+the updater for @uref{https://crates.io, Crates} packages.
+@item launchpad
+the updater for @uref{https://launchpad.net, Launchpad} packages.
+@end table
+
+For instance, the following command only checks for updates of Emacs
+packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:
@example
-guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")'
+$ guix refresh --type=elpa,cran
+gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
+gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
@end example
-@item --load=@var{file}
-@itemx -l @var{file}
-Create an environment for the package or list of packages that the code
-within @var{file} evaluates to.
+@end table
-As an example, @var{file} might contain a definition like this
-(@pxref{Defining Packages}):
+In addition, @command{guix refresh} can be passed one or more package
+names, as in this example:
@example
-@verbatiminclude environment-gdb.scm
+$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8
@end example
-@item --manifest=@var{file}
-@itemx -m @var{file}
-Create an environment for the packages contained in the manifest object
-returned by the Scheme code in @var{file}.
+@noindent
+The command above specifically updates the @code{emacs} and
+@code{idutils} packages. The @code{--select} option would have no
+effect in this case.
-This is similar to the same-named option in @command{guix package}
-(@pxref{profile-manifest, @option{--manifest}}) and uses the same
-manifest files.
+When considering whether to upgrade a package, it is sometimes
+convenient to know which packages would be affected by the upgrade and
+should be checked for compatibility. For this the following option may
+be used when passing @command{guix refresh} one or more package names:
-@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
-useful for quickly creating an environment without having to write a
-package expression to contain the desired inputs.
+@table @code
-For instance, the command:
+@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
+end, display the fraction of packages covered by all these updaters.
+
+@item --list-dependent
+@itemx -l
+List top-level dependent packages that would need to be rebuilt as a
+result of upgrading one or more packages.
+
+@xref{Invoking guix graph, the @code{reverse-package} type of
+@command{guix graph}}, for information on how to visualize the list of
+dependents of a package.
+
+@end table
+
+Be aware that the @code{--list-dependent} option only
+@emph{approximates} the rebuilds that would be required as a result of
+an upgrade. More rebuilds might be required under some circumstances.
@example
-guix environment --ad-hoc guile guile-sdl -- guile
+$ guix refresh --list-dependent flex
+Building the following 120 packages would ensure 213 dependent packages are rebuilt:
+hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
@end example
-runs @command{guile} in an environment where Guile and Guile-SDL are
-available.
+The command above lists a set of packages that could be built to check
+for compatibility with an upgraded @code{flex} package.
-Note that this example implicitly asks for the default output of
-@code{guile} and @code{guile-sdl}, but it is possible to ask for a
-specific output---e.g., @code{glib:bin} asks for the @code{bin} output
-of @code{glib} (@pxref{Packages with Multiple Outputs}).
+@table @code
-This option may be composed with the default behavior of @command{guix
-environment}. Packages appearing before @code{--ad-hoc} are interpreted
-as packages whose dependencies will be added to the environment, the
-default behavior. Packages appearing after are interpreted as packages
-that will be added to the environment directly.
+@item --list-transitive
+List all the packages which one or more packages depend upon.
-@item --pure
-Unset existing environment variables when building the new environment.
-This has the effect of creating an environment in which search paths
-only contain package inputs.
+@example
+$ guix refresh --list-transitive flex
+flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6
+bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4 file@@5.33 @dots{}
+@end example
-@item --search-paths
-Display the environment variable definitions that make up the
-environment.
+@end table
-@item --system=@var{system}
-@itemx -s @var{system}
-Attempt to build for @var{system}---e.g., @code{i686-linux}.
+The command above lists a set of packages which, when changed, would cause
+@code{flex} to be rebuilt.
-@item --container
-@itemx -C
-@cindex container
-Run @var{command} within an isolated container. The current working
-directory outside the container is mapped inside the container.
-Additionally, unless overridden with @code{--user}, a dummy home
-directory is created that matches the current user's home directory, and
-@file{/etc/passwd} is configured accordingly. The spawned process runs
-as the current user outside the container, but has root privileges in
-the context of the container.
+The following options can be used to customize GnuPG operation:
-@item --network
-@itemx -N
-For containers, share the network namespace with the host system.
-Containers created without this flag only have access to the loopback
-device.
+@table @code
-@item --link-profile
-@itemx -P
-For containers, link the environment profile to
-@file{~/.guix-profile} within the container. This is equivalent to
-running the command @command{ln -s $GUIX_ENVIRONMENT ~/.guix-profile}
-within the container. Linking will fail and abort the environment if
-the directory already exists, which will certainly be the case if
-@command{guix environment} was invoked in the user's home directory.
+@item --gpg=@var{command}
+Use @var{command} as the GnuPG 2.x command. @var{command} is searched
+for in @code{$PATH}.
-Certain packages are configured to look in
-@code{~/.guix-profile} for configuration files and data;@footnote{For
-example, the @code{fontconfig} package inspects
-@file{~/.guix-profile/share/fonts} for additional fonts.}
-@code{--link-profile} allows these programs to behave as expected within
-the environment.
+@item --keyring=@var{file}
+Use @var{file} as the keyring for upstream keys. @var{file} must be in the
+@dfn{keybox format}. Keybox files usually have a name ending in @file{.kbx}
+and the GNU@tie{}Privacy Guard (GPG) can manipulate these files
+(@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, for
+information on a tool to manipulate keybox files).
-@item --user=@var{user}
-@itemx -u @var{user}
-For containers, use the username @var{user} in place of the current
-user. The generated @file{/etc/passwd} entry within the container will
-contain the name @var{user}; the home directory will be
-@file{/home/USER}; and no user GECOS data will be copied. @var{user}
-need not exist on the system.
+When this option is omitted, @command{guix refresh} uses
+@file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream
+signing keys. OpenPGP signatures are checked against keys from this keyring;
+missing keys are downloaded to this keyring as well (see
+@option{--key-download} below.)
-Additionally, any shared or exposed path (see @code{--share} and
-@code{--expose} respectively) whose target is within the current user's
-home directory will be remapped relative to @file{/home/USER}; this
-includes the automatic mapping of the current working directory.
+You can export keys from your default GPG keyring into a keybox file using
+commands like this one:
+
+@example
+gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx
+@end example
+
+Likewise, you can fetch keys to a specific keybox file like this:
@example
-# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
-cd $HOME/wd
-guix environment --container --user=foo \
- --expose=$HOME/test \
- --expose=/tmp/target=$HOME/target
+gpg --no-default-keyring --keyring mykeyring.kbx \
+ --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example
-While this will limit the leaking of user identity through home paths
-and each of the user fields, this is only one useful component of a
-broader privacy/anonymity solution---not one in and of itself.
+@ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
+Privacy Guard}, for more information on GPG's @option{--keyring} option.
-@item --expose=@var{source}[=@var{target}]
-For containers, expose the file system @var{source} from the host system
-as the read-only file system @var{target} within the container. If
-@var{target} is not specified, @var{source} is used as the target mount
-point in the container.
+@item --key-download=@var{policy}
+Handle missing OpenPGP keys according to @var{policy}, which may be one
+of:
-The example below spawns a Guile REPL in a container in which the user's
-home directory is accessible read-only via the @file{/exchange}
-directory:
+@table @code
+@item always
+Always download missing OpenPGP keys from the key server, and add them
+to the user's GnuPG keyring.
-@example
-guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
-@end example
+@item never
+Never try to download missing OpenPGP keys. Instead just bail out.
-@item --share=@var{source}[=@var{target}]
-For containers, share the file system @var{source} from the host system
-as the writable file system @var{target} within the container. If
-@var{target} is not specified, @var{source} is used as the target mount
-point in the container.
+@item interactive
+When a package signed with an unknown OpenPGP key is encountered, ask
+the user whether to download it or not. This is the default behavior.
+@end table
-The example below spawns a Guile REPL in a container in which the user's
-home directory is accessible for both reading and writing via the
-@file{/exchange} directory:
+@item --key-server=@var{host}
+Use @var{host} as the OpenPGP key server when importing a public key.
-@example
-guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile
-@end example
@end table
-@command{guix environment}
-also supports all of the common build options that @command{guix
-build} supports (@pxref{Common Build Options}) as well as package
-transformation options (@pxref{Package Transformation Options}).
+The @code{github} updater uses the
+@uref{https://developer.github.com/v3/, GitHub API} to query for new
+releases. When used repeatedly e.g.@: when refreshing all packages,
+GitHub will eventually refuse to answer any further API requests. By
+default 60 API requests per hour are allowed, and a full refresh on all
+GitHub packages in Guix requires more than this. Authentication with
+GitHub through the use of an API token alleviates these limits. To use
+an API token, set the environment variable @code{GUIX_GITHUB_TOKEN} to a
+token procured from @uref{https://github.com/settings/tokens} or
+otherwise.
-@node Invoking guix publish
-@section Invoking @command{guix publish}
+@node Invoking guix lint
+@section Invoking @command{guix lint}
-@cindex @command{guix publish}
-The purpose of @command{guix publish} is to enable users to easily share
-their store with others, who can then use it as a substitute server
-(@pxref{Substitutes}).
+@cindex @command{guix lint}
+@cindex package, checking for errors
+The @command{guix lint} command is meant to help package developers avoid
+common errors and use a consistent style. It runs a number of checks on
+a given set of packages in order to find common mistakes in their
+definitions. Available @dfn{checkers} include (see
+@code{--list-checkers} for a complete list):
-When @command{guix publish} runs, it spawns an HTTP server which allows
-anyone with network access to obtain substitutes from it. This means
-that any machine running Guix can also act as if it were a build farm,
-since the HTTP interface is compatible with Hydra, the software behind
-the @code{@value{SUBSTITUTE-SERVER}} build farm.
+@table @code
+@item synopsis
+@itemx description
+Validate certain typographical and stylistic rules about package
+descriptions and synopses.
-For security, each substitute is signed, allowing recipients to check
-their authenticity and integrity (@pxref{Substitutes}). Because
-@command{guix publish} uses the signing key of the system, which is only
-readable by the system administrator, it must be started as root; the
-@code{--user} option makes it drop root privileges early on.
+@item inputs-should-be-native
+Identify inputs that should most likely be native inputs.
-The signing key pair must be generated before @command{guix publish} is
-launched, using @command{guix archive --generate-key} (@pxref{Invoking
-guix archive}).
+@item source
+@itemx home-page
+@itemx mirror-url
+@itemx github-url
+@itemx source-file-name
+Probe @code{home-page} and @code{source} URLs and report those that are
+invalid. Suggest a @code{mirror://} URL when applicable. If the
+@code{source} URL redirects to a GitHub URL, recommend usage of the GitHub
+URL. Check that the source file name is meaningful, e.g.@: is not just a
+version number or ``git-checkout'', without a declared @code{file-name}
+(@pxref{origin Reference}).
-The general syntax is:
+@item source-unstable-tarball
+Parse the @code{source} URL to determine if a tarball from GitHub is
+autogenerated or if it is a release tarball. Unfortunately GitHub's
+autogenerated tarballs are sometimes regenerated.
-@example
-guix publish @var{options}@dots{}
-@end example
+@item cve
+@cindex security vulnerabilities
+@cindex CVE, Common Vulnerabilities and Exposures
+Report known vulnerabilities found in the Common Vulnerabilities and
+Exposures (CVE) databases of the current and past year
+@uref{https://nvd.nist.gov/download.cfm#CVE_FEED, published by the US
+NIST}.
-Running @command{guix publish} without any additional arguments will
-spawn an HTTP server on port 8080:
+To view information about a particular vulnerability, visit pages such as:
+
+@itemize
+@item
+@indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
+@item
+@indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
+@end itemize
+
+@noindent
+where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
+@code{CVE-2015-7554}.
+
+Package developers can specify in package recipes the
+@uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)}
+name and version of the package when they differ from the name or version
+that Guix uses, as in this example:
@example
-guix publish
+(package
+ (name "grub")
+ ;; @dots{}
+ ;; CPE calls this package "grub2".
+ (properties '((cpe-name . "grub2")
+ (cpe-version . "2.3")))
@end example
-Once a publishing server has been authorized (@pxref{Invoking guix
-archive}), the daemon may download substitutes from it:
+@c See <http://www.openwall.com/lists/oss-security/2017/03/15/3>.
+Some entries in the CVE database do not specify which version of a
+package they apply to, and would thus ``stick around'' forever. Package
+developers who found CVE alerts and verified they can be ignored can
+declare them as in this example:
@example
-guix-daemon --substitute-urls=http://example.org:8080
+(package
+ (name "t1lib")
+ ;; @dots{}
+ ;; These CVEs no longer apply and can be safely ignored.
+ (properties `((lint-hidden-cve . ("CVE-2011-0433"
+ "CVE-2011-1553"
+ "CVE-2011-1554"
+ "CVE-2011-5244")))))
@end example
-By default, @command{guix publish} compresses archives on the fly as it
-serves them. This ``on-the-fly'' mode is convenient in that it requires
-no setup and is immediately available. However, when serving lots of
-clients, we recommend using the @option{--cache} option, which enables
-caching of the archives before they are sent to clients---see below for
-details. The @command{guix weather} command provides a handy way to
-check what a server provides (@pxref{Invoking guix weather}).
+@item formatting
+Warn about obvious source code formatting issues: trailing white space,
+use of tabulations, etc.
+@end table
-As a bonus, @command{guix publish} also serves as a content-addressed
-mirror for source files referenced in @code{origin} records
-(@pxref{origin Reference}). For instance, assuming @command{guix
-publish} is running on @code{example.org}, the following URL returns the
-raw @file{hello-2.10.tar.gz} file with the given SHA256 hash
-(represented in @code{nix-base32} format, @pxref{Invoking guix hash}):
+The general syntax is:
@example
-http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i
+guix lint @var{options} @var{package}@dots{}
@end example
-Obviously, these URLs only work for files that are in the store; in
-other cases, they return 404 (``Not Found'').
+If no package is given on the command line, then all packages are checked.
+The @var{options} may be zero or more of the following:
-@cindex build logs, publication
-Build logs are available from @code{/log} URLs like:
+@table @code
+@item --list-checkers
+@itemx -l
+List and describe all the available checkers that will be run on packages
+and exit.
-@example
-http://example.org/log/gwspk@dots{}-guile-2.2.3
-@end example
+@item --checkers
+@itemx -c
+Only enable the checkers specified in a comma-separated list using the
+names returned by @code{--list-checkers}.
-@noindent
-When @command{guix-daemon} is configured to save compressed build logs,
-as is the case by default (@pxref{Invoking guix-daemon}), @code{/log}
-URLs return the compressed log as-is, with an appropriate
-@code{Content-Type} and/or @code{Content-Encoding} header. We recommend
-running @command{guix-daemon} with @code{--log-compression=gzip} since
-Web browsers can automatically decompress it, which is not the case with
-bzip2 compression.
+@end table
-The following options are available:
+@node Invoking guix size
+@section Invoking @command{guix size}
-@table @code
-@item --port=@var{port}
-@itemx -p @var{port}
-Listen for HTTP requests on @var{port}.
+@cindex size
+@cindex package size
+@cindex closure
+@cindex @command{guix size}
+The @command{guix size} command helps package developers profile the
+disk usage of packages. It is easy to overlook the impact of an
+additional dependency added to a package, or the impact of using a
+single output for a package that could easily be split (@pxref{Packages
+with Multiple Outputs}). Such are the typical issues that
+@command{guix size} can highlight.
+
+The command can be passed one or more package specifications
+such as @code{gcc@@4.8}
+or @code{guile:debug}, or a file name in the store. Consider this
+example:
+
+@example
+$ guix size coreutils
+store item total self
+/gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
+/gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
+/gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
+/gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
+/gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
+/gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
+/gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
+/gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
+total: 78.9 MiB
+@end example
+
+@cindex closure
+The store items listed here constitute the @dfn{transitive closure} of
+Coreutils---i.e., Coreutils and all its dependencies, recursively---as
+would be returned by:
-@item --listen=@var{host}
-Listen on the network interface for @var{host}. The default is to
-accept connections from any interface.
+@example
+$ guix gc -R /gnu/store/@dots{}-coreutils-8.23
+@end example
-@item --user=@var{user}
-@itemx -u @var{user}
-Change privileges to @var{user} as soon as possible---i.e., once the
-server socket is open and the signing key has been read.
+Here the output shows three columns next to store items. The first column,
+labeled ``total'', shows the size in mebibytes (MiB) of the closure of
+the store item---that is, its own size plus the size of all its
+dependencies. The next column, labeled ``self'', shows the size of the
+item itself. The last column shows the ratio of the size of the item
+itself to the space occupied by all the items listed here.
-@item --compression[=@var{level}]
-@itemx -C [@var{level}]
-Compress data using the given @var{level}. When @var{level} is zero,
-disable compression. The range 1 to 9 corresponds to different gzip
-compression levels: 1 is the fastest, and 9 is the best (CPU-intensive).
-The default is 3.
+In this example, we see that the closure of Coreutils weighs in at
+79@tie{}MiB, most of which is taken by libc and GCC's run-time support
+libraries. (That libc and GCC's libraries represent a large fraction of
+the closure is not a problem @i{per se} because they are always available
+on the system anyway.)
-Unless @option{--cache} is used, compression occurs on the fly and
-the compressed streams are not
-cached. Thus, to reduce load on the machine that runs @command{guix
-publish}, it may be a good idea to choose a low compression level, to
-run @command{guix publish} behind a caching proxy, or to use
-@option{--cache}. Using @option{--cache} has the advantage that it
-allows @command{guix publish} to add @code{Content-Length} HTTP header
-to its responses.
+When the package(s) passed to @command{guix size} are available in the
+store@footnote{More precisely, @command{guix size} looks for the
+@emph{ungrafted} variant of the given package(s), as returned by
+@code{guix build @var{package} --no-grafts}. @xref{Security Updates},
+for information on grafts.}, @command{guix size} queries the daemon to determine its
+dependencies, and measures its size in the store, similar to @command{du
+-ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
+Coreutils}).
-@item --cache=@var{directory}
-@itemx -c @var{directory}
-Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory}
-and only serve archives that are in cache.
+When the given packages are @emph{not} in the store, @command{guix size}
+reports information based on the available substitutes
+(@pxref{Substitutes}). This makes it possible it to profile disk usage of
+store items that are not even on disk, only available remotely.
-When this option is omitted, archives and meta-data are created
-on-the-fly. This can reduce the available bandwidth, especially when
-compression is enabled, since this may become CPU-bound. Another
-drawback of the default mode is that the length of archives is not known
-in advance, so @command{guix publish} does not add a
-@code{Content-Length} HTTP header to its responses, which in turn
-prevents clients from knowing the amount of data being downloaded.
+You can also specify several package names:
-Conversely, when @option{--cache} is used, the first request for a store
-item (@i{via} a @code{.narinfo} URL) returns 404 and triggers a
-background process to @dfn{bake} the archive---computing its
-@code{.narinfo} and compressing the archive, if needed. Once the
-archive is cached in @var{directory}, subsequent requests succeed and
-are served directly from the cache, which guarantees that clients get
-the best possible bandwidth.
+@example
+$ guix size coreutils grep sed bash
+store item total self
+/gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4%
+/gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8%
+/gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6%
+/gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2%
+@dots{}
+total: 102.3 MiB
+@end example
-The ``baking'' process is performed by worker threads. By default, one
-thread per CPU core is created, but this can be customized. See
-@option{--workers} below.
+@noindent
+In this example we see that the combination of the four packages takes
+102.3@tie{}MiB in total, which is much less than the sum of each closure
+since they have a lot of dependencies in common.
-When @option{--ttl} is used, cached entries are automatically deleted
-when they have expired.
+The available options are:
-@item --workers=@var{N}
-When @option{--cache} is used, request the allocation of @var{N} worker
-threads to ``bake'' archives.
+@table @option
-@item --ttl=@var{ttl}
-Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
-(TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5
-days, @code{1m} means 1 month, and so on.
+@item --substitute-urls=@var{urls}
+Use substitute information from @var{urls}.
+@xref{client-substitute-urls, the same option for @code{guix build}}.
-This allows the user's Guix to keep substitute information in cache for
-@var{ttl}. However, note that @code{guix publish} does not itself
-guarantee that the store items it provides will indeed remain available
-for as long as @var{ttl}.
+@item --sort=@var{key}
+Sort lines according to @var{key}, one of the following options:
-Additionally, when @option{--cache} is used, cached entries that have
-not been accessed for @var{ttl} and that no longer have a corresponding
-item in the store, may be deleted.
+@table @code
+@item self
+the size of each item (the default);
+@item closure
+the total size of the item's closure.
+@end table
-@item --nar-path=@var{path}
-Use @var{path} as the prefix for the URLs of ``nar'' files
-(@pxref{Invoking guix archive, normalized archives}).
+@item --map-file=@var{file}
+Write a graphical map of disk usage in PNG format to @var{file}.
-By default, nars are served at a URL such as
-@code{/nar/gzip/@dots{}-coreutils-8.25}. This option allows you to
-change the @code{/nar} part to @var{path}.
+For the example above, the map looks like this:
-@item --public-key=@var{file}
-@itemx --private-key=@var{file}
-Use the specific @var{file}s as the public/private key pair used to sign
-the store items being published.
+@image{images/coreutils-size-map,5in,, map of Coreutils disk usage
+produced by @command{guix size}}
-The files must correspond to the same key pair (the private key is used
-for signing and the public key is merely advertised in the signature
-metadata). They must contain keys in the canonical s-expression format
-as produced by @command{guix archive --generate-key} (@pxref{Invoking
-guix archive}). By default, @file{/etc/guix/signing-key.pub} and
-@file{/etc/guix/signing-key.sec} are used.
+This option requires that
+@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be
+installed and visible in Guile's module search path. When that is not
+the case, @command{guix size} fails as it tries to load it.
-@item --repl[=@var{port}]
-@itemx -r [@var{port}]
-Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
-Reference Manual}) on @var{port} (37146 by default). This is used
-primarily for debugging a running @command{guix publish} server.
-@end table
+@item --system=@var{system}
+@itemx -s @var{system}
+Consider packages for @var{system}---e.g., @code{x86_64-linux}.
-Enabling @command{guix publish} on a GuixSD system is a one-liner: just
-instantiate a @code{guix-publish-service-type} service in the @code{services} field
-of the @code{operating-system} declaration (@pxref{guix-publish-service-type,
-@code{guix-publish-service-type}}).
+@end table
-If you are instead running Guix on a ``foreign distro'', follow these
-instructions:”
+@node Invoking guix graph
+@section Invoking @command{guix graph}
-@itemize
-@item
-If your host distro uses the systemd init system:
+@cindex DAG
+@cindex @command{guix graph}
+@cindex package dependencies
+Packages and their dependencies form a @dfn{graph}, specifically a
+directed acyclic graph (DAG). It can quickly become difficult to have a
+mental model of the package DAG, so the @command{guix graph} command
+provides a visual representation of the DAG. By default,
+@command{guix graph} emits a DAG representation in the input format of
+@uref{http://www.graphviz.org/, Graphviz}, so its output can be passed
+directly to the @command{dot} command of Graphviz. It can also emit an
+HTML page with embedded JavaScript code to display a ``chord diagram''
+in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
+emit Cypher queries to construct a graph in a graph database supporting
+the @uref{http://www.opencypher.org/, openCypher} query language.
+The general syntax is:
@example
-# ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
- /etc/systemd/system/
-# systemctl start guix-publish && systemctl enable guix-publish
+guix graph @var{options} @var{package}@dots{}
@end example
-@item
-If your host distro uses the Upstart init system:
+For example, the following command generates a PDF file representing the
+package DAG for the GNU@tie{}Core Utilities, showing its build-time
+dependencies:
@example
-# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
-# start guix-publish
+guix graph coreutils | dot -Tpdf > dag.pdf
@end example
-@item
-Otherwise, proceed similarly with your distro's init system.
-@end itemize
-
-@node Invoking guix challenge
-@section Invoking @command{guix challenge}
+The output looks like this:
-@cindex reproducible builds
-@cindex verifiable builds
-@cindex @command{guix challenge}
-@cindex challenge
-Do the binaries provided by this server really correspond to the source
-code it claims to build? Is a package build process deterministic?
-These are the questions the @command{guix challenge} command attempts to
-answer.
+@image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
-The former is obviously an important question: Before using a substitute
-server (@pxref{Substitutes}), one had better @emph{verify} that it
-provides the right binaries, and thus @emph{challenge} it. The latter
-is what enables the former: If package builds are deterministic, then
-independent builds of the package should yield the exact same result,
-bit for bit; if a server provides a binary different from the one
-obtained locally, it may be either corrupt or malicious.
+Nice little graph, no?
-We know that the hash that shows up in @file{/gnu/store} file names is
-the hash of all the inputs of the process that built the file or
-directory---compilers, libraries, build scripts,
-etc. (@pxref{Introduction}). Assuming deterministic build processes,
-one store file name should map to exactly one build output.
-@command{guix challenge} checks whether there is, indeed, a single
-mapping by comparing the build outputs of several independent builds of
-any given store item.
+But there is more than one graph! The one above is concise: it is the
+graph of package objects, omitting implicit inputs such as GCC, libc,
+grep, etc. It is often useful to have such a concise graph, but
+sometimes one may want to see more details. @command{guix graph} supports
+several types of graphs, allowing you to choose the level of detail:
-The command output looks like this:
+@table @code
+@item package
+This is the default type used in the example above. It shows the DAG of
+package objects, excluding implicit dependencies. It is concise, but
+filters out many details.
-@smallexample
-$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org"
-updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 100.0%
-updating list of substitutes from 'https://guix.example.org'... 100.0%
-/gnu/store/@dots{}-openssl-1.0.2d contents differ:
- local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
- https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
- https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
-/gnu/store/@dots{}-git-2.5.0 contents differ:
- local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
- https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
- https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
-/gnu/store/@dots{}-pius-2.1.1 contents differ:
- local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
- https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
- https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
+@item reverse-package
+This shows the @emph{reverse} DAG of packages. For example:
-@dots{}
+@example
+guix graph --type=reverse-package ocaml
+@end example
-6,406 store items were analyzed:
- - 4,749 (74.1%) were identical
- - 525 (8.2%) differed
- - 1,132 (17.7%) were inconclusive
-@end smallexample
+...@: yields the graph of packages that @emph{explicitly} depend on OCaml (if
+you are also interested in cases where OCaml is an implicit dependency, see
+@code{reverse-bag} below.)
-@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.
+Note that for core packages this can yield huge graphs. If all you want
+is to know the number of packages that depend on a given package, use
+@command{guix refresh --list-dependent} (@pxref{Invoking guix refresh,
+@option{--list-dependent}}).
-@cindex non-determinism, in package builds
-As an example, @code{guix.example.org} always gets a different answer.
-Conversely, @code{@value{SUBSTITUTE-SERVER}} agrees with local builds, except in the
-case of Git. This might indicate that the build process of Git is
-non-deterministic, meaning that its output varies as a function of
-various things that Guix does not fully control, in spite of building
-packages in isolated environments (@pxref{Features}). Most common
-sources of non-determinism include the addition of timestamps in build
-results, the inclusion of random numbers, and directory listings sorted
-by inode number. See @uref{https://reproducible-builds.org/docs/}, for
-more information.
+@item bag-emerged
+This is the package DAG, @emph{including} implicit inputs.
-To find out what is wrong with this Git binary, we can do something along
-these lines (@pxref{Invoking guix archive}):
+For instance, the following command:
@example
-$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \
- | guix archive -x /tmp/git
-$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
+guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf
@end example
-This command shows the difference between the files resulting from the
-local build, and the files resulting from the build on
-@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging Files,,
-diffutils, Comparing and Merging Files}). The @command{diff} command
-works great for text files. When binary files differ, a better option
-is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
-visualize differences for all kinds of files.
+...@: yields this bigger graph:
-Once you have done that work, you can tell whether the differences are due
-to a non-deterministic build process or to a malicious server. We try
-hard to remove sources of non-determinism in packages to make it easier
-to verify substitutes, but of course, this is a process that
-involves not just Guix, but a large part of the free software community.
-In the meantime, @command{guix challenge} is one tool to help address
-the problem.
+@image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils}
-If you are writing packages for Guix, you are encouraged to check
-whether @code{@value{SUBSTITUTE-SERVER}} and other substitute servers obtain the
-same build result as you did with:
+At the bottom of the graph, we see all the implicit inputs of
+@var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}).
+
+Now, note that the dependencies of these implicit inputs---that is, the
+@dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown
+here, for conciseness.
+
+@item bag
+Similar to @code{bag-emerged}, but this time including all the bootstrap
+dependencies.
+
+@item bag-with-origins
+Similar to @code{bag}, but also showing origins and their dependencies.
+
+@item reverse-bag
+This shows the @emph{reverse} DAG of packages. Unlike @code{reverse-package},
+it also takes implicit dependencies into account. For example:
@example
-$ guix challenge @var{package}
+guix graph -t reverse-bag dune
@end example
@noindent
-where @var{package} is a package specification such as
-@code{guile@@2.0} or @code{glibc:debug}.
+...@: yields the graph of all packages that depend on Dune, directly or
+indirectly. Since Dune is an @emph{implicit} dependency of many packages
+@i{via} @code{dune-build-system}, this shows a large number of packages,
+whereas @code{reverse-package} would show very few if any.
-The general syntax is:
+@item derivation
+This is the most detailed representation: It shows the DAG of
+derivations (@pxref{Derivations}) and plain store items. Compared to
+the above representation, many additional nodes are visible, including
+build scripts, patches, Guile modules, etc.
+
+For this type of graph, it is also possible to pass a @file{.drv} file
+name instead of a package name, as in:
@example
-guix challenge @var{options} [@var{packages}@dots{}]
+guix graph -t derivation `guix system build -d my-config.scm`
@end example
-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
-its exit code is 2 (other non-zero exit codes denote other kinds of
-errors.)
+@item module
+This is the graph of @dfn{package modules} (@pxref{Package Modules}).
+For example, the following command shows the graph for the package
+module that defines the @code{guile} package:
-The one option that matters is:
+@example
+guix graph -t module guile | dot -Tpdf > module-graph.pdf
+@end example
+@end table
+
+All the types above correspond to @emph{build-time dependencies}. The
+following graph type represents the @emph{run-time dependencies}:
@table @code
+@item references
+This is the graph of @dfn{references} of a package output, as returned
+by @command{guix gc --references} (@pxref{Invoking guix gc}).
-@item --substitute-urls=@var{urls}
-Consider @var{urls} the whitespace-separated list of substitute source
-URLs to compare to.
+If the given package output is not available in the store, @command{guix
+graph} attempts to obtain dependency information from substitutes.
-@item --verbose
-@itemx -v
-Show details about matches (identical contents) in addition to
-information about mismatches.
+Here you can also pass a store file name instead of a package name. For
+example, the command below produces the reference graph of your profile
+(which can be big!):
-@end table
+@example
+guix graph -t references `readlink -f ~/.guix-profile`
+@end example
-@node Invoking guix copy
-@section Invoking @command{guix copy}
+@item referrers
+This is the graph of the @dfn{referrers} of a store item, as returned by
+@command{guix gc --referrers} (@pxref{Invoking guix gc}).
-@cindex copy, of store items, over SSH
-@cindex SSH, copy of store items
-@cindex sharing store items across machines
-@cindex transferring store items across machines
-The @command{guix copy} command copies items from the store of one
-machine to that of another machine over a secure shell (SSH)
-connection@footnote{This command is available only when Guile-SSH was
-found. @xref{Requirements}, for details.}. For example, the following
-command copies the @code{coreutils} package, the user's profile, and all
-their dependencies over to @var{host}, logged in as @var{user}:
+This relies exclusively on local information from your store. For
+instance, let us suppose that the current Inkscape is available in 10
+profiles on your machine; @command{guix graph -t referrers inkscape}
+will show a graph rooted at Inkscape and with those 10 profiles linked
+to it.
-@example
-guix copy --to=@var{user}@@@var{host} \
- coreutils `readlink -f ~/.guix-profile`
-@end example
+It can help determine what is preventing a store item from being garbage
+collected.
-If some of the items to be copied are already present on @var{host},
-they are not actually sent.
+@end table
-The command below retrieves @code{libreoffice} and @code{gimp} from
-@var{host}, assuming they are available there:
+The available options are the following:
-@example
-guix copy --from=@var{host} libreoffice gimp
-@end example
+@table @option
+@item --type=@var{type}
+@itemx -t @var{type}
+Produce a graph output of @var{type}, where @var{type} must be one of
+the values listed above.
-The SSH connection is established using the Guile-SSH client, which is
-compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
-@file{~/.ssh/config}, and uses the SSH agent for authentication.
+@item --list-types
+List the supported graph types.
-The key used to sign items that are sent must be accepted by the remote
-machine. Likewise, the key used by the remote machine to sign items you
-are retrieving must be in @file{/etc/guix/acl} so it is accepted by your
-own daemon. @xref{Invoking guix archive}, for more information about
-store item authentication.
+@item --backend=@var{backend}
+@itemx -b @var{backend}
+Produce a graph using the selected @var{backend}.
-The general syntax is:
+@item --list-backends
+List the supported graph backends.
+
+Currently, the available backends are Graphviz and d3.js.
+
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Consider the package @var{expr} evaluates to.
+
+This is useful to precisely refer to a package, as in this example:
@example
-guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
+guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
@end example
-You must always specify one of the following options:
+@item --system=@var{system}
+@itemx -s @var{system}
+Display the graph for @var{system}---e.g., @code{i686-linux}.
-@table @code
-@item --to=@var{spec}
-@itemx --from=@var{spec}
-Specify the host to send to or receive from. @var{spec} must be an SSH
-spec such as @code{example.org}, @code{charlie@@example.org}, or
-@code{charlie@@example.org:2222}.
+The package dependency graph is largely architecture-independent, but there
+are some architecture-dependent bits that this option allows you to visualize.
@end table
-The @var{items} can be either package names, such as @code{gimp}, or
-store items, such as @file{/gnu/store/@dots{}-idutils-4.6}.
-When specifying the name of a package to send, it is first built if
-needed, unless @option{--dry-run} was specified. Common build options
-are supported (@pxref{Common Build Options}).
+@node Invoking guix publish
+@section Invoking @command{guix publish}
-@node Invoking guix container
-@section Invoking @command{guix container}
-@cindex container
-@cindex @command{guix container}
-@quotation Note
-As of version @value{VERSION}, this tool is experimental. The interface
-is subject to radical change in the future.
-@end quotation
+@cindex @command{guix publish}
+The purpose of @command{guix publish} is to enable users to easily share
+their store with others, who can then use it as a substitute server
+(@pxref{Substitutes}).
-The purpose of @command{guix container} is to manipulate processes
-running within an isolated environment, commonly known as a
-``container'', typically created by the @command{guix environment}
-(@pxref{Invoking guix environment}) and @command{guix system container}
-(@pxref{Invoking guix system}) commands.
+When @command{guix publish} runs, it spawns an HTTP server which allows
+anyone with network access to obtain substitutes from it. This means
+that any machine running Guix can also act as if it were a build farm,
+since the HTTP interface is compatible with Hydra, the software behind
+the @code{@value{SUBSTITUTE-SERVER}} build farm.
+
+For security, each substitute is signed, allowing recipients to check
+their authenticity and integrity (@pxref{Substitutes}). Because
+@command{guix publish} uses the signing key of the system, which is only
+readable by the system administrator, it must be started as root; the
+@code{--user} option makes it drop root privileges early on.
+
+The signing key pair must be generated before @command{guix publish} is
+launched, using @command{guix archive --generate-key} (@pxref{Invoking
+guix archive}).
The general syntax is:
@example
-guix container @var{action} @var{options}@dots{}
+guix publish @var{options}@dots{}
@end example
-@var{action} specifies the operation to perform with a container, and
-@var{options} specifies the context-specific arguments for the action.
+Running @command{guix publish} without any additional arguments will
+spawn an HTTP server on port 8080:
-The following actions are available:
+@example
+guix publish
+@end example
-@table @code
-@item exec
-Execute a command within the context of a running container.
+Once a publishing server has been authorized (@pxref{Invoking guix
+archive}), the daemon may download substitutes from it:
+
+@example
+guix-daemon --substitute-urls=http://example.org:8080
+@end example
+
+By default, @command{guix publish} compresses archives on the fly as it
+serves them. This ``on-the-fly'' mode is convenient in that it requires
+no setup and is immediately available. However, when serving lots of
+clients, we recommend using the @option{--cache} option, which enables
+caching of the archives before they are sent to clients---see below for
+details. The @command{guix weather} command provides a handy way to
+check what a server provides (@pxref{Invoking guix weather}).
-The syntax is:
+As a bonus, @command{guix publish} also serves as a content-addressed
+mirror for source files referenced in @code{origin} records
+(@pxref{origin Reference}). For instance, assuming @command{guix
+publish} is running on @code{example.org}, the following URL returns the
+raw @file{hello-2.10.tar.gz} file with the given SHA256 hash
+(represented in @code{nix-base32} format, @pxref{Invoking guix hash}):
@example
-guix container exec @var{pid} @var{program} @var{arguments}@dots{}
+http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i
@end example
-@var{pid} specifies the process ID of the running container.
-@var{program} specifies an executable file name within the root file
-system of the container. @var{arguments} are the additional options that
-will be passed to @var{program}.
+Obviously, these URLs only work for files that are in the store; in
+other cases, they return 404 (``Not Found'').
-The following command launches an interactive login shell inside a
-GuixSD container, started by @command{guix system container}, and whose
-process ID is 9001:
+@cindex build logs, publication
+Build logs are available from @code{/log} URLs like:
@example
-guix container exec 9001 /run/current-system/profile/bin/bash --login
+http://example.org/log/gwspk@dots{}-guile-2.2.3
@end example
-Note that the @var{pid} cannot be the parent process of a container. It
-must be PID 1 of the container or one of its child processes.
+@noindent
+When @command{guix-daemon} is configured to save compressed build logs,
+as is the case by default (@pxref{Invoking guix-daemon}), @code{/log}
+URLs return the compressed log as-is, with an appropriate
+@code{Content-Type} and/or @code{Content-Encoding} header. We recommend
+running @command{guix-daemon} with @code{--log-compression=gzip} since
+Web browsers can automatically decompress it, which is not the case with
+bzip2 compression.
-@end table
+The following options are available:
-@node Invoking guix weather
-@section Invoking @command{guix weather}
+@table @code
+@item --port=@var{port}
+@itemx -p @var{port}
+Listen for HTTP requests on @var{port}.
-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
-specified servers so you can have an idea of whether you'll be grumpy
-today. It can sometimes be useful info as a user, but it is primarily
-useful to people running @command{guix publish} (@pxref{Invoking guix
-publish}).
+@item --listen=@var{host}
+Listen on the network interface for @var{host}. The default is to
+accept connections from any interface.
-@cindex statistics, for substitutes
-@cindex availability of substitutes
-@cindex substitute availability
-@cindex weather, substitute availability
-Here's a sample run:
+@item --user=@var{user}
+@itemx -u @var{user}
+Change privileges to @var{user} as soon as possible---i.e., once the
+server socket is open and the signing key has been read.
-@example
-$ 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%
-https://guix.example.org
- 43.4% substitutes available (2,658 out of 6,128)
- 7,032.5 MiB of nars (compressed)
- 19,824.2 MiB on disk (uncompressed)
- 0.030 seconds per request (182.9 seconds in total)
- 33.5 requests per second
+@item --compression[=@var{level}]
+@itemx -C [@var{level}]
+Compress data using the given @var{level}. When @var{level} is zero,
+disable compression. The range 1 to 9 corresponds to different gzip
+compression levels: 1 is the fastest, and 9 is the best (CPU-intensive).
+The default is 3.
- 9.8% (342 out of 3,470) of the missing items are queued
- 867 queued builds
- x86_64-linux: 518 (59.7%)
- i686-linux: 221 (25.5%)
- aarch64-linux: 128 (14.8%)
- build rate: 23.41 builds per hour
- x86_64-linux: 11.16 builds per hour
- i686-linux: 6.03 builds per hour
- aarch64-linux: 6.41 builds per hour
-@end example
+Unless @option{--cache} is used, compression occurs on the fly and
+the compressed streams are not
+cached. Thus, to reduce load on the machine that runs @command{guix
+publish}, it may be a good idea to choose a low compression level, to
+run @command{guix publish} behind a caching proxy, or to use
+@option{--cache}. Using @option{--cache} has the advantage that it
+allows @command{guix publish} to add @code{Content-Length} HTTP header
+to its responses.
-@cindex continuous integration, statistics
-As you can see, it reports the fraction of all the packages for which
-substitutes are available on the server---regardless of whether
-substitutes are enabled, and regardless of whether this server's signing
-key is authorized. It also reports the size of the compressed archives
-(``nars'') provided by the server, the size the corresponding store
-items occupy in the store (assuming deduplication is turned off), and
-the server's throughput. The second part gives continuous integration
-(CI) statistics, if the server supports it.
+@item --cache=@var{directory}
+@itemx -c @var{directory}
+Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory}
+and only serve archives that are in cache.
-To achieve that, @command{guix weather} queries over HTTP(S) meta-data
-(@dfn{narinfos}) for all the relevant store items. Like @command{guix
-challenge}, it ignores signatures on those substitutes, which is
-innocuous since the command only gathers statistics and cannot install
-those substitutes.
+When this option is omitted, archives and meta-data are created
+on-the-fly. This can reduce the available bandwidth, especially when
+compression is enabled, since this may become CPU-bound. Another
+drawback of the default mode is that the length of archives is not known
+in advance, so @command{guix publish} does not add a
+@code{Content-Length} HTTP header to its responses, which in turn
+prevents clients from knowing the amount of data being downloaded.
-Among other things, it is possible to query specific system types and
-specific package sets. The available options are listed below.
+Conversely, when @option{--cache} is used, the first request for a store
+item (@i{via} a @code{.narinfo} URL) returns 404 and triggers a
+background process to @dfn{bake} the archive---computing its
+@code{.narinfo} and compressing the archive, if needed. Once the
+archive is cached in @var{directory}, subsequent requests succeed and
+are served directly from the cache, which guarantees that clients get
+the best possible bandwidth.
-@table @code
-@item --substitute-urls=@var{urls}
-@var{urls} is the space-separated list of substitute server URLs to
-query. When this option is omitted, the default set of substitute
-servers is queried.
+The ``baking'' process is performed by worker threads. By default, one
+thread per CPU core is created, but this can be customized. See
+@option{--workers} below.
-@item --system=@var{system}
-@itemx -s @var{system}
-Query substitutes for @var{system}---e.g., @code{aarch64-linux}. This
-option can be repeated, in which case @command{guix weather} will query
-substitutes for several system types.
+When @option{--ttl} is used, cached entries are automatically deleted
+when they have expired.
-@item --manifest=@var{file}
-Instead of querying substitutes for all the packages, only ask for those
-specified in @var{file}. @var{file} must contain a @dfn{manifest}, as
-with the @code{-m} option of @command{guix package} (@pxref{Invoking
-guix package}).
-@end table
+@item --workers=@var{N}
+When @option{--cache} is used, request the allocation of @var{N} worker
+threads to ``bake'' archives.
-@node Invoking guix processes
-@section Invoking @command{guix processes}
+@item --ttl=@var{ttl}
+Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
+(TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5
+days, @code{1m} means 1 month, and so on.
-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
-the processes involved@footnote{Remote sessions, when @command{guix-daemon} is
-started with @option{--listen} specifying a TCP endpoint, are @emph{not}
-listed.}. Here's an example of the information it returns:
+This allows the user's Guix to keep substitute information in cache for
+@var{ttl}. However, note that @code{guix publish} does not itself
+guarantee that the store items it provides will indeed remain available
+for as long as @var{ttl}.
-@example
-$ sudo guix processes
-SessionPID: 19002
-ClientPID: 19090
-ClientCommand: guix environment --ad-hoc python
+Additionally, when @option{--cache} is used, cached entries that have
+not been accessed for @var{ttl} and that no longer have a corresponding
+item in the store, may be deleted.
-SessionPID: 19402
-ClientPID: 19367
-ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{}
+@item --nar-path=@var{path}
+Use @var{path} as the prefix for the URLs of ``nar'' files
+(@pxref{Invoking guix archive, normalized archives}).
-SessionPID: 19444
-ClientPID: 19419
-ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
-LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock
-LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock
-LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock
-ChildProcess: 20495: guix offload x86_64-linux 7200 1 28800
-ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800
-ChildProcess: 27793: guix offload x86_64-linux 7200 1 28800
-@end example
+By default, nars are served at a URL such as
+@code{/nar/gzip/@dots{}-coreutils-8.25}. This option allows you to
+change the @code{/nar} part to @var{path}.
-In this example we see that @command{guix-daemon} has three clients:
-@command{guix environment}, @command{guix publish}, and the Cuirass continuous
-integration tool; their process identifier (PID) is given by the
-@code{ClientPID} field. The @code{SessionPID} field gives the PID of the
-@command{guix-daemon} sub-process of this particular session.
+@item --public-key=@var{file}
+@itemx --private-key=@var{file}
+Use the specific @var{file}s as the public/private key pair used to sign
+the store items being published.
-The @code{LockHeld} fields show which store items are currently locked by this
-session, which corresponds to store items being built or substituted (the
-@code{LockHeld} field is not displayed when @command{guix processes} is not
-running as root.) Last, by looking at the @code{ChildProcess} field, we
-understand that these three builds are being offloaded (@pxref{Daemon Offload
-Setup}).
+The files must correspond to the same key pair (the private key is used
+for signing and the public key is merely advertised in the signature
+metadata). They must contain keys in the canonical s-expression format
+as produced by @command{guix archive --generate-key} (@pxref{Invoking
+guix archive}). By default, @file{/etc/guix/signing-key.pub} and
+@file{/etc/guix/signing-key.sec} are used.
-The output is in Recutils format so we can use the handy @command{recsel}
-command to select sessions of interest (@pxref{Selection Expressions,,,
-recutils, GNU recutils manual}). As an example, the command shows the command
-line and PID of the client that triggered the build of a Perl package:
+@item --repl[=@var{port}]
+@itemx -r [@var{port}]
+Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
+Reference Manual}) on @var{port} (37146 by default). This is used
+primarily for debugging a running @command{guix publish} server.
+@end table
-@example
-$ sudo guix processes | \
- recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
-ClientPID: 19419
-ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
-@end example
+Enabling @command{guix publish} on Guix System is a one-liner: just
+instantiate a @code{guix-publish-service-type} service in the @code{services} field
+of the @code{operating-system} declaration (@pxref{guix-publish-service-type,
+@code{guix-publish-service-type}}).
-@c *********************************************************************
-@node GNU Distribution
-@chapter GNU Distribution
+If you are instead running Guix on a ``foreign distro'', follow these
+instructions:”
-@cindex Guix System Distribution
-@cindex GuixSD
-Guix comes with a distribution of the GNU system consisting entirely of
-free software@footnote{The term ``free'' here refers to the
-@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
-users of that software}.}. The
-distribution can be installed on its own (@pxref{System Installation}),
-but it is also possible to install Guix as a package manager on top of
-an installed GNU/Linux system (@pxref{Installation}). To distinguish
-between the two, we refer to the standalone distribution as the Guix
-System Distribution, or GuixSD.
+@itemize
+@item
+If your host distro uses the systemd init system:
-The distribution provides core GNU packages such as GNU libc, GCC, and
-Binutils, as well as many GNU and non-GNU applications. The complete
-list of available packages can be browsed
-@url{http://www.gnu.org/software/guix/packages,on-line} or by
-running @command{guix package} (@pxref{Invoking guix package}):
+@example
+# ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
+ /etc/systemd/system/
+# systemctl start guix-publish && systemctl enable guix-publish
+@end example
+
+@item
+If your host distro uses the Upstart init system:
@example
-guix package --list-available
+# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
+# start guix-publish
@end example
-Our goal is to provide a practical 100% free software distribution of
-Linux-based and other variants of GNU, with a focus on the promotion and
-tight integration of GNU components, and an emphasis on programs and
-tools that help users exert that freedom.
-
-Packages are currently available on the following platforms:
+@item
+Otherwise, proceed similarly with your distro's init system.
+@end itemize
-@table @code
+@node Invoking guix challenge
+@section Invoking @command{guix challenge}
-@item x86_64-linux
-Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
+@cindex reproducible builds
+@cindex verifiable builds
+@cindex @command{guix challenge}
+@cindex challenge
+Do the binaries provided by this server really correspond to the source
+code it claims to build? Is a package build process deterministic?
+These are the questions the @command{guix challenge} command attempts to
+answer.
-@item i686-linux
-Intel 32-bit architecture (IA32), Linux-Libre kernel;
+The former is obviously an important question: Before using a substitute
+server (@pxref{Substitutes}), one had better @emph{verify} that it
+provides the right binaries, and thus @emph{challenge} it. The latter
+is what enables the former: If package builds are deterministic, then
+independent builds of the package should yield the exact same result,
+bit for bit; if a server provides a binary different from the one
+obtained locally, it may be either corrupt or malicious.
-@item armhf-linux
-ARMv7-A architecture with hard float, Thumb-2 and NEON,
-using the EABI hard-float application binary interface (ABI),
-and Linux-Libre kernel.
+We know that the hash that shows up in @file{/gnu/store} file names is
+the hash of all the inputs of the process that built the file or
+directory---compilers, libraries, build scripts,
+etc. (@pxref{Introduction}). Assuming deterministic build processes,
+one store file name should map to exactly one build output.
+@command{guix challenge} checks whether there is, indeed, a single
+mapping by comparing the build outputs of several independent builds of
+any given store item.
-@item aarch64-linux
-little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is
-currently in an experimental stage, with limited support.
-@xref{Contributing}, for how to help!
+The command output looks like this:
-@item mips64el-linux
-little-endian 64-bit MIPS processors, specifically the Loongson series,
-n32 ABI, and Linux-Libre kernel.
+@smallexample
+$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org"
+updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 100.0%
+updating list of substitutes from 'https://guix.example.org'... 100.0%
+/gnu/store/@dots{}-openssl-1.0.2d contents differ:
+ local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
+ https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
+ https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
+/gnu/store/@dots{}-git-2.5.0 contents differ:
+ local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
+ https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
+ https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
+/gnu/store/@dots{}-pius-2.1.1 contents differ:
+ local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
+ https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
+ https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
-@end table
+@dots{}
-GuixSD itself is currently only available on @code{i686} and @code{x86_64}.
+6,406 store items were analyzed:
+ - 4,749 (74.1%) were identical
+ - 525 (8.2%) differed
+ - 1,132 (17.7%) were inconclusive
+@end smallexample
@noindent
-For information on porting to other architectures or kernels,
-@pxref{Porting}.
+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.
-@menu
-* System Installation:: Installing the whole operating system.
-* System Configuration:: Configuring the operating system.
-* Documentation:: Browsing software user manuals.
-* Installing Debugging Files:: Feeding the debugger.
-* Security Updates:: Deploying security fixes quickly.
-* Package Modules:: Packages from the programmer's viewpoint.
-* Packaging Guidelines:: Growing the distribution.
-* Bootstrapping:: GNU/Linux built from scratch.
-* Porting:: Targeting another platform or kernel.
-@end menu
+@cindex non-determinism, in package builds
+As an example, @code{guix.example.org} always gets a different answer.
+Conversely, @code{@value{SUBSTITUTE-SERVER}} agrees with local builds, except in the
+case of Git. This might indicate that the build process of Git is
+non-deterministic, meaning that its output varies as a function of
+various things that Guix does not fully control, in spite of building
+packages in isolated environments (@pxref{Features}). Most common
+sources of non-determinism include the addition of timestamps in build
+results, the inclusion of random numbers, and directory listings sorted
+by inode number. See @uref{https://reproducible-builds.org/docs/}, for
+more information.
-Building this distribution is a cooperative effort, and you are invited
-to join! @xref{Contributing}, for information about how you can help.
+To find out what is wrong with this Git binary, we can do something along
+these lines (@pxref{Invoking guix archive}):
-@node System Installation
-@section System Installation
+@example
+$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \
+ | guix archive -x /tmp/git
+$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
+@end example
-@cindex installing GuixSD
-@cindex Guix System Distribution
-This section explains how to install the Guix System Distribution (GuixSD)
-on a machine. The Guix package manager can
-also be installed on top of a running GNU/Linux system,
-@pxref{Installation}.
+This command shows the difference between the files resulting from the
+local build, and the files resulting from the build on
+@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging Files,,
+diffutils, Comparing and Merging Files}). The @command{diff} command
+works great for text files. When binary files differ, a better option
+is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
+visualize differences for all kinds of files.
-@ifinfo
-@quotation Note
-@c This paragraph is for people reading this from tty2 of the
-@c installation image.
-You are reading this documentation with an Info reader. For details on
-how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
-link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU
-Info}. Hit @kbd{l} afterwards to come back here.
+Once you have done that work, you can tell whether the differences are due
+to a non-deterministic build process or to a malicious server. We try
+hard to remove sources of non-determinism in packages to make it easier
+to verify substitutes, but of course, this is a process that
+involves not just Guix, but a large part of the free software community.
+In the meantime, @command{guix challenge} is one tool to help address
+the problem.
-Alternately, run @command{info info} in another tty to keep the manual
-available.
-@end quotation
-@end ifinfo
+If you are writing packages for Guix, you are encouraged to check
+whether @code{@value{SUBSTITUTE-SERVER}} and other substitute servers obtain the
+same build result as you did with:
-@menu
-* Limitations:: What you can expect.
-* Hardware Considerations:: Supported hardware.
-* USB Stick and DVD Installation:: Preparing the installation medium.
-* Preparing for Installation:: Networking, partitioning, etc.
-* Proceeding with the Installation:: The real thing.
-* Installing GuixSD in a VM:: GuixSD playground.
-* Building the Installation Image:: How this comes to be.
-@end menu
+@example
+$ guix challenge @var{package}
+@end example
-@node Limitations
-@subsection Limitations
+@noindent
+where @var{package} is a package specification such as
+@code{guile@@2.0} or @code{glibc:debug}.
-As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
-not production-ready. It may contain bugs and lack important
-features. Thus, if you are looking for a stable production system that
-respects your freedom as a computer user, a good solution at this point
-is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
-the more established GNU/Linux distributions}. We hope you can soon switch
-to the GuixSD without fear, of course. In the meantime, you can
-also keep using your distribution and try out the package manager on top
-of it (@pxref{Installation}).
+The general syntax is:
-Before you proceed with the installation, be aware of the following
-noteworthy limitations applicable to version @value{VERSION}:
+@example
+guix challenge @var{options} [@var{packages}@dots{}]
+@end example
-@itemize
-@item
-The installation process does not include a graphical user interface and
-requires familiarity with GNU/Linux (see the following subsections to
-get a feel of what that means.)
+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
+its exit code is 2 (other non-zero exit codes denote other kinds of
+errors.)
-@item
-Support for the Logical Volume Manager (LVM) is missing.
+The one option that matters is:
-@item
-More and more system services are provided (@pxref{Services}), but some
-may be missing.
+@table @code
-@item
-More than 8,500 packages are available, but you might
-occasionally find that a useful package is missing.
+@item --substitute-urls=@var{urls}
+Consider @var{urls} the whitespace-separated list of substitute source
+URLs to compare to.
-@item
-GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
-as well as a number of X11 window managers. However, some graphical
-applications may be missing, as well as KDE.
-@end itemize
+@item --verbose
+@itemx -v
+Show details about matches (identical contents) in addition to
+information about mismatches.
-You have been warned! But more than a disclaimer, this is an invitation
-to report issues (and success stories!), and to join us in improving it.
-@xref{Contributing}, for more info.
+@end table
+@node Invoking guix copy
+@section Invoking @command{guix copy}
-@node Hardware Considerations
-@subsection Hardware Considerations
+@cindex copy, of store items, over SSH
+@cindex SSH, copy of store items
+@cindex sharing store items across machines
+@cindex transferring store items across machines
+The @command{guix copy} command copies items from the store of one
+machine to that of another machine over a secure shell (SSH)
+connection@footnote{This command is available only when Guile-SSH was
+found. @xref{Requirements}, for details.}. For example, the following
+command copies the @code{coreutils} package, the user's profile, and all
+their dependencies over to @var{host}, logged in as @var{user}:
-@cindex hardware support on GuixSD
-GNU@tie{}GuixSD focuses on respecting the user's computing freedom. It
-builds around the kernel Linux-libre, which means that only hardware for
-which free software drivers and firmware exist is supported. Nowadays,
-a wide range of off-the-shelf hardware is supported on
-GNU/Linux-libre---from keyboards to graphics cards to scanners and
-Ethernet controllers. Unfortunately, there are still areas where
-hardware vendors deny users control over their own computing, and such
-hardware is not supported on GuixSD.
+@example
+guix copy --to=@var{user}@@@var{host} \
+ coreutils `readlink -f ~/.guix-profile`
+@end example
-@cindex WiFi, hardware support
-One of the main areas where free drivers or firmware are lacking is WiFi
-devices. WiFi devices known to work include those using Atheros chips
-(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
-driver, and those using Broadcom/AirForce chips (BCM43xx with
-Wireless-Core Revision 5), which corresponds to the @code{b43-open}
-Linux-libre driver. Free firmware exists for both and is available
-out-of-the-box on GuixSD, as part of @var{%base-firmware}
-(@pxref{operating-system Reference, @code{firmware}}).
+If some of the items to be copied are already present on @var{host},
+they are not actually sent.
-@cindex RYF, Respects Your Freedom
-The @uref{https://www.fsf.org/, Free Software Foundation} runs
-@uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a
-certification program for hardware products that respect your freedom
-and your privacy and ensure that you have control over your device. We
-encourage you to check the list of RYF-certified devices.
+The command below retrieves @code{libreoffice} and @code{gimp} from
+@var{host}, assuming they are available there:
+
+@example
+guix copy --from=@var{host} libreoffice gimp
+@end example
-Another useful resource is the @uref{https://www.h-node.org/, H-Node}
-web site. It contains a catalog of hardware devices with information
-about their support in GNU/Linux.
+The SSH connection is established using the Guile-SSH client, which is
+compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
+@file{~/.ssh/config}, and uses the SSH agent for authentication.
+The key used to sign items that are sent must be accepted by the remote
+machine. Likewise, the key used by the remote machine to sign items you
+are retrieving must be in @file{/etc/guix/acl} so it is accepted by your
+own daemon. @xref{Invoking guix archive}, for more information about
+store item authentication.
-@node USB Stick and DVD Installation
-@subsection USB Stick and DVD Installation
+The general syntax is:
-An ISO-9660 installation image that can be written to a USB stick or
-burnt to a DVD can be downloaded from
-@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz},
-where @var{system} is one of:
+@example
+guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
+@end example
-@table @code
-@item x86_64-linux
-for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
+You must always specify one of the following options:
-@item i686-linux
-for a 32-bit GNU/Linux system on Intel-compatible CPUs.
+@table @code
+@item --to=@var{spec}
+@itemx --from=@var{spec}
+Specify the host to send to or receive from. @var{spec} must be an SSH
+spec such as @code{example.org}, @code{charlie@@example.org}, or
+@code{charlie@@example.org:2222}.
@end table
-@c start duplication of authentication part from ``Binary Installation''
-Make sure to download the associated @file{.sig} file and to verify the
-authenticity of the image against it, along these lines:
+The @var{items} can be either package names, such as @code{gimp}, or
+store items, such as @file{/gnu/store/@dots{}-idutils-4.6}.
-@example
-$ wget https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig
-$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig
-@end example
+When specifying the name of a package to send, it is first built if
+needed, unless @option{--dry-run} was specified. Common build options
+are supported (@pxref{Common Build Options}).
-If that command fails because you do not have the required public key,
-then run this command to import it:
+
+@node Invoking guix container
+@section Invoking @command{guix container}
+@cindex container
+@cindex @command{guix container}
+@quotation Note
+As of version @value{VERSION}, this tool is experimental. The interface
+is subject to radical change in the future.
+@end quotation
+
+The purpose of @command{guix container} is to manipulate processes
+running within an isolated environment, commonly known as a
+``container'', typically created by the @command{guix environment}
+(@pxref{Invoking guix environment}) and @command{guix system container}
+(@pxref{Invoking guix system}) commands.
+
+The general syntax is:
@example
-$ gpg --keyserver @value{KEY-SERVER} \
- --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+guix container @var{action} @var{options}@dots{}
@end example
-@noindent
-and rerun the @code{gpg --verify} command.
-@c end duplication
-
-This image contains the tools necessary for an installation.
-It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
+@var{action} specifies the operation to perform with a container, and
+@var{options} specifies the context-specific arguments for the action.
-@unnumberedsubsubsec Copying to a USB Stick
+The following actions are available:
-To copy the image to a USB stick, follow these steps:
+@table @code
+@item exec
+Execute a command within the context of a running container.
-@enumerate
-@item
-Decompress the image using the @command{xz} command:
+The syntax is:
@example
-xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz
+guix container exec @var{pid} @var{program} @var{arguments}@dots{}
@end example
-@item
-Insert a USB stick of 1@tie{}GiB or more into your machine, and determine
-its device name. Assuming that the USB stick is known as @file{/dev/sdX},
-copy the image with:
+@var{pid} specifies the process ID of the running container.
+@var{program} specifies an executable file name within the root file
+system of the container. @var{arguments} are the additional options that
+will be passed to @var{program}.
+
+The following command launches an interactive login shell inside a
+Guix system container, started by @command{guix system container}, and whose
+process ID is 9001:
@example
-dd if=guixsd-install-@value{VERSION}.@var{system}.iso of=/dev/sdX
-sync
+guix container exec 9001 /run/current-system/profile/bin/bash --login
@end example
-Access to @file{/dev/sdX} usually requires root privileges.
-@end enumerate
-
-@unnumberedsubsubsec Burning on a DVD
+Note that the @var{pid} cannot be the parent process of a container. It
+must be PID 1 of the container or one of its child processes.
-To copy the image to a DVD, follow these steps:
+@end table
-@enumerate
-@item
-Decompress the image using the @command{xz} command:
+@node Invoking guix weather
+@section Invoking @command{guix weather}
-@example
-xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz
-@end example
+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
+specified servers so you can have an idea of whether you'll be grumpy
+today. It can sometimes be useful info as a user, but it is primarily
+useful to people running @command{guix publish} (@pxref{Invoking guix
+publish}).
-@item
-Insert a blank DVD into your machine, and determine
-its device name. Assuming that the DVD drive is known as @file{/dev/srX},
-copy the image with:
+@cindex statistics, for substitutes
+@cindex availability of substitutes
+@cindex substitute availability
+@cindex weather, substitute availability
+Here's a sample run:
@example
-growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.@var{system}.iso
+$ 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%
+https://guix.example.org
+ 43.4% substitutes available (2,658 out of 6,128)
+ 7,032.5 MiB of nars (compressed)
+ 19,824.2 MiB on disk (uncompressed)
+ 0.030 seconds per request (182.9 seconds in total)
+ 33.5 requests per second
+
+ 9.8% (342 out of 3,470) of the missing items are queued
+ 867 queued builds
+ x86_64-linux: 518 (59.7%)
+ i686-linux: 221 (25.5%)
+ aarch64-linux: 128 (14.8%)
+ build rate: 23.41 builds per hour
+ x86_64-linux: 11.16 builds per hour
+ i686-linux: 6.03 builds per hour
+ aarch64-linux: 6.41 builds per hour
@end example
-Access to @file{/dev/srX} usually requires root privileges.
-@end enumerate
+@cindex continuous integration, statistics
+As you can see, it reports the fraction of all the packages for which
+substitutes are available on the server---regardless of whether
+substitutes are enabled, and regardless of whether this server's signing
+key is authorized. It also reports the size of the compressed archives
+(``nars'') provided by the server, the size the corresponding store
+items occupy in the store (assuming deduplication is turned off), and
+the server's throughput. The second part gives continuous integration
+(CI) statistics, if the server supports it. In addition, using the
+@option{--coverage} option, @command{guix weather} can list ``important''
+package substitutes missing on the server (see below).
-@unnumberedsubsubsec Booting
+To achieve that, @command{guix weather} queries over HTTP(S) meta-data
+(@dfn{narinfos}) for all the relevant store items. Like @command{guix
+challenge}, it ignores signatures on those substitutes, which is
+innocuous since the command only gathers statistics and cannot install
+those substitutes.
-Once this is done, you should be able to reboot the system and boot from
-the USB stick or DVD. The latter usually requires you to get in the
-BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
+Among other things, it is possible to query specific system types and
+specific package sets. The available options are listed below.
-@xref{Installing GuixSD in a VM}, if, instead, you would like to install
-GuixSD in a virtual machine (VM).
+@table @code
+@item --substitute-urls=@var{urls}
+@var{urls} is the space-separated list of substitute server URLs to
+query. When this option is omitted, the default set of substitute
+servers is queried.
+@item --system=@var{system}
+@itemx -s @var{system}
+Query substitutes for @var{system}---e.g., @code{aarch64-linux}. This
+option can be repeated, in which case @command{guix weather} will query
+substitutes for several system types.
-@node Preparing for Installation
-@subsection Preparing for Installation
+@item --manifest=@var{file}
+Instead of querying substitutes for all the packages, only ask for those
+specified in @var{file}. @var{file} must contain a @dfn{manifest}, as
+with the @code{-m} option of @command{guix package} (@pxref{Invoking
+guix package}).
-Once you have successfully booted your computer using the installation medium,
-you should end up with a root prompt. Several console TTYs are configured
-and can be used to run commands as root. TTY2 shows this documentation,
-browsable using the Info reader commands (@pxref{Top,,, info-stnd,
-Stand-alone GNU Info}). The installation system runs the GPM mouse
-daemon, which allows you to select text with the left mouse button and
-to paste it with the middle button.
+@item --coverage[=@var{count}]
+@itemx -c [@var{count}]
+Report on substitute coverage for packages: list packages with at least
+@var{count} dependents (zero by default) for which substitutes are
+unavailable. Dependent packages themselves are not listed: if @var{b} depends
+on @var{a} and @var{a} has no substitutes, only @var{a} is listed, even though
+@var{b} usually lacks substitutes as well. The result looks like this:
+
+@example
+$ guix weather --substitute-urls=https://ci.guix.info -c 10
+computing 8,983 package derivations for x86_64-linux...
+looking for 9,343 store items on https://ci.guix.info...
+updating substitutes from 'https://ci.guix.info'... 100.0%
+https://ci.guix.info
+ 64.7% substitutes available (6,047 out of 9,343)
+@dots{}
+2502 packages are missing from 'https://ci.guix.info' for 'x86_64-linux', among which:
+ 58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0
+ 46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1
+ 37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008
+ @dots{}
+@end example
-@quotation Note
-Installation requires access to the Internet so that any missing
-dependencies of your system configuration can be downloaded. See the
-``Networking'' section below.
-@end quotation
+What this example shows is that @code{kcoreaddons} and presumably the 58
+packages that depend on it have no substitutes at @code{ci.guix.info};
+likewise for @code{qgpgme} and the 46 packages that depend on it.
-The installation system includes many common tools needed for this task.
-But it is also a full-blown GuixSD system, which means that you can
-install additional packages, should you need it, using @command{guix
-package} (@pxref{Invoking guix package}).
+If you are a Guix developer, or if you are taking care of this build farm,
+you'll probably want to have a closer look at these packages: they may simply
+fail to build.
+@end table
-@subsubsection Keyboard Layout
+@node Invoking guix processes
+@section Invoking @command{guix processes}
-@cindex keyboard layout
-The installation image uses the US qwerty keyboard layout. If you want
-to change it, you can use the @command{loadkeys} command. For example,
-the following command selects the Dvorak keyboard layout:
+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
+the processes involved@footnote{Remote sessions, when @command{guix-daemon} is
+started with @option{--listen} specifying a TCP endpoint, are @emph{not}
+listed.}. Here's an example of the information it returns:
@example
-loadkeys dvorak
+$ sudo guix processes
+SessionPID: 19002
+ClientPID: 19090
+ClientCommand: guix environment --ad-hoc python
+
+SessionPID: 19402
+ClientPID: 19367
+ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{}
+
+SessionPID: 19444
+ClientPID: 19419
+ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
+LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock
+LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock
+LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock
+ChildProcess: 20495: guix offload x86_64-linux 7200 1 28800
+ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800
+ChildProcess: 27793: guix offload x86_64-linux 7200 1 28800
@end example
-See the files under @file{/run/current-system/profile/share/keymaps} for
-a list of available keyboard layouts. Run @command{man loadkeys} for
-more information.
+In this example we see that @command{guix-daemon} has three clients:
+@command{guix environment}, @command{guix publish}, and the Cuirass continuous
+integration tool; their process identifier (PID) is given by the
+@code{ClientPID} field. The @code{SessionPID} field gives the PID of the
+@command{guix-daemon} sub-process of this particular session.
-@subsubsection Networking
+The @code{LockHeld} fields show which store items are currently locked by this
+session, which corresponds to store items being built or substituted (the
+@code{LockHeld} field is not displayed when @command{guix processes} is not
+running as root.) Last, by looking at the @code{ChildProcess} field, we
+understand that these three builds are being offloaded (@pxref{Daemon Offload
+Setup}).
-Run the following command to see what your network interfaces are called:
+The output is in Recutils format so we can use the handy @command{recsel}
+command to select sessions of interest (@pxref{Selection Expressions,,,
+recutils, GNU recutils manual}). As an example, the command shows the command
+line and PID of the client that triggered the build of a Perl package:
@example
-ifconfig -a
+$ sudo guix processes | \
+ recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
+ClientPID: 19419
+ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
@end example
-@noindent
-@dots{} or, using the GNU/Linux-specific @command{ip} command:
-@example
-ip a
-@end example
+@node System Configuration
+@chapter System Configuration
+
+@cindex system configuration
+The Guix System Distribution supports a consistent whole-system configuration
+mechanism. By that we mean that all aspects of the global system
+configuration---such as the available system services, timezone and
+locale settings, user accounts---are declared in a single place. Such
+a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
+
+One of the advantages of putting all the system configuration under the
+control of Guix is that it supports transactional system upgrades, and
+makes it possible to roll back to a previous system instantiation,
+should something go wrong with the new one (@pxref{Features}). Another
+advantage is that it makes it easy to replicate the exact same configuration
+across different machines, or at different points in time, without
+having to resort to additional administration tools layered on top of
+the own tools of the system.
+@c Yes, we're talking of Puppet, Chef, & co. here. ↑
+
+This section describes this mechanism. First we focus on the system
+administrator's viewpoint---explaining how the system is configured and
+instantiated. Then we show how this mechanism can be extended, for
+instance to support new system services.
-@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
-Wired interfaces have a name starting with @samp{e}; for example, the
-interface corresponding to the first on-board Ethernet controller is
-called @samp{eno1}. Wireless interfaces have a name starting with
-@samp{w}, like @samp{w1p2s0}.
+@menu
+* Using the Configuration System:: Customizing your GNU system.
+* operating-system Reference:: Detail of operating-system declarations.
+* File Systems:: Configuring file system mounts.
+* Mapped Devices:: Block device extra processing.
+* User Accounts:: Specifying user accounts.
+* Locales:: Language and cultural convention settings.
+* Services:: Specifying system services.
+* Setuid Programs:: Programs running with root privileges.
+* X.509 Certificates:: Authenticating HTTPS servers.
+* Name Service Switch:: Configuring libc's name service switch.
+* Initial RAM Disk:: Linux-Libre bootstrapping.
+* Bootloader Configuration:: Configuring the boot loader.
+* Invoking guix system:: Instantiating a system configuration.
+* Running Guix in a VM:: How to run Guix System in a virtual machine.
+* Defining Services:: Adding new service definitions.
+@end menu
-@table @asis
-@item Wired connection
-To configure a wired network run the following command, substituting
-@var{interface} with the name of the wired interface you want to use.
+@node Using the Configuration System
+@section Using the Configuration System
-@example
-ifconfig @var{interface} up
-@end example
+The operating system is configured by providing an
+@code{operating-system} declaration in a file that can then be passed to
+the @command{guix system} command (@pxref{Invoking guix system}). A
+simple setup, with the default system services, the default Linux-Libre
+kernel, initial RAM disk, and boot loader looks like this:
-@item Wireless connection
-@cindex wireless
-@cindex WiFi
-To configure wireless networking, you can create a configuration file
-for the @command{wpa_supplicant} configuration tool (its location is not
-important) using one of the available text editors such as
-@command{nano}:
+@findex operating-system
+@lisp
+@include os-config-bare-bones.texi
+@end lisp
-@example
-nano wpa_supplicant.conf
-@end example
+This example should be self-describing. Some of the fields defined
+above, such as @code{host-name} and @code{bootloader}, are mandatory.
+Others, such as @code{packages} and @code{services}, can be omitted, in
+which case they get a default value.
-As an example, the following stanza can go to this file and will work
-for many wireless networks, provided you give the actual SSID and
-passphrase for the network you are connecting to:
+Below we discuss the effect of some of the most important fields
+(@pxref{operating-system Reference}, for details about all the available
+fields), and how to @dfn{instantiate} the operating system using
+@command{guix system}.
-@example
-network=@{
- ssid="@var{my-ssid}"
- key_mgmt=WPA-PSK
- psk="the network's secret passphrase"
-@}
-@end example
+@unnumberedsubsec Bootloader
-Start the wireless service and run it in the background with the
-following command (substitute @var{interface} with the name of the
-network interface you want to use):
+@cindex legacy boot, on Intel machines
+@cindex BIOS boot, on Intel machines
+@cindex UEFI boot
+@cindex EFI boot
+The @code{bootloader} field describes the method that will be used to boot
+your system. Machines based on Intel processors can boot in ``legacy'' BIOS
+mode, as in the example above. However, more recent machines rely instead on
+the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that case,
+the @code{bootloader} field should contain something along these lines:
@example
-wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
+(bootloader-configuration
+ (bootloader grub-efi-bootloader)
+ (target "/boot/efi"))
@end example
-Run @command{man wpa_supplicant} for more information.
-@end table
+@xref{Bootloader Configuration}, for more information on the available
+configuration options.
-@cindex DHCP
-At this point, you need to acquire an IP address. On a network where IP
-addresses are automatically assigned @i{via} DHCP, you can run:
+@unnumberedsubsec Globally-Visible Packages
-@example
-dhclient -v @var{interface}
-@end example
+@vindex %base-packages
+The @code{packages} field lists packages that will be globally visible
+on the system, for all user accounts---i.e., in every user's @code{PATH}
+environment variable---in addition to the per-user profiles
+(@pxref{Invoking guix package}). The @var{%base-packages} variable
+provides all the tools one would expect for basic user and administrator
+tasks---including the GNU Core Utilities, the GNU Networking Utilities,
+the GNU Zile lightweight text editor, @command{find}, @command{grep},
+etc. The example above adds GNU@tie{}Screen to those,
+taken from the @code{(gnu packages screen)}
+module (@pxref{Package Modules}). The
+@code{(list package output)} syntax can be used to add a specific output
+of a package:
-Try to ping a server to see if networking is up and running:
+@lisp
+(use-modules (gnu packages))
+(use-modules (gnu packages dns))
-@example
-ping -c 3 gnu.org
-@end example
+(operating-system
+ ;; ...
+ (packages (cons (list bind "utils")
+ %base-packages)))
+@end lisp
-Setting up network access is almost always a requirement because the
-image does not contain all the software and tools that may be needed.
+@findex specification->package
+Referring to packages by variable name, like @code{bind} above, has
+the advantage of being unambiguous; it also allows typos and such to be
+diagnosed right away as ``unbound variables''. The downside is that one
+needs to know which module defines which package, and to augment the
+@code{use-package-modules} line accordingly. To avoid that, one can use
+the @code{specification->package} procedure of the @code{(gnu packages)}
+module, which returns the best package for a given name or name and
+version:
-@cindex installing over SSH
-If you want to, you can continue the installation remotely by starting
-an SSH server:
+@lisp
+(use-modules (gnu packages))
-@example
-herd start ssh-daemon
-@end example
+(operating-system
+ ;; ...
+ (packages (append (map specification->package
+ '("tcpdump" "htop" "gnupg@@2.0"))
+ %base-packages)))
+@end lisp
-Make sure to either set a password with @command{passwd}, or configure
-OpenSSH public key authentication before logging in.
+@unnumberedsubsec System Services
-@subsubsection Disk Partitioning
+@cindex services
+@vindex %base-services
+The @code{services} field lists @dfn{system services} to be made
+available when the system starts (@pxref{Services}).
+The @code{operating-system} declaration above specifies that, in
+addition to the basic services, we want the OpenSSH secure shell
+daemon listening on port 2222 (@pxref{Networking Services,
+@code{openssh-service-type}}). Under the hood,
+@code{openssh-service-type} arranges so that @command{sshd} is started with the
+right command-line options, possibly with supporting configuration files
+generated as needed (@pxref{Defining Services}).
-Unless this has already been done, the next step is to partition, and
-then format the target partition(s).
+@cindex customization, of services
+@findex modify-services
+Occasionally, instead of using the base services as is, you will want to
+customize them. To do this, use @code{modify-services} (@pxref{Service
+Reference, @code{modify-services}}) to modify the list.
-The installation image includes several partitioning tools, including
-Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
-@command{fdisk}, and @command{cfdisk}. Run it and set up your disk with
-the partition layout you want:
+For example, suppose you want to modify @code{guix-daemon} and Mingetty
+(the console log-in) in the @var{%base-services} list (@pxref{Base
+Services, @code{%base-services}}). To do that, you can write the
+following in your operating system declaration:
-@example
-cfdisk
-@end example
+@lisp
+(define %my-services
+ ;; My very own list of services.
+ (modify-services %base-services
+ (guix-service-type config =>
+ (guix-configuration
+ (inherit config)
+ (use-substitutes? #f)
+ (extra-options '("--gc-keep-derivations"))))
+ (mingetty-service-type config =>
+ (mingetty-configuration
+ (inherit config)))))
-If your disk uses the GUID Partition Table (GPT) format and you plan to
-install BIOS-based GRUB (which is the default), make sure a BIOS Boot
-Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB
-manual}).
+(operating-system
+ ;; @dots{}
+ (services %my-services))
+@end lisp
-@cindex EFI, installation
-@cindex UEFI, installation
-@cindex ESP, EFI system partition
-If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition}
-(ESP) is required. This partition should be mounted at @file{/boot/efi} and
-must have the @code{esp} flag set. E.g., for @command{parted}:
+This changes the configuration---i.e., the service parameters---of the
+@code{guix-service-type} instance, and that of all the
+@code{mingetty-service-type} instances in the @var{%base-services} list.
+Observe how this is accomplished: first, we arrange for the original
+configuration to be bound to the identifier @code{config} in the
+@var{body}, and then we write the @var{body} so that it evaluates to the
+desired configuration. In particular, notice how we use @code{inherit}
+to create a new configuration which has the same values as the old
+configuration, but with a few modifications.
-@example
-parted /dev/sda set 1 esp on
-@end example
+@cindex encrypted disk
+The configuration for a typical ``desktop'' usage, with an encrypted
+root partition, the X11 display
+server, GNOME and Xfce (users can choose which of these desktop
+environments to use at the log-in screen by pressing @kbd{F1}), network
+management, power management, and more, would look like this:
-@quotation Note
-@vindex grub-bootloader
-@vindex grub-efi-bootloader
-Unsure whether to use EFI- or BIOS-based GRUB? If the directory
-@file{/sys/firmware/efi} exists in the installation image, then you should
-probably perform an EFI installation, using @code{grub-efi-bootloader}.
-Otherwise you should use the BIOS-based GRUB, known as
-@code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on
-bootloaders.
-@end quotation
+@lisp
+@include os-config-desktop.texi
+@end lisp
-Once you are done partitioning the target hard disk drive, you have to
-create a file system on the relevant partition(s)@footnote{Currently
-GuixSD only supports ext4 and btrfs file systems. In particular, code
-that reads file system UUIDs and labels only works for these file system
-types.}. For the ESP, if you have one and assuming it is
-@file{/dev/sda1}, run:
+A graphical system with a choice of lightweight window managers
+instead of full-blown desktop environments would look like this:
-@example
-mkfs.fat -F32 /dev/sda1
-@end example
+@lisp
+@include os-config-lightweight-desktop.texi
+@end lisp
-Preferably, assign file systems a label so that you can easily and
-reliably refer to them in @code{file-system} declarations (@pxref{File
-Systems}). This is typically done using the @code{-L} option of
-@command{mkfs.ext4} and related commands. So, assuming the target root
-partition lives at @file{/dev/sda2}, a file system with the label
-@code{my-root} can be created with:
+This example refers to the @file{/boot/efi} file system by its UUID,
+@code{1234-ABCD}. Replace this UUID with the right UUID on your system,
+as returned by the @command{blkid} command.
-@example
-mkfs.ext4 -L my-root /dev/sda2
-@end example
+@xref{Desktop Services}, for the exact list of services provided by
+@var{%desktop-services}. @xref{X.509 Certificates}, for background
+information about the @code{nss-certs} package that is used here.
-@cindex encrypted disk
-If you are instead planning to encrypt the root partition, you can use
-the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
-@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
-@code{man cryptsetup}} for more information.) Assuming you want to
-store the root partition on @file{/dev/sda2}, the command sequence would
-be along these lines:
+Again, @var{%desktop-services} is just a list of service objects. If
+you want to remove services from there, you can do so using the
+procedures for list filtering (@pxref{SRFI-1 Filtering and
+Partitioning,,, guile, GNU Guile Reference Manual}). For instance, the
+following expression returns a list that contains all the services in
+@var{%desktop-services} minus the Avahi service:
@example
-cryptsetup luksFormat /dev/sda2
-cryptsetup open --type luks /dev/sda2 my-partition
-mkfs.ext4 -L my-root /dev/mapper/my-partition
+(remove (lambda (service)
+ (eq? (service-kind service) avahi-service-type))
+ %desktop-services)
@end example
-Once that is done, mount the target file system under @file{/mnt}
-with a command like (again, assuming @code{my-root} is the label of the
-root file system):
+@unnumberedsubsec Instantiating the System
-@example
-mount LABEL=my-root /mnt
-@end example
+Assuming the @code{operating-system} declaration
+is stored in the @file{my-system-config.scm}
+file, the @command{guix system reconfigure my-system-config.scm} command
+instantiates that configuration, and makes it the default GRUB boot
+entry (@pxref{Invoking guix system}).
-Also mount any other file systems you would like to use on the target
-system relative to this path. If you have @file{/boot} on a separate
-partition for example, mount it at @file{/mnt/boot} now so it is found
-by @code{guix system init} afterwards.
+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
+system state such as @command{useradd} or @command{grub-install}. In
+fact, you must avoid that since that would not only void your warranty
+but also prevent you from rolling back to previous versions of your
+system, should you ever need to.
-Finally, if you plan to use one or more swap partitions (@pxref{Memory
-Concepts, swap space,, libc, The GNU C Library Reference Manual}), make
-sure to initialize them with @command{mkswap}. Assuming you have one
-swap partition on @file{/dev/sda3}, you would run:
+@cindex roll-back, of the operating system
+Speaking of roll-back, each time you run @command{guix system
+reconfigure}, a new @dfn{generation} of the system is created---without
+modifying or deleting previous generations. Old system generations get
+an entry in the bootloader boot menu, allowing you to boot them in case
+something went wrong with the latest generation. Reassuring, no? The
+@command{guix system list-generations} command lists the system
+generations available on disk. It is also possible to roll back the
+system via the commands @command{guix system roll-back} and
+@command{guix system switch-generation}.
-@example
-mkswap /dev/sda3
-swapon /dev/sda3
-@end example
+Although the @command{guix system reconfigure} command will not modify
+previous generations, you must take care when the current generation is not
+the latest (e.g., after invoking @command{guix system roll-back}), since
+the operation might overwrite a later generation (@pxref{Invoking guix
+system}).
-Alternatively, you may use a swap file. For example, assuming that in
-the new system you want to use the file @file{/swapfile} as a swap file,
-you would run@footnote{This example will work for many types of file
-systems (e.g., ext4). However, for copy-on-write file systems (e.g.,
-btrfs), the required steps may be different. For details, see the
-manual pages for @command{mkswap} and @command{swapon}.}:
+@unnumberedsubsec The Programming Interface
-@example
-# This is 10 GiB of swap space. Adjust "count" to change the size.
-dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
-# For security, make the file readable and writable only by root.
-chmod 600 /mnt/swapfile
-mkswap /mnt/swapfile
-swapon /mnt/swapfile
-@end example
+At the Scheme level, the bulk of an @code{operating-system} declaration
+is instantiated with the following monadic procedure (@pxref{The Store
+Monad}):
-Note that if you have encrypted the root partition and created a swap
-file in its file system as described above, then the encryption also
-protects the swap file, just like any other file in that file system.
+@deffn {Monadic Procedure} operating-system-derivation os
+Return a derivation that builds @var{os}, an @code{operating-system}
+object (@pxref{Derivations}).
-@node Proceeding with the Installation
-@subsection Proceeding with the Installation
+The output of the derivation is a single directory that refers to all
+the packages, configuration files, and other supporting files needed to
+instantiate @var{os}.
+@end deffn
-With the target partitions ready and the target root mounted on
-@file{/mnt}, we're ready to go. First, run:
+This procedure is provided by the @code{(gnu system)} module. Along
+with @code{(gnu services)} (@pxref{Services}), this module contains the
+guts of Guix System. Make sure to visit it!
-@example
-herd start cow-store /mnt
-@end example
-This makes @file{/gnu/store} copy-on-write, such that packages added to it
-during the installation phase are written to the target disk on @file{/mnt}
-rather than kept in memory. This is necessary because the first phase of
-the @command{guix system init} command (see below) entails downloads or
-builds to @file{/gnu/store} which, initially, is an in-memory file system.
+@node operating-system Reference
+@section @code{operating-system} Reference
-Next, you have to edit a file and
-provide the declaration of the operating system to be installed. To
-that end, the installation system comes with three text editors. We
-recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
-supports syntax highlighting and parentheses matching; other editors
-include GNU Zile (an Emacs clone), and
-nvi (a clone of the original BSD @command{vi} editor).
-We strongly recommend storing that file on the target root file system, say,
-as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
-configuration file once you have rebooted into the newly-installed system.
+This section summarizes all the options available in
+@code{operating-system} declarations (@pxref{Using the Configuration
+System}).
-@xref{Using the Configuration System}, for an overview of the
-configuration file. The example configurations discussed in that
-section are available under @file{/etc/configuration} in the
-installation image. Thus, to get started with a system configuration
-providing a graphical display server (a ``desktop'' system), you can run
-something along these lines:
+@deftp {Data Type} operating-system
+This is the data type representing an operating system configuration.
+By that, we mean all the global system configuration, not per-user
+configuration (@pxref{Using the Configuration System}).
-@example
-# mkdir /mnt/etc
-# cp /etc/configuration/desktop.scm /mnt/etc/config.scm
-# nano /mnt/etc/config.scm
-@end example
+@table @asis
+@item @code{kernel} (default: @var{linux-libre})
+The package object of the operating system kernel to use@footnote{Currently
+only the Linux-libre kernel is supported. In the future, it will be
+possible to use the GNU@tie{}Hurd.}.
-You should pay attention to what your configuration file contains, and
-in particular:
+@item @code{kernel-arguments} (default: @code{'()})
+List of strings or gexps representing additional arguments to pass on
+the command-line of the kernel---e.g., @code{("console=ttyS0")}.
-@itemize
-@item
-Make sure the @code{bootloader-configuration} form refers to the target
-you want to install GRUB on. It should mention @code{grub-bootloader} if
-you are installing GRUB in the legacy way, or @code{grub-efi-bootloader}
-for newer UEFI systems. For legacy systems, the @code{target} field
-names a device, like @code{/dev/sda}; for UEFI systems it names a path
-to a mounted EFI partition, like @code{/boot/efi}, and do make sure the
-path is actually mounted.
+@item @code{bootloader}
+The system bootloader configuration object. @xref{Bootloader Configuration}.
-@item
-Be sure that your file system labels match the value of their respective
-@code{device} fields in your @code{file-system} configuration, assuming
-your @code{file-system} configuration uses the @code{file-system-label}
-procedure in its @code{device} field.
+@item @code{keyboard-layout} (default: @code{#f})
+This field specifies the keyboard layout to use in the console. It can be
+either @code{#f}, in which case the default keyboard layout is used (usually
+US English), or a @code{<keyboard-layout>} record.
-@item
-If there are encrypted or RAID partitions, make sure to add a
-@code{mapped-devices} field to describe them (@pxref{Mapped Devices}).
-@end itemize
+This keyboard layout is in effect as soon as the kernel has booted. For
+instance, it is the keyboard layout in effect when you type a passphrase if
+your root file system is on a @code{luks-device-mapping} mapped device
+(@pxref{Mapped Devices}).
-Once you are done preparing the configuration file, the new system must
-be initialized (remember that the target root file system is mounted
-under @file{/mnt}):
+@quotation Note
+This does @emph{not} specify the keyboard layout used by the bootloader, nor
+that used by the graphical display server. @xref{Bootloader Configuration},
+for information on how to specify the bootloader's keyboard layout. @xref{X
+Window}, for information on how to specify the keyboard layout used by the X
+Window System.
+@end quotation
-@example
-guix system init /mnt/etc/config.scm /mnt
-@end example
+@item @code{initrd-modules} (default: @code{%base-initrd-modules})
+@cindex initrd
+@cindex initial RAM disk
+The list of Linux kernel modules that need to be available in the
+initial RAM disk. @xref{Initial RAM Disk}.
-@noindent
-This copies all the necessary files and installs GRUB on
-@file{/dev/sdX}, unless you pass the @option{--no-bootloader} option. For
-more information, @pxref{Invoking guix system}. This command may trigger
-downloads or builds of missing packages, which can take some time.
+@item @code{initrd} (default: @code{base-initrd})
+A procedure that returns an initial RAM disk for the Linux
+kernel. This field is provided to support low-level customization and
+should rarely be needed for casual use. @xref{Initial RAM Disk}.
-Once that command has completed---and hopefully succeeded!---you can run
-@command{reboot} and boot into the new system. The @code{root} password
-in the new system is initially empty; other users' passwords need to be
-initialized by running the @command{passwd} command as @code{root},
-unless your configuration specifies otherwise
-(@pxref{user-account-password, user account passwords}).
+@item @code{firmware} (default: @var{%base-firmware})
+@cindex firmware
+List of firmware packages loadable by the operating system kernel.
-@cindex upgrading GuixSD
-From then on, you can update GuixSD whenever you want by running
-@command{guix pull} as @code{root} (@pxref{Invoking guix pull}), and
-then running @command{guix system reconfigure} to build a new system
-generation with the latest packages and services (@pxref{Invoking guix
-system}). We recommend doing that regularly so that your system
-includes the latest security updates (@pxref{Security Updates}).
+The default includes firmware needed for Atheros- and Broadcom-based
+WiFi devices (Linux-libre modules @code{ath9k} and @code{b43-open},
+respectively). @xref{Hardware Considerations}, for more info on
+supported hardware.
-Join us on @code{#guix} on the Freenode IRC network or on
-@email{guix-devel@@gnu.org} to share your experience---good or not so
-good.
+@item @code{host-name}
+The host name.
-@node Installing GuixSD in a VM
-@subsection Installing GuixSD in a Virtual Machine
+@item @code{hosts-file}
+@cindex hosts file
+A file-like object (@pxref{G-Expressions, file-like objects}) for use as
+@file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
+Reference Manual}). The default is a file with entries for
+@code{localhost} and @var{host-name}.
-@cindex virtual machine, GuixSD installation
-@cindex virtual private server (VPS)
-@cindex VPS (virtual private server)
-If you'd like to install GuixSD in a virtual machine (VM) or on a
-virtual private server (VPS) rather than on your beloved machine, this
-section is for you.
+@item @code{mapped-devices} (default: @code{'()})
+A list of mapped devices. @xref{Mapped Devices}.
-To boot a @uref{http://qemu.org/,QEMU} VM for installing GuixSD in a
-disk image, follow these steps:
+@item @code{file-systems}
+A list of file systems. @xref{File Systems}.
-@enumerate
-@item
-First, retrieve and decompress the GuixSD installation image as
-described previously (@pxref{USB Stick and DVD Installation}).
+@item @code{swap-devices} (default: @code{'()})
+@cindex swap devices
+A list of strings identifying devices or files to be used for ``swap
+space'' (@pxref{Memory Concepts,,, libc, The GNU C Library Reference
+Manual}). For example, @code{'("/dev/sda3")} or @code{'("/swapfile")}.
+It is possible to specify a swap file in a file system on a mapped
+device, provided that the necessary device mapping and file system are
+also specified. @xref{Mapped Devices} and @ref{File Systems}.
-@item
-Create a disk image that will hold the installed system. To make a
-qcow2-formatted disk image, use the @command{qemu-img} command:
+@item @code{users} (default: @code{%base-user-accounts})
+@itemx @code{groups} (default: @var{%base-groups})
+List of user accounts and groups. @xref{User Accounts}.
-@example
-qemu-img create -f qcow2 guixsd.img 50G
-@end example
+If the @code{users} list lacks a user account with UID@tie{}0, a
+``root'' account with UID@tie{}0 is automatically added.
-The resulting file will be much smaller than 50 GB (typically less than
-1 MB), but it will grow as the virtualized storage device is filled up.
+@item @code{skeletons} (default: @code{(default-skeletons)})
+A list target file name/file-like object tuples (@pxref{G-Expressions,
+file-like objects}). These are the skeleton files that will be added to
+the home directory of newly-created user accounts.
-@item
-Boot the USB installation image in an VM:
+For instance, a valid value may look like this:
@example
-qemu-system-x86_64 -m 1024 -smp 1 \
- -net user -net nic,model=virtio -boot menu=on \
- -drive file=guixsd-install-@value{VERSION}.@var{system}.iso \
- -drive file=guixsd.img
+`((".bashrc" ,(plain-file "bashrc" "echo Hello\n"))
+ (".guile" ,(plain-file "guile"
+ "(use-modules (ice-9 readline))
+ (activate-readline)")))
@end example
-The ordering of the drives matters.
-
-In the VM console, quickly press the @kbd{F12} key to enter the boot
-menu. Then press the @kbd{2} key and the @kbd{RET} key to validate your
-selection.
+@item @code{issue} (default: @var{%default-issue})
+A string denoting the contents of the @file{/etc/issue} file, which is
+displayed when users log in on a text console.
-@item
-You're now root in the VM, proceed with the installation process.
-@xref{Preparing for Installation}, and follow the instructions.
-@end enumerate
+@item @code{packages} (default: @var{%base-packages})
+The set of packages installed in the global profile, which is accessible
+at @file{/run/current-system/profile}.
-Once installation is complete, you can boot the system that's on your
-@file{guixsd.img} image. @xref{Running GuixSD in a VM}, for how to do
-that.
+The default set includes core utilities and it is good practice to
+install non-core utilities in user profiles (@pxref{Invoking guix
+package}).
-@node Building the Installation Image
-@subsection Building the Installation Image
+@item @code{timezone}
+A timezone identifying string---e.g., @code{"Europe/Paris"}.
-@cindex installation image
-The installation image described above was built using the @command{guix
-system} command, specifically:
+You can run the @command{tzselect} command to find out which timezone
+string corresponds to your region. Choosing an invalid timezone name
+causes @command{guix system} to fail.
-@example
-guix system disk-image gnu/system/install.scm
-@end example
+@item @code{locale} (default: @code{"en_US.utf8"})
+The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
+Library Reference Manual}). @xref{Locales}, for more information.
-Have a look at @file{gnu/system/install.scm} in the source tree,
-and see also @ref{Invoking guix system} for more information
-about the installation image.
+@item @code{locale-definitions} (default: @var{%default-locale-definitions})
+The list of locale definitions to be compiled and that may be used at
+run time. @xref{Locales}.
-@subsection Building the Installation Image for ARM Boards
+@item @code{locale-libcs} (default: @code{(list @var{glibc})})
+The list of GNU@tie{}libc packages whose locale data and tools are used
+to build the locale definitions. @xref{Locales}, for compatibility
+considerations that justify this option.
-Many ARM boards require a specific variant of the
-@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
+@item @code{name-service-switch} (default: @var{%default-nss})
+Configuration of the libc name service switch (NSS)---a
+@code{<name-service-switch>} object. @xref{Name Service Switch}, for
+details.
-If you build a disk image and the bootloader is not available otherwise
-(on another boot drive etc), it's advisable to build an image that
-includes the bootloader, specifically:
+@item @code{services} (default: @var{%base-services})
+A list of service objects denoting system services. @xref{Services}.
-@example
-guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
-@end example
+@item @code{pam-services} (default: @code{(base-pam-services)})
+@cindex PAM
+@cindex pluggable authentication modules
+Linux @dfn{pluggable authentication module} (PAM) services.
+@c FIXME: Add xref to PAM services section.
-@code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid
-board, a list of possible boards will be printed.
+@item @code{setuid-programs} (default: @var{%setuid-programs})
+List of string-valued G-expressions denoting setuid programs.
+@xref{Setuid Programs}.
-@node System Configuration
-@section System Configuration
+@item @code{sudoers-file} (default: @var{%sudoers-specification})
+@cindex sudoers file
+The contents of the @file{/etc/sudoers} file as a file-like object
+(@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
-@cindex system configuration
-The Guix System Distribution supports a consistent whole-system configuration
-mechanism. By that we mean that all aspects of the global system
-configuration---such as the available system services, timezone and
-locale settings, user accounts---are declared in a single place. Such
-a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
+This file specifies which users can use the @command{sudo} command, what
+they are allowed to do, and what privileges they may gain. The default
+is that only @code{root} and members of the @code{wheel} group may use
+@code{sudo}.
-One of the advantages of putting all the system configuration under the
-control of Guix is that it supports transactional system upgrades, and
-makes it possible to roll back to a previous system instantiation,
-should something go wrong with the new one (@pxref{Features}). Another
-advantage is that it makes it easy to replicate the exact same configuration
-across different machines, or at different points in time, without
-having to resort to additional administration tools layered on top of
-the own tools of the system.
-@c Yes, we're talking of Puppet, Chef, & co. here. ↑
+@end table
+@end deftp
-This section describes this mechanism. First we focus on the system
-administrator's viewpoint---explaining how the system is configured and
-instantiated. Then we show how this mechanism can be extended, for
-instance to support new system services.
+@node File Systems
+@section File Systems
-@menu
-* Using the Configuration System:: Customizing your GNU system.
-* operating-system Reference:: Detail of operating-system declarations.
-* File Systems:: Configuring file system mounts.
-* Mapped Devices:: Block device extra processing.
-* User Accounts:: Specifying user accounts.
-* Locales:: Language and cultural convention settings.
-* Services:: Specifying system services.
-* Setuid Programs:: Programs running with root privileges.
-* X.509 Certificates:: Authenticating HTTPS servers.
-* Name Service Switch:: Configuring libc's name service switch.
-* Initial RAM Disk:: Linux-Libre bootstrapping.
-* Bootloader Configuration:: Configuring the boot loader.
-* Invoking guix system:: Instantiating a system configuration.
-* Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
-* Defining Services:: Adding new service definitions.
-@end menu
+The list of file systems to be mounted is specified in the
+@code{file-systems} field of the operating system declaration
+(@pxref{Using the Configuration System}). Each file system is declared
+using the @code{file-system} form, like this:
-@node Using the Configuration System
-@subsection Using the Configuration System
+@example
+(file-system
+ (mount-point "/home")
+ (device "/dev/sda3")
+ (type "ext4"))
+@end example
-The operating system is configured by providing an
-@code{operating-system} declaration in a file that can then be passed to
-the @command{guix system} command (@pxref{Invoking guix system}). A
-simple setup, with the default system services, the default Linux-Libre
-kernel, initial RAM disk, and boot loader looks like this:
+As usual, some of the fields are mandatory---those shown in the example
+above---while others can be omitted. These are described below.
-@findex operating-system
-@lisp
-@include os-config-bare-bones.texi
-@end lisp
+@deftp {Data Type} file-system
+Objects of this type represent file systems to be mounted. They
+contain the following members:
-This example should be self-describing. Some of the fields defined
-above, such as @code{host-name} and @code{bootloader}, are mandatory.
-Others, such as @code{packages} and @code{services}, can be omitted, in
-which case they get a default value.
+@table @asis
+@item @code{type}
+This is a string specifying the type of the file system---e.g.,
+@code{"ext4"}.
-Below we discuss the effect of some of the most important fields
-(@pxref{operating-system Reference}, for details about all the available
-fields), and how to @dfn{instantiate} the operating system using
-@command{guix system}.
+@item @code{mount-point}
+This designates the place where the file system is to be mounted.
-@unnumberedsubsubsec Bootloader
+@item @code{device}
+This names the ``source'' of the file system. It can be one of three
+things: a file system label, a file system UUID, or the name of a
+@file{/dev} node. Labels and UUIDs offer a way to refer to file
+systems without having to hard-code their actual device
+name@footnote{Note that, while it is tempting to use
+@file{/dev/disk/by-uuid} and similar device names to achieve the same
+result, this is not recommended: These special device nodes are created
+by the udev daemon and may be unavailable at the time the device is
+mounted.}.
-@cindex legacy boot, on Intel machines
-@cindex BIOS boot, on Intel machines
-@cindex UEFI boot
-@cindex EFI boot
-The @code{bootloader} field describes the method that will be used to boot
-your system. Machines based on Intel processors can boot in ``legacy'' BIOS
-mode, as in the example above. However, more recent machines rely instead on
-the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that case,
-the @code{bootloader} field should contain something along these lines:
+@findex file-system-label
+File system labels are created using the @code{file-system-label}
+procedure, UUIDs are created using @code{uuid}, and @file{/dev} node are
+plain strings. Here's an example of a file system referred to by its
+label, as shown by the @command{e2label} command:
@example
-(bootloader-configuration
- (bootloader grub-efi-bootloader)
- (target "/boot/efi"))
+(file-system
+ (mount-point "/home")
+ (type "ext4")
+ (device (file-system-label "my-home")))
@end example
-@xref{Bootloader Configuration}, for more information on the available
-configuration options.
-
-@unnumberedsubsubsec Globally-Visible Packages
+@findex uuid
+UUIDs are converted from their string representation (as shown by the
+@command{tune2fs -l} command) using the @code{uuid} form@footnote{The
+@code{uuid} form expects 16-byte UUIDs as defined in
+@uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. This is the
+form of UUID used by the ext2 family of file systems and others, but it
+is different from ``UUIDs'' found in FAT file systems, for instance.},
+like this:
-@vindex %base-packages
-The @code{packages} field lists packages that will be globally visible
-on the system, for all user accounts---i.e., in every user's @code{PATH}
-environment variable---in addition to the per-user profiles
-(@pxref{Invoking guix package}). The @var{%base-packages} variable
-provides all the tools one would expect for basic user and administrator
-tasks---including the GNU Core Utilities, the GNU Networking Utilities,
-the GNU Zile lightweight text editor, @command{find}, @command{grep},
-etc. The example above adds GNU@tie{}Screen to those,
-taken from the @code{(gnu packages screen)}
-module (@pxref{Package Modules}). The
-@code{(list package output)} syntax can be used to add a specific output
-of a package:
+@example
+(file-system
+ (mount-point "/home")
+ (type "ext4")
+ (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
+@end example
-@lisp
-(use-modules (gnu packages))
-(use-modules (gnu packages dns))
+When the source of a file system is a mapped device (@pxref{Mapped
+Devices}), its @code{device} field @emph{must} refer to the mapped
+device name---e.g., @file{"/dev/mapper/root-partition"}.
+This is required so that
+the system knows that mounting the file system depends on having the
+corresponding device mapping established.
-(operating-system
- ;; ...
- (packages (cons (list bind "utils")
- %base-packages)))
-@end lisp
+@item @code{flags} (default: @code{'()})
+This is a list of symbols denoting mount flags. Recognized flags
+include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
+access to special files), @code{no-suid} (ignore setuid and setgid
+bits), and @code{no-exec} (disallow program execution.)
-@findex specification->package
-Referring to packages by variable name, like @code{bind} above, has
-the advantage of being unambiguous; it also allows typos and such to be
-diagnosed right away as ``unbound variables''. The downside is that one
-needs to know which module defines which package, and to augment the
-@code{use-package-modules} line accordingly. To avoid that, one can use
-the @code{specification->package} procedure of the @code{(gnu packages)}
-module, which returns the best package for a given name or name and
-version:
+@item @code{options} (default: @code{#f})
+This is either @code{#f}, or a string denoting mount options.
-@lisp
-(use-modules (gnu packages))
+@item @code{mount?} (default: @code{#t})
+This value indicates whether to automatically mount the file system when
+the system is brought up. When set to @code{#f}, the file system gets
+an entry in @file{/etc/fstab} (read by the @command{mount} command) but
+is not automatically mounted.
-(operating-system
- ;; ...
- (packages (append (map specification->package
- '("tcpdump" "htop" "gnupg@@2.0"))
- %base-packages)))
-@end lisp
+@item @code{needed-for-boot?} (default: @code{#f})
+This Boolean value indicates whether the file system is needed when
+booting. If that is true, then the file system is mounted when the
+initial RAM disk (initrd) is loaded. This is always the case, for
+instance, for the root file system.
-@unnumberedsubsubsec System Services
+@item @code{check?} (default: @code{#t})
+This Boolean indicates whether the file system needs to be checked for
+errors before being mounted.
-@cindex services
-@vindex %base-services
-The @code{services} field lists @dfn{system services} to be made
-available when the system starts (@pxref{Services}).
-The @code{operating-system} declaration above specifies that, in
-addition to the basic services, we want the @command{lshd} secure shell
-daemon listening on port 2222 (@pxref{Networking Services,
-@code{lsh-service}}). Under the hood,
-@code{lsh-service} arranges so that @code{lshd} is started with the
-right command-line options, possibly with supporting configuration files
-generated as needed (@pxref{Defining Services}).
+@item @code{create-mount-point?} (default: @code{#f})
+When true, the mount point is created if it does not exist yet.
-@cindex customization, of services
-@findex modify-services
-Occasionally, instead of using the base services as is, you will want to
-customize them. To do this, use @code{modify-services} (@pxref{Service
-Reference, @code{modify-services}}) to modify the list.
+@item @code{dependencies} (default: @code{'()})
+This is a list of @code{<file-system>} or @code{<mapped-device>} objects
+representing file systems that must be mounted or mapped devices that
+must be opened before (and unmounted or closed after) this one.
-For example, suppose you want to modify @code{guix-daemon} and Mingetty
-(the console log-in) in the @var{%base-services} list (@pxref{Base
-Services, @code{%base-services}}). To do that, you can write the
-following in your operating system declaration:
+As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is
+a dependency of @file{/sys/fs/cgroup/cpu} and
+@file{/sys/fs/cgroup/memory}.
-@lisp
-(define %my-services
- ;; My very own list of services.
- (modify-services %base-services
- (guix-service-type config =>
- (guix-configuration
- (inherit config)
- (use-substitutes? #f)
- (extra-options '("--gc-keep-derivations"))))
- (mingetty-service-type config =>
- (mingetty-configuration
- (inherit config)))))
+Another example is a file system that depends on a mapped device, for
+example for an encrypted partition (@pxref{Mapped Devices}).
+@end table
+@end deftp
-(operating-system
- ;; @dots{}
- (services %my-services))
-@end lisp
+The @code{(gnu system file-systems)} exports the following useful
+variables.
-This changes the configuration---i.e., the service parameters---of the
-@code{guix-service-type} instance, and that of all the
-@code{mingetty-service-type} instances in the @var{%base-services} list.
-Observe how this is accomplished: first, we arrange for the original
-configuration to be bound to the identifier @code{config} in the
-@var{body}, and then we write the @var{body} so that it evaluates to the
-desired configuration. In particular, notice how we use @code{inherit}
-to create a new configuration which has the same values as the old
-configuration, but with a few modifications.
+@defvr {Scheme Variable} %base-file-systems
+These are essential file systems that are required on normal systems,
+such as @var{%pseudo-terminal-file-system} and @var{%immutable-store} (see
+below.) Operating system declarations should always contain at least
+these.
+@end defvr
-@cindex encrypted disk
-The configuration for a typical ``desktop'' usage, with an encrypted
-root partition, the X11 display
-server, GNOME and Xfce (users can choose which of these desktop
-environments to use at the log-in screen by pressing @kbd{F1}), network
-management, power management, and more, would look like this:
+@defvr {Scheme Variable} %pseudo-terminal-file-system
+This is the file system to be mounted as @file{/dev/pts}. It supports
+@dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
+functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
+Manual}). Pseudo-terminals are used by terminal emulators such as
+@command{xterm}.
+@end defvr
-@lisp
-@include os-config-desktop.texi
-@end lisp
+@defvr {Scheme Variable} %shared-memory-file-system
+This file system is mounted as @file{/dev/shm} and is used to support
+memory sharing across processes (@pxref{Memory-mapped I/O,
+@code{shm_open},, libc, The GNU C Library Reference Manual}).
+@end defvr
-A graphical system with a choice of lightweight window managers
-instead of full-blown desktop environments would look like this:
+@defvr {Scheme Variable} %immutable-store
+This file system performs a read-only ``bind mount'' of
+@file{/gnu/store}, making it read-only for all the users including
+@code{root}. This prevents against accidental modification by software
+running as @code{root} or by system administrators.
-@lisp
-@include os-config-lightweight-desktop.texi
-@end lisp
+The daemon itself is still able to write to the store: it remounts it
+read-write in its own ``name space.''
+@end defvr
-This example refers to the @file{/boot/efi} file system by its UUID,
-@code{1234-ABCD}. Replace this UUID with the right UUID on your system,
-as returned by the @command{blkid} command.
+@defvr {Scheme Variable} %binary-format-file-system
+The @code{binfmt_misc} file system, which allows handling of arbitrary
+executable file types to be delegated to user space. This requires the
+@code{binfmt.ko} kernel module to be loaded.
+@end defvr
-@xref{Desktop Services}, for the exact list of services provided by
-@var{%desktop-services}. @xref{X.509 Certificates}, for background
-information about the @code{nss-certs} package that is used here.
+@defvr {Scheme Variable} %fuse-control-file-system
+The @code{fusectl} file system, which allows unprivileged users to mount
+and unmount user-space FUSE file systems. This requires the
+@code{fuse.ko} kernel module to be loaded.
+@end defvr
-Again, @var{%desktop-services} is just a list of service objects. If
-you want to remove services from there, you can do so using the
-procedures for list filtering (@pxref{SRFI-1 Filtering and
-Partitioning,,, guile, GNU Guile Reference Manual}). For instance, the
-following expression returns a list that contains all the services in
-@var{%desktop-services} minus the Avahi service:
+@node Mapped Devices
+@section Mapped Devices
-@example
-(remove (lambda (service)
- (eq? (service-kind service) avahi-service-type))
- %desktop-services)
-@end example
+@cindex device mapping
+@cindex mapped devices
+The Linux kernel has a notion of @dfn{device mapping}: a block device,
+such as a hard disk partition, can be @dfn{mapped} into another device,
+usually in @code{/dev/mapper/},
+with additional processing over the data that flows through
+it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
+concept of a ``mapped device'' and that of a file system: both boil down
+to @emph{translating} input/output operations made on a file to
+operations on its backing store. Thus, the Hurd implements mapped
+devices, like file systems, using the generic @dfn{translator} mechanism
+(@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
+typical example is encryption device mapping: all writes to the mapped
+device are encrypted, and all reads are deciphered, transparently.
+Guix extends this notion by considering any device or set of devices that
+are @dfn{transformed} in some way to create a new device; for instance,
+RAID devices are obtained by @dfn{assembling} several other devices, such
+as hard disks or partitions, into a new one that behaves as one partition.
+Other examples, not yet implemented, are LVM logical volumes.
-@unnumberedsubsubsec Instantiating the System
+Mapped devices are declared using the @code{mapped-device} form,
+defined as follows; for examples, see below.
-Assuming the @code{operating-system} declaration
-is stored in the @file{my-system-config.scm}
-file, the @command{guix system reconfigure my-system-config.scm} command
-instantiates that configuration, and makes it the default GRUB boot
-entry (@pxref{Invoking guix system}).
+@deftp {Data Type} mapped-device
+Objects of this type represent device mappings that will be made when
+the system boots up.
-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
-system state such as @command{useradd} or @command{grub-install}. In
-fact, you must avoid that since that would not only void your warranty
-but also prevent you from rolling back to previous versions of your
-system, should you ever need to.
+@table @code
+@item source
+This is either a string specifying the name of the block device to be mapped,
+such as @code{"/dev/sda3"}, or a list of such strings when several devices
+need to be assembled for creating a new one.
-@cindex roll-back, of the operating system
-Speaking of roll-back, each time you run @command{guix system
-reconfigure}, a new @dfn{generation} of the system is created---without
-modifying or deleting previous generations. Old system generations get
-an entry in the bootloader boot menu, allowing you to boot them in case
-something went wrong with the latest generation. Reassuring, no? The
-@command{guix system list-generations} command lists the system
-generations available on disk. It is also possible to roll back the
-system via the commands @command{guix system roll-back} and
-@command{guix system switch-generation}.
+@item target
+This string specifies the name of the resulting mapped device. For
+kernel mappers such as encrypted devices of type @code{luks-device-mapping},
+specifying @code{"my-partition"} leads to the creation of
+the @code{"/dev/mapper/my-partition"} device.
+For RAID devices of type @code{raid-device-mapping}, the full device name
+such as @code{"/dev/md0"} needs to be given.
-Although the @command{guix system reconfigure} command will not modify
-previous generations, you must take care when the current generation is not
-the latest (e.g., after invoking @command{guix system roll-back}), since
-the operation might overwrite a later generation (@pxref{Invoking guix
-system}).
+@item type
+This must be a @code{mapped-device-kind} object, which specifies how
+@var{source} is mapped to @var{target}.
+@end table
+@end deftp
-@unnumberedsubsubsec The Programming Interface
+@defvr {Scheme Variable} luks-device-mapping
+This defines LUKS block device encryption using the @command{cryptsetup}
+command from the package with the same name. It relies on the
+@code{dm-crypt} Linux kernel module.
+@end defvr
-At the Scheme level, the bulk of an @code{operating-system} declaration
-is instantiated with the following monadic procedure (@pxref{The Store
-Monad}):
+@defvr {Scheme Variable} raid-device-mapping
+This defines a RAID device, which is assembled using the @code{mdadm}
+command from the package with the same name. It requires a Linux kernel
+module for the appropriate RAID level to be loaded, such as @code{raid456}
+for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
+@end defvr
-@deffn {Monadic Procedure} operating-system-derivation os
-Return a derivation that builds @var{os}, an @code{operating-system}
-object (@pxref{Derivations}).
+@cindex disk encryption
+@cindex LUKS
+The following example specifies a mapping from @file{/dev/sda3} to
+@file{/dev/mapper/home} using LUKS---the
+@url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, a
+standard mechanism for disk encryption.
+The @file{/dev/mapper/home}
+device can then be used as the @code{device} of a @code{file-system}
+declaration (@pxref{File Systems}).
-The output of the derivation is a single directory that refers to all
-the packages, configuration files, and other supporting files needed to
-instantiate @var{os}.
-@end deffn
+@example
+(mapped-device
+ (source "/dev/sda3")
+ (target "home")
+ (type luks-device-mapping))
+@end example
-This procedure is provided by the @code{(gnu system)} module. Along
-with @code{(gnu services)} (@pxref{Services}), this module contains the
-guts of GuixSD. Make sure to visit it!
+Alternatively, to become independent of device numbering, one may obtain
+the LUKS UUID (@dfn{unique identifier}) of the source device by a
+command like:
+
+@example
+cryptsetup luksUUID /dev/sda3
+@end example
+and use it as follows:
-@node operating-system Reference
-@subsection @code{operating-system} Reference
+@example
+(mapped-device
+ (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
+ (target "home")
+ (type luks-device-mapping))
+@end example
-This section summarizes all the options available in
-@code{operating-system} declarations (@pxref{Using the Configuration
-System}).
+@cindex swap encryption
+It is also desirable to encrypt swap space, since swap space may contain
+sensitive data. One way to accomplish that is to use a swap file in a
+file system on a device mapped via LUKS encryption. In this way, the
+swap file is encrypted because the entire device is encrypted.
+@xref{Preparing for Installation,,Disk Partitioning}, for an example.
-@deftp {Data Type} operating-system
-This is the data type representing an operating system configuration.
-By that, we mean all the global system configuration, not per-user
-configuration (@pxref{Using the Configuration System}).
+A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
+may be declared as follows:
-@table @asis
-@item @code{kernel} (default: @var{linux-libre})
-The package object of the operating system kernel to use@footnote{Currently
-only the Linux-libre kernel is supported. In the future, it will be
-possible to use the GNU@tie{}Hurd.}.
+@example
+(mapped-device
+ (source (list "/dev/sda1" "/dev/sdb1"))
+ (target "/dev/md0")
+ (type raid-device-mapping))
+@end example
-@item @code{kernel-arguments} (default: @code{'()})
-List of strings or gexps representing additional arguments to pass on
-the command-line of the kernel---e.g., @code{("console=ttyS0")}.
+The @file{/dev/md0} device can then be used as the @code{device} of a
+@code{file-system} declaration (@pxref{File Systems}).
+Note that the RAID level need not be given; it is chosen during the
+initial creation and formatting of the RAID device and is determined
+automatically later.
-@item @code{bootloader}
-The system bootloader configuration object. @xref{Bootloader Configuration}.
-@item @code{initrd-modules} (default: @code{%base-initrd-modules})
-@cindex initrd
-@cindex initial RAM disk
-The list of Linux kernel modules that need to be available in the
-initial RAM disk. @xref{Initial RAM Disk}.
+@node User Accounts
+@section User Accounts
-@item @code{initrd} (default: @code{base-initrd})
-A procedure that returns an initial RAM disk for the Linux
-kernel. This field is provided to support low-level customization and
-should rarely be needed for casual use. @xref{Initial RAM Disk}.
+@cindex users
+@cindex accounts
+@cindex user accounts
+User accounts and groups are entirely managed through the
+@code{operating-system} declaration. They are specified with the
+@code{user-account} and @code{user-group} forms:
-@item @code{firmware} (default: @var{%base-firmware})
-@cindex firmware
-List of firmware packages loadable by the operating system kernel.
+@example
+(user-account
+ (name "alice")
+ (group "users")
+ (supplementary-groups '("wheel" ;allow use of sudo, etc.
+ "audio" ;sound card
+ "video" ;video devices such as webcams
+ "cdrom")) ;the good ol' CD-ROM
+ (comment "Bob's sister")
+ (home-directory "/home/alice"))
+@end example
-The default includes firmware needed for Atheros- and Broadcom-based
-WiFi devices (Linux-libre modules @code{ath9k} and @code{b43-open},
-respectively). @xref{Hardware Considerations}, for more info on
-supported hardware.
+When booting or upon completion of @command{guix system reconfigure},
+the system ensures that only the user accounts and groups specified in
+the @code{operating-system} declaration exist, and with the specified
+properties. Thus, account or group creations or modifications made by
+directly invoking commands such as @command{useradd} are lost upon
+reconfiguration or reboot. This ensures that the system remains exactly
+as declared.
-@item @code{host-name}
-The host name.
+@deftp {Data Type} user-account
+Objects of this type represent user accounts. The following members may
+be specified:
-@item @code{hosts-file}
-@cindex hosts file
-A file-like object (@pxref{G-Expressions, file-like objects}) for use as
-@file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
-Reference Manual}). The default is a file with entries for
-@code{localhost} and @var{host-name}.
+@table @asis
+@item @code{name}
+The name of the user account.
-@item @code{mapped-devices} (default: @code{'()})
-A list of mapped devices. @xref{Mapped Devices}.
+@item @code{group}
+@cindex groups
+This is the name (a string) or identifier (a number) of the user group
+this account belongs to.
-@item @code{file-systems}
-A list of file systems. @xref{File Systems}.
+@item @code{supplementary-groups} (default: @code{'()})
+Optionally, this can be defined as a list of group names that this
+account belongs to.
-@item @code{swap-devices} (default: @code{'()})
-@cindex swap devices
-A list of strings identifying devices or files to be used for ``swap
-space'' (@pxref{Memory Concepts,,, libc, The GNU C Library Reference
-Manual}). For example, @code{'("/dev/sda3")} or @code{'("/swapfile")}.
-It is possible to specify a swap file in a file system on a mapped
-device, provided that the necessary device mapping and file system are
-also specified. @xref{Mapped Devices} and @ref{File Systems}.
+@item @code{uid} (default: @code{#f})
+This is the user ID for this account (a number), or @code{#f}. In the
+latter case, a number is automatically chosen by the system when the
+account is created.
-@item @code{users} (default: @code{%base-user-accounts})
-@itemx @code{groups} (default: @var{%base-groups})
-List of user accounts and groups. @xref{User Accounts}.
+@item @code{comment} (default: @code{""})
+A comment about the account, such as the account owner's full name.
-If the @code{users} list lacks a user account with UID@tie{}0, a
-``root'' account with UID@tie{}0 is automatically added.
+@item @code{home-directory}
+This is the name of the home directory for the account.
-@item @code{skeletons} (default: @code{(default-skeletons)})
-A list target file name/file-like object tuples (@pxref{G-Expressions,
-file-like objects}). These are the skeleton files that will be added to
-the home directory of newly-created user accounts.
+@item @code{create-home-directory?} (default: @code{#t})
+Indicates whether the home directory of this account should be created
+if it does not exist yet.
-For instance, a valid value may look like this:
+@item @code{shell} (default: Bash)
+This is a G-expression denoting the file name of a program to be used as
+the shell (@pxref{G-Expressions}).
-@example
-`((".bashrc" ,(plain-file "bashrc" "echo Hello\n"))
- (".guile" ,(plain-file "guile"
- "(use-modules (ice-9 readline))
- (activate-readline)")))
-@end example
+@item @code{system?} (default: @code{#f})
+This Boolean value indicates whether the account is a ``system''
+account. System accounts are sometimes treated specially; for instance,
+graphical login managers do not list them.
-@item @code{issue} (default: @var{%default-issue})
-A string denoting the contents of the @file{/etc/issue} file, which is
-displayed when users log in on a text console.
+@anchor{user-account-password}
+@cindex password, for user accounts
+@item @code{password} (default: @code{#f})
+You would normally leave this field to @code{#f}, initialize user
+passwords as @code{root} with the @command{passwd} command, and then let
+users change it with @command{passwd}. Passwords set with
+@command{passwd} are of course preserved across reboot and
+reconfiguration.
-@item @code{packages} (default: @var{%base-packages})
-The set of packages installed in the global profile, which is accessible
-at @file{/run/current-system/profile}.
+If you @emph{do} want to set an initial password for an account, then
+this field must contain the encrypted password, as a string. You can use the
+@code{crypt} procedure for this purpose:
-The default set includes core utilities and it is good practice to
-install non-core utilities in user profiles (@pxref{Invoking guix
-package}).
+@example
+(user-account
+ (name "charlie")
+ (home-directory "/home/charlie")
+ (group "users")
-@item @code{timezone}
-A timezone identifying string---e.g., @code{"Europe/Paris"}.
+ ;; Specify a SHA-512-hashed initial password.
+ (password (crypt "InitialPassword!" "$6$abc")))
+@end example
-You can run the @command{tzselect} command to find out which timezone
-string corresponds to your region. Choosing an invalid timezone name
-causes @command{guix system} to fail.
+@quotation Note
+The hash of this initial password will be available in a file in
+@file{/gnu/store}, readable by all the users, so this method must be used with
+care.
+@end quotation
-@item @code{locale} (default: @code{"en_US.utf8"})
-The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
-Library Reference Manual}). @xref{Locales}, for more information.
+@xref{Passphrase Storage,,, libc, The GNU C Library Reference Manual}, for
+more information on password encryption, and @ref{Encryption,,, guile, GNU
+Guile Reference Manual}, for information on Guile's @code{crypt} procedure.
-@item @code{locale-definitions} (default: @var{%default-locale-definitions})
-The list of locale definitions to be compiled and that may be used at
-run time. @xref{Locales}.
+@end table
+@end deftp
-@item @code{locale-libcs} (default: @code{(list @var{glibc})})
-The list of GNU@tie{}libc packages whose locale data and tools are used
-to build the locale definitions. @xref{Locales}, for compatibility
-considerations that justify this option.
+@cindex groups
+User group declarations are even simpler:
-@item @code{name-service-switch} (default: @var{%default-nss})
-Configuration of the libc name service switch (NSS)---a
-@code{<name-service-switch>} object. @xref{Name Service Switch}, for
-details.
+@example
+(user-group (name "students"))
+@end example
-@item @code{services} (default: @var{%base-services})
-A list of service objects denoting system services. @xref{Services}.
+@deftp {Data Type} user-group
+This type is for, well, user groups. There are just a few fields:
-@item @code{pam-services} (default: @code{(base-pam-services)})
-@cindex PAM
-@cindex pluggable authentication modules
-Linux @dfn{pluggable authentication module} (PAM) services.
-@c FIXME: Add xref to PAM services section.
+@table @asis
+@item @code{name}
+The name of the group.
-@item @code{setuid-programs} (default: @var{%setuid-programs})
-List of string-valued G-expressions denoting setuid programs.
-@xref{Setuid Programs}.
+@item @code{id} (default: @code{#f})
+The group identifier (a number). If @code{#f}, a new number is
+automatically allocated when the group is created.
-@item @code{sudoers-file} (default: @var{%sudoers-specification})
-@cindex sudoers file
-The contents of the @file{/etc/sudoers} file as a file-like object
-(@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
+@item @code{system?} (default: @code{#f})
+This Boolean value indicates whether the group is a ``system'' group.
+System groups have low numerical IDs.
-This file specifies which users can use the @command{sudo} command, what
-they are allowed to do, and what privileges they may gain. The default
-is that only @code{root} and members of the @code{wheel} group may use
-@code{sudo}.
+@item @code{password} (default: @code{#f})
+What, user groups can have a password? Well, apparently yes. Unless
+@code{#f}, this field specifies the password of the group.
@end table
@end deftp
-@node File Systems
-@subsection File Systems
+For convenience, a variable lists all the basic user groups one may
+expect:
-The list of file systems to be mounted is specified in the
-@code{file-systems} field of the operating system declaration
-(@pxref{Using the Configuration System}). Each file system is declared
-using the @code{file-system} form, like this:
+@defvr {Scheme Variable} %base-groups
+This is the list of basic user groups that users and/or packages expect
+to be present on the system. This includes groups such as ``root'',
+``wheel'', and ``users'', as well as groups used to control access to
+specific devices such as ``audio'', ``disk'', and ``cdrom''.
+@end defvr
-@example
-(file-system
- (mount-point "/home")
- (device "/dev/sda3")
- (type "ext4"))
-@end example
+@defvr {Scheme Variable} %base-user-accounts
+This is the list of basic system accounts that programs may expect to
+find on a GNU/Linux system, such as the ``nobody'' account.
-As usual, some of the fields are mandatory---those shown in the example
-above---while others can be omitted. These are described below.
+Note that the ``root'' account is not included here. It is a
+special-case and is automatically added whether or not it is specified.
+@end defvr
-@deftp {Data Type} file-system
-Objects of this type represent file systems to be mounted. They
-contain the following members:
+@node Locales
+@section Locales
-@table @asis
-@item @code{type}
-This is a string specifying the type of the file system---e.g.,
-@code{"ext4"}.
+@cindex locale
+A @dfn{locale} defines cultural conventions for a particular language
+and region of the world (@pxref{Locales,,, libc, The GNU C Library
+Reference Manual}). Each locale has a name that typically has the form
+@code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
+@code{fr_LU.utf8} designates the locale for the French language, with
+cultural conventions from Luxembourg, and using the UTF-8 encoding.
-@item @code{mount-point}
-This designates the place where the file system is to be mounted.
+@cindex locale definition
+Usually, you will want to specify the default locale for the machine
+using the @code{locale} field of the @code{operating-system} declaration
+(@pxref{operating-system Reference, @code{locale}}).
-@item @code{device}
-This names the ``source'' of the file system. It can be one of three
-things: a file system label, a file system UUID, or the name of a
-@file{/dev} node. Labels and UUIDs offer a way to refer to file
-systems without having to hard-code their actual device
-name@footnote{Note that, while it is tempting to use
-@file{/dev/disk/by-uuid} and similar device names to achieve the same
-result, this is not recommended: These special device nodes are created
-by the udev daemon and may be unavailable at the time the device is
-mounted.}.
+The selected locale is automatically added to the @dfn{locale
+definitions} known to the system if needed, with its codeset inferred
+from its name---e.g., @code{bo_CN.utf8} will be assumed to use the
+@code{UTF-8} codeset. Additional locale definitions can be specified in
+the @code{locale-definitions} slot of @code{operating-system}---this is
+useful, for instance, if the codeset could not be inferred from the
+locale name. The default set of locale definitions includes some widely
+used locales, but not all the available locales, in order to save space.
-@findex file-system-label
-File system labels are created using the @code{file-system-label}
-procedure, UUIDs are created using @code{uuid}, and @file{/dev} node are
-plain strings. Here's an example of a file system referred to by its
-label, as shown by the @command{e2label} command:
+For instance, to add the North Frisian locale for Germany, the value of
+that field may be:
@example
-(file-system
- (mount-point "/home")
- (type "ext4")
- (device (file-system-label "my-home")))
+(cons (locale-definition
+ (name "fy_DE.utf8") (source "fy_DE"))
+ %default-locale-definitions)
@end example
-@findex uuid
-UUIDs are converted from their string representation (as shown by the
-@command{tune2fs -l} command) using the @code{uuid} form@footnote{The
-@code{uuid} form expects 16-byte UUIDs as defined in
-@uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. This is the
-form of UUID used by the ext2 family of file systems and others, but it
-is different from ``UUIDs'' found in FAT file systems, for instance.},
-like this:
+Likewise, to save space, one might want @code{locale-definitions} to
+list only the locales that are actually used, as in:
@example
-(file-system
- (mount-point "/home")
- (type "ext4")
- (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
+(list (locale-definition
+ (name "ja_JP.eucjp") (source "ja_JP")
+ (charset "EUC-JP")))
@end example
-When the source of a file system is a mapped device (@pxref{Mapped
-Devices}), its @code{device} field @emph{must} refer to the mapped
-device name---e.g., @file{"/dev/mapper/root-partition"}.
-This is required so that
-the system knows that mounting the file system depends on having the
-corresponding device mapping established.
-
-@item @code{flags} (default: @code{'()})
-This is a list of symbols denoting mount flags. Recognized flags
-include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
-access to special files), @code{no-suid} (ignore setuid and setgid
-bits), and @code{no-exec} (disallow program execution.)
-
-@item @code{options} (default: @code{#f})
-This is either @code{#f}, or a string denoting mount options.
+@vindex LOCPATH
+The compiled locale definitions are available at
+@file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
+version, which is the default location where the GNU@tie{}libc provided
+by Guix looks for locale data. This can be overridden using the
+@code{LOCPATH} environment variable (@pxref{locales-and-locpath,
+@code{LOCPATH} and locale packages}).
-@item @code{mount?} (default: @code{#t})
-This value indicates whether to automatically mount the file system when
-the system is brought up. When set to @code{#f}, the file system gets
-an entry in @file{/etc/fstab} (read by the @command{mount} command) but
-is not automatically mounted.
+The @code{locale-definition} form is provided by the @code{(gnu system
+locale)} module. Details are given below.
-@item @code{needed-for-boot?} (default: @code{#f})
-This Boolean value indicates whether the file system is needed when
-booting. If that is true, then the file system is mounted when the
-initial RAM disk (initrd) is loaded. This is always the case, for
-instance, for the root file system.
+@deftp {Data Type} locale-definition
+This is the data type of a locale definition.
-@item @code{check?} (default: @code{#t})
-This Boolean indicates whether the file system needs to be checked for
-errors before being mounted.
+@table @asis
-@item @code{create-mount-point?} (default: @code{#f})
-When true, the mount point is created if it does not exist yet.
+@item @code{name}
+The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
+Reference Manual}, for more information on locale names.
-@item @code{dependencies} (default: @code{'()})
-This is a list of @code{<file-system>} or @code{<mapped-device>} objects
-representing file systems that must be mounted or mapped devices that
-must be opened before (and unmounted or closed after) this one.
+@item @code{source}
+The name of the source for that locale. This is typically the
+@code{@var{language}_@var{territory}} part of the locale name.
-As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is
-a dependency of @file{/sys/fs/cgroup/cpu} and
-@file{/sys/fs/cgroup/memory}.
+@item @code{charset} (default: @code{"UTF-8"})
+The ``character set'' or ``code set'' for that locale,
+@uref{http://www.iana.org/assignments/character-sets, as defined by
+IANA}.
-Another example is a file system that depends on a mapped device, for
-example for an encrypted partition (@pxref{Mapped Devices}).
@end table
@end deftp
-The @code{(gnu system file-systems)} exports the following useful
-variables.
-
-@defvr {Scheme Variable} %base-file-systems
-These are essential file systems that are required on normal systems,
-such as @var{%pseudo-terminal-file-system} and @var{%immutable-store} (see
-below.) Operating system declarations should always contain at least
-these.
-@end defvr
-
-@defvr {Scheme Variable} %pseudo-terminal-file-system
-This is the file system to be mounted as @file{/dev/pts}. It supports
-@dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
-functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
-Manual}). Pseudo-terminals are used by terminal emulators such as
-@command{xterm}.
-@end defvr
+@defvr {Scheme Variable} %default-locale-definitions
+A list of commonly used UTF-8 locales, used as the default
+value of the @code{locale-definitions} field of @code{operating-system}
+declarations.
-@defvr {Scheme Variable} %shared-memory-file-system
-This file system is mounted as @file{/dev/shm} and is used to support
-memory sharing across processes (@pxref{Memory-mapped I/O,
-@code{shm_open},, libc, The GNU C Library Reference Manual}).
+@cindex locale name
+@cindex normalized codeset in locale names
+These locale definitions use the @dfn{normalized codeset} for the part
+that follows the dot in the name (@pxref{Using gettextized software,
+normalized codeset,, libc, The GNU C Library Reference Manual}). So for
+instance it has @code{uk_UA.utf8} but @emph{not}, say,
+@code{uk_UA.UTF-8}.
@end defvr
-@defvr {Scheme Variable} %immutable-store
-This file system performs a read-only ``bind mount'' of
-@file{/gnu/store}, making it read-only for all the users including
-@code{root}. This prevents against accidental modification by software
-running as @code{root} or by system administrators.
+@subsection Locale Data Compatibility Considerations
-The daemon itself is still able to write to the store: it remounts it
-read-write in its own ``name space.''
-@end defvr
+@cindex incompatibility, of locale data
+@code{operating-system} declarations provide a @code{locale-libcs} field
+to specify the GNU@tie{}libc packages that are used to compile locale
+declarations (@pxref{operating-system Reference}). ``Why would I
+care?'', you may ask. Well, it turns out that the binary format of
+locale data is occasionally incompatible from one libc version to
+another.
-@defvr {Scheme Variable} %binary-format-file-system
-The @code{binfmt_misc} file system, which allows handling of arbitrary
-executable file types to be delegated to user space. This requires the
-@code{binfmt.ko} kernel module to be loaded.
-@end defvr
+@c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
+@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
+For instance, a program linked against libc version 2.21 is unable to
+read locale data produced with libc 2.22; worse, that program
+@emph{aborts} instead of simply ignoring the incompatible locale
+data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
+the incompatible locale data, which is already an improvement.}.
+Similarly, a program linked against libc 2.22 can read most, but not
+all, of the locale data from libc 2.21 (specifically, @code{LC_COLLATE}
+data is incompatible); thus calls to @code{setlocale} may fail, but
+programs will not abort.
-@defvr {Scheme Variable} %fuse-control-file-system
-The @code{fusectl} file system, which allows unprivileged users to mount
-and unmount user-space FUSE file systems. This requires the
-@code{fuse.ko} kernel module to be loaded.
-@end defvr
+The ``problem'' with Guix is that users have a lot of freedom: They can
+choose whether and when to upgrade software in their profiles, and might
+be using a libc version different from the one the system administrator
+used to build the system-wide locale data.
-@node Mapped Devices
-@subsection Mapped Devices
+Fortunately, unprivileged users can also install their own locale data
+and define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
+@code{GUIX_LOCPATH} and locale packages}).
-@cindex device mapping
-@cindex mapped devices
-The Linux kernel has a notion of @dfn{device mapping}: a block device,
-such as a hard disk partition, can be @dfn{mapped} into another device,
-usually in @code{/dev/mapper/},
-with additional processing over the data that flows through
-it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
-concept of a ``mapped device'' and that of a file system: both boil down
-to @emph{translating} input/output operations made on a file to
-operations on its backing store. Thus, the Hurd implements mapped
-devices, like file systems, using the generic @dfn{translator} mechanism
-(@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
-typical example is encryption device mapping: all writes to the mapped
-device are encrypted, and all reads are deciphered, transparently.
-Guix extends this notion by considering any device or set of devices that
-are @dfn{transformed} in some way to create a new device; for instance,
-RAID devices are obtained by @dfn{assembling} several other devices, such
-as hard disks or partitions, into a new one that behaves as one partition.
-Other examples, not yet implemented, are LVM logical volumes.
+Still, it is best if the system-wide locale data at
+@file{/run/current-system/locale} is built for all the libc versions
+actually in use on the system, so that all the programs can access
+it---this is especially crucial on a multi-user system. To do that, the
+administrator can specify several libc packages in the
+@code{locale-libcs} field of @code{operating-system}:
-Mapped devices are declared using the @code{mapped-device} form,
-defined as follows; for examples, see below.
+@example
+(use-package-modules base)
-@deftp {Data Type} mapped-device
-Objects of this type represent device mappings that will be made when
-the system boots up.
+(operating-system
+ ;; @dots{}
+ (locale-libcs (list glibc-2.21 (canonical-package glibc))))
+@end example
-@table @code
-@item source
-This is either a string specifying the name of the block device to be mapped,
-such as @code{"/dev/sda3"}, or a list of such strings when several devices
-need to be assembled for creating a new one.
+This example would lead to a system containing locale definitions for
+both libc 2.21 and the current version of libc in
+@file{/run/current-system/locale}.
-@item target
-This string specifies the name of the resulting mapped device. For
-kernel mappers such as encrypted devices of type @code{luks-device-mapping},
-specifying @code{"my-partition"} leads to the creation of
-the @code{"/dev/mapper/my-partition"} device.
-For RAID devices of type @code{raid-device-mapping}, the full device name
-such as @code{"/dev/md0"} needs to be given.
-@item type
-This must be a @code{mapped-device-kind} object, which specifies how
-@var{source} is mapped to @var{target}.
-@end table
-@end deftp
+@node Services
+@section Services
-@defvr {Scheme Variable} luks-device-mapping
-This defines LUKS block device encryption using the @command{cryptsetup}
-command from the package with the same name. It relies on the
-@code{dm-crypt} Linux kernel module.
-@end defvr
+@cindex system services
+An important part of preparing an @code{operating-system} declaration is
+listing @dfn{system services} and their configuration (@pxref{Using the
+Configuration System}). System services are typically daemons launched
+when the system boots, or other actions needed at that time---e.g.,
+configuring network access.
-@defvr {Scheme Variable} raid-device-mapping
-This defines a RAID device, which is assembled using the @code{mdadm}
-command from the package with the same name. It requires a Linux kernel
-module for the appropriate RAID level to be loaded, such as @code{raid456}
-for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
-@end defvr
+Guix has a broad definition of ``service'' (@pxref{Service
+Composition}), but many services are managed by the GNU@tie{}Shepherd
+(@pxref{Shepherd Services}). On a running system, the @command{herd}
+command allows you to list the available services, show their status,
+start and stop them, or do other specific operations (@pxref{Jump
+Start,,, shepherd, The GNU Shepherd Manual}). For example:
-@cindex disk encryption
-@cindex LUKS
-The following example specifies a mapping from @file{/dev/sda3} to
-@file{/dev/mapper/home} using LUKS---the
-@url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, a
-standard mechanism for disk encryption.
-The @file{/dev/mapper/home}
-device can then be used as the @code{device} of a @code{file-system}
-declaration (@pxref{File Systems}).
+@example
+# herd status
+@end example
+
+The above command, run as @code{root}, lists the currently defined
+services. The @command{herd doc} command shows a synopsis of the given
+service and its associated actions:
@example
-(mapped-device
- (source "/dev/sda3")
- (target "home")
- (type luks-device-mapping))
+# herd doc nscd
+Run libc's name service cache daemon (nscd).
+
+# herd doc nscd action invalidate
+invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.
@end example
-Alternatively, to become independent of device numbering, one may obtain
-the LUKS UUID (@dfn{unique identifier}) of the source device by a
-command like:
+The @command{start}, @command{stop}, and @command{restart} sub-commands
+have the effect you would expect. For instance, the commands below stop
+the nscd service and restart the Xorg display server:
@example
-cryptsetup luksUUID /dev/sda3
+# herd stop nscd
+Service nscd has been stopped.
+# herd restart xorg-server
+Service xorg-server has been stopped.
+Service xorg-server has been started.
@end example
-and use it as follows:
+The following sections document the available services, starting with
+the core services, that may be used in an @code{operating-system}
+declaration.
+
+@menu
+* Base Services:: Essential system services.
+* Scheduled Job Execution:: The mcron service.
+* Log Rotation:: The rottlog service.
+* Networking Services:: Network setup, SSH daemon, etc.
+* X Window:: Graphical display.
+* Printing Services:: Local and remote printer support.
+* Desktop Services:: D-Bus and desktop services.
+* Sound Services:: ALSA and Pulseaudio services.
+* Database Services:: SQL databases, key-value stores, etc.
+* Mail Services:: IMAP, POP3, SMTP, and all that.
+* Messaging Services:: Messaging services.
+* Telephony Services:: Telephony services.
+* Monitoring Services:: Monitoring services.
+* Kerberos Services:: Kerberos services.
+* LDAP Services:: LDAP services.
+* Web Services:: Web servers.
+* Certificate Services:: TLS certificates via Let's Encrypt.
+* DNS Services:: DNS daemons.
+* VPN Services:: VPN daemons.
+* Network File System:: NFS related services.
+* Continuous Integration:: The Cuirass service.
+* Power Management Services:: Extending battery life.
+* Audio Services:: The MPD.
+* Virtualization Services:: Virtualization services.
+* Version Control Services:: Providing remote access to Git repositories.
+* Game Services:: Game servers.
+* Miscellaneous Services:: Other services.
+@end menu
+
+@node Base Services
+@subsection Base Services
+
+The @code{(gnu services base)} module provides definitions for the basic
+services that one expects from the system. The services exported by
+this module are listed below.
+
+@defvr {Scheme Variable} %base-services
+This variable contains a list of basic services (@pxref{Service Types
+and Services}, for more information on service objects) one would
+expect from the system: a login service (mingetty) on each tty, syslogd,
+the libc name service cache daemon (nscd), the udev device manager, and
+more.
+
+This is the default value of the @code{services} field of
+@code{operating-system} declarations. Usually, when customizing a
+system, you will want to append services to @var{%base-services}, like
+this:
@example
-(mapped-device
- (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
- (target "home")
- (type luks-device-mapping))
+(append (list (service avahi-service-type)
+ (service openssh-service-type))
+ %base-services)
@end example
+@end defvr
-@cindex swap encryption
-It is also desirable to encrypt swap space, since swap space may contain
-sensitive data. One way to accomplish that is to use a swap file in a
-file system on a device mapped via LUKS encryption. In this way, the
-swap file is encrypted because the entire device is encrypted.
-@xref{Preparing for Installation,,Disk Partitioning}, for an example.
+@defvr {Scheme Variable} special-files-service-type
+This is the service that sets up ``special files'' such as
+@file{/bin/sh}; an instance of it is part of @code{%base-services}.
-A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
-may be declared as follows:
+The value associated with @code{special-files-service-type} services
+must be a list of tuples where the first element is the ``special file''
+and the second element is its target. By default it is:
+@cindex @file{/bin/sh}
+@cindex @file{sh}, in @file{/bin}
@example
-(mapped-device
- (source (list "/dev/sda1" "/dev/sdb1"))
- (target "/dev/md0")
- (type raid-device-mapping))
+`(("/bin/sh" ,(file-append @var{bash} "/bin/sh")))
@end example
-The @file{/dev/md0} device can then be used as the @code{device} of a
-@code{file-system} declaration (@pxref{File Systems}).
-Note that the RAID level need not be given; it is chosen during the
-initial creation and formatting of the RAID device and is determined
-automatically later.
+@cindex @file{/usr/bin/env}
+@cindex @file{env}, in @file{/usr/bin}
+If you want to add, say, @code{/usr/bin/env} to your system, you can
+change it to:
+
+@example
+`(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))
+ ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env")))
+@end example
+Since this is part of @code{%base-services}, you can use
+@code{modify-services} to customize the set of special files
+(@pxref{Service Reference, @code{modify-services}}). But the simple way
+to add a special file is @i{via} the @code{extra-special-file} procedure
+(see below.)
+@end defvr
-@node User Accounts
-@subsection User Accounts
+@deffn {Scheme Procedure} extra-special-file @var{file} @var{target}
+Use @var{target} as the ``special file'' @var{file}.
-@cindex users
-@cindex accounts
-@cindex user accounts
-User accounts and groups are entirely managed through the
-@code{operating-system} declaration. They are specified with the
-@code{user-account} and @code{user-group} forms:
+For example, adding the following lines to the @code{services} field of
+your operating system declaration leads to a @file{/usr/bin/env}
+symlink:
@example
-(user-account
- (name "alice")
- (group "users")
- (supplementary-groups '("wheel" ;allow use of sudo, etc.
- "audio" ;sound card
- "video" ;video devices such as webcams
- "cdrom")) ;the good ol' CD-ROM
- (comment "Bob's sister")
- (home-directory "/home/alice"))
+(extra-special-file "/usr/bin/env"
+ (file-append coreutils "/bin/env"))
@end example
+@end deffn
-When booting or upon completion of @command{guix system reconfigure},
-the system ensures that only the user accounts and groups specified in
-the @code{operating-system} declaration exist, and with the specified
-properties. Thus, account or group creations or modifications made by
-directly invoking commands such as @command{useradd} are lost upon
-reconfiguration or reboot. This ensures that the system remains exactly
-as declared.
+@deffn {Scheme Procedure} host-name-service @var{name}
+Return a service that sets the host name to @var{name}.
+@end deffn
-@deftp {Data Type} user-account
-Objects of this type represent user accounts. The following members may
-be specified:
+@deffn {Scheme Procedure} login-service @var{config}
+Return a service to run login according to @var{config}, a
+@code{<login-configuration>} object, which specifies the message of the day,
+among other things.
+@end deffn
+
+@deftp {Data Type} login-configuration
+This is the data type representing the configuration of login.
@table @asis
-@item @code{name}
-The name of the user account.
-@item @code{group}
-@cindex groups
-This is the name (a string) or identifier (a number) of the user group
-this account belongs to.
+@item @code{motd}
+@cindex message of the day
+A file-like object containing the ``message of the day''.
-@item @code{supplementary-groups} (default: @code{'()})
-Optionally, this can be defined as a list of group names that this
-account belongs to.
+@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{uid} (default: @code{#f})
-This is the user ID for this account (a number), or @code{#f}. In the
-latter case, a number is automatically chosen by the system when the
-account is created.
+@end table
+@end deftp
-@item @code{comment} (default: @code{""})
-A comment about the account, such as the account owner's full name.
+@deffn {Scheme Procedure} mingetty-service @var{config}
+Return a service to run mingetty according to @var{config}, a
+@code{<mingetty-configuration>} object, which specifies the tty to run, among
+other things.
+@end deffn
-@item @code{home-directory}
-This is the name of the home directory for the account.
+@deftp {Data Type} mingetty-configuration
+This is the data type representing the configuration of Mingetty, which
+provides the default implementation of virtual console log-in.
-@item @code{create-home-directory?} (default: @code{#t})
-Indicates whether the home directory of this account should be created
-if it does not exist yet.
+@table @asis
-@item @code{shell} (default: Bash)
-This is a G-expression denoting the file name of a program to be used as
-the shell (@pxref{G-Expressions}).
+@item @code{tty}
+The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
-@item @code{system?} (default: @code{#f})
-This Boolean value indicates whether the account is a ``system''
-account. System accounts are sometimes treated specially; for instance,
-graphical login managers do not list them.
+@item @code{auto-login} (default: @code{#f})
+When true, this field must be a string denoting the user name under
+which the system automatically logs in. When it is @code{#f}, a
+user name and password must be entered to log in.
-@anchor{user-account-password}
-@item @code{password} (default: @code{#f})
-You would normally leave this field to @code{#f}, initialize user
-passwords as @code{root} with the @command{passwd} command, and then let
-users change it with @command{passwd}. Passwords set with
-@command{passwd} are of course preserved across reboot and
-reconfiguration.
+@item @code{login-program} (default: @code{#f})
+This must be either @code{#f}, in which case the default log-in program
+is used (@command{login} from the Shadow tool suite), or a gexp denoting
+the name of the log-in program.
+
+@item @code{login-pause?} (default: @code{#f})
+When set to @code{#t} in conjunction with @var{auto-login}, the user
+will have to press a key before the log-in shell is launched.
-If you @emph{do} want to have a preset password for an account, then
-this field must contain the encrypted password, as a string.
-@xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
-on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
-Manual}, for information on Guile's @code{crypt} procedure.
+@item @code{mingetty} (default: @var{mingetty})
+The Mingetty package to use.
@end table
@end deftp
-@cindex groups
-User group declarations are even simpler:
-
-@example
-(user-group (name "students"))
-@end example
+@deffn {Scheme Procedure} agetty-service @var{config}
+Return a service to run agetty according to @var{config}, an
+@code{<agetty-configuration>} object, which specifies the tty to run,
+among other things.
+@end deffn
-@deftp {Data Type} user-group
-This type is for, well, user groups. There are just a few fields:
+@deftp {Data Type} agetty-configuration
+This is the data type representing the configuration of agetty, which
+implements virtual and serial console log-in. See the @code{agetty(8)}
+man page for more information.
@table @asis
-@item @code{name}
-The name of the group.
-@item @code{id} (default: @code{#f})
-The group identifier (a number). If @code{#f}, a new number is
-automatically allocated when the group is created.
+@item @code{tty}
+The name of the console this agetty runs on, as a string---e.g.,
+@code{"ttyS0"}. This argument is optional, it will default to
+a reasonable default serial port used by the kernel Linux.
-@item @code{system?} (default: @code{#f})
-This Boolean value indicates whether the group is a ``system'' group.
-System groups have low numerical IDs.
+For this, if there is a value for an option @code{agetty.tty} in the kernel
+command line, agetty will extract the device name of the serial port
+from it and use that.
-@item @code{password} (default: @code{#f})
-What, user groups can have a password? Well, apparently yes. Unless
-@code{#f}, this field specifies the password of the group.
+If not and if there is a value for an option @code{console} with a tty in
+the Linux command line, agetty will extract the device name of the
+serial port from it and use that.
-@end table
-@end deftp
+In both cases, agetty will leave the other serial device settings
+(baud rate etc.)@: alone---in the hope that Linux pinned them to the
+correct values.
-For convenience, a variable lists all the basic user groups one may
-expect:
+@item @code{baud-rate} (default: @code{#f})
+A string containing a comma-separated list of one or more baud rates, in
+descending order.
-@defvr {Scheme Variable} %base-groups
-This is the list of basic user groups that users and/or packages expect
-to be present on the system. This includes groups such as ``root'',
-``wheel'', and ``users'', as well as groups used to control access to
-specific devices such as ``audio'', ``disk'', and ``cdrom''.
-@end defvr
+@item @code{term} (default: @code{#f})
+A string containing the value used for the @code{TERM} environment
+variable.
-@defvr {Scheme Variable} %base-user-accounts
-This is the list of basic system accounts that programs may expect to
-find on a GNU/Linux system, such as the ``nobody'' account.
+@item @code{eight-bits?} (default: @code{#f})
+When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection is
+disabled.
-Note that the ``root'' account is not included here. It is a
-special-case and is automatically added whether or not it is specified.
-@end defvr
+@item @code{auto-login} (default: @code{#f})
+When passed a login name, as a string, the specified user will be logged
+in automatically without prompting for their login name or password.
-@node Locales
-@subsection Locales
+@item @code{no-reset?} (default: @code{#f})
+When @code{#t}, don't reset terminal cflags (control modes).
-@cindex locale
-A @dfn{locale} defines cultural conventions for a particular language
-and region of the world (@pxref{Locales,,, libc, The GNU C Library
-Reference Manual}). Each locale has a name that typically has the form
-@code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
-@code{fr_LU.utf8} designates the locale for the French language, with
-cultural conventions from Luxembourg, and using the UTF-8 encoding.
+@item @code{host} (default: @code{#f})
+This accepts a string containing the "login_host", which will be written
+into the @file{/var/run/utmpx} file.
-@cindex locale definition
-Usually, you will want to specify the default locale for the machine
-using the @code{locale} field of the @code{operating-system} declaration
-(@pxref{operating-system Reference, @code{locale}}).
+@item @code{remote?} (default: @code{#f})
+When set to @code{#t} in conjunction with @var{host}, this will add an
+@code{-r} fakehost option to the command line of the login program
+specified in @var{login-program}.
-The selected locale is automatically added to the @dfn{locale
-definitions} known to the system if needed, with its codeset inferred
-from its name---e.g., @code{bo_CN.utf8} will be assumed to use the
-@code{UTF-8} codeset. Additional locale definitions can be specified in
-the @code{locale-definitions} slot of @code{operating-system}---this is
-useful, for instance, if the codeset could not be inferred from the
-locale name. The default set of locale definitions includes some widely
-used locales, but not all the available locales, in order to save space.
+@item @code{flow-control?} (default: @code{#f})
+When set to @code{#t}, enable hardware (RTS/CTS) flow control.
-For instance, to add the North Frisian locale for Germany, the value of
-that field may be:
+@item @code{no-issue?} (default: @code{#f})
+When set to @code{#t}, the contents of the @file{/etc/issue} file will
+not be displayed before presenting the login prompt.
-@example
-(cons (locale-definition
- (name "fy_DE.utf8") (source "fy_DE"))
- %default-locale-definitions)
-@end example
+@item @code{init-string} (default: @code{#f})
+This accepts a string that will be sent to the tty or modem before
+sending anything else. It can be used to initialize a modem.
-Likewise, to save space, one might want @code{locale-definitions} to
-list only the locales that are actually used, as in:
+@item @code{no-clear?} (default: @code{#f})
+When set to @code{#t}, agetty will not clear the screen before showing
+the login prompt.
-@example
-(list (locale-definition
- (name "ja_JP.eucjp") (source "ja_JP")
- (charset "EUC-JP")))
-@end example
+@item @code{login-program} (default: (file-append shadow "/bin/login"))
+This must be either a gexp denoting the name of a log-in program, or
+unset, in which case the default value is the @command{login} from the
+Shadow tool suite.
-@vindex LOCPATH
-The compiled locale definitions are available at
-@file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
-version, which is the default location where the GNU@tie{}libc provided
-by Guix looks for locale data. This can be overridden using the
-@code{LOCPATH} environment variable (@pxref{locales-and-locpath,
-@code{LOCPATH} and locale packages}).
+@item @code{local-line} (default: @code{#f})
+Control the CLOCAL line flag. This accepts one of three symbols as
+arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f},
+the default value chosen by agetty is @code{'auto}.
-The @code{locale-definition} form is provided by the @code{(gnu system
-locale)} module. Details are given below.
+@item @code{extract-baud?} (default: @code{#f})
+When set to @code{#t}, instruct agetty to try to extract the baud rate
+from the status messages produced by certain types of modems.
-@deftp {Data Type} locale-definition
-This is the data type of a locale definition.
+@item @code{skip-login?} (default: @code{#f})
+When set to @code{#t}, do not prompt the user for a login name. This
+can be used with @var{login-program} field to use non-standard login
+systems.
-@table @asis
+@item @code{no-newline?} (default: @code{#f})
+When set to @code{#t}, do not print a newline before printing the
+@file{/etc/issue} file.
-@item @code{name}
-The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
-Reference Manual}, for more information on locale names.
+@c Is this dangerous only when used with login-program, or always?
+@item @code{login-options} (default: @code{#f})
+This option accepts a string containing options that are passed to the
+login program. When used with the @var{login-program}, be aware that a
+malicious user could try to enter a login name containing embedded
+options that could be parsed by the login program.
-@item @code{source}
-The name of the source for that locale. This is typically the
-@code{@var{language}_@var{territory}} part of the locale name.
+@item @code{login-pause} (default: @code{#f})
+When set to @code{#t}, wait for any key before showing the login prompt.
+This can be used in conjunction with @var{auto-login} to save memory by
+lazily spawning shells.
-@item @code{charset} (default: @code{"UTF-8"})
-The ``character set'' or ``code set'' for that locale,
-@uref{http://www.iana.org/assignments/character-sets, as defined by
-IANA}.
+@item @code{chroot} (default: @code{#f})
+Change root to the specified directory. This option accepts a directory
+path as a string.
-@end table
-@end deftp
+@item @code{hangup?} (default: @code{#f})
+Use the Linux system call @code{vhangup} to do a virtual hangup of the
+specified terminal.
-@defvr {Scheme Variable} %default-locale-definitions
-A list of commonly used UTF-8 locales, used as the default
-value of the @code{locale-definitions} field of @code{operating-system}
-declarations.
+@item @code{keep-baud?} (default: @code{#f})
+When set to @code{#t}, try to keep the existing baud rate. The baud
+rates from @var{baud-rate} are used when agetty receives a @key{BREAK}
+character.
-@cindex locale name
-@cindex normalized codeset in locale names
-These locale definitions use the @dfn{normalized codeset} for the part
-that follows the dot in the name (@pxref{Using gettextized software,
-normalized codeset,, libc, The GNU C Library Reference Manual}). So for
-instance it has @code{uk_UA.utf8} but @emph{not}, say,
-@code{uk_UA.UTF-8}.
-@end defvr
+@item @code{timeout} (default: @code{#f})
+When set to an integer value, terminate if no user name could be read
+within @var{timeout} seconds.
-@subsubsection Locale Data Compatibility Considerations
+@item @code{detect-case?} (default: @code{#f})
+When set to @code{#t}, turn on support for detecting an uppercase-only
+terminal. This setting will detect a login name containing only
+uppercase letters as indicating an uppercase-only terminal and turn on
+some upper-to-lower case conversions. Note that this will not support
+Unicode characters.
-@cindex incompatibility, of locale data
-@code{operating-system} declarations provide a @code{locale-libcs} field
-to specify the GNU@tie{}libc packages that are used to compile locale
-declarations (@pxref{operating-system Reference}). ``Why would I
-care?'', you may ask. Well, it turns out that the binary format of
-locale data is occasionally incompatible from one libc version to
-another.
+@item @code{wait-cr?} (default: @code{#f})
+When set to @code{#t}, wait for the user or modem to send a
+carriage-return or linefeed character before displaying
+@file{/etc/issue} or login prompt. This is typically used with the
+@var{init-string} option.
-@c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
-@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
-For instance, a program linked against libc version 2.21 is unable to
-read locale data produced with libc 2.22; worse, that program
-@emph{aborts} instead of simply ignoring the incompatible locale
-data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
-the incompatible locale data, which is already an improvement.}.
-Similarly, a program linked against libc 2.22 can read most, but not
-all, of the locale data from libc 2.21 (specifically, @code{LC_COLLATE}
-data is incompatible); thus calls to @code{setlocale} may fail, but
-programs will not abort.
+@item @code{no-hints?} (default: @code{#f})
+When set to @code{#t}, do not print hints about Num, Caps, and Scroll
+locks.
-The ``problem'' in GuixSD is that users have a lot of freedom: They can
-choose whether and when to upgrade software in their profiles, and might
-be using a libc version different from the one the system administrator
-used to build the system-wide locale data.
+@item @code{no-hostname?} (default: @code{#f})
+By default, the hostname is printed. When this option is set to
+@code{#t}, no hostname will be shown at all.
-Fortunately, unprivileged users can also install their own locale data
-and define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
-@code{GUIX_LOCPATH} and locale packages}).
+@item @code{long-hostname?} (default: @code{#f})
+By default, the hostname is only printed until the first dot. When this
+option is set to @code{#t}, the fully qualified hostname by
+@code{gethostname} or @code{getaddrinfo} is shown.
-Still, it is best if the system-wide locale data at
-@file{/run/current-system/locale} is built for all the libc versions
-actually in use on the system, so that all the programs can access
-it---this is especially crucial on a multi-user system. To do that, the
-administrator can specify several libc packages in the
-@code{locale-libcs} field of @code{operating-system}:
+@item @code{erase-characters} (default: @code{#f})
+This option accepts a string of additional characters that should be
+interpreted as backspace when the user types their login name.
-@example
-(use-package-modules base)
+@item @code{kill-characters} (default: @code{#f})
+This option accepts a string that should be interpreted to mean "ignore
+all previous characters" (also called a "kill" character) when the types
+their login name.
-(operating-system
- ;; @dots{}
- (locale-libcs (list glibc-2.21 (canonical-package glibc))))
-@end example
+@item @code{chdir} (default: @code{#f})
+This option accepts, as a string, a directory path that will be changed
+to before login.
-This example would lead to a system containing locale definitions for
-both libc 2.21 and the current version of libc in
-@file{/run/current-system/locale}.
+@item @code{delay} (default: @code{#f})
+This options accepts, as an integer, the number of seconds to sleep
+before opening the tty and displaying the login prompt.
+@item @code{nice} (default: @code{#f})
+This option accepts, as an integer, the nice value with which to run the
+@command{login} program.
-@node Services
-@subsection Services
+@item @code{extra-options} (default: @code{'()})
+This option provides an "escape hatch" for the user to provide arbitrary
+command-line arguments to @command{agetty} as a list of strings.
-@cindex system services
-An important part of preparing an @code{operating-system} declaration is
-listing @dfn{system services} and their configuration (@pxref{Using the
-Configuration System}). System services are typically daemons launched
-when the system boots, or other actions needed at that time---e.g.,
-configuring network access.
+@end table
+@end deftp
-GuixSD has a broad definition of ``service'' (@pxref{Service
-Composition}), but many services are managed by the GNU@tie{}Shepherd
-(@pxref{Shepherd Services}). On a running system, the @command{herd}
-command allows you to list the available services, show their status,
-start and stop them, or do other specific operations (@pxref{Jump
-Start,,, shepherd, The GNU Shepherd Manual}). For example:
+@deffn {Scheme Procedure} kmscon-service-type @var{config}
+Return a service to run @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}
+according to @var{config}, a @code{<kmscon-configuration>} object, which
+specifies the tty to run, among other things.
+@end deffn
-@example
-# herd status
-@end example
+@deftp {Data Type} kmscon-configuration
+This is the data type representing the configuration of Kmscon, which
+implements virtual console log-in.
-The above command, run as @code{root}, lists the currently defined
-services. The @command{herd doc} command shows a synopsis of the given
-service and its associated actions:
+@table @asis
-@example
-# herd doc nscd
-Run libc's name service cache daemon (nscd).
+@item @code{virtual-terminal}
+The name of the console this Kmscon runs on---e.g., @code{"tty1"}.
-# herd doc nscd action invalidate
-invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.
-@end example
+@item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
+A gexp denoting the name of the log-in program. The default log-in program is
+@command{login} from the Shadow tool suite.
-The @command{start}, @command{stop}, and @command{restart} sub-commands
-have the effect you would expect. For instance, the commands below stop
-the nscd service and restart the Xorg display server:
+@item @code{login-arguments} (default: @code{'("-p")})
+A list of arguments to pass to @command{login}.
-@example
-# herd stop nscd
-Service nscd has been stopped.
-# herd restart xorg-server
-Service xorg-server has been stopped.
-Service xorg-server has been started.
-@end example
+@item @code{auto-login} (default: @code{#f})
+When passed a login name, as a string, the specified user will be logged
+in automatically without prompting for their login name or password.
-The following sections document the available services, starting with
-the core services, that may be used in an @code{operating-system}
-declaration.
+@item @code{hardware-acceleration?} (default: #f)
+Whether to use hardware acceleration.
-@menu
-* Base Services:: Essential system services.
-* Scheduled Job Execution:: The mcron service.
-* Log Rotation:: The rottlog service.
-* Networking Services:: Network setup, SSH daemon, etc.
-* X Window:: Graphical display.
-* Printing Services:: Local and remote printer support.
-* Desktop Services:: D-Bus and desktop services.
-* Sound Services:: ALSA and Pulseaudio services.
-* Database Services:: SQL databases, key-value stores, etc.
-* Mail Services:: IMAP, POP3, SMTP, and all that.
-* Messaging Services:: Messaging services.
-* Telephony Services:: Telephony services.
-* Monitoring Services:: Monitoring services.
-* Kerberos Services:: Kerberos services.
-* Web Services:: Web servers.
-* Certificate Services:: TLS certificates via Let's Encrypt.
-* DNS Services:: DNS daemons.
-* VPN Services:: VPN daemons.
-* Network File System:: NFS related services.
-* Continuous Integration:: The Cuirass service.
-* Power Management Services:: Extending battery life.
-* Audio Services:: The MPD.
-* Virtualization Services:: Virtualization services.
-* Version Control Services:: Providing remote access to Git repositories.
-* Game Services:: Game servers.
-* Miscellaneous Services:: Other services.
-@end menu
+@item @code{kmscon} (default: @var{kmscon})
+The Kmscon package to use.
-@node Base Services
-@subsubsection Base Services
+@end table
+@end deftp
-The @code{(gnu services base)} module provides definitions for the basic
-services that one expects from the system. The services exported by
-this module are listed below.
+@cindex name service cache daemon
+@cindex nscd
+@deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
+ [#:name-services '()]
+Return a service that runs the libc name service cache daemon (nscd) with the
+given @var{config}---an @code{<nscd-configuration>} object. @xref{Name
+Service Switch}, for an example.
-@defvr {Scheme Variable} %base-services
-This variable contains a list of basic services (@pxref{Service Types
-and Services}, for more information on service objects) one would
-expect from the system: a login service (mingetty) on each tty, syslogd,
-the libc name service cache daemon (nscd), the udev device manager, and
-more.
+For convenience, the Shepherd service for nscd provides the following actions:
-This is the default value of the @code{services} field of
-@code{operating-system} declarations. Usually, when customizing a
-system, you will want to append services to @var{%base-services}, like
-this:
+@table @code
+@item invalidate
+@cindex cache invalidation, nscd
+@cindex nscd, cache invalidation
+This invalidate the given cache. For instance, running:
@example
-(cons* (avahi-service) (lsh-service) %base-services)
+herd invalidate nscd hosts
@end example
+
+@noindent
+invalidates the host name lookup cache of nscd.
+
+@item statistics
+Running @command{herd statistics nscd} displays information about nscd usage
+and caches.
+@end table
+
+@end deffn
+
+@defvr {Scheme Variable} %nscd-default-configuration
+This is the default @code{<nscd-configuration>} value (see below) used
+by @code{nscd-service}. It uses the caches defined by
+@var{%nscd-default-caches}; see below.
@end defvr
-@defvr {Scheme Variable} special-files-service-type
-This is the service that sets up ``special files'' such as
-@file{/bin/sh}; an instance of it is part of @code{%base-services}.
+@deftp {Data Type} nscd-configuration
+This is the data type representing the name service cache daemon (nscd)
+configuration.
-The value associated with @code{special-files-service-type} services
-must be a list of tuples where the first element is the ``special file''
-and the second element is its target. By default it is:
+@table @asis
-@cindex @file{/bin/sh}
-@cindex @file{sh}, in @file{/bin}
-@example
-`(("/bin/sh" ,(file-append @var{bash} "/bin/sh")))
-@end example
+@item @code{name-services} (default: @code{'()})
+List of packages denoting @dfn{name services} that must be visible to
+the nscd---e.g., @code{(list @var{nss-mdns})}.
-@cindex @file{/usr/bin/env}
-@cindex @file{env}, in @file{/usr/bin}
-If you want to add, say, @code{/usr/bin/env} to your system, you can
-change it to:
+@item @code{glibc} (default: @var{glibc})
+Package object denoting the GNU C Library providing the @command{nscd}
+command.
-@example
-`(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))
- ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env")))
-@end example
+@item @code{log-file} (default: @code{"/var/log/nscd.log"})
+Name of the nscd log file. This is where debugging output goes when
+@code{debug-level} is strictly positive.
-Since this is part of @code{%base-services}, you can use
-@code{modify-services} to customize the set of special files
-(@pxref{Service Reference, @code{modify-services}}). But the simple way
-to add a special file is @i{via} the @code{extra-special-file} procedure
-(see below.)
-@end defvr
+@item @code{debug-level} (default: @code{0})
+Integer denoting the debugging levels. Higher numbers mean that more
+debugging output is logged.
-@deffn {Scheme Procedure} extra-special-file @var{file} @var{target}
-Use @var{target} as the ``special file'' @var{file}.
+@item @code{caches} (default: @var{%nscd-default-caches})
+List of @code{<nscd-cache>} objects denoting things to be cached; see
+below.
-For example, adding the following lines to the @code{services} field of
-your operating system declaration leads to a @file{/usr/bin/env}
-symlink:
+@end table
+@end deftp
-@example
-(extra-special-file "/usr/bin/env"
- (file-append coreutils "/bin/env"))
-@end example
-@end deffn
+@deftp {Data Type} nscd-cache
+Data type representing a cache database of nscd and its parameters.
-@deffn {Scheme Procedure} host-name-service @var{name}
-Return a service that sets the host name to @var{name}.
-@end deffn
+@table @asis
-@deffn {Scheme Procedure} login-service @var{config}
-Return a service to run login according to @var{config}, a
-@code{<login-configuration>} object, which specifies the message of the day,
-among other things.
-@end deffn
+@item @code{database}
+This is a symbol representing the name of the database to be cached.
+Valid values are @code{passwd}, @code{group}, @code{hosts}, and
+@code{services}, which designate the corresponding NSS database
+(@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
-@deftp {Data Type} login-configuration
-This is the data type representing the configuration of login.
+@item @code{positive-time-to-live}
+@itemx @code{negative-time-to-live} (default: @code{20})
+A number representing the number of seconds during which a positive or
+negative lookup result remains in cache.
-@table @asis
+@item @code{check-files?} (default: @code{#t})
+Whether to check for updates of the files corresponding to
+@var{database}.
-@item @code{motd}
-@cindex message of the day
-A file-like object containing the ``message of the day''.
+For instance, when @var{database} is @code{hosts}, setting this flag
+instructs nscd to check for updates in @file{/etc/hosts} and to take
+them into account.
-@item @code{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{persistent?} (default: @code{#t})
+Whether the cache should be stored persistently on disk.
-@end table
-@end deftp
+@item @code{shared?} (default: @code{#t})
+Whether the cache should be shared among users.
-@deffn {Scheme Procedure} mingetty-service @var{config}
-Return a service to run mingetty according to @var{config}, a
-@code{<mingetty-configuration>} object, which specifies the tty to run, among
-other things.
-@end deffn
+@item @code{max-database-size} (default: 32@tie{}MiB)
+Maximum size in bytes of the database cache.
-@deftp {Data Type} mingetty-configuration
-This is the data type representing the configuration of Mingetty, which
-provides the default implementation of virtual console log-in.
+@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
+@c settings, so leave them out.
-@table @asis
+@end table
+@end deftp
-@item @code{tty}
-The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
+@defvr {Scheme Variable} %nscd-default-caches
+List of @code{<nscd-cache>} objects used by default by
+@code{nscd-configuration} (see above).
-@item @code{auto-login} (default: @code{#f})
-When true, this field must be a string denoting the user name under
-which the system automatically logs in. When it is @code{#f}, a
-user name and password must be entered to log in.
+It enables persistent and aggressive caching of service and host name
+lookups. The latter provides better host name lookup performance,
+resilience in the face of unreliable name servers, and also better
+privacy---often the result of host name lookups is in local cache, so
+external name servers do not even need to be queried.
+@end defvr
-@item @code{login-program} (default: @code{#f})
-This must be either @code{#f}, in which case the default log-in program
-is used (@command{login} from the Shadow tool suite), or a gexp denoting
-the name of the log-in program.
+@anchor{syslog-configuration-type}
+@cindex syslog
+@cindex logging
+@deftp {Data Type} syslog-configuration
+This data type represents the configuration of the syslog daemon.
-@item @code{login-pause?} (default: @code{#f})
-When set to @code{#t} in conjunction with @var{auto-login}, the user
-will have to press a key before the log-in shell is launched.
+@table @asis
+@item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")})
+The syslog daemon to use.
-@item @code{mingetty} (default: @var{mingetty})
-The Mingetty package to use.
+@item @code{config-file} (default: @code{%default-syslog.conf})
+The syslog configuration file to use.
@end table
@end deftp
-@deffn {Scheme Procedure} agetty-service @var{config}
-Return a service to run agetty according to @var{config}, an
-@code{<agetty-configuration>} object, which specifies the tty to run,
-among other things.
+@anchor{syslog-service}
+@cindex syslog
+@deffn {Scheme Procedure} syslog-service @var{config}
+Return a service that runs a syslog daemon according to @var{config}.
+
+@xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more
+information on the configuration file syntax.
@end deffn
-@deftp {Data Type} agetty-configuration
-This is the data type representing the configuration of agetty, which
-implements virtual and serial console log-in. See the @code{agetty(8)}
-man page for more information.
+@defvr {Scheme Variable} guix-service-type
+This is the type of the service that runs the build daemon,
+@command{guix-daemon} (@pxref{Invoking guix-daemon}). Its value must be a
+@code{guix-configuration} record as described below.
+@end defvr
+
+@anchor{guix-configuration-type}
+@deftp {Data Type} guix-configuration
+This data type represents the configuration of the Guix build daemon.
+@xref{Invoking guix-daemon}, for more information.
@table @asis
+@item @code{guix} (default: @var{guix})
+The Guix package to use.
-@item @code{tty}
-The name of the console this agetty runs on, as a string---e.g.,
-@code{"ttyS0"}. This argument is optional, it will default to
-a reasonable default serial port used by the kernel Linux.
+@item @code{build-group} (default: @code{"guixbuild"})
+Name of the group for build user accounts.
-For this, if there is a value for an option @code{agetty.tty} in the kernel
-command line, agetty will extract the device name of the serial port
-from it and use that.
+@item @code{build-accounts} (default: @code{10})
+Number of build user accounts to create.
-If not and if there is a value for an option @code{console} with a tty in
-the Linux command line, agetty will extract the device name of the
-serial port from it and use that.
+@item @code{authorize-key?} (default: @code{#t})
+@cindex substitutes, authorization thereof
+Whether to authorize the substitute keys listed in
+@code{authorized-keys}---by default that of @code{@value{SUBSTITUTE-SERVER}}
+(@pxref{Substitutes}).
-In both cases, agetty will leave the other serial device settings
-(baud rate etc.)@: alone---in the hope that Linux pinned them to the
-correct values.
+@vindex %default-authorized-guix-keys
+@item @code{authorized-keys} (default: @var{%default-authorized-guix-keys})
+The list of authorized key files for archive imports, as a list of
+string-valued gexps (@pxref{Invoking guix archive}). By default, it
+contains that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitutes}).
-@item @code{baud-rate} (default: @code{#f})
-A string containing a comma-separated list of one or more baud rates, in
-descending order.
+@item @code{use-substitutes?} (default: @code{#t})
+Whether to use substitutes.
-@item @code{term} (default: @code{#f})
-A string containing the value used for the @code{TERM} environment
-variable.
+@item @code{substitute-urls} (default: @var{%default-substitute-urls})
+The list of URLs where to look for substitutes by default.
-@item @code{eight-bits?} (default: @code{#f})
-When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection is
-disabled.
+@item @code{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,
+respectively, after which a build process times out. A value of zero
+disables the timeout.
-@item @code{auto-login} (default: @code{#f})
-When passed a login name, as a string, the specified user will be logged
-in automatically without prompting for their login name or password.
+@item @code{log-compression} (default: @code{'bzip2})
+The type of compression used for build logs---one of @code{gzip},
+@code{bzip2}, or @code{none}.
-@item @code{no-reset?} (default: @code{#f})
-When @code{#t}, don't reset terminal cflags (control modes).
+@item @code{extra-options} (default: @code{'()})
+List of extra command-line options for @command{guix-daemon}.
-@item @code{host} (default: @code{#f})
-This accepts a string containing the "login_host", which will be written
-into the @file{/var/run/utmpx} file.
+@item @code{log-file} (default: @code{"/var/log/guix-daemon.log"})
+File where @command{guix-daemon}'s standard output and standard error
+are written.
-@item @code{remote?} (default: @code{#f})
-When set to @code{#t} in conjunction with @var{host}, this will add an
-@code{-r} fakehost option to the command line of the login program
-specified in @var{login-program}.
+@item @code{http-proxy} (default: @code{#f})
+The HTTP proxy used for downloading fixed-output derivations and
+substitutes.
-@item @code{flow-control?} (default: @code{#f})
-When set to @code{#t}, enable hardware (RTS/CTS) flow control.
+@item @code{tmpdir} (default: @code{#f})
+A directory path where the @command{guix-daemon} will perform builds.
-@item @code{no-issue?} (default: @code{#f})
-When set to @code{#t}, the contents of the @file{/etc/issue} file will
-not be displayed before presenting the login prompt.
+@end table
+@end deftp
-@item @code{init-string} (default: @code{#f})
-This accepts a string that will be sent to the tty or modem before
-sending anything else. It can be used to initialize a modem.
+@deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
+Run @var{udev}, which populates the @file{/dev} directory dynamically.
+udev rules can be provided as a list of files through the @var{rules}
+variable. The procedures @var{udev-rule} and @var{file->udev-rule} from
+@code{(gnu services base)} simplify the creation of such rule files.
+@end deffn
-@item @code{no-clear?} (default: @code{#f})
-When set to @code{#t}, agetty will not clear the screen before showing
-the login prompt.
+@deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}]
+Return a udev-rule file named @var{file-name} containing the rules
+defined by the @var{contents} literal.
-@item @code{login-program} (default: (file-append shadow "/bin/login"))
-This must be either a gexp denoting the name of a log-in program, or
-unset, in which case the default value is the @command{login} from the
-Shadow tool suite.
+In the following example, a rule for a USB device is defined to be
+stored in the file @file{90-usb-thing.rules}. The rule runs a script
+upon detecting a USB device with a given product identifier.
-@item @code{local-line} (default: @code{#f})
-Control the CLOCAL line flag. This accepts one of three symbols as
-arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f},
-the default value chosen by agetty is @code{'auto}.
+@example
+(define %example-udev-rule
+ (udev-rule
+ "90-usb-thing.rules"
+ (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
+ "ATTR@{product@}==\"Example\", "
+ "RUN+=\"/path/to/script\"")))
+@end example
-@item @code{extract-baud?} (default: @code{#f})
-When set to @code{#t}, instruct agetty to try to extract the baud rate
-from the status messages produced by certain types of modems.
+The @command{herd rules udev} command, as root, returns the name of the
+directory containing all the active udev rules.
+@end deffn
-@item @code{skip-login?} (default: @code{#f})
-When set to @code{#t}, do not prompt the user for a login name. This
-can be used with @var{login-program} field to use non-standard login
-systems.
+Here we show how the default @var{udev-service} can be extended with it.
+
+@example
+(operating-system
+ ;; @dots{}
+ (services
+ (modify-services %desktop-services
+ (udev-service-type config =>
+ (udev-configuration (inherit config)
+ (rules (append (udev-configuration-rules config)
+ (list %example-udev-rule))))))))
+@end example
+
+@deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}]
+Return a udev file named @var{file-name} containing the rules defined
+within @var{file}, a file-like object.
+
+The following example showcases how we can use an existing rule file.
+
+@example
+(use-modules (guix download) ;for url-fetch
+ (guix packages) ;for origin
+ ;; @dots{})
+
+(define %android-udev-rules
+ (file->udev-rule
+ "51-android-udev.rules"
+ (let ((version "20170910"))
+ (origin
+ (method url-fetch)
+ (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
+ "android-udev-rules/" version "/51-android.rules"))
+ (sha256
+ (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))
+@end example
+@end deffn
-@item @code{no-newline?} (default: @code{#f})
-When set to @code{#t}, do not print a newline before printing the
-@file{/etc/issue} file.
+Additionally, Guix package definitions can be included in @var{rules} in
+order to extend the udev rules with the definitions found under their
+@file{lib/udev/rules.d} sub-directory. In lieu of the previous
+@var{file->udev-rule} example, we could have used the
+@var{android-udev-rules} package which exists in Guix in the @code{(gnu
+packages android)} module.
-@c Is this dangerous only when used with login-program, or always?
-@item @code{login-options} (default: @code{#f})
-This option accepts a string containing options that are passed to the
-login program. When used with the @var{login-program}, be aware that a
-malicious user could try to enter a login name containing embedded
-options that could be parsed by the login program.
+The following example shows how to use the @var{android-udev-rules}
+package so that the Android tool @command{adb} can detect devices
+without root privileges. It also details how to create the
+@code{adbusers} group, which is required for the proper functioning of
+the rules defined within the @var{android-udev-rules} package. To
+create such a group, we must define it both as part of the
+@var{supplementary-groups} of our @var{user-account} declaration, as
+well as in the @var{groups} field of the @var{operating-system} record.
-@item @code{login-pause} (default: @code{#f})
-When set to @code{#t}, wait for any key before showing the login prompt.
-This can be used in conjunction with @var{auto-login} to save memory by
-lazily spawning shells.
+@example
+(use-modules (gnu packages android) ;for android-udev-rules
+ (gnu system shadow) ;for user-group
+ ;; @dots{})
-@item @code{chroot} (default: @code{#f})
-Change root to the specified directory. This option accepts a directory
-path as a string.
+(operating-system
+ ;; @dots{}
+ (users (cons (user-acount
+ ;; @dots{}
+ (supplementary-groups
+ '("adbusers" ;for adb
+ "wheel" "netdev" "audio" "video"))
+ ;; @dots{})))
-@item @code{hangup?} (default: @code{#f})
-Use the Linux system call @code{vhangup} to do a virtual hangup of the
-specified terminal.
+ (groups (cons (user-group (system? #t) (name "adbusers"))
+ %base-groups))
-@item @code{keep-baud?} (default: @code{#f})
-When set to @code{#t}, try to keep the existing baud rate. The baud
-rates from @var{baud-rate} are used when agetty receives a @key{BREAK}
-character.
+ ;; @dots{}
-@item @code{timeout} (default: @code{#f})
-When set to an integer value, terminate if no user name could be read
-within @var{timeout} seconds.
+ (services
+ (modify-services %desktop-services
+ (udev-service-type
+ config =>
+ (udev-configuration (inherit config)
+ (rules (cons android-udev-rules
+ (udev-configuration-rules config))))))))
+@end example
-@item @code{detect-case?} (default: @code{#f})
-When set to @code{#t}, turn on support for detecting an uppercase-only
-terminal. This setting will detect a login name containing only
-uppercase letters as indicating an uppercase-only terminal and turn on
-some upper-to-lower case conversions. Note that this will not support
-Unicode characters.
+@defvr {Scheme Variable} urandom-seed-service-type
+Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom}
+when rebooting. It also tries to seed @file{/dev/urandom} from
+@file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is
+readable.
+@end defvr
-@item @code{wait-cr?} (default: @code{#f})
-When set to @code{#t}, wait for the user or modem to send a
-carriage-return or linefeed character before displaying
-@file{/etc/issue} or login prompt. This is typically used with the
-@var{init-string} option.
+@defvr {Scheme Variable} %random-seed-file
+This is the name of the file where some random bytes are saved by
+@var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting.
+It defaults to @file{/var/lib/random-seed}.
+@end defvr
-@item @code{no-hints?} (default: @code{#f})
-When set to @code{#t}, do not print hints about Num, Caps, and Scroll
-locks.
+@cindex keymap
+@cindex keyboard
+@deffn {Scheme Procedure} console-keymap-service @var{files} ...
+@cindex keyboard layout
+Return a service to load console keymaps from @var{files} using
+@command{loadkeys} command. Most likely, you want to load some default
+keymap, which can be done like this:
-@item @code{no-hostname?} (default: @code{#f})
-By default, the hostname is printed. When this option is set to
-@code{#t}, no hostname will be shown at all.
+@example
+(console-keymap-service "dvorak")
+@end example
-@item @code{long-hostname?} (default: @code{#f})
-By default, the hostname is only printed until the first dot. When this
-option is set to @code{#t}, the fully qualified hostname by
-@code{gethostname} or @code{getaddrinfo} is shown.
+Or, for example, for a Swedish keyboard, you may need to combine
+the following keymaps:
+@example
+(console-keymap-service "se-lat6" "se-fi-lat6")
+@end example
-@item @code{erase-characters} (default: @code{#f})
-This option accepts a string of additional characters that should be
-interpreted as backspace when the user types their login name.
+Also you can specify a full file name (or file names) of your keymap(s).
+See @code{man loadkeys} for details.
-@item @code{kill-characters} (default: @code{#f})
-This option accepts a string that should be interpreted to mean "ignore
-all previous characters" (also called a "kill" character) when the types
-their login name.
+@end deffn
-@item @code{chdir} (default: @code{#f})
-This option accepts, as a string, a directory path that will be changed
-to before login.
+@cindex mouse
+@cindex gpm
+@defvr {Scheme Variable} gpm-service-type
+This is the type of the service that runs GPM, the @dfn{general-purpose
+mouse daemon}, which provides mouse support to the Linux console. GPM
+allows users to use the mouse in the console, notably to select, copy,
+and paste text.
-@item @code{delay} (default: @code{#f})
-This options accepts, as an integer, the number of seconds to sleep
-before opening the tty and displaying the login prompt.
+The value for services of this type must be a @code{gpm-configuration}
+(see below). This service is not part of @var{%base-services}.
+@end defvr
-@item @code{nice} (default: @code{#f})
-This option accepts, as an integer, the nice value with which to run the
-@command{login} program.
+@deftp {Data Type} gpm-configuration
+Data type representing the configuration of GPM.
-@item @code{extra-options} (default: @code{'()})
-This option provides an "escape hatch" for the user to provide arbitrary
-command-line arguments to @command{agetty} as a list of strings.
+@table @asis
+@item @code{options} (default: @code{%default-gpm-options})
+Command-line options passed to @command{gpm}. The default set of
+options instruct @command{gpm} to listen to mouse events on
+@file{/dev/input/mice}. @xref{Command Line,,, gpm, gpm manual}, for
+more information.
+
+@item @code{gpm} (default: @code{gpm})
+The GPM package to use.
@end table
@end deftp
-@deffn {Scheme Procedure} kmscon-service-type @var{config}
-Return a service to run @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}
-according to @var{config}, a @code{<kmscon-configuration>} object, which
-specifies the tty to run, among other things.
+@anchor{guix-publish-service-type}
+@deffn {Scheme Variable} guix-publish-service-type
+This is the service type for @command{guix publish} (@pxref{Invoking
+guix publish}). Its value must be a @code{guix-configuration}
+object, as described below.
+
+This assumes that @file{/etc/guix} already contains a signing key pair as
+created by @command{guix archive --generate-key} (@pxref{Invoking guix
+archive}). If that is not the case, the service will fail to start.
@end deffn
-@deftp {Data Type} kmscon-configuration
-This is the data type representing the configuration of Kmscon, which
-implements virtual console log-in.
+@deftp {Data Type} guix-publish-configuration
+Data type representing the configuration of the @code{guix publish}
+service.
@table @asis
+@item @code{guix} (default: @code{guix})
+The Guix package to use.
-@item @code{virtual-terminal}
-The name of the console this Kmscon runs on---e.g., @code{"tty1"}.
+@item @code{port} (default: @code{80})
+The TCP port to listen for connections.
-@item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
-A gexp denoting the name of the log-in program. The default log-in program is
-@command{login} from the Shadow tool suite.
+@item @code{host} (default: @code{"localhost"})
+The host (and thus, network interface) to listen to. Use
+@code{"0.0.0.0"} to listen on all the network interfaces.
-@item @code{login-arguments} (default: @code{'("-p")})
-A list of arguments to pass to @command{login}.
+@item @code{compression-level} (default: @code{3})
+The gzip compression level at which substitutes are compressed. Use
+@code{0} to disable compression altogether, and @code{9} to get the best
+compression ratio at the expense of increased CPU usage.
-@item @code{auto-login} (default: @code{#f})
-When passed a login name, as a string, the specified user will be logged
-in automatically without prompting for their login name or password.
+@item @code{nar-path} (default: @code{"nar"})
+The URL path at which ``nars'' can be fetched. @xref{Invoking guix
+publish, @code{--nar-path}}, for details.
-@item @code{hardware-acceleration?} (default: #f)
-Whether to use hardware acceleration.
+@item @code{cache} (default: @code{#f})
+When it is @code{#f}, disable caching and instead generate archives on
+demand. Otherwise, this should be the name of a directory---e.g.,
+@code{"/var/cache/guix/publish"}---where @command{guix publish} caches
+archives and meta-data ready to be sent. @xref{Invoking guix publish,
+@option{--cache}}, for more information on the tradeoffs involved.
-@item @code{kmscon} (default: @var{kmscon})
-The Kmscon package to use.
+@item @code{workers} (default: @code{#f})
+When it is an integer, this is the number of worker threads used for
+caching; when @code{#f}, the number of processors is used.
+@xref{Invoking guix publish, @option{--workers}}, for more information.
+@item @code{ttl} (default: @code{#f})
+When it is an integer, this denotes the @dfn{time-to-live} in seconds
+of the published archives. @xref{Invoking guix publish, @option{--ttl}},
+for more information.
@end table
@end deftp
-@cindex name service cache daemon
-@cindex nscd
-@deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
- [#:name-services '()]
-Return a service that runs the libc name service cache daemon (nscd) with the
-given @var{config}---an @code{<nscd-configuration>} object. @xref{Name
-Service Switch}, for an example.
-
-For convenience, the Shepherd service for nscd provides the following actions:
+@anchor{rngd-service}
+@deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @
+ [#:device "/dev/hwrng"]
+Return a service that runs the @command{rngd} program from @var{rng-tools}
+to add @var{device} to the kernel's entropy pool. The service will fail if
+@var{device} does not exist.
+@end deffn
-@table @code
-@item invalidate
-@cindex cache invalidation, nscd
-@cindex nscd, cache invalidation
-This invalidate the given cache. For instance, running:
+@anchor{pam-limits-service}
+@cindex session limits
+@cindex ulimit
+@cindex priority
+@cindex realtime
+@cindex jackd
+@deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]
-@example
-herd invalidate nscd hosts
-@end example
+Return a service that installs a configuration file for the
+@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,
+@code{pam_limits} module}. The procedure optionally takes a list of
+@code{pam-limits-entry} values, which can be used to specify
+@code{ulimit} limits and nice priority limits to user sessions.
-@noindent
-invalidates the host name lookup cache of nscd.
+The following limits definition sets two hard and soft limits for all
+login sessions of users in the @code{realtime} group:
-@item statistics
-Running @command{herd statistics nscd} displays information about nscd usage
-and caches.
-@end table
+@example
+(pam-limits-service
+ (list
+ (pam-limits-entry "@@realtime" 'both 'rtprio 99)
+ (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited)))
+@end example
+The first entry increases the maximum realtime priority for
+non-privileged processes; the second entry lifts any restriction of the
+maximum address space that can be locked in memory. These settings are
+commonly used for real-time audio systems.
@end deffn
-@defvr {Scheme Variable} %nscd-default-configuration
-This is the default @code{<nscd-configuration>} value (see below) used
-by @code{nscd-service}. It uses the caches defined by
-@var{%nscd-default-caches}; see below.
-@end defvr
-
-@deftp {Data Type} nscd-configuration
-This is the data type representing the name service cache daemon (nscd)
-configuration.
-
-@table @asis
+@node Scheduled Job Execution
+@subsection Scheduled Job Execution
-@item @code{name-services} (default: @code{'()})
-List of packages denoting @dfn{name services} that must be visible to
-the nscd---e.g., @code{(list @var{nss-mdns})}.
+@cindex cron
+@cindex mcron
+@cindex scheduling jobs
+The @code{(gnu services mcron)} module provides an interface to
+GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
+mcron, GNU@tie{}mcron}). GNU@tie{}mcron is similar to the traditional
+Unix @command{cron} daemon; the main difference is that it is
+implemented in Guile Scheme, which provides a lot of flexibility when
+specifying the scheduling of jobs and their actions.
-@item @code{glibc} (default: @var{glibc})
-Package object denoting the GNU C Library providing the @command{nscd}
-command.
+The example below defines an operating system that runs the
+@command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files})
+and the @command{guix gc} commands (@pxref{Invoking guix gc}) daily, as
+well as the @command{mkid} command on behalf of an unprivileged user
+(@pxref{mkid invocation,,, idutils, ID Database Utilities}). It uses
+gexps to introduce job definitions that are passed to mcron
+(@pxref{G-Expressions}).
-@item @code{log-file} (default: @code{"/var/log/nscd.log"})
-Name of the nscd log file. This is where debugging output goes when
-@code{debug-level} is strictly positive.
+@lisp
+(use-modules (guix) (gnu) (gnu services mcron))
+(use-package-modules base idutils)
-@item @code{debug-level} (default: @code{0})
-Integer denoting the debugging levels. Higher numbers mean that more
-debugging output is logged.
+(define updatedb-job
+ ;; Run 'updatedb' at 3AM every day. Here we write the
+ ;; job's action as a Scheme procedure.
+ #~(job '(next-hour '(3))
+ (lambda ()
+ (execl (string-append #$findutils "/bin/updatedb")
+ "updatedb"
+ "--prunepaths=/tmp /var/tmp /gnu/store"))))
-@item @code{caches} (default: @var{%nscd-default-caches})
-List of @code{<nscd-cache>} objects denoting things to be cached; see
-below.
+(define garbage-collector-job
+ ;; Collect garbage 5 minutes after midnight every day.
+ ;; The job's action is a shell command.
+ #~(job "5 0 * * *" ;Vixie cron syntax
+ "guix gc -F 1G"))
-@end table
-@end deftp
+(define idutils-job
+ ;; Update the index database as user "charlie" at 12:15PM
+ ;; and 19:15PM. This runs from the user's home directory.
+ #~(job '(next-minute-from (next-hour '(12 19)) '(15))
+ (string-append #$idutils "/bin/mkid src")
+ #:user "charlie"))
-@deftp {Data Type} nscd-cache
-Data type representing a cache database of nscd and its parameters.
+(operating-system
+ ;; @dots{}
+ (services (cons (service mcron-service-type
+ (mcron-configuration
+ (jobs (list garbage-collector-job
+ updatedb-job
+ idutils-job))))
+ %base-services)))
+@end lisp
-@table @asis
+@xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron},
+for more information on mcron job specifications. Below is the
+reference of the mcron service.
-@item @code{database}
-This is a symbol representing the name of the database to be cached.
-Valid values are @code{passwd}, @code{group}, @code{hosts}, and
-@code{services}, which designate the corresponding NSS database
-(@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
+On a running system, you can use the @code{schedule} action of the service to
+visualize the mcron jobs that will be executed next:
-@item @code{positive-time-to-live}
-@itemx @code{negative-time-to-live} (default: @code{20})
-A number representing the number of seconds during which a positive or
-negative lookup result remains in cache.
+@example
+# herd schedule mcron
+@end example
-@item @code{check-files?} (default: @code{#t})
-Whether to check for updates of the files corresponding to
-@var{database}.
+@noindent
+The example above lists the next five tasks that will be executed, but you can
+also specify the number of tasks to display:
-For instance, when @var{database} is @code{hosts}, setting this flag
-instructs nscd to check for updates in @file{/etc/hosts} and to take
-them into account.
+@example
+# herd schedule mcron 10
+@end example
-@item @code{persistent?} (default: @code{#t})
-Whether the cache should be stored persistently on disk.
+@defvr {Scheme Variable} mcron-service-type
+This is the type of the @code{mcron} service, whose value is an
+@code{mcron-configuration} object.
-@item @code{shared?} (default: @code{#t})
-Whether the cache should be shared among users.
+This service type can be the target of a service extension that provides
+it additional job specifications (@pxref{Service Composition}). In
+other words, it is possible to define services that provide additional
+mcron jobs to run.
+@end defvr
-@item @code{max-database-size} (default: 32@tie{}MiB)
-Maximum size in bytes of the database cache.
+@deftp {Data Type} mcron-configuration
+Data type representing the configuration of mcron.
-@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
-@c settings, so leave them out.
+@table @asis
+@item @code{mcron} (default: @var{mcron})
+The mcron package to use.
+@item @code{jobs}
+This is a list of gexps (@pxref{G-Expressions}), where each gexp
+corresponds to an mcron job specification (@pxref{Syntax, mcron job
+specifications,, mcron, GNU@tie{}mcron}).
@end table
@end deftp
-@defvr {Scheme Variable} %nscd-default-caches
-List of @code{<nscd-cache>} objects used by default by
-@code{nscd-configuration} (see above).
-It enables persistent and aggressive caching of service and host name
-lookups. The latter provides better host name lookup performance,
-resilience in the face of unreliable name servers, and also better
-privacy---often the result of host name lookups is in local cache, so
-external name servers do not even need to be queried.
-@end defvr
+@node Log Rotation
+@subsection Log Rotation
-@anchor{syslog-configuration-type}
-@cindex syslog
+@cindex rottlog
+@cindex log rotation
@cindex logging
-@deftp {Data Type} syslog-configuration
-This data type represents the configuration of the syslog daemon.
+Log files such as those found in @file{/var/log} tend to grow endlessly,
+so it's a good idea to @dfn{rotate} them once in a while---i.e., archive
+their contents in separate files, possibly compressed. The @code{(gnu
+services admin)} module provides an interface to GNU@tie{}Rot[t]log, a
+log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
-@table @asis
-@item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")})
-The syslog daemon to use.
+The example below defines an operating system that provides log rotation
+with the default settings, for commonly encountered log files.
-@item @code{config-file} (default: @code{%default-syslog.conf})
-The syslog configuration file to use.
+@lisp
+(use-modules (guix) (gnu))
+(use-service-modules admin mcron)
+(use-package-modules base idutils)
-@end table
-@end deftp
+(operating-system
+ ;; @dots{}
+ (services (cons (service rottlog-service-type)
+ %base-services)))
+@end lisp
-@anchor{syslog-service}
-@cindex syslog
-@deffn {Scheme Procedure} syslog-service @var{config}
-Return a service that runs a syslog daemon according to @var{config}.
+@defvr {Scheme Variable} rottlog-service-type
+This is the type of the Rottlog service, whose value is a
+@code{rottlog-configuration} object.
-@xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more
-information on the configuration file syntax.
-@end deffn
+Other services can extend this one with new @code{log-rotation} objects
+(see below), thereby augmenting the set of files to be rotated.
-@defvr {Scheme Variable} guix-service-type
-This is the type of the service that runs the build daemon,
-@command{guix-daemon} (@pxref{Invoking guix-daemon}). Its value must be a
-@code{guix-configuration} record as described below.
+This service type can define mcron jobs (@pxref{Scheduled Job
+Execution}) to run the rottlog service.
@end defvr
-@anchor{guix-configuration-type}
-@deftp {Data Type} guix-configuration
-This data type represents the configuration of the Guix build daemon.
-@xref{Invoking guix-daemon}, for more information.
+@deftp {Data Type} rottlog-configuration
+Data type representing the configuration of rottlog.
@table @asis
-@item @code{guix} (default: @var{guix})
-The Guix package to use.
-
-@item @code{build-group} (default: @code{"guixbuild"})
-Name of the group for build user accounts.
-
-@item @code{build-accounts} (default: @code{10})
-Number of build user accounts to create.
+@item @code{rottlog} (default: @code{rottlog})
+The Rottlog package to use.
-@item @code{authorize-key?} (default: @code{#t})
-@cindex substitutes, authorization thereof
-Whether to authorize the substitute keys listed in
-@code{authorized-keys}---by default that of @code{@value{SUBSTITUTE-SERVER}}
-(@pxref{Substitutes}).
+@item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")})
+The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,,
+rottlog, GNU Rot[t]log Manual}).
-@vindex %default-authorized-guix-keys
-@item @code{authorized-keys} (default: @var{%default-authorized-guix-keys})
-The list of authorized key files for archive imports, as a list of
-string-valued gexps (@pxref{Invoking guix archive}). By default, it
-contains that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitutes}).
+@item @code{rotations} (default: @code{%default-rotations})
+A list of @code{log-rotation} objects as defined below.
-@item @code{use-substitutes?} (default: @code{#t})
-Whether to use substitutes.
+@item @code{jobs}
+This is a list of gexps where each gexp corresponds to an mcron job
+specification (@pxref{Scheduled Job Execution}).
+@end table
+@end deftp
-@item @code{substitute-urls} (default: @var{%default-substitute-urls})
-The list of URLs where to look for substitutes by default.
+@deftp {Data Type} log-rotation
+Data type representing the rotation of a group of log files.
-@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,
-respectively, after which a build process times out. A value of zero
-disables the timeout.
+Taking an example from the Rottlog manual (@pxref{Period Related File
+Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be
+defined like this:
-@item @code{log-compression} (default: @code{'bzip2})
-The type of compression used for build logs---one of @code{gzip},
-@code{bzip2}, or @code{none}.
+@example
+(log-rotation
+ (frequency 'daily)
+ (files '("/var/log/apache/*"))
+ (options '("storedir apache-archives"
+ "rotate 6"
+ "notifempty"
+ "nocompress")))
+@end example
-@item @code{extra-options} (default: @code{'()})
-List of extra command-line options for @command{guix-daemon}.
+The list of fields is as follows:
-@item @code{log-file} (default: @code{"/var/log/guix-daemon.log"})
-File where @command{guix-daemon}'s standard output and standard error
-are written.
+@table @asis
+@item @code{frequency} (default: @code{'weekly})
+The log rotation frequency, a symbol.
-@item @code{http-proxy} (default: @code{#f})
-The HTTP proxy used for downloading fixed-output derivations and
-substitutes.
+@item @code{files}
+The list of files or file glob patterns to rotate.
-@item @code{tmpdir} (default: @code{#f})
-A directory path where the @command{guix-daemon} will perform builds.
+@item @code{options} (default: @code{'()})
+The list of rottlog options for this rotation (@pxref{Configuration
+parameters,,, rottlog, GNU Rot[t]lg Manual}).
+@item @code{post-rotate} (default: @code{#f})
+Either @code{#f} or a gexp to execute once the rotation has completed.
@end table
@end deftp
-@deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
-Run @var{udev}, which populates the @file{/dev} directory dynamically.
-udev rules can be provided as a list of files through the @var{rules}
-variable. The procedures @var{udev-rule} and @var{file->udev-rule} from
-@code{(gnu services base)} simplify the creation of such rule files.
-@end deffn
+@defvr {Scheme Variable} %default-rotations
+Specifies weekly rotation of @var{%rotated-files} and
+a couple of other files.
+@end defvr
-@deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}]
-Return a udev-rule file named @var{file-name} containing the rules
-defined by the @var{contents} literal.
+@defvr {Scheme Variable} %rotated-files
+The list of syslog-controlled files to be rotated. By default it is:
+@code{'("/var/log/messages" "/var/log/secure")}.
+@end defvr
-In the following example, a rule for a USB device is defined to be
-stored in the file @file{90-usb-thing.rules}. The rule runs a script
-upon detecting a USB device with a given product identifier.
+@node Networking Services
+@subsection Networking Services
-@example
-(define %example-udev-rule
- (udev-rule
- "90-usb-thing.rules"
- (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
- "ATTR@{product@}==\"Example\", "
- "RUN+=\"/path/to/script\"")))
-@end example
+The @code{(gnu services networking)} module provides services to configure
+the network interface.
-The @command{herd rules udev} command, as root, returns the name of the
-directory containing all the active udev rules.
-@end deffn
+@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.
+@end defvr
-Here we show how the default @var{udev-service} can be extended with it.
+@deffn {Scheme Procedure} dhcpd-service-type
+This type defines a service that runs a DHCP daemon. To create a
+service of this type, you must supply a @code{<dhcpd-configuration>}.
+For example:
@example
-(operating-system
- ;; @dots{}
- (services
- (modify-services %desktop-services
- (udev-service-type config =>
- (udev-configuration (inherit config)
- (rules (append (udev-configuration-rules config)
- (list %example-udev-rule))))))))
+(service dhcpd-service-type
+ (dhcpd-configuration
+ (config-file (local-file "my-dhcpd.conf"))
+ (interfaces '("enp0s25"))))
@end example
+@end deffn
-@deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}]
-Return a udev file named @var{file-name} containing the rules defined
-within @var{file}, a file-like object.
-
-The following example showcases how we can use an existing rule file.
+@deftp {Data Type} dhcpd-configuration
+@table @asis
+@item @code{package} (default: @code{isc-dhcp})
+The package that provides the DHCP daemon. This package is expected to
+provide the daemon at @file{sbin/dhcpd} relative to its output
+directory. The default package is the
+@uref{http://www.isc.org/products/DHCP, ISC's DHCP server}.
+@item @code{config-file} (default: @code{#f})
+The configuration file to use. This is required. It will be passed to
+@code{dhcpd} via its @code{-cf} option. This may be any ``file-like''
+object (@pxref{G-Expressions, file-like objects}). See @code{man
+dhcpd.conf} for details on the configuration file syntax.
+@item @code{version} (default: @code{"4"})
+The DHCP version to use. The ISC DHCP server supports the values ``4'',
+``6'', and ``4o6''. These correspond to the @code{dhcpd} program
+options @code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for
+details.
+@item @code{run-directory} (default: @code{"/run/dhcpd"})
+The run directory to use. At service activation time, this directory
+will be created if it does not exist.
+@item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"})
+The PID file to use. This corresponds to the @code{-pf} option of
+@code{dhcpd}. See @code{man dhcpd} for details.
+@item @code{interfaces} (default: @code{'()})
+The names of the network interfaces on which dhcpd should listen for
+broadcasts. If this list is not empty, then its elements (which must be
+strings) will be appended to the @code{dhcpd} invocation when starting
+the daemon. It may not be necessary to explicitly specify any
+interfaces here; see @code{man dhcpd} for details.
+@end table
+@end deftp
-@example
-(use-modules (guix download) ;for url-fetch
- (guix packages) ;for origin
- ;; @dots{})
+@defvr {Scheme Variable} static-networking-service-type
+This is the type for statically-configured network interfaces.
+@c TODO Document <static-networking> data structures.
+@end defvr
-(define %android-udev-rules
- (file->udev-rule
- "51-android-udev.rules"
- (let ((version "20170910"))
- (origin
- (method url-fetch)
- (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
- "android-udev-rules/" version "/51-android.rules"))
- (sha256
- (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))
-@end example
-@end deffn
+@deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @
+ [#:netmask #f] [#:gateway #f] [#:name-servers @code{'()}] @
+ [#:requirement @code{'(udev)}]
+Return a service that starts @var{interface} with address @var{ip}. If
+@var{netmask} is true, use it as the network mask. If @var{gateway} is true,
+it must be a string specifying the default network gateway. @var{requirement}
+can be used to declare a dependency on another service before configuring the
+interface.
-Additionally, Guix package definitions can be included in @var{rules} in
-order to extend the udev rules with the definitions found under their
-@file{lib/udev/rules.d} sub-directory. In lieu of the previous
-@var{file->udev-rule} example, we could have used the
-@var{android-udev-rules} package which exists in Guix in the @code{(gnu
-packages android)} module.
+This procedure can be called several times, one for each network
+interface of interest. Behind the scenes what it does is extend
+@code{static-networking-service-type} with additional network interfaces
+to handle.
-The following example shows how to use the @var{android-udev-rules}
-package so that the Android tool @command{adb} can detect devices
-without root privileges. It also details how to create the
-@code{adbusers} group, which is required for the proper functioning of
-the rules defined within the @var{android-udev-rules} package. To
-create such a group, we must define it both as part of the
-@var{supplementary-groups} of our @var{user-account} declaration, as
-well as in the @var{groups} field of the @var{operating-system} record.
+For example:
@example
-(use-modules (gnu packages android) ;for android-udev-rules
- (gnu system shadow) ;for user-group
- ;; @dots{})
-
-(operating-system
- ;; @dots{}
- (users (cons (user-acount
- ;; @dots{}
- (supplementary-groups
- '("adbusers" ;for adb
- "wheel" "netdev" "audio" "video"))
- ;; @dots{})))
+(static-networking-service "eno1" "192.168.1.82"
+ #:gateway "192.168.1.2"
+ #:name-servers '("192.168.1.2"))
+@end example
+@end deffn
- (groups (cons (user-group (system? #t) (name "adbusers"))
- %base-groups))
+@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.
- ;; @dots{}
+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
- (services
- (modify-services %desktop-services
- (udev-service-type config =>
- (udev-configuration (inherit config)
- (rules (cons* android-udev-rules
- (udev-configuration-rules config))))))))
-@end example
+@cindex ModemManager
-@defvr {Scheme Variable} urandom-seed-service-type
-Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom}
-when rebooting. It also tries to seed @file{/dev/urandom} from
-@file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is
-readable.
-@end defvr
+@defvr {Scheme Variable} modem-manager-service-type
+This is the service type for the
+@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager}
+service. The value for this service type is a
+@code{modem-manager-configuration} record.
-@defvr {Scheme Variable} %random-seed-file
-This is the name of the file where some random bytes are saved by
-@var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting.
-It defaults to @file{/var/lib/random-seed}.
+This service is part of @code{%desktop-services} (@pxref{Desktop
+Services}).
@end defvr
-@cindex keymap
-@cindex keyboard
-@deffn {Scheme Procedure} console-keymap-service @var{files} ...
-@cindex keyboard layout
-Return a service to load console keymaps from @var{files} using
-@command{loadkeys} command. Most likely, you want to load some default
-keymap, which can be done like this:
-
-@example
-(console-keymap-service "dvorak")
-@end example
+@deftp {Data Type} modem-manager-configuration
+Data type representing the configuration of ModemManager.
-Or, for example, for a Swedish keyboard, you may need to combine
-the following keymaps:
-@example
-(console-keymap-service "se-lat6" "se-fi-lat6")
-@end example
+@table @asis
+@item @code{modem-manager} (default: @code{modem-manager})
+The ModemManager package to use.
-Also you can specify a full file name (or file names) of your keymap(s).
-See @code{man loadkeys} for details.
+@end table
+@end deftp
-@end deffn
+@cindex NetworkManager
-@cindex mouse
-@cindex gpm
-@defvr {Scheme Variable} gpm-service-type
-This is the type of the service that runs GPM, the @dfn{general-purpose
-mouse daemon}, which provides mouse support to the Linux console. GPM
-allows users to use the mouse in the console, notably to select, copy,
-and paste text.
+@defvr {Scheme Variable} network-manager-service-type
+This is the service type for the
+@uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager}
+service. The value for this service type is a
+@code{network-manager-configuration} record.
-The value for services of this type must be a @code{gpm-configuration}
-(see below). This service is not part of @var{%base-services}.
+This service is part of @code{%desktop-services} (@pxref{Desktop
+Services}).
@end defvr
-@deftp {Data Type} gpm-configuration
-Data type representing the configuration of GPM.
+@deftp {Data Type} network-manager-configuration
+Data type representing the configuration of NetworkManager.
@table @asis
-@item @code{options} (default: @code{%default-gpm-options})
-Command-line options passed to @command{gpm}. The default set of
-options instruct @command{gpm} to listen to mouse events on
-@file{/dev/input/mice}. @xref{Command Line,,, gpm, gpm manual}, for
-more information.
+@item @code{network-manager} (default: @code{network-manager})
+The NetworkManager package to use.
-@item @code{gpm} (default: @code{gpm})
-The GPM package to use.
+@item @code{dns} (default: @code{"default"})
+Processing mode for DNS, which affects how NetworkManager uses the
+@code{resolv.conf} configuration file.
-@end table
-@end deftp
+@table @samp
+@item default
+NetworkManager will update @code{resolv.conf} to reflect the nameservers
+provided by currently active connections.
-@anchor{guix-publish-service-type}
-@deffn {Scheme Variable} guix-publish-service-type
-This is the service type for @command{guix publish} (@pxref{Invoking
-guix publish}). Its value must be a @code{guix-configuration}
-object, as described below.
+@item dnsmasq
+NetworkManager will run @code{dnsmasq} as a local caching nameserver,
+using a "split DNS" configuration if you are connected to a VPN, and
+then update @code{resolv.conf} to point to the local nameserver.
-This assumes that @file{/etc/guix} already contains a signing key pair as
-created by @command{guix archive --generate-key} (@pxref{Invoking guix
-archive}). If that is not the case, the service will fail to start.
-@end deffn
+@item none
+NetworkManager will not modify @code{resolv.conf}.
+@end table
-@deftp {Data Type} guix-publish-configuration
-Data type representing the configuration of the @code{guix publish}
-service.
+@item @code{vpn-plugins} (default: @code{'()})
+This is the list of available plugins for virtual private networks
+(VPNs). An example of this is the @code{network-manager-openvpn}
+package, which allows NetworkManager to manage VPNs @i{via} OpenVPN.
-@table @asis
-@item @code{guix} (default: @code{guix})
-The Guix package to use.
+@end table
+@end deftp
-@item @code{port} (default: @code{80})
-The TCP port to listen for connections.
+@cindex Connman
+@deffn {Scheme Variable} connman-service-type
+This is the service type to run @url{https://01.org/connman,Connman},
+a network connection manager.
-@item @code{host} (default: @code{"localhost"})
-The host (and thus, network interface) to listen to. Use
-@code{"0.0.0.0"} to listen on all the network interfaces.
+Its value must be an
+@code{connman-configuration} record as in this example:
-@item @code{compression-level} (default: @code{3})
-The gzip compression level at which substitutes are compressed. Use
-@code{0} to disable compression altogether, and @code{9} to get the best
-compression ratio at the expense of increased CPU usage.
+@example
+(service connman-service-type
+ (connman-configuration
+ (disable-vpn? #t)))
+@end example
-@item @code{nar-path} (default: @code{"nar"})
-The URL path at which ``nars'' can be fetched. @xref{Invoking guix
-publish, @code{--nar-path}}, for details.
+See below for details about @code{connman-configuration}.
+@end deffn
-@item @code{cache} (default: @code{#f})
-When it is @code{#f}, disable caching and instead generate archives on
-demand. Otherwise, this should be the name of a directory---e.g.,
-@code{"/var/cache/guix/publish"}---where @command{guix publish} caches
-archives and meta-data ready to be sent. @xref{Invoking guix publish,
-@option{--cache}}, for more information on the tradeoffs involved.
+@deftp {Data Type} connman-configuration
+Data Type representing the configuration of connman.
-@item @code{workers} (default: @code{#f})
-When it is an integer, this is the number of worker threads used for
-caching; when @code{#f}, the number of processors is used.
-@xref{Invoking guix publish, @option{--workers}}, for more information.
+@table @asis
+@item @code{connman} (default: @var{connman})
+The connman package to use.
-@item @code{ttl} (default: @code{#f})
-When it is an integer, this denotes the @dfn{time-to-live} in seconds
-of the published archives. @xref{Invoking guix publish, @option{--ttl}},
-for more information.
+@item @code{disable-vpn?} (default: @code{#f})
+When true, disable connman's vpn plugin.
@end table
@end deftp
-@anchor{rngd-service}
-@deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @
- [#:device "/dev/hwrng"]
-Return a service that runs the @command{rngd} program from @var{rng-tools}
-to add @var{device} to the kernel's entropy pool. The service will fail if
-@var{device} does not exist.
-@end deffn
+@cindex WPA Supplicant
+@defvr {Scheme Variable} wpa-supplicant-service-type
+This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA
+supplicant}, an authentication daemon required to authenticate against
+encrypted WiFi or ethernet networks.
+@end defvr
-@anchor{pam-limits-service}
-@cindex session limits
-@cindex ulimit
-@cindex priority
-@cindex realtime
-@cindex jackd
-@deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]
+@deftp {Data Type} wpa-supplicant-configuration
+Data type representing the configuration of WPA Supplicant.
-Return a service that installs a configuration file for the
-@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,
-@code{pam_limits} module}. The procedure optionally takes a list of
-@code{pam-limits-entry} values, which can be used to specify
-@code{ulimit} limits and nice priority limits to user sessions.
+It takes the following parameters:
-The following limits definition sets two hard and soft limits for all
-login sessions of users in the @code{realtime} group:
+@table @asis
+@item @code{wpa-supplicant} (default: @code{wpa-supplicant})
+The WPA Supplicant package to use.
-@example
-(pam-limits-service
- (list
- (pam-limits-entry "@@realtime" 'both 'rtprio 99)
- (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited)))
-@end example
+@item @code{dbus?} (default: @code{#t})
+Whether to listen for requests on D-Bus.
-The first entry increases the maximum realtime priority for
-non-privileged processes; the second entry lifts any restriction of the
-maximum address space that can be locked in memory. These settings are
-commonly used for real-time audio systems.
-@end deffn
+@item @code{pid-file} (default: @code{"/var/run/wpa_supplicant.pid"})
+Where to store the PID file.
-@node Scheduled Job Execution
-@subsubsection Scheduled Job Execution
+@item @code{interface} (default: @code{#f})
+If this is set, it must specify the name of a network interface that
+WPA supplicant will control.
-@cindex cron
-@cindex mcron
-@cindex scheduling jobs
-The @code{(gnu services mcron)} module provides an interface to
-GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
-mcron, GNU@tie{}mcron}). GNU@tie{}mcron is similar to the traditional
-Unix @command{cron} daemon; the main difference is that it is
-implemented in Guile Scheme, which provides a lot of flexibility when
-specifying the scheduling of jobs and their actions.
+@item @code{config-file} (default: @code{#f})
+Optional configuration file to use.
-The example below defines an operating system that runs the
-@command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files})
-and the @command{guix gc} commands (@pxref{Invoking guix gc}) daily, as
-well as the @command{mkid} command on behalf of an unprivileged user
-(@pxref{mkid invocation,,, idutils, ID Database Utilities}). It uses
-gexps to introduce job definitions that are passed to mcron
-(@pxref{G-Expressions}).
+@item @code{extra-options} (default: @code{'()})
+List of additional command-line arguments to pass to the daemon.
+@end table
+@end deftp
+
+@cindex iptables
+@defvr {Scheme Variable} iptables-service-type
+This is the service type to set up an iptables configuration. iptables is a
+packet filtering framework supported by the Linux kernel. This service
+supports configuring iptables for both IPv4 and IPv6. A simple example
+configuration rejecting all incoming connections except those to the ssh port
+22 is shown below.
@lisp
-(use-modules (guix) (gnu) (gnu services mcron))
-(use-package-modules base idutils)
+(service iptables-service-type
+ (iptables-configuration
+ (ipv4-rules (plain-file "iptables.rules" "*filter
+:INPUT ACCEPT
+:FORWARD ACCEPT
+:OUTPUT ACCEPT
+-A INPUT -p tcp --dport 22 -j ACCEPT
+-A INPUT -j REJECT --reject-with icmp-port-unreachable
+COMMIT
+"))
+ (ipv6-rules (plain-file "ip6tables.rules" "*filter
+:INPUT ACCEPT
+:FORWARD ACCEPT
+:OUTPUT ACCEPT
+-A INPUT -p tcp --dport 22 -j ACCEPT
+-A INPUT -j REJECT --reject-with icmp6-port-unreachable
+COMMIT
+"))))
+@end lisp
+@end defvr
-(define updatedb-job
- ;; Run 'updatedb' at 3AM every day. Here we write the
- ;; job's action as a Scheme procedure.
- #~(job '(next-hour '(3))
- (lambda ()
- (execl (string-append #$findutils "/bin/updatedb")
- "updatedb"
- "--prunepaths=/tmp /var/tmp /gnu/store"))))
+@deftp {Data Type} iptables-configuration
+The data type representing the configuration of iptables.
-(define garbage-collector-job
- ;; Collect garbage 5 minutes after midnight every day.
- ;; The job's action is a shell command.
- #~(job "5 0 * * *" ;Vixie cron syntax
- "guix gc -F 1G"))
+@table @asis
+@item @code{iptables} (default: @code{iptables})
+The iptables package that provides @code{iptables-restore} and
+@code{ip6tables-restore}.
+@item @code{ipv4-rules} (default: @code{%iptables-accept-all-rules})
+The iptables rules to use. It will be passed to @code{iptables-restore}.
+This may be any ``file-like'' object (@pxref{G-Expressions, file-like
+objects}).
+@item @code{ipv6-rules} (default: @code{%iptables-accept-all-rules})
+The ip6tables rules to use. It will be passed to @code{ip6tables-restore}.
+This may be any ``file-like'' object (@pxref{G-Expressions, file-like
+objects}).
+@end table
+@end deftp
-(define idutils-job
- ;; Update the index database as user "charlie" at 12:15PM
- ;; and 19:15PM. This runs from the user's home directory.
- #~(job '(next-minute-from (next-hour '(12 19)) '(15))
- (string-append #$idutils "/bin/mkid src")
- #:user "charlie"))
+@cindex NTP (Network Time Protocol), service
+@cindex real time clock
+@defvr {Scheme Variable} ntp-service-type
+This is the type of the service running the @uref{http://www.ntp.org,
+Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep the
+system clock synchronized with that of the specified NTP servers.
+
+The value of this service is an @code{ntpd-configuration} object, as described
+below.
+@end defvr
+
+@deftp {Data Type} ntp-configuration
+This is the data type for the NTP service configuration.
+
+@table @asis
+@item @code{servers} (default: @code{%ntp-servers})
+This is the list of servers (host names) with which @command{ntpd} will be
+synchronized.
-(operating-system
- ;; @dots{}
- (services (cons (service mcron-service-type
- (mcron-configuration
- (jobs (list garbage-collector-job
- updatedb-job
- idutils-job))))
- %base-services)))
-@end lisp
+@item @code{allow-large-adjustment?} (default: @code{#f})
+This determines whether @command{ntpd} is allowed to make an initial
+adjustment of more than 1,000 seconds.
-@xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron},
-for more information on mcron job specifications. Below is the
-reference of the mcron service.
+@item @code{ntp} (default: @code{ntp})
+The NTP package to use.
+@end table
+@end deftp
-On a running system, you can use the @code{schedule} action of the service to
-visualize the mcron jobs that will be executed next:
+@defvr {Scheme Variable} %ntp-servers
+List of host names used as the default NTP servers. These are servers of the
+@uref{https://www.ntppool.org/en/, NTP Pool Project}.
+@end defvr
+
+@cindex OpenNTPD
+@deffn {Scheme Procedure} openntpd-service-type
+Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as implemented
+by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will keep the system
+clock synchronized with that of the given servers.
@example
-# herd schedule mcron
+(service
+ openntpd-service-type
+ (openntpd-configuration
+ (listen-on '("127.0.0.1" "::1"))
+ (sensor '("udcf0 correction 70000"))
+ (constraint-from '("www.gnu.org"))
+ (constraints-from '("https://www.google.com/"))
+ (allow-large-adjustment? #t)))
+
@end example
+@end deffn
-@noindent
-The example above lists the next five tasks that will be executed, but you can
-also specify the number of tasks to display:
+@deftp {Data Type} openntpd-configuration
+@table @asis
+@item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")})
+The openntpd executable to use.
+@item @code{listen-on} (default: @code{'("127.0.0.1" "::1")})
+A list of local IP addresses or hostnames the ntpd daemon should listen on.
+@item @code{query-from} (default: @code{'()})
+A list of local IP address the ntpd daemon should use for outgoing queries.
+@item @code{sensor} (default: @code{'()})
+Specify a list of timedelta sensor devices ntpd should use. @code{ntpd}
+will listen to each sensor that acutally exists and ignore non-existant ones.
+See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
+information.
+@item @code{server} (default: @var{%ntp-servers})
+Specify a list of IP addresses or hostnames of NTP servers to synchronize to.
+@item @code{servers} (default: @code{'()})
+Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
+@item @code{constraint-from} (default: @code{'()})
+@code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers via TLS.
+This time information is not used for precision but acts as an authenticated
+constraint, thereby reducing the impact of unauthenticated NTP
+man-in-the-middle attacks.
+Specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide
+a constraint.
+@item @code{constraints-from} (default: @code{'()})
+As with constraint from, specify a list of URLs, IP addresses or hostnames of
+HTTPS servers to provide a constraint. Should the hostname resolve to multiple
+IP addresses, @code{ntpd} will calculate a median constraint from all of them.
+@item @code{allow-large-adjustment?} (default: @code{#f})
+Determines if @code{ntpd} is allowed to make an initial adjustment of more
+than 180 seconds.
+@end table
+@end deftp
+
+@cindex inetd
+@deffn {Scheme variable} inetd-service-type
+This service runs the @command{inetd} (@pxref{inetd invocation,,,
+inetutils, GNU Inetutils}) daemon. @command{inetd} listens for
+connections on internet sockets, and lazily starts the specified server
+program when a connection is made on one of these sockets.
+
+The value of this service is an @code{inetd-configuration} object. The
+following example configures the @command{inetd} daemon to provide the
+built-in @command{echo} service, as well as an smtp service which
+forwards smtp traffic over ssh to a server @code{smtp-server} behind a
+gateway @code{hostname}:
@example
-# herd schedule mcron 10
+(service
+ inetd-service-type
+ (inetd-configuration
+ (entries (list
+ (inetd-entry
+ (name "echo")
+ (socket-type 'stream)
+ (protocol "tcp")
+ (wait? #f)
+ (user "root"))
+ (inetd-entry
+ (node "127.0.0.1")
+ (name "smtp")
+ (socket-type 'stream)
+ (protocol "tcp")
+ (wait? #f)
+ (user "root")
+ (program (file-append openssh "/bin/ssh"))
+ (arguments
+ '("ssh" "-qT" "-i" "/path/to/ssh_key"
+ "-W" "smtp-server:25" "user@@hostname")))))
@end example
-@defvr {Scheme Variable} mcron-service-type
-This is the type of the @code{mcron} service, whose value is an
-@code{mcron-configuration} object.
-
-This service type can be the target of a service extension that provides
-it additional job specifications (@pxref{Service Composition}). In
-other words, it is possible to define services that provide additional
-mcron jobs to run.
-@end defvr
+See below for more details about @code{inetd-configuration}.
+@end deffn
-@deftp {Data Type} mcron-configuration
-Data type representing the configuration of mcron.
+@deftp {Data Type} inetd-configuration
+Data type representing the configuration of @command{inetd}.
@table @asis
-@item @code{mcron} (default: @var{mcron})
-The mcron package to use.
+@item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")})
+The @command{inetd} executable to use.
-@item @code{jobs}
-This is a list of gexps (@pxref{G-Expressions}), where each gexp
-corresponds to an mcron job specification (@pxref{Syntax, mcron job
-specifications,, mcron, GNU@tie{}mcron}).
+@item @code{entries} (default: @code{'()})
+A list of @command{inetd} service entries. Each entry should be created
+by the @code{inetd-entry} constructor.
@end table
@end deftp
+@deftp {Data Type} inetd-entry
+Data type representing an entry in the @command{inetd} configuration.
+Each entry corresponds to a socket where @command{inetd} will listen for
+requests.
-@node Log Rotation
-@subsubsection Log Rotation
+@table @asis
+@item @code{node} (default: @code{#f})
+Optional string, a comma-separated list of local addresses
+@command{inetd} should use when listening for this service.
+@xref{Configuration file,,, inetutils, GNU Inetutils} for a complete
+description of all options.
+@item @code{name}
+A string, the name must correspond to an entry in @code{/etc/services}.
+@item @code{socket-type}
+One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or
+@code{'seqpacket}.
+@item @code{protocol}
+A string, must correspond to an entry in @code{/etc/protocols}.
+@item @code{wait?} (default: @code{#t})
+Whether @command{inetd} should wait for the server to exit before
+listening to new service requests.
+@item @code{user}
+A string containing the user (and, optionally, group) name of the user
+as whom the server should run. The group name can be specified in a
+suffix, separated by a colon or period, i.e.@: @code{"user"},
+@code{"user:group"} or @code{"user.group"}.
+@item @code{program} (default: @code{"internal"})
+The server program which will serve the requests, or @code{"internal"}
+if @command{inetd} should use a built-in service.
+@item @code{arguments} (default: @code{'()})
+A list strings or file-like objects, which are the server program's
+arguments, starting with the zeroth argument, i.e.@: the name of the
+program itself. For @command{inetd}'s internal services, this entry
+must be @code{'()} or @code{'("internal")}.
+@end table
-@cindex rottlog
-@cindex log rotation
-@cindex logging
-Log files such as those found in @file{/var/log} tend to grow endlessly,
-so it's a good idea to @dfn{rotate} them once in a while---i.e., archive
-their contents in separate files, possibly compressed. The @code{(gnu
-services admin)} module provides an interface to GNU@tie{}Rot[t]log, a
-log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
+@xref{Configuration file,,, inetutils, GNU Inetutils} for a more
+detailed discussion of each configuration field.
+@end deftp
-The example below defines an operating system that provides log rotation
-with the default settings, for commonly encountered log files.
+@cindex Tor
+@defvr {Scheme Variable} tor-service-type
+This is the type for a service that runs the @uref{https://torproject.org,
+Tor} anonymous networking daemon. The service is configured using a
+@code{<tor-configuration>} record. By default, the Tor daemon runs as the
+@code{tor} unprivileged user, which is a member of the @code{tor} group.
-@lisp
-(use-modules (guix) (gnu))
-(use-service-modules admin mcron)
-(use-package-modules base idutils)
+@end defvr
-(operating-system
- ;; @dots{}
- (services (cons (service rottlog-service-type)
- %base-services)))
-@end lisp
+@deftp {Data Type} tor-configuration
+@table @asis
+@item @code{tor} (default: @code{tor})
+The package that provides the Tor daemon. This package is expected to provide
+the daemon at @file{bin/tor} relative to its output directory. The default
+package is the @uref{https://www.torproject.org, Tor Project's}
+implementation.
-@defvr {Scheme Variable} rottlog-service-type
-This is the type of the Rottlog service, whose value is a
-@code{rottlog-configuration} object.
+@item @code{config-file} (default: @code{(plain-file "empty" "")})
+The configuration file to use. It will be appended to a default configuration
+file, and the final configuration file will be passed to @code{tor} via its
+@code{-f} option. This may be any ``file-like'' object (@pxref{G-Expressions,
+file-like objects}). See @code{man tor} for details on the configuration file
+syntax.
-Other services can extend this one with new @code{log-rotation} objects
-(see below), thereby augmenting the set of files to be rotated.
+@item @code{hidden-services} (default: @code{'()})
+The list of @code{<hidden-service>} records to use. For any hidden service
+you include in this list, appropriate configuration to enable the hidden
+service will be automatically added to the default configuration file. You
+may conveniently create @code{<hidden-service>} records using the
+@code{tor-hidden-service} procedure described below.
-This service type can define mcron jobs (@pxref{Scheduled Job
-Execution}) to run the rottlog service.
-@end defvr
+@item @code{socks-socket-type} (default: @code{'tcp})
+The default socket type that Tor should use for its SOCKS socket. This must
+be either @code{'tcp} or @code{'unix}. If it is @code{'tcp}, then by default
+Tor will listen on TCP port 9050 on the loopback interface (i.e., localhost).
+If it is @code{'unix}, then Tor will listen on the UNIX domain socket
+@file{/var/run/tor/socks-sock}, which will be made writable by members of the
+@code{tor} group.
-@deftp {Data Type} rottlog-configuration
-Data type representing the configuration of rottlog.
+If you want to customize the SOCKS socket in more detail, leave
+@code{socks-socket-type} at its default value of @code{'tcp} and use
+@code{config-file} to override the default by providing your own
+@code{SocksPort} option.
+@end table
+@end deftp
+
+@cindex hidden service
+@deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
+Define a new Tor @dfn{hidden service} called @var{name} and implementing
+@var{mapping}. @var{mapping} is a list of port/host tuples, such as:
+
+@example
+ '((22 "127.0.0.1:22")
+ (80 "127.0.0.1:8080"))
+@end example
-@table @asis
-@item @code{rottlog} (default: @code{rottlog})
-The Rottlog package to use.
+In this example, port 22 of the hidden service is mapped to local port 22, and
+port 80 is mapped to local port 8080.
-@item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")})
-The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,,
-rottlog, GNU Rot[t]log Manual}).
+This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, where
+the @file{hostname} file contains the @code{.onion} host name for the hidden
+service.
-@item @code{rotations} (default: @code{%default-rotations})
-A list of @code{log-rotation} objects as defined below.
+See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
+project's documentation} for more information.
+@end deffn
-@item @code{jobs}
-This is a list of gexps where each gexp corresponds to an mcron job
-specification (@pxref{Scheduled Job Execution}).
-@end table
-@end deftp
+The @code{(gnu services rsync)} module provides the following services:
-@deftp {Data Type} log-rotation
-Data type representing the rotation of a group of log files.
+You might want an rsync daemon if you have files that you want available
+so anyone (or just yourself) can download existing files or upload new
+files.
-Taking an example from the Rottlog manual (@pxref{Period Related File
-Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be
-defined like this:
+@deffn {Scheme Variable} rsync-service-type
+This is the type for the @uref{https://rsync.samba.org, rsync} rsync daemon,
+@command{rsync-configuration} record as in this example:
@example
-(log-rotation
- (frequency 'daily)
- (files '("/var/log/apache/*"))
- (options '("storedir apache-archives"
- "rotate 6"
- "notifempty"
- "nocompress")))
+(service rsync-service-type)
@end example
-The list of fields is as follows:
+See below for details about @code{rsync-configuration}.
+@end deffn
+
+@deftp {Data Type} rsync-configuration
+Data type representing the configuration for @code{rsync-service}.
@table @asis
-@item @code{frequency} (default: @code{'weekly})
-The log rotation frequency, a symbol.
+@item @code{package} (default: @var{rsync})
+@code{rsync} package to use.
-@item @code{files}
-The list of files or file glob patterns to rotate.
+@item @code{port-number} (default: @code{873})
+TCP port on which @command{rsync} listens for incoming connections. If port
+is less than @code{1024} @command{rsync} needs to be started as the
+@code{root} user and group.
-@item @code{options} (default: @code{'()})
-The list of rottlog options for this rotation (@pxref{Configuration
-parameters,,, rottlog, GNU Rot[t]lg Manual}).
+@item @code{pid-file} (default: @code{"/var/run/rsyncd/rsyncd.pid"})
+Name of the file where @command{rsync} writes its PID.
-@item @code{post-rotate} (default: @code{#f})
-Either @code{#f} or a gexp to execute once the rotation has completed.
-@end table
-@end deftp
+@item @code{lock-file} (default: @code{"/var/run/rsyncd/rsyncd.lock"})
+Name of the file where @command{rsync} writes its lock file.
-@defvr {Scheme Variable} %default-rotations
-Specifies weekly rotation of @var{%rotated-files} and
-a couple of other files.
-@end defvr
+@item @code{log-file} (default: @code{"/var/log/rsyncd.log"})
+Name of the file where @command{rsync} writes its log file.
-@defvr {Scheme Variable} %rotated-files
-The list of syslog-controlled files to be rotated. By default it is:
-@code{'("/var/log/messages" "/var/log/secure")}.
-@end defvr
+@item @code{use-chroot?} (default: @var{#t})
+Whether to use chroot for @command{rsync} shared directory.
-@node Networking Services
-@subsubsection Networking Services
+@item @code{share-path} (default: @file{/srv/rsync})
+Location of the @command{rsync} shared directory.
-The @code{(gnu services networking)} module provides services to configure
-the network interface.
+@item @code{share-comment} (default: @code{"Rsync share"})
+Comment of the @command{rsync} shared directory.
-@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.
-@end defvr
+@item @code{read-only?} (default: @var{#f})
+Read-write permissions to shared directory.
-@deffn {Scheme Procedure} dhcpd-service-type
-This type defines a service that runs a DHCP daemon. To create a
-service of this type, you must supply a @code{<dhcpd-configuration>}.
-For example:
+@item @code{timeout} (default: @code{300})
+I/O timeout in seconds.
-@example
-(service dhcpd-service-type
- (dhcpd-configuration
- (config-file (local-file "my-dhcpd.conf"))
- (interfaces '("enp0s25"))))
-@end example
-@end deffn
+@item @code{user} (default: @var{"root"})
+Owner of the @code{rsync} process.
+
+@item @code{group} (default: @var{"root"})
+Group of the @code{rsync} process.
+
+@item @code{uid} (default: @var{"rsyncd"})
+User name or user ID that file transfers to and from that module should take
+place as when the daemon was run as @code{root}.
+
+@item @code{gid} (default: @var{"rsyncd"})
+Group name or group ID that will be used when accessing the module.
-@deftp {Data Type} dhcpd-configuration
-@table @asis
-@item @code{package} (default: @code{isc-dhcp})
-The package that provides the DHCP daemon. This package is expected to
-provide the daemon at @file{sbin/dhcpd} relative to its output
-directory. The default package is the
-@uref{http://www.isc.org/products/DHCP, ISC's DHCP server}.
-@item @code{config-file} (default: @code{#f})
-The configuration file to use. This is required. It will be passed to
-@code{dhcpd} via its @code{-cf} option. This may be any ``file-like''
-object (@pxref{G-Expressions, file-like objects}). See @code{man
-dhcpd.conf} for details on the configuration file syntax.
-@item @code{version} (default: @code{"4"})
-The DHCP version to use. The ISC DHCP server supports the values ``4'',
-``6'', and ``4o6''. These correspond to the @code{dhcpd} program
-options @code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for
-details.
-@item @code{run-directory} (default: @code{"/run/dhcpd"})
-The run directory to use. At service activation time, this directory
-will be created if it does not exist.
-@item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"})
-The PID file to use. This corresponds to the @code{-pf} option of
-@code{dhcpd}. See @code{man dhcpd} for details.
-@item @code{interfaces} (default: @code{'()})
-The names of the network interfaces on which dhcpd should listen for
-broadcasts. If this list is not empty, then its elements (which must be
-strings) will be appended to the @code{dhcpd} invocation when starting
-the daemon. It may not be necessary to explicitly specify any
-interfaces here; see @code{man dhcpd} for details.
@end table
@end deftp
-@defvr {Scheme Variable} static-networking-service-type
-This is the type for statically-configured network interfaces.
-@c TODO Document <static-networking> data structures.
-@end defvr
+Furthermore, @code{(gnu services ssh)} provides the following services.
+@cindex SSH
+@cindex SSH server
-@deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @
- [#:netmask #f] [#:gateway #f] [#:name-servers @code{'()}] @
- [#:requirement @code{'(udev)}]
-Return a service that starts @var{interface} with address @var{ip}. If
-@var{netmask} is true, use it as the network mask. If @var{gateway} is true,
-it must be a string specifying the default network gateway. @var{requirement}
-can be used to declare a dependency on another service before configuring the
-interface.
+@deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
+ [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
+ [#:allow-empty-passwords? #f] [#:root-login? #f] @
+ [#:syslog-output? #t] [#:x11-forwarding? #t] @
+ [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
+ [#:public-key-authentication? #t] [#:initialize? #t]
+Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
+@var{host-key} must designate a file containing the host key, and readable
+only by root.
-This procedure can be called several times, one for each network
-interface of interest. Behind the scenes what it does is extend
-@code{static-networking-service-type} with additional network interfaces
-to handle.
+When @var{daemonic?} is true, @command{lshd} will detach from the
+controlling terminal and log its output to syslogd, unless one sets
+@var{syslog-output?} to false. Obviously, it also makes lsh-service
+depend on existence of syslogd service. When @var{pid-file?} is true,
+@command{lshd} writes its PID to the file called @var{pid-file}.
-For example:
+When @var{initialize?} is true, automatically create the seed and host key
+upon service activation if they do not exist yet. This may take long and
+require interaction.
+
+When @var{initialize?} is false, it is up to the user to initialize the
+randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
+a key pair with the private key stored in file @var{host-key} (@pxref{lshd
+basics,,, lsh, LSH Manual}).
+
+When @var{interfaces} is empty, lshd listens for connections on all the
+network interfaces; otherwise, @var{interfaces} must be a list of host names
+or addresses.
+
+@var{allow-empty-passwords?} specifies whether to accept log-ins with empty
+passwords, and @var{root-login?} specifies whether to accept log-ins as
+root.
+
+The other options should be self-descriptive.
+@end deffn
+
+@cindex SSH
+@cindex SSH server
+@deffn {Scheme Variable} openssh-service-type
+This is the type for the @uref{http://www.openssh.org, OpenSSH} secure
+shell daemon, @command{sshd}. Its value must be an
+@code{openssh-configuration} record as in this example:
@example
-(static-networking-service "eno1" "192.168.1.82"
- #:gateway "192.168.1.2"
- #:name-servers '("192.168.1.2"))
+(service openssh-service-type
+ (openssh-configuration
+ (x11-forwarding? #t)
+ (permit-root-login 'without-password)
+ (authorized-keys
+ `(("alice" ,(local-file "alice.pub"))
+ ("bob" ,(local-file "bob.pub"))))))
@end example
-@end deffn
-@cindex wicd
-@cindex wireless
-@cindex WiFi
-@cindex network management
-@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}]
-Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network
-management daemon that aims to simplify wired and wireless networking.
+See below for details about @code{openssh-configuration}.
-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
+This service can be extended with extra authorized keys, as in this
+example:
-@cindex ModemManager
+@example
+(service-extension openssh-service-type
+ (const `(("charlie"
+ ,(local-file "charlie.pub")))))
+@end example
+@end deffn
-@defvr {Scheme Variable} modem-manager-service-type
-This is the service type for the
-@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager}
-service. The value for this service type is a
-@code{modem-manager-configuration} record.
+@deftp {Data Type} openssh-configuration
+This is the configuration record for OpenSSH's @command{sshd}.
-This service is part of @code{%desktop-services} (@pxref{Desktop
-Services}).
-@end defvr
+@table @asis
+@item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
+Name of the file where @command{sshd} writes its PID.
-@deftp {Data Type} modem-manager-configuration
-Data type representing the configuration of ModemManager.
+@item @code{port-number} (default: @code{22})
+TCP port on which @command{sshd} listens for incoming connections.
-@table @asis
-@item @code{modem-manager} (default: @code{modem-manager})
-The ModemManager package to use.
+@item @code{permit-root-login} (default: @code{#f})
+This field determines whether and when to allow logins as root. If
+@code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
+If it's the symbol @code{'without-password}, then root logins are
+permitted but not with password-based authentication.
-@end table
-@end deftp
+@item @code{allow-empty-passwords?} (default: @code{#f})
+When true, users with empty passwords may log in. When false, they may
+not.
-@cindex NetworkManager
+@item @code{password-authentication?} (default: @code{#t})
+When true, users may log in with their password. When false, they have
+other authentication methods.
-@defvr {Scheme Variable} network-manager-service-type
-This is the service type for the
-@uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager}
-service. The value for this service type is a
-@code{network-manager-configuration} record.
+@item @code{public-key-authentication?} (default: @code{#t})
+When true, users may log in using public key authentication. When
+false, users have to use other authentication method.
-This service is part of @code{%desktop-services} (@pxref{Desktop
-Services}).
-@end defvr
+Authorized public keys are stored in @file{~/.ssh/authorized_keys}.
+This is used only by protocol version 2.
-@deftp {Data Type} network-manager-configuration
-Data type representing the configuration of NetworkManager.
+@item @code{x11-forwarding?} (default: @code{#f})
+When true, forwarding of X11 graphical client connections is
+enabled---in other words, @command{ssh} options @option{-X} and
+@option{-Y} will work.
-@table @asis
-@item @code{network-manager} (default: @code{network-manager})
-The NetworkManager package to use.
+@item @code{allow-agent-forwarding?} (default: @code{#t})
+Whether to allow agent forwarding.
-@item @code{dns} (default: @code{"default"})
-Processing mode for DNS, which affects how NetworkManager uses the
-@code{resolv.conf} configuration file.
+@item @code{allow-tcp-forwarding?} (default: @code{#t})
+Whether to allow TCP forwarding.
-@table @samp
-@item default
-NetworkManager will update @code{resolv.conf} to reflect the nameservers
-provided by currently active connections.
+@item @code{gateway-ports?} (default: @code{#f})
+Whether to allow gateway ports.
-@item dnsmasq
-NetworkManager will run @code{dnsmasq} as a local caching nameserver,
-using a "split DNS" configuration if you are connected to a VPN, and
-then update @code{resolv.conf} to point to the local nameserver.
+@item @code{challenge-response-authentication?} (default: @code{#f})
+Specifies whether challenge response authentication is allowed (e.g.@: via
+PAM).
-@item none
-NetworkManager will not modify @code{resolv.conf}.
-@end table
+@item @code{use-pam?} (default: @code{#t})
+Enables the Pluggable Authentication Module interface. If set to
+@code{#t}, this will enable PAM authentication using
+@code{challenge-response-authentication?} and
+@code{password-authentication?}, in addition to PAM account and session
+module processing for all authentication types.
-@item @code{vpn-plugins} (default: @code{'()})
-This is the list of available plugins for virtual private networks
-(VPNs). An example of this is the @code{network-manager-openvpn}
-package, which allows NetworkManager to manage VPNs @i{via} OpenVPN.
+Because PAM challenge response authentication usually serves an
+equivalent role to password authentication, you should disable either
+@code{challenge-response-authentication?} or
+@code{password-authentication?}.
-@end table
-@end deftp
+@item @code{print-last-log?} (default: @code{#t})
+Specifies whether @command{sshd} should print the date and time of the
+last user login when a user logs in interactively.
-@cindex Connman
-@deffn {Scheme Variable} connman-service-type
-This is the service type to run @url{https://01.org/connman,Connman},
-a network connection manager.
+@item @code{subsystems} (default: @code{'(("sftp" "internal-sftp"))})
+Configures external subsystems (e.g.@: file transfer daemon).
-Its value must be an
-@code{connman-configuration} record as in this example:
+This is a list of two-element lists, each of which containing the
+subsystem name and a command (with optional arguments) to execute upon
+subsystem request.
+The command @command{internal-sftp} implements an in-process SFTP
+server. Alternately, one can specify the @command{sftp-server} command:
@example
-(service connman-service-type
- (connman-configuration
- (disable-vpn? #t)))
+(service openssh-service-type
+ (openssh-configuration
+ (subsystems
+ `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
@end example
-See below for details about @code{connman-configuration}.
-@end deffn
+@item @code{accepted-environment} (default: @code{'()})
+List of strings describing which environment variables may be exported.
-@deftp {Data Type} connman-configuration
-Data Type representing the configuration of connman.
+Each string gets on its own line. See the @code{AcceptEnv} option in
+@code{man sshd_config}.
-@table @asis
-@item @code{connman} (default: @var{connman})
-The connman package to use.
+This example allows ssh-clients to export the @code{COLORTERM} variable.
+It is set by terminal emulators, which support colors. You can use it in
+your shell's ressource file to enable colors for the prompt and commands
+if this variable is set.
-@item @code{disable-vpn?} (default: @code{#f})
-When true, disable connman's vpn plugin.
-@end table
-@end deftp
+@example
+(service openssh-service-type
+ (openssh-configuration
+ (accepted-environment '("COLORTERM"))))
+@end example
-@cindex WPA Supplicant
-@defvr {Scheme Variable} wpa-supplicant-service-type
-This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA
-supplicant}, an authentication daemon required to authenticate against
-encrypted WiFi or ethernet networks.
-@end defvr
+@item @code{authorized-keys} (default: @code{'()})
+@cindex authorized keys, SSH
+@cindex SSH authorized keys
+This is the list of authorized keys. Each element of the list is a user
+name followed by one or more file-like objects that represent SSH public
+keys. For example:
-@deftp {Data Type} wpa-supplicant-configuration
-Data type representing the configuration of WPA Supplicant.
+@example
+(openssh-configuration
+ (authorized-keys
+ `(("rekado" ,(local-file "rekado.pub"))
+ ("chris" ,(local-file "chris.pub"))
+ ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))
+@end example
-It takes the following parameters:
+@noindent
+registers the specified public keys for user accounts @code{rekado},
+@code{chris}, and @code{root}.
-@table @asis
-@item @code{wpa-supplicant} (default: @code{wpa-supplicant})
-The WPA Supplicant package to use.
+Additional authorized keys can be specified @i{via}
+@code{service-extension}.
-@item @code{dbus?} (default: @code{#t})
-Whether to listen for requests on D-Bus.
+Note that this does @emph{not} interfere with the use of
+@file{~/.ssh/authorized_keys}.
-@item @code{pid-file} (default: @code{"/var/run/wpa_supplicant.pid"})
-Where to store the PID file.
+@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
+page for @file{sshd_config} for the full list of level names.
-@item @code{interface} (default: @code{#f})
-If this is set, it must specify the name of a network interface that
-WPA supplicant will control.
+@item @code{extra-content} (default: @code{""})
+This field can be used to append arbitrary text to the configuration file. It
+is especially useful for elaborate configurations that cannot be expressed
+otherwise. This configuration, for example, would generally disable root
+logins, but permit them from one specific IP address:
-@item @code{config-file} (default: @code{#f})
-Optional configuration file to use.
+@example
+(openssh-configuration
+ (extra-content "\
+Match Address 192.168.0.1
+ PermitRootLogin yes"))
+@end example
-@item @code{extra-options} (default: @code{'()})
-List of additional command-line arguments to pass to the daemon.
@end table
@end deftp
-@cindex iptables
-@defvr {Scheme Variable} iptables-service-type
-This is the service type to set up an iptables configuration. iptables is a
-packet filtering framework supported by the Linux kernel. This service
-supports configuring iptables for both IPv4 and IPv6. A simple example
-configuration rejecting all incoming connections except those to the ssh port
-22 is shown below.
+@deffn {Scheme Procedure} dropbear-service [@var{config}]
+Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH
+daemon} with the given @var{config}, a @code{<dropbear-configuration>}
+object.
-@lisp
-(service iptables-service-type
- (iptables-configuration
- (ipv4-rules (plain-file "iptables.rules" "*filter
-:INPUT ACCEPT
-:FORWARD ACCEPT
-:OUTPUT ACCEPT
--A INPUT -p tcp --dport 22 -j ACCEPT
--A INPUT -j REJECT --reject-with icmp-port-unreachable
-COMMIT
-"))
- (ipv6-rules (plain-file "ip6tables.rules" "*filter
-:INPUT ACCEPT
-:FORWARD ACCEPT
-:OUTPUT ACCEPT
--A INPUT -p tcp --dport 22 -j ACCEPT
--A INPUT -j REJECT --reject-with icmp6-port-unreachable
-COMMIT
-"))))
-@end lisp
-@end defvr
+For example, to specify a Dropbear service listening on port 1234, add
+this call to the operating system's @code{services} field:
-@deftp {Data Type} iptables-configuration
-The data type representing the configuration of iptables.
+@example
+(dropbear-service (dropbear-configuration
+ (port-number 1234)))
+@end example
+@end deffn
+
+@deftp {Data Type} dropbear-configuration
+This data type represents the configuration of a Dropbear SSH daemon.
@table @asis
-@item @code{iptables} (default: @code{iptables})
-The iptables package that provides @code{iptables-restore} and
-@code{ip6tables-restore}.
-@item @code{ipv4-rules} (default: @code{%iptables-accept-all-rules})
-The iptables rules to use. It will be passed to @code{iptables-restore}.
-This may be any ``file-like'' object (@pxref{G-Expressions, file-like
-objects}).
-@item @code{ipv6-rules} (default: @code{%iptables-accept-all-rules})
-The ip6tables rules to use. It will be passed to @code{ip6tables-restore}.
-This may be any ``file-like'' object (@pxref{G-Expressions, file-like
-objects}).
-@end table
-@end deftp
+@item @code{dropbear} (default: @var{dropbear})
+The Dropbear package to use.
-@cindex NTP (Network Time Protocol), service
-@cindex real time clock
-@defvr {Scheme Variable} ntp-service-type
-This is the type of the service running the @uref{http://www.ntp.org,
-Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep the
-system clock synchronized with that of the specified NTP servers.
+@item @code{port-number} (default: 22)
+The TCP port where the daemon waits for incoming connections.
-The value of this service is an @code{ntpd-configuration} object, as described
-below.
-@end defvr
+@item @code{syslog-output?} (default: @code{#t})
+Whether to enable syslog output.
-@deftp {Data Type} ntp-configuration
-This is the data type for the NTP service configuration.
+@item @code{pid-file} (default: @code{"/var/run/dropbear.pid"})
+File name of the daemon's PID file.
-@table @asis
-@item @code{servers} (default: @code{%ntp-servers})
-This is the list of servers (host names) with which @command{ntpd} will be
-synchronized.
+@item @code{root-login?} (default: @code{#f})
+Whether to allow @code{root} logins.
-@item @code{allow-large-adjustment?} (default: @code{#f})
-This determines whether @command{ntpd} is allowed to make an initial
-adjustment of more than 1,000 seconds.
+@item @code{allow-empty-passwords?} (default: @code{#f})
+Whether to allow empty passwords.
-@item @code{ntp} (default: @code{ntp})
-The NTP package to use.
+@item @code{password-authentication?} (default: @code{#t})
+Whether to enable password-based authentication.
@end table
@end deftp
-@defvr {Scheme Variable} %ntp-servers
-List of host names used as the default NTP servers. These are servers of the
-@uref{https://www.ntppool.org/en/, NTP Pool Project}.
-@end defvr
+@defvr {Scheme Variable} %facebook-host-aliases
+This variable contains a string for use in @file{/etc/hosts}
+(@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
+line contains a entry that maps a known server name of the Facebook
+on-line service---e.g., @code{www.facebook.com}---to the local
+host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
-@cindex OpenNTPD
-@deffn {Scheme Procedure} openntpd-service-type
-Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as implemented
-by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will keep the system
-clock synchronized with that of the given servers.
+This variable is typically used in the @code{hosts-file} field of an
+@code{operating-system} declaration (@pxref{operating-system Reference,
+@file{/etc/hosts}}):
@example
-(service
- openntpd-service-type
- (openntpd-configuration
- (listen-on '("127.0.0.1" "::1"))
- (sensor '("udcf0 correction 70000"))
- (constraint-from '("www.gnu.org"))
- (constraints-from '("https://www.google.com/"))
- (allow-large-adjustment? #t)))
+(use-modules (gnu) (guix))
+(operating-system
+ (host-name "mymachine")
+ ;; ...
+ (hosts-file
+ ;; Create a /etc/hosts file with aliases for "localhost"
+ ;; and "mymachine", as well as for Facebook servers.
+ (plain-file "hosts"
+ (string-append (local-host-aliases host-name)
+ %facebook-host-aliases))))
@end example
-@end deffn
-@deftp {Data Type} openntpd-configuration
+This mechanism can prevent programs running locally, such as Web
+browsers, from accessing Facebook.
+@end defvr
+
+The @code{(gnu services avahi)} provides the following definition.
+
+@defvr {Scheme Variable} avahi-service-type
+This is the service that runs @command{avahi-daemon}, a system-wide
+mDNS/DNS-SD responder that allows for service discovery and
+``zero-configuration'' host name lookups (see @uref{http://avahi.org/}).
+Its value must be a @code{zero-configuration} record---see below.
+
+This service extends the name service cache daemon (nscd) so that it can
+resolve @code{.local} host names using
+@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name
+Service Switch}, for information on host name resolution.
+
+Additionally, add the @var{avahi} package to the system profile so that
+commands such as @command{avahi-browse} are directly usable.
+@end defvr
+
+@deftp {Data Type} avahi-configuration
+Data type representation the configuration for Avahi.
+
@table @asis
-@item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")})
-The openntpd executable to use.
-@item @code{listen-on} (default: @code{'("127.0.0.1" "::1")})
-A list of local IP addresses or hostnames the ntpd daemon should listen on.
-@item @code{query-from} (default: @code{'()})
-A list of local IP address the ntpd daemon should use for outgoing queries.
-@item @code{sensor} (default: @code{'()})
-Specify a list of timedelta sensor devices ntpd should use. @code{ntpd}
-will listen to each sensor that acutally exists and ignore non-existant ones.
-See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
-information.
-@item @code{server} (default: @var{%ntp-servers})
-Specify a list of IP addresses or hostnames of NTP servers to synchronize to.
-@item @code{servers} (default: @code{'()})
-Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
-@item @code{constraint-from} (default: @code{'()})
-@code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers via TLS.
-This time information is not used for precision but acts as an authenticated
-constraint, thereby reducing the impact of unauthenticated NTP
-man-in-the-middle attacks.
-Specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide
-a constraint.
-@item @code{constraints-from} (default: @code{'()})
-As with constraint from, specify a list of URLs, IP addresses or hostnames of
-HTTPS servers to provide a constraint. Should the hostname resolve to multiple
-IP addresses, @code{ntpd} will calculate a median constraint from all of them.
-@item @code{allow-large-adjustment?} (default: @code{#f})
-Determines if @code{ntpd} is allowed to make an initial adjustment of more
-than 180 seconds.
-@end table
-@end deftp
-@cindex inetd
-@deffn {Scheme variable} inetd-service-type
-This service runs the @command{inetd} (@pxref{inetd invocation,,,
-inetutils, GNU Inetutils}) daemon. @command{inetd} listens for
-connections on internet sockets, and lazily starts the specified server
-program when a connection is made on one of these sockets.
+@item @code{host-name} (default: @code{#f})
+If different from @code{#f}, use that as the host name to
+publish for this machine; otherwise, use the machine's actual host name.
-The value of this service is an @code{inetd-configuration} object. The
-following example configures the @command{inetd} daemon to provide the
-built-in @command{echo} service, as well as an smtp service which
-forwards smtp traffic over ssh to a server @code{smtp-server} behind a
-gateway @code{hostname}:
+@item @code{publish?} (default: @code{#t})
+When true, allow host names and services to be published (broadcast) over the
+network.
+
+@item @code{publish-workstation?} (default: @code{#t})
+When true, @command{avahi-daemon} publishes the machine's host name and IP
+address via mDNS on the local network. To view the host names published on
+your local network, you can run:
@example
-(service
- inetd-service-type
- (inetd-configuration
- (entries (list
- (inetd-entry
- (name "echo")
- (socket-type 'stream)
- (protocol "tcp")
- (wait? #f)
- (user "root"))
- (inetd-entry
- (node "127.0.0.1")
- (name "smtp")
- (socket-type 'stream)
- (protocol "tcp")
- (wait? #f)
- (user "root")
- (program (file-append openssh "/bin/ssh"))
- (arguments
- '("ssh" "-qT" "-i" "/path/to/ssh_key"
- "-W" "smtp-server:25" "user@@hostname")))))
+avahi-browse _workstation._tcp
@end example
-See below for more details about @code{inetd-configuration}.
+@item @code{wide-area?} (default: @code{#f})
+When true, DNS-SD over unicast DNS is enabled.
+
+@item @code{ipv4?} (default: @code{#t})
+@itemx @code{ipv6?} (default: @code{#t})
+These fields determine whether to use IPv4/IPv6 sockets.
+
+@item @code{domains-to-browse} (default: @code{'()})
+This is a list of domains to browse.
+@end table
+@end deftp
+
+@deffn {Scheme Variable} openvswitch-service-type
+This is the type of the @uref{http://www.openvswitch.org, Open vSwitch}
+service, whose value should be an @code{openvswitch-configuration}
+object.
@end deffn
-@deftp {Data Type} inetd-configuration
-Data type representing the configuration of @command{inetd}.
+@deftp {Data Type} openvswitch-configuration
+Data type representing the configuration of Open vSwitch, a multilayer
+virtual switch which is designed to enable massive network automation
+through programmatic extension.
@table @asis
-@item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")})
-The @command{inetd} executable to use.
+@item @code{package} (default: @var{openvswitch})
+Package object of the Open vSwitch.
-@item @code{entries} (default: @code{'()})
-A list of @command{inetd} service entries. Each entry should be created
-by the @code{inetd-entry} constructor.
@end table
@end deftp
-@deftp {Data Type} inetd-entry
-Data type representing an entry in the @command{inetd} configuration.
-Each entry corresponds to a socket where @command{inetd} will listen for
-requests.
+@node X Window
+@subsection X Window
-@table @asis
-@item @code{node} (default: @code{#f})
-Optional string, a comma-separated list of local addresses
-@command{inetd} should use when listening for this service.
-@xref{Configuration file,,, inetutils, GNU Inetutils} for a complete
-description of all options.
-@item @code{name}
-A string, the name must correspond to an entry in @code{/etc/services}.
-@item @code{socket-type}
-One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or
-@code{'seqpacket}.
-@item @code{protocol}
-A string, must correspond to an entry in @code{/etc/protocols}.
-@item @code{wait?} (default: @code{#t})
-Whether @command{inetd} should wait for the server to exit before
-listening to new service requests.
-@item @code{user}
-A string containing the user (and, optionally, group) name of the user
-as whom the server should run. The group name can be specified in a
-suffix, separated by a colon or period, i.e.@: @code{"user"},
-@code{"user:group"} or @code{"user.group"}.
-@item @code{program} (default: @code{"internal"})
-The server program which will serve the requests, or @code{"internal"}
-if @command{inetd} should use a built-in service.
-@item @code{arguments} (default: @code{'()})
-A list strings or file-like objects, which are the server program's
-arguments, starting with the zeroth argument, i.e.@: the name of the
-program itself. For @command{inetd}'s internal services, this entry
-must be @code{'()} or @code{'("internal")}.
-@end table
+@cindex X11
+@cindex X Window System
+@cindex login manager
+Support for the X Window graphical display system---specifically
+Xorg---is provided by the @code{(gnu services xorg)} module. Note that
+there is no @code{xorg-service} procedure. Instead, the X server is
+started by the @dfn{login manager}, by default SLiM.
-@xref{Configuration file,,, inetutils, GNU Inetutils} for a more
-detailed discussion of each configuration field.
-@end deftp
+@cindex window manager
+To use X11, you must install at least one @dfn{window manager}---for
+example the @code{windowmaker} or @code{openbox} packages---preferably
+by adding it to the @code{packages} field of your operating system
+definition (@pxref{operating-system Reference, system-wide packages}).
-@cindex Tor
-@defvr {Scheme Variable} tor-service-type
-This is the type for a service that runs the @uref{https://torproject.org,
-Tor} anonymous networking daemon. The service is configured using a
-@code{<tor-configuration>} record. By default, the Tor daemon runs as the
-@code{tor} unprivileged user, which is a member of the @code{tor} group.
+@defvr {Scheme Variable} slim-service-type
+This is the type for the SLiM graphical login manager for X11.
-@end defvr
+@cindex session types (X11)
+@cindex X11 session types
+SLiM looks for @dfn{session types} described by the @file{.desktop} files in
+@file{/run/current-system/profile/share/xsessions} and allows users to
+choose a session from the log-in screen using @kbd{F1}. Packages such
+as @code{xfce}, @code{sawfish}, and @code{ratpoison} provide
+@file{.desktop} files; adding them to the system-wide set of packages
+automatically makes them available at the log-in screen.
-@deftp {Data Type} tor-configuration
-@table @asis
-@item @code{tor} (default: @code{tor})
-The package that provides the Tor daemon. This package is expected to provide
-the daemon at @file{bin/tor} relative to its output directory. The default
-package is the @uref{https://www.torproject.org, Tor Project's}
-implementation.
+In addition, @file{~/.xsession} files are honored. When available,
+@file{~/.xsession} must be an executable that starts a window manager
+and/or other X clients.
+@end defvr
-@item @code{config-file} (default: @code{(plain-file "empty" "")})
-The configuration file to use. It will be appended to a default configuration
-file, and the final configuration file will be passed to @code{tor} via its
-@code{-f} option. This may be any ``file-like'' object (@pxref{G-Expressions,
-file-like objects}). See @code{man tor} for details on the configuration file
-syntax.
+@deftp {Data Type} slim-configuration
+Data type representing the configuration of @code{slim-service-type}.
-@item @code{hidden-services} (default: @code{'()})
-The list of @code{<hidden-service>} records to use. For any hidden service
-you include in this list, appropriate configuration to enable the hidden
-service will be automatically added to the default configuration file. You
-may conveniently create @code{<hidden-service>} records using the
-@code{tor-hidden-service} procedure described below.
+@table @asis
+@item @code{allow-empty-passwords?} (default: @code{#t})
+Whether to allow logins with empty passwords.
-@item @code{socks-socket-type} (default: @code{'tcp})
-The default socket type that Tor should use for its SOCKS socket. This must
-be either @code{'tcp} or @code{'unix}. If it is @code{'tcp}, then by default
-Tor will listen on TCP port 9050 on the loopback interface (i.e., localhost).
-If it is @code{'unix}, then Tor will listen on the UNIX domain socket
-@file{/var/run/tor/socks-sock}, which will be made writable by members of the
-@code{tor} group.
+@item @code{auto-login?} (default: @code{#f})
+@itemx @code{default-user} (default: @code{""})
+When @code{auto-login?} is false, SLiM presents a log-in screen.
-If you want to customize the SOCKS socket in more detail, leave
-@code{socks-socket-type} at its default value of @code{'tcp} and use
-@code{config-file} to override the default by providing your own
-@code{SocksPort} option.
-@end table
-@end deftp
+When @code{auto-login?} is true, SLiM logs in directly as
+@code{default-user}.
-@cindex hidden service
-@deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
-Define a new Tor @dfn{hidden service} called @var{name} and implementing
-@var{mapping}. @var{mapping} is a list of port/host tuples, such as:
+@item @code{theme} (default: @code{%default-slim-theme})
+@itemx @code{theme-name} (default: @code{%default-slim-theme-name})
+The graphical theme to use and its name.
-@example
- '((22 "127.0.0.1:22")
- (80 "127.0.0.1:8080"))
-@end example
+@item @code{auto-login-session} (default: @code{#f})
+If true, this must be the name of the executable to start as the default
+session---e.g., @code{(file-append windowmaker "/bin/windowmaker")}.
-In this example, port 22 of the hidden service is mapped to local port 22, and
-port 80 is mapped to local port 8080.
+If false, a session described by one of the available @file{.desktop}
+files in @code{/run/current-system/profile} and @code{~/.guix-profile}
+will be used.
-This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, where
-the @file{hostname} file contains the @code{.onion} host name for the hidden
-service.
+@quotation Note
+You must install at least one window manager in the system profile or in
+your user profile. Failing to do that, if @code{auto-login-session} is
+false, you will be unable to log in.
+@end quotation
-See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
-project's documentation} for more information.
-@end deffn
+@item @code{xorg-configuration} (default @code{(xorg-configuration)})
+Configuration of the Xorg graphical server.
-The @code{(gnu services rsync)} module provides the following services:
+@item @code{xauth} (default: @code{xauth})
+The XAuth package to use.
-You might want an rsync daemon if you have files that you want available
-so anyone (or just yourself) can download existing files or upload new
-files.
+@item @code{shepherd} (default: @code{shepherd})
+The Shepherd package used when invoking @command{halt} and
+@command{reboot}.
-@deffn {Scheme Variable} rsync-service-type
-This is the type for the @uref{https://rsync.samba.org, rsync} rsync daemon,
-@command{rsync-configuration} record as in this example:
+@item @code{sessreg} (default: @code{sessreg})
+The sessreg package used in order to register the session.
-@example
-(service rsync-service-type)
-@end example
+@item @code{slim} (default: @code{slim})
+The SLiM package to use.
+@end table
+@end deftp
-See below for details about @code{rsync-configuration}.
-@end deffn
+@defvr {Scheme Variable} %default-theme
+@defvrx {Scheme Variable} %default-theme-name
+The default SLiM theme and its name.
+@end defvr
-@deftp {Data Type} rsync-configuration
-Data type representing the configuration for @code{rsync-service}.
+
+@deftp {Data Type} sddm-configuration
+This is the data type representing the sddm service configuration.
@table @asis
-@item @code{package} (default: @var{rsync})
-@code{rsync} package to use.
+@item @code{display-server} (default: "x11")
+Select display server to use for the greeter. Valid values are "x11"
+or "wayland".
-@item @code{port-number} (default: @code{873})
-TCP port on which @command{rsync} listens for incoming connections. If port
-is less than @code{1024} @command{rsync} needs to be started as the
-@code{root} user and group.
+@item @code{numlock} (default: "on")
+Valid values are "on", "off" or "none".
-@item @code{pid-file} (default: @code{"/var/run/rsyncd/rsyncd.pid"})
-Name of the file where @command{rsync} writes its PID.
+@item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")})
+Command to run when halting.
-@item @code{lock-file} (default: @code{"/var/run/rsyncd/rsyncd.lock"})
-Name of the file where @command{rsync} writes its lock file.
+@item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")})
+Command to run when rebooting.
-@item @code{log-file} (default: @code{"/var/log/rsyncd.log"})
-Name of the file where @command{rsync} writes its log file.
+@item @code{theme} (default "maldives")
+Theme to use. Default themes provided by SDDM are "elarun" or "maldives".
-@item @code{use-chroot?} (default: @var{#t})
-Whether to use chroot for @command{rsync} shared directory.
+@item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
+Directory to look for themes.
-@item @code{share-path} (default: @file{/srv/rsync})
-Location of the @command{rsync} shared directory.
+@item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces")
+Directory to look for faces.
-@item @code{share-comment} (default: @code{"Rsync share"})
-Comment of the @command{rsync} shared directory.
+@item @code{default-path} (default "/run/current-system/profile/bin")
+Default PATH to use.
-@item @code{read-only?} (default: @var{#f})
-Read-write permissions to shared directory.
+@item @code{minimum-uid} (default 1000)
+Minimum UID to display in SDDM.
-@item @code{timeout} (default: @code{300})
-I/O timeout in seconds.
+@item @code{maximum-uid} (default 2000)
+Maximum UID to display in SDDM
-@item @code{user} (default: @var{"root"})
-Owner of the @code{rsync} process.
+@item @code{remember-last-user?} (default #t)
+Remember last user.
-@item @code{group} (default: @var{"root"})
-Group of the @code{rsync} process.
+@item @code{remember-last-session?} (default #t)
+Remember last session.
-@item @code{uid} (default: @var{"rsyncd"})
-User name or user ID that file transfers to and from that module should take
-place as when the daemon was run as @code{root}.
+@item @code{hide-users} (default "")
+Usernames to hide from SDDM greeter.
-@item @code{gid} (default: @var{"rsyncd"})
-Group name or group ID that will be used when accessing the module.
+@item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")})
+Users with shells listed will be hidden from the SDDM greeter.
-@end table
-@end deftp
+@item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")})
+Script to run before starting a wayland session.
-Furthermore, @code{(gnu services ssh)} provides the following services.
-@cindex SSH
-@cindex SSH server
+@item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions")
+Directory to look for desktop files starting wayland sessions.
-@deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
- [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
- [#:allow-empty-passwords? #f] [#:root-login? #f] @
- [#:syslog-output? #t] [#:x11-forwarding? #t] @
- [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
- [#:public-key-authentication? #t] [#:initialize? #t]
-Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
-@var{host-key} must designate a file containing the host key, and readable
-only by root.
+@item @code{xorg-configuration} (default @code{(xorg-configuration)})
+Configuration of the Xorg graphical server.
-When @var{daemonic?} is true, @command{lshd} will detach from the
-controlling terminal and log its output to syslogd, unless one sets
-@var{syslog-output?} to false. Obviously, it also makes lsh-service
-depend on existence of syslogd service. When @var{pid-file?} is true,
-@command{lshd} writes its PID to the file called @var{pid-file}.
+@item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")})
+Path to xauth.
-When @var{initialize?} is true, automatically create the seed and host key
-upon service activation if they do not exist yet. This may take long and
-require interaction.
+@item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")})
+Path to Xephyr.
-When @var{initialize?} is false, it is up to the user to initialize the
-randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
-a key pair with the private key stored in file @var{host-key} (@pxref{lshd
-basics,,, lsh, LSH Manual}).
+@item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")})
+Script to run after starting xorg-server.
-When @var{interfaces} is empty, lshd listens for connections on all the
-network interfaces; otherwise, @var{interfaces} must be a list of host names
-or addresses.
+@item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")})
+Script to run before stopping xorg-server.
-@var{allow-empty-passwords?} specifies whether to accept log-ins with empty
-passwords, and @var{root-login?} specifies whether to accept log-ins as
-root.
+@item @code{xsession-command} (default: @code{xinitrc})
+Script to run before starting a X session.
-The other options should be self-descriptive.
-@end deffn
+@item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions")
+Directory to look for desktop files starting X sessions.
-@cindex SSH
-@cindex SSH server
-@deffn {Scheme Variable} openssh-service-type
-This is the type for the @uref{http://www.openssh.org, OpenSSH} secure
-shell daemon, @command{sshd}. Its value must be an
-@code{openssh-configuration} record as in this example:
+@item @code{minimum-vt} (default: 7)
+Minimum VT to use.
-@example
-(service openssh-service-type
- (openssh-configuration
- (x11-forwarding? #t)
- (permit-root-login 'without-password)
- (authorized-keys
- `(("alice" ,(local-file "alice.pub"))
- ("bob" ,(local-file "bob.pub"))))))
-@end example
+@item @code{auto-login-user} (default "")
+User to use for auto-login.
-See below for details about @code{openssh-configuration}.
+@item @code{auto-login-session} (default "")
+Desktop file to use for auto-login.
-This service can be extended with extra authorized keys, as in this
-example:
+@item @code{relogin?} (default #f)
+Relogin after logout.
+
+@end table
+@end deftp
+
+@cindex login manager
+@cindex X11 login
+@deffn {Scheme Procedure} sddm-service config
+Return a service that spawns the SDDM graphical login manager for config of
+type @code{<sddm-configuration>}.
@example
-(service-extension openssh-service-type
- (const `(("charlie"
- ,(local-file "charlie.pub")))))
+ (sddm-service (sddm-configuration
+ (auto-login-user "Alice")
+ (auto-login-session "xfce.desktop")))
@end example
@end deffn
-@deftp {Data Type} openssh-configuration
-This is the configuration record for OpenSSH's @command{sshd}.
+@cindex Xorg, configuration
+@deftp {Data Type} xorg-configuration
+This data type represents the configuration of the Xorg graphical display
+server. Note that there is not Xorg service; instead, the X server is started
+by a ``display manager'' such as GDM, SDDM, and SLiM. Thus, the configuration
+of these display managers aggregates an @code{xorg-configuration} record.
@table @asis
-@item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
-Name of the file where @command{sshd} writes its PID.
-
-@item @code{port-number} (default: @code{22})
-TCP port on which @command{sshd} listens for incoming connections.
-
-@item @code{permit-root-login} (default: @code{#f})
-This field determines whether and when to allow logins as root. If
-@code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
-If it's the symbol @code{'without-password}, then root logins are
-permitted but not with password-based authentication.
-
-@item @code{allow-empty-passwords?} (default: @code{#f})
-When true, users with empty passwords may log in. When false, they may
-not.
-
-@item @code{password-authentication?} (default: @code{#t})
-When true, users may log in with their password. When false, they have
-other authentication methods.
+@item @code{modules} (default: @code{%default-xorg-modules})
+This is a list of @dfn{module packages} loaded by the Xorg
+server---e.g., @code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on.
-@item @code{public-key-authentication?} (default: @code{#t})
-When true, users may log in using public key authentication. When
-false, users have to use other authentication method.
+@item @code{fonts} (default: @code{%default-xorg-fonts})
+This is a list of font directories to add to the server's @dfn{font path}.
-Authorized public keys are stored in @file{~/.ssh/authorized_keys}.
-This is used only by protocol version 2.
+@item @code{drivers} (default: @code{'()})
+This must be either the empty list, in which case Xorg chooses a graphics
+driver automatically, or a list of driver names that will be tried in this
+order---e.g., @code{("modesetting" "vesa")}.
-@item @code{x11-forwarding?} (default: @code{#f})
-When true, forwarding of X11 graphical client connections is
-enabled---in other words, @command{ssh} options @option{-X} and
-@option{-Y} will work.
+@item @code{resolutions} (default: @code{'()})
+When @code{resolutions} is the empty list, Xorg chooses an appropriate screen
+resolution. Otherwise, it must be a list of resolutions---e.g., @code{((1024
+768) (640 480))}.
-@item @code{allow-agent-forwarding?} (default: @code{#t})
-Whether to allow agent forwarding.
+@cindex keyboard layout, for Xorg
+@cindex keymap, for Xorg
+@item @code{keyboard-layout} (default: @code{#f})
+If this is @code{#f}, Xorg uses the default keyboard layout---usually US
+English (``qwerty'') for a 105-key PC keyboard.
-@item @code{allow-tcp-forwarding?} (default: @code{#t})
-Whether to allow TCP forwarding.
+Otherwise this must be a @code{keyboard-layout} object specifying the keyboard
+layout in use when Xorg is running.
-@item @code{gateway-ports?} (default: @code{#f})
-Whether to allow gateway ports.
+@item @code{extra-config} (default: @code{'()})
+This is a list of strings or objects appended to the configuration file. It
+is used to pass extra text to be added verbatim to the configuration file.
-@item @code{challenge-response-authentication?} (default: @code{#f})
-Specifies whether challenge response authentication is allowed (e.g.@: via
-PAM).
+@item @code{server} (default: @code{xorg-server})
+This is the package providing the Xorg server.
-@item @code{use-pam?} (default: @code{#t})
-Enables the Pluggable Authentication Module interface. If set to
-@code{#t}, this will enable PAM authentication using
-@code{challenge-response-authentication?} and
-@code{password-authentication?}, in addition to PAM account and session
-module processing for all authentication types.
+@item @code{server-arguments} (default: @code{%default-xorg-server-arguments})
+This is the list of command-line arguments to pass to the X server. The
+default is @code{-nolisten tcp}.
+@end table
+@end deftp
-Because PAM challenge response authentication usually serves an
-equivalent role to password authentication, you should disable either
-@code{challenge-response-authentication?} or
-@code{password-authentication?}.
+@deffn {Scheme Procedure} xorg-start-command [@var{config}]
+Return a @code{startx} script in which the modules, fonts, etc. specified
+in @var{config}, are available. The result should be used in place of
+@code{startx}.
-@item @code{print-last-log?} (default: @code{#t})
-Specifies whether @command{sshd} should print the date and time of the
-last user login when a user logs in interactively.
+Usually the X server is started by a login manager.
+@end deffn
-@item @code{subsystems} (default: @code{'(("sftp" "internal-sftp"))})
-Configures external subsystems (e.g.@: file transfer daemon).
-This is a list of two-element lists, each of which containing the
-subsystem name and a command (with optional arguments) to execute upon
-subsystem request.
+@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}]
+Add @var{package}, a package for a screen locker or screen saver whose
+command is @var{program}, to the set of setuid programs and add a PAM entry
+for it. For example:
-The command @command{internal-sftp} implements an in-process SFTP
-server. Alternately, one can specify the @command{sftp-server} command:
-@example
-(service openssh-service-type
- (openssh-configuration
- (subsystems
- `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
-@end example
+@lisp
+(screen-locker-service xlockmore "xlock")
+@end lisp
-@item @code{accepted-environment} (default: @code{'()})
-List of strings describing which environment variables may be exported.
+makes the good ol' XlockMore usable.
+@end deffn
-Each string gets on its own line. See the @code{AcceptEnv} option in
-@code{man sshd_config}.
-This example allows ssh-clients to export the @code{COLORTERM} variable.
-It is set by terminal emulators, which support colors. You can use it in
-your shell's ressource file to enable colors for the prompt and commands
-if this variable is set.
+@node Printing Services
+@subsection Printing Services
+
+@cindex printer support with CUPS
+The @code{(gnu services cups)} module provides a Guix service definition
+for the CUPS printing service. To add printer support to a Guix
+system, add a @code{cups-service} to the operating system definition:
+@deffn {Scheme Variable} cups-service-type
+The service type for the CUPS print server. Its value should be a valid
+CUPS configuration (see below). To use the default settings, simply
+write:
@example
-(service openssh-service-type
- (openssh-configuration
- (accepted-environment '("COLORTERM"))))
+(service cups-service-type)
@end example
+@end deffn
-@item @code{authorized-keys} (default: @code{'()})
-@cindex authorized keys, SSH
-@cindex SSH authorized keys
-This is the list of authorized keys. Each element of the list is a user
-name followed by one or more file-like objects that represent SSH public
-keys. For example:
+The CUPS configuration controls the basic things about your CUPS
+installation: what interfaces it listens on, what to do if a print job
+fails, how much logging to do, and so on. To actually add a printer,
+you have to visit the @url{http://localhost:631} URL, or use a tool such
+as GNOME's printer configuration services. By default, configuring a
+CUPS service will generate a self-signed certificate if needed, for
+secure connections to the print server.
+
+Suppose you want to enable the Web interface of CUPS and also add
+support for Epson printers @i{via} the @code{escpr} package and for HP
+printers @i{via} the @code{hplip-minimal} package. You can do that directly,
+like this (you need to use the @code{(gnu packages cups)} module):
@example
-(openssh-configuration
- (authorized-keys
- `(("rekado" ,(local-file "rekado.pub"))
- ("chris" ,(local-file "chris.pub"))
- ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))
+(service cups-service-type
+ (cups-configuration
+ (web-interface? #t)
+ (extensions
+ (list cups-filters escpr hplip-minimal))))
@end example
-@noindent
-registers the specified public keys for user accounts @code{rekado},
-@code{chris}, and @code{root}.
+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.
-Additional authorized keys can be specified @i{via}
-@code{service-extension}.
+The available configuration parameters follow. Each parameter
+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. There is also a way to specify the configuration as a string,
+if you have an old @code{cupsd.conf} file that you want to port over
+from some other system; see the end for more details.
-Note that this does @emph{not} interfere with the use of
-@file{~/.ssh/authorized_keys}.
+@c The following documentation was initially generated by
+@c (generate-documentation) in (gnu services cups). Manually maintained
+@c documentation is better, so we shouldn't hesitate to edit below as
+@c needed. However if the change you want to make to this documentation
+@c can be done in an automated way, it's probably easier to change
+@c (generate-documentation) than to make it below and have to deal with
+@c the churn as CUPS updates.
-@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
-page for @file{sshd_config} for the full list of level names.
-@end table
-@end deftp
+Available @code{cups-configuration} fields are:
-@deffn {Scheme Procedure} dropbear-service [@var{config}]
-Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH
-daemon} with the given @var{config}, a @code{<dropbear-configuration>}
-object.
+@deftypevr {@code{cups-configuration} parameter} package cups
+The CUPS package.
+@end deftypevr
-For example, to specify a Dropbear service listening on port 1234, add
-this call to the operating system's @code{services} field:
+@deftypevr {@code{cups-configuration} parameter} package-list extensions
+Drivers and other extensions to the CUPS package.
+@end deftypevr
-@example
-(dropbear-service (dropbear-configuration
- (port-number 1234)))
-@end example
-@end deffn
+@deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration
+Configuration of where to write logs, what directories to use for print
+spools, and related privileged configuration parameters.
-@deftp {Data Type} dropbear-configuration
-This data type represents the configuration of a Dropbear SSH daemon.
+Available @code{files-configuration} fields are:
-@table @asis
-@item @code{dropbear} (default: @var{dropbear})
-The Dropbear package to use.
+@deftypevr {@code{files-configuration} parameter} log-location access-log
+Defines the access log filename. Specifying a blank filename disables
+access log generation. The value @code{stderr} causes log entries to be
+sent to the standard error file when the scheduler is running in the
+foreground, or to the system log daemon when run in the background. The
+value @code{syslog} causes log entries to be sent to the system log
+daemon. The server name may be included in filenames using the string
+@code{%s}, as in @code{/var/log/cups/%s-access_log}.
-@item @code{port-number} (default: 22)
-The TCP port where the daemon waits for incoming connections.
+Defaults to @samp{"/var/log/cups/access_log"}.
+@end deftypevr
-@item @code{syslog-output?} (default: @code{#t})
-Whether to enable syslog output.
+@deftypevr {@code{files-configuration} parameter} file-name cache-dir
+Where CUPS should cache data.
-@item @code{pid-file} (default: @code{"/var/run/dropbear.pid"})
-File name of the daemon's PID file.
+Defaults to @samp{"/var/cache/cups"}.
+@end deftypevr
-@item @code{root-login?} (default: @code{#f})
-Whether to allow @code{root} logins.
+@deftypevr {@code{files-configuration} parameter} string config-file-perm
+Specifies the permissions for all configuration files that the scheduler
+writes.
-@item @code{allow-empty-passwords?} (default: @code{#f})
-Whether to allow empty passwords.
+Note that the permissions for the printers.conf file are currently
+masked to only allow access from the scheduler user (typically root).
+This is done because printer device URIs sometimes contain sensitive
+authentication information that should not be generally known on the
+system. There is no way to disable this security feature.
-@item @code{password-authentication?} (default: @code{#t})
-Whether to enable password-based authentication.
-@end table
-@end deftp
+Defaults to @samp{"0640"}.
+@end deftypevr
-@defvr {Scheme Variable} %facebook-host-aliases
-This variable contains a string for use in @file{/etc/hosts}
-(@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
-line contains a entry that maps a known server name of the Facebook
-on-line service---e.g., @code{www.facebook.com}---to the local
-host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
+@deftypevr {@code{files-configuration} parameter} log-location error-log
+Defines the error log filename. Specifying a blank filename disables
+access log generation. The value @code{stderr} causes log entries to be
+sent to the standard error file when the scheduler is running in the
+foreground, or to the system log daemon when run in the background. The
+value @code{syslog} causes log entries to be sent to the system log
+daemon. The server name may be included in filenames using the string
+@code{%s}, as in @code{/var/log/cups/%s-error_log}.
-This variable is typically used in the @code{hosts-file} field of an
-@code{operating-system} declaration (@pxref{operating-system Reference,
-@file{/etc/hosts}}):
+Defaults to @samp{"/var/log/cups/error_log"}.
+@end deftypevr
-@example
-(use-modules (gnu) (guix))
+@deftypevr {@code{files-configuration} parameter} string fatal-errors
+Specifies which errors are fatal, causing the scheduler to exit. The
+kind strings are:
-(operating-system
- (host-name "mymachine")
- ;; ...
- (hosts-file
- ;; Create a /etc/hosts file with aliases for "localhost"
- ;; and "mymachine", as well as for Facebook servers.
- (plain-file "hosts"
- (string-append (local-host-aliases host-name)
- %facebook-host-aliases))))
-@end example
+@table @code
+@item none
+No errors are fatal.
-This mechanism can prevent programs running locally, such as Web
-browsers, from accessing Facebook.
-@end defvr
+@item all
+All of the errors below are fatal.
-The @code{(gnu services avahi)} provides the following definition.
+@item browse
+Browsing initialization errors are fatal, for example failed connections
+to the DNS-SD daemon.
-@deffn {Scheme Procedure} avahi-service [#:avahi @var{avahi}] @
- [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @
- [#:ipv6? #t] [#:wide-area? #f] @
- [#:domains-to-browse '()] [#:debug? #f]
-Return a service that runs @command{avahi-daemon}, a system-wide
-mDNS/DNS-SD responder that allows for service discovery and
-"zero-configuration" host name lookups (see @uref{http://avahi.org/}), and
-extends the name service cache daemon (nscd) so that it can resolve
-@code{.local} host names using
-@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. Additionally,
-add the @var{avahi} package to the system profile so that commands such as
-@command{avahi-browse} are directly usable.
-
-If @var{host-name} is different from @code{#f}, use that as the host name to
-publish for this machine; otherwise, use the machine's actual host name.
+@item config
+Configuration file syntax errors are fatal.
-When @var{publish?} is true, publishing of host names and services is allowed;
-in particular, avahi-daemon will publish the machine's host name and IP
-address via mDNS on the local network.
+@item listen
+Listen or Port errors are fatal, except for IPv6 failures on the
+loopback or @code{any} addresses.
+
+@item log
+Log file creation or write errors are fatal.
+
+@item permissions
+Bad startup file permissions are fatal, for example shared TLS
+certificate and key files with world-read permissions.
+@end table
+
+Defaults to @samp{"all -browse"}.
+@end deftypevr
+
+@deftypevr {@code{files-configuration} parameter} boolean file-device?
+Specifies whether the file pseudo-device can be used for new printer
+queues. The URI @uref{file:///dev/null} is always allowed.
-When @var{wide-area?} is true, DNS-SD over unicast DNS is enabled.
+Defaults to @samp{#f}.
+@end deftypevr
-Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use IPv4/IPv6
-sockets.
-@end deffn
+@deftypevr {@code{files-configuration} parameter} string group
+Specifies the group name or ID that will be used when executing external
+programs.
-@deffn {Scheme Variable} openvswitch-service-type
-This is the type of the @uref{http://www.openvswitch.org, Open vSwitch}
-service, whose value should be an @code{openvswitch-configuration}
-object.
-@end deffn
+Defaults to @samp{"lp"}.
+@end deftypevr
-@deftp {Data Type} openvswitch-configuration
-Data type representing the configuration of Open vSwitch, a multilayer
-virtual switch which is designed to enable massive network automation
-through programmatic extension.
+@deftypevr {@code{files-configuration} parameter} string log-file-perm
+Specifies the permissions for all log files that the scheduler writes.
-@table @asis
-@item @code{package} (default: @var{openvswitch})
-Package object of the Open vSwitch.
+Defaults to @samp{"0644"}.
+@end deftypevr
-@end table
-@end deftp
+@deftypevr {@code{files-configuration} parameter} log-location page-log
+Defines the page log filename. Specifying a blank filename disables
+access log generation. The value @code{stderr} causes log entries to be
+sent to the standard error file when the scheduler is running in the
+foreground, or to the system log daemon when run in the background. The
+value @code{syslog} causes log entries to be sent to the system log
+daemon. The server name may be included in filenames using the string
+@code{%s}, as in @code{/var/log/cups/%s-page_log}.
-@node X Window
-@subsubsection X Window
+Defaults to @samp{"/var/log/cups/page_log"}.
+@end deftypevr
-@cindex X11
-@cindex X Window System
-@cindex login manager
-Support for the X Window graphical display system---specifically
-Xorg---is provided by the @code{(gnu services xorg)} module. Note that
-there is no @code{xorg-service} procedure. Instead, the X server is
-started by the @dfn{login manager}, by default SLiM.
+@deftypevr {@code{files-configuration} parameter} string remote-root
+Specifies the username that is associated with unauthenticated accesses
+by clients claiming to be the root user. The default is @code{remroot}.
-@cindex window manager
-To use X11, you must install at least one @dfn{window manager}---for
-example the @code{windowmaker} or @code{openbox} packages---preferably
-by adding it to the @code{packages} field of your operating system
-definition (@pxref{operating-system Reference, system-wide packages}).
+Defaults to @samp{"remroot"}.
+@end deftypevr
-@defvr {Scheme Variable} slim-service-type
-This is the type for the SLiM graphical login manager for X11.
+@deftypevr {@code{files-configuration} parameter} file-name request-root
+Specifies the directory that contains print jobs and other HTTP request
+data.
-@cindex session types (X11)
-@cindex X11 session types
-SLiM looks for @dfn{session types} described by the @file{.desktop} files in
-@file{/run/current-system/profile/share/xsessions} and allows users to
-choose a session from the log-in screen using @kbd{F1}. Packages such
-as @code{xfce}, @code{sawfish}, and @code{ratpoison} provide
-@file{.desktop} files; adding them to the system-wide set of packages
-automatically makes them available at the log-in screen.
+Defaults to @samp{"/var/spool/cups"}.
+@end deftypevr
-In addition, @file{~/.xsession} files are honored. When available,
-@file{~/.xsession} must be an executable that starts a window manager
-and/or other X clients.
-@end defvr
+@deftypevr {@code{files-configuration} parameter} sandboxing sandboxing
+Specifies the level of security sandboxing that is applied to print
+filters, backends, and other child processes of the scheduler; either
+@code{relaxed} or @code{strict}. This directive is currently only
+used/supported on macOS.
-@deftp {Data Type} slim-configuration
-Data type representing the configuration of @code{slim-service-type}.
+Defaults to @samp{strict}.
+@end deftypevr
-@table @asis
-@item @code{allow-empty-passwords?} (default: @code{#t})
-Whether to allow logins with empty passwords.
+@deftypevr {@code{files-configuration} parameter} file-name server-keychain
+Specifies the location of TLS certificates and private keys. CUPS will
+look for public and private keys in this directory: a @code{.crt} files
+for PEM-encoded certificates and corresponding @code{.key} files for
+PEM-encoded private keys.
-@item @code{auto-login?} (default: @code{#f})
-@itemx @code{default-user} (default: @code{""})
-When @code{auto-login?} is false, SLiM presents a log-in screen.
+Defaults to @samp{"/etc/cups/ssl"}.
+@end deftypevr
-When @code{auto-login?} is true, SLiM logs in directly as
-@code{default-user}.
+@deftypevr {@code{files-configuration} parameter} file-name server-root
+Specifies the directory containing the server configuration files.
-@item @code{theme} (default: @code{%default-slim-theme})
-@itemx @code{theme-name} (default: @code{%default-slim-theme-name})
-The graphical theme to use and its name.
+Defaults to @samp{"/etc/cups"}.
+@end deftypevr
-@item @code{auto-login-session} (default: @code{#f})
-If true, this must be the name of the executable to start as the default
-session---e.g., @code{(file-append windowmaker "/bin/windowmaker")}.
+@deftypevr {@code{files-configuration} parameter} boolean sync-on-close?
+Specifies whether the scheduler calls fsync(2) after writing
+configuration or state files.
-If false, a session described by one of the available @file{.desktop}
-files in @code{/run/current-system/profile} and @code{~/.guix-profile}
-will be used.
+Defaults to @samp{#f}.
+@end deftypevr
-@quotation Note
-You must install at least one window manager in the system profile or in
-your user profile. Failing to do that, if @code{auto-login-session} is
-false, you will be unable to log in.
-@end quotation
+@deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group
+Specifies the group(s) to use for @code{@@SYSTEM} group authentication.
+@end deftypevr
-@item @code{startx} (default: @code{(xorg-start-command)})
-The command used to start the X11 graphical server.
+@deftypevr {@code{files-configuration} parameter} file-name temp-dir
+Specifies the directory where temporary files are stored.
-@item @code{xauth} (default: @code{xauth})
-The XAuth package to use.
+Defaults to @samp{"/var/spool/cups/tmp"}.
+@end deftypevr
-@item @code{shepherd} (default: @code{shepherd})
-The Shepherd package used when invoking @command{halt} and
-@command{reboot}.
+@deftypevr {@code{files-configuration} parameter} string user
+Specifies the user name or ID that is used when running external
+programs.
-@item @code{sessreg} (default: @code{sessreg})
-The sessreg package used in order to register the session.
+Defaults to @samp{"lp"}.
+@end deftypevr
+@end deftypevr
-@item @code{slim} (default: @code{slim})
-The SLiM package to use.
-@end table
-@end deftp
+@deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level
+Specifies the logging level for the AccessLog file. The @code{config}
+level logs when printers and classes are added, deleted, or modified and
+when configuration files are accessed or updated. The @code{actions}
+level logs when print jobs are submitted, held, released, modified, or
+canceled, and any of the conditions for @code{config}. The @code{all}
+level logs all requests.
-@defvr {Scheme Variable} %default-theme
-@defvrx {Scheme Variable} %default-theme-name
-The default SLiM theme and its name.
-@end defvr
+Defaults to @samp{actions}.
+@end deftypevr
+@deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs?
+Specifies whether to purge job history data automatically when it is no
+longer required for quotas.
-@deftp {Data Type} sddm-configuration
-This is the data type representing the sddm service configuration.
+Defaults to @samp{#f}.
+@end deftypevr
-@table @asis
-@item @code{display-server} (default: "x11")
-Select display server to use for the greeter. Valid values are "x11"
-or "wayland".
+@deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols
+Specifies which protocols to use for local printer sharing.
-@item @code{numlock} (default: "on")
-Valid values are "on", "off" or "none".
+Defaults to @samp{dnssd}.
+@end deftypevr
-@item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")})
-Command to run when halting.
+@deftypevr {@code{cups-configuration} parameter} boolean browse-web-if?
+Specifies whether the CUPS web interface is advertised.
-@item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")})
-Command to run when rebooting.
+Defaults to @samp{#f}.
+@end deftypevr
-@item @code{theme} (default "maldives")
-Theme to use. Default themes provided by SDDM are "elarun" or "maldives".
+@deftypevr {@code{cups-configuration} parameter} boolean browsing?
+Specifies whether shared printers are advertised.
-@item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
-Directory to look for themes.
+Defaults to @samp{#f}.
+@end deftypevr
-@item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces")
-Directory to look for faces.
+@deftypevr {@code{cups-configuration} parameter} string classification
+Specifies the security classification of the server. Any valid banner
+name can be used, including "classified", "confidential", "secret",
+"topsecret", and "unclassified", or the banner can be omitted to disable
+secure printing functions.
-@item @code{default-path} (default "/run/current-system/profile/bin")
-Default PATH to use.
+Defaults to @samp{""}.
+@end deftypevr
-@item @code{minimum-uid} (default 1000)
-Minimum UID to display in SDDM.
+@deftypevr {@code{cups-configuration} parameter} boolean classify-override?
+Specifies whether users may override the classification (cover page) of
+individual print jobs using the @code{job-sheets} option.
-@item @code{maximum-uid} (default 2000)
-Maximum UID to display in SDDM
+Defaults to @samp{#f}.
+@end deftypevr
-@item @code{remember-last-user?} (default #t)
-Remember last user.
+@deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type
+Specifies the default type of authentication to use.
-@item @code{remember-last-session?} (default #t)
-Remember last session.
+Defaults to @samp{Basic}.
+@end deftypevr
-@item @code{hide-users} (default "")
-Usernames to hide from SDDM greeter.
+@deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption
+Specifies whether encryption will be used for authenticated requests.
-@item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")})
-Users with shells listed will be hidden from the SDDM greeter.
+Defaults to @samp{Required}.
+@end deftypevr
-@item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")})
-Script to run before starting a wayland session.
+@deftypevr {@code{cups-configuration} parameter} string default-language
+Specifies the default language to use for text and web content.
-@item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions")
-Directory to look for desktop files starting wayland sessions.
+Defaults to @samp{"en"}.
+@end deftypevr
-@item @code{xorg-server-path} (default @code{xorg-start-command})
-Path to xorg-server.
+@deftypevr {@code{cups-configuration} parameter} string default-paper-size
+Specifies the default paper size for new print queues. @samp{"Auto"}
+uses a locale-specific default, while @samp{"None"} specifies there is
+no default paper size. Specific size names are typically
+@samp{"Letter"} or @samp{"A4"}.
-@item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")})
-Path to xauth.
+Defaults to @samp{"Auto"}.
+@end deftypevr
-@item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")})
-Path to Xephyr.
+@deftypevr {@code{cups-configuration} parameter} string default-policy
+Specifies the default access policy to use.
-@item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")})
-Script to run after starting xorg-server.
+Defaults to @samp{"default"}.
+@end deftypevr
-@item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")})
-Script to run before stopping xorg-server.
+@deftypevr {@code{cups-configuration} parameter} boolean default-shared?
+Specifies whether local printers are shared by default.
-@item @code{xsession-command} (default: @code{xinitrc})
-Script to run before starting a X session.
+Defaults to @samp{#t}.
+@end deftypevr
-@item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions")
-Directory to look for desktop files starting X sessions.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval
+Specifies the delay for updating of configuration and state files, in
+seconds. A value of 0 causes the update to happen as soon as possible,
+typically within a few milliseconds.
-@item @code{minimum-vt} (default: 7)
-Minimum VT to use.
+Defaults to @samp{30}.
+@end deftypevr
-@item @code{xserver-arguments} (default "-nolisten tcp")
-Arguments to pass to xorg-server.
+@deftypevr {@code{cups-configuration} parameter} error-policy error-policy
+Specifies what to do when an error occurs. Possible values are
+@code{abort-job}, which will discard the failed print job;
+@code{retry-job}, which will retry the job at a later time;
+@code{retry-this-job}, which retries the failed job immediately; and
+@code{stop-printer}, which stops the printer.
-@item @code{auto-login-user} (default "")
-User to use for auto-login.
+Defaults to @samp{stop-printer}.
+@end deftypevr
-@item @code{auto-login-session} (default "")
-Desktop file to use for auto-login.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit
+Specifies the maximum cost of filters that are run concurrently, which
+can be used to minimize disk, memory, and CPU resource problems. A
+limit of 0 disables filter limiting. An average print to a
+non-PostScript printer needs a filter limit of about 200. A PostScript
+printer needs about half that (100). Setting the limit below these
+thresholds will effectively limit the scheduler to printing a single job
+at any time.
-@item @code{relogin?} (default #f)
-Relogin after logout.
+Defaults to @samp{0}.
+@end deftypevr
-@end table
-@end deftp
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice
+Specifies the scheduling priority of filters that are run to print a
+job. The nice value ranges from 0, the highest priority, to 19, the
+lowest priority.
-@cindex login manager
-@cindex X11 login
-@deffn {Scheme Procedure} sddm-service config
-Return a service that spawns the SDDM graphical login manager for config of
-type @code{<sddm-configuration>}.
+Defaults to @samp{0}.
+@end deftypevr
-@example
- (sddm-service (sddm-configuration
- (auto-login-user "Alice")
- (auto-login-session "xfce.desktop")))
-@end example
-@end deffn
+@deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups
+Specifies whether to do reverse lookups on connecting clients. The
+@code{double} setting causes @code{cupsd} to verify that the hostname
+resolved from the address matches one of the addresses returned for that
+hostname. Double lookups also prevent clients with unregistered
+addresses from connecting to your server. Only set this option to
+@code{#t} or @code{double} if absolutely required.
-@deffn {Scheme Procedure} xorg-start-command [#:guile] @
- [#:modules %default-xorg-modules] @
- [#:fonts %default-xorg-fonts] @
- [#:configuration-file (xorg-configuration-file @dots{})] @
- [#:xorg-server @var{xorg-server}]
-Return a @code{startx} script in which @var{modules}, a list of X module
-packages, and @var{fonts}, a list of X font directories, are available. See
-@code{xorg-wrapper} for more details on the arguments. The result should be
-used in place of @code{startx}.
+Defaults to @samp{#f}.
+@end deftypevr
-Usually the X server is started by a login manager.
-@end deffn
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay
+Specifies the number of seconds to wait before killing the filters and
+backend associated with a canceled or held job.
-@deffn {Scheme Procedure} xorg-configuration-file @
- [#:modules %default-xorg-modules] @
- [#:fonts %default-xorg-fonts] @
- [#:drivers '()] [#:resolutions '()] [#:extra-config '()]
-Return a configuration file for the Xorg server containing search paths for
-all the common drivers.
+Defaults to @samp{30}.
+@end deftypevr
-@var{modules} must be a list of @dfn{module packages} loaded by the Xorg
-server---e.g., @code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on.
-@var{fonts} must be a list of font directories to add to the server's
-@dfn{font path}.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval
+Specifies the interval between retries of jobs in seconds. This is
+typically used for fax queues but can also be used with normal print
+queues whose error policy is @code{retry-job} or
+@code{retry-current-job}.
-@var{drivers} must be either the empty list, in which case Xorg chooses a
-graphics driver automatically, or a list of driver names that will be tried in
-this order---e.g., @code{("modesetting" "vesa")}.
+Defaults to @samp{30}.
+@end deftypevr
-Likewise, when @var{resolutions} is the empty list, Xorg chooses an
-appropriate screen resolution; otherwise, it must be a list of
-resolutions---e.g., @code{((1024 768) (640 480))}.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit
+Specifies the number of retries that are done for jobs. This is
+typically used for fax queues but can also be used with normal print
+queues whose error policy is @code{retry-job} or
+@code{retry-current-job}.
-Last, @var{extra-config} is a list of strings or objects appended to the
-configuration file. It is used to pass extra text to be
-added verbatim to the configuration file.
+Defaults to @samp{5}.
+@end deftypevr
-@cindex keymap
-@cindex keyboard layout
-This procedure is especially useful to configure a different keyboard layout
-than the default US keymap. For instance, to use the ``bépo'' keymap by
-default on the display manager:
+@deftypevr {@code{cups-configuration} parameter} boolean keep-alive?
+Specifies whether to support HTTP keep-alive connections.
-@example
-(define bepo-evdev
- "Section \"InputClass\"
- Identifier \"evdev keyboard catchall\"
- Driver \"evdev\"
- MatchIsKeyboard \"on\"
- Option \"xkb_layout\" \"fr\"
- Option \"xkb_variant\" \"bepo\"
-EndSection")
+Defaults to @samp{#t}.
+@end deftypevr
-(operating-system
- ...
- (services
- (modify-services %desktop-services
- (slim-service-type config =>
- (slim-configuration
- (inherit config)
- (startx (xorg-start-command
- #:configuration-file
- (xorg-configuration-file
- #:extra-config
- (list bepo-evdev)))))))))
-@end example
-
-The @code{MatchIsKeyboard} line specifies that we only apply the configuration
-to keyboards. Without this line, other devices such as touchpad may not work
-correctly because they will be attached to the wrong driver. In this example,
-the user typically used @code{setxkbmap fr bepo} to set their favorite keymap
-once logged in. The first argument corresponds to the layout, while the second
-argument corresponds to the variant. The @code{xkb_variant} line can be omitted
-to select the default variant.
-@end deffn
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer keep-alive-timeout
+Specifies how long an idle client connection remains open, in seconds.
-@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}]
-Add @var{package}, a package for a screen locker or screen saver whose
-command is @var{program}, to the set of setuid programs and add a PAM entry
-for it. For example:
+Defaults to @samp{30}.
+@end deftypevr
-@lisp
-(screen-locker-service xlockmore "xlock")
-@end lisp
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
+Specifies the maximum size of print files, IPP requests, and HTML form
+data. A limit of 0 disables the limit check.
-makes the good ol' XlockMore usable.
-@end deffn
+Defaults to @samp{0}.
+@end deftypevr
+@deftypevr {@code{cups-configuration} parameter} multiline-string-list listen
+Listens on the specified interfaces for connections. Valid values are
+of the form @var{address}:@var{port}, where @var{address} is either an
+IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to
+indicate all addresses. Values can also be file names of local UNIX
+domain sockets. The Listen directive is similar to the Port directive
+but allows you to restrict access to specific interfaces or networks.
+@end deftypevr
-@node Printing Services
-@subsubsection Printing Services
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log
+Specifies the number of pending connections that will be allowed. This
+normally only affects very busy servers that have reached the MaxClients
+limit, but can also be triggered by large numbers of simultaneous
+connections. When the limit is reached, the operating system will
+refuse additional connections until the scheduler can accept the pending
+ones.
-@cindex printer support with CUPS
-The @code{(gnu services cups)} module provides a Guix service definition
-for the CUPS printing service. To add printer support to a GuixSD
-system, add a @code{cups-service} to the operating system definition:
+Defaults to @samp{128}.
+@end deftypevr
-@deffn {Scheme Variable} cups-service-type
-The service type for the CUPS print server. Its value should be a valid
-CUPS configuration (see below). To use the default settings, simply
-write:
-@example
-(service cups-service-type)
-@end example
-@end deffn
+@deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls
+Specifies a set of additional access controls.
-The CUPS configuration controls the basic things about your CUPS
-installation: what interfaces it listens on, what to do if a print job
-fails, how much logging to do, and so on. To actually add a printer,
-you have to visit the @url{http://localhost:631} URL, or use a tool such
-as GNOME's printer configuration services. By default, configuring a
-CUPS service will generate a self-signed certificate if needed, for
-secure connections to the print server.
+Available @code{location-access-controls} fields are:
-Suppose you want to enable the Web interface of CUPS and also add
-support for Epson printers @i{via} the @code{escpr} package and for HP
-printers @i{via} the @code{hplip-minimal} package. You can do that directly,
-like this (you need to use the @code{(gnu packages cups)} module):
+@deftypevr {@code{location-access-controls} parameter} file-name path
+Specifies the URI path to which the access control applies.
+@end deftypevr
-@example
-(service cups-service-type
- (cups-configuration
- (web-interface? #t)
- (extensions
- (list cups-filters escpr hplip-minimal))))
-@end example
+@deftypevr {@code{location-access-controls} parameter} access-control-list access-controls
+Access controls for all access to this path, in the same format as the
+@code{access-controls} of @code{operation-access-control}.
-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.
+Defaults to @samp{()}.
+@end deftypevr
-The available configuration parameters follow. Each parameter
-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. There is also a way to specify the configuration as a string,
-if you have an old @code{cupsd.conf} file that you want to port over
-from some other system; see the end for more details.
+@deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls
+Access controls for method-specific access to this path.
-@c The following documentation was initially generated by
-@c (generate-documentation) in (gnu services cups). Manually maintained
-@c documentation is better, so we shouldn't hesitate to edit below as
-@c needed. However if the change you want to make to this documentation
-@c can be done in an automated way, it's probably easier to change
-@c (generate-documentation) than to make it below and have to deal with
-@c the churn as CUPS updates.
+Defaults to @samp{()}.
+Available @code{method-access-controls} fields are:
-Available @code{cups-configuration} fields are:
+@deftypevr {@code{method-access-controls} parameter} boolean reverse?
+If @code{#t}, apply access controls to all methods except the listed
+methods. Otherwise apply to only the listed methods.
-@deftypevr {@code{cups-configuration} parameter} package cups
-The CUPS package.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} package-list extensions
-Drivers and other extensions to the CUPS package.
+@deftypevr {@code{method-access-controls} parameter} method-list methods
+Methods to which this access control applies.
+
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration
-Configuration of where to write logs, what directories to use for print
-spools, and related privileged configuration parameters.
+@deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
+Access control directives, as a list of strings. Each string should be
+one directive, such as "Order allow,deny".
-Available @code{files-configuration} fields are:
+Defaults to @samp{()}.
+@end deftypevr
+@end deftypevr
+@end deftypevr
-@deftypevr {@code{files-configuration} parameter} log-location access-log
-Defines the access log filename. Specifying a blank filename disables
-access log generation. The value @code{stderr} causes log entries to be
-sent to the standard error file when the scheduler is running in the
-foreground, or to the system log daemon when run in the background. The
-value @code{syslog} causes log entries to be sent to the system log
-daemon. The server name may be included in filenames using the string
-@code{%s}, as in @code{/var/log/cups/%s-access_log}.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history
+Specifies the number of debugging messages that are retained for logging
+if an error occurs in a print job. Debug messages are logged regardless
+of the LogLevel setting.
-Defaults to @samp{"/var/log/cups/access_log"}.
+Defaults to @samp{100}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} file-name cache-dir
-Where CUPS should cache data.
+@deftypevr {@code{cups-configuration} parameter} log-level log-level
+Specifies the level of logging for the ErrorLog file. The value
+@code{none} stops all logging while @code{debug2} logs everything.
-Defaults to @samp{"/var/cache/cups"}.
+Defaults to @samp{info}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} string config-file-perm
-Specifies the permissions for all configuration files that the scheduler
-writes.
+@deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format
+Specifies the format of the date and time in the log files. The value
+@code{standard} logs whole seconds while @code{usecs} logs microseconds.
-Note that the permissions for the printers.conf file are currently
-masked to only allow access from the scheduler user (typically root).
-This is done because printer device URIs sometimes contain sensitive
-authentication information that should not be generally known on the
-system. There is no way to disable this security feature.
+Defaults to @samp{standard}.
+@end deftypevr
+
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients
+Specifies the maximum number of simultaneous clients that are allowed by
+the scheduler.
-Defaults to @samp{"0640"}.
+Defaults to @samp{100}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} log-location error-log
-Defines the error log filename. Specifying a blank filename disables
-access log generation. The value @code{stderr} causes log entries to be
-sent to the standard error file when the scheduler is running in the
-foreground, or to the system log daemon when run in the background. The
-value @code{syslog} causes log entries to be sent to the system log
-daemon. The server name may be included in filenames using the string
-@code{%s}, as in @code{/var/log/cups/%s-error_log}.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host
+Specifies the maximum number of simultaneous clients that are allowed
+from a single address.
-Defaults to @samp{"/var/log/cups/error_log"}.
+Defaults to @samp{100}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} string fatal-errors
-Specifies which errors are fatal, causing the scheduler to exit. The
-kind strings are:
-
-@table @code
-@item none
-No errors are fatal.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies
+Specifies the maximum number of copies that a user can print of each
+job.
-@item all
-All of the errors below are fatal.
+Defaults to @samp{9999}.
+@end deftypevr
-@item browse
-Browsing initialization errors are fatal, for example failed connections
-to the DNS-SD daemon.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time
+Specifies the maximum time a job may remain in the @code{indefinite}
+hold state before it is canceled. A value of 0 disables cancellation of
+held jobs.
-@item config
-Configuration file syntax errors are fatal.
+Defaults to @samp{0}.
+@end deftypevr
-@item listen
-Listen or Port errors are fatal, except for IPv6 failures on the
-loopback or @code{any} addresses.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs
+Specifies the maximum number of simultaneous jobs that are allowed. Set
+to 0 to allow an unlimited number of jobs.
-@item log
-Log file creation or write errors are fatal.
+Defaults to @samp{500}.
+@end deftypevr
-@item permissions
-Bad startup file permissions are fatal, for example shared TLS
-certificate and key files with world-read permissions.
-@end table
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer
+Specifies the maximum number of simultaneous jobs that are allowed per
+printer. A value of 0 allows up to MaxJobs jobs per printer.
-Defaults to @samp{"all -browse"}.
+Defaults to @samp{0}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} boolean file-device?
-Specifies whether the file pseudo-device can be used for new printer
-queues. The URI @uref{file:///dev/null} is always allowed.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user
+Specifies the maximum number of simultaneous jobs that are allowed per
+user. A value of 0 allows up to MaxJobs jobs per user.
-Defaults to @samp{#f}.
+Defaults to @samp{0}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} string group
-Specifies the group name or ID that will be used when executing external
-programs.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
+Specifies the maximum time a job may take to print before it is
+canceled, in seconds. Set to 0 to disable cancellation of "stuck" jobs.
-Defaults to @samp{"lp"}.
+Defaults to @samp{10800}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} string log-file-perm
-Specifies the permissions for all log files that the scheduler writes.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size
+Specifies the maximum size of the log files before they are rotated, in
+bytes. The value 0 disables log rotation.
-Defaults to @samp{"0644"}.
+Defaults to @samp{1048576}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} log-location page-log
-Defines the page log filename. Specifying a blank filename disables
-access log generation. The value @code{stderr} causes log entries to be
-sent to the standard error file when the scheduler is running in the
-foreground, or to the system log daemon when run in the background. The
-value @code{syslog} causes log entries to be sent to the system log
-daemon. The server name may be included in filenames using the string
-@code{%s}, as in @code{/var/log/cups/%s-page_log}.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout
+Specifies the maximum amount of time to allow between files in a
+multiple file print job, in seconds.
-Defaults to @samp{"/var/log/cups/page_log"}.
+Defaults to @samp{300}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} string remote-root
-Specifies the username that is associated with unauthenticated accesses
-by clients claiming to be the root user. The default is @code{remroot}.
+@deftypevr {@code{cups-configuration} parameter} string page-log-format
+Specifies the format of PageLog lines. Sequences beginning with percent
+(@samp{%}) characters are replaced with the corresponding information,
+while all other characters are copied literally. The following percent
+sequences are recognized:
-Defaults to @samp{"remroot"}.
-@end deftypevr
+@table @samp
+@item %%
+insert a single percent character
-@deftypevr {@code{files-configuration} parameter} file-name request-root
-Specifies the directory that contains print jobs and other HTTP request
-data.
+@item %@{name@}
+insert the value of the specified IPP attribute
-Defaults to @samp{"/var/spool/cups"}.
+@item %C
+insert the number of copies for the current page
+
+@item %P
+insert the current page number
+
+@item %T
+insert the current date and time in common log format
+
+@item %j
+insert the job ID
+
+@item %p
+insert the printer name
+
+@item %u
+insert the username
+@end table
+
+A value of the empty string disables page logging. The string @code{%p
+%u %j %T %P %C %@{job-billing@} %@{job-originating-host-name@}
+%@{job-name@} %@{media@} %@{sides@}} creates a page log with the
+standard items.
+
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} sandboxing sandboxing
-Specifies the level of security sandboxing that is applied to print
-filters, backends, and other child processes of the scheduler; either
-@code{relaxed} or @code{strict}. This directive is currently only
-used/supported on macOS.
+@deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables
+Passes the specified environment variable(s) to child processes; a list
+of strings.
-Defaults to @samp{strict}.
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} file-name server-keychain
-Specifies the location of TLS certificates and private keys. CUPS will
-look for public and private keys in this directory: a @code{.crt} files
-for PEM-encoded certificates and corresponding @code{.key} files for
-PEM-encoded private keys.
+@deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies
+Specifies named access control policies.
-Defaults to @samp{"/etc/cups/ssl"}.
+Available @code{policy-configuration} fields are:
+
+@deftypevr {@code{policy-configuration} parameter} string name
+Name of the policy.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} file-name server-root
-Specifies the directory containing the server configuration files.
+@deftypevr {@code{policy-configuration} parameter} string job-private-access
+Specifies an access list for a job's private values. @code{@@ACL} maps
+to the printer's requesting-user-name-allowed or
+requesting-user-name-denied values. @code{@@OWNER} maps to the job's
+owner. @code{@@SYSTEM} maps to the groups listed for the
+@code{system-group} field of the @code{files-config} configuration,
+which is reified into the @code{cups-files.conf(5)} file. Other
+possible elements of the access list include specific user names, and
+@code{@@@var{group}} to indicate members of a specific group. The
+access list may also be simply @code{all} or @code{default}.
-Defaults to @samp{"/etc/cups"}.
+Defaults to @samp{"@@OWNER @@SYSTEM"}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} boolean sync-on-close?
-Specifies whether the scheduler calls fsync(2) after writing
-configuration or state files.
+@deftypevr {@code{policy-configuration} parameter} string job-private-values
+Specifies the list of job values to make private, or @code{all},
+@code{default}, or @code{none}.
-Defaults to @samp{#f}.
+Defaults to @samp{"job-name job-originating-host-name
+job-originating-user-name phone"}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group
-Specifies the group(s) to use for @code{@@SYSTEM} group authentication.
+@deftypevr {@code{policy-configuration} parameter} string subscription-private-access
+Specifies an access list for a subscription's private values.
+@code{@@ACL} maps to the printer's requesting-user-name-allowed or
+requesting-user-name-denied values. @code{@@OWNER} maps to the job's
+owner. @code{@@SYSTEM} maps to the groups listed for the
+@code{system-group} field of the @code{files-config} configuration,
+which is reified into the @code{cups-files.conf(5)} file. Other
+possible elements of the access list include specific user names, and
+@code{@@@var{group}} to indicate members of a specific group. The
+access list may also be simply @code{all} or @code{default}.
+
+Defaults to @samp{"@@OWNER @@SYSTEM"}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} file-name temp-dir
-Specifies the directory where temporary files are stored.
+@deftypevr {@code{policy-configuration} parameter} string subscription-private-values
+Specifies the list of job values to make private, or @code{all},
+@code{default}, or @code{none}.
-Defaults to @samp{"/var/spool/cups/tmp"}.
+Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri
+notify-subscriber-user-name notify-user-data"}.
@end deftypevr
-@deftypevr {@code{files-configuration} parameter} string user
-Specifies the user name or ID that is used when running external
-programs.
+@deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls
+Access control by IPP operation.
-Defaults to @samp{"lp"}.
+Defaults to @samp{()}.
@end deftypevr
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level
-Specifies the logging level for the AccessLog file. The @code{config}
-level logs when printers and classes are added, deleted, or modified and
-when configuration files are accessed or updated. The @code{actions}
-level logs when print jobs are submitted, held, released, modified, or
-canceled, and any of the conditions for @code{config}. The @code{all}
-level logs all requests.
+@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files
+Specifies whether job files (documents) are preserved after a job is
+printed. If a numeric value is specified, job files are preserved for
+the indicated number of seconds after printing. Otherwise a boolean
+value applies indefinitely.
-Defaults to @samp{actions}.
+Defaults to @samp{86400}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs?
-Specifies whether to purge job history data automatically when it is no
-longer required for quotas.
+@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history
+Specifies whether the job history is preserved after a job is printed.
+If a numeric value is specified, the job history is preserved for the
+indicated number of seconds after printing. If @code{#t}, the job
+history is preserved until the MaxJobs limit is reached.
-Defaults to @samp{#f}.
+Defaults to @samp{#t}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols
-Specifies which protocols to use for local printer sharing.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout
+Specifies the amount of time to wait for job completion before
+restarting the scheduler.
-Defaults to @samp{dnssd}.
+Defaults to @samp{30}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} boolean browse-web-if?
-Specifies whether the CUPS web interface is advertised.
+@deftypevr {@code{cups-configuration} parameter} string rip-cache
+Specifies the maximum amount of memory to use when converting documents
+into bitmaps for a printer.
-Defaults to @samp{#f}.
+Defaults to @samp{"128m"}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} boolean browsing?
-Specifies whether shared printers are advertised.
+@deftypevr {@code{cups-configuration} parameter} string server-admin
+Specifies the email address of the server administrator.
-Defaults to @samp{#f}.
+Defaults to @samp{"root@@localhost.localdomain"}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} string classification
-Specifies the security classification of the server. Any valid banner
-name can be used, including "classified", "confidential", "secret",
-"topsecret", and "unclassified", or the banner can be omitted to disable
-secure printing functions.
+@deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias
+The ServerAlias directive is used for HTTP Host header validation when
+clients connect to the scheduler from external interfaces. Using the
+special name @code{*} can expose your system to known browser-based DNS
+rebinding attacks, even when accessing sites through a firewall. If the
+auto-discovery of alternate names does not work, we recommend listing
+each alternate name with a ServerAlias directive instead of using
+@code{*}.
-Defaults to @samp{""}.
+Defaults to @samp{*}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} boolean classify-override?
-Specifies whether users may override the classification (cover page) of
-individual print jobs using the @code{job-sheets} option.
+@deftypevr {@code{cups-configuration} parameter} string server-name
+Specifies the fully-qualified host name of the server.
-Defaults to @samp{#f}.
+Defaults to @samp{"localhost"}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type
-Specifies the default type of authentication to use.
+@deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens
+Specifies what information is included in the Server header of HTTP
+responses. @code{None} disables the Server header. @code{ProductOnly}
+reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor}
+reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}.
+@code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is
+the output of the @code{uname} command. @code{Full} reports @code{CUPS
+2.0.0 (@var{uname}) IPP/2.0}.
-Defaults to @samp{Basic}.
+Defaults to @samp{Minimal}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption
-Specifies whether encryption will be used for authenticated requests.
+@deftypevr {@code{cups-configuration} parameter} string set-env
+Set the specified environment variable to be passed to child processes.
-Defaults to @samp{Required}.
+Defaults to @samp{"variable value"}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} string default-language
-Specifies the default language to use for text and web content.
+@deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen
+Listens on the specified interfaces for encrypted connections. Valid
+values are of the form @var{address}:@var{port}, where @var{address} is
+either an IPv6 address enclosed in brackets, an IPv4 address, or
+@code{*} to indicate all addresses.
-Defaults to @samp{"en"}.
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} string default-paper-size
-Specifies the default paper size for new print queues. @samp{"Auto"}
-uses a locale-specific default, while @samp{"None"} specifies there is
-no default paper size. Specific size names are typically
-@samp{"Letter"} or @samp{"A4"}.
+@deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
+Sets encryption options. By default, CUPS only supports encryption
+using TLS v1.0 or higher using known secure cipher suites. The
+@code{AllowRC4} option enables the 128-bit RC4 cipher suites, which are
+required for some older clients that do not implement newer ones. The
+@code{AllowSSL3} option enables SSL v3.0, which is required for some
+older clients that do not support TLS v1.0.
-Defaults to @samp{"Auto"}.
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} string default-policy
-Specifies the default access policy to use.
+@deftypevr {@code{cups-configuration} parameter} boolean strict-conformance?
+Specifies whether the scheduler requires clients to strictly adhere to
+the IPP specifications.
-Defaults to @samp{"default"}.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} boolean default-shared?
-Specifies whether local printers are shared by default.
+@deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout
+Specifies the HTTP request timeout, in seconds.
+
+Defaults to @samp{300}.
-Defaults to @samp{#t}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval
-Specifies the delay for updating of configuration and state files, in
-seconds. A value of 0 causes the update to happen as soon as possible,
-typically within a few milliseconds.
+@deftypevr {@code{cups-configuration} parameter} boolean web-interface?
+Specifies whether the web interface is enabled.
-Defaults to @samp{30}.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} error-policy error-policy
-Specifies what to do when an error occurs. Possible values are
-@code{abort-job}, which will discard the failed print job;
-@code{retry-job}, which will retry the job at a later time;
-@code{retry-this-job}, which retries the failed job immediately; and
-@code{stop-printer}, which stops the printer.
+At this point you're probably thinking ``oh dear, Guix manual, I like
+you but you can stop already with the configuration options''. Indeed.
+However, one more point: it could be that you have an existing
+@code{cupsd.conf} that you want to use. In that case, you can pass an
+@code{opaque-cups-configuration} as the configuration of a
+@code{cups-service-type}.
-Defaults to @samp{stop-printer}.
+Available @code{opaque-cups-configuration} fields are:
+
+@deftypevr {@code{opaque-cups-configuration} parameter} package cups
+The CUPS package.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit
-Specifies the maximum cost of filters that are run concurrently, which
-can be used to minimize disk, memory, and CPU resource problems. A
-limit of 0 disables filter limiting. An average print to a
-non-PostScript printer needs a filter limit of about 200. A PostScript
-printer needs about half that (100). Setting the limit below these
-thresholds will effectively limit the scheduler to printing a single job
-at any time.
+@deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf
+The contents of the @code{cupsd.conf}, as a string.
+@end deftypevr
-Defaults to @samp{0}.
+@deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf
+The contents of the @code{cups-files.conf} file, as a string.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice
-Specifies the scheduling priority of filters that are run to print a
-job. The nice value ranges from 0, the highest priority, to 19, the
-lowest priority.
+For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in
+strings of the same name, you could instantiate a CUPS service like
+this:
-Defaults to @samp{0}.
-@end deftypevr
+@example
+(service cups-service-type
+ (opaque-cups-configuration
+ (cupsd.conf cupsd.conf)
+ (cups-files.conf cups-files.conf)))
+@end example
-@deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups
-Specifies whether to do reverse lookups on connecting clients. The
-@code{double} setting causes @code{cupsd} to verify that the hostname
-resolved from the address matches one of the addresses returned for that
-hostname. Double lookups also prevent clients with unregistered
-addresses from connecting to your server. Only set this option to
-@code{#t} or @code{double} if absolutely required.
-Defaults to @samp{#f}.
-@end deftypevr
+@node Desktop Services
+@subsection Desktop Services
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay
-Specifies the number of seconds to wait before killing the filters and
-backend associated with a canceled or held job.
+The @code{(gnu services desktop)} module provides services that are
+usually useful in the context of a ``desktop'' setup---that is, on a
+machine running a graphical display server, possibly with graphical user
+interfaces, etc. It also defines services that provide specific desktop
+environments like GNOME, XFCE or MATE.
-Defaults to @samp{30}.
-@end deftypevr
+To simplify things, the module defines a variable containing the set of
+services that users typically expect on a machine with a graphical
+environment and networking:
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval
-Specifies the interval between retries of jobs in seconds. This is
-typically used for fax queues but can also be used with normal print
-queues whose error policy is @code{retry-job} or
-@code{retry-current-job}.
+@defvr {Scheme Variable} %desktop-services
+This is a list of services that builds upon @var{%base-services} and
+adds or adjusts services for a typical ``desktop'' setup.
-Defaults to @samp{30}.
-@end deftypevr
+In particular, it adds a graphical login manager (@pxref{X Window,
+@code{slim-service}}), screen lockers, a network management tool
+(@pxref{Networking Services, @code{network-manager-service-type}}), energy and color
+management services, the @code{elogind} login and seat manager, the
+Polkit privilege service, the GeoClue location service, the
+AccountsService daemon that allows authorized users change system
+passwords, an NTP client (@pxref{Networking Services}), the Avahi
+daemon, and has the name service switch service configured to be able to
+use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}).
+@end defvr
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit
-Specifies the number of retries that are done for jobs. This is
-typically used for fax queues but can also be used with normal print
-queues whose error policy is @code{retry-job} or
-@code{retry-current-job}.
+The @var{%desktop-services} variable can be used as the @code{services}
+field of an @code{operating-system} declaration (@pxref{operating-system
+Reference, @code{services}}).
-Defaults to @samp{5}.
-@end deftypevr
+Additionally, the @code{gnome-desktop-service},
+@code{xfce-desktop-service}, @code{mate-desktop-service-type} and
+@code{enlightenment-desktop-service-type} procedures can add GNOME, XFCE, MATE
+and/or Enlightenment to a system. To ``add GNOME'' means that system-level
+services like the backlight adjustment helpers and the power management
+utilities are added to the system, extending @code{polkit} and @code{dbus}
+appropriately, allowing GNOME to operate with elevated privileges on a
+limited number of special-purpose system interfaces. Additionally,
+adding a service made by @code{gnome-desktop-service} adds the GNOME
+metapackage to the system profile. Likewise, adding the XFCE service
+not only adds the @code{xfce} metapackage to the system profile, but it
+also gives the Thunar file manager the ability to open a ``root-mode''
+file management window, if the user authenticates using the
+administrator's password via the standard polkit graphical interface.
+To ``add MATE'' means that @code{polkit} and @code{dbus} are extended
+appropriately, allowing MATE to operate with elevated privileges on a
+limited number of special-purpose system interfaces. Additionally,
+adding a service of type @code{mate-desktop-service-type} adds the MATE
+metapackage to the system profile. ``Adding Enlightenment'' means that
+@code{dbus} is extended appropriately, and several of Enlightenment's binaries
+are set as setuid, allowing Enlightenment's screen locker and other
+functionality to work as expetected.
-@deftypevr {@code{cups-configuration} parameter} boolean keep-alive?
-Specifies whether to support HTTP keep-alive connections.
+The desktop environments in Guix use the Xorg display server by
+default. If you'd like to use the newer display server protocol
+called Wayland, you need to use the @code{sddm-service} instead of the
+@code{slim-service} for the graphical login manager. You should then
+select the ``GNOME (Wayland)'' session in SDDM. Alternatively you can
+also try starting GNOME on Wayland manually from a TTY with the
+command ``XDG_SESSION_TYPE=wayland exec dbus-run-session
+gnome-session``. Currently only GNOME has support for Wayland.
-Defaults to @samp{#t}.
-@end deftypevr
+@deffn {Scheme Procedure} gnome-desktop-service
+Return a service that adds the @code{gnome} package to the system
+profile, and extends polkit with the actions from
+@code{gnome-settings-daemon}.
+@end deffn
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer keep-alive-timeout
-Specifies how long an idle client connection remains open, in seconds.
+@deffn {Scheme Procedure} xfce-desktop-service
+Return a service that adds the @code{xfce} package to the system profile,
+and extends polkit with the ability for @code{thunar} to manipulate the
+file system as root from within a user session, after the user has
+authenticated with the administrator's password.
+@end deffn
-Defaults to @samp{30}.
-@end deftypevr
+@deffn {Scheme Variable} mate-desktop-service-type
+This is the type of the service that runs the @uref{https://mate-desktop.org/,
+MATE desktop environment}. Its value is a @code{mate-desktop-configuration}
+object (see below.)
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
-Specifies the maximum size of print files, IPP requests, and HTML form
-data. A limit of 0 disables the limit check.
+This service adds the @code{mate} package to the system
+profile, and extends polkit with the actions from
+@code{mate-settings-daemon}.
+@end deffn
-Defaults to @samp{0}.
-@end deftypevr
+@deftp {Data Type} mate-desktop-configuration
+Configuration record for the MATE desktop environment.
-@deftypevr {@code{cups-configuration} parameter} multiline-string-list listen
-Listens on the specified interfaces for connections. Valid values are
-of the form @var{address}:@var{port}, where @var{address} is either an
-IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to
-indicate all addresses. Values can also be file names of local UNIX
-domain sockets. The Listen directive is similar to the Port directive
-but allows you to restrict access to specific interfaces or networks.
-@end deftypevr
+@table @asis
+@item @code{mate} (default @code{mate})
+The MATE package to use.
+@end table
+@end deftp
+
+@deffn {Scheme Variable} enlightenment-desktop-service-type
+Return a service that adds the @code{enlightenment} package to the system
+profile, and extends dbus with actions from @code{efl}.
+@end deffn
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log
-Specifies the number of pending connections that will be allowed. This
-normally only affects very busy servers that have reached the MaxClients
-limit, but can also be triggered by large numbers of simultaneous
-connections. When the limit is reached, the operating system will
-refuse additional connections until the scheduler can accept the pending
-ones.
+@deftp {Data Type} enlightenment-desktop-service-configuration
+@table @asis
+@item @code{enlightenment} (default @code{enlightenment})
+The enlightenment package to use.
+@end table
+@end deftp
-Defaults to @samp{128}.
-@end deftypevr
+Because the GNOME, XFCE and MATE desktop services pull in so many packages,
+the default @code{%desktop-services} variable doesn't include any of
+them by default. To add GNOME, XFCE or MATE, just @code{cons} them onto
+@code{%desktop-services} in the @code{services} field of your
+@code{operating-system}:
-@deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls
-Specifies a set of additional access controls.
+@example
+(use-modules (gnu))
+(use-service-modules desktop)
+(operating-system
+ ...
+ ;; cons* adds items to the list given as its last argument.
+ (services (cons* (gnome-desktop-service)
+ (xfce-desktop-service)
+ %desktop-services))
+ ...)
+@end example
-Available @code{location-access-controls} fields are:
+These desktop environments will then be available as options in the
+graphical login window.
-@deftypevr {@code{location-access-controls} parameter} file-name path
-Specifies the URI path to which the access control applies.
-@end deftypevr
+The actual service definitions included in @code{%desktop-services} and
+provided by @code{(gnu services dbus)} and @code{(gnu services desktop)}
+are described below.
-@deftypevr {@code{location-access-controls} parameter} access-control-list access-controls
-Access controls for all access to this path, in the same format as the
-@code{access-controls} of @code{operation-access-control}.
+@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
+Return a service that runs the ``system bus'', using @var{dbus}, with
+support for @var{services}.
-Defaults to @samp{()}.
-@end deftypevr
+@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
+facility. Its system bus is used to allow system services to communicate
+and to be notified of system-wide events.
-@deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls
-Access controls for method-specific access to this path.
+@var{services} must be a list of packages that provide an
+@file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
+and policy files. For example, to allow avahi-daemon to use the system bus,
+@var{services} must be equal to @code{(list avahi)}.
+@end deffn
-Defaults to @samp{()}.
+@deffn {Scheme Procedure} elogind-service [#:config @var{config}]
+Return a service that runs the @code{elogind} login and
+seat management daemon. @uref{https://github.com/elogind/elogind,
+Elogind} exposes a D-Bus interface that can be used to know which users
+are logged in, know what kind of sessions they have open, suspend the
+system, inhibit system suspend, reboot the system, and other tasks.
-Available @code{method-access-controls} fields are:
+Elogind handles most system-level power events for a computer, for
+example suspending the system when a lid is closed, or shutting it down
+when the power button is pressed.
-@deftypevr {@code{method-access-controls} parameter} boolean reverse?
-If @code{#t}, apply access controls to all methods except the listed
-methods. Otherwise apply to only the listed methods.
+The @var{config} keyword argument specifies the configuration for
+elogind, and should be the result of an @code{(elogind-configuration
+(@var{parameter} @var{value})...)} invocation. Available parameters and
+their default values are:
-Defaults to @samp{#f}.
-@end deftypevr
+@table @code
+@item kill-user-processes?
+@code{#f}
+@item kill-only-users
+@code{()}
+@item kill-exclude-users
+@code{("root")}
+@item inhibit-delay-max-seconds
+@code{5}
+@item handle-power-key
+@code{poweroff}
+@item handle-suspend-key
+@code{suspend}
+@item handle-hibernate-key
+@code{hibernate}
+@item handle-lid-switch
+@code{suspend}
+@item handle-lid-switch-docked
+@code{ignore}
+@item power-key-ignore-inhibited?
+@code{#f}
+@item suspend-key-ignore-inhibited?
+@code{#f}
+@item hibernate-key-ignore-inhibited?
+@code{#f}
+@item lid-switch-ignore-inhibited?
+@code{#t}
+@item holdoff-timeout-seconds
+@code{30}
+@item idle-action
+@code{ignore}
+@item idle-action-seconds
+@code{(* 30 60)}
+@item runtime-directory-size-percent
+@code{10}
+@item runtime-directory-size
+@code{#f}
+@item remove-ipc?
+@code{#t}
+@item suspend-state
+@code{("mem" "standby" "freeze")}
+@item suspend-mode
+@code{()}
+@item hibernate-state
+@code{("disk")}
+@item hibernate-mode
+@code{("platform" "shutdown")}
+@item hybrid-sleep-state
+@code{("disk")}
+@item hybrid-sleep-mode
+@code{("suspend" "platform" "shutdown")}
+@end table
+@end deffn
-@deftypevr {@code{method-access-controls} parameter} method-list methods
-Methods to which this access control applies.
+@deffn {Scheme Procedure} accountsservice-service @
+ [#:accountsservice @var{accountsservice}]
+Return a service that runs AccountsService, a system service that can
+list available accounts, change their passwords, and so on.
+AccountsService integrates with PolicyKit to enable unprivileged users
+to acquire the capability to modify their system configuration.
+@uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the
+accountsservice web site} for more information.
-Defaults to @samp{()}.
-@end deftypevr
+The @var{accountsservice} keyword argument is the @code{accountsservice}
+package to expose as a service.
+@end deffn
-@deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
-Access control directives, as a list of strings. Each string should be
-one directive, such as "Order allow,deny".
+@deffn {Scheme Procedure} polkit-service @
+ [#:polkit @var{polkit}]
+Return a service that runs the
+@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
+management service}, which allows system administrators to grant access to
+privileged operations in a structured way. By querying the Polkit service, a
+privileged system component can know when it should grant additional
+capabilities to ordinary users. For example, an ordinary user can be granted
+the capability to suspend the system if the user is logged in locally.
+@end deffn
-Defaults to @samp{()}.
-@end deftypevr
-@end deftypevr
-@end deftypevr
+@defvr {Scheme Variable} upower-service-type
+Service that runs @uref{http://upower.freedesktop.org/, @command{upowerd}}, a
+system-wide monitor for power consumption and battery levels, with the given
+configuration settings.
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history
-Specifies the number of debugging messages that are retained for logging
-if an error occurs in a print job. Debug messages are logged regardless
-of the LogLevel setting.
+It implements the @code{org.freedesktop.UPower} D-Bus interface, and is
+notably used by GNOME.
+@end defvr
-Defaults to @samp{100}.
-@end deftypevr
+@deftp {Data Type} upower-configuration
+Data type representation the configuration for UPower.
-@deftypevr {@code{cups-configuration} parameter} log-level log-level
-Specifies the level of logging for the ErrorLog file. The value
-@code{none} stops all logging while @code{debug2} logs everything.
+@table @asis
-Defaults to @samp{info}.
-@end deftypevr
+@item @code{upower} (default: @var{upower})
+Package to use for @code{upower}.
-@deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format
-Specifies the format of the date and time in the log files. The value
-@code{standard} logs whole seconds while @code{usecs} logs microseconds.
+@item @code{watts-up-pro?} (default: @code{#f})
+Enable the Watts Up Pro device.
-Defaults to @samp{standard}.
-@end deftypevr
+@item @code{poll-batteries?} (default: @code{#t})
+Enable polling the kernel for battery level changes.
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients
-Specifies the maximum number of simultaneous clients that are allowed by
-the scheduler.
+@item @code{ignore-lid?} (default: @code{#f})
+Ignore the lid state, this can be useful if it's incorrect on a device.
-Defaults to @samp{100}.
-@end deftypevr
+@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.
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host
-Specifies the maximum number of simultaneous clients that are allowed
-from a single address.
+@item @code{percentage-low} (default: @code{10})
+When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
+at which the battery is considered low.
-Defaults to @samp{100}.
-@end deftypevr
+@item @code{percentage-critical} (default: @code{3})
+When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
+at which the battery is considered critical.
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies
-Specifies the maximum number of copies that a user can print of each
-job.
+@item @code{percentage-action} (default: @code{2})
+When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
+at which action will be taken.
-Defaults to @samp{9999}.
-@end deftypevr
+@item @code{time-low} (default: @code{1200})
+When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
+seconds at which the battery is considered low.
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time
-Specifies the maximum time a job may remain in the @code{indefinite}
-hold state before it is canceled. A value of 0 disables cancellation of
-held jobs.
+@item @code{time-critical} (default: @code{300})
+When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
+seconds at which the battery is considered critical.
-Defaults to @samp{0}.
-@end deftypevr
+@item @code{time-action} (default: @code{120})
+When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
+seconds at which action will be taken.
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs
-Specifies the maximum number of simultaneous jobs that are allowed. Set
-to 0 to allow an unlimited number of jobs.
+@item @code{critical-power-action} (default: @code{'hybrid-sleep})
+The action taken when @code{percentage-action} or @code{time-action} is
+reached (depending on the configuration of @code{use-percentage-for-policy?}).
-Defaults to @samp{500}.
-@end deftypevr
+Possible values are:
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer
-Specifies the maximum number of simultaneous jobs that are allowed per
-printer. A value of 0 allows up to MaxJobs jobs per printer.
+@itemize @bullet
+@item
+@code{'power-off}
-Defaults to @samp{0}.
-@end deftypevr
+@item
+@code{'hibernate}
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user
-Specifies the maximum number of simultaneous jobs that are allowed per
-user. A value of 0 allows up to MaxJobs jobs per user.
+@item
+@code{'hybrid-sleep}.
+@end itemize
-Defaults to @samp{0}.
-@end deftypevr
+@end table
+@end deftp
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
-Specifies the maximum time a job may take to print before it is
-canceled, in seconds. Set to 0 to disable cancellation of "stuck" jobs.
+@deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
+Return a service for @uref{http://udisks.freedesktop.org/docs/latest/,
+UDisks}, a @dfn{disk management} daemon that provides user interfaces with
+notifications and ways to mount/unmount disks. Programs that talk to UDisks
+include the @command{udisksctl} command, part of UDisks, and GNOME Disks.
+@end deffn
-Defaults to @samp{10800}.
-@end deftypevr
+@deffn {Scheme Procedure} colord-service [#:colord @var{colord}]
+Return a service that runs @command{colord}, a system service with a D-Bus
+interface to manage the color profiles of input and output devices such as
+screens and scanners. It is notably used by the GNOME Color Manager graphical
+tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web
+site} for more information.
+@end deffn
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size
-Specifies the maximum size of the log files before they are rotated, in
-bytes. The value 0 disables log rotation.
+@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
+Return a configuration allowing an application to access GeoClue
+location data. @var{name} is the Desktop ID of the application, without
+the @code{.desktop} part. If @var{allowed?} is true, the application
+will have access to location information by default. The boolean
+@var{system?} value indicates whether an application is a system component
+or not. Finally @var{users} is a list of UIDs of all users for which
+this application is allowed location info access. An empty users list
+means that all users are allowed.
+@end deffn
-Defaults to @samp{1048576}.
-@end deftypevr
+@defvr {Scheme Variable} %standard-geoclue-applications
+The standard list of well-known GeoClue application configurations,
+granting authority to the GNOME date-and-time utility to ask for the
+current location in order to set the time zone, and allowing the
+IceCat and Epiphany web browsers to request location information.
+IceCat and Epiphany both query the user before allowing a web page to
+know the user's location.
+@end defvr
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout
-Specifies the maximum amount of time to allow between files in a
-multiple file print job, in seconds.
+@deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @
+ [#:whitelist '()] @
+ [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
+ [#:submit-data? #f]
+ [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] @
+ [#:submission-nick "geoclue"] @
+ [#:applications %standard-geoclue-applications]
+Return a service that runs the GeoClue location service. This service
+provides a D-Bus interface to allow applications to request access to a
+user's physical location, and optionally to add information to online
+location databases. See
+@uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue
+web site} for more information.
+@end deffn
-Defaults to @samp{300}.
-@end deftypevr
+@deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @
+ [@w{#:auto-enable? #f}]
+Return a service that runs the @command{bluetoothd} daemon, which
+manages all the Bluetooth devices and provides a number of D-Bus
+interfaces. When AUTO-ENABLE? is true, the bluetooth controller is
+powered automatically at boot, which can be useful when using a
+bluetooth keyboard or mouse.
-@deftypevr {@code{cups-configuration} parameter} string page-log-format
-Specifies the format of PageLog lines. Sequences beginning with percent
-(@samp{%}) characters are replaced with the corresponding information,
-while all other characters are copied literally. The following percent
-sequences are recognized:
+Users need to be in the @code{lp} group to access the D-Bus service.
+@end deffn
-@table @samp
-@item %%
-insert a single percent character
+@node Sound Services
+@subsection Sound Services
-@item %@{name@}
-insert the value of the specified IPP attribute
+@cindex sound support
+@cindex ALSA
+@cindex PulseAudio, sound support
-@item %C
-insert the number of copies for the current page
+The @code{(gnu services sound)} module provides a service to configure the
+Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the
+preferred ALSA output driver.
-@item %P
-insert the current page number
+@deffn {Scheme Variable} alsa-service-type
+This is the type for the @uref{https://alsa-project.org/, Advanced Linux Sound
+Architecture} (ALSA) system, which generates the @file{/etc/asound.conf}
+configuration file. The value for this type is a @command{alsa-configuration}
+record as in this example:
-@item %T
-insert the current date and time in common log format
+@example
+(service alsa-service-type)
+@end example
-@item %j
-insert the job ID
+See below for details about @code{alsa-configuration}.
+@end deffn
-@item %p
-insert the printer name
+@deftp {Data Type} alsa-configuration
+Data type representing the configuration for @code{alsa-service}.
-@item %u
-insert the username
-@end table
+@table @asis
+@item @code{alsa-plugins} (default: @var{alsa-plugins})
+@code{alsa-plugins} package to use.
-A value of the empty string disables page logging. The string @code{%p
-%u %j %T %P %C %@{job-billing@} %@{job-originating-host-name@}
-%@{job-name@} %@{media@} %@{sides@}} creates a page log with the
-standard items.
+@item @code{pulseaudio?} (default: @var{#t})
+Whether ALSA applications should transparently be made to use the
+@uref{http://www.pulseaudio.org/, PulseAudio} sound server.
-Defaults to @samp{""}.
-@end deftypevr
+Using PulseAudio allows you to run several sound-producing applications
+at the same time and to individual control them @i{via}
+@command{pavucontrol}, among other things.
-@deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables
-Passes the specified environment variable(s) to child processes; a list
-of strings.
+@item @code{extra-options} (default: @var{""})
+String to append to the @file{/etc/asound.conf} file.
-Defaults to @samp{()}.
-@end deftypevr
+@end table
+@end deftp
-@deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies
-Specifies named access control policies.
+Individual users who want to override the system configuration of ALSA can do
+it with the @file{~/.asoundrc} file:
-Available @code{policy-configuration} fields are:
+@example
+# In guix, we have to specify the absolute path for plugins.
+pcm_type.jack @{
+ lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so"
+@}
-@deftypevr {@code{policy-configuration} parameter} string name
-Name of the policy.
-@end deftypevr
+# Routing ALSA to jack:
+# <http://jackaudio.org/faq/routing_alsa.html>.
+pcm.rawjack @{
+ type jack
+ playback_ports @{
+ 0 system:playback_1
+ 1 system:playback_2
+ @}
-@deftypevr {@code{policy-configuration} parameter} string job-private-access
-Specifies an access list for a job's private values. @code{@@ACL} maps
-to the printer's requesting-user-name-allowed or
-requesting-user-name-denied values. @code{@@OWNER} maps to the job's
-owner. @code{@@SYSTEM} maps to the groups listed for the
-@code{system-group} field of the @code{files-config} configuration,
-which is reified into the @code{cups-files.conf(5)} file. Other
-possible elements of the access list include specific user names, and
-@code{@@@var{group}} to indicate members of a specific group. The
-access list may also be simply @code{all} or @code{default}.
+ capture_ports @{
+ 0 system:capture_1
+ 1 system:capture_2
+ @}
+@}
-Defaults to @samp{"@@OWNER @@SYSTEM"}.
-@end deftypevr
+pcm.!default @{
+ type plug
+ slave @{
+ pcm "rawjack"
+ @}
+@}
+@end example
-@deftypevr {@code{policy-configuration} parameter} string job-private-values
-Specifies the list of job values to make private, or @code{all},
-@code{default}, or @code{none}.
+See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the
+details.
-Defaults to @samp{"job-name job-originating-host-name
-job-originating-user-name phone"}.
-@end deftypevr
-@deftypevr {@code{policy-configuration} parameter} string subscription-private-access
-Specifies an access list for a subscription's private values.
-@code{@@ACL} maps to the printer's requesting-user-name-allowed or
-requesting-user-name-denied values. @code{@@OWNER} maps to the job's
-owner. @code{@@SYSTEM} maps to the groups listed for the
-@code{system-group} field of the @code{files-config} configuration,
-which is reified into the @code{cups-files.conf(5)} file. Other
-possible elements of the access list include specific user names, and
-@code{@@@var{group}} to indicate members of a specific group. The
-access list may also be simply @code{all} or @code{default}.
+@node Database Services
+@subsection Database Services
-Defaults to @samp{"@@OWNER @@SYSTEM"}.
-@end deftypevr
+@cindex database
+@cindex SQL
+The @code{(gnu services databases)} module provides the following services.
-@deftypevr {@code{policy-configuration} parameter} string subscription-private-values
-Specifies the list of job values to make private, or @code{all},
-@code{default}, or @code{none}.
+@deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @
+ [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] @
+ [#:port 5432] [#:locale ``en_US.utf8''] [#:extension-packages '()]
+Return a service that runs @var{postgresql}, the PostgreSQL database
+server.
-Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri
-notify-subscriber-user-name notify-user-data"}.
-@end deftypevr
+The PostgreSQL daemon loads its runtime configuration from @var{config-file},
+creates a database cluster with @var{locale} as the default
+locale, stored in @var{data-directory}. It then listens on @var{port}.
-@deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls
-Access control by IPP operation.
+@cindex postgresql extension-packages
+Additional extensions are loaded from packages listed in
+@var{extension-packages}. Extensions are available at runtime. For instance,
+to create a geographic database using the @code{postgis} extension, a user can
+configure the postgresql-service as in this example:
-Defaults to @samp{()}.
-@end deftypevr
-@end deftypevr
+@cindex postgis
+@example
+(use-package-modules databases geo)
-@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files
-Specifies whether job files (documents) are preserved after a job is
-printed. If a numeric value is specified, job files are preserved for
-the indicated number of seconds after printing. Otherwise a boolean
-value applies indefinitely.
+(operating-system
+ ...
+ ;; postgresql is required to run `psql' but postgis is not required for
+ ;; proper operation.
+ (packages (cons* postgresql %base-packages))
+ (services
+ (cons*
+ (postgresql-service #:extension-packages (list postgis))
+ %base-services)))
+@end example
-Defaults to @samp{86400}.
-@end deftypevr
+Then the extension becomes visible and you can initialise an empty geographic
+database in this way:
-@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history
-Specifies whether the job history is preserved after a job is printed.
-If a numeric value is specified, the job history is preserved for the
-indicated number of seconds after printing. If @code{#t}, the job
-history is preserved until the MaxJobs limit is reached.
+@example
+psql -U postgres
+> create database postgistest;
+> \connect postgistest;
+> create extension postgis;
+> create extension postgis_topology;
+@end example
-Defaults to @samp{#t}.
-@end deftypevr
+There is no need to add this field for contrib extensions such as hstore or
+dblink as they are already loadable by postgresql. This field is only
+required to add extensions provided by other packages.
+@end deffn
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout
-Specifies the amount of time to wait for job completion before
-restarting the scheduler.
+@deffn {Scheme Procedure} mysql-service [#:config (mysql-configuration)]
+Return a service that runs @command{mysqld}, the MySQL or MariaDB
+database server.
-Defaults to @samp{30}.
-@end deftypevr
+The optional @var{config} argument specifies the configuration for
+@command{mysqld}, which should be a @code{<mysql-configuration>} object.
+@end deffn
-@deftypevr {@code{cups-configuration} parameter} string rip-cache
-Specifies the maximum amount of memory to use when converting documents
-into bitmaps for a printer.
+@deftp {Data Type} mysql-configuration
+Data type representing the configuration of @var{mysql-service}.
-Defaults to @samp{"128m"}.
-@end deftypevr
+@table @asis
+@item @code{mysql} (default: @var{mariadb})
+Package object of the MySQL database server, can be either @var{mariadb}
+or @var{mysql}.
-@deftypevr {@code{cups-configuration} parameter} string server-admin
-Specifies the email address of the server administrator.
+For MySQL, a temporary root password will be displayed at activation time.
+For MariaDB, the root password is empty.
-Defaults to @samp{"root@@localhost.localdomain"}.
-@end deftypevr
+@item @code{port} (default: @code{3306})
+TCP port on which the database server listens for incoming connections.
+@end table
+@end deftp
-@deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias
-The ServerAlias directive is used for HTTP Host header validation when
-clients connect to the scheduler from external interfaces. Using the
-special name @code{*} can expose your system to known browser-based DNS
-rebinding attacks, even when accessing sites through a firewall. If the
-auto-discovery of alternate names does not work, we recommend listing
-each alternate name with a ServerAlias directive instead of using
-@code{*}.
+@defvr {Scheme Variable} memcached-service-type
+This is the service type for the @uref{https://memcached.org/,
+Memcached} service, which provides a distributed in memory cache. The
+value for the service type is a @code{memcached-configuration} object.
+@end defvr
-Defaults to @samp{*}.
-@end deftypevr
+@example
+(service memcached-service-type)
+@end example
-@deftypevr {@code{cups-configuration} parameter} string server-name
-Specifies the fully-qualified host name of the server.
+@deftp {Data Type} memcached-configuration
+Data type representing the configuration of memcached.
-Defaults to @samp{"localhost"}.
-@end deftypevr
+@table @asis
+@item @code{memcached} (default: @code{memcached})
+The Memcached package to use.
-@deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens
-Specifies what information is included in the Server header of HTTP
-responses. @code{None} disables the Server header. @code{ProductOnly}
-reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor}
-reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}.
-@code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is
-the output of the @code{uname} command. @code{Full} reports @code{CUPS
-2.0.0 (@var{uname}) IPP/2.0}.
+@item @code{interfaces} (default: @code{'("0.0.0.0")})
+Network interfaces on which to listen.
-Defaults to @samp{Minimal}.
-@end deftypevr
+@item @code{tcp-port} (default: @code{11211})
+Port on which to accept connections on,
-@deftypevr {@code{cups-configuration} parameter} string set-env
-Set the specified environment variable to be passed to child processes.
+@item @code{udp-port} (default: @code{11211})
+Port on which to accept UDP connections on, a value of 0 will disable
+listening on a UDP socket.
-Defaults to @samp{"variable value"}.
-@end deftypevr
+@item @code{additional-options} (default: @code{'()})
+Additional command line options to pass to @code{memcached}.
+@end table
+@end deftp
-@deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen
-Listens on the specified interfaces for encrypted connections. Valid
-values are of the form @var{address}:@var{port}, where @var{address} is
-either an IPv6 address enclosed in brackets, an IPv4 address, or
-@code{*} to indicate all addresses.
+@defvr {Scheme Variable} mongodb-service-type
+This is the service type for @uref{https://www.mongodb.com/, MongoDB}.
+The value for the service type is a @code{mongodb-configuration} object.
+@end defvr
-Defaults to @samp{()}.
-@end deftypevr
+@example
+(service mongodb-service-type)
+@end example
-@deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
-Sets encryption options. By default, CUPS only supports encryption
-using TLS v1.0 or higher using known secure cipher suites. The
-@code{AllowRC4} option enables the 128-bit RC4 cipher suites, which are
-required for some older clients that do not implement newer ones. The
-@code{AllowSSL3} option enables SSL v3.0, which is required for some
-older clients that do not support TLS v1.0.
+@deftp {Data Type} mongodb-configuration
+Data type representing the configuration of mongodb.
-Defaults to @samp{()}.
-@end deftypevr
+@table @asis
+@item @code{mongodb} (default: @code{mongodb})
+The MongoDB package to use.
-@deftypevr {@code{cups-configuration} parameter} boolean strict-conformance?
-Specifies whether the scheduler requires clients to strictly adhere to
-the IPP specifications.
+@item @code{config-file} (default: @code{%default-mongodb-configuration-file})
+The configuration file for MongoDB.
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{data-directory} (default: @code{"/var/lib/mongodb"})
+This value is used to create the directory, so that it exists and is
+owned by the mongodb user. It should match the data-directory which
+MongoDB is configured to use through the configuration file.
+@end table
+@end deftp
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout
-Specifies the HTTP request timeout, in seconds.
+@defvr {Scheme Variable} redis-service-type
+This is the service type for the @uref{https://redis.io/, Redis}
+key/value store, whose value is a @code{redis-configuration} object.
+@end defvr
-Defaults to @samp{300}.
+@deftp {Data Type} redis-configuration
+Data type representing the configuration of redis.
-@end deftypevr
+@table @asis
+@item @code{redis} (default: @code{redis})
+The Redis package to use.
-@deftypevr {@code{cups-configuration} parameter} boolean web-interface?
-Specifies whether the web interface is enabled.
+@item @code{bind} (default: @code{"127.0.0.1"})
+Network interface on which to listen.
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{port} (default: @code{6379})
+Port on which to accept connections on, a value of 0 will disable
+listening on a TCP socket.
-At this point you're probably thinking ``oh dear, Guix manual, I like
-you but you can stop already with the configuration options''. Indeed.
-However, one more point: it could be that you have an existing
-@code{cupsd.conf} that you want to use. In that case, you can pass an
-@code{opaque-cups-configuration} as the configuration of a
-@code{cups-service-type}.
+@item @code{working-directory} (default: @code{"/var/lib/redis"})
+Directory in which to store the database and related files.
+@end table
+@end deftp
-Available @code{opaque-cups-configuration} fields are:
+@node Mail Services
+@subsection Mail Services
-@deftypevr {@code{opaque-cups-configuration} parameter} package cups
-The CUPS package.
-@end deftypevr
+@cindex mail
+@cindex email
+The @code{(gnu services mail)} module provides Guix service definitions
+for email services: IMAP, POP3, and LMTP servers, as well as mail
+transport agents (MTAs). Lots of acronyms! These services are detailed
+in the subsections below.
-@deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf
-The contents of the @code{cupsd.conf}, as a string.
-@end deftypevr
+@subsubheading Dovecot Service
-@deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf
-The contents of the @code{cups-files.conf} file, as a string.
-@end deftypevr
+@deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)]
+Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.
+@end deffn
-For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in
-strings of the same name, you could instantiate a CUPS service like
-this:
+By default, Dovecot does not need much configuration; the default
+configuration object created by @code{(dovecot-configuration)} will
+suffice if your mail is delivered to @code{~/Maildir}. A self-signed
+certificate will be generated for TLS-protected connections, though
+Dovecot will also listen on cleartext ports by default. There are a
+number of options, though, which mail administrators might need to change,
+and as is the case with other services, Guix allows the system
+administrator to specify these parameters via a uniform Scheme interface.
+
+For example, to specify that mail is located at @code{maildir~/.mail},
+one would instantiate the Dovecot service like this:
@example
-(service cups-service-type
- (opaque-cups-configuration
- (cupsd.conf cupsd.conf)
- (cups-files.conf cups-files.conf)))
+(dovecot-service #:config
+ (dovecot-configuration
+ (mail-location "maildir:~/.mail")))
@end example
+The available configuration parameters follow. Each parameter
+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. There is also a way to specify the configuration as a string,
+if you have an old @code{dovecot.conf} file that you want to port over
+from some other system; see the end for more details.
-@node Desktop Services
-@subsubsection Desktop Services
+@c The following documentation was initially generated by
+@c (generate-documentation) in (gnu services mail). Manually maintained
+@c documentation is better, so we shouldn't hesitate to edit below as
+@c needed. However if the change you want to make to this documentation
+@c can be done in an automated way, it's probably easier to change
+@c (generate-documentation) than to make it below and have to deal with
+@c the churn as dovecot updates.
-The @code{(gnu services desktop)} module provides services that are
-usually useful in the context of a ``desktop'' setup---that is, on a
-machine running a graphical display server, possibly with graphical user
-interfaces, etc. It also defines services that provide specific desktop
-environments like GNOME, XFCE or MATE.
+Available @code{dovecot-configuration} fields are:
-To simplify things, the module defines a variable containing the set of
-services that users typically expect on a machine with a graphical
-environment and networking:
+@deftypevr {@code{dovecot-configuration} parameter} package dovecot
+The dovecot package.
+@end deftypevr
-@defvr {Scheme Variable} %desktop-services
-This is a list of services that builds upon @var{%base-services} and
-adds or adjusts services for a typical ``desktop'' setup.
+@deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen
+A list of IPs or hosts where to listen for connections. @samp{*}
+listens on all IPv4 interfaces, @samp{::} listens on all IPv6
+interfaces. If you want to specify non-default ports or anything more
+complex, customize the address and port fields of the
+@samp{inet-listener} of the specific services you are interested in.
+@end deftypevr
-In particular, it adds a graphical login manager (@pxref{X Window,
-@code{slim-service}}), screen lockers, a network management tool
-(@pxref{Networking Services, @code{network-manager-service-type}}), energy and color
-management services, the @code{elogind} login and seat manager, the
-Polkit privilege service, the GeoClue location service, the
-AccountsService daemon that allows authorized users change system
-passwords, an NTP client (@pxref{Networking Services}), the Avahi
-daemon, and has the name service switch service configured to be able to
-use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}).
-@end defvr
+@deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols
+List of protocols we want to serve. Available protocols include
+@samp{imap}, @samp{pop3}, and @samp{lmtp}.
-The @var{%desktop-services} variable can be used as the @code{services}
-field of an @code{operating-system} declaration (@pxref{operating-system
-Reference, @code{services}}).
+Available @code{protocol-configuration} fields are:
-Additionally, the @code{gnome-desktop-service},
-@code{xfce-desktop-service}, @code{mate-desktop-service} and
-@code{enlightenment-desktop-service-type} procedures can add GNOME, XFCE, MATE
-and/or Enlightenment to a system. To ``add GNOME'' means that system-level
-services like the backlight adjustment helpers and the power management
-utilities are added to the system, extending @code{polkit} and @code{dbus}
-appropriately, allowing GNOME to operate with elevated privileges on a
-limited number of special-purpose system interfaces. Additionally,
-adding a service made by @code{gnome-desktop-service} adds the GNOME
-metapackage to the system profile. Likewise, adding the XFCE service
-not only adds the @code{xfce} metapackage to the system profile, but it
-also gives the Thunar file manager the ability to open a ``root-mode''
-file management window, if the user authenticates using the
-administrator's password via the standard polkit graphical interface.
-To ``add MATE'' means that @code{polkit} and @code{dbus} are extended
-appropriately, allowing MATE to operate with elevated privileges on a
-limited number of special-purpose system interfaces. Additionally,
-adding a service made by @code{mate-desktop-service} adds the MATE
-metapackage to the system profile. ``Adding ENLIGHTENMENT'' means that
-@code{dbus} is extended appropriately, and several of Enlightenment's binaries
-are set as setuid, allowing Enlightenment's screen locker and other
-functionality to work as expetected.
+@deftypevr {@code{protocol-configuration} parameter} string name
+The name of the protocol.
+@end deftypevr
-The desktop environments in Guix use the Xorg display server by
-default. If you'd like to use the newer display server protocol
-called Wayland, you need to use the @code{sddm-service} instead of the
-@code{slim-service} for the graphical login manager. You should then
-select the ``GNOME (Wayland)'' session in SDDM. Alternatively you can
-also try starting GNOME on Wayland manually from a TTY with the
-command ``XDG_SESSION_TYPE=wayland exec dbus-run-session
-gnome-session``. Currently only GNOME has support for Wayland.
+@deftypevr {@code{protocol-configuration} parameter} string auth-socket-path
+UNIX socket path to the master authentication server to find users.
+This is used by imap (for shared users) and lda.
+It defaults to @samp{"/var/run/dovecot/auth-userdb"}.
+@end deftypevr
-@deffn {Scheme Procedure} gnome-desktop-service
-Return a service that adds the @code{gnome} package to the system
-profile, and extends polkit with the actions from
-@code{gnome-settings-daemon}.
-@end deffn
+@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins
+Space separated list of plugins to load.
+@end deftypevr
+
+@deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections
+Maximum number of IMAP connections allowed for a user from each IP
+address. NOTE: The username is compared case-sensitively.
+Defaults to @samp{10}.
+@end deftypevr
-@deffn {Scheme Procedure} xfce-desktop-service
-Return a service that adds the @code{xfce} package to the system profile,
-and extends polkit with the ability for @code{thunar} to manipulate the
-file system as root from within a user session, after the user has
-authenticated with the administrator's password.
-@end deffn
+@end deftypevr
-@deffn {Scheme Procedure} mate-desktop-service
-Return a service that adds the @code{mate} package to the system
-profile, and extends polkit with the actions from
-@code{mate-settings-daemon}.
-@end deffn
+@deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services
+List of services to enable. Available services include @samp{imap},
+@samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and
+@samp{lmtp}.
-@deffn {Scheme Procedure} enlightenment-desktop-service-type
-Return a service that adds the @code{enlightenment} package to the system
-profile, and extends dbus with actions from @code{efl}.
-@end deffn
+Available @code{service-configuration} fields are:
-@deftp {Data Type} enlightenment-desktop-service-configuration
-@table @asis
-@item @code{enlightenment} (default @code{enlightenment})
-The enlightenment package to use.
-@end table
-@end deftp
+@deftypevr {@code{service-configuration} parameter} string kind
+The service kind. Valid values include @code{director},
+@code{imap-login}, @code{pop3-login}, @code{lmtp}, @code{imap},
+@code{pop3}, @code{auth}, @code{auth-worker}, @code{dict},
+@code{tcpwrap}, @code{quota-warning}, or anything else.
+@end deftypevr
-Because the GNOME, XFCE and MATE desktop services pull in so many packages,
-the default @code{%desktop-services} variable doesn't include any of
-them by default. To add GNOME, XFCE or MATE, just @code{cons} them onto
-@code{%desktop-services} in the @code{services} field of your
-@code{operating-system}:
+@deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners
+Listeners for the service. A listener is either a
+@code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or
+an @code{inet-listener-configuration}.
+Defaults to @samp{()}.
-@example
-(use-modules (gnu))
-(use-service-modules desktop)
-(operating-system
- ...
- ;; cons* adds items to the list given as its last argument.
- (services (cons* (gnome-desktop-service)
- (xfce-desktop-service)
- %desktop-services))
- ...)
-@end example
+Available @code{unix-listener-configuration} fields are:
-These desktop environments will then be available as options in the
-graphical login window.
+@deftypevr {@code{unix-listener-configuration} parameter} string path
+Path to the file, relative to @code{base-dir} field. This is also used as
+the section name.
+@end deftypevr
-The actual service definitions included in @code{%desktop-services} and
-provided by @code{(gnu services dbus)} and @code{(gnu services desktop)}
-are described below.
+@deftypevr {@code{unix-listener-configuration} parameter} string mode
+The access mode for the socket.
+Defaults to @samp{"0600"}.
+@end deftypevr
-@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
-Return a service that runs the ``system bus'', using @var{dbus}, with
-support for @var{services}.
+@deftypevr {@code{unix-listener-configuration} parameter} string user
+The user to own the socket.
+Defaults to @samp{""}.
+@end deftypevr
-@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
-facility. Its system bus is used to allow system services to communicate
-and to be notified of system-wide events.
+@deftypevr {@code{unix-listener-configuration} parameter} string group
+The group to own the socket.
+Defaults to @samp{""}.
+@end deftypevr
-@var{services} must be a list of packages that provide an
-@file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
-and policy files. For example, to allow avahi-daemon to use the system bus,
-@var{services} must be equal to @code{(list avahi)}.
-@end deffn
-@deffn {Scheme Procedure} elogind-service [#:config @var{config}]
-Return a service that runs the @code{elogind} login and
-seat management daemon. @uref{https://github.com/elogind/elogind,
-Elogind} exposes a D-Bus interface that can be used to know which users
-are logged in, know what kind of sessions they have open, suspend the
-system, inhibit system suspend, reboot the system, and other tasks.
+Available @code{fifo-listener-configuration} fields are:
-Elogind handles most system-level power events for a computer, for
-example suspending the system when a lid is closed, or shutting it down
-when the power button is pressed.
+@deftypevr {@code{fifo-listener-configuration} parameter} string path
+Path to the file, relative to @code{base-dir} field. This is also used as
+the section name.
+@end deftypevr
-The @var{config} keyword argument specifies the configuration for
-elogind, and should be the result of an @code{(elogind-configuration
-(@var{parameter} @var{value})...)} invocation. Available parameters and
-their default values are:
+@deftypevr {@code{fifo-listener-configuration} parameter} string mode
+The access mode for the socket.
+Defaults to @samp{"0600"}.
+@end deftypevr
-@table @code
-@item kill-user-processes?
-@code{#f}
-@item kill-only-users
-@code{()}
-@item kill-exclude-users
-@code{("root")}
-@item inhibit-delay-max-seconds
-@code{5}
-@item handle-power-key
-@code{poweroff}
-@item handle-suspend-key
-@code{suspend}
-@item handle-hibernate-key
-@code{hibernate}
-@item handle-lid-switch
-@code{suspend}
-@item handle-lid-switch-docked
-@code{ignore}
-@item power-key-ignore-inhibited?
-@code{#f}
-@item suspend-key-ignore-inhibited?
-@code{#f}
-@item hibernate-key-ignore-inhibited?
-@code{#f}
-@item lid-switch-ignore-inhibited?
-@code{#t}
-@item holdoff-timeout-seconds
-@code{30}
-@item idle-action
-@code{ignore}
-@item idle-action-seconds
-@code{(* 30 60)}
-@item runtime-directory-size-percent
-@code{10}
-@item runtime-directory-size
-@code{#f}
-@item remove-ipc?
-@code{#t}
-@item suspend-state
-@code{("mem" "standby" "freeze")}
-@item suspend-mode
-@code{()}
-@item hibernate-state
-@code{("disk")}
-@item hibernate-mode
-@code{("platform" "shutdown")}
-@item hybrid-sleep-state
-@code{("disk")}
-@item hybrid-sleep-mode
-@code{("suspend" "platform" "shutdown")}
-@end table
-@end deffn
+@deftypevr {@code{fifo-listener-configuration} parameter} string user
+The user to own the socket.
+Defaults to @samp{""}.
+@end deftypevr
-@deffn {Scheme Procedure} accountsservice-service @
- [#:accountsservice @var{accountsservice}]
-Return a service that runs AccountsService, a system service that can
-list available accounts, change their passwords, and so on.
-AccountsService integrates with PolicyKit to enable unprivileged users
-to acquire the capability to modify their system configuration.
-@uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the
-accountsservice web site} for more information.
+@deftypevr {@code{fifo-listener-configuration} parameter} string group
+The group to own the socket.
+Defaults to @samp{""}.
+@end deftypevr
-The @var{accountsservice} keyword argument is the @code{accountsservice}
-package to expose as a service.
-@end deffn
-@deffn {Scheme Procedure} polkit-service @
- [#:polkit @var{polkit}]
-Return a service that runs the
-@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
-management service}, which allows system administrators to grant access to
-privileged operations in a structured way. By querying the Polkit service, a
-privileged system component can know when it should grant additional
-capabilities to ordinary users. For example, an ordinary user can be granted
-the capability to suspend the system if the user is logged in locally.
-@end deffn
+Available @code{inet-listener-configuration} fields are:
-@deffn {Scheme Procedure} upower-service [#:upower @var{upower}] @
- [#:watts-up-pro? #f] @
- [#:poll-batteries? #t] @
- [#:ignore-lid? #f] @
- [#:use-percentage-for-policy? #f] @
- [#:percentage-low 10] @
- [#:percentage-critical 3] @
- [#:percentage-action 2] @
- [#:time-low 1200] @
- [#:time-critical 300] @
- [#:time-action 120] @
- [#:critical-power-action 'hybrid-sleep]
-Return a service that runs @uref{http://upower.freedesktop.org/,
-@command{upowerd}}, a system-wide monitor for power consumption and battery
-levels, with the given configuration settings. It implements the
-@code{org.freedesktop.UPower} D-Bus interface, and is notably used by
-GNOME.
-@end deffn
+@deftypevr {@code{inet-listener-configuration} parameter} string protocol
+The protocol to listen for.
+@end deftypevr
-@deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
-Return a service for @uref{http://udisks.freedesktop.org/docs/latest/,
-UDisks}, a @dfn{disk management} daemon that provides user interfaces with
-notifications and ways to mount/unmount disks. Programs that talk to UDisks
-include the @command{udisksctl} command, part of UDisks, and GNOME Disks.
-@end deffn
+@deftypevr {@code{inet-listener-configuration} parameter} string address
+The address on which to listen, or empty for all addresses.
+Defaults to @samp{""}.
+@end deftypevr
-@deffn {Scheme Procedure} colord-service [#:colord @var{colord}]
-Return a service that runs @command{colord}, a system service with a D-Bus
-interface to manage the color profiles of input and output devices such as
-screens and scanners. It is notably used by the GNOME Color Manager graphical
-tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web
-site} for more information.
-@end deffn
+@deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port
+The port on which to listen.
+@end deftypevr
-@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
-Return a configuration allowing an application to access GeoClue
-location data. @var{name} is the Desktop ID of the application, without
-the @code{.desktop} part. If @var{allowed?} is true, the application
-will have access to location information by default. The boolean
-@var{system?} value indicates whether an application is a system component
-or not. Finally @var{users} is a list of UIDs of all users for which
-this application is allowed location info access. An empty users list
-means that all users are allowed.
-@end deffn
+@deftypevr {@code{inet-listener-configuration} parameter} boolean ssl?
+Whether to use SSL for this service; @samp{yes}, @samp{no}, or
+@samp{required}.
+Defaults to @samp{#t}.
+@end deftypevr
-@defvr {Scheme Variable} %standard-geoclue-applications
-The standard list of well-known GeoClue application configurations,
-granting authority to the GNOME date-and-time utility to ask for the
-current location in order to set the time zone, and allowing the
-IceCat and Epiphany web browsers to request location information.
-IceCat and Epiphany both query the user before allowing a web page to
-know the user's location.
-@end defvr
+@end deftypevr
-@deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @
- [#:whitelist '()] @
- [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
- [#:submit-data? #f]
- [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] @
- [#:submission-nick "geoclue"] @
- [#:applications %standard-geoclue-applications]
-Return a service that runs the GeoClue location service. This service
-provides a D-Bus interface to allow applications to request access to a
-user's physical location, and optionally to add information to online
-location databases. See
-@uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue
-web site} for more information.
-@end deffn
+@deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit
+Maximum number of simultaneous client connections per process. Once
+this number of connections is received, the next incoming connection
+will prompt Dovecot to spawn another process. If set to 0,
+@code{default-client-limit} is used instead.
-@deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @
- [@w{#:auto-enable? #f}]
-Return a service that runs the @command{bluetoothd} daemon, which
-manages all the Bluetooth devices and provides a number of D-Bus
-interfaces. When AUTO-ENABLE? is true, the bluetooth controller is
-powered automatically at boot, which can be useful when using a
-bluetooth keyboard or mouse.
+Defaults to @samp{0}.
-Users need to be in the @code{lp} group to access the D-Bus service.
-@end deffn
+@end deftypevr
-@node Sound Services
-@subsubsection Sound Services
+@deftypevr {@code{service-configuration} parameter} non-negative-integer service-count
+Number of connections to handle before starting a new process.
+Typically the only useful values are 0 (unlimited) or 1. 1 is more
+secure, but 0 is faster. <doc/wiki/LoginProcess.txt>.
+Defaults to @samp{1}.
-@cindex sound support
-@cindex ALSA
-@cindex PulseAudio, sound support
+@end deftypevr
-The @code{(gnu services sound)} module provides a service to configure the
-Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the
-preferred ALSA output driver.
+@deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit
+Maximum number of processes that can exist for this service. If set to
+0, @code{default-process-limit} is used instead.
-@deffn {Scheme Variable} alsa-service-type
-This is the type for the @uref{https://alsa-project.org/, Advanced Linux Sound
-Architecture} (ALSA) system, which generates the @file{/etc/asound.conf}
-configuration file. The value for this type is a @command{alsa-configuration}
-record as in this example:
+Defaults to @samp{0}.
-@example
-(service alsa-service-type)
-@end example
+@end deftypevr
-See below for details about @code{alsa-configuration}.
-@end deffn
+@deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail
+Number of processes to always keep waiting for more connections.
+Defaults to @samp{0}.
+@end deftypevr
-@deftp {Data Type} alsa-configuration
-Data type representing the configuration for @code{alsa-service}.
+@deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit
+If you set @samp{service-count 0}, you probably need to grow
+this.
+Defaults to @samp{256000000}.
+@end deftypevr
-@table @asis
-@item @code{alsa-plugins} (default: @var{alsa-plugins})
-@code{alsa-plugins} package to use.
+@end deftypevr
-@item @code{pulseaudio?} (default: @var{#t})
-Whether ALSA applications should transparently be made to use the
-@uref{http://www.pulseaudio.org/, PulseAudio} sound server.
+@deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict
+Dict configuration, as created by the @code{dict-configuration}
+constructor.
-Using PulseAudio allows you to run several sound-producing applications
-at the same time and to individual control them @i{via}
-@command{pavucontrol}, among other things.
+Available @code{dict-configuration} fields are:
-@item @code{extra-options} (default: @var{""})
-String to append to the @file{/etc/asound.conf} file.
+@deftypevr {@code{dict-configuration} parameter} free-form-fields entries
+A list of key-value pairs that this dict should hold.
+Defaults to @samp{()}.
+@end deftypevr
-@end table
-@end deftp
+@end deftypevr
-Individual users who want to override the system configuration of ALSA can do
-it with the @file{~/.asoundrc} file:
+@deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs
+A list of passdb configurations, each one created by the
+@code{passdb-configuration} constructor.
-@example
-# In guix, we have to specify the absolute path for plugins.
-pcm_type.jack @{
- lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so"
-@}
+Available @code{passdb-configuration} fields are:
-# Routing ALSA to jack:
-# <http://jackaudio.org/faq/routing_alsa.html>.
-pcm.rawjack @{
- type jack
- playback_ports @{
- 0 system:playback_1
- 1 system:playback_2
- @}
+@deftypevr {@code{passdb-configuration} parameter} string driver
+The driver that the passdb should use. Valid values include
+@samp{pam}, @samp{passwd}, @samp{shadow}, @samp{bsdauth}, and
+@samp{static}.
+Defaults to @samp{"pam"}.
+@end deftypevr
- capture_ports @{
- 0 system:capture_1
- 1 system:capture_2
- @}
-@}
+@deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args
+Space separated list of arguments to the passdb driver.
+Defaults to @samp{""}.
+@end deftypevr
-pcm.!default @{
- type plug
- slave @{
- pcm "rawjack"
- @}
-@}
-@end example
+@end deftypevr
-See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the
-details.
+@deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs
+List of userdb configurations, each one created by the
+@code{userdb-configuration} constructor.
+Available @code{userdb-configuration} fields are:
-@node Database Services
-@subsubsection Database Services
+@deftypevr {@code{userdb-configuration} parameter} string driver
+The driver that the userdb should use. Valid values include
+@samp{passwd} and @samp{static}.
+Defaults to @samp{"passwd"}.
+@end deftypevr
-@cindex database
-@cindex SQL
-The @code{(gnu services databases)} module provides the following services.
+@deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args
+Space separated list of arguments to the userdb driver.
+Defaults to @samp{""}.
+@end deftypevr
-@deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @
- [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] @
- [#:port 5432] [#:locale ``en_US.utf8'']
-Return a service that runs @var{postgresql}, the PostgreSQL database
-server.
+@deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields
+Override fields from passwd.
+Defaults to @samp{()}.
+@end deftypevr
-The PostgreSQL daemon loads its runtime configuration from @var{config-file},
-creates a database cluster with @var{locale} as the default
-locale, stored in @var{data-directory}. It then listens on @var{port}.
-@end deffn
+@end deftypevr
-@deffn {Scheme Procedure} mysql-service [#:config (mysql-configuration)]
-Return a service that runs @command{mysqld}, the MySQL or MariaDB
-database server.
+@deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration
+Plug-in configuration, created by the @code{plugin-configuration}
+constructor.
+@end deftypevr
-The optional @var{config} argument specifies the configuration for
-@command{mysqld}, which should be a @code{<mysql-configuration>} object.
-@end deffn
+@deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces
+List of namespaces. Each item in the list is created by the
+@code{namespace-configuration} constructor.
-@deftp {Data Type} mysql-configuration
-Data type representing the configuration of @var{mysql-service}.
+Available @code{namespace-configuration} fields are:
-@table @asis
-@item @code{mysql} (default: @var{mariadb})
-Package object of the MySQL database server, can be either @var{mariadb}
-or @var{mysql}.
+@deftypevr {@code{namespace-configuration} parameter} string name
+Name for this namespace.
+@end deftypevr
-For MySQL, a temporary root password will be displayed at activation time.
-For MariaDB, the root password is empty.
+@deftypevr {@code{namespace-configuration} parameter} string type
+Namespace type: @samp{private}, @samp{shared} or @samp{public}.
+Defaults to @samp{"private"}.
+@end deftypevr
-@item @code{port} (default: @code{3306})
-TCP port on which the database server listens for incoming connections.
-@end table
-@end deftp
+@deftypevr {@code{namespace-configuration} parameter} string separator
+Hierarchy separator to use. You should use the same separator for
+all namespaces or some clients get confused. @samp{/} is usually a good
+one. The default however depends on the underlying mail storage
+format.
+Defaults to @samp{""}.
+@end deftypevr
-@defvr {Scheme Variable} memcached-service-type
-This is the service type for the @uref{https://memcached.org/,
-Memcached} service, which provides a distributed in memory cache. The
-value for the service type is a @code{memcached-configuration} object.
-@end defvr
+@deftypevr {@code{namespace-configuration} parameter} string prefix
+Prefix required to access this namespace. This needs to be
+different for all namespaces. For example @samp{Public/}.
+Defaults to @samp{""}.
+@end deftypevr
-@example
-(service memcached-service-type)
-@end example
+@deftypevr {@code{namespace-configuration} parameter} string location
+Physical location of the mailbox. This is in the same format as
+mail_location, which is also the default for it.
+Defaults to @samp{""}.
+@end deftypevr
-@deftp {Data Type} memcached-configuration
-Data type representing the configuration of memcached.
+@deftypevr {@code{namespace-configuration} parameter} boolean inbox?
+There can be only one INBOX, and this setting defines which
+namespace has it.
+Defaults to @samp{#f}.
+@end deftypevr
-@table @asis
-@item @code{memcached} (default: @code{memcached})
-The Memcached package to use.
+@deftypevr {@code{namespace-configuration} parameter} boolean hidden?
+If namespace is hidden, it's not advertised to clients via NAMESPACE
+extension. You'll most likely also want to set @samp{list? #f}. This is mostly
+useful when converting from another server with different namespaces
+which you want to deprecate but still keep working. For example you can
+create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/}
+and @samp{mail/}.
+Defaults to @samp{#f}.
+@end deftypevr
-@item @code{interfaces} (default: @code{'("0.0.0.0")})
-Network interfaces on which to listen.
+@deftypevr {@code{namespace-configuration} parameter} boolean list?
+Show the mailboxes under this namespace with the LIST command. This
+makes the namespace visible for clients that do not support the NAMESPACE
+extension. The special @code{children} value lists child mailboxes, but
+hides the namespace prefix.
+Defaults to @samp{#t}.
+@end deftypevr
-@item @code{tcp-port} (default: @code{11211})
-Port on which to accept connections on,
+@deftypevr {@code{namespace-configuration} parameter} boolean subscriptions?
+Namespace handles its own subscriptions. If set to @code{#f}, the
+parent namespace handles them. The empty prefix should always have this
+as @code{#t}).
+Defaults to @samp{#t}.
+@end deftypevr
-@item @code{udp-port} (default: @code{11211})
-Port on which to accept UDP connections on, a value of 0 will disable
-listening on a UDP socket.
+@deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes
+List of predefined mailboxes in this namespace.
+Defaults to @samp{()}.
-@item @code{additional-options} (default: @code{'()})
-Additional command line options to pass to @code{memcached}.
-@end table
-@end deftp
+Available @code{mailbox-configuration} fields are:
+
+@deftypevr {@code{mailbox-configuration} parameter} string name
+Name for this mailbox.
+@end deftypevr
-@defvr {Scheme Variable} mongodb-service-type
-This is the service type for @uref{https://www.mongodb.com/, MongoDB}.
-The value for the service type is a @code{mongodb-configuration} object.
-@end defvr
+@deftypevr {@code{mailbox-configuration} parameter} string auto
+@samp{create} will automatically create this mailbox.
+@samp{subscribe} will both create and subscribe to the mailbox.
+Defaults to @samp{"no"}.
+@end deftypevr
-@example
-(service mongodb-service-type)
-@end example
+@deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use
+List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154.
+Valid values are @code{\All}, @code{\Archive}, @code{\Drafts},
+@code{\Flagged}, @code{\Junk}, @code{\Sent}, and @code{\Trash}.
+Defaults to @samp{()}.
+@end deftypevr
-@deftp {Data Type} mongodb-configuration
-Data type representing the configuration of mongodb.
+@end deftypevr
-@table @asis
-@item @code{mongodb} (default: @code{mongodb})
-The MongoDB package to use.
+@end deftypevr
-@item @code{config-file} (default: @code{%default-mongodb-configuration-file})
-The configuration file for MongoDB.
+@deftypevr {@code{dovecot-configuration} parameter} file-name base-dir
+Base directory where to store runtime data.
+Defaults to @samp{"/var/run/dovecot/"}.
+@end deftypevr
-@item @code{data-directory} (default: @code{"/var/lib/mongodb"})
-This value is used to create the directory, so that it exists and is
-owned by the mongodb user. It should match the data-directory which
-MongoDB is configured to use through the configuration file.
-@end table
-@end deftp
+@deftypevr {@code{dovecot-configuration} parameter} string login-greeting
+Greeting message for clients.
+Defaults to @samp{"Dovecot ready."}.
+@end deftypevr
-@defvr {Scheme Variable} redis-service-type
-This is the service type for the @uref{https://redis.io/, Redis}
-key/value store, whose value is a @code{redis-configuration} object.
-@end defvr
+@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks
+List of trusted network ranges. Connections from these IPs are
+allowed to override their IP addresses and ports (for logging and for
+authentication checks). @samp{disable-plaintext-auth} is also ignored
+for these networks. Typically you would specify your IMAP proxy servers
+here.
+Defaults to @samp{()}.
+@end deftypevr
-@deftp {Data Type} redis-configuration
-Data type representing the configuration of redis.
+@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets
+List of login access check sockets (e.g.@: tcpwrap).
+Defaults to @samp{()}.
+@end deftypevr
-@table @asis
-@item @code{redis} (default: @code{redis})
-The Redis package to use.
+@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle?
+Show more verbose process titles (in ps). Currently shows user name
+and IP address. Useful for seeing who is actually using the IMAP
+processes (e.g.@: shared mailboxes or if the same uid is used for multiple
+accounts).
+Defaults to @samp{#f}.
+@end deftypevr
-@item @code{bind} (default: @code{"127.0.0.1"})
-Network interface on which to listen.
+@deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients?
+Should all processes be killed when Dovecot master process shuts down.
+Setting this to @code{#f} means that Dovecot can be upgraded without
+forcing existing client connections to close (although that could also
+be a problem if the upgrade is e.g.@: due to a security fix).
+Defaults to @samp{#t}.
+@end deftypevr
-@item @code{port} (default: @code{6379})
-Port on which to accept connections on, a value of 0 will disable
-listening on a TCP socket.
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count
+If non-zero, run mail commands via this many connections to doveadm
+server, instead of running them directly in the same process.
+Defaults to @samp{0}.
+@end deftypevr
-@item @code{working-directory} (default: @code{"/var/lib/redis"})
-Directory in which to store the database and related files.
-@end table
-@end deftp
+@deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path
+UNIX socket or host:port used for connecting to doveadm server.
+Defaults to @samp{"doveadm-server"}.
+@end deftypevr
-@node Mail Services
-@subsubsection Mail Services
+@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment
+List of environment variables that are preserved on Dovecot startup
+and passed down to all of its child processes. You can also give
+key=value pairs to always set specific settings.
+@end deftypevr
-@cindex mail
-@cindex email
-The @code{(gnu services mail)} module provides Guix service definitions
-for email services: IMAP, POP3, and LMTP servers, as well as mail
-transport agents (MTAs). Lots of acronyms! These services are detailed
-in the subsections below.
+@deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth?
+Disable LOGIN command and all other plaintext authentications unless
+SSL/TLS is used (LOGINDISABLED capability). Note that if the remote IP
+matches the local IP (i.e.@: you're connecting from the same computer),
+the connection is considered secure and plaintext authentication is
+allowed. See also ssl=required setting.
+Defaults to @samp{#t}.
+@end deftypevr
-@subsubheading Dovecot Service
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size
+Authentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled.
+Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set
+for caching to be used.
+Defaults to @samp{0}.
+@end deftypevr
-@deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)]
-Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.
-@end deffn
+@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttl
+Time to live for cached data. After TTL expires the cached record
+is no longer used, *except* if the main database lookup returns internal
+failure. We also try to handle password changes automatically: If
+user's previous authentication was successful, but this one wasn't, the
+cache isn't used. For now this works only with plaintext
+authentication.
+Defaults to @samp{"1 hour"}.
+@end deftypevr
-By default, Dovecot does not need much configuration; the default
-configuration object created by @code{(dovecot-configuration)} will
-suffice if your mail is delivered to @code{~/Maildir}. A self-signed
-certificate will be generated for TLS-protected connections, though
-Dovecot will also listen on cleartext ports by default. There are a
-number of options, though, which mail administrators might need to change,
-and as is the case with other services, Guix allows the system
-administrator to specify these parameters via a uniform Scheme interface.
+@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl
+TTL for negative hits (user not found, password mismatch).
+0 disables caching them completely.
+Defaults to @samp{"1 hour"}.
+@end deftypevr
-For example, to specify that mail is located at @code{maildir~/.mail},
-one would instantiate the Dovecot service like this:
+@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realms
+List of realms for SASL authentication mechanisms that need them.
+You can leave it empty if you don't want to support multiple realms.
+Many clients simply use the first one listed here, so keep the default
+realm first.
+Defaults to @samp{()}.
+@end deftypevr
-@example
-(dovecot-service #:config
- (dovecot-configuration
- (mail-location "maildir:~/.mail")))
-@end example
+@deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm
+Default realm/domain to use if none was specified. This is used for
+both SASL realms and appending @@domain to username in plaintext
+logins.
+Defaults to @samp{""}.
+@end deftypevr
-The available configuration parameters follow. Each parameter
-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. There is also a way to specify the configuration as a string,
-if you have an old @code{dovecot.conf} file that you want to port over
-from some other system; see the end for more details.
+@deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars
+List of allowed characters in username. If the user-given username
+contains a character not listed in here, the login automatically fails.
+This is just an extra check to make sure user can't exploit any
+potential quote escaping vulnerabilities with SQL/LDAP databases. If
+you want to allow all characters, set this value to empty.
+Defaults to @samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}.
+@end deftypevr
-@c The following documentation was initially generated by
-@c (generate-documentation) in (gnu services mail). Manually maintained
-@c documentation is better, so we shouldn't hesitate to edit below as
-@c needed. However if the change you want to make to this documentation
-@c can be done in an automated way, it's probably easier to change
-@c (generate-documentation) than to make it below and have to deal with
-@c the churn as dovecot updates.
+@deftypevr {@code{dovecot-configuration} parameter} string auth-username-translation
+Username character translations before it's looked up from
+databases. The value contains series of from -> to characters. For
+example @samp{#@@/@@} means that @samp{#} and @samp{/} characters are
+translated to @samp{@@}.
+Defaults to @samp{""}.
+@end deftypevr
-Available @code{dovecot-configuration} fields are:
+@deftypevr {@code{dovecot-configuration} parameter} string auth-username-format
+Username formatting before it's looked up from databases. You can
+use the standard variables here, e.g.@: %Lu would lowercase the username,
+%n would drop away the domain if it was given, or @samp{%n-AT-%d} would
+change the @samp{@@} into @samp{-AT-}. This translation is done after
+@samp{auth-username-translation} changes.
+Defaults to @samp{"%Lu"}.
+@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} package dovecot
-The dovecot package.
+@deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator
+If you want to allow master users to log in by specifying the master
+username within the normal username string (i.e.@: not using SASL
+mechanism's support for it), you can specify the separator character
+here. The format is then <username><separator><master username>.
+UW-IMAP uses @samp{*} as the separator, so that could be a good
+choice.
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen
-A list of IPs or hosts where to listen for connections. @samp{*}
-listens on all IPv4 interfaces, @samp{::} listens on all IPv6
-interfaces. If you want to specify non-default ports or anything more
-complex, customize the address and port fields of the
-@samp{inet-listener} of the specific services you are interested in.
+@deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username
+Username to use for users logging in with ANONYMOUS SASL
+mechanism.
+Defaults to @samp{"anonymous"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols
-List of protocols we want to serve. Available protocols include
-@samp{imap}, @samp{pop3}, and @samp{lmtp}.
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count
+Maximum number of dovecot-auth worker processes. They're used to
+execute blocking passdb and userdb queries (e.g.@: MySQL and PAM).
+They're automatically created and destroyed as needed.
+Defaults to @samp{30}.
+@end deftypevr
-Available @code{protocol-configuration} fields are:
+@deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostname
+Host name to use in GSSAPI principal names. The default is to use
+the name returned by gethostname(). Use @samp{$ALL} (with quotes) to
+allow all keytab entries.
+Defaults to @samp{""}.
+@end deftypevr
-@deftypevr {@code{protocol-configuration} parameter} string name
-The name of the protocol.
+@deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab
+Kerberos keytab to use for the GSSAPI mechanism. Will use the
+system default (usually @file{/etc/krb5.keytab}) if not specified. You may
+need to change the auth service to run as root to be able to read this
+file.
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{protocol-configuration} parameter} string auth-socket-path
-UNIX socket path to the master authentication server to find users.
-This is used by imap (for shared users) and lda.
-It defaults to @samp{"/var/run/dovecot/auth-userdb"}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind?
+Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon
+and @samp{ntlm-auth} helper.
+<doc/wiki/Authentication/Mechanisms/Winbind.txt>.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins
-Space separated list of plugins to load.
+@deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path
+Path for Samba's @samp{ntlm-auth} helper binary.
+Defaults to @samp{"/usr/bin/ntlm_auth"}.
@end deftypevr
-@deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections
-Maximum number of IMAP connections allowed for a user from each IP
-address. NOTE: The username is compared case-sensitively.
-Defaults to @samp{10}.
+@deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay
+Time to delay before replying to failed authentications.
+Defaults to @samp{"2 secs"}.
@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert?
+Require a valid SSL client certificate or the authentication
+fails.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services
-List of services to enable. Available services include @samp{imap},
-@samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and
-@samp{lmtp}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert?
+Take the username from client's SSL certificate, using
+@code{X509_NAME_get_text_by_NID()} which returns the subject's DN's
+CommonName.
+Defaults to @samp{#f}.
+@end deftypevr
-Available @code{service-configuration} fields are:
+@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms
+List of wanted authentication mechanisms. Supported mechanisms are:
+@samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5},
+@samp{ntlm}, @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi},
+@samp{otp}, @samp{skey}, and @samp{gss-spnego}. NOTE: See also
+@samp{disable-plaintext-auth} setting.
+@end deftypevr
-@deftypevr {@code{service-configuration} parameter} string kind
-The service kind. Valid values include @code{director},
-@code{imap-login}, @code{pop3-login}, @code{lmtp}, @code{imap},
-@code{pop3}, @code{auth}, @code{auth-worker}, @code{dict},
-@code{tcpwrap}, @code{quota-warning}, or anything else.
+@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers
+List of IPs or hostnames to all director servers, including ourself.
+Ports can be specified as ip:port. The default port is the same as what
+director service's @samp{inet-listener} is using.
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners
-Listeners for the service. A listener is either a
-@code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or
-an @code{inet-listener-configuration}.
+@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers
+List of IPs or hostnames to all backend mail servers. Ranges are
+allowed too, like 10.0.0.10-10.0.0.30.
Defaults to @samp{()}.
+@end deftypevr
-Available @code{unix-listener-configuration} fields are:
+@deftypevr {@code{dovecot-configuration} parameter} string director-user-expire
+How long to redirect users to a specific server after it no longer
+has any connections.
+Defaults to @samp{"15 min"}.
+@end deftypevr
-@deftypevr {@code{unix-listener-configuration} parameter} string path
-Path to the file, relative to @code{base-dir} field. This is also used as
-the section name.
+@deftypevr {@code{dovecot-configuration} parameter} string director-username-hash
+How the username is translated before being hashed. Useful values
+include %Ln if user can log in with or without @@domain, %Ld if mailboxes
+are shared within domain.
+Defaults to @samp{"%Lu"}.
@end deftypevr
-@deftypevr {@code{unix-listener-configuration} parameter} string mode
-The access mode for the socket.
-Defaults to @samp{"0600"}.
+@deftypevr {@code{dovecot-configuration} parameter} string log-path
+Log file to use for error messages. @samp{syslog} logs to syslog,
+@samp{/dev/stderr} logs to stderr.
+Defaults to @samp{"syslog"}.
@end deftypevr
-@deftypevr {@code{unix-listener-configuration} parameter} string user
-The user to own the socket.
+@deftypevr {@code{dovecot-configuration} parameter} string info-log-path
+Log file to use for informational messages. Defaults to
+@samp{log-path}.
Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{unix-listener-configuration} parameter} string group
-The group to own the socket.
+@deftypevr {@code{dovecot-configuration} parameter} string debug-log-path
+Log file to use for debug messages. Defaults to
+@samp{info-log-path}.
Defaults to @samp{""}.
@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} string syslog-facility
+Syslog facility to use if you're logging to syslog. Usually if you
+don't want to use @samp{mail}, you'll use local0..local7. Also other
+standard facilities are supported.
+Defaults to @samp{"mail"}.
+@end deftypevr
-Available @code{fifo-listener-configuration} fields are:
-
-@deftypevr {@code{fifo-listener-configuration} parameter} string path
-Path to the file, relative to @code{base-dir} field. This is also used as
-the section name.
+@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose?
+Log unsuccessful authentication attempts and the reasons why they
+failed.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{fifo-listener-configuration} parameter} string mode
-The access mode for the socket.
-Defaults to @samp{"0600"}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords?
+In case of password mismatches, log the attempted password. Valid
+values are no, plain and sha1. sha1 can be useful for detecting brute
+force password attempts vs. user simply trying the same password over
+and over again. You can also truncate the value to n chars by appending
+":n" (e.g.@: sha1:6).
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{fifo-listener-configuration} parameter} string user
-The user to own the socket.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
+Even more verbose logging for debugging purposes. Shows for example
+SQL queries.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{fifo-listener-configuration} parameter} string group
-The group to own the socket.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords?
+In case of password mismatches, log the passwords and used scheme so
+the problem can be debugged. Enabling this also enables
+@samp{auth-debug}.
+Defaults to @samp{#f}.
@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug?
+Enable mail process debugging. This can help you figure out why
+Dovecot isn't finding your mails.
+Defaults to @samp{#f}.
+@end deftypevr
-Available @code{inet-listener-configuration} fields are:
+@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl?
+Show protocol level SSL errors.
+Defaults to @samp{#f}.
+@end deftypevr
-@deftypevr {@code{inet-listener-configuration} parameter} string protocol
-The protocol to listen for.
+@deftypevr {@code{dovecot-configuration} parameter} string log-timestamp
+Prefix for each line written to log file. % codes are in
+strftime(3) format.
+Defaults to @samp{"\"%b %d %H:%M:%S \""}.
@end deftypevr
-@deftypevr {@code{inet-listener-configuration} parameter} string address
-The address on which to listen, or empty for all addresses.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-elements
+List of elements we want to log. The elements which have a
+non-empty variable value are joined together to form a comma-separated
+string.
@end deftypevr
-@deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port
-The port on which to listen.
+@deftypevr {@code{dovecot-configuration} parameter} string login-log-format
+Login log format. %s contains @samp{login-log-format-elements}
+string, %$ contains the data we want to log.
+Defaults to @samp{"%$: %s"}.
@end deftypevr
-@deftypevr {@code{inet-listener-configuration} parameter} boolean ssl?
-Whether to use SSL for this service; @samp{yes}, @samp{no}, or
-@samp{required}.
-Defaults to @samp{#t}.
+@deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix
+Log prefix for mail processes. See doc/wiki/Variables.txt for list
+of possible variables you can use.
+Defaults to @samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}.
@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format
+Format to use for logging mail deliveries. You can use variables:
+@table @code
+@item %$
+Delivery status message (e.g.@: @samp{saved to INBOX})
+@item %m
+Message-ID
+@item %s
+Subject
+@item %f
+From address
+@item %p
+Physical size
+@item %w
+Virtual size.
+@end table
+Defaults to @samp{"msgid=%m: %$"}.
@end deftypevr
-@deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit
-Maximum number of simultaneous client connections per process. Once
-this number of connections is received, the next incoming connection
-will prompt Dovecot to spawn another process. If set to 0,
-@code{default-client-limit} is used instead.
+@deftypevr {@code{dovecot-configuration} parameter} string mail-location
+Location for users' mailboxes. The default is empty, which means
+that Dovecot tries to find the mailboxes automatically. This won't work
+if the user doesn't yet have any mail, so you should explicitly tell
+Dovecot the full location.
-Defaults to @samp{0}.
+If you're using mbox, giving a path to the INBOX
+file (e.g.@: /var/mail/%u) isn't enough. You'll also need to tell Dovecot
+where the other mailboxes are kept. This is called the "root mail
+directory", and it must be the first path given in the
+@samp{mail-location} setting.
+
+There are a few special variables you can use, eg.:
+
+@table @samp
+@item %u
+username
+@item %n
+user part in user@@domain, same as %u if there's no domain
+@item %d
+domain part in user@@domain, empty if there's no domain
+@item %h
+home director
+@end table
+See doc/wiki/Variables.txt for full list. Some examples:
+@table @samp
+@item maildir:~/Maildir
+@item mbox:~/mail:INBOX=/var/mail/%u
+@item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%
+@end table
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{service-configuration} parameter} non-negative-integer service-count
-Number of connections to handle before starting a new process.
-Typically the only useful values are 0 (unlimited) or 1. 1 is more
-secure, but 0 is faster. <doc/wiki/LoginProcess.txt>.
-Defaults to @samp{1}.
+@deftypevr {@code{dovecot-configuration} parameter} string mail-uid
+System user and group used to access mails. If you use multiple,
+userdb can override these by returning uid or gid fields. You can use
+either numbers or names. <doc/wiki/UserIds.txt>.
+Defaults to @samp{""}.
+@end deftypevr
+
+@deftypevr {@code{dovecot-configuration} parameter} string mail-gid
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit
-Maximum number of processes that can exist for this service. If set to
-0, @code{default-process-limit} is used instead.
+@deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group
+Group to enable temporarily for privileged operations. Currently
+this is used only with INBOX when either its initial creation or
+dotlocking fails. Typically this is set to "mail" to give access to
+/var/mail.
+Defaults to @samp{""}.
+@end deftypevr
-Defaults to @samp{0}.
+@deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups
+Grant access to these supplementary groups for mail processes.
+Typically these are used to set up access to shared mailboxes. Note
+that it may be dangerous to set these if users can create
+symlinks (e.g.@: if "mail" group is set here, ln -s /var/mail ~/mail/var
+could allow a user to delete others' mailboxes, or ln -s
+/secret/shared/box ~/mail/mybox would allow reading it).
+Defaults to @samp{""}.
+@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
+Allow full file system access to clients. There's no access checks
+other than what the operating system does for the active UID/GID. It
+works with both maildir and mboxes, allowing you to prefix mailboxes
+names with e.g.@: /path/ or ~user/.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail
-Number of processes to always keep waiting for more connections.
-Defaults to @samp{0}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
+Don't use mmap() at all. This is required if you store indexes to
+shared file systems (NFS or clustered file system).
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit
-If you set @samp{service-count 0}, you probably need to grow
-this.
-Defaults to @samp{256000000}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl?
+Rely on @samp{O_EXCL} to work when creating dotlock files. NFS
+supports @samp{O_EXCL} since version 3, so this should be safe to use
+nowadays by default.
+Defaults to @samp{#t}.
@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} string mail-fsync
+When to use fsync() or fdatasync() calls:
+@table @code
+@item optimized
+Whenever necessary to avoid losing important data
+@item always
+Useful with e.g.@: NFS when write()s are delayed
+@item never
+Never use it (best performance, but crashes can lose data).
+@end table
+Defaults to @samp{"optimized"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict
-Dict configuration, as created by the @code{dict-configuration}
-constructor.
-
-Available @code{dict-configuration} fields are:
-
-@deftypevr {@code{dict-configuration} parameter} free-form-fields entries
-A list of key-value pairs that this dict should hold.
-Defaults to @samp{()}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage?
+Mail storage exists in NFS. Set this to yes to make Dovecot flush
+NFS caches whenever needed. If you're using only a single mail server
+this isn't needed.
+Defaults to @samp{#f}.
@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index?
+Mail index files also exist in NFS. Setting this to yes requires
+@samp{mmap-disable? #t} and @samp{fsync-disable? #f}.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs
-A list of passdb configurations, each one created by the
-@code{passdb-configuration} constructor.
-
-Available @code{passdb-configuration} fields are:
-
-@deftypevr {@code{passdb-configuration} parameter} string driver
-The driver that the passdb should use. Valid values include
-@samp{pam}, @samp{passwd}, @samp{shadow}, @samp{bsdauth}, and
-@samp{static}.
-Defaults to @samp{"pam"}.
+@deftypevr {@code{dovecot-configuration} parameter} string lock-method
+Locking method for index files. Alternatives are fcntl, flock and
+dotlock. Dotlocking uses some tricks which may create more disk I/O
+than other locking methods. NFS users: flock doesn't work, remember to
+change @samp{mmap-disable}.
+Defaults to @samp{"fcntl"}.
@end deftypevr
-@deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args
-Space separated list of arguments to the passdb driver.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir
+Directory in which LDA/LMTP temporarily stores incoming mails >128
+kB.
+Defaults to @samp{"/tmp"}.
@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid
+Valid UID range for users. This is mostly to make sure that users can't
+log in as daemons or other system users. Note that denying root logins is
+hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid}
+is set to 0.
+Defaults to @samp{500}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs
-List of userdb configurations, each one created by the
-@code{userdb-configuration} constructor.
-
-Available @code{userdb-configuration} fields are:
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid
-@deftypevr {@code{userdb-configuration} parameter} string driver
-The driver that the userdb should use. Valid values include
-@samp{passwd} and @samp{static}.
-Defaults to @samp{"passwd"}.
+Defaults to @samp{0}.
@end deftypevr
-@deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args
-Space separated list of arguments to the userdb driver.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-gid
+Valid GID range for users. Users having non-valid GID as primary group ID
+aren't allowed to log in. If user belongs to supplementary groups with
+non-valid GIDs, those groups are not set.
+Defaults to @samp{1}.
@end deftypevr
-@deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields
-Override fields from passwd.
-Defaults to @samp{()}.
-@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid
+Defaults to @samp{0}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration
-Plug-in configuration, created by the @code{plugin-configuration}
-constructor.
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length
+Maximum allowed length for mail keyword name. It's only forced when
+trying to create new keywords.
+Defaults to @samp{50}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces
-List of namespaces. Each item in the list is created by the
-@code{namespace-configuration} constructor.
-
-Available @code{namespace-configuration} fields are:
+@deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs
+List of directories under which chrooting is allowed for mail
+processes (i.e.@: /var/mail will allow chrooting to /var/mail/foo/bar
+too). This setting doesn't affect @samp{login-chroot}
+@samp{mail-chroot} or auth chroot settings. If this setting is empty,
+"/./" in home dirs are ignored. WARNING: Never add directories here
+which local users can modify, that may lead to root exploit. Usually
+this should be done only if you don't allow shell access for users.
+<doc/wiki/Chrooting.txt>.
+Defaults to @samp{()}.
+@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} string name
-Name for this namespace.
+@deftypevr {@code{dovecot-configuration} parameter} string mail-chroot
+Default chroot directory for mail processes. This can be overridden
+for specific users in user database by giving /./ in user's home
+directory (e.g.@: /home/./user chroots into /home). Note that usually
+there is no real need to do chrooting, Dovecot doesn't allow users to
+access files outside their mail directory anyway. If your home
+directories are prefixed with the chroot directory, append "/."@: to
+@samp{mail-chroot}. <doc/wiki/Chrooting.txt>.
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} string type
-Namespace type: @samp{private}, @samp{shared} or @samp{public}.
-Defaults to @samp{"private"}.
+@deftypevr {@code{dovecot-configuration} parameter} file-name auth-socket-path
+UNIX socket path to master authentication server to find users.
+This is used by imap (for shared users) and lda.
+Defaults to @samp{"/var/run/dovecot/auth-userdb"}.
@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} string separator
-Hierarchy separator to use. You should use the same separator for
-all namespaces or some clients get confused. @samp{/} is usually a good
-one. The default however depends on the underlying mail storage
-format.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir
+Directory where to look up mail plugins.
+Defaults to @samp{"/usr/lib/dovecot"}.
@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} string prefix
-Prefix required to access this namespace. This needs to be
-different for all namespaces. For example @samp{Public/}.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins
+List of plugins to load for all services. Plugins specific to IMAP,
+LDA, etc.@: are added to this list in their own .conf files.
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} string location
-Physical location of the mailbox. This is in the same format as
-mail_location, which is also the default for it.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count
+The minimum number of mails in a mailbox before updates are done to
+cache file. This allows optimizing Dovecot's behavior to do less disk
+writes at the cost of more disk reads.
+Defaults to @samp{0}.
@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} boolean inbox?
-There can be only one INBOX, and this setting defines which
-namespace has it.
-Defaults to @samp{#f}.
+@deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-interval
+When IDLE command is running, mailbox is checked once in a while to
+see if there are any new mails or other changes. This setting defines
+the minimum time to wait between those checks. Dovecot can also use
+dnotify, inotify and kqueue to find out immediately when changes
+occur.
+Defaults to @samp{"30 secs"}.
@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} boolean hidden?
-If namespace is hidden, it's not advertised to clients via NAMESPACE
-extension. You'll most likely also want to set @samp{list? #f}. This is mostly
-useful when converting from another server with different namespaces
-which you want to deprecate but still keep working. For example you can
-create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/}
-and @samp{mail/}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf?
+Save mails with CR+LF instead of plain LF. This makes sending those
+mails take less CPU, especially with sendfile() syscall with Linux and
+FreeBSD. But it also creates a bit more disk I/O which may just make it
+slower. Also note that if other software reads the mboxes/maildirs,
+they may handle the extra CRs wrong and cause problems.
Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} boolean list?
-Show the mailboxes under this namespace with the LIST command. This
-makes the namespace visible for clients that do not support the NAMESPACE
-extension. The special @code{children} value lists child mailboxes, but
-hides the namespace prefix.
-Defaults to @samp{#t}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-stat-dirs?
+By default LIST command returns all entries in maildir beginning
+with a dot. Enabling this option makes Dovecot return only entries
+which are directories. This is done by stat()ing each entry, so it
+causes more disk I/O.
+ (For systems setting struct @samp{dirent->d_type} this check is free
+and it's done always regardless of this setting).
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} boolean subscriptions?
-Namespace handles its own subscriptions. If set to @code{#f}, the
-parent namespace handles them. The empty prefix should always have this
-as @code{#t}).
+@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks?
+When copying a message, do it with hard links whenever possible.
+This makes the performance much better, and it's unlikely to have any
+side effects.
Defaults to @samp{#t}.
@end deftypevr
-@deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes
-List of predefined mailboxes in this namespace.
-Defaults to @samp{()}.
-
-Available @code{mailbox-configuration} fields are:
-
-@deftypevr {@code{mailbox-configuration} parameter} string name
-Name for this mailbox.
+@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs?
+Assume Dovecot is the only MUA accessing Maildir: Scan cur/
+directory only when its mtime changes unexpectedly or when we can't find
+the mail otherwise.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{mailbox-configuration} parameter} string auto
-@samp{create} will automatically create this mailbox.
-@samp{subscribe} will both create and subscribe to the mailbox.
-Defaults to @samp{"no"}.
-@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks
+Which locking methods to use for locking mbox. There are four
+available:
-@deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use
-List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154.
-Valid values are @code{\All}, @code{\Archive}, @code{\Drafts},
-@code{\Flagged}, @code{\Junk}, @code{\Sent}, and @code{\Trash}.
-Defaults to @samp{()}.
-@end deftypevr
+@table @code
+@item dotlock
+Create <mailbox>.lock file. This is the oldest and most NFS-safe
+solution. If you want to use /var/mail/ like directory, the users will
+need write access to that directory.
+@item dotlock-try
+Same as dotlock, but if it fails because of permissions or because there
+isn't enough disk space, just skip it.
+@item fcntl
+Use this if possible. Works with NFS too if lockd is used.
+@item flock
+May not exist in all systems. Doesn't work with NFS.
+@item lockf
+May not exist in all systems. Doesn't work with NFS.
+@end table
+You can use multiple locking methods; if you do the order they're declared
+in is important to avoid deadlocks if other MTAs/MUAs are using multiple
+locking methods as well. Some operating systems don't allow using some of
+them simultaneously.
@end deftypevr
-@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks
-@deftypevr {@code{dovecot-configuration} parameter} file-name base-dir
-Base directory where to store runtime data.
-Defaults to @samp{"/var/run/dovecot/"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string login-greeting
-Greeting message for clients.
-Defaults to @samp{"Dovecot ready."}.
+@deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout
+Maximum time to wait for lock (all of them) before aborting.
+Defaults to @samp{"5 mins"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks
-List of trusted network ranges. Connections from these IPs are
-allowed to override their IP addresses and ports (for logging and for
-authentication checks). @samp{disable-plaintext-auth} is also ignored
-for these networks. Typically you would specify your IMAP proxy servers
-here.
-Defaults to @samp{()}.
+@deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout
+If dotlock exists but the mailbox isn't modified in any way,
+override the lock file after this much time.
+Defaults to @samp{"2 mins"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets
-List of login access check sockets (e.g.@: tcpwrap).
-Defaults to @samp{()}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs?
+When mbox changes unexpectedly we have to fully read it to find out
+what changed. If the mbox is large this can take a long time. Since
+the change is usually just a newly appended mail, it'd be faster to
+simply read the new mails. If this setting is enabled, Dovecot does
+this but still safely fallbacks to re-reading the whole mbox file
+whenever something in mbox isn't how it's expected to be. The only real
+downside to this setting is that if some other MUA changes message
+flags, Dovecot doesn't notice it immediately. Note that a full sync is
+done with SELECT, EXAMINE, EXPUNGE and CHECK commands.
+Defaults to @samp{#t}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle?
-Show more verbose process titles (in ps). Currently shows user name
-and IP address. Useful for seeing who is actually using the IMAP
-processes (e.g.@: shared mailboxes or if the same uid is used for multiple
-accounts).
+@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs?
+Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
+EXAMINE, EXPUNGE or CHECK commands. If this is set,
+@samp{mbox-dirty-syncs} is ignored.
Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients?
-Should all processes be killed when Dovecot master process shuts down.
-Setting this to @code{#f} means that Dovecot can be upgraded without
-forcing existing client connections to close (although that could also
-be a problem if the upgrade is e.g.@: due to a security fix).
+@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes?
+Delay writing mbox headers until doing a full write sync (EXPUNGE
+and CHECK commands and when closing the mailbox). This is especially
+useful for POP3 where clients often delete all mails. The downside is
+that our changes aren't immediately visible to other MUAs.
Defaults to @samp{#t}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count
-If non-zero, run mail commands via this many connections to doveadm
-server, instead of running them directly in the same process.
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size
+If mbox size is smaller than this (e.g.@: 100k), don't write index
+files. If an index file already exists it's still read, just not
+updated.
Defaults to @samp{0}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path
-UNIX socket or host:port used for connecting to doveadm server.
-Defaults to @samp{"doveadm-server"}.
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size
+Maximum dbox file size until it's rotated.
+Defaults to @samp{10000000}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment
-List of environment variables that are preserved on Dovecot startup
-and passed down to all of its child processes. You can also give
-key=value pairs to always set specific settings.
+@deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval
+Maximum dbox file age until it's rotated. Typically in days. Day
+begins from midnight, so 1d = today, 2d = yesterday, etc. 0 = check
+disabled.
+Defaults to @samp{"1d"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth?
-Disable LOGIN command and all other plaintext authentications unless
-SSL/TLS is used (LOGINDISABLED capability). Note that if the remote IP
-matches the local IP (i.e.@: you're connecting from the same computer),
-the connection is considered secure and plaintext authentication is
-allowed. See also ssl=required setting.
-Defaults to @samp{#t}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space?
+When creating new mdbox files, immediately preallocate their size to
+@samp{mdbox-rotate-size}. This setting currently works only in Linux
+with some file systems (ext4, xfs).
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size
-Authentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled.
-Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set
-for caching to be used.
-Defaults to @samp{0}.
-@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir
+sdbox and mdbox support saving mail attachments to external files,
+which also allows single instance storage for them. Other backends
+don't support this for now.
-@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttl
-Time to live for cached data. After TTL expires the cached record
-is no longer used, *except* if the main database lookup returns internal
-failure. We also try to handle password changes automatically: If
-user's previous authentication was successful, but this one wasn't, the
-cache isn't used. For now this works only with plaintext
-authentication.
-Defaults to @samp{"1 hour"}.
+WARNING: This feature hasn't been tested much yet. Use at your own risk.
+
+Directory root where to store mail attachments. Disabled, if empty.
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl
-TTL for negative hits (user not found, password mismatch).
-0 disables caching them completely.
-Defaults to @samp{"1 hour"}.
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size
+Attachments smaller than this aren't saved externally. It's also
+possible to write a plugin to disable saving specific attachments
+externally.
+Defaults to @samp{128000}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realms
-List of realms for SASL authentication mechanisms that need them.
-You can leave it empty if you don't want to support multiple realms.
-Many clients simply use the first one listed here, so keep the default
-realm first.
-Defaults to @samp{()}.
+@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs
+File system backend to use for saving attachments:
+@table @code
+@item posix
+No SiS done by Dovecot (but this might help FS's own deduplication)
+@item sis posix
+SiS with immediate byte-by-byte comparison during saving
+@item sis-queue posix
+SiS with delayed comparison and deduplication.
+@end table
+Defaults to @samp{"sis posix"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm
-Default realm/domain to use if none was specified. This is used for
-both SASL realms and appending @@domain to username in plaintext
-logins.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash
+Hash format to use in attachment filenames. You can add any text and
+variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}},
+@code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be
+truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits.
+Defaults to @samp{"%@{sha1@}"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars
-List of allowed characters in username. If the user-given username
-contains a character not listed in here, the login automatically fails.
-This is just an extra check to make sure user can't exploit any
-potential quote escaping vulnerabilities with SQL/LDAP databases. If
-you want to allow all characters, set this value to empty.
-Defaults to @samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}.
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit
+
+Defaults to @samp{100}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string auth-username-translation
-Username character translations before it's looked up from
-databases. The value contains series of from -> to characters. For
-example @samp{#@@/@@} means that @samp{#} and @samp{/} characters are
-translated to @samp{@@}.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit
+
+Defaults to @samp{1000}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string auth-username-format
-Username formatting before it's looked up from databases. You can
-use the standard variables here, e.g.@: %Lu would lowercase the username,
-%n would drop away the domain if it was given, or @samp{%n-AT-%d} would
-change the @samp{@@} into @samp{-AT-}. This translation is done after
-@samp{auth-username-translation} changes.
-Defaults to @samp{"%Lu"}.
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit
+Default VSZ (virtual memory size) limit for service processes.
+This is mainly intended to catch and kill processes that leak memory
+before they eat up everything.
+Defaults to @samp{256000000}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator
-If you want to allow master users to log in by specifying the master
-username within the normal username string (i.e.@: not using SASL
-mechanism's support for it), you can specify the separator character
-here. The format is then <username><separator><master username>.
-UW-IMAP uses @samp{*} as the separator, so that could be a good
-choice.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} string default-login-user
+Login user is internally used by login processes. This is the most
+untrusted user in Dovecot system. It shouldn't have access to anything
+at all.
+Defaults to @samp{"dovenull"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username
-Username to use for users logging in with ANONYMOUS SASL
-mechanism.
-Defaults to @samp{"anonymous"}.
+@deftypevr {@code{dovecot-configuration} parameter} string default-internal-user
+Internal user is used by unprivileged processes. It should be
+separate from login user, so that login processes can't disturb other
+processes.
+Defaults to @samp{"dovecot"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count
-Maximum number of dovecot-auth worker processes. They're used to
-execute blocking passdb and userdb queries (e.g.@: MySQL and PAM).
-They're automatically created and destroyed as needed.
-Defaults to @samp{30}.
+@deftypevr {@code{dovecot-configuration} parameter} string ssl?
+SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>.
+Defaults to @samp{"required"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostname
-Host name to use in GSSAPI principal names. The default is to use
-the name returned by gethostname(). Use @samp{$ALL} (with quotes) to
-allow all keytab entries.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert
+PEM encoded X.509 SSL/TLS certificate (public key).
+Defaults to @samp{"</etc/dovecot/default.pem"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab
-Kerberos keytab to use for the GSSAPI mechanism. Will use the
-system default (usually @file{/etc/krb5.keytab}) if not specified. You may
-need to change the auth service to run as root to be able to read this
-file.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} string ssl-key
+PEM encoded SSL/TLS private key. The key is opened before
+dropping root privileges, so keep the key file unreadable by anyone but
+root.
+Defaults to @samp{"</etc/dovecot/private/default.pem"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind?
-Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon
-and @samp{ntlm-auth} helper.
-<doc/wiki/Authentication/Mechanisms/Winbind.txt>.
-Defaults to @samp{#f}.
+@deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password
+If key file is password protected, give the password here.
+Alternatively give it when starting dovecot with -p parameter. Since
+this file is often world-readable, you may want to place this setting
+instead to a different.
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path
-Path for Samba's @samp{ntlm-auth} helper binary.
-Defaults to @samp{"/usr/bin/ntlm_auth"}.
+@deftypevr {@code{dovecot-configuration} parameter} string ssl-ca
+PEM encoded trusted certificate authority. Set this only if you
+intend to use @samp{ssl-verify-client-cert? #t}. The file should
+contain the CA certificate(s) followed by the matching
+CRL(s). (e.g.@: @samp{ssl-ca </etc/ssl/certs/ca.pem}).
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay
-Time to delay before replying to failed authentications.
-Defaults to @samp{"2 secs"}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl?
+Require that CRL check succeeds for client certificates.
+Defaults to @samp{#t}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert?
-Require a valid SSL client certificate or the authentication
-fails.
+@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert?
+Request client to send a certificate. If you also want to require
+it, set @samp{auth-ssl-require-client-cert? #t} in auth section.
Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert?
-Take the username from client's SSL certificate, using
-@code{X509_NAME_get_text_by_NID()} which returns the subject's DN's
-CommonName.
-Defaults to @samp{#f}.
+@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field
+Which field from certificate to use for username. commonName and
+x500UniqueIdentifier are the usual choices. You'll also need to set
+@samp{auth-ssl-username-from-cert? #t}.
+Defaults to @samp{"commonName"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms
-List of wanted authentication mechanisms. Supported mechanisms are:
-@samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5},
-@samp{ntlm}, @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi},
-@samp{otp}, @samp{skey}, and @samp{gss-spnego}. NOTE: See also
-@samp{disable-plaintext-auth} setting.
+@deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol
+Minimum SSL protocol version to accept.
+Defaults to @samp{"TLSv1"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers
-List of IPs or hostnames to all director servers, including ourself.
-Ports can be specified as ip:port. The default port is the same as what
-director service's @samp{inet-listener} is using.
-Defaults to @samp{()}.
+@deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list
+SSL ciphers to use.
+Defaults to @samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers
-List of IPs or hostnames to all backend mail servers. Ranges are
-allowed too, like 10.0.0.10-10.0.0.30.
-Defaults to @samp{()}.
+@deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device
+SSL crypto device to use, for valid values run "openssl engine".
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string director-user-expire
-How long to redirect users to a specific server after it no longer
-has any connections.
-Defaults to @samp{"15 min"}.
+@deftypevr {@code{dovecot-configuration} parameter} string postmaster-address
+Address to use when sending rejection mails.
+%d expands to recipient domain.
+Defaults to @samp{"postmaster@@%d"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string director-username-hash
-How the username is translated before being hashed. Useful values
-include %Ln if user can log in with or without @@domain, %Ld if mailboxes
-are shared within domain.
-Defaults to @samp{"%Lu"}.
+@deftypevr {@code{dovecot-configuration} parameter} string hostname
+Hostname to use in various parts of sent mails (e.g.@: in Message-Id)
+and in LMTP replies. Default is the system's real hostname@@domain.
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string log-path
-Log file to use for error messages. @samp{syslog} logs to syslog,
-@samp{/dev/stderr} logs to stderr.
-Defaults to @samp{"syslog"}.
+@deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail?
+If user is over quota, return with temporary failure instead of
+bouncing the mail.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string info-log-path
-Log file to use for informational messages. Defaults to
-@samp{log-path}.
-Defaults to @samp{""}.
+@deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path
+Binary to use for sending mails.
+Defaults to @samp{"/usr/sbin/sendmail"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string debug-log-path
-Log file to use for debug messages. Defaults to
-@samp{info-log-path}.
+@deftypevr {@code{dovecot-configuration} parameter} string submission-host
+If non-empty, send mails via this SMTP host[:port] instead of
+sendmail.
Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string syslog-facility
-Syslog facility to use if you're logging to syslog. Usually if you
-don't want to use @samp{mail}, you'll use local0..local7. Also other
-standard facilities are supported.
-Defaults to @samp{"mail"}.
+@deftypevr {@code{dovecot-configuration} parameter} string rejection-subject
+Subject: header to use for rejection mails. You can use the same
+variables as for @samp{rejection-reason} below.
+Defaults to @samp{"Rejected: %s"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose?
-Log unsuccessful authentication attempts and the reasons why they
-failed.
-Defaults to @samp{#f}.
-@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} string rejection-reason
+Human readable error message for rejection mails. You can use
+variables:
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords?
-In case of password mismatches, log the attempted password. Valid
-values are no, plain and sha1. sha1 can be useful for detecting brute
-force password attempts vs. user simply trying the same password over
-and over again. You can also truncate the value to n chars by appending
-":n" (e.g.@: sha1:6).
-Defaults to @samp{#f}.
+@table @code
+@item %n
+CRLF
+@item %r
+reason
+@item %s
+original subject
+@item %t
+recipient
+@end table
+Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
-Even more verbose logging for debugging purposes. Shows for example
-SQL queries.
-Defaults to @samp{#f}.
+@deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter
+Delimiter character between local-part and detail in email
+address.
+Defaults to @samp{"+"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords?
-In case of password mismatches, log the passwords and used scheme so
-the problem can be debugged. Enabling this also enables
-@samp{auth-debug}.
-Defaults to @samp{#f}.
+@deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-header
+Header where the original recipient address (SMTP's RCPT TO:
+address) is taken from if not available elsewhere. With dovecot-lda -a
+parameter overrides this. A commonly used header for this is
+X-Original-To.
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug?
-Enable mail process debugging. This can help you figure out why
-Dovecot isn't finding your mails.
+@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate?
+Should saving a mail to a nonexistent mailbox automatically create
+it?.
Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl?
-Show protocol level SSL errors.
+@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe?
+Should automatically created mailboxes be also automatically
+subscribed?.
Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string log-timestamp
-Prefix for each line written to log file. % codes are in
-strftime(3) format.
-Defaults to @samp{"\"%b %d %H:%M:%S \""}.
+@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length
+Maximum IMAP command line length. Some clients generate very long
+command lines with huge mailboxes, so you may need to raise this if you
+get "Too long argument" or "IMAP command line too large" errors
+often.
+Defaults to @samp{64000}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-elements
-List of elements we want to log. The elements which have a
-non-empty variable value are joined together to form a comma-separated
-string.
+@deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format
+IMAP logout format string:
+@table @code
+@item %i
+total number of bytes read from client
+@item %o
+total number of bytes sent to client.
+@end table
+See @file{doc/wiki/Variables.txt} for a list of all the variables you can use.
+Defaults to @samp{"in=%i out=%o deleted=%@{deleted@} expunged=%@{expunged@} trashed=%@{trashed@} hdr_count=%@{fetch_hdr_count@} hdr_bytes=%@{fetch_hdr_bytes@} body_count=%@{fetch_body_count@} body_bytes=%@{fetch_body_bytes@}"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string login-log-format
-Login log format. %s contains @samp{login-log-format-elements}
-string, %$ contains the data we want to log.
-Defaults to @samp{"%$: %s"}.
+@deftypevr {@code{dovecot-configuration} parameter} string imap-capability
+Override the IMAP CAPABILITY response. If the value begins with '+',
+add the given capabilities on top of the defaults (e.g.@: +XFOO XBAR).
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix
-Log prefix for mail processes. See doc/wiki/Variables.txt for list
-of possible variables you can use.
-Defaults to @samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}.
+@deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval
+How long to wait between "OK Still here" notifications when client
+is IDLEing.
+Defaults to @samp{"2 mins"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format
-Format to use for logging mail deliveries. You can use variables:
-@table @code
-@item %$
-Delivery status message (e.g.@: @samp{saved to INBOX})
-@item %m
-Message-ID
-@item %s
-Subject
-@item %f
-From address
-@item %p
-Physical size
-@item %w
-Virtual size.
-@end table
-Defaults to @samp{"msgid=%m: %$"}.
+@deftypevr {@code{dovecot-configuration} parameter} string imap-id-send
+ID field names and values to send to clients. Using * as the value
+makes Dovecot use the default value. The following fields have default
+values currently: name, version, os, os-version, support-url,
+support-email.
+Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-location
-Location for users' mailboxes. The default is empty, which means
-that Dovecot tries to find the mailboxes automatically. This won't work
-if the user doesn't yet have any mail, so you should explicitly tell
-Dovecot the full location.
+@deftypevr {@code{dovecot-configuration} parameter} string imap-id-log
+ID fields sent by client to log. * means everything.
+Defaults to @samp{""}.
+@end deftypevr
-If you're using mbox, giving a path to the INBOX
-file (e.g.@: /var/mail/%u) isn't enough. You'll also need to tell Dovecot
-where the other mailboxes are kept. This is called the "root mail
-directory", and it must be the first path given in the
-@samp{mail-location} setting.
+@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds
+Workarounds for various client bugs:
-There are a few special variables you can use, eg.:
+@table @code
+@item delay-newmail
+Send EXISTS/RECENT new mail notifications only when replying to NOOP and
+CHECK commands. Some clients ignore them otherwise, for example OSX
+Mail (<v2.1). Outlook Express breaks more badly though, without this it
+may show user "Message no longer in server" errors. Note that OE6
+still breaks even with this workaround if synchronization is set to
+"Headers Only".
-@table @samp
-@item %u
-username
-@item %n
-user part in user@@domain, same as %u if there's no domain
-@item %d
-domain part in user@@domain, empty if there's no domain
-@item %h
-home director
-@end table
+@item tb-extra-mailbox-sep
+Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and
+adds extra @samp{/} suffixes to mailbox names. This option causes Dovecot to
+ignore the extra @samp{/} instead of treating it as invalid mailbox name.
-See doc/wiki/Variables.txt for full list. Some examples:
-@table @samp
-@item maildir:~/Maildir
-@item mbox:~/mail:INBOX=/var/mail/%u
-@item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%
+@item tb-lsub-flags
+Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox).
+This makes Thunderbird realize they aren't selectable and show them
+greyed out, instead of only later giving "not selectable" popup error.
@end table
-Defaults to @samp{""}.
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-uid
-System user and group used to access mails. If you use multiple,
-userdb can override these by returning uid or gid fields. You can use
-either numbers or names. <doc/wiki/UserIds.txt>.
+@deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host
+Host allowed in URLAUTH URLs sent by client. "*" allows all.
Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-gid
-Defaults to @samp{""}.
-@end deftypevr
+Whew! Lots of configuration options. The nice thing about it though is
+that Guix has a complete interface to Dovecot's configuration
+language. This allows not only a nice way to declare configurations,
+but also offers reflective capabilities as well: users can write code to
+inspect and transform configurations from within Scheme.
-@deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group
-Group to enable temporarily for privileged operations. Currently
-this is used only with INBOX when either its initial creation or
-dotlocking fails. Typically this is set to "mail" to give access to
-/var/mail.
-Defaults to @samp{""}.
-@end deftypevr
+However, it could be that you just want to get a @code{dovecot.conf} up
+and running. In that case, you can pass an
+@code{opaque-dovecot-configuration} as the @code{#:config} parameter to
+@code{dovecot-service}. As its name indicates, an opaque configuration
+does not have easy reflective capabilities.
-@deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups
-Grant access to these supplementary groups for mail processes.
-Typically these are used to set up access to shared mailboxes. Note
-that it may be dangerous to set these if users can create
-symlinks (e.g.@: if "mail" group is set here, ln -s /var/mail ~/mail/var
-could allow a user to delete others' mailboxes, or ln -s
-/secret/shared/box ~/mail/mybox would allow reading it).
-Defaults to @samp{""}.
-@end deftypevr
+Available @code{opaque-dovecot-configuration} fields are:
-@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
-Allow full file system access to clients. There's no access checks
-other than what the operating system does for the active UID/GID. It
-works with both maildir and mboxes, allowing you to prefix mailboxes
-names with e.g.@: /path/ or ~user/.
-Defaults to @samp{#f}.
+@deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot
+The dovecot package.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
-Don't use mmap() at all. This is required if you store indexes to
-shared file systems (NFS or clustered file system).
-Defaults to @samp{#f}.
+@deftypevr {@code{opaque-dovecot-configuration} parameter} string string
+The contents of the @code{dovecot.conf}, as a string.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl?
-Rely on @samp{O_EXCL} to work when creating dotlock files. NFS
-supports @samp{O_EXCL} since version 3, so this should be safe to use
-nowadays by default.
-Defaults to @samp{#t}.
-@end deftypevr
+For example, if your @code{dovecot.conf} is just the empty string, you
+could instantiate a dovecot service like this:
+
+@example
+(dovecot-service #:config
+ (opaque-dovecot-configuration
+ (string "")))
+@end example
+
+@subsubheading OpenSMTPD Service
+
+@deffn {Scheme Variable} opensmtpd-service-type
+This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD}
+service, whose value should be an @code{opensmtpd-configuration} object
+as in this example:
+
+@example
+(service opensmtpd-service-type
+ (opensmtpd-configuration
+ (config-file (local-file "./my-smtpd.conf"))))
+@end example
+@end deffn
+
+@deftp {Data Type} opensmtpd-configuration
+Data type representing the configuration of opensmtpd.
+
+@table @asis
+@item @code{package} (default: @var{opensmtpd})
+Package object of the OpenSMTPD SMTP server.
+
+@item @code{config-file} (default: @var{%default-opensmtpd-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.
-@deftypevr {@code{dovecot-configuration} parameter} string mail-fsync
-When to use fsync() or fdatasync() calls:
-@table @code
-@item optimized
-Whenever necessary to avoid losing important data
-@item always
-Useful with e.g.@: NFS when write()s are delayed
-@item never
-Never use it (best performance, but crashes can lose data).
@end table
-Defaults to @samp{"optimized"}.
-@end deftypevr
+@end deftp
-@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage?
-Mail storage exists in NFS. Set this to yes to make Dovecot flush
-NFS caches whenever needed. If you're using only a single mail server
-this isn't needed.
-Defaults to @samp{#f}.
-@end deftypevr
+@subsubheading Exim Service
-@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index?
-Mail index files also exist in NFS. Setting this to yes requires
-@samp{mmap-disable? #t} and @samp{fsync-disable? #f}.
-Defaults to @samp{#f}.
-@end deftypevr
+@cindex mail transfer agent (MTA)
+@cindex MTA (mail transfer agent)
+@cindex SMTP
-@deftypevr {@code{dovecot-configuration} parameter} string lock-method
-Locking method for index files. Alternatives are fcntl, flock and
-dotlock. Dotlocking uses some tricks which may create more disk I/O
-than other locking methods. NFS users: flock doesn't work, remember to
-change @samp{mmap-disable}.
-Defaults to @samp{"fcntl"}.
-@end deftypevr
+@deffn {Scheme Variable} exim-service-type
+This is the type of the @uref{https://exim.org, Exim} mail transfer
+agent (MTA), whose value should be an @code{exim-configuration} object
+as in this example:
-@deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir
-Directory in which LDA/LMTP temporarily stores incoming mails >128
-kB.
-Defaults to @samp{"/tmp"}.
-@end deftypevr
+@example
+(service exim-service-type
+ (exim-configuration
+ (config-file (local-file "./my-exim.conf"))))
+@end example
+@end deffn
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid
-Valid UID range for users. This is mostly to make sure that users can't
-log in as daemons or other system users. Note that denying root logins is
-hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid}
-is set to 0.
-Defaults to @samp{500}.
-@end deftypevr
+In order to use an @code{exim-service-type} service you must also have a
+@code{mail-aliases-service-type} service present in your
+@code{operating-system} (even if it has no aliases).
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid
+@deftp {Data Type} exim-configuration
+Data type representing the configuration of exim.
-Defaults to @samp{0}.
-@end deftypevr
+@table @asis
+@item @code{package} (default: @var{exim})
+Package object of the Exim server.
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-gid
-Valid GID range for users. Users having non-valid GID as primary group ID
-aren't allowed to log in. If user belongs to supplementary groups with
-non-valid GIDs, those groups are not set.
-Defaults to @samp{1}.
-@end deftypevr
+@item @code{config-file} (default: @code{#f})
+File-like object of the Exim configuration file to use. If its value is
+@code{#f} then use the default configuration file from the package
+provided in @code{package}. The resulting configuration file is loaded
+after setting the @code{exim_user} and @code{exim_group} configuration
+variables.
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid
+@end table
+@end deftp
-Defaults to @samp{0}.
-@end deftypevr
+@subsubheading Mail Aliases Service
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length
-Maximum allowed length for mail keyword name. It's only forced when
-trying to create new keywords.
-Defaults to @samp{50}.
-@end deftypevr
+@cindex email aliases
+@cindex aliases, for email addresses
-@deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs
-List of directories under which chrooting is allowed for mail
-processes (i.e.@: /var/mail will allow chrooting to /var/mail/foo/bar
-too). This setting doesn't affect @samp{login-chroot}
-@samp{mail-chroot} or auth chroot settings. If this setting is empty,
-"/./" in home dirs are ignored. WARNING: Never add directories here
-which local users can modify, that may lead to root exploit. Usually
-this should be done only if you don't allow shell access for users.
-<doc/wiki/Chrooting.txt>.
-Defaults to @samp{()}.
-@end deftypevr
+@deffn {Scheme Variable} mail-aliases-service-type
+This is the type of the service which provides @code{/etc/aliases},
+specifying how to deliver mail to users on this system.
-@deftypevr {@code{dovecot-configuration} parameter} string mail-chroot
-Default chroot directory for mail processes. This can be overridden
-for specific users in user database by giving /./ in user's home
-directory (e.g.@: /home/./user chroots into /home). Note that usually
-there is no real need to do chrooting, Dovecot doesn't allow users to
-access files outside their mail directory anyway. If your home
-directories are prefixed with the chroot directory, append "/."@: to
-@samp{mail-chroot}. <doc/wiki/Chrooting.txt>.
-Defaults to @samp{""}.
-@end deftypevr
+@example
+(service mail-aliases-service-type
+ '(("postmaster" "bob")
+ ("bob" "bob@@example.com" "bob@@example2.com")))
+@end example
+@end deffn
+
+The configuration for a @code{mail-aliases-service-type} service is an
+association list denoting how to deliver mail that comes to this
+system. Each entry is of the form @code{(alias addresses ...)}, with
+@code{alias} specifying the local alias and @code{addresses} specifying
+where to deliver this user's mail.
+
+The aliases aren't required to exist as users on the local system. In
+the above example, there doesn't need to be a @code{postmaster} entry in
+the @code{operating-system}'s @code{user-accounts} in order to deliver
+the @code{postmaster} mail to @code{bob} (which subsequently would
+deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}).
+
+@node Messaging Services
+@subsection Messaging Services
+
+@cindex messaging
+@cindex jabber
+@cindex XMPP
+The @code{(gnu services messaging)} module provides Guix service
+definitions for messaging services: currently only Prosody is supported.
+
+@subsubheading Prosody Service
+
+@deffn {Scheme Variable} prosody-service-type
+This is the type for the @uref{https://prosody.im, Prosody XMPP
+communication server}. Its value must be a @code{prosody-configuration}
+record as in this example:
+
+@example
+(service prosody-service-type
+ (prosody-configuration
+ (modules-enabled (cons "groups" "mam" %default-modules-enabled))
+ (int-components
+ (list
+ (int-component-configuration
+ (hostname "conference.example.net")
+ (plugin "muc")
+ (mod-muc (mod-muc-configuration)))))
+ (virtualhosts
+ (list
+ (virtualhost-configuration
+ (domain "example.net"))))))
+@end example
-@deftypevr {@code{dovecot-configuration} parameter} file-name auth-socket-path
-UNIX socket path to master authentication server to find users.
-This is used by imap (for shared users) and lda.
-Defaults to @samp{"/var/run/dovecot/auth-userdb"}.
-@end deftypevr
+See below for details about @code{prosody-configuration}.
-@deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir
-Directory where to look up mail plugins.
-Defaults to @samp{"/usr/lib/dovecot"}.
-@end deftypevr
+@end deffn
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins
-List of plugins to load for all services. Plugins specific to IMAP,
-LDA, etc.@: are added to this list in their own .conf files.
-Defaults to @samp{()}.
-@end deftypevr
+By default, Prosody does not need much configuration. Only one
+@code{virtualhosts} field is needed: it specifies the domain you wish
+Prosody to serve.
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count
-The minimum number of mails in a mailbox before updates are done to
-cache file. This allows optimizing Dovecot's behavior to do less disk
-writes at the cost of more disk reads.
-Defaults to @samp{0}.
-@end deftypevr
+You can perform various sanity checks on the generated configuration
+with the @code{prosodyctl check} command.
-@deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-interval
-When IDLE command is running, mailbox is checked once in a while to
-see if there are any new mails or other changes. This setting defines
-the minimum time to wait between those checks. Dovecot can also use
-dnotify, inotify and kqueue to find out immediately when changes
-occur.
-Defaults to @samp{"30 secs"}.
-@end deftypevr
+Prosodyctl will also help you to import certificates from the
+@code{letsencrypt} directory so that the @code{prosody} user can access
+them. See @url{https://prosody.im/doc/letsencrypt}.
-@deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf?
-Save mails with CR+LF instead of plain LF. This makes sending those
-mails take less CPU, especially with sendfile() syscall with Linux and
-FreeBSD. But it also creates a bit more disk I/O which may just make it
-slower. Also note that if other software reads the mboxes/maildirs,
-they may handle the extra CRs wrong and cause problems.
-Defaults to @samp{#f}.
-@end deftypevr
+@example
+prosodyctl --root cert import /etc/letsencrypt/live
+@end example
-@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-stat-dirs?
-By default LIST command returns all entries in maildir beginning
-with a dot. Enabling this option makes Dovecot return only entries
-which are directories. This is done by stat()ing each entry, so it
-causes more disk I/O.
- (For systems setting struct @samp{dirent->d_type} this check is free
-and it's done always regardless of this setting).
-Defaults to @samp{#f}.
-@end deftypevr
+The available configuration parameters follow. Each parameter
+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}.
-@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks?
-When copying a message, do it with hard links whenever possible.
-This makes the performance much better, and it's unlikely to have any
-side effects.
-Defaults to @samp{#t}.
-@end deftypevr
+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
+some other system; see the end for more details.
-@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs?
-Assume Dovecot is the only MUA accessing Maildir: Scan cur/
-directory only when its mtime changes unexpectedly or when we can't find
-the mail otherwise.
-Defaults to @samp{#f}.
-@end deftypevr
+The @code{file-object} type designates either a file-like object
+(@pxref{G-Expressions, file-like objects}) or a file name.
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks
-Which locking methods to use for locking mbox. There are four
-available:
+@c The following documentation was initially generated by
+@c (generate-documentation) in (gnu services messaging). Manually maintained
+@c documentation is better, so we shouldn't hesitate to edit below as
+@c needed. However if the change you want to make to this documentation
+@c can be done in an automated way, it's probably easier to change
+@c (generate-documentation) than to make it below and have to deal with
+@c the churn as Prosody updates.
-@table @code
-@item dotlock
-Create <mailbox>.lock file. This is the oldest and most NFS-safe
-solution. If you want to use /var/mail/ like directory, the users will
-need write access to that directory.
-@item dotlock-try
-Same as dotlock, but if it fails because of permissions or because there
-isn't enough disk space, just skip it.
-@item fcntl
-Use this if possible. Works with NFS too if lockd is used.
-@item flock
-May not exist in all systems. Doesn't work with NFS.
-@item lockf
-May not exist in all systems. Doesn't work with NFS.
-@end table
+Available @code{prosody-configuration} fields are:
-You can use multiple locking methods; if you do the order they're declared
-in is important to avoid deadlocks if other MTAs/MUAs are using multiple
-locking methods as well. Some operating systems don't allow using some of
-them simultaneously.
+@deftypevr {@code{prosody-configuration} parameter} package prosody
+The Prosody package.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks
-
+@deftypevr {@code{prosody-configuration} parameter} file-name data-path
+Location of the Prosody data storage directory. See
+@url{https://prosody.im/doc/configure}.
+Defaults to @samp{"/var/lib/prosody"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout
-Maximum time to wait for lock (all of them) before aborting.
-Defaults to @samp{"5 mins"}.
+@deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths
+Additional plugin directories. They are searched in all the specified
+paths in order. See @url{https://prosody.im/doc/plugins_directory}.
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout
-If dotlock exists but the mailbox isn't modified in any way,
-override the lock file after this much time.
-Defaults to @samp{"2 mins"}.
+@deftypevr {@code{prosody-configuration} parameter} file-name certificates
+Every virtual host and component needs a certificate so that clients and
+servers can securely verify its identity. Prosody will automatically load
+certificates/keys from the directory specified here.
+Defaults to @samp{"/etc/prosody/certs"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs?
-When mbox changes unexpectedly we have to fully read it to find out
-what changed. If the mbox is large this can take a long time. Since
-the change is usually just a newly appended mail, it'd be faster to
-simply read the new mails. If this setting is enabled, Dovecot does
-this but still safely fallbacks to re-reading the whole mbox file
-whenever something in mbox isn't how it's expected to be. The only real
-downside to this setting is that if some other MUA changes message
-flags, Dovecot doesn't notice it immediately. Note that a full sync is
-done with SELECT, EXAMINE, EXPUNGE and CHECK commands.
-Defaults to @samp{#t}.
+@deftypevr {@code{prosody-configuration} parameter} string-list admins
+This is a list of accounts that are admins for the server. Note that you
+must create the accounts separately. See @url{https://prosody.im/doc/admins} and
+@url{https://prosody.im/doc/creating_accounts}.
+Example: @code{(admins '("user1@@example.com" "user2@@example.net"))}
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs?
-Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
-EXAMINE, EXPUNGE or CHECK commands. If this is set,
-@samp{mbox-dirty-syncs} is ignored.
+@deftypevr {@code{prosody-configuration} parameter} boolean use-libevent?
+Enable use of libevent for better performance under high load. See
+@url{https://prosody.im/doc/libevent}.
Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes?
-Delay writing mbox headers until doing a full write sync (EXPUNGE
-and CHECK commands and when closing the mailbox). This is especially
-useful for POP3 where clients often delete all mails. The downside is
-that our changes aren't immediately visible to other MUAs.
-Defaults to @samp{#t}.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size
-If mbox size is smaller than this (e.g.@: 100k), don't write index
-files. If an index file already exists it's still read, just not
-updated.
-Defaults to @samp{0}.
+@deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled
+This is the list of modules Prosody will load on startup. It looks for
+@code{mod_modulename.lua} in the plugins folder, so make sure that exists too.
+Documentation on modules can be found at:
+@url{https://prosody.im/doc/modules}.
+Defaults to @samp{("roster" "saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" "version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size
-Maximum dbox file size until it's rotated.
-Defaults to @samp{10000000}.
+@deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled
+@samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but
+should you want to disable them then add them to this list.
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval
-Maximum dbox file age until it's rotated. Typically in days. Day
-begins from midnight, so 1d = today, 2d = yesterday, etc. 0 = check
-disabled.
-Defaults to @samp{"1d"}.
+@deftypevr {@code{prosody-configuration} parameter} file-object groups-file
+Path to a text file where the shared groups are defined. If this path is
+empty then @samp{mod_groups} does nothing. See
+@url{https://prosody.im/doc/modules/mod_groups}.
+Defaults to @samp{"/var/lib/prosody/sharedgroups.txt"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space?
-When creating new mdbox files, immediately preallocate their size to
-@samp{mdbox-rotate-size}. This setting currently works only in Linux
-with some file systems (ext4, xfs).
+@deftypevr {@code{prosody-configuration} parameter} boolean allow-registration?
+Disable account creation by default, for security. See
+@url{https://prosody.im/doc/creating_accounts}.
Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir
-sdbox and mdbox support saving mail attachments to external files,
-which also allows single instance storage for them. Other backends
-don't support this for now.
+@deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl
+These are the SSL/TLS-related settings. Most of them are disabled so to
+use Prosody's defaults. If you do not completely understand these options, do
+not add them to your config, it is easy to lower the security of your server
+using them. See @url{https://prosody.im/doc/advanced_ssl_config}.
-WARNING: This feature hasn't been tested much yet. Use at your own risk.
+Available @code{ssl-configuration} fields are:
-Directory root where to store mail attachments. Disabled, if empty.
-Defaults to @samp{""}.
+@deftypevr {@code{ssl-configuration} parameter} maybe-string protocol
+This determines what handshake to use.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size
-Attachments smaller than this aren't saved externally. It's also
-possible to write a plugin to disable saving specific attachments
-externally.
-Defaults to @samp{128000}.
+@deftypevr {@code{ssl-configuration} parameter} maybe-file-name key
+Path to your private key file.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs
-File system backend to use for saving attachments:
-@table @code
-@item posix
-No SiS done by Dovecot (but this might help FS's own deduplication)
-@item sis posix
-SiS with immediate byte-by-byte comparison during saving
-@item sis-queue posix
-SiS with delayed comparison and deduplication.
-@end table
-Defaults to @samp{"sis posix"}.
+@deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificate
+Path to your certificate file.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash
-Hash format to use in attachment filenames. You can add any text and
-variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}},
-@code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be
-truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits.
-Defaults to @samp{"%@{sha1@}"}.
+@deftypevr {@code{ssl-configuration} parameter} file-object capath
+Path to directory containing root certificates that you wish Prosody to
+trust when verifying the certificates of remote servers.
+Defaults to @samp{"/etc/ssl/certs"}.
+@end deftypevr
+
+@deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile
+Path to a file containing root certificates that you wish Prosody to trust.
+Similar to @code{capath} but with all certificates concatenated together.
+@end deftypevr
+
+@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify
+A list of verification options (these mostly map to OpenSSL's
+@code{set_verify()} flags).
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit
+@deftypevr {@code{ssl-configuration} parameter} maybe-string-list options
+A list of general options relating to SSL/TLS. These map to OpenSSL's
+@code{set_options()}. For a full list of options available in LuaSec, see the
+LuaSec source.
+@end deftypevr
-Defaults to @samp{100}.
+@deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth
+How long a chain of certificate authorities to check when looking for a
+trusted root certificate.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit
+@deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers
+An OpenSSL cipher string. This selects what ciphers Prosody will offer to
+clients, and in what order.
+@end deftypevr
-Defaults to @samp{1000}.
+@deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam
+A path to a file containing parameters for Diffie-Hellman key exchange. You
+can create such a file with:
+@code{openssl dhparam -out /etc/prosody/certs/dh-2048.pem 2048}
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit
-Default VSZ (virtual memory size) limit for service processes.
-This is mainly intended to catch and kill processes that leak memory
-before they eat up everything.
-Defaults to @samp{256000000}.
+@deftypevr {@code{ssl-configuration} parameter} maybe-string curve
+Curve for Elliptic curve Diffie-Hellman. Prosody's default is
+@samp{"secp384r1"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string default-login-user
-Login user is internally used by login processes. This is the most
-untrusted user in Dovecot system. It shouldn't have access to anything
-at all.
-Defaults to @samp{"dovenull"}.
+@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext
+A list of "extra" verification options.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string default-internal-user
-Internal user is used by unprivileged processes. It should be
-separate from login user, so that login processes can't disturb other
-processes.
-Defaults to @samp{"dovecot"}.
+@deftypevr {@code{ssl-configuration} parameter} maybe-string password
+Password for encrypted private keys.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl?
-SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>.
-Defaults to @samp{"required"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert
-PEM encoded X.509 SSL/TLS certificate (public key).
-Defaults to @samp{"</etc/dovecot/default.pem"}.
+@deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption?
+Whether to force all client-to-server connections to be encrypted or not.
+See @url{https://prosody.im/doc/modules/mod_tls}.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-key
-PEM encoded SSL/TLS private key. The key is opened before
-dropping root privileges, so keep the key file unreadable by anyone but
-root.
-Defaults to @samp{"</etc/dovecot/private/default.pem"}.
+@deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms
+Set of mechanisms that will never be offered. See
+@url{https://prosody.im/doc/modules/mod_saslauth}.
+Defaults to @samp{("DIGEST-MD5")}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password
-If key file is password protected, give the password here.
-Alternatively give it when starting dovecot with -p parameter. Since
-this file is often world-readable, you may want to place this setting
-instead to a different.
-Defaults to @samp{""}.
+@deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption?
+Whether to force all server-to-server connections to be encrypted or not.
+See @url{https://prosody.im/doc/modules/mod_tls}.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-ca
-PEM encoded trusted certificate authority. Set this only if you
-intend to use @samp{ssl-verify-client-cert? #t}. The file should
-contain the CA certificate(s) followed by the matching
-CRL(s). (e.g.@: @samp{ssl-ca </etc/ssl/certs/ca.pem}).
-Defaults to @samp{""}.
+@deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth?
+Whether to require encryption and certificate authentication. This
+provides ideal security, but requires servers you communicate with to support
+encryption AND present valid, trusted certificates. See
+@url{https://prosody.im/doc/s2s#security}.
+Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl?
-Require that CRL check succeeds for client certificates.
-Defaults to @samp{#t}.
+@deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains
+Many servers don't support encryption or have invalid or self-signed
+certificates. You can list domains here that will not be required to
+authenticate using certificates. They will be authenticated using DNS. See
+@url{https://prosody.im/doc/s2s#security}.
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert?
-Request client to send a certificate. If you also want to require
-it, set @samp{auth-ssl-require-client-cert? #t} in auth section.
-Defaults to @samp{#f}.
+@deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains
+Even if you leave @code{s2s-secure-auth?} disabled, you can still require
+valid certificates for some domains by specifying a list here. See
+@url{https://prosody.im/doc/s2s#security}.
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field
-Which field from certificate to use for username. commonName and
-x500UniqueIdentifier are the usual choices. You'll also need to set
-@samp{auth-ssl-username-from-cert? #t}.
-Defaults to @samp{"commonName"}.
+@deftypevr {@code{prosody-configuration} parameter} string authentication
+Select the authentication backend to use. The default provider stores
+passwords in plaintext and uses Prosody's configured data storage to store the
+authentication data. If you do not trust your server please see
+@url{https://prosody.im/doc/modules/mod_auth_internal_hashed} for information
+about using the hashed backend. See also
+@url{https://prosody.im/doc/authentication}
+Defaults to @samp{"internal_plain"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol
-Minimum SSL protocol version to accept.
-Defaults to @samp{"TLSv1"}.
+@deftypevr {@code{prosody-configuration} parameter} maybe-string log
+Set logging options. Advanced logging configuration is not yet supported
+by the Prosody service. See @url{https://prosody.im/doc/logging}.
+Defaults to @samp{"*syslog"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list
-SSL ciphers to use.
-Defaults to @samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}.
+@deftypevr {@code{prosody-configuration} parameter} file-name pidfile
+File to write pid in. See @url{https://prosody.im/doc/modules/mod_posix}.
+Defaults to @samp{"/var/run/prosody/prosody.pid"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device
-SSL crypto device to use, for valid values run "openssl engine".
-Defaults to @samp{""}.
+@deftypevr {@code{prosody-configuration} parameter} maybe-non-negative-integer http-max-content-size
+Maximum allowed size of the HTTP body (in bytes).
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string postmaster-address
-Address to use when sending rejection mails.
-%d expands to recipient domain.
-Defaults to @samp{"postmaster@@%d"}.
+@deftypevr {@code{prosody-configuration} parameter} maybe-string http-external-url
+Some modules expose their own URL in various ways. This URL is built
+from the protocol, host and port used. If Prosody sits behind a proxy, the
+public URL will be @code{http-external-url} instead. See
+@url{https://prosody.im/doc/http#external_url}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string hostname
-Hostname to use in various parts of sent mails (e.g.@: in Message-Id)
-and in LMTP replies. Default is the system's real hostname@@domain.
-Defaults to @samp{""}.
+@deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts
+A host in Prosody is a domain on which user accounts can be created. For
+example if you want your users to have addresses like
+@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 "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}.
+
+Available @code{virtualhost-configuration} fields are:
+
+all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
+@deftypevr {@code{virtualhost-configuration} parameter} string domain
+Domain you wish Prosody to serve.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail?
-If user is over quota, return with temporary failure instead of
-bouncing the mail.
-Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path
-Binary to use for sending mails.
-Defaults to @samp{"/usr/sbin/sendmail"}.
+@deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-components
+Components are extra services on a server which are available to clients,
+usually on a subdomain of the main server (such as
+@samp{"mycomponent.example.com"}). Example components might be chatroom
+servers, user directories, or gateways to other protocols.
+
+Internal components are implemented with Prosody-specific plugins. To add an
+internal component, you simply fill the hostname field, and the plugin you wish
+to use for the component.
+
+See @url{https://prosody.im/doc/components}.
+Defaults to @samp{()}.
+
+Available @code{int-component-configuration} fields are:
+
+all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
+@deftypevr {@code{int-component-configuration} parameter} string hostname
+Hostname of the component.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string submission-host
-If non-empty, send mails via this SMTP host[:port] instead of
-sendmail.
-Defaults to @samp{""}.
+@deftypevr {@code{int-component-configuration} parameter} string plugin
+Plugin you wish to use for the component.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string rejection-subject
-Subject: header to use for rejection mails. You can use the same
-variables as for @samp{rejection-reason} below.
-Defaults to @samp{"Rejected: %s"}.
+@deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-muc
+Multi-user chat (MUC) is Prosody's module for allowing you to create
+hosted chatrooms/conferences for XMPP users.
+
+General information on setting up and using multi-user chatrooms can be found
+in the "Chatrooms" documentation (@url{https://prosody.im/doc/chatrooms}),
+which you should read if you are new to XMPP chatrooms.
+
+See also @url{https://prosody.im/doc/modules/mod_muc}.
+
+Available @code{mod-muc-configuration} fields are:
+
+@deftypevr {@code{mod-muc-configuration} parameter} string name
+The name to return in service discovery responses.
+Defaults to @samp{"Prosody Chatrooms"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string rejection-reason
-Human readable error message for rejection mails. You can use
-variables:
+@deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation
+If @samp{#t}, this will only allow admins to create new chatrooms.
+Otherwise anyone can create a room. The value @samp{"local"} restricts room
+creation to users on the service's parent domain. E.g.@: @samp{user@@example.com}
+can create rooms on @samp{rooms.example.com}. The value @samp{"admin"}
+restricts to service administrators only.
+Defaults to @samp{#f}.
+@end deftypevr
-@table @code
-@item %n
-CRLF
-@item %r
-reason
-@item %s
-original subject
-@item %t
-recipient
-@end table
-Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}.
+@deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messages
+Maximum number of history messages that will be sent to the member that has
+just joined the room.
+Defaults to @samp{20}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter
-Delimiter character between local-part and detail in email
-address.
-Defaults to @samp{"+"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-header
-Header where the original recipient address (SMTP's RCPT TO:
-address) is taken from if not available elsewhere. With dovecot-lda -a
-parameter overrides this. A commonly used header for this is
-X-Original-To.
-Defaults to @samp{""}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate?
-Should saving a mail to a nonexistent mailbox automatically create
-it?.
-Defaults to @samp{#f}.
+@deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-components
+External components use XEP-0114, which most standalone components
+support. To add an external component, you simply fill the hostname field. See
+@url{https://prosody.im/doc/components}.
+Defaults to @samp{()}.
+
+Available @code{ext-component-configuration} fields are:
+
+all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
+@deftypevr {@code{ext-component-configuration} parameter} string component-secret
+Password which the component will use to log in.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe?
-Should automatically created mailboxes be also automatically
-subscribed?.
-Defaults to @samp{#f}.
+@deftypevr {@code{ext-component-configuration} parameter} string hostname
+Hostname of the component.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length
-Maximum IMAP command line length. Some clients generate very long
-command lines with huge mailboxes, so you may need to raise this if you
-get "Too long argument" or "IMAP command line too large" errors
-often.
-Defaults to @samp{64000}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format
-IMAP logout format string:
-@table @code
-@item %i
-total number of bytes read from client
-@item %o
-total number of bytes sent to client.
-@end table
-See @file{doc/wiki/Variables.txt} for a list of all the variables you can use.
-Defaults to @samp{"in=%i out=%o deleted=%@{deleted@} expunged=%@{expunged@} trashed=%@{trashed@} hdr_count=%@{fetch_hdr_count@} hdr_bytes=%@{fetch_hdr_bytes@} body_count=%@{fetch_body_count@} body_bytes=%@{fetch_body_bytes@}"}.
+@deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports
+Port(s) Prosody listens on for component connections.
+Defaults to @samp{(5347)}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string imap-capability
-Override the IMAP CAPABILITY response. If the value begins with '+',
-add the given capabilities on top of the defaults (e.g.@: +XFOO XBAR).
-Defaults to @samp{""}.
+@deftypevr {@code{prosody-configuration} parameter} string component-interface
+Interface Prosody listens on for component connections.
+Defaults to @samp{"127.0.0.1"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval
-How long to wait between "OK Still here" notifications when client
-is IDLEing.
-Defaults to @samp{"2 mins"}.
+@deftypevr {@code{prosody-configuration} parameter} maybe-raw-content raw-content
+Raw content that will be added to the configuration file.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string imap-id-send
-ID field names and values to send to clients. Using * as the value
-makes Dovecot use the default value. The following fields have default
-values currently: name, version, os, os-version, support-url,
-support-email.
-Defaults to @samp{""}.
+It could be that you just want to get a @code{prosody.cfg.lua}
+up and running. In that case, you can pass an
+@code{opaque-prosody-configuration} record as the value of
+@code{prosody-service-type}. As its name indicates, an opaque configuration
+does not have easy reflective capabilities.
+Available @code{opaque-prosody-configuration} fields are:
+
+@deftypevr {@code{opaque-prosody-configuration} parameter} package prosody
+The prosody package.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} string imap-id-log
-ID fields sent by client to log. * means everything.
-Defaults to @samp{""}.
+@deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua
+The contents of the @code{prosody.cfg.lua} to use.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds
-Workarounds for various client bugs:
+For example, if your @code{prosody.cfg.lua} is just the empty
+string, you could instantiate a prosody service like this:
-@table @code
-@item delay-newmail
-Send EXISTS/RECENT new mail notifications only when replying to NOOP and
-CHECK commands. Some clients ignore them otherwise, for example OSX
-Mail (<v2.1). Outlook Express breaks more badly though, without this it
-may show user "Message no longer in server" errors. Note that OE6
-still breaks even with this workaround if synchronization is set to
-"Headers Only".
+@example
+(service prosody-service-type
+ (opaque-prosody-configuration
+ (prosody.cfg.lua "")))
+@end example
-@item tb-extra-mailbox-sep
-Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and
-adds extra @samp{/} suffixes to mailbox names. This option causes Dovecot to
-ignore the extra @samp{/} instead of treating it as invalid mailbox name.
+@c end of Prosody auto-generated documentation
-@item tb-lsub-flags
-Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox).
-This makes Thunderbird realize they aren't selectable and show them
-greyed out, instead of only later giving "not selectable" popup error.
+@subsubheading BitlBee Service
+
+@cindex IRC (Internet Relay Chat)
+@cindex IRC gateway
+@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC
+interface to a variety of messaging protocols such as XMPP.
+
+@defvr {Scheme Variable} bitlbee-service-type
+This is the service type for the @url{http://bitlbee.org,BitlBee} IRC
+gateway daemon. Its value is a @code{bitlbee-configuration} (see
+below).
+
+To have BitlBee listen on port 6667 on localhost, add this line to your
+services:
+
+@example
+(service bitlbee-service-type)
+@end example
+@end defvr
+
+@deftp {Data Type} bitlbee-configuration
+This is the configuration for BitlBee, with the following fields:
+
+@table @asis
+@item @code{interface} (default: @code{"127.0.0.1"})
+@itemx @code{port} (default: @code{6667})
+Listen on the network interface corresponding to the IP address
+specified in @var{interface}, on @var{port}.
+
+When @var{interface} is @code{127.0.0.1}, only local clients can
+connect; when it is @code{0.0.0.0}, connections can come from any
+networking interface.
+
+@item @code{package} (default: @code{bitlbee})
+The BitlBee package to use.
+
+@item @code{plugins} (default: @code{'()})
+List of plugin packages to use---e.g., @code{bitlbee-discord}.
+
+@item @code{extra-settings} (default: @code{""})
+Configuration snippet added as-is to the BitlBee configuration file.
@end table
-Defaults to @samp{()}.
-@end deftypevr
+@end deftp
-@deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host
-Host allowed in URLAUTH URLs sent by client. "*" allows all.
-Defaults to @samp{""}.
-@end deftypevr
+@subsubheading Quassel Service
+@cindex IRC (Internet Relay Chat)
+@url{https://quassel-irc.org/,Quassel} is a distributed IRC client,
+meaning that one or more clients can attach to and detach from the
+central core.
-Whew! Lots of configuration options. The nice thing about it though is
-that GuixSD has a complete interface to Dovecot's configuration
-language. This allows not only a nice way to declare configurations,
-but also offers reflective capabilities as well: users can write code to
-inspect and transform configurations from within Scheme.
+@defvr {Scheme Variable} quassel-service-type
+This is the service type for the @url{https://quassel-irc.org/,Quassel}
+IRC backend daemon. Its value is a @code{quassel-configuration}
+(see below).
+@end defvr
-However, it could be that you just want to get a @code{dovecot.conf} up
-and running. In that case, you can pass an
-@code{opaque-dovecot-configuration} as the @code{#:config} parameter to
-@code{dovecot-service}. As its name indicates, an opaque configuration
-does not have easy reflective capabilities.
+@deftp {Data Type} quassel-configuration
+This is the configuration for Quassel, with the following fields:
-Available @code{opaque-dovecot-configuration} fields are:
+@table @asis
+@item @code{quassel} (default: @code{quassel})
+The Quassel package to use.
-@deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot
-The dovecot package.
-@end deftypevr
+@item @code{interface} (default: @code{"::,0.0.0.0"})
+@item @code{port} (default: @code{4242})
+Listen on the network interface(s) corresponding to the IPv4 or IPv6
+interfaces specified in the comma delimited @var{interface}, on
+@var{port}.
-@deftypevr {@code{opaque-dovecot-configuration} parameter} string string
-The contents of the @code{dovecot.conf}, as a string.
-@end deftypevr
+@item @code{loglevel} (default: @code{"Info"})
+The level of logging desired. Accepted values are Debug, Info, Warning
+and Error.
+@end table
+@end deftp
-For example, if your @code{dovecot.conf} is just the empty string, you
-could instantiate a dovecot service like this:
+@node Telephony Services
+@subsection Telephony Services
+
+@cindex Murmur (VoIP server)
+@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.
+
+@deftp {Data Type} murmur-configuration
+The service type for the Murmur server. An example configuration can
+look like this:
@example
-(dovecot-service #:config
- (opaque-dovecot-configuration
- (string "")))
+(service murmur-service-type
+ (murmur-configuration
+ (welcome-text
+ "Welcome to this Mumble server running on Guix!")
+ (cert-required? #t) ;disallow text password logins
+ (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem")
+ (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem")))
@end example
-@subsubheading OpenSMTPD Service
+After reconfiguring your system, you can manually set the murmur @code{SuperUser}
+password with the command that is printed during the activation phase.
-@deffn {Scheme Variable} opensmtpd-service-type
-This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD}
-service, whose value should be an @code{opensmtpd-configuration} object
-as in this example:
+It is recommended to register a normal Mumble user account
+and grant it admin or moderator rights.
+You can use the @code{mumble} client to
+login as new normal user, register yourself, and log out.
+For the next step login with the name @code{SuperUser} use
+the @code{SuperUser} password that you set previously,
+and grant your newly registered mumble user administrator or moderator
+rights and create some channels.
+
+Available @code{murmur-configuration} fields are:
+
+@table @asis
+@item @code{package} (default: @code{mumble})
+Package that contains @code{bin/murmurd}.
+
+@item @code{user} (default: @code{"murmur"})
+User who will run the Murmur server.
+
+@item @code{group} (default: @code{"murmur"})
+Group of the user who will run the murmur server.
+
+@item @code{port} (default: @code{64738})
+Port on which the server will listen.
+
+@item @code{welcome-text} (default: @code{""})
+Welcome text sent to clients when they connect.
+
+@item @code{server-password} (default: @code{""})
+Password the clients have to enter in order to connect.
+
+@item @code{max-users} (default: @code{100})
+Maximum of users that can be connected to the server at once.
+
+@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"})
+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"})
+File name of the log file.
+The service's user will become the owner of the directory.
+
+@item @code{autoban-attempts} (default: @code{10})
+Maximum number of logins a user can make in @code{autoban-timeframe}
+without getting auto banned for @code{autoban-time}.
-@example
-(service opensmtpd-service-type
- (opensmtpd-configuration
- (config-file (local-file "./my-smtpd.conf"))))
-@end example
-@end deffn
+@item @code{autoban-timeframe} (default: @code{120})
+Timeframe for autoban in seconds.
-@deftp {Data Type} opensmtpd-configuration
-Data type representing the configuration of opensmtpd.
+@item @code{autoban-time} (default: @code{300})
+Amount of time in seconds for which a client gets banned
+when violating the autoban limits.
-@table @asis
-@item @code{package} (default: @var{opensmtpd})
-Package object of the OpenSMTPD SMTP server.
+@item @code{opus-threshold} (default: @code{100})
+Percentage of clients that need to support opus
+before switching over to opus audio codec.
-@item @code{config-file} (default: @var{%default-opensmtpd-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{channel-nesting-limit} (default: @code{10})
+How deep channels can be nested at maximum.
-@end table
-@end deftp
+@item @code{channelname-regex} (default: @code{#f})
+A string in form of a Qt regular expression that channel names must conform to.
-@subsubheading Exim Service
+@item @code{username-regex} (default: @code{#f})
+A string in form of a Qt regular expression that user names must conform to.
-@cindex mail transfer agent (MTA)
-@cindex MTA (mail transfer agent)
-@cindex SMTP
+@item @code{text-message-length} (default: @code{5000})
+Maximum size in bytes that a user can send in one text chat message.
-@deffn {Scheme Variable} exim-service-type
-This is the type of the @uref{https://exim.org, Exim} mail transfer
-agent (MTA), whose value should be an @code{exim-configuration} object
-as in this example:
+@item @code{image-message-length} (default: @code{(* 128 1024)})
+Maximum size in bytes that a user can send in one image message.
-@example
-(service exim-service-type
- (exim-configuration
- (config-file (local-file "./my-exim.conf"))))
-@end example
-@end deffn
+@item @code{cert-required?} (default: @code{#f})
+If it is set to @code{#t} clients that use weak password authentification
+will not be accepted. Users must have completed the certificate wizard to join.
-In order to use an @code{exim-service-type} service you must also have a
-@code{mail-aliases-service-type} service present in your
-@code{operating-system} (even if it has no aliases).
+@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.
-@deftp {Data Type} exim-configuration
-Data type representing the configuration of exim.
+@item @code{allow-html?} (default: @code{#f})
+Should html be allowed in text messages, user comments, and channel descriptions.
-@table @asis
-@item @code{package} (default: @var{exim})
-Package object of the Exim server.
+@item @code{allow-ping?} (default: @code{#f})
+Setting to true exposes the current user count, the maximum user count, and
+the server's maximum bandwidth per client to unauthenticated users. In the
+Mumble client, this information is shown in the Connect dialog.
-@item @code{config-file} (default: @code{#f})
-File-like object of the Exim configuration file to use. If its value is
-@code{#f} then use the default configuration file from the package
-provided in @code{package}. The resulting configuration file is loaded
-after setting the @code{exim_user} and @code{exim_group} configuration
-variables.
+Disabling this setting will prevent public listing of the server.
-@end table
-@end deftp
+@item @code{bonjour?} (default: @code{#f})
+Should the server advertise itself in the local network through the bonjour protocol.
-@subsubheading Mail Aliases Service
+@item @code{send-version?} (default: @code{#f})
+Should the murmur server version be exposed in ping requests.
-@cindex email aliases
-@cindex aliases, for email addresses
+@item @code{log-days} (default: @code{31})
+Murmur 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.
-@deffn {Scheme Variable} mail-aliases-service-type
-This is the type of the service which provides @code{/etc/aliases},
-specifying how to deliver mail to users on this system.
+@item @code{obfuscate-ips?} (default: @code{#t})
+Should logged ips be obfuscated to protect the privacy of users.
+
+@item @code{ssl-cert} (default: @code{#f})
+File name of the SSL/TLS certificate used for encrypted connections.
@example
-(service mail-aliases-service-type
- '(("postmaster" "bob")
- ("bob" "bob@@example.com" "bob@@example2.com")))
+(ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem")
+@end example
+@item @code{ssl-key} (default: @code{#f})
+Filepath to the ssl private key used for encrypted connections.
+@example
+(ssl-key "/etc/letsencrypt/live/example.com/privkey.pem")
@end example
-@end deffn
-The configuration for a @code{mail-aliases-service-type} service is an
-association list denoting how to deliver mail that comes to this
-system. Each entry is of the form @code{(alias addresses ...)}, with
-@code{alias} specifying the local alias and @code{addresses} specifying
-where to deliver this user's mail.
+@item @code{ssl-dh-params} (default: @code{#f})
+File name of a PEM-encoded file with Diffie-Hellman parameters
+for the SSL/TLS encryption. Alternatively you set it to
+@code{"@@ffdhe2048"}, @code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"}
+or @code{"@@ffdhe8192"} to use bundled parameters from RFC 7919.
-The aliases aren't required to exist as users on the local system. In
-the above example, there doesn't need to be a @code{postmaster} entry in
-the @code{operating-system}'s @code{user-accounts} in order to deliver
-the @code{postmaster} mail to @code{bob} (which subsequently would
-deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}).
+@item @code{ssl-ciphers} (default: @code{#f})
+The @code{ssl-ciphers} option chooses the cipher suites to make available for use
+in SSL/TLS.
-@node Messaging Services
-@subsubsection Messaging Services
+This option is specified using
+@uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT,
+OpenSSL cipher list notation}.
-@cindex messaging
-@cindex jabber
-@cindex XMPP
-The @code{(gnu services messaging)} module provides Guix service
-definitions for messaging services: currently only Prosody is supported.
+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.
-@subsubheading Prosody Service
+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.
-@deffn {Scheme Variable} prosody-service-type
-This is the type for the @uref{https://prosody.im, Prosody XMPP
-communication server}. Its value must be a @code{prosody-configuration}
-record as in this example:
+@item @code{public-registration} (default: @code{#f})
+Must be a @code{<murmur-public-registration-configuration>} record or @code{#f}.
-@example
-(service prosody-service-type
- (prosody-configuration
- (modules-enabled (cons "groups" "mam" %default-modules-enabled))
- (int-components
- (list
- (int-component-configuration
- (hostname "conference.example.net")
- (plugin "muc")
- (mod-muc (mod-muc-configuration)))))
- (virtualhosts
- (list
- (virtualhost-configuration
- (domain "example.net"))))))
-@end example
+You can optionally register your server in the public server list that the
+@code{mumble} client shows on startup.
+You cannot register your server if you have set a @code{server-password},
+or set @code{allow-ping} to @code{#f}.
-See below for details about @code{prosody-configuration}.
+It might take a few hours until it shows up in the public list.
-@end deffn
+@item @code{file} (default: @code{#f})
+Optional alternative override for this configuration.
+@end table
+@end deftp
-By default, Prosody does not need much configuration. Only one
-@code{virtualhosts} field is needed: it specifies the domain you wish
-Prosody to serve.
+@deftp {Data Type} murmur-public-registration-configuration
+Configuration for public registration of a murmur service.
-You can perform various sanity checks on the generated configuration
-with the @code{prosodyctl check} command.
+@table @asis
+@item @code{name}
+This is a display name for your server. Not to be confused with the hostname.
-Prosodyctl will also help you to import certificates from the
-@code{letsencrypt} directory so that the @code{prosody} user can access
-them. See @url{https://prosody.im/doc/letsencrypt}.
+@item @code{password}
+A password to identify your registration.
+Subsequent updates will need the same password. Don't lose your password.
-@example
-prosodyctl --root cert import /etc/letsencrypt/live
-@end example
+@item @code{url}
+This should be a @code{http://} or @code{https://} link to your web
+site.
-The available configuration parameters follow. Each parameter
-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}.
+@item @code{hostname} (default: @code{#f})
+By default your server will be listed by its IP address.
+If it is set your server will be linked by this host name instead.
+@end table
+@end deftp
-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
-some other system; see the end for more details.
-The @code{file-object} type designates either a file-like object
-(@pxref{G-Expressions, file-like objects}) or a file name.
-@c The following documentation was initially generated by
-@c (generate-documentation) in (gnu services messaging). Manually maintained
-@c documentation is better, so we shouldn't hesitate to edit below as
-@c needed. However if the change you want to make to this documentation
-@c can be done in an automated way, it's probably easier to change
-@c (generate-documentation) than to make it below and have to deal with
-@c the churn as Prosody updates.
+@node Monitoring Services
+@subsection Monitoring Services
-Available @code{prosody-configuration} fields are:
+@subsubheading Tailon Service
-@deftypevr {@code{prosody-configuration} parameter} package prosody
-The Prosody package.
-@end deftypevr
+@uref{https://tailon.readthedocs.io/, Tailon} is a web application for
+viewing and searching log files.
-@deftypevr {@code{prosody-configuration} parameter} file-name data-path
-Location of the Prosody data storage directory. See
-@url{https://prosody.im/doc/configure}.
-Defaults to @samp{"/var/lib/prosody"}.
-@end deftypevr
+The following example will configure the service with default values.
+By default, Tailon can be accessed on port 8080 (@code{http://localhost:8080}).
-@deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths
-Additional plugin directories. They are searched in all the specified
-paths in order. See @url{https://prosody.im/doc/plugins_directory}.
-Defaults to @samp{()}.
-@end deftypevr
+@example
+(service tailon-service-type)
+@end example
-@deftypevr {@code{prosody-configuration} parameter} file-name certificates
-Every virtual host and component needs a certificate so that clients and
-servers can securely verify its identity. Prosody will automatically load
-certificates/keys from the directory specified here.
-Defaults to @samp{"/etc/prosody/certs"}.
-@end deftypevr
+The following example customises more of the Tailon configuration,
+adding @command{sed} to the list of allowed commands.
+
+@example
+(service tailon-service-type
+ (tailon-configuration
+ (config-file
+ (tailon-configuration-file
+ (allowed-commands '("tail" "grep" "awk" "sed"))))))
+@end example
-@deftypevr {@code{prosody-configuration} parameter} string-list admins
-This is a list of accounts that are admins for the server. Note that you
-must create the accounts separately. See @url{https://prosody.im/doc/admins} and
-@url{https://prosody.im/doc/creating_accounts}.
-Example: @code{(admins '("user1@@example.com" "user2@@example.net"))}
-Defaults to @samp{()}.
-@end deftypevr
-@deftypevr {@code{prosody-configuration} parameter} boolean use-libevent?
-Enable use of libevent for better performance under high load. See
-@url{https://prosody.im/doc/libevent}.
-Defaults to @samp{#f}.
-@end deftypevr
+@deftp {Data Type} tailon-configuration
+Data type representing the configuration of Tailon.
+This type has the following parameters:
-@deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled
-This is the list of modules Prosody will load on startup. It looks for
-@code{mod_modulename.lua} in the plugins folder, so make sure that exists too.
-Documentation on modules can be found at:
-@url{https://prosody.im/doc/modules}.
-Defaults to @samp{("roster" "saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" "version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}.
-@end deftypevr
+@table @asis
+@item @code{config-file} (default: @code{(tailon-configuration-file)})
+The configuration file to use for Tailon. This can be set to a
+@dfn{tailon-configuration-file} record value, or any gexp
+(@pxref{G-Expressions}).
-@deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled
-@samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but
-should you want to disable them then add them to this list.
-Defaults to @samp{()}.
-@end deftypevr
+For example, to instead use a local file, the @code{local-file} function
+can be used:
-@deftypevr {@code{prosody-configuration} parameter} file-object groups-file
-Path to a text file where the shared groups are defined. If this path is
-empty then @samp{mod_groups} does nothing. See
-@url{https://prosody.im/doc/modules/mod_groups}.
-Defaults to @samp{"/var/lib/prosody/sharedgroups.txt"}.
-@end deftypevr
+@example
+(service tailon-service-type
+ (tailon-configuration
+ (config-file (local-file "./my-tailon.conf"))))
+@end example
-@deftypevr {@code{prosody-configuration} parameter} boolean allow-registration?
-Disable account creation by default, for security. See
-@url{https://prosody.im/doc/creating_accounts}.
-Defaults to @samp{#f}.
-@end deftypevr
+@item @code{package} (default: @code{tailon})
+The tailon package to use.
-@deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl
-These are the SSL/TLS-related settings. Most of them are disabled so to
-use Prosody's defaults. If you do not completely understand these options, do
-not add them to your config, it is easy to lower the security of your server
-using them. See @url{https://prosody.im/doc/advanced_ssl_config}.
+@end table
+@end deftp
-Available @code{ssl-configuration} fields are:
+@deftp {Data Type} tailon-configuration-file
+Data type representing the configuration options for Tailon.
+This type has the following parameters:
-@deftypevr {@code{ssl-configuration} parameter} maybe-string protocol
-This determines what handshake to use.
-@end deftypevr
+@table @asis
+@item @code{files} (default: @code{(list "/var/log")})
+List of files to display. The list can include strings for a single file
+or directory, or a list, where the first item is the name of a
+subsection, and the remaining items are the files or directories in that
+subsection.
-@deftypevr {@code{ssl-configuration} parameter} maybe-file-name key
-Path to your private key file.
-@end deftypevr
+@item @code{bind} (default: @code{"localhost:8080"})
+Address and port to which Tailon should bind on.
-@deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificate
-Path to your certificate file.
-@end deftypevr
+@item @code{relative-root} (default: @code{#f})
+URL path to use for Tailon, set to @code{#f} to not use a path.
-@deftypevr {@code{ssl-configuration} parameter} file-object capath
-Path to directory containing root certificates that you wish Prosody to
-trust when verifying the certificates of remote servers.
-Defaults to @samp{"/etc/ssl/certs"}.
-@end deftypevr
+@item @code{allow-transfers?} (default: @code{#t})
+Allow downloading the log files in the web interface.
-@deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile
-Path to a file containing root certificates that you wish Prosody to trust.
-Similar to @code{capath} but with all certificates concatenated together.
-@end deftypevr
+@item @code{follow-names?} (default: @code{#t})
+Allow tailing of not-yet existent files.
-@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify
-A list of verification options (these mostly map to OpenSSL's
-@code{set_verify()} flags).
-@end deftypevr
+@item @code{tail-lines} (default: @code{200})
+Number of lines to read initially from each file.
-@deftypevr {@code{ssl-configuration} parameter} maybe-string-list options
-A list of general options relating to SSL/TLS. These map to OpenSSL's
-@code{set_options()}. For a full list of options available in LuaSec, see the
-LuaSec source.
-@end deftypevr
+@item @code{allowed-commands} (default: @code{(list "tail" "grep" "awk")})
+Commands to allow running. By default, @code{sed} is disabled.
-@deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth
-How long a chain of certificate authorities to check when looking for a
-trusted root certificate.
-@end deftypevr
+@item @code{debug?} (default: @code{#f})
+Set @code{debug?} to @code{#t} to show debug messages.
-@deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers
-An OpenSSL cipher string. This selects what ciphers Prosody will offer to
-clients, and in what order.
-@end deftypevr
+@item @code{wrap-lines} (default: @code{#t})
+Initial line wrapping state in the web interface. Set to @code{#t} to
+initially wrap lines (the default), or to @code{#f} to initially not
+wrap lines.
-@deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam
-A path to a file containing parameters for Diffie-Hellman key exchange. You
-can create such a file with:
-@code{openssl dhparam -out /etc/prosody/certs/dh-2048.pem 2048}
-@end deftypevr
+@item @code{http-auth} (default: @code{#f})
+HTTP authentication type to use. Set to @code{#f} to disable
+authentication (the default). Supported values are @code{"digest"} or
+@code{"basic"}.
-@deftypevr {@code{ssl-configuration} parameter} maybe-string curve
-Curve for Elliptic curve Diffie-Hellman. Prosody's default is
-@samp{"secp384r1"}.
-@end deftypevr
+@item @code{users} (default: @code{#f})
+If HTTP authentication is enabled (see @code{http-auth}), access will be
+restricted to the credentials provided here. To configure users, use a
+list of pairs, where the first element of the pair is the username, and
+the 2nd element of the pair is the password.
-@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext
-A list of "extra" verification options.
-@end deftypevr
+@example
+(tailon-configuration-file
+ (http-auth "basic")
+ (users '(("user1" . "password1")
+ ("user2" . "password2"))))
+@end example
-@deftypevr {@code{ssl-configuration} parameter} maybe-string password
-Password for encrypted private keys.
-@end deftypevr
+@end table
+@end deftp
-@end deftypevr
-@deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption?
-Whether to force all client-to-server connections to be encrypted or not.
-See @url{https://prosody.im/doc/modules/mod_tls}.
-Defaults to @samp{#f}.
-@end deftypevr
+@subsubheading Darkstat Service
+@cindex darkstat
+Darkstat is a packet sniffer that captures network traffic, calculates
+statistics about usage, and serves reports over HTTP.
-@deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms
-Set of mechanisms that will never be offered. See
-@url{https://prosody.im/doc/modules/mod_saslauth}.
-Defaults to @samp{("DIGEST-MD5")}.
-@end deftypevr
+@defvar {Scheme Variable} darkstat-service-type
+This is the service type for the
+@uref{https://unix4lyfe.org/darkstat/, darkstat}
+service, its value must be a @code{darkstat-configuration} record as in
+this example:
-@deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption?
-Whether to force all server-to-server connections to be encrypted or not.
-See @url{https://prosody.im/doc/modules/mod_tls}.
-Defaults to @samp{#f}.
-@end deftypevr
+@example
+(service darkstat-service-type
+ (darkstat-configuration
+ (interface "eno1")))
+@end example
+@end defvar
-@deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth?
-Whether to require encryption and certificate authentication. This
-provides ideal security, but requires servers you communicate with to support
-encryption AND present valid, trusted certificates. See
-@url{https://prosody.im/doc/s2s#security}.
-Defaults to @samp{#f}.
-@end deftypevr
+@deftp {Data Type} darkstat-configuration
+Data type representing the configuration of @command{darkstat}.
-@deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains
-Many servers don't support encryption or have invalid or self-signed
-certificates. You can list domains here that will not be required to
-authenticate using certificates. They will be authenticated using DNS. See
-@url{https://prosody.im/doc/s2s#security}.
-Defaults to @samp{()}.
-@end deftypevr
+@table @asis
+@item @code{package} (default: @code{darkstat})
+The darkstat package to use.
-@deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains
-Even if you leave @code{s2s-secure-auth?} disabled, you can still require
-valid certificates for some domains by specifying a list here. See
-@url{https://prosody.im/doc/s2s#security}.
-Defaults to @samp{()}.
-@end deftypevr
+@item @code{interface}
+Capture traffic on the specified network interface.
-@deftypevr {@code{prosody-configuration} parameter} string authentication
-Select the authentication backend to use. The default provider stores
-passwords in plaintext and uses Prosody's configured data storage to store the
-authentication data. If you do not trust your server please see
-@url{https://prosody.im/doc/modules/mod_auth_internal_hashed} for information
-about using the hashed backend. See also
-@url{https://prosody.im/doc/authentication}
-Defaults to @samp{"internal_plain"}.
-@end deftypevr
+@item @code{port} (default: @code{"667"})
+Bind the web interface to the specified port.
-@deftypevr {@code{prosody-configuration} parameter} maybe-string log
-Set logging options. Advanced logging configuration is not yet supported
-by the GuixSD Prosody Service. See @url{https://prosody.im/doc/logging}.
-Defaults to @samp{"*syslog"}.
-@end deftypevr
+@item @code{bind-address} (default: @code{"127.0.0.1"})
+Bind the web interface to the specified address.
-@deftypevr {@code{prosody-configuration} parameter} file-name pidfile
-File to write pid in. See @url{https://prosody.im/doc/modules/mod_posix}.
-Defaults to @samp{"/var/run/prosody/prosody.pid"}.
-@end deftypevr
+@item @code{base} (default: @code{"/"})
+Specify the path of the base URL. This can be useful if
+@command{darkstat} is accessed via a reverse proxy.
-@deftypevr {@code{prosody-configuration} parameter} maybe-non-negative-integer http-max-content-size
-Maximum allowed size of the HTTP body (in bytes).
-@end deftypevr
+@end table
+@end deftp
-@deftypevr {@code{prosody-configuration} parameter} maybe-string http-external-url
-Some modules expose their own URL in various ways. This URL is built
-from the protocol, host and port used. If Prosody sits behind a proxy, the
-public URL will be @code{http-external-url} instead. See
-@url{https://prosody.im/doc/http#external_url}.
-@end deftypevr
+@subsubheading Prometheus Node Exporter Service
+
+@cindex prometheus-node-exporter
+The Prometheus ``node exporter'' makes hardware and operating system statistics
+provided by the Linux kernel available for the Prometheus monitoring system.
+This service should be deployed on all physical nodes and virtual machines,
+where monitoring these statistics is desirable.
-@deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts
-A host in Prosody is a domain on which user accounts can be created. For
-example if you want your users to have addresses like
-@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.
+@defvar {Scheme variable} prometheus-node-exporter-service-type
+This is the service type for the
+@uref{https://github.com/prometheus/node_exporter/, prometheus-node-exporter}
+service, its value must be a @code{prometheus-node-exporter-configuration}
+record as in this example:
-Note: the name "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.
+@example
+(service prometheus-node-exporter-service-type
+ (prometheus-node-exporter-configuration
+ (web-listen-address ":9100")))
+@end example
+@end defvar
-See @url{https://prosody.im/doc/configure#virtual_host_settings}.
+@deftp {Data Type} prometheus-node-exporter-configuration
+Data type representing the configuration of @command{node_exporter}.
-Available @code{virtualhost-configuration} fields are:
+@table @asis
+@item @code{package} (default: @code{go-github-com-prometheus-node-exporter})
+The prometheus-node-exporter package to use.
-all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
-@deftypevr {@code{virtualhost-configuration} parameter} string domain
-Domain you wish Prosody to serve.
-@end deftypevr
+@item @code{web-listen-address} (default: @code{":9100"})
+Bind the web interface to the specified address.
-@end deftypevr
+@end table
+@end deftp
-@deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-components
-Components are extra services on a server which are available to clients,
-usually on a subdomain of the main server (such as
-@samp{"mycomponent.example.com"}). Example components might be chatroom
-servers, user directories, or gateways to other protocols.
+@subsubheading Zabbix server
+@cindex zabbix zabbix-server
+Zabbix provides monitoring metrics, among others network utilization, CPU load
+and disk space consumption:
-Internal components are implemented with Prosody-specific plugins. To add an
-internal component, you simply fill the hostname field, and the plugin you wish
-to use for the component.
+@itemize
+@item High performance, high capacity (able to monitor hundreds of thousands of devices).
+@item Auto-discovery of servers and network devices and interfaces.
+@item Low-level discovery, allows to automatically start monitoring new items, file systems or network interfaces among others.
+@item Distributed monitoring with centralized web administration.
+@item Native high performance agents.
+@item SLA, and ITIL KPI metrics on reporting.
+@item High-level (business) view of monitored resources through user-defined visual console screens and dashboards.
+@item Remote command execution through Zabbix proxies.
+@end itemize
-See @url{https://prosody.im/doc/components}.
-Defaults to @samp{()}.
+@c %start of fragment
-Available @code{int-component-configuration} fields are:
+Available @code{zabbix-server-configuration} fields are:
-all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
-@deftypevr {@code{int-component-configuration} parameter} string hostname
-Hostname of the component.
-@end deftypevr
+@deftypevr {@code{zabbix-server-configuration} parameter} package zabbix-server
+The zabbix-server package.
-@deftypevr {@code{int-component-configuration} parameter} string plugin
-Plugin you wish to use for the component.
@end deftypevr
-@deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-muc
-Multi-user chat (MUC) is Prosody's module for allowing you to create
-hosted chatrooms/conferences for XMPP users.
+@deftypevr {@code{zabbix-server-configuration} parameter} string user
+User who will run the Zabbix server.
-General information on setting up and using multi-user chatrooms can be found
-in the "Chatrooms" documentation (@url{https://prosody.im/doc/chatrooms}),
-which you should read if you are new to XMPP chatrooms.
+Defaults to @samp{"zabbix"}.
-See also @url{https://prosody.im/doc/modules/mod_muc}.
+@end deftypevr
-Available @code{mod-muc-configuration} fields are:
+@deftypevr {@code{zabbix-server-configuration} parameter} group group
+Group who will run the Zabbix server.
-@deftypevr {@code{mod-muc-configuration} parameter} string name
-The name to return in service discovery responses.
-Defaults to @samp{"Prosody Chatrooms"}.
-@end deftypevr
+Defaults to @samp{"zabbix"}.
-@deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation
-If @samp{#t}, this will only allow admins to create new chatrooms.
-Otherwise anyone can create a room. The value @samp{"local"} restricts room
-creation to users on the service's parent domain. E.g.@: @samp{user@@example.com}
-can create rooms on @samp{rooms.example.com}. The value @samp{"admin"}
-restricts to service administrators only.
-Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messages
-Maximum number of history messages that will be sent to the member that has
-just joined the room.
-Defaults to @samp{20}.
-@end deftypevr
+@deftypevr {@code{zabbix-server-configuration} parameter} string db-host
+Database host name.
-@end deftypevr
+Defaults to @samp{"127.0.0.1"}.
@end deftypevr
-@deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-components
-External components use XEP-0114, which most standalone components
-support. To add an external component, you simply fill the hostname field. See
-@url{https://prosody.im/doc/components}.
-Defaults to @samp{()}.
+@deftypevr {@code{zabbix-server-configuration} parameter} string db-name
+Database name.
-Available @code{ext-component-configuration} fields are:
+Defaults to @samp{"zabbix"}.
-all these @code{prosody-configuration} fields: @code{admins}, @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, @code{groups-file}, @code{allow-registration?}, @code{ssl}, @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, @code{s2s-require-encryption?}, @code{s2s-secure-auth?}, @code{s2s-insecure-domains}, @code{s2s-secure-domains}, @code{authentication}, @code{log}, @code{http-max-content-size}, @code{http-external-url}, @code{raw-content}, plus:
-@deftypevr {@code{ext-component-configuration} parameter} string component-secret
-Password which the component will use to log in.
@end deftypevr
-@deftypevr {@code{ext-component-configuration} parameter} string hostname
-Hostname of the component.
-@end deftypevr
+@deftypevr {@code{zabbix-server-configuration} parameter} string db-user
+Database user.
-@end deftypevr
+Defaults to @samp{"zabbix"}.
-@deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports
-Port(s) Prosody listens on for component connections.
-Defaults to @samp{(5347)}.
@end deftypevr
-@deftypevr {@code{prosody-configuration} parameter} string component-interface
-Interface Prosody listens on for component connections.
-Defaults to @samp{"127.0.0.1"}.
-@end deftypevr
+@deftypevr {@code{zabbix-server-configuration} parameter} string db-password
+Database password. Please, use @code{include-files} with
+@code{DBPassword=SECRET} inside a specified file instead.
+
+Defaults to @samp{""}.
-@deftypevr {@code{prosody-configuration} parameter} maybe-raw-content raw-content
-Raw content that will be added to the configuration file.
@end deftypevr
-It could be that you just want to get a @code{prosody.cfg.lua}
-up and running. In that case, you can pass an
-@code{opaque-prosody-configuration} record as the value of
-@code{prosody-service-type}. As its name indicates, an opaque configuration
-does not have easy reflective capabilities.
-Available @code{opaque-prosody-configuration} fields are:
+@deftypevr {@code{zabbix-server-configuration} parameter} number db-port
+Database port.
-@deftypevr {@code{opaque-prosody-configuration} parameter} package prosody
-The prosody package.
-@end deftypevr
+Defaults to @samp{5432}.
-@deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua
-The contents of the @code{prosody.cfg.lua} to use.
@end deftypevr
-For example, if your @code{prosody.cfg.lua} is just the empty
-string, you could instantiate a prosody service like this:
+@deftypevr {@code{zabbix-server-configuration} parameter} string log-type
+Specifies where log messages are written to:
-@example
-(service prosody-service-type
- (opaque-prosody-configuration
- (prosody.cfg.lua "")))
-@end example
+@itemize @bullet
+@item
+@code{system} - syslog.
-@c end of Prosody auto-generated documentation
+@item
+@code{file} - file specified with @code{log-file} parameter.
-@subsubheading BitlBee Service
+@item
+@code{console} - standard output.
-@cindex IRC (Internet Relay Chat)
-@cindex IRC gateway
-@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC
-interface to a variety of messaging protocols such as XMPP.
+@end itemize
-@defvr {Scheme Variable} bitlbee-service-type
-This is the service type for the @url{http://bitlbee.org,BitlBee} IRC
-gateway daemon. Its value is a @code{bitlbee-configuration} (see
-below).
+Defaults to @samp{""}.
-To have BitlBee listen on port 6667 on localhost, add this line to your
-services:
+@end deftypevr
-@example
-(service bitlbee-service-type)
-@end example
-@end defvr
+@deftypevr {@code{zabbix-server-configuration} parameter} string log-file
+Log file name for @code{log-type} @code{file} parameter.
-@deftp {Data Type} bitlbee-configuration
-This is the configuration for BitlBee, with the following fields:
+Defaults to @samp{"/var/log/zabbix/server.log"}.
-@table @asis
-@item @code{interface} (default: @code{"127.0.0.1"})
-@itemx @code{port} (default: @code{6667})
-Listen on the network interface corresponding to the IP address
-specified in @var{interface}, on @var{port}.
+@end deftypevr
-When @var{interface} is @code{127.0.0.1}, only local clients can
-connect; when it is @code{0.0.0.0}, connections can come from any
-networking interface.
+@deftypevr {@code{zabbix-server-configuration} parameter} string pid-file
+Name of PID file.
-@item @code{package} (default: @code{bitlbee})
-The BitlBee package to use.
+Defaults to @samp{"/var/run/zabbix/zabbix_server.pid"}.
-@item @code{plugins} (default: @code{'()})
-List of plugin packages to use---e.g., @code{bitlbee-discord}.
+@end deftypevr
-@item @code{extra-settings} (default: @code{""})
-Configuration snippet added as-is to the BitlBee configuration file.
-@end table
-@end deftp
+@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-ca-location
+The location of certificate authority (CA) files for SSL server
+certificate verification.
-@subsubheading Quassel Service
+Defaults to @samp{"/etc/ssl/certs/ca-certificates.crt"}.
-@cindex IRC (Internet Relay Chat)
-@url{https://quassel-irc.org/,Quassel} is a distributed IRC client,
-meaning that one or more clients can attach to and detach from the
-central core.
+@end deftypevr
-@defvr {Scheme Variable} quassel-service-type
-This is the service type for the @url{https://quassel-irc.org/,Quassel}
-IRC backend daemon. Its value is a @code{quassel-configuration}
-(see below).
-@end defvr
+@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-cert-location
+Location of SSL client certificates.
-@deftp {Data Type} quassel-configuration
-This is the configuration for Quassel, with the following fields:
+Defaults to @samp{"/etc/ssl/certs"}.
-@table @asis
-@item @code{quassel} (default: @code{quassel})
-The Quassel package to use.
+@end deftypevr
-@item @code{interface} (default: @code{"::,0.0.0.0"})
-@item @code{port} (default: @code{4242})
-Listen on the network interface(s) corresponding to the IPv4 or IPv6
-interfaces specified in the comma delimited @var{interface}, on
-@var{port}.
+@deftypevr {@code{zabbix-server-configuration} parameter} string extra-options
+Extra options will be appended to Zabbix server configuration file.
-@item @code{loglevel} (default: @code{"Info"})
-The level of logging desired. Accepted values are Debug, Info, Warning
-and Error.
-@end table
-@end deftp
+Defaults to @samp{""}.
-@node Telephony Services
-@subsubsection Telephony Services
+@end deftypevr
+
+@deftypevr {@code{zabbix-server-configuration} parameter} include-files include-files
+You may include individual files or all files in a directory in the
+configuration file.
-@cindex Murmur (VoIP server)
-@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.
+Defaults to @samp{()}.
-@deftp {Data Type} murmur-configuration
-The service type for the Murmur server. An example configuration can
-look like this:
+@end deftypevr
-@example
-(service murmur-service-type
- (murmur-configuration
- (welcome-text
- "Welcome to this Mumble server running on GuixSD!")
- (cert-required? #t) ;disallow text password logins
- (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem")
- (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem")))
-@end example
+@c %end of fragment
-After reconfiguring your system, you can manually set the murmur @code{SuperUser}
-password with the command that is printed during the activation phase.
+@subsubheading Zabbix agent
+@cindex zabbix zabbix-agent
-It is recommended to register a normal Mumble user account
-and grant it admin or moderator rights.
-You can use the @code{mumble} client to
-login as new normal user, register yourself, and log out.
-For the next step login with the name @code{SuperUser} use
-the @code{SuperUser} password that you set previously,
-and grant your newly registered mumble user administrator or moderator
-rights and create some channels.
+Zabbix agent gathers information for Zabbix server.
-Available @code{murmur-configuration} fields are:
+@c %start of fragment
-@table @asis
-@item @code{package} (default: @code{mumble})
-Package that contains @code{bin/murmurd}.
+Available @code{zabbix-agent-configuration} fields are:
-@item @code{user} (default: @code{"murmur"})
-User who will run the Murmur server.
+@deftypevr {@code{zabbix-agent-configuration} parameter} package zabbix-agent
+The zabbix-agent package.
-@item @code{group} (default: @code{"murmur"})
-Group of the user who will run the murmur server.
+@end deftypevr
-@item @code{port} (default: @code{64738})
-Port on which the server will listen.
+@deftypevr {@code{zabbix-agent-configuration} parameter} string user
+User who will run the Zabbix agent.
-@item @code{welcome-text} (default: @code{""})
-Welcome text sent to clients when they connect.
+Defaults to @samp{"zabbix"}.
-@item @code{server-password} (default: @code{""})
-Password the clients have to enter in order to connect.
+@end deftypevr
-@item @code{max-users} (default: @code{100})
-Maximum of users that can be connected to the server at once.
+@deftypevr {@code{zabbix-agent-configuration} parameter} group group
+Group who will run the Zabbix agent.
-@item @code{max-user-bandwidth} (default: @code{#f})
-Maximum voice traffic a user can send per second.
+Defaults to @samp{"zabbix"}.
-@item @code{database-file} (default: @code{"/var/lib/murmur/db.sqlite"})
-File name of the sqlite database.
-The service's user will become the owner of the directory.
+@end deftypevr
-@item @code{log-file} (default: @code{"/var/log/murmur/murmur.log"})
-File name of the log file.
-The service's user will become the owner of the directory.
+@deftypevr {@code{zabbix-agent-configuration} parameter} string hostname
+Unique, case sensitive hostname which is required for active checks and
+must match hostname as configured on the server.
-@item @code{autoban-attempts} (default: @code{10})
-Maximum number of logins a user can make in @code{autoban-timeframe}
-without getting auto banned for @code{autoban-time}.
+Defaults to @samp{"Zabbix server"}.
-@item @code{autoban-timeframe} (default: @code{120})
-Timeframe for autoban in seconds.
+@end deftypevr
-@item @code{autoban-time} (default: @code{300})
-Amount of time in seconds for which a client gets banned
-when violating the autoban limits.
+@deftypevr {@code{zabbix-agent-configuration} parameter} string log-type
+Specifies where log messages are written to:
-@item @code{opus-threshold} (default: @code{100})
-Percentage of clients that need to support opus
-before switching over to opus audio codec.
+@itemize @bullet
+@item
+@code{system} - syslog.
-@item @code{channel-nesting-limit} (default: @code{10})
-How deep channels can be nested at maximum.
+@item
+@code{file} - file specified with @code{log-file} parameter.
-@item @code{channelname-regex} (default: @code{#f})
-A string in form of a Qt regular expression that channel names must conform to.
+@item
+@code{console} - standard output.
-@item @code{username-regex} (default: @code{#f})
-A string in form of a Qt regular expression that user names must conform to.
+@end itemize
-@item @code{text-message-length} (default: @code{5000})
-Maximum size in bytes that a user can send in one text chat message.
+Defaults to @samp{""}.
-@item @code{image-message-length} (default: @code{(* 128 1024)})
-Maximum size in bytes that a user can send in one image message.
+@end deftypevr
-@item @code{cert-required?} (default: @code{#f})
-If it is set to @code{#t} clients that use weak password authentification
-will not be accepted. Users must have completed the certificate wizard to join.
+@deftypevr {@code{zabbix-agent-configuration} parameter} string log-file
+Log file name for @code{log-type} @code{file} parameter.
-@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.
+Defaults to @samp{"/var/log/zabbix/agent.log"}.
-@item @code{allow-html?} (default: @code{#f})
-Should html be allowed in text messages, user comments, and channel descriptions.
+@end deftypevr
-@item @code{allow-ping?} (default: @code{#f})
-Setting to true exposes the current user count, the maximum user count, and
-the server's maximum bandwidth per client to unauthenticated users. In the
-Mumble client, this information is shown in the Connect dialog.
+@deftypevr {@code{zabbix-agent-configuration} parameter} string pid-file
+Name of PID file.
-Disabling this setting will prevent public listing of the server.
+Defaults to @samp{"/var/run/zabbix/zabbix_agent.pid"}.
-@item @code{bonjour?} (default: @code{#f})
-Should the server advertise itself in the local network through the bonjour protocol.
+@end deftypevr
-@item @code{send-version?} (default: @code{#f})
-Should the murmur server version be exposed in ping requests.
+@deftypevr {@code{zabbix-agent-configuration} parameter} list server
+List of IP addresses, optionally in CIDR notation, or hostnames of
+Zabbix servers and Zabbix proxies. Incoming connections will be
+accepted only from the hosts listed here.
-@item @code{log-days} (default: @code{31})
-Murmur 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.
+Defaults to @samp{("127.0.0.1")}.
-@item @code{obfuscate-ips?} (default: @code{#t})
-Should logged ips be obfuscated to protect the privacy of users.
+@end deftypevr
-@item @code{ssl-cert} (default: @code{#f})
-File name of the SSL/TLS certificate used for encrypted connections.
+@deftypevr {@code{zabbix-agent-configuration} parameter} list server-active
+List of IP:port (or hostname:port) pairs of Zabbix servers and Zabbix
+proxies for active checks. If port is not specified, default port is
+used. If this parameter is not specified, active checks are disabled.
-@example
-(ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem")
-@end example
-@item @code{ssl-key} (default: @code{#f})
-Filepath to the ssl private key used for encrypted connections.
-@example
-(ssl-key "/etc/letsencrypt/live/example.com/privkey.pem")
-@end example
+Defaults to @samp{("127.0.0.1")}.
-@item @code{ssl-dh-params} (default: @code{#f})
-File name of a PEM-encoded file with Diffie-Hellman parameters
-for the SSL/TLS encryption. Alternatively you set it to
-@code{"@@ffdhe2048"}, @code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"}
-or @code{"@@ffdhe8192"} to use bundled parameters from RFC 7919.
+@end deftypevr
-@item @code{ssl-ciphers} (default: @code{#f})
-The @code{ssl-ciphers} option chooses the cipher suites to make available for use
-in SSL/TLS.
+@deftypevr {@code{zabbix-agent-configuration} parameter} string extra-options
+Extra options will be appended to Zabbix server configuration file.
-This option is specified using
-@uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT,
-OpenSSL cipher list notation}.
+Defaults to @samp{""}.
-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.
+@end deftypevr
-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.
+@deftypevr {@code{zabbix-agent-configuration} parameter} include-files include-files
+You may include individual files or all files in a directory in the
+configuration file.
-@item @code{public-registration} (default: @code{#f})
-Must be a @code{<murmur-public-registration-configuration>} record or @code{#f}.
+Defaults to @samp{()}.
-You can optionally register your server in the public server list that the
-@code{mumble} client shows on startup.
-You cannot register your server if you have set a @code{server-password},
-or set @code{allow-ping} to @code{#f}.
+@end deftypevr
-It might take a few hours until it shows up in the public list.
+@c %end of fragment
-@item @code{file} (default: @code{#f})
-Optional alternative override for this configuration.
-@end table
-@end deftp
+@subsubheading Zabbix front-end
+@cindex zabbix zabbix-front-end
-@deftp {Data Type} murmur-public-registration-configuration
-Configuration for public registration of a murmur service.
+This service provides a WEB interface to Zabbix server.
-@table @asis
-@item @code{name}
-This is a display name for your server. Not to be confused with the hostname.
+@c %start of fragment
-@item @code{password}
-A password to identify your registration.
-Subsequent updates will need the same password. Don't lose your password.
+Available @code{zabbix-front-end-configuration} fields are:
-@item @code{url}
-This should be a @code{http://} or @code{https://} link to your web
-site.
+@deftypevr {@code{zabbix-front-end-configuration} parameter} nginx-server-configuration-list nginx
+NGINX configuration.
-@item @code{hostname} (default: @code{#f})
-By default your server will be listed by its IP address.
-If it is set your server will be linked by this host name instead.
-@end table
-@end deftp
+@end deftypevr
+@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-host
+Database host name.
+Defaults to @samp{"localhost"}.
-@node Monitoring Services
-@subsubsection Monitoring Services
+@end deftypevr
-@subsubheading Tailon Service
+@deftypevr {@code{zabbix-front-end-configuration} parameter} number db-port
+Database port.
-@uref{https://tailon.readthedocs.io/, Tailon} is a web application for
-viewing and searching log files.
+Defaults to @samp{5432}.
-The following example will configure the service with default values.
-By default, Tailon can be accessed on port 8080 (@code{http://localhost:8080}).
+@end deftypevr
-@example
-(service tailon-service-type)
-@end example
+@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-name
+Database name.
-The following example customises more of the Tailon configuration,
-adding @command{sed} to the list of allowed commands.
+Defaults to @samp{"zabbix"}.
-@example
-(service tailon-service-type
- (tailon-configuration
- (config-file
- (tailon-configuration-file
- (allowed-commands '("tail" "grep" "awk" "sed"))))))
-@end example
+@end deftypevr
+@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-user
+Database user.
-@deftp {Data Type} tailon-configuration
-Data type representing the configuration of Tailon.
-This type has the following parameters:
+Defaults to @samp{"zabbix"}.
-@table @asis
-@item @code{config-file} (default: @code{(tailon-configuration-file)})
-The configuration file to use for Tailon. This can be set to a
-@dfn{tailon-configuration-file} record value, or any gexp
-(@pxref{G-Expressions}).
+@end deftypevr
-For example, to instead use a local file, the @code{local-file} function
-can be used:
+@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-password
+Database password. Please, use @code{db-secret-file} instead.
-@example
-(service tailon-service-type
- (tailon-configuration
- (config-file (local-file "./my-tailon.conf"))))
-@end example
+Defaults to @samp{""}.
-@item @code{package} (default: @code{tailon})
-The tailon package to use.
+@end deftypevr
-@end table
-@end deftp
+@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-secret-file
+Secret file which will be appended to @file{zabbix.conf.php} file. This
+file contains credentials for use by Zabbix front-end. You are expected
+to create it manually.
-@deftp {Data Type} tailon-configuration-file
-Data type representing the configuration options for Tailon.
-This type has the following parameters:
+Defaults to @samp{""}.
-@table @asis
-@item @code{files} (default: @code{(list "/var/log")})
-List of files to display. The list can include strings for a single file
-or directory, or a list, where the first item is the name of a
-subsection, and the remaining items are the files or directories in that
-subsection.
+@end deftypevr
-@item @code{bind} (default: @code{"localhost:8080"})
-Address and port to which Tailon should bind on.
+@deftypevr {@code{zabbix-front-end-configuration} parameter} string zabbix-host
+Zabbix server hostname.
-@item @code{relative-root} (default: @code{#f})
-URL path to use for Tailon, set to @code{#f} to not use a path.
+Defaults to @samp{"localhost"}.
-@item @code{allow-transfers?} (default: @code{#t})
-Allow downloading the log files in the web interface.
+@end deftypevr
-@item @code{follow-names?} (default: @code{#t})
-Allow tailing of not-yet existent files.
+@deftypevr {@code{zabbix-front-end-configuration} parameter} number zabbix-port
+Zabbix server port.
-@item @code{tail-lines} (default: @code{200})
-Number of lines to read initially from each file.
+Defaults to @samp{10051}.
-@item @code{allowed-commands} (default: @code{(list "tail" "grep" "awk")})
-Commands to allow running. By default, @code{sed} is disabled.
+@end deftypevr
-@item @code{debug?} (default: @code{#f})
-Set @code{debug?} to @code{#t} to show debug messages.
-@item @code{wrap-lines} (default: @code{#t})
-Initial line wrapping state in the web interface. Set to @code{#t} to
-initially wrap lines (the default), or to @code{#f} to initially not
-wrap lines.
+@c %end of fragment
-@item @code{http-auth} (default: @code{#f})
-HTTP authentication type to use. Set to @code{#f} to disable
-authentication (the default). Supported values are @code{"digest"} or
-@code{"basic"}.
+@node Kerberos Services
+@subsection Kerberos Services
+@cindex Kerberos
-@item @code{users} (default: @code{#f})
-If HTTP authentication is enabled (see @code{http-auth}), access will be
-restricted to the credentials provided here. To configure users, use a
-list of pairs, where the first element of the pair is the username, and
-the 2nd element of the pair is the password.
+The @code{(gnu services kerberos)} module provides services relating to
+the authentication protocol @dfn{Kerberos}.
-@example
-(tailon-configuration-file
- (http-auth "basic")
- (users '(("user1" . "password1")
- ("user2" . "password2"))))
-@end example
+@subsubheading Krb5 Service
-@end table
-@end deftp
+Programs using a Kerberos client library normally
+expect a configuration file in @file{/etc/krb5.conf}.
+This service generates such a file from a definition provided in the
+operating system declaration.
+It does not cause any daemon to be started.
+No ``keytab'' files are provided by this service---you must explicitly create them.
+This service is known to work with the MIT client library, @code{mit-krb5}.
+Other implementations have not been tested.
-@subsubheading Darkstat Service
-@cindex darkstat
-Darkstat is a packet sniffer that captures network traffic, calculates
-statistics about usage, and serves reports over HTTP.
+@defvr {Scheme Variable} krb5-service-type
+A service type for Kerberos 5 clients.
+@end defvr
-@defvar {Scheme Variable} darkstat-service-type
-This is the service type for the
-@uref{https://unix4lyfe.org/darkstat/, darkstat}
-service, its value must be a @code{darkstat-configuration} record as in
-this example:
+@noindent
+Here is an example of its use:
+@lisp
+(service krb5-service-type
+ (krb5-configuration
+ (default-realm "EXAMPLE.COM")
+ (allow-weak-crypto? #t)
+ (realms (list
+ (krb5-realm
+ (name "EXAMPLE.COM")
+ (admin-server "groucho.example.com")
+ (kdc "karl.example.com"))
+ (krb5-realm
+ (name "ARGRX.EDU")
+ (admin-server "kerb-admin.argrx.edu")
+ (kdc "keys.argrx.edu"))))))
+@end lisp
-@example
-(service darkstat-service-type
- (darkstat-configuration
- (interface "eno1")))
-@end example
-@end defvar
+@noindent
+This example provides a Kerberos@tie{}5 client configuration which:
+@itemize
+@item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both
+of which have distinct administration servers and key distribution centers;
+@item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly
+specified by clients;
+@item Accepts services which only support encryption types known to be weak.
+@end itemize
-@deftp {Data Type} darkstat-configuration
-Data type representing the configuration of @command{darkstat}.
+The @code{krb5-realm} and @code{krb5-configuration} types have many fields.
+Only the most commonly used ones are described here.
+For a full list, and more detailed explanation of each, see the MIT
+@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
+documentation.
+
+@deftp {Data Type} krb5-realm
+@cindex realm, kerberos
@table @asis
-@item @code{package} (default: @code{darkstat})
-The darkstat package to use.
+@item @code{name}
+This field is a string identifying the name of the realm.
+A common convention is to use the fully qualified DNS name of your organization,
+converted to upper case.
-@item @code{interface}
-Capture traffic on the specified network interface.
+@item @code{admin-server}
+This field is a string identifying the host where the administration server is
+running.
-@item @code{port} (default: @code{"667"})
-Bind the web interface to the specified port.
+@item @code{kdc}
+This field is a string identifying the key distribution center
+for the realm.
+@end table
+@end deftp
-@item @code{bind-address} (default: @code{"127.0.0.1"})
-Bind the web interface to the specified address.
+@deftp {Data Type} krb5-configuration
-@item @code{base} (default: @code{"/"})
-Specify the path of the base URL. This can be useful if
-@command{darkstat} is accessed via a reverse proxy.
+@table @asis
+@item @code{allow-weak-crypto?} (default: @code{#f})
+If this flag is @code{#t} then services which only offer encryption algorithms
+known to be weak will be accepted.
+
+@item @code{default-realm} (default: @code{#f})
+This field should be a string identifying the default Kerberos
+realm for the client.
+You should set this field to the name of your Kerberos realm.
+If this value is @code{#f}
+then a realm must be specified with every Kerberos principal when invoking programs
+such as @command{kinit}.
+@item @code{realms}
+This should be a non-empty list of @code{krb5-realm} objects, which clients may
+access.
+Normally, one of them will have a @code{name} field matching the @code{default-realm}
+field.
@end table
@end deftp
-@subsubheading Prometheus Node Exporter Service
-
-@cindex prometheus-node-exporter
-The Prometheus ``node exporter'' makes hardware and operating system statistics
-provided by the Linux kernel available for the Prometheus monitoring system.
-This service should be deployed on all physical nodes and virtual machines,
-where monitoring these statistics is desirable.
-@defvar {Scheme variable} prometheus-node-exporter-service-type
-This is the service type for the
-@uref{https://github.com/prometheus/node_exporter/, prometheus-node-exporter}
-service, its value must be a @code{prometheus-node-exporter-configuration}
-record as in this example:
+@subsubheading PAM krb5 Service
+@cindex pam-krb5
-@example
-(service prometheus-node-exporter-service-type
- (prometheus-node-exporter-configuration
- (web-listen-address ":9100")))
-@end example
-@end defvar
+The @code{pam-krb5} service allows for login authentication and password
+management via Kerberos.
+You will need this service if you want PAM enabled applications to authenticate
+users using Kerberos.
-@deftp {Data Type} prometheus-node-exporter-configuration
-Data type representing the configuration of @command{node_exporter}.
+@defvr {Scheme Variable} pam-krb5-service-type
+A service type for the Kerberos 5 PAM module.
+@end defvr
+@deftp {Data Type} pam-krb5-configuration
+Data type representing the configuration of the Kerberos 5 PAM module
+This type has the following parameters:
@table @asis
-@item @code{package} (default: @code{go-github-com-prometheus-node-exporter})
-The prometheus-node-exporter package to use.
-
-@item @code{web-listen-address} (default: @code{":9100"})
-Bind the web interface to the specified address.
+@item @code{pam-krb5} (default: @code{pam-krb5})
+The pam-krb5 package to use.
+@item @code{minimum-uid} (default: @code{1000})
+The smallest user ID for which Kerberos authentications should be attempted.
+Local accounts with lower values will silently fail to authenticate.
@end table
@end deftp
-@subsubheading Zabbix server
-@cindex zabbix zabbix-server
-Zabbix provides monitoring metrics, among others network utilization, CPU load
-and disk space consumption:
-@itemize
-@item High performance, high capacity (able to monitor hundreds of thousands of devices).
-@item Auto-discovery of servers and network devices and interfaces.
-@item Low-level discovery, allows to automatically start monitoring new items, file systems or network interfaces among others.
-@item Distributed monitoring with centralized web administration.
-@item Native high performance agents.
-@item SLA, and ITIL KPI metrics on reporting.
-@item High-level (business) view of monitored resources through user-defined visual console screens and dashboards.
-@item Remote command execution through Zabbix proxies.
-@end itemize
+@node LDAP Services
+@subsection LDAP Services
+@cindex LDAP
+@cindex nslcd, LDAP service
+
+The @code{(gnu services authentication)} module provides the
+@code{nslcd-service-type}, which can be used to authenticate against an LDAP
+server. In addition to configuring the service itself, you may want to add
+@code{ldap} as a name service to the Name Service Switch. @xref{Name Service
+Switch} for detailed information.
+
+Here is a simple operating system declaration with a default configuration of
+the @code{nslcd-service-type} and a Name Service Switch configuration that
+consults the @code{ldap} name service last:
+
+@example
+(use-service-modules authentication)
+(use-modules (gnu system nss))
+...
+(operating-system
+ ...
+ (services
+ (cons*
+ (service nslcd-service-type)
+ (service dhcp-client-service-type)
+ %base-services))
+ (name-service-switch
+ (let ((services (list (name-service (name "db"))
+ (name-service (name "files"))
+ (name-service (name "ldap")))))
+ (name-service-switch
+ (inherit %mdns-host-lookup-nss)
+ (password services)
+ (shadow services)
+ (group services)
+ (netgroup services)
+ (gshadow services)))))
+@end example
-@c %start of fragment
+@c %start of generated documentation for nslcd-configuration
-Available @code{zabbix-server-configuration} fields are:
+Available @code{nslcd-configuration} fields are:
-@deftypevr {@code{zabbix-server-configuration} parameter} package zabbix-server
-The zabbix-server package.
+@deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd
+The @code{nss-pam-ldapd} package to use.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} string user
-User who will run the Zabbix server.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number threads
+The number of threads to start that can handle requests and perform LDAP
+queries. Each thread opens a separate connection to the LDAP server.
+The default is to start 5 threads.
-Defaults to @samp{"zabbix"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} group group
-Group who will run the Zabbix server.
+@deftypevr {@code{nslcd-configuration} parameter} string uid
+This specifies the user id with which the daemon should be run.
-Defaults to @samp{"zabbix"}.
+Defaults to @samp{"nslcd"}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} string db-host
-Database host name.
+@deftypevr {@code{nslcd-configuration} parameter} string gid
+This specifies the group id with which the daemon should be run.
-Defaults to @samp{"127.0.0.1"}.
+Defaults to @samp{"nslcd"}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} string db-name
-Database name.
+@deftypevr {@code{nslcd-configuration} parameter} log-option log
+This option controls the way logging is done via a list containing
+SCHEME and LEVEL. The SCHEME argument may either be the symbols "none"
+or "syslog", or an absolute file name. The LEVEL argument is optional
+and specifies the log level. The log level may be one of the following
+symbols: "crit", "error", "warning", "notice", "info" or "debug". All
+messages with the specified log level or higher are logged.
-Defaults to @samp{"zabbix"}.
+Defaults to @samp{("/var/log/nslcd" info)}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} string db-user
-Database user.
+@deftypevr {@code{nslcd-configuration} parameter} list uri
+The list of LDAP server URIs. Normally, only the first server will be
+used with the following servers as fall-back.
-Defaults to @samp{"zabbix"}.
+Defaults to @samp{("ldap://localhost:389/")}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} string db-password
-Database password. Please, use @code{include-files} with
-@code{DBPassword=SECRET} inside a specified file instead.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version
+The version of the LDAP protocol to use. The default is to use the
+maximum version supported by the LDAP library.
-Defaults to @samp{""}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} number db-port
-Database port.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn
+Specifies the distinguished name with which to bind to the directory
+server for lookups. The default is to bind anonymously.
-Defaults to @samp{5432}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} string log-type
-Specifies where log messages are written to:
-
-@itemize @bullet
-@item
-@code{system} - syslog.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw
+Specifies the credentials with which to bind. This option is only
+applicable when used with binddn.
-@item
-@code{file} - file specified with @code{log-file} parameter.
+Defaults to @samp{disabled}.
-@item
-@code{console} - standard output.
+@end deftypevr
-@end itemize
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn
+Specifies the distinguished name to use when the root user tries to
+modify a user's password using the PAM module.
-Defaults to @samp{""}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} string log-file
-Log file name for @code{log-type} @code{file} parameter.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw
+Specifies the credentials with which to bind if the root user tries to
+change a user's password. This option is only applicable when used with
+rootpwmoddn
-Defaults to @samp{"/var/log/zabbix/server.log"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} string pid-file
-Name of PID file.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech
+Specifies the SASL mechanism to be used when performing SASL
+authentication.
-Defaults to @samp{"/var/run/zabbix/zabbix_server.pid"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-ca-location
-The location of certificate authority (CA) files for SSL server
-certificate verification.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm
+Specifies the SASL realm to be used when performing SASL authentication.
-Defaults to @samp{"/etc/ssl/certs/ca-certificates.crt"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-cert-location
-Location of SSL client certificates.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid
+Specifies the authentication identity to be used when performing SASL
+authentication.
-Defaults to @samp{"/etc/ssl/certs"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} string extra-options
-Extra options will be appended to Zabbix server configuration file.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid
+Specifies the authorization identity to be used when performing SASL
+authentication.
-Defaults to @samp{""}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-server-configuration} parameter} include-files include-files
-You may include individual files or all files in a directory in the
-configuration file.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize?
+Determines whether the LDAP server host name should be canonicalised. If
+this is enabled the LDAP library will do a reverse host name lookup. By
+default, it is left up to the LDAP library whether this check is
+performed or not.
-Defaults to @samp{()}.
+Defaults to @samp{disabled}.
@end deftypevr
-@c %end of fragment
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname
+Set the name for the GSS-API Kerberos credentials cache.
-@subsubheading Zabbix agent
-@cindex zabbix zabbix-agent
+Defaults to @samp{disabled}.
-Zabbix agent gathers information for Zabbix server.
+@end deftypevr
-@c %start of fragment
+@deftypevr {@code{nslcd-configuration} parameter} string base
+The directory search base.
-Available @code{zabbix-agent-configuration} fields are:
+Defaults to @samp{"dc=example,dc=com"}.
-@deftypevr {@code{zabbix-agent-configuration} parameter} package zabbix-agent
-The zabbix-agent package.
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} scope-option scope
+Specifies the search scope (subtree, onelevel, base or children). The
+default scope is subtree; base scope is almost never useful for name
+service lookups; children scope is not supported on all servers.
+
+Defaults to @samp{(subtree)}.
@end deftypevr
-@deftypevr {@code{zabbix-agent-configuration} parameter} string user
-User who will run the Zabbix agent.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref
+Specifies the policy for dereferencing aliases. The default policy is
+to never dereference aliases.
-Defaults to @samp{"zabbix"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-agent-configuration} parameter} group group
-Group who will run the Zabbix agent.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals
+Specifies whether automatic referral chasing should be enabled. The
+default behaviour is to chase referrals.
-Defaults to @samp{"zabbix"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-agent-configuration} parameter} string hostname
-Unique, case sensitive hostname which is required for active checks and
-must match hostname as configured on the server.
+@deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps
+This option allows for custom attributes to be looked up instead of the
+default RFC 2307 attributes. It is a list of maps, each consisting of
+the name of a map, the RFC 2307 attribute to match and the query
+expression for the attribute as it is available in the directory.
-Defaults to @samp{"Zabbix server"}.
+Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{zabbix-agent-configuration} parameter} string log-type
-Specifies where log messages are written to:
+@deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters
+A list of filters consisting of the name of a map to which the filter
+applies and an LDAP search filter expression.
-@itemize @bullet
-@item
-@code{system} - syslog.
+Defaults to @samp{()}.
-@item
-@code{file} - file specified with @code{log-file} parameter.
+@end deftypevr
-@item
-@code{console} - standard output.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit
+Specifies the time limit in seconds to use when connecting to the
+directory server. The default value is 10 seconds.
-@end itemize
+Defaults to @samp{disabled}.
-Defaults to @samp{""}.
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit
+Specifies the time limit (in seconds) to wait for a response from the
+LDAP server. A value of zero, which is the default, is to wait
+indefinitely for searches to be completed.
+
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-agent-configuration} parameter} string log-file
-Log file name for @code{log-type} @code{file} parameter.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit
+Specifies the period if inactivity (in seconds) after which the con‐
+nection to the LDAP server will be closed. The default is not to time
+out connections.
-Defaults to @samp{"/var/log/zabbix/agent.log"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-agent-configuration} parameter} string pid-file
-Name of PID file.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime
+Specifies the number of seconds to sleep when connecting to all LDAP
+servers fails. By default one second is waited between the first
+failure and the first retry.
-Defaults to @samp{"/var/run/zabbix/zabbix_agent.pid"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-agent-configuration} parameter} list server
-List of IP addresses, optionally in CIDR notation, or hostnames of
-Zabbix servers and Zabbix proxies. Incoming connections will be
-accepted only from the hosts listed here.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime
+Specifies the time after which the LDAP server is considered to be
+permanently unavailable. Once this time is reached retries will be done
+only once per this time period. The default value is 10 seconds.
-Defaults to @samp{("127.0.0.1")}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-agent-configuration} parameter} list server-active
-List of IP:port (or hostname:port) pairs of Zabbix servers and Zabbix
-proxies for active checks. If port is not specified, default port is
-used. If this parameter is not specified, active checks are disabled.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl
+Specifies whether to use SSL/TLS or not (the default is not to). If
+'start-tls is specified then StartTLS is used rather than raw LDAP over
+SSL.
-Defaults to @samp{("127.0.0.1")}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-agent-configuration} parameter} string extra-options
-Extra options will be appended to Zabbix server configuration file.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert
+Specifies what checks to perform on a server-supplied certificate. The
+meaning of the values is described in the ldap.conf(5) manual page.
-Defaults to @samp{""}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-agent-configuration} parameter} include-files include-files
-You may include individual files or all files in a directory in the
-configuration file.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir
+Specifies the directory containing X.509 certificates for peer authen‐
+tication. This parameter is ignored when using GnuTLS.
-Defaults to @samp{()}.
+Defaults to @samp{disabled}.
@end deftypevr
-@c %end of fragment
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile
+Specifies the path to the X.509 certificate for peer authentication.
-@subsubheading Zabbix front-end
-@cindex zabbix zabbix-front-end
+Defaults to @samp{disabled}.
-This service provides a WEB interface to Zabbix server.
+@end deftypevr
-@c %start of fragment
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile
+Specifies the path to an entropy source. This parameter is ignored when
+using GnuTLS.
-Available @code{zabbix-front-end-configuration} fields are:
+Defaults to @samp{disabled}.
-@deftypevr {@code{zabbix-front-end-configuration} parameter} nginx-server-configuration-list nginx
-NGINX configuration.
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers
+Specifies the ciphers to use for TLS as a string.
+
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-host
-Database host name.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert
+Specifies the path to the file containing the local certificate for
+client TLS authentication.
-Defaults to @samp{"localhost"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-front-end-configuration} parameter} number db-port
-Database port.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key
+Specifies the path to the file containing the private key for client TLS
+authentication.
-Defaults to @samp{5432}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-name
-Database name.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize
+Set this to a number greater than 0 to request paged results from the
+LDAP server in accordance with RFC2696. The default (0) is to not
+request paged results.
-Defaults to @samp{"zabbix"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-user
-Database user.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers
+This option prevents group membership lookups through LDAP for the
+specified users. Alternatively, the value 'all-local may be used. With
+that value nslcd builds a full list of non-LDAP users on startup.
-Defaults to @samp{"zabbix"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-password
-Database password. Please, use @code{db-secret-file} instead.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid
+This option ensures that LDAP users with a numeric user id lower than
+the specified value are ignored.
-Defaults to @samp{""}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-secret-file
-Secret file which will be appended to @file{zabbix.conf.php} file. This
-file contains credentials for use by Zabbix front-end. You are expected
-to create it manually.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset
+This option specifies an offset that is added to all LDAP numeric user
+ids. This can be used to avoid user id collisions with local users.
-Defaults to @samp{""}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-front-end-configuration} parameter} string zabbix-host
-Zabbix server hostname.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset
+This option specifies an offset that is added to all LDAP numeric group
+ids. This can be used to avoid user id collisions with local groups.
-Defaults to @samp{"localhost"}.
+Defaults to @samp{disabled}.
@end deftypevr
-@deftypevr {@code{zabbix-front-end-configuration} parameter} number zabbix-port
-Zabbix server port.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups
+If this option is set, the member attribute of a group may point to
+another group. Members of nested groups are also returned in the higher
+level group and parent groups are returned when finding groups for a
+specific user. The default is not to perform extra searches for nested
+groups.
-Defaults to @samp{10051}.
+Defaults to @samp{disabled}.
@end deftypevr
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers
+If this option is set, the group member list is not retrieved when
+looking up groups. Lookups for finding which groups a user belongs to
+will remain functional so the user will likely still get the correct
+groups assigned on login.
-@c %end of fragment
+Defaults to @samp{disabled}.
-@node Kerberos Services
-@subsubsection Kerberos Services
-@cindex Kerberos
+@end deftypevr
-The @code{(gnu services kerberos)} module provides services relating to
-the authentication protocol @dfn{Kerberos}.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration
+If this option is set, functions which cause all user/group entries to
+be loaded from the directory will not succeed in doing so. This can
+dramatically reduce LDAP server load in situations where there are a
+great number of users and/or groups. This option is not recommended for
+most configurations.
-@subsubheading Krb5 Service
+Defaults to @samp{disabled}.
-Programs using a Kerberos client library normally
-expect a configuration file in @file{/etc/krb5.conf}.
-This service generates such a file from a definition provided in the
-operating system declaration.
-It does not cause any daemon to be started.
+@end deftypevr
-No ``keytab'' files are provided by this service---you must explicitly create them.
-This service is known to work with the MIT client library, @code{mit-krb5}.
-Other implementations have not been tested.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames
+This option can be used to specify how user and group names are verified
+within the system. This pattern is used to check all user and group
+names that are requested and returned from LDAP.
-@defvr {Scheme Variable} krb5-service-type
-A service type for Kerberos 5 clients.
-@end defvr
+Defaults to @samp{disabled}.
-@noindent
-Here is an example of its use:
-@lisp
-(service krb5-service-type
- (krb5-configuration
- (default-realm "EXAMPLE.COM")
- (allow-weak-crypto? #t)
- (realms (list
- (krb5-realm
- (name "EXAMPLE.COM")
- (admin-server "groucho.example.com")
- (kdc "karl.example.com"))
- (krb5-realm
- (name "ARGRX.EDU")
- (admin-server "kerb-admin.argrx.edu")
- (kdc "keys.argrx.edu"))))))
-@end lisp
+@end deftypevr
-@noindent
-This example provides a Kerberos@tie{}5 client configuration which:
-@itemize
-@item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both
-of which have distinct administration servers and key distribution centers;
-@item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly
-specified by clients;
-@item Accepts services which only support encryption types known to be weak.
-@end itemize
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase
+This specifies whether or not to perform searches using case-insensitive
+matching. Enabling this could open up the system to authorization
+bypass vulnerabilities and introduce nscd cache poisoning
+vulnerabilities which allow denial of service.
-The @code{krb5-realm} and @code{krb5-configuration} types have many fields.
-Only the most commonly used ones are described here.
-For a full list, and more detailed explanation of each, see the MIT
-@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
-documentation.
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy
+This option specifies whether password policy controls are requested and
+handled from the LDAP server when performing user authentication.
+Defaults to @samp{disabled}.
-@deftp {Data Type} krb5-realm
-@cindex realm, kerberos
-@table @asis
-@item @code{name}
-This field is a string identifying the name of the realm.
-A common convention is to use the fully qualified DNS name of your organization,
-converted to upper case.
+@end deftypevr
-@item @code{admin-server}
-This field is a string identifying the host where the administration server is
-running.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search
+By default nslcd performs an LDAP search with the user's credentials
+after BIND (authentication) to ensure that the BIND operation was
+successful. The default search is a simple check to see if the user's
+DN exists. A search filter can be specified that will be used instead.
+It should return at least one entry.
-@item @code{kdc}
-This field is a string identifying the key distribution center
-for the realm.
-@end table
-@end deftp
+Defaults to @samp{disabled}.
-@deftp {Data Type} krb5-configuration
+@end deftypevr
-@table @asis
-@item @code{allow-weak-crypto?} (default: @code{#f})
-If this flag is @code{#t} then services which only offer encryption algorithms
-known to be weak will be accepted.
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search
+This option allows flexible fine tuning of the authorisation check that
+should be performed. The search filter specified is executed and if any
+entries match, access is granted, otherwise access is denied.
-@item @code{default-realm} (default: @code{#f})
-This field should be a string identifying the default Kerberos
-realm for the client.
-You should set this field to the name of your Kerberos realm.
-If this value is @code{#f}
-then a realm must be specified with every Kerberos principal when invoking programs
-such as @command{kinit}.
+Defaults to @samp{disabled}.
-@item @code{realms}
-This should be a non-empty list of @code{krb5-realm} objects, which clients may
-access.
-Normally, one of them will have a @code{name} field matching the @code{default-realm}
-field.
-@end table
-@end deftp
+@end deftypevr
+@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message
+If this option is set password modification using pam_ldap will be
+denied and the specified message will be presented to the user instead.
+The message can be used to direct the user to an alternative means of
+changing their password.
-@subsubheading PAM krb5 Service
-@cindex pam-krb5
+Defaults to @samp{disabled}.
-The @code{pam-krb5} service allows for login authentication and password
-management via Kerberos.
-You will need this service if you want PAM enabled applications to authenticate
-users using Kerberos.
+@end deftypevr
-@defvr {Scheme Variable} pam-krb5-service-type
-A service type for the Kerberos 5 PAM module.
-@end defvr
+@deftypevr {@code{nslcd-configuration} parameter} list pam-services
+List of pam service names for which LDAP authentication should suffice.
-@deftp {Data Type} pam-krb5-configuration
-Data type representing the configuration of the Kerberos 5 PAM module
-This type has the following parameters:
-@table @asis
-@item @code{pam-krb5} (default: @code{pam-krb5})
-The pam-krb5 package to use.
+Defaults to @samp{()}.
-@item @code{minimum-uid} (default: @code{1000})
-The smallest user ID for which Kerberos authentications should be attempted.
-Local accounts with lower values will silently fail to authenticate.
-@end table
-@end deftp
+@end deftypevr
+
+@c %end of generated documentation for nslcd-configuration
@node Web Services
-@subsubsection Web Services
+@subsection Web Services
@cindex web
@cindex www
@end quotation
@node Certificate Services
-@subsubsection Certificate Services
+@subsection Certificate Services
@cindex Web
@cindex HTTP, HTTPS
@code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is
saved to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}.
@node DNS Services
-@subsubsection DNS Services
+@subsection DNS Services
@cindex DNS (domain name system)
@cindex domain name system (DNS)
@node VPN Services
-@subsubsection VPN Services
+@subsection VPN Services
@cindex VPN (virtual private network)
@cindex virtual private network (VPN)
@node Network File System
-@subsubsection Network File System
+@subsection Network File System
@cindex NFS
The @code{(gnu services nfs)} module provides the following services,
@end deftp
@node Continuous Integration
-@subsubsection Continuous Integration
+@subsection Continuous Integration
@cindex continuous integration
@uref{https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, Cuirass} is a
@end deftp
@node Power Management Services
-@subsubsection Power Management Services
+@subsection Power Management Services
@cindex tlp
@cindex power management with TLP
@end deftp
@node Audio Services
-@subsubsection Audio Services
+@subsection Audio Services
The @code{(gnu services audio)} module provides a service to start MPD
(the Music Player Daemon).
@item @code{playlist-dir} (default: @code{"~/.mpd/playlists"})
The directory to store playlists.
+@item @code{db-file} (default: @code{"~/.mpd/tag_cache"})
+The location of the music database.
+
+@item @code{state-file} (default: @code{"~/.mpd/state"})
+The location of the file that stores current MPD's state.
+
+@item @code{sticker-file} (default: @code{"~/.mpd/sticker.sql"})
+The location of the sticker database.
+
@item @code{port} (default: @code{"6600"})
The port to run mpd on.
@end deftp
@node Virtualization Services
-@subsubsection Virtualization services
+@subsection Virtualization services
The @code{(gnu services virtualization)} module provides services for
the libvirt and virtlog daemons, as well as other virtualization-related
@example
(service qemu-binfmt-service-type
(qemu-binfmt-configuration
- (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc"))))
+ (platforms (lookup-qemu-platforms "arm" "aarch64" "mips64el"))))
@end example
In this example, we enable transparent emulation for the ARM and aarch64
@end deffn
@node Version Control Services
-@subsubsection Version Control Services
+@subsection Version Control Services
The @code{(gnu services version-control)} module provides a service to
allow remote access to local Git repositories. There are three options:
@node Game Services
-@subsubsection Game Services
+@subsection Game Services
@subsubheading The Battle for Wesnoth Service
@cindex wesnothd
@end deftp
@node Miscellaneous Services
-@subsubsection Miscellaneous Services
+@subsection Miscellaneous Services
@cindex fingerprint
@subsubheading Fingerprint Service
resolution when the graphical console window resizes.
@end deffn
-@subsubsection Dictionary Services
+@cindex inputattach
+@subsubheading inputattach Service
+
+@cindex tablet input, for Xorg
+@cindex touchscreen input, for Xorg
+The @uref{https://linuxwacom.github.io/, inputattach} service allows you to
+use input devices such as Wacom tablets, touchscreens, or joysticks with the
+Xorg display server.
+
+@deffn {Scheme Variable} inputattach-service-type
+Type of a service that runs @command{inputattach} on a device and
+dispatches events from it.
+@end deffn
+
+@deftp {Data Type} inputattach-configuration
+@table @asis
+@item @code{device-type} (default: @code{"wacom"})
+The type of device to connect to. Run @command{inputattach --help}, from the
+@code{inputattach} package, to see the list of supported device types.
+
+@item @code{device} (default: @code{"/dev/ttyS0"})
+The device file to connect to the device.
+
+@item @code{log-file} (default: @code{#f})
+If true, this must be the name of a file to log messages to.
+@end table
+@end deftp
+
+@subsection Dictionary Services
@cindex dictionary
The @code{(gnu services dict)} module provides the following service:
@end deftp
@node Setuid Programs
-@subsection Setuid Programs
+@section Setuid Programs
@cindex setuid programs
Some programs need to run with ``root'' privileges, even when they are
store.
@node X.509 Certificates
-@subsection X.509 Certificates
+@section X.509 Certificates
@cindex HTTPS, certificates
@cindex X.509 certificates
certificates can be found.
@cindex @code{nss-certs}
-In GuixSD, this is done by adding a package that provides certificates
+In Guix, this is done by adding a package that provides certificates
to the @code{packages} field of the @code{operating-system} declaration
-(@pxref{operating-system Reference}). GuixSD includes one such package,
+(@pxref{operating-system Reference}). Guix includes one such package,
@code{nss-certs}, which is a set of CA certificates provided as part of
Mozilla's Network Security Services.
@node Name Service Switch
-@subsection Name Service Switch
+@section Name Service Switch
@cindex name service switch
@cindex NSS
Note that, in this case, in addition to setting the
@code{name-service-switch} of the @code{operating-system} declaration,
-you also need to use @code{avahi-service} (@pxref{Networking Services,
-@code{avahi-service}}), or @var{%desktop-services}, which includes it
+you also need to use @code{avahi-service-type} (@pxref{Networking Services,
+@code{avahi-service-type}}), or @var{%desktop-services}, which includes it
(@pxref{Desktop Services}). Doing this makes @code{nss-mdns} accessible
to the name service cache daemon (@pxref{Base Services,
@code{nscd-service}}).
@end deftp
@node Initial RAM Disk
-@subsection Initial RAM Disk
+@section Initial RAM Disk
@cindex initrd
@cindex initial RAM disk
Tell the initial RAM disk to load @var{boot}, a file containing a Scheme
program, once it has mounted the root file system.
-GuixSD uses this option to yield control to a boot program that runs the
+Guix uses this option to yield control to a boot program that runs the
service activation programs and then spawns the GNU@tie{}Shepherd, the
initialization system.
@cindex initial RAM disk
@deffn {Scheme Procedure} raw-initrd @var{file-systems} @
[#:linux-modules '()] [#:mapped-devices '()] @
+ [#:keyboard-layout #f] @
[#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f]
Return a derivation that builds a raw initrd. @var{file-systems} is
a list of file systems to be mounted by the initrd, possibly in addition to
include @code{e2fsck/static} or other packages needed by the initrd to check
the root file system.
+When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
+the desired console keyboard layout. This is done before @var{mapped-devices}
+are set up and before @var{file-systems} are mounted such that, should the
+user need to enter a passphrase or use the REPL, this happens using the
+intended keyboard layout.
+
When @var{qemu-networking?} is true, set up networking with the standard QEMU
parameters. When @var{virtio?} is true, load additional modules so that the
initrd can be used as a QEMU guest with para-virtualized I/O drivers.
@end deffn
@deffn {Scheme Procedure} base-initrd @var{file-systems} @
- [#:mapped-devices '()] [#:qemu-networking? #f] [#:volatile-root? #f]@
+ [#:mapped-devices '()] [#:keyboard-layout #f] @
+ [#:qemu-networking? #f] [#:volatile-root? #f] @
[#:linux-modules '()]
Return as a file-like object a generic initrd, with kernel
modules taken from @var{linux}. @var{file-systems} is a list of file-systems to be
on the kernel command line via @code{--root}. @var{mapped-devices} is a list of device
mappings to realize before @var{file-systems} are mounted.
+When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
+the desired console keyboard layout. This is done before @var{mapped-devices}
+are set up and before @var{file-systems} are mounted such that, should the
+user need to enter a passphrase or use the REPL, this happens using the
+intended keyboard layout.
+
@var{qemu-networking?} and @var{volatile-root?} behaves as in @code{raw-initrd}.
The initrd is automatically populated with all the kernel modules necessary
@end deffn
@node Bootloader Configuration
-@subsection Bootloader Configuration
+@section Bootloader Configuration
@cindex bootloader
@cindex boot loader
The number of seconds to wait for keyboard input before booting. Set to
0 to boot immediately, and to -1 to wait indefinitely.
+@cindex keyboard layout, for the bootloader
+@item @code{keyboard-layout} (default: @code{#f})
+If this is @code{#f}, the bootloader's menu (if any) uses the default keyboard
+layout, usually US@tie{}English (``qwerty'').
+
+Otherwise, this must be a @code{keyboard-layout} object. For instance, the
+following example defines a standard German keyboard layout:
+
+@example
+(keyboard-layout "de")
+@end example
+
+@noindent
+while the example below designates the bépo layout for French:
+
+@example
+(keyboard-layout "fr" "bepo")
+@end example
+
+The layout name and variant must match an existing layout in the
+@code{xkeyboard-config} package under the @file{share/X11/xkb/symbols}
+directory.
+
+@quotation Note
+This option is currently ignored by bootloaders other than @code{grub} and
+@code{grub-efi}.
+@end quotation
+
@item @code{theme} (default: @var{#f})
The bootloader theme object describing the theme to use. If no theme
is provided, some bootloaders might use a default theme, that's true
@node Invoking guix system
-@subsection Invoking @code{guix system}
+@section Invoking @code{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
Build the operating system described in @var{file}, activate it, and
switch to it@footnote{This action (and the related actions
@code{switch-generation} and @code{roll-back}) are usable only on
-systems already running GuixSD.}.
+systems already running Guix System.}.
This effects all the configuration specified in @var{file}: user
accounts, system services, global package list, setuid programs, etc.
running this action to actually start using the preceding system
generation.
+@item delete-generations
+@cindex deleting system generations
+@cindex saving space
+Delete system generations, making them candidates for garbage collection
+(@pxref{Invoking guix gc}, for information on how to run the ``garbage
+collector'').
+
+This works in the same way as @command{guix package --delete-generations}
+(@pxref{Invoking guix package, @code{--delete-generations}}). With no
+arguments, all system generations but the current one are deleted:
+
+@example
+guix system delete-generations
+@end example
+
+You can also select the generations you want to delete. The example below
+deletes all the system generations that are more than two month old:
+
+@example
+guix system delete-generations 2m
+@end example
+
+Running this command automatically reinstalls the bootloader with an updated
+list of menu entries---e.g., the ``old generations'' sub-menu in GRUB no
+longer lists the generations that have been deleted.
+
@item build
Build the derivation of the operating system, which includes all the
configuration files and programs needed to boot and run the system.
@item init
Populate the given directory with all the files necessary to run the
operating system specified in @var{file}. This is useful for first-time
-installations of GuixSD. For instance:
+installations of Guix System. For instance:
@example
guix system init my-os-config.scm /mnt
@anchor{guix system vm}
Build a virtual machine that contains the operating system declared in
@var{file}, and return a script to run that virtual machine (VM).
+
+@quotation Note
+The @code{vm} action and others below
+can use KVM support in the Linux-libre kernel. Specifically, if the
+machine has hardware virtualization support, the corresponding
+KVM kernel module should be loaded, and the @file{/dev/kvm} device node
+must exist and be readable and writable by the user and by the
+build users of the daemon (@pxref{Build Environment Setup}).
+@end quotation
+
Arguments given to the script are passed to QEMU as in the example
below, which enables networking and requests 1@tie{}GiB of RAM for the
emulated machine:
@option{--file-system-type} option. It defaults to @code{ext4}.
When using @code{vm-image}, the returned image is in qcow2 format, which
-the QEMU emulator can efficiently use. @xref{Running GuixSD in a VM},
+the QEMU emulator can efficiently use. @xref{Running Guix in a VM},
for more information on how to run the image in a virtual machine.
When using @code{disk-image}, a raw disk image is produced; it can be
Docker container using commands like the following:
@example
-image_id="$(docker load < guixsd-docker-image.tar.gz)"
+image_id="$(docker load < guix-system-docker-image.tar.gz)"
docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\
--entrypoint /var/guix/profiles/system/profile/bin/guile \\
$image_id /var/guix/profiles/system/boot
@end example
This command starts a new Docker container from the specified image. It
-will boot the GuixSD system in the usual manner, which means it will
+will boot the Guix system in the usual manner, which means it will
start any services you have defined in the operating system
configuration. Depending on what you run in the Docker container, it
may be necessary to give the container additional permissions. For
Consider the operating-system @var{expr} evaluates to.
This is an alternative to specifying a file which evaluates to an
operating system.
-This is used to generate the GuixSD installer @pxref{Building the
+This is used to generate the Guix system installer @pxref{Building the
Installation Image}).
@item --system=@var{system}
@end table
@end table
-@quotation Note
-All the actions above, except @code{build} and @code{init},
-can use KVM support in the Linux-libre kernel. Specifically, if the
-machine has hardware virtualization support, the corresponding
-KVM kernel module should be loaded, and the @file{/dev/kvm} device node
-must exist and be readable and writable by the user and by the
-build users of the daemon (@pxref{Build Environment Setup}).
-@end quotation
-
Once you have built, configured, re-configured, and re-re-configured
-your GuixSD installation, you may find it useful to list the operating
+your Guix installation, you may find it useful to list the operating
system generations available on disk---and that you can choose from the
bootloader boot menu:
@end table
-@node Running GuixSD in a VM
-@subsection Running GuixSD in a Virtual Machine
+@node Running Guix in a VM
+@section Running Guix in a Virtual Machine
@cindex virtual machine
-To run GuixSD in a virtual machine (VM), one can either use the
-pre-built GuixSD VM image distributed at
-@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-vm-image-@value{VERSION}.@var{system}.xz}
+To run Guix in a virtual machine (VM), one can either use the
+pre-built Guix VM image distributed at
+@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-vm-image-@value{VERSION}.@var{system}.xz}
, or build their own virtual machine image using @command{guix system
vm-image} (@pxref{Invoking guix system}). The returned image is in
qcow2 format, which the @uref{http://qemu.org/, QEMU emulator} can
it uses the ICMP protocol. You'll have to use a different command to check for
network connectivity, for example @command{guix download}.
-@subsubsection Connecting Through SSH
+@subsection Connecting Through SSH
@cindex SSH
@cindex SSH server
@command{-o StrictHostKeyChecking=no} prevents you from having to allow a
connection to an unknown host every time you connect.
-@subsubsection Using @command{virt-viewer} with Spice
+@subsection Using @command{virt-viewer} with Spice
As an alternative to the default @command{qemu} graphical client you can
use the @command{remote-viewer} from the @command{virt-viewer} package. To
You'll also need to add the @pxref{Miscellaneous Services, Spice service}.
@node Defining Services
-@subsection Defining Services
+@section Defining Services
The previous sections show the available services and how one can combine
them in an @code{operating-system} declaration. But how do we define
@end menu
@node Service Composition
-@subsubsection Service Composition
+@subsection Service Composition
@cindex services
@cindex daemons
of the system.
@cindex service extensions
-GuixSD services are connected by @dfn{extensions}. For instance, the
-secure shell service @emph{extends} the Shepherd---the GuixSD
+Guix system services are connected by @dfn{extensions}. For instance, the
+secure shell service @emph{extends} the Shepherd---the
initialization system, running as PID@tie{}1---by giving it the command
lines to start and stop the secure shell daemon (@pxref{Networking
-Services, @code{lsh-service}}); the UPower service extends the D-Bus
+Services, @code{openssh-service-type}}); the UPower service extends the D-Bus
service by passing it its @file{.service} specification, and extends the
udev service by passing it device management rules (@pxref{Desktop
Services, @code{upower-service}}); the Guix daemon service extends the
Technically, developers can define @dfn{service types} to express these
relations. There can be any number of services of a given type on the
system---for instance, a system running two instances of the GNU secure
-shell server (lsh) has two instances of @var{lsh-service-type}, with
+shell server (lsh) has two instances of @code{lsh-service-type}, with
different parameters.
The following section describes the programming interface for service
types and services.
@node Service Types and Services
-@subsubsection Service Types and Services
+@subsection Service Types and Services
A @dfn{service type} is a node in the DAG described above. Let us start
with a simple example, the service type for the Guix build daemon
interface for services.
@node Service Reference
-@subsubsection Service Reference
+@subsection Service Reference
We have seen an overview of service types (@pxref{Service Types and
Services}). This section provides a reference on how to manipulate
@node Shepherd Services
-@subsubsection Shepherd Services
+@subsection Shepherd Services
@cindex shepherd services
@cindex PID 1
@cindex init system
The @code{(gnu services shepherd)} module provides a way to define
-services managed by the GNU@tie{}Shepherd, which is the GuixSD
+services managed by the GNU@tie{}Shepherd, which is the
initialization system---the first process that is started when the
system boots, also known as PID@tie{}1
(@pxref{Introduction,,, shepherd, The GNU Shepherd Manual}).
@node Documentation
-@section Documentation
+@chapter Documentation
@cindex documentation, searching for
@cindex searching for documentation
Introduction}, for an introduction to Info navigation.
@node Installing Debugging Files
-@section Installing Debugging Files
+@chapter Installing Debugging Files
@cindex debugging files
Program binaries, as produced by the GCC compilers for instance, are
@node Security Updates
-@section Security Updates
+@chapter Security Updates
@cindex security updates
@cindex security vulnerabilities
@noindent
@dots{} and compare the store file names that you get with those above.
-Likewise for a complete GuixSD system generation:
+Likewise for a complete Guix system generation:
@example
guix gc -R `guix system build my-config.scm` | grep bash
@end example
-@node Package Modules
-@section Package Modules
-
-From a programming viewpoint, the package definitions of the
-GNU distribution are provided by Guile modules in the @code{(gnu packages
-@dots{})} name space@footnote{Note that packages under the @code{(gnu
-packages @dots{})} module name space are not necessarily ``GNU
-packages''. This module naming scheme follows the usual Guile module
-naming convention: @code{gnu} means that these modules are distributed
-as part of the GNU system, and @code{packages} identifies modules that
-define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
-Reference Manual}). For instance, the @code{(gnu packages emacs)}
-module exports a variable named @code{emacs}, which is bound to a
-@code{<package>} object (@pxref{Defining Packages}).
-
-The @code{(gnu packages @dots{})} module name space is
-automatically scanned for packages by the command-line tools. For
-instance, when running @code{guix package -i emacs}, all the @code{(gnu
-packages @dots{})} modules are scanned until one that exports a package
-object whose name is @code{emacs} is found. This package search
-facility is implemented in the @code{(gnu packages)} module.
-
-@cindex customization, of packages
-@cindex package module search path
-Users can store package definitions in modules with different
-names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
-name and module name must match. For instance, the @code{(my-packages
-emacs)} module must be stored in a @file{my-packages/emacs.scm} file
-relative to the load path specified with @option{--load-path} or
-@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
-guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
-these package definitions visible to the user interfaces:
-
-@enumerate
-@item
-By adding the directory containing your package modules to the search path
-with the @code{-L} flag of @command{guix package} and other commands
-(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH}
-environment variable described below.
-
-@item
-By defining a @dfn{channel} and configuring @command{guix pull} so that it
-pulls from it. A channel is essentially a Git repository containing package
-modules. @xref{Channels}, for more information on how to define and use
-channels.
-@end enumerate
-
-@code{GUIX_PACKAGE_PATH} works similarly to other search path variables:
-
-@defvr {Environment Variable} GUIX_PACKAGE_PATH
-This is a colon-separated list of directories to search for additional
-package modules. Directories listed in this variable take precedence
-over the own modules of the distribution.
-@end defvr
-
-The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
-each package is built based solely on other packages in the
-distribution. The root of this dependency graph is a small set of
-@dfn{bootstrap binaries}, provided by the @code{(gnu packages
-bootstrap)} module. For more information on bootstrapping,
-@pxref{Bootstrapping}.
-
-@node Packaging Guidelines
-@section Packaging Guidelines
-
-@cindex packages, creating
-The GNU distribution is nascent and may well lack some of your favorite
-packages. This section describes how you can help make the distribution
-grow. @xref{Contributing}, for additional information on how you can
-help.
-
-Free software packages are usually distributed in the form of
-@dfn{source code tarballs}---typically @file{tar.gz} files that contain
-all the source files. Adding a package to the distribution means
-essentially two things: adding a @dfn{recipe} that describes how to
-build the package, including a list of other packages required to build
-it, and adding @dfn{package metadata} along with that recipe, such as a
-description and licensing information.
-
-In Guix all this information is embodied in @dfn{package definitions}.
-Package definitions provide a high-level view of the package. They are
-written using the syntax of the Scheme programming language; in fact,
-for each package we define a variable bound to the package definition,
-and export that variable from a module (@pxref{Package Modules}).
-However, in-depth Scheme knowledge is @emph{not} a prerequisite for
-creating packages. For more information on package definitions,
-@pxref{Defining Packages}.
-
-Once a package definition is in place, stored in a file in the Guix
-source tree, it can be tested using the @command{guix build} command
-(@pxref{Invoking guix build}). For example, assuming the new package is
-called @code{gnew}, you may run this command from the Guix build tree
-(@pxref{Running Guix Before It Is Installed}):
-
-@example
-./pre-inst-env guix build gnew --keep-failed
-@end example
-
-Using @code{--keep-failed} makes it easier to debug build failures since
-it provides access to the failed build tree. Another useful
-command-line option when debugging is @code{--log-file}, to access the
-build log.
-
-If the package is unknown to the @command{guix} command, it may be that
-the source file contains a syntax error, or lacks a @code{define-public}
-clause to export the package variable. To figure it out, you may load
-the module from Guile to get more information about the actual error:
-
-@example
-./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
-@end example
-
-Once your package builds correctly, please send us a patch
-(@pxref{Contributing}). Well, if you need help, we will be happy to
-help you too. Once the patch is committed in the Guix repository, the
-new package automatically gets built on the supported platforms by
-@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
-system}.
-
-@cindex substituter
-Users can obtain the new package definition simply by running
-@command{guix pull} (@pxref{Invoking guix pull}). When
-@code{@value{SUBSTITUTE-SERVER}} is done building the package, installing the
-package automatically downloads binaries from there
-(@pxref{Substitutes}). The only place where human intervention is
-needed is to review and apply the patch.
-
-
-@menu
-* Software Freedom:: What may go into the distribution.
-* Package Naming:: What's in a name?
-* Version Numbers:: When the name is not enough.
-* Synopses and Descriptions:: Helping users find the right package.
-* Python Modules:: A touch of British comedy.
-* Perl Modules:: Little pearls.
-* Java Packages:: Coffee break.
-* Fonts:: Fond of fonts.
-@end menu
-
-@node Software Freedom
-@subsection Software Freedom
-
-@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
-@cindex free software
-The GNU operating system has been developed so that users can have
-freedom in their computing. GNU is @dfn{free software}, meaning that
-users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
-essential freedoms}: to run the program, to study and change the program
-in source code form, to redistribute exact copies, and to distribute
-modified versions. Packages found in the GNU distribution provide only
-software that conveys these four freedoms.
-
-In addition, the GNU distribution follow the
-@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
-software distribution guidelines}. Among other things, these guidelines
-reject non-free firmware, recommendations of non-free software, and
-discuss ways to deal with trademarks and patents.
-
-Some otherwise free upstream package sources contain a small and optional
-subset that violates the above guidelines, for instance because this subset
-is itself non-free code. When that happens, the offending items are removed
-with appropriate patches or code snippets in the @code{origin} form of the
-package (@pxref{Defining Packages}). This way, @code{guix
-build --source} returns the ``freed'' source rather than the unmodified
-upstream source.
-
-
-@node Package Naming
-@subsection Package Naming
-
-@cindex package name
-A package has actually two names associated with it:
-First, there is the name of the @emph{Scheme variable}, the one following
-@code{define-public}. By this name, the package can be made known in the
-Scheme code, for instance as input to another package. Second, there is
-the string in the @code{name} field of a package definition. This name
-is used by package management commands such as
-@command{guix package} and @command{guix build}.
-
-Both are usually the same and correspond to the lowercase conversion of
-the project name chosen upstream, with underscores replaced with
-hyphens. For instance, GNUnet is available as @code{gnunet}, and
-SDL_net as @code{sdl-net}.
-
-We do not add @code{lib} prefixes for library packages, unless these are
-already part of the official project name. But @pxref{Python
-Modules} and @ref{Perl Modules} for special rules concerning modules for
-the Python and Perl languages.
-
-Font package names are handled differently, @pxref{Fonts}.
-
-
-@node Version Numbers
-@subsection Version Numbers
-
-@cindex package version
-We usually package only the latest version of a given free software
-project. But sometimes, for instance for incompatible library versions,
-two (or more) versions of the same package are needed. These require
-different Scheme variable names. We use the name as defined
-in @ref{Package Naming}
-for the most recent version; previous versions use the same name, suffixed
-by @code{-} and the smallest prefix of the version number that may
-distinguish the two versions.
-
-The name inside the package definition is the same for all versions of a
-package and does not contain any version number.
-
-For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
-
-@example
-(define-public gtk+
- (package
- (name "gtk+")
- (version "3.9.12")
- ...))
-(define-public gtk+-2
- (package
- (name "gtk+")
- (version "2.24.20")
- ...))
-@end example
-If we also wanted GTK+ 3.8.2, this would be packaged as
-@example
-(define-public gtk+-3.8
- (package
- (name "gtk+")
- (version "3.8.2")
- ...))
-@end example
-
-@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
-@c for a discussion of what follows.
-@cindex version number, for VCS snapshots
-Occasionally, we package snapshots of upstream's version control system
-(VCS) instead of formal releases. This should remain exceptional,
-because it is up to upstream developers to clarify what the stable
-release is. Yet, it is sometimes necessary. So, what should we put in
-the @code{version} field?
-
-Clearly, we need to make the commit identifier of the VCS snapshot
-visible in the version string, but we also need to make sure that the
-version string is monotonically increasing so that @command{guix package
---upgrade} can determine which version is newer. Since commit
-identifiers, notably with Git, are not monotonically increasing, we add
-a revision number that we increase each time we upgrade to a newer
-snapshot. The resulting version string looks like this:
-
-@example
-2.0.11-3.cabba9e
- ^ ^ ^
- | | `-- upstream commit ID
- | |
- | `--- Guix package revision
- |
-latest upstream version
-@end example
-
-It is a good idea to strip commit identifiers in the @code{version}
-field to, say, 7 digits. It avoids an aesthetic annoyance (assuming
-aesthetics have a role to play here) as well as problems related to OS
-limits such as the maximum shebang length (127 bytes for the Linux
-kernel.) It is best to use the full commit identifiers in
-@code{origin}s, though, to avoid ambiguities. A typical package
-definition may look like this:
-
-@example
-(define my-package
- (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
- (revision "1")) ;Guix package revision
- (package
- (version (git-version "0.9" revision commit))
- (source (origin
- (method git-fetch)
- (uri (git-reference
- (url "git://example.org/my-package.git")
- (commit commit)))
- (sha256 (base32 "1mbikn@dots{}"))
- (file-name (git-file-name name version))))
- ;; @dots{}
- )))
-@end example
-
-@node Synopses and Descriptions
-@subsection Synopses and Descriptions
-
-@cindex package description
-@cindex package synopsis
-As we have seen before, each package in GNU@tie{}Guix includes a
-synopsis and a description (@pxref{Defining Packages}). Synopses and
-descriptions are important: They are what @command{guix package
---search} searches, and a crucial piece of information to help users
-determine whether a given package suits their needs. Consequently,
-packagers should pay attention to what goes into them.
-
-Synopses must start with a capital letter and must not end with a
-period. They must not start with ``a'' or ``the'', which usually does
-not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
-tool that frobs files''. The synopsis should say what the package
-is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
-used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
-matching a pattern''.
-
-Keep in mind that the synopsis must be meaningful for a very wide
-audience. For example, ``Manipulate alignments in the SAM format''
-might make sense for a seasoned bioinformatics researcher, but might be
-fairly unhelpful or even misleading to a non-specialized audience. It
-is a good idea to come up with a synopsis that gives an idea of the
-application domain of the package. In this example, this might give
-something like ``Manipulate nucleotide sequence alignments'', which
-hopefully gives the user a better idea of whether this is what they are
-looking for.
-
-Descriptions should take between five and ten lines. Use full
-sentences, and avoid using acronyms without first introducing them.
-Please avoid marketing phrases such as ``world-leading'',
-``industrial-strength'', and ``next-generation'', and avoid superlatives
-like ``the most advanced''---they are not helpful to users looking for a
-package and may even sound suspicious. Instead, try to be factual,
-mentioning use cases and features.
-
-@cindex Texinfo markup, in package descriptions
-Descriptions can include Texinfo markup, which is useful to introduce
-ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
-hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
-should be careful when using some characters for example @samp{@@} and
-curly braces which are the basic special characters in Texinfo
-(@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
-such as @command{guix package --show} take care of rendering it
-appropriately.
-
-Synopses and descriptions are translated by volunteers
-@uref{http://translationproject.org/domain/guix-packages.html, at the
-Translation Project} so that as many users as possible can read them in
-their native language. User interfaces search them and display them in
-the language specified by the current locale.
-
-To allow @command{xgettext} to extract them as translatable strings,
-synopses and descriptions @emph{must be literal strings}. This means
-that you cannot use @code{string-append} or @code{format} to construct
-these strings:
-
-@lisp
-(package
- ;; @dots{}
- (synopsis "This is translatable")
- (description (string-append "This is " "*not*" " translatable.")))
-@end lisp
-
-Translation is a lot of work so, as a packager, please pay even more
-attention to your synopses and descriptions as every change may entail
-additional work for translators. In order to help them, it is possible
-to make recommendations or instructions visible to them by inserting
-special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
-Gettext}):
-
-@example
-;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
-(description "ARandR is designed to provide a simple visual front end
-for the X11 resize-and-rotate (RandR) extension. @dots{}")
-@end example
-
-
-@node Python Modules
-@subsection Python Modules
-
-@cindex python
-We currently package Python 2 and Python 3, under the Scheme variable names
-@code{python-2} and @code{python} as explained in @ref{Version Numbers}.
-To avoid confusion and naming clashes with other programming languages, it
-seems desirable that the name of a package for a Python module contains
-the word @code{python}.
-
-Some modules are compatible with only one version of Python, others with both.
-If the package Foo compiles only with Python 3, we name it
-@code{python-foo}; if it compiles only with Python 2, we name it
-@code{python2-foo}. If it is compatible with both versions, we create two
-packages with the corresponding names.
-
-If a project already contains the word @code{python}, we drop this;
-for instance, the module python-dateutil is packaged under the names
-@code{python-dateutil} and @code{python2-dateutil}. If the project name
-starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
-described above.
-
-@subsubsection Specifying Dependencies
-@cindex inputs, for Python packages
-
-Dependency information for Python packages is usually available in the
-package source tree, with varying degrees of accuracy: in the
-@file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
-
-Your mission, when writing a recipe for a Python package, is to map
-these dependencies to the appropriate type of ``input'' (@pxref{package
-Reference, inputs}). Although the @code{pypi} importer normally does a
-good job (@pxref{Invoking guix import}), you may want to check the
-following check list to determine which dependency goes where.
-
-@itemize
-
-@item
-We currently package Python 2 with @code{setuptools} and @code{pip}
-installed like Python 3.4 has per default. Thus you don't need to
-specify either of these as an input. @command{guix lint} will warn you
-if you do.
-
-@item
-Python dependencies required at run time go into
-@code{propagated-inputs}. They are typically defined with the
-@code{install_requires} keyword in @file{setup.py}, or in the
-@file{requirements.txt} file.
-
-@item
-Python packages required only at build time---e.g., those listed with
-the @code{setup_requires} keyword in @file{setup.py}---or only for
-testing---e.g., those in @code{tests_require}---go into
-@code{native-inputs}. The rationale is that (1) they do not need to be
-propagated because they are not needed at run time, and (2) in a
-cross-compilation context, it's the ``native'' input that we'd want.
-
-Examples are the @code{pytest}, @code{mock}, and @code{nose} test
-frameworks. Of course if any of these packages is also required at
-run-time, it needs to go to @code{propagated-inputs}.
-
-@item
-Anything that does not fall in the previous categories goes to
-@code{inputs}, for example programs or C libraries required for building
-Python packages containing C extensions.
-
-@item
-If a Python package has optional dependencies (@code{extras_require}),
-it is up to you to decide whether to add them or not, based on their
-usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
-size}}).
-
-@end itemize
-
-
-@node Perl Modules
-@subsection Perl Modules
-
-@cindex perl
-Perl programs standing for themselves are named as any other package,
-using the lowercase upstream name.
-For Perl packages containing a single class, we use the lowercase class name,
-replace all occurrences of @code{::} by dashes and prepend the prefix
-@code{perl-}.
-So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
-Modules containing several classes keep their lowercase upstream name and
-are also prepended by @code{perl-}. Such modules tend to have the word
-@code{perl} somewhere in their name, which gets dropped in favor of the
-prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
-
-
-@node Java Packages
-@subsection Java Packages
-
-@cindex java
-Java programs standing for themselves are named as any other package,
-using the lowercase upstream name.
-
-To avoid confusion and naming clashes with other programming languages,
-it is desirable that the name of a package for a Java package is
-prefixed with @code{java-}. If a project already contains the word
-@code{java}, we drop this; for instance, the package @code{ngsjava} is
-packaged under the name @code{java-ngs}.
-
-For Java packages containing a single class or a small class hierarchy,
-we use the lowercase class name, replace all occurrences of @code{.} by
-dashes and prepend the prefix @code{java-}. So the class
-@code{apache.commons.cli} becomes package
-@code{java-apache-commons-cli}.
-
-
-@node Fonts
-@subsection Fonts
-
-@cindex fonts
-For fonts that are in general not installed by a user for typesetting
-purposes, or that are distributed as part of a larger software package,
-we rely on the general packaging rules for software; for instance, this
-applies to the fonts delivered as part of the X.Org system or fonts that
-are part of TeX Live.
-
-To make it easier for a user to search for fonts, names for other packages
-containing only fonts are constructed as follows, independently of the
-upstream package name.
-
-The name of a package containing only one font family starts with
-@code{font-}; it is followed by the foundry name and a dash @code{-}
-if the foundry is known, and the font family name, in which spaces are
-replaced by dashes (and as usual, all upper case letters are transformed
-to lower case).
-For example, the Gentium font family by SIL is packaged under the name
-@code{font-sil-gentium}.
-
-For a package containing several font families, the name of the collection
-is used in the place of the font family name.
-For instance, the Liberation fonts consist of three families,
-Liberation Sans, Liberation Serif and Liberation Mono.
-These could be packaged separately under the names
-@code{font-liberation-sans} and so on; but as they are distributed together
-under a common name, we prefer to package them together as
-@code{font-liberation}.
-
-In the case where several formats of the same font family or font collection
-are packaged separately, a short form of the format, prepended by a dash,
-is added to the package name. We use @code{-ttf} for TrueType fonts,
-@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
-fonts.
-
-
-
@node Bootstrapping
-@section Bootstrapping
+@chapter Bootstrapping
@c Adapted from the ELS 2013 paper.
These bootstrap binaries are ``taken for granted'', though we can also
re-create them if needed (more on that later).
-@unnumberedsubsec Preparing to Use the Bootstrap Binaries
+@unnumberedsec Preparing to Use the Bootstrap Binaries
@c As of Emacs 24.3, Info-mode displays the image, but since it's a
@c large image, it's hard to scroll. Oh well.
etc., at which point we have a working C tool chain.
-@unnumberedsubsec Building the Build Tools
+@unnumberedsec Building the Build Tools
Bootstrapping is complete when we have a full tool chain that does not
depend on the pre-built bootstrap tools discussed above. This
(@pxref{Build Systems, @code{gnu-build-system}}).
-@unnumberedsubsec Building the Bootstrap Binaries
+@unnumberedsec Building the Bootstrap Binaries
@cindex bootstrap binaries
Because the final tool chain does not depend on the bootstrap binaries,
significant computational and storage resources to do so), then let us
know.
-@unnumberedsubsec Reducing the Set of Bootstrap Binaries
+@unnumberedsec Reducing the Set of Bootstrap Binaries
Our bootstrap binaries currently include GCC, Guile, etc. That's a lot
of binary code! Why is that a problem? It's a problem because these
@node Porting
-@section Porting to a New Platform
+@chapter Porting to a New Platform
As discussed above, the GNU distribution is self-contained, and
self-containment is achieved by relying on pre-built ``bootstrap
HCoop / jackhill / guix / guix.git / blobdiff