@set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER}
@copying
-Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Courtès@*
+Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
Copyright @copyright{} 2013 Nikita Karetnikov@*
Copyright @copyright{} 2014, 2015, 2016 Alex Kost@*
Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2016, 2017, 2018, 2019 Christopher Baines@*
Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@*
-Copyright @copyright{} 2017, 2018, 2020 Mathieu Othacehe@*
+Copyright @copyright{} 2017, 2018, 2020, 2021 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017, 2018, 2019, 2020 Arun Isaac@*
Copyright @copyright{} 2017 nee@*
Copyright @copyright{} 2018 Rutger Helling@*
-Copyright @copyright{} 2018 Oleg Pykhalov@*
+Copyright @copyright{} 2018, 2021 Oleg Pykhalov@*
Copyright @copyright{} 2018 Mike Gerwitz@*
Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
Copyright @copyright{} 2018, 2019 Gábor Boskovits@*
Copyright @copyright{} 2020 André Batista@*
Copyright @copyright{} 2020 Alexandru-Sergiu Marton@*
Copyright @copyright{} 2020 raingloom@*
+Copyright @copyright{} 2020 Daniel Brooks@*
+Copyright @copyright{} 2020 John Soo@*
+Copyright @copyright{} 2020 Jonathan Brielmaier@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@dircategory Software development
@direntry
-* guix environment: (guix)Invoking guix environment. Building development environments with Guix.
+* guix environment: (guix)Invoking guix environment. Building development environments with Guix.
* guix build: (guix)Invoking guix build. Building packages.
* guix pack: (guix)Invoking guix pack. Creating binary bundles.
@end direntry
Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}),
Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), and
Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you
-would like to translate it in your native language, consider joining the
-@uref{https://translationproject.org/domain/guix-manual.html, Translation
-Project}.
+would like to translate it in your native language, consider joining
+@uref{https://translate.fedoraproject.org/projects/guix/documentation-manual,
+Weblate}.
@menu
* Introduction:: What is Guix about?
* Specifying Channel Authorizations:: Defining channel authors authorizations.
* Primary URL:: Distinguishing mirror to original.
* Writing Channel News:: Communicating information to channel's users.
+* Channels with Substitutes:: Using channels with available substitutes.
Development
@cindex user interfaces
Guix provides a command-line package management interface
(@pxref{Package Management}), tools to help with software development
-(@pxref{Development}), command-line utilities for more advanced usage,
+(@pxref{Development}), command-line utilities for more advanced usage
(@pxref{Utilities}), as well as Scheme programming interfaces
(@pxref{Programming Interface}).
@cindex build daemon
little-endian 64-bit MIPS processors, specifically the Loongson series,
n32 ABI, and Linux-Libre kernel. This configuration is no longer fully
supported; in particular, there is no ongoing work to ensure that this
-architecture still works. Should someone decide they wish to revive this
+architecture still works. Should someone decide they wish to revive this
architecture then the code is still available.
@end table
or later;
@item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib};
@item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
+@item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
@item
@c FIXME: Specify a version number once a release has been made.
@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.3.0
version 0.13.0 or later.
@item
-When @url{https://www.nongnu.org/lzip/lzlib.html, lzlib} is available, lzlib
-substitutes can be used and @command{guix publish} can compress substitutes
-with lzlib.
+@uref{https://notabug.org/guile-zstd/guile-zstd, Guile-zstd}, for zstd
+compression and decompression in @command{guix publish} and for
+substitutes (@pxref{Invoking guix publish}).
+
+@item
+@uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for
+the @code{crate} importer (@pxref{Invoking guix import}).
@item
When @url{http://www.bzip.org, libbz2} is available,
make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
@end example
+The underlying SRFI 64 custom Automake test driver used for the 'check'
+test suite (located at @file{build-aux/test-driver.scm}) also allows
+selecting which test cases to run at a finer level, via its
+@option{--select} and @option{--exclude} options. Here's an example, to
+run all the test cases from the @file{tests/packages.scm} test file
+whose names start with ``transaction-upgrade-entry'':
+
+@example
+export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry"
+make check TESTS="tests/packages.scm"
+@end example
+
+Those wishing to inspect the results of failed tests directly from the
+command line can add the @option{--errors-only=yes} option to the
+@code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE}
+Automake makefile variable, as in:
+
+@example
+make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1
+@end example
+
+@xref{Parallel Test Harness,,,automake,GNU Automake} for more
+information about the Automake Parallel Test Harness.
+
Upon failure, please email @email{bug-guix@@gnu.org} and attach the
@file{test-suite.log} file. Please specify the Guix version being used
as well as version numbers of the dependencies (@pxref{Requirements}) in
@end example
This will attempt to connect to each of the build machines specified in
-@file{/etc/guix/machines.scm}, make sure Guile and the Guix modules are
+@file{/etc/guix/machines.scm}, make sure Guix is
available on each machine, attempt to export to the machine and import
from it, and report any error in the process.
At that point SELinux could not prevent it from accessing files that are
allowed for processes in that domain.
+You will need to relabel the store directory after all upgrades to
+@file{guix-daemon}, such as after running @code{guix pull}. Assuming the
+store is in @file{/gnu}, you can do this with @code{restorecon -vR /gnu},
+or by other means provided by your operating system.
+
We could generate a much more restrictive policy at installation time,
so that only the @emph{exact} file name of the currently installed
@code{guix-daemon} executable would be labelled with
@var{localstatedir}. To save space, the daemon automatically compresses
them with Bzip2 by default.
+@item --discover[=yes|no]
+Whether to discover substitute servers on the local network using mDNS
+and DNS-SD.
+
+This feature is still experimental. However, here are a few
+considerations.
+
+@enumerate
+@item
+It might be faster/less expensive than fetching from remote servers;
+@item
+There are no security risks, only genuine substitutes will be used
+(@pxref{Substitute Authentication});
+@item
+An attacker advertising @command{guix publish} on your LAN cannot serve
+you malicious binaries, but they can learn what software you’re
+installing;
+@item
+Servers may serve substitute over HTTP, unencrypted, so anyone on the
+LAN can see what software you’re installing.
+@end enumerate
+
+It is also possible to enable or disable substitute server discovery at
+run-time by running:
+
+@example
+herd discover guix-daemon on
+herd discover guix-daemon off
+@end example
+
@item --disable-deduplication
@cindex deduplication
Disable automatic file ``deduplication'' in the store.
Note that the @code{glibc-locales} package contains data for all the
locales supported by the GNU@tie{}libc and weighs in at around
-917@tie{}MiB. Alternatively, the @code{glibc-utf8-locales} is smaller but
+917@tie{}MiB@. Alternatively, the @code{glibc-utf8-locales} is smaller but
limited to a few UTF-8 locales.
The @env{GUIX_LOCPATH} variable plays a role similar to @env{LOCPATH}
following noteworthy limitations applicable to version @value{VERSION}:
@itemize
-@item
-Support for the Logical Volume Manager (LVM) is missing.
-
@item
More and more system services are provided (@pxref{Services}), but some
may be missing.
@unnumberedsubsec Booting
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
+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.
In order to boot from Libreboot, switch to the command mode by pressing
the @kbd{c} key and type @command{search_grub usb}.
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, btrfs, and JFS 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
+Guix System only supports ext4, btrfs, JFS, and F2FS 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:
@example
system} command, specifically:
@example
-guix system disk-image -t iso9660 gnu/system/install.scm
+guix system image -t iso9660 gnu/system/install.scm
@end example
Have a look at @file{gnu/system/install.scm} in the source tree,
includes the bootloader, specifically:
@example
-guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
+guix system image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
@end example
@code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid
lines in your terminal and @file{.bash_profile}:
@example
-GUIX_PROFILE="$HOME/.config/guix/current/etc/profile"
+GUIX_PROFILE="$HOME/.config/guix/current"
. "$GUIX_PROFILE/etc/profile"
@end example
@example
GUIX_PROFILE="$HOME/.guix-profile" ; \
-source "$HOME/.guix-profile/etc/profile"
+source "$GUIX_PROFILE/etc/profile"
@end example
In a multi-user setup, user profiles are stored in a place registered as
'("emacs" "guile@@2.2" "guile@@2.2:debug"))
@end lisp
+@xref{export-manifest, @option{--export-manifest}}, to learn how to
+obtain a manifest file from an existing profile.
+
@item --roll-back
@cindex rolling back
@cindex undoing transactions
Note that deleting generations prevents rolling back to them.
Consequently, this command must be used with care.
+@cindex manifest, exporting
+@anchor{export-manifest}
+@item --export-manifest
+Write to standard output a manifest suitable for @option{--manifest}
+corresponding to the chosen profile(s).
+
+This option is meant to help you migrate from the ``imperative''
+operating mode---running @command{guix install}, @command{guix upgrade},
+etc.---to the declarative mode that @option{--manifest} offers.
+
+Be aware that the resulting manifest @emph{approximates} what your
+profile actually contains; for instance, depending on how your profile
+was created, it can refer to packages or package versions that are not
+exactly what you specified.
+
+Keep in mind that a manifest is purely symbolic: it only contains
+package names and possibly versions, and their meaning varies over time.
+If you wish to ``pin'' channels to the revisions that were used to build
+the profile(s), see @option{--export-channels} below.
+
+@cindex pinning, channel revisions of a profile
+@item --export-channels
+Write to standard output the list of channels used by the chosen
+profile(s), in a format suitable for @command{guix pull --channels} or
+@command{guix time-machine --channels} (@pxref{Channels}).
+
+Together with @option{--export-manifest}, this option provides
+information allowing you to replicate the current profile
+(@pxref{Replicating Guix}).
+
+However, note that the output of this command @emph{approximates} what
+was actually used to build this profile. In particular, a single
+profile might have been built from several different revisions of the
+same channel. In that case, @option{--export-manifest} chooses the last
+one and writes the list of other revisions in a comment. If you really
+need to pick packages from different channel revisions, you can use
+inferiors in your manifest to do so (@pxref{Inferiors}).
+
+Together with @option{--export-manifest}, this is a good starting point
+if you are willing to migrate from the ``imperative'' model to the fully
+declarative model consisting of a manifest file along with a channels
+file pinning the exact channel revision(s) you want.
@end table
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 @env{GUIX_PACKAGE_PATH}
-(@pxref{Defining Packages}).
+@option{--with-source}, and preserves them across upgrades
+(@pxref{Package Transformation Options}).
@node Substitutes
@section Substitutes
@vindex http_proxy
@vindex https_proxy
-Substitutes are downloaded over HTTP or HTTPS. The @env{http_proxy} and
+Substitutes are downloaded over HTTP or HTTPS@. The @env{http_proxy} and
@env{https_proxy} environment variables can be set in the environment of
@command{guix-daemon} and are honored for downloads of substitutes.
Note that the value of those environment variables in the environment
describe the current status of Guix.
This @code{~/.config/guix/current} profile works exactly like the profiles
-created by @command{guix package} (@pxref{Invoking guix package}). That
+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:
@end table
As for @command{guix pull}, the absence of any options means that the
-latest commit on the master branch will be used. The command
+latest commit on the master branch will be used. The command
@example
guix time-machine -- build hello
* Specifying Channel Authorizations:: Defining channel authors authorizations.
* Primary URL:: Distinguishing mirror to original.
* Writing Channel News:: Communicating information to channel's users.
+* Channels with Substitutes:: Using channels with available substitutes.
@end menu
@node Specifying Additional Channels
@cindex extending the package collection (channels)
@cindex variant packages (channels)
-You can specify @emph{additional channels} to pull from. To use a channel, write
+You can specify @emph{additional channels} to pull from. 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):
This allows @command{guix pull} to determine whether it is pulling code
from a mirror of the channel; when that is the case, it warns the user
-that the mirror might be stale and displays the primary URL. That way,
+that the mirror might be stale and displays the primary URL@. That way,
users cannot be tricked into fetching code from a stale mirror that does
not receive security updates.
To sum up, yes, you could use your channel as a blog. But beware, this
is @emph{not quite} what your users might expect.
+@node Channels with Substitutes
+@section Channels with Substitutes
+
+When running @command{guix pull}, Guix will first compile the
+definitions of every available package. This is an expensive operation
+for which substitutes (@pxref{Substitutes}) may be available. The
+following snippet in @file{channels.scm} will ensure that @command{guix
+pull} uses the latest commit with available substitutes for the package
+definitions: this is done by querying the continuous integration
+server at @url{https://ci.guix.gnu.org}.
+
+@lisp
+(use-modules (guix ci))
+
+(list (channel-with-substitutes-available
+ %default-guix-channel
+ "https://ci.guix.gnu.org"))
+@end lisp
+
+Note that this does not mean that all the packages that you will
+install after running @command{guix pull} will have available
+substitutes. It only ensures that @command{guix pull} will not try to
+compile package definitions. This is particularly useful when using
+machines with limited resources.
@c *********************************************************************
@node Development
@cindex fixed-output derivations, for download
@item @code{method}
-A monadic procedure that handles the given URI. The procedure must
+A monadic procedure that handles the given URI@. The procedure must
accept at least three arguments: the value of the @code{uri} field and
the hash algorithm and hash value specified by the @code{hash} field.
It must return a store item or a derivation in the store monad
@end lisp
@end deftp
+For Mercurial repositories, the module @code{(guix hg-download)} defines
+the @code{hg-fetch} origin method and @code{hg-reference} data type for
+support of the Mercurial version control system.
+
+@deffn {Scheme Procedure} hg-fetch @var{ref} @var{hash-algo} @var{hash} @
+ [name]
+Return a fixed-output derivation that fetches @var{ref}, a
+@code{<hg-reference>} object. The output is expected to have recursive
+hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
+the file name, or a generic name if @code{#false}.
+@end deffn
+
@node Defining Package Variants
@section Defining Package Variants
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
+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")},
+disable some tests. It defaults to @code{(list "**/Abstract*.java")},
because abstract classes cannot be run as tests.
The parameter @code{#:build-target} can be used to specify the Ant task
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
+@url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
definition facility for Common Lisp programs and libraries.
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
+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.
defined by the crate.
@end defvr
+@defvr {Scheme Variable} chicken-build-system
+This variable is exported by @code{(guix build-system chicken)}. It
+builds @uref{https://call-cc.org/, CHICKEN Scheme} modules, also called
+``eggs'' or ``extensions''. CHICKEN generates C source code, which then
+gets compiled by a C compiler, in this case GCC.
+
+This build system adds @code{chicken} to the package inputs, as well as
+the packages of @code{gnu-build-system}.
+
+The build system can't (yet) deduce the egg's name automatically, so just like
+with @code{go-build-system} and its @code{#:import-path}, you should define
+@code{#:egg-name} in the package's @code{arguments} field.
+
+For example, if you are packaging the @code{srfi-1} egg:
+
+@lisp
+(arguments '(#:egg-name "srfi-1"))
+@end lisp
+
+Egg dependencies must be defined in @code{propagated-inputs}, not @code{inputs}
+because CHICKEN doesn't embed absolute references in compiled eggs.
+Test dependencies should go to @code{native-inputs}, as usual.
+@end defvr
@defvr {Scheme Variable} copy-build-system
This variable is exported by @code{(guix build-system copy)}. It
julia} packages, which essentially is similar to running @samp{julia -e
'using Pkg; Pkg.add(package)'} in an environment where
@env{JULIA_LOAD_PATH} contains the paths to all Julia package inputs.
-Tests are run with @code{Pkg.test}.
+Tests are run by calling @code{/test/runtests.jl}.
-Julia packages require the source @code{file-name} to be the real name of the
-package, correctly capitalized.
+The Julia package name is read from the file @file{Project.toml}. This
+value can be overridden by passing the argument @code{#:julia-file-name}
+(which must be correctly capitalized).
For packages requiring shared library dependencies, you may need to write the
-@file{/deps/deps.jl} file manually. It's usually a line of @code{const
+@file{/deps/deps.jl} file manually. It's usually a line of @code{const
variable = /gnu/store/library.so} for each dependency, plus a void function
@code{check_deps() = nothing}.
Some older packages that aren't using @file{Package.toml} yet, will require
-this file to be created, too. The function @code{julia-create-package-toml}
-helps creating the file. You need to pass the outputs and the source of the
+this file to be created, too. The function @code{julia-create-package-toml}
+helps creating the file. You need to pass the outputs and the source of the
package, it's name (the same as the @code{file-name} parameter), the package
uuid, the package version, and a list of dependencies specified by their name
and their uuid.
@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
+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
parameter which defaults to @code{ldc}.
@end defvr
+@anchor{emacs-build-system}
@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
@item ssh
@cindex SSH access to build daemons
-These URIs allow you to connect to a remote daemon over SSH. This
+These URIs allow you to connect to a remote daemon over SSH@. This
feature requires Guile-SSH (@pxref{Requirements}) and a working
@command{guile} binary in @env{PATH} on the destination machine. It
supports public key and GSSAPI authentication. A typical URL might look
@quotation Note
There can be application binary interface (ABI) incompatibilities among
tool chains. This is particularly true of the C++ standard library and
-run-time support libraries such as that of OpenMP. By rebuilding all
+run-time support libraries such as that of OpenMP@. By rebuilding all
dependents with the same tool chain, @option{--with-c-toolchain} minimizes
the risks of incompatibility but cannot entirely eliminate them. Choose
@var{package} wisely.
@var{commit} rather than the tip of a branch. @var{commit} must be a valid
Git commit SHA1 identifier or a tag.
+@item --with-patch=@var{package}=@var{file}
+Add @var{file} to the list of patches applied to @var{package}, where
+@var{package} is a spec such as @code{python@@3.8} or @code{glibc}.
+@var{file} must contain a patch; it is applied with the flags specified
+in the @code{origin} of @var{package} (@pxref{origin Reference}), which
+by default includes @code{-p1} (@pxref{patch Directories,,, diffutils,
+Comparing and Merging Files}).
+
+As an example, the command below rebuilds Coreutils with the GNU C
+Library (glibc) patched with the given patch:
+
+@example
+guix build coreutils --with-patch=glibc=./glibc-frob.patch
+@end example
+
+In this example, glibc itself as well as everything that leads to
+Coreutils in the dependency graph is rebuilt.
+
+@cindex upstream, latest version
+@item --with-latest=@var{package}
+So you like living on the bleeding edge? This option is for you! It
+replaces occurrences of @var{package} in the dependency graph with its
+latest upstream version, as reported by @command{guix refresh}
+(@pxref{Invoking guix refresh}).
+
+It does so by determining the latest upstream release of @var{package}
+(if possible), downloading it, and authenticating it @emph{if} it comes
+with an OpenPGP signature.
+
+As an example, the command below builds Guix against the latest version
+of Guile-JSON:
+
+@example
+guix build guix --with-latest=guile-json
+@end example
+
+There are limitations. First, in cases where the tool cannot or does
+not know how to authenticate source code, you are at risk of running
+malicious code; a warning is emitted in this case. Second, this option
+simply changes the source used in the existing package definitions,
+which is not always sufficient: there might be additional dependencies
+that need to be added, patches to apply, and more generally the quality
+assurance work that Guix developers normally do will be missing.
+
+You've been warned! In all the other cases, it's a snappy way to stay
+on top. We encourage you to submit patches updating the actual package
+definitions once you have successfully tested an upgrade
+(@pxref{Contributing}).
+
@cindex test suite, skipping
@item --without-tests=@var{package}
Build @var{package} without running its tests. This can be useful in
code snippets specified in the package @code{origin} (@pxref{Defining
Packages}).
+@cindex source, verification
+As with other derivations, the result of building a source derivation
+can be verified using the @option{--check} option (@pxref{build-check}).
+This is useful to validate that a (potentially already built or
+substituted, thus cached) package source matches against its declared
+hash.
+
Note that @command{guix build -S} compiles the sources only of the
specified packages. They do not include the sources of statically
linked dependencies and by themselves are insufficient for reproducing
dependency graph of the given upstream package recursively and generate
package expressions for all those packages that are not yet in Guix.
+When @option{--style=specification} is added, the importer will generate
+package definitions whose inputs are package specifications instead of
+references to package variables. This is useful when generated package
+definitions are to be appended to existing user modules, as the list of
+used package modules need not be changed. The default is
+@option{--style=variable}.
+
When @option{--archive=bioconductor} is added, metadata is imported from
@uref{https://www.bioconductor.org/, Bioconductor}, a repository of R
packages for the analysis and comprehension of high-throughput
@cindex OCaml
Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package
repository used by the OCaml community.
+
+Additional options include:
+
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@item --repo
+Select the given repository (a repository name). Possible values include:
+@itemize
+@item @code{opam}, the default opam repository,
+@item @code{coq} or @code{coq-released}, the stable repository for coq packages,
+@item @code{coq-core-dev}, the repository that contains development versions of coq,
+@item @code{coq-extra-dev}, the repository that contains development versions
+ of coq packages.
+@end itemize
+@end table
@end table
The structure of the @command{guix import} code is modular. It would be
@item --manifest=@var{file}
@itemx -m @var{file}
-Select all the packages from the manifest in @var{file}. This is useful to
+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}
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
+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}).
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,
+provides a visual representation of the DAG@. By default,
@command{guix graph} emits a DAG representation in the input format of
@uref{https://www.graphviz.org/, Graphviz}, so its output can be passed
directly to the @command{dot} command of Graphviz. It can also emit an
launched, using @command{guix archive --generate-key} (@pxref{Invoking
guix archive}).
+When the @option{--advertise} option is passed, the server advertises
+its availability on the local network using multicast DNS (mDNS) and DNS
+service discovery (DNS-SD), currently @i{via} Guile-Avahi (@pxref{Top,,,
+guile-avahi, Using Avahi in Guile Scheme Programs}).
+
The general syntax is:
@example
@item --compression[=@var{method}[:@var{level}]]
@itemx -C [@var{method}[:@var{level}]]
Compress data using the given @var{method} and @var{level}. @var{method} is
-one of @code{lzip} and @code{gzip}; when @var{method} is omitted, @code{gzip}
-is used.
+one of @code{lzip}, @code{zstd}, and @code{gzip}; when @var{method} is
+omitted, @code{gzip} is used.
When @var{level} is zero, disable compression. The range 1 to 9 corresponds
to different compression levels: 1 is the fastest, and 9 is the best
(CPU-intensive). The default is 3.
-Usually, @code{lzip} compresses noticeably better than @code{gzip} for a small
-increase in CPU usage; see
-@uref{https://nongnu.org/lzip/lzip_benchmark.html,benchmarks on the lzip Web
-page}.
+Usually, @code{lzip} compresses noticeably better than @code{gzip} for a
+small increase in CPU usage; see
+@uref{https://nongnu.org/lzip/lzip_benchmark.html,benchmarks on the lzip
+Web page}. However, @code{lzip} achieves low decompression throughput
+(on the order of 50@tie{}MiB/s on modern hardware), which can be a
+bottleneck for someone who downloads over a fast network connection.
+
+The compression ratio of @code{zstd} is between that of @code{lzip} and
+that of @code{gzip}; its main advantage is a
+@uref{https://facebook.github.io/zstd/,high decompression speed}.
Unless @option{--cache} is used, compression occurs on the fly and
the compressed streams are not
@end example
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.
+packages that depend on it have no substitutes at
+@code{@value{SUBSTITUTE-SERVER}}; likewise for @code{qgpgme} and the 46
+packages that depend on it.
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
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
+ChildPID: 20495
+ChildCommand: guix offload x86_64-linux 7200 1 28800
+ChildPID: 27733
+ChildCommand: guix offload x86_64-linux 7200 1 28800
+ChildPID: 27793
+ChildCommand: guix offload x86_64-linux 7200 1 28800
@end example
In this example we see that @command{guix-daemon} has three clients:
@code{ClientPID} field. The @code{SessionPID} field gives the PID of the
@command{guix-daemon} sub-process of this particular session.
-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 @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{ChildPID} and @code{ChildCommand} fields, we understand that
+these three builds are being offloaded (@pxref{Daemon Offload Setup}).
The output is in Recutils format so we can use the handy @command{recsel}
command to select sessions of interest (@pxref{Selection Expressions,,,
ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
@end example
+Additional options are listed below.
+
+@table @code
+@item --format=@var{format}
+@itemx -f @var{format}
+Produce output in the specified @var{format}, one of:
+
+@table @code
+@item recutils
+The default option. It outputs a set of Session recutils records
+that include each @code{ChildProcess} as a field.
+
+@item normalized
+Normalize the output records into record sets (@pxref{Record Sets,,,
+recutils, GNU recutils manual}). Normalizing into record sets allows
+joins across record types. The example below lists the PID of each
+@code{ChildProcess} and the associated PID for @code{Session} that
+spawned the @code{ChildProcess} where the @code{Session} was started
+using @command{guix build}.
+
+@example
+$ guix processes --format=normalized | \
+ recsel \
+ -j Session \
+ -t ChildProcess \
+ -p Session.PID,PID \
+ -e 'Session.ClientCommand ~ "guix build"'
+PID: 4435
+Session_PID: 4278
+
+PID: 4554
+Session_PID: 4278
+
+PID: 4646
+Session_PID: 4278
+@end example
+@end table
+@end table
+
@node System Configuration
@chapter System Configuration
@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.
+US English), or a @code{<keyboard-layout>} record. @xref{Keyboard Layout},
+for more information.
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
@table @code
@item (list (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))
-Use the swap partition with the given UUID. You can learn the UUID of a
+Use the swap partition with the given UUID@. You can learn the UUID of a
Linux swap partition by running @command{swaplabel @var{device}}, where
@var{device} is the @file{/dev} file name of that partition.
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.
Mapped devices are declared using the @code{mapped-device} form,
defined as follows; for examples, see below.
@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.
+need to be assembled for creating a new one. In case of LVM this is a
+string specifying name of the volume group to be mapped.
@item target
This string specifies the name of the resulting mapped device. For
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.
+LVM logical volumes of type @code{lvm-device-mapping} need to
+be specified as @code{"VGNAME-LVNAME"}.
+
+@item targets
+This list of strings specifies names of the resulting mapped devices in case
+there are several. The format is identical to @var{target}.
@item type
This must be a @code{mapped-device-kind} object, which specifies how
for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
@end defvr
+@cindex LVM, logical volume manager
+@defvr {Scheme Variable} lvm-device-mapping
+This defines one or more logical volumes for the Linux
+@uref{https://www.sourceware.org/lvm2/, Logical Volume Manager (LVM)}.
+The volume group is activated by the @command{vgchange} command from the
+@code{lvm2} package.
+@end defvr
+
@cindex disk encryption
@cindex LUKS
The following example specifies a mapping from @file{/dev/sda3} to
initial creation and formatting of the RAID device and is determined
automatically later.
+LVM logical volumes ``alpha'' and ``beta'' from volume group ``vg0'' can
+be declared as follows:
+
+@lisp
+(mapped-device
+ (source "vg0")
+ (targets (list "vg0-alpha" "vg0-beta"))
+ (type lvm-device-mapping))
+@end lisp
+
+Devices @file{/dev/mapper/vg0-alpha} and @file{/dev/mapper/vg0-beta} can
+then be used as the @code{device} of a @code{file-system} declaration
+(@pxref{File Systems}).
@node User Accounts
@section User Accounts
When set to @code{#t} in conjunction with @var{auto-login}, the user
will have to press a key before the log-in shell is launched.
+@item @code{clear-on-logout?} (default: @code{#t})
+When set to @code{#t}, the screen will be cleared after logout.
+
@item @code{mingetty} (default: @var{mingetty})
The Mingetty package to use.
@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},
+arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f},
the default value chosen by agetty is @code{'auto}.
@item @code{extract-baud?} (default: @code{#f})
The name of the console this Kmscon runs on---e.g., @code{"tty1"}.
@item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
-A gexp denoting the name of the log-in program. The default log-in program is
+A gexp denoting the name of the log-in program. The default log-in program is
@command{login} from the Shadow tool suite.
@item @code{login-arguments} (default: @code{'("-p")})
The type of compression used for build logs---one of @code{gzip},
@code{bzip2}, or @code{none}.
+@item @code{discover?} (default: @code{#f})
+Whether to discover substitute servers on the local network using mDNS
+and DNS-SD.
+
@item @code{extra-options} (default: @code{'()})
List of extra command-line options for @command{guix-daemon}.
The host (and thus, network interface) to listen to. Use
@code{"0.0.0.0"} to listen on all the network interfaces.
+@item @code{advertise?} (default: @code{#f})
+When true, advertise the service on the local network @i{via} the DNS-SD
+protocol, using Avahi.
+
+This allows neighboring Guix devices with discovery on (see
+@code{guix-configuration} above) to discover this @command{guix publish}
+instance and to automatically download substitutes from it.
+
@item @code{compression} (default: @code{'(("gzip" 3))})
This is a list of compression method/level tuple used when compressing
substitutes. For example, to compress all substitutes with @emph{both} lzip
@end lisp
Level 9 achieves the best compression ratio at the expense of increased CPU
-usage, whereas level 1 achieves fast compression.
+usage, whereas level 1 achieves fast compression. @xref{Invoking guix
+publish}, for more information on the available compression methods and
+the tradeoffs involved.
An empty list disables compression altogether.
(operating-system
;; @dots{}
- (services (cons (service mcron-service-type
- (mcron-configuration
- (jobs (list garbage-collector-job
- updatedb-job
- idutils-job))))
+
+ ;; %BASE-SERVICES already includes an instance of
+ ;; 'mcron-service-type', which we extend with additional
+ ;; jobs using 'simple-service'.
+ (services (cons (simple-service 'my-cron-jobs
+ mcron-service-type
+ (list garbage-collector-job
+ updatedb-job
+ idutils-job))
%base-services)))
@end lisp
@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
+service. The value for this service type is a
@code{modem-manager-configuration} record.
This service is part of @code{%desktop-services} (@pxref{Desktop
@defvr {Scheme Variable} usb-modeswitch-service-type
This is the service type for the
-@uref{https://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch} service. The
-value for this service type is a @code{usb-modeswitch-configuration} record.
+@uref{https://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch}
+service. The value for this service type is
+a @code{usb-modeswitch-configuration} record.
When plugged in, some USB modems (and other USB devices) initially present
themselves as a read-only storage medium and not as a modem. They need to be
@table @asis
@item @code{type} (default: @code{'server})
-The type of the NTP server, given as a symbol. One of @code{'pool},
+The type of the NTP server, given as a symbol. One of @code{'pool},
@code{'server}, @code{'peer}, @code{'broadcast} or @code{'manycastclient}.
@item @code{address}
@item @code{options}
NTPD options to use with that specific server, given as a list of option names
-and/or of option names and values tuples. The following example define a server
+and/or of option names and values tuples. The following example define a server
to use with the options @option{iburst} and @option{prefer}, as well as
@option{version} 3 and a @option{maxpoll} time of 16 seconds.
(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)))
+ (constraints-from '("https://www.google.com/"))))
@end lisp
@end deffn
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
@end table
@end deftp
+The @code{(gnu services syncthing)} module provides the following services:
+@cindex syncthing
+
+You might want a syncthing daemon if you have files between two or more
+computers and want to sync them in real time, safely protected from
+prying eyes.
+
+@deffn {Scheme Variable} syncthing-service-type
+This is the service type for the @uref{https://syncthing.net/,
+syncthing} daemon, The value for this service type is a
+@command{syncthing-configuration} record as in this example:
+
+@lisp
+(service syncthing-service-type
+ (syncthing-configuration (user "alice")))
+@end lisp
+
+See below for details about @code{syncthing-configuration}.
+
+@deftp {Data Type} syncthing-configuration
+Data type representing the configuration for @code{syncthing-service-type}.
+
+@table @asis
+@item @code{syncthing} (default: @var{syncthing})
+@code{syncthing} package to use.
+
+@item @code{arguments} (default: @var{'()})
+List of command-line arguments passing to @code{syncthing} binary.
+
+@item @code{logflags} (default: @var{0})
+Sum of loging flags, see
+@uref{https://docs.syncthing.net/users/syncthing.html#cmdoption-logflags, Syncthing documentation logflags}.
+
+@item @code{user} (default: @var{#f})
+The user as which the Syncthing service is to be run.
+This assumes that the specified user exists.
+
+@item @code{group} (default: @var{"users"})
+The group as which the Syncthing service is to be run.
+This assumes that the specified group exists.
+
+@item @code{home} (default: @var{#f})
+Common configuration and data directory. The default configuration
+directory is @file{$HOME} of the specified Syncthing @code{user}.
+
+@end table
+@end deftp
+@end deffn
+
Furthermore, @code{(gnu services ssh)} provides the following services.
@cindex SSH
@cindex SSH server
List of hosts which allowed for SSH connection from @command{webssh}.
@item @code{log-file} (default: @file{"/var/log/webssh.log"})
-Name of the file where @command{rsync} writes its log file.
+Name of the file where @command{webssh} writes its log file.
@item @code{log-level} (default: @var{#f})
Logging level.
@uref{https://pagekite.net,,pagekite.net} service.
@item @code{kites} (default: @code{'("http:@@kitename:localhost:80:@@kitesecret")})
-List of service kites to use. Exposes HTTP on port 80 by default. The format
+List of service kites to use. Exposes HTTP on port 80 by default. The format
is @code{proto:kitename:host:port:secret}.
@item @code{extra-file} (default: @code{#f})
@end table
@end deftp
+@cindex keepalived
+@deffn {Scheme Variable} keepalived-service-type
+This is the type for the @uref{https://www.keepalived.org/, Keepalived}
+routing software, @command{keepalived}. Its value must be an
+@code{keepalived-configuration} record as in this example for master
+machine:
+
+@lisp
+(service keepalived-service-type
+ (keepalived-configuration
+ (config-file (local-file "keepalived-master.conf"))))
+@end lisp
+
+where @file{keepalived-master.conf}:
+
+@example
+vrrp_instance my-group @{
+ state MASTER
+ interface enp9s0
+ virtual_router_id 100
+ priority 100
+ unicast_peer @{ 10.0.0.2 @}
+ virtual_ipaddress @{
+ 10.0.0.4/24
+ @}
+@}
+@end example
+
+and for backup machine:
+
+@lisp
+(service keepalived-service-type
+ (keepalived-configuration
+ (config-file (local-file "keepalived-backup.conf"))))
+@end lisp
+
+where @file{keepalived-backup.conf}:
+
+@example
+vrrp_instance my-group @{
+ state BACKUP
+ interface enp9s0
+ virtual_router_id 100
+ priority 99
+ unicast_peer @{ 10.0.0.3 @}
+ virtual_ipaddress @{
+ 10.0.0.4/24
+ @}
+@}
+@end example
+@end deffn
+
@node Unattended Upgrades
@subsection Unattended Upgrades
conservative: it minimizes disruption but leaves outdated services
running.
+Use @command{herd status} to find out candidates for restarting.
+@xref{Services}, for general information about services. Common
+services to restart would include @code{ntpd} and @code{ssh-daemon}.
+
By default, the @code{mcron} service is restarted. This ensures that
the latest version of the unattended upgrade job will be used next time.
@deftp {Data Type} xorg-configuration
This data type represents the configuration of the Xorg graphical display
server. Note that there is no Xorg service; instead, the X server is started
-by a ``display manager'' such as GDM, SDDM, and SLiM. Thus, the configuration
+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
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):
+support for Epson printers @i{via} the @code{epson-inkjet-printer-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):
@lisp
(service cups-service-type
(cups-configuration
(web-interface? #t)
(extensions
- (list cups-filters escpr hplip-minimal))))
+ (list cups-filters epson-inkjet-printer-escpr hplip-minimal))))
@end lisp
Note: If you wish to use the Qt5 based GUI which comes with the hplip
The CUPS package.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} package-list extensions
+@deftypevr {@code{cups-configuration} parameter} package-list extensions (default: @code{(list brlaser cups-filters epson-inkjet-printer-escpr foomatic-filters hplip-minimal splix)})
Drivers and other extensions to the CUPS package.
@end deftypevr
default. If you'd like to use the newer display server protocol
called Wayland, you need to use the @code{sddm-service} instead of
GDM as the graphical login manager. You should then
-select the ``GNOME (Wayland)'' session in SDDM. Alternatively you can
+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.
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.
+
+Note that @code{xfce4-panel} and its plugin packages should be installed in
+the same profile to ensure compatibility. When using this service, you should
+add extra plugins (@code{xfce4-whiskermenu-plugin},
+@code{xfce4-weather-plugin}, etc.) to the @code{packages} field of your
+@code{operating-system}.
@end defvr
@deftp {Data Type} xfce-desktop-configuration
Locale to use as the default when creating the database cluster.
@item @code{config-file} (default: @code{(postgresql-config-file)})
-The configuration file to use when running PostgreSQL. The default
+The configuration file to use when running PostgreSQL@. The default
behaviour uses the postgresql-config-file record with the default values
for the fields.
+@item @code{log-directory} (default: @code{"/var/log/postgresql"})
+The directory where @command{pg_ctl} output will be written in a file
+named @code{"pg_ctl.log"}. This file can be useful to debug PostgreSQL
+configuration errors for instance.
+
@item @code{data-directory} (default: @code{"/var/lib/postgresql/data"})
Directory in which to store the data.
@deftp {Data Type} postgresql-config-file
Data type representing the PostgreSQL configuration file. As shown in
the following example, this can be used to customize the configuration
-of PostgreSQL. Note that you can use any G-expression or filename in
+of PostgreSQL@. Note that you can use any G-expression or filename in
place of this record, if you already have a configuration file you'd
like to use for example.
host all all 127.0.0.1/32 md5
host all all ::1/128 md5"))
(extra-config
- '(("session_preload_libraries" "'auto_explain'")
- ("random_page_cost" "2")
- ("auto_explain.log_min_duration" "'100ms'")
- ("work_mem" "'500MB'")
- ("logging_collector" "on")
- ("log_directory" "'/var/log/postgresql'")))))))
+ '(("session_preload_libraries" "auto_explain")
+ ("random_page_cost" 2)
+ ("auto_explain.log_min_duration" "100 ms")
+ ("work_mem" "500 MB")
+ ("logging_collector" #t)
+ ("log_directory" "/var/log/postgresql")))))))
@end lisp
@table @asis
@item @code{log-destination} (default: @code{"syslog"})
-The logging method to use for PostgreSQL. Multiple values are accepted,
+The logging method to use for PostgreSQL@. Multiple values are accepted,
separated by commas.
@item @code{hba-file} (default: @code{%default-postgres-hba})
@item @code{ident-file} (default: @code{%default-postgres-ident})
Filename or G-expression for the user name mapping configuration.
+@item @code{socket-directory} (default: @code{"/var/lib/postgresql"})
+Specifies the directory of the Unix-domain socket(s) on which PostgreSQL
+is to listen for connections from client applications. If set to
+@code{#false} PostgreSQL does not listen on any Unix-domain sockets, in
+which case only TCP/IP sockets can be used to connect to the server.
+
@item @code{extra-config} (default: @code{'()})
List of additional keys and values to include in the PostgreSQL config
file. Each entry in the list should be a list where the first element
is the key, and the remaining elements are the values.
+The values can be numbers, booleans or strings and will be mapped to
+PostgreSQL parameters types @code{Boolean}, @code{String},
+@code{Numeric}, @code{Numeric with Unit} and @code{Enumerated} described
+@uref{https://www.postgresql.org/docs/current/config-setting.html,
+here}.
+
@end table
@end deftp
-@subsubheading MariaDB/MySQL
+@deffn {Scheme Variable} postgresql-role-service-type
+This service allows to create PostgreSQL roles and databases after
+PostgreSQL service start. Here is an example of its use.
-@deffn {Scheme Procedure} mysql-service [#:config (mysql-configuration)]
-Return a service that runs @command{mysqld}, the MySQL or MariaDB
-database server.
+@lisp
+(service postgresql-role-service-type
+ (postgresql-role-configuration
+ (roles
+ (list (postgresql-role
+ (name "test")
+ (create-database? #t))))))
+@end lisp
-The optional @var{config} argument specifies the configuration for
-@command{mysqld}, which should be a @code{<mysql-configuration>} object.
+This service can be extended with extra roles, as in this
+example:
+
+@lisp
+(service-extension postgresql-role-service-type
+ (const (postgresql-role
+ (name "alice")
+ (create-database? #t))))
+@end lisp
@end deffn
+@deftp {Data Type} postgresql-role
+PostgreSQL manages database access permissions using the concept of
+roles. A role can be thought of as either a database user, or a group
+of database users, depending on how the role is set up. Roles can own
+database objects (for example, tables) and can assign privileges on
+those objects to other roles to control who has access to which objects.
+
+@table @asis
+@item @code{name}
+The role name.
+
+@item @code{permissions} (default: @code{'(createdb login)})
+The role permissions list. Supported permissions are @code{bypassrls},
+@code{createdb}, @code{createrole}, @code{login}, @code{replication} and
+@code{superuser}.
+
+@item @code{create-database?} (default: @code{#f})
+Whether to create a database with the same name as the role.
+
+@end table
+@end deftp
+
+@deftp {Data Type} postgresql-role-configuration
+Data type representing the configuration of
+@var{postgresql-role-service-type}.
+
+@table @asis
+@item @code{host} (default: @code{"/var/run/postgresql"})
+The PostgreSQL host to connect to.
+
+@item @code{log} (default: @code{"/var/log/postgresql_roles.log"})
+File name of the log file.
+
+@item @code{roles} (default: @code{'()})
+The initial PostgreSQL roles to create.
+@end table
+@end deftp
+
+@subsubheading MariaDB/MySQL
+
+@defvr {Scheme Variable} mysql-service-type
+This is the service type for a MySQL or MariaDB database server. Its value
+is a @code{mysql-configuration} object that specifies which package to use,
+as well as various settings for the @command{mysqld} daemon.
+@end defvr
+
@deftp {Data Type} mysql-configuration
-Data type representing the configuration of @var{mysql-service}.
+Data type representing the configuration of @var{mysql-service-type}.
@table @asis
@item @code{mysql} (default: @var{mariadb})
For MySQL, a temporary root password will be displayed at activation time.
For MariaDB, the root password is empty.
+@item @code{bind-address} (default: @code{"127.0.0.1"})
+The IP on which to listen for network connections. Use @code{"0.0.0.0"}
+to bind to all available network interfaces.
+
@item @code{port} (default: @code{3306})
TCP port on which the database server listens for incoming connections.
+
+@item @code{socket} (default: @code{"/run/mysqld/mysqld.sock"})
+Socket file to use for local (non-network) connections.
+
+@item @code{extra-content} (default: @code{""})
+Additional settings for the @file{my.cnf} configuration file.
+
+@item @code{auto-upgrade?} (default: @code{#t})
+Whether to automatically run @command{mysql_upgrade} after starting the
+service. This is necessary to upgrade the @dfn{system schema} after
+``major'' updates (such as switching from MariaDB 10.4 to 10.5), but can
+be disabled if you would rather do that manually.
+
@end table
@end deftp
Network interfaces on which to listen.
@item @code{tcp-port} (default: @code{11211})
-Port on which to accept connections on,
+Port on which to accept connections.
@item @code{udp-port} (default: @code{11211})
Port on which to accept UDP connections on, a value of 0 will disable
@end deftypevr
@deftypevr {@code{namespace-configuration} parameter} string separator
-Hierarchy separator to use. You should use the same separator for
+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.
@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/}.
+different for all namespaces. For example @samp{Public/}.
Defaults to @samp{""}.
@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
+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/}
@end deftypevr
@deftypevr {@code{namespace-configuration} parameter} boolean list?
-Show the mailboxes under this namespace with the LIST command. This
+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.
@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
+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.@: @file{/path/} or @file{~user/}.
Defaults to @samp{#f}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage?
-Mail storage exists in NFS. Set this to yes to make Dovecot flush
+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
+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
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf?
-Save mails with CR+LF instead of plain LF. This makes sending those
+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
+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}.
Package object of the Exim server.
@item @code{config-file} (default: @code{#f})
-File-like object of the Exim configuration file to use. If its value is
+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
+provided in @code{package}. The resulting configuration file is loaded
after setting the @code{exim_user} and @code{exim_group} configuration
variables.
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
+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 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
@end table
@end deftp
+@subsubheading Radicale Service
+@cindex CalDAV
+@cindex CardDAV
+
+@deffn {Scheme Variable} radicale-service-type
+This is the type of the @uref{https://radicale.org, Radicale} CalDAV/CardDAV
+server whose value should be a @code{radicale-configuration}.
+@end deffn
+
+@deftp {Data Type} radicale-configuration
+Data type representing the configuration of @command{radicale}.
+
+@table @asis
+@item @code{package} (default: @code{radicale})
+The package that provides @command{radicale}.
+
+@item @code{config-file} (default: @code{%default-radicale-config-file})
+File-like object of the configuration file to use, by default it will listen
+on TCP port 5232 of @code{localhost} and use the @code{htpasswd} file at
+@file{/var/lib/radicale/users} with no (@code{plain}) encryption.
+
+@end table
+@end deftp
+
@node Messaging Services
@subsection Messaging Services
@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-string-list options
-A list of general options relating to SSL/TLS. These map to OpenSSL's
+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
@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
+authenticate using certificates. They will be authenticated using DNS@. See
@url{https://prosody.im/doc/s2s#security}.
Defaults to @samp{()}.
@end deftypevr
@item @code{cert-required?} (default: @code{#f})
If it is set to @code{#t} clients that use weak password authentication
-will not be accepted. Users must have completed the certificate wizard to join.
+will not be accepted. Users must have completed the certificate wizard to join.
@item @code{remember-channel?} (default: @code{#f})
Should murmur remember the last channel each user was in when they disconnected
@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
+the server's maximum bandwidth per client to unauthenticated users. In the
Mumble client, this information is shown in the Connect dialog.
Disabling this setting will prevent public listing of the server.
@table @asis
@item @code{name}
-This is a display name for your server. Not to be confused with the hostname.
+This is a display name for your server. Not to be confused with the hostname.
@item @code{password}
A password to identify your registration.
-Subsequent updates will need the same password. Don't lose your password.
+Subsequent updates will need the same password. Don't lose your password.
@item @code{url}
This should be a @code{http://} or @code{https://} link to your web
@table @asis
@item @code{config-file} (default: @code{(tailon-configuration-file)})
-The configuration file to use for Tailon. This can be set to a
+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}).
@table @asis
@item @code{files} (default: @code{(list "/var/log")})
-List of files to display. The list can include strings for a single file
+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.
Number of lines to read initially from each file.
@item @code{allowed-commands} (default: @code{(list "tail" "grep" "awk")})
-Commands to allow running. By default, @code{sed} is disabled.
+Commands to allow running. By default, @code{sed} is disabled.
@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
+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.
@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
+HTTP authentication type to use. Set to @code{#f} to disable
+authentication (the default). Supported values are @code{"digest"} or
@code{"basic"}.
@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
+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.
Bind the web interface to the specified address.
@item @code{base} (default: @code{"/"})
-Specify the path of the base URL. This can be useful if
+Specify the path of the base URL@. This can be useful if
@command{darkstat} is accessed via a reverse proxy.
@end table
@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:
+service, its value must be a @code{prometheus-node-exporter-configuration}.
@lisp
-(service prometheus-node-exporter-service-type
- (prometheus-node-exporter-configuration
- (web-listen-address ":9100")))
+(service prometheus-node-exporter-service-type)
@end lisp
@end defvar
@item @code{web-listen-address} (default: @code{":9100"})
Bind the web interface to the specified address.
+@item @code{textfile-directory} (default: @code{"/var/lib/prometheus/node-exporter"})
+This directory can be used to export metrics specific to this machine.
+Files containing metrics in the text format, with the filename ending in
+@code{.prom} should be placed in this directory.
+
+@item @code{extra-options} (default: @code{'()})
+Extra options to pass to the Prometheus node exporter.
+
@end table
@end deftp
Unique, case sensitive hostname which is required for active checks and
must match hostname as configured on the server.
-Defaults to @samp{"Zabbix server"}.
+Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{nslcd-configuration} parameter} log-option log
This option controls the way logging is done via a list containing
-SCHEME and LEVEL. The SCHEME argument may either be the symbols
+SCHEME and LEVEL@. The SCHEME argument may either be the symbols
@samp{none} or @samp{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: @samp{crit}, @samp{error}, @samp{warning},
The pid file used by the shepherd-service.
@item @code{config} (default: @code{(httpd-config-file)})
-The configuration file to use with the httpd service. The default value
+The configuration file to use with the httpd service. The default value
is a @code{httpd-config-file} record, but this can also be a different
-G-expression that generates a file, for example a @code{plain-file}. A
+G-expression that generates a file, for example a @code{plain-file}. A
file outside of the store can also be specified through a string.
@end table
The name of the module.
@item @code{file}
-The file for the module. This can be relative to the httpd package being
+The file for the module. This can be relative to the httpd package being
used, the absolute location of a file, or a G-expression for a file
within the store, for example @code{(file-append mod-wsgi
"/modules/mod_wsgi.so")}.
@table @asis
@item @code{modules} (default: @code{%default-httpd-modules})
-The modules to load. Additional modules can be added here, or loaded by
+The modules to load. Additional modules can be added here, or loaded by
additional configuration.
For example, in order to handle requests for PHP files, you can use Apache’s
@item @code{server-root} (default: @code{httpd})
The @code{ServerRoot} in the configuration file, defaults to the httpd
-package. Directives including @code{Include} and @code{LoadModule} are
+package. Directives including @code{Include} and @code{LoadModule} are
taken as relative to the server root.
@item @code{server-name} (default: @code{#f})
itself.
This doesn't need to be set in the server config, and can be specified
-in virtual hosts. The default is @code{#f} to not specify a
+in virtual hosts. The default is @code{#f} to not specify a
@code{ServerName}.
@item @code{document-root} (default: @code{"/srv/http"})
@item @code{listen} (default: @code{'("80")})
The list of values for the @code{Listen} directives in the config
-file. The value should be a list of strings, when each string can
+file. The value should be a list of strings, when each string can
specify the port number to listen on, and optionally the IP address and
protocol to use.
@item @code{pid-file} (default: @code{"/var/run/httpd"})
-The @code{PidFile} to use. This should match the @code{pid-file} set in
+The @code{PidFile} to use. This should match the @code{pid-file} set in
the @code{httpd-configuration} so that the Shepherd service is
configured correctly.
with the @var{log-directory} configuration option.
@deffn {Data Type} nginx-configuration
-This data type represents the configuration for NGinx. Some
+This data type represents the configuration for NGinx. Some
configuration can be done through this and the other provided record
types, or alternatively, a config file can be provided.
@anchor{nginx-location-configuration body}
@item @code{body}
-Body of the location block, specified as a list of strings. This can contain
+Body of the location block, specified as a list of strings. This can contain
many
configuration directives. For example, to pass requests to a upstream
server group defined using an @code{nginx-upstream-configuration} block,
host.
@item @code{settings-module}
-The settings module to use for Patchwork. As a Django application, Patchwork
-is configured with a Python module containing the settings. This can either be
+The settings module to use for Patchwork. As a Django application, Patchwork
+is configured with a Python module containing the settings. This can either be
an instance of the @code{<patchwork-settings-module>} record, any other record
that represents the settings in the store, or a directory outside of the
store.
@item @code{getmail-retriever-config}
The getmail-retriever-configuration record value to use with
-Patchwork. Getmail will be configured with this value, the messages will be
+Patchwork. Getmail will be configured with this value, the messages will be
delivered to Patchwork.
@end table
This setting relates to Django.
@item @code{allowed-hosts}
-A list of valid hosts for this Patchwork service. This should at least include
+A list of valid hosts for this Patchwork service. This should at least include
the domain specified in the @code{<patchwork-configuration>} record.
This is a Django setting.
This is a Patchwork setting.
@item @code{static-url} (default: @code{#f})
-The URL to use when serving static assets. It can be part of a URL, or a full
+The URL to use when serving static assets. It can be part of a URL, or a full
URL, but must end in a @code{/}.
If the default value is used, the @code{static-path} value from the
to the Let's Encrypt certificate authority (CA) to sign the key. The CA
checks that the request originates from the host in question by using a
challenge-response protocol, requiring the server to provide its
-response over HTTP. If that protocol completes successfully, the CA
+response over HTTP@. If that protocol completes successfully, the CA
signs the key, resulting in a certificate. That certificate is valid
for a limited period of time, and therefore to continue to provide TLS
services, the server needs to periodically ask the CA to renew its
@table @asis
@item @code{id} (default: @code{""})
-An identifier for other configuration fields to refer to this key. IDs must
+An identifier for other configuration fields to refer to this key. IDs must
be unique and must not be empty.
@item @code{algorithm} (default: @code{#f})
@table @asis
@item @code{id} (default: @code{""})
-An identifier for other configuration fields to refer to this key. IDs must be
+An identifier for other configuration fields to refer to this key. IDs must be
unique and must not be empty.
@item @code{address} (default: @code{'()})
that a key is not require to match that ACL.
@item @code{action} (default: @code{'()})
-An ordered list of actions that are permitted or forbidden by this ACL. Possible
+An ordered list of actions that are permitted or forbidden by this ACL@. Possible
values are lists of zero or more elements from @code{'transfer}, @code{'notify}
and @code{'update}.
@table @asis
@item @code{id} (default: @code{""})
-An identifier for other configuration fields to refer to this remote. IDs must
+An identifier for other configuration fields to refer to this remote. IDs must
be unique and must not be empty.
@item @code{address} (default: @code{'()})
@item @code{via} (default: @code{'()})
An ordered list of source IP addresses. An empty list will have Knot choose
-an appropriate source IP. An optional port can be given with the @@ separator.
+an appropriate source IP@. An optional port can be given with the @@ separator.
The default is to choose at random.
@item @code{key} (default: @code{#f})
An algorithm of signing keys and issued signatures.
@item @code{ksk-size} (default: @code{256})
-The length of the KSK. Note that this value is correct for the default
+The length of the KSK@. Note that this value is correct for the default
algorithm, but would be unsecure for other algorithms.
@item @code{zsk-size} (default: @code{256})
-The length of the ZSK. Note that this value is correct for the default
+The length of the ZSK@. Note that this value is correct for the default
algorithm, but would be unsecure for other algorithms.
@item @code{dnskey-ttl} (default: @code{'default})
@item @code{tftp-root} (default: @code{/var/empty,lo})
Look for files to transfer using TFTP relative to the given directory.
-When this is set, TFTP paths which include ".." are rejected, to stop clients
-getting outside the specified root. Absolute paths (starting with /) are
-allowed, but they must be within the tftp-root. If the optional interface
+When this is set, TFTP paths which include @samp{..} are rejected, to stop clients
+getting outside the specified root. Absolute paths (starting with @samp{/}) are
+allowed, but they must be within the TFTP-root. If the optional interface
argument is given, the directory is only used for TFTP requests via that
interface.
directory exists. Defaults to adding IP address (in standard dotted-quad
format).
-For instance, if --tftp-root is "/tftp" and client 1.2.3.4 requests file
-"myfile" then the effective path will be "/tftp/1.2.3.4/myfile" if
-/tftp/1.2.3.4 exists or /tftp/myfile otherwise. When "=mac" is specified
-it will append the MAC address instead, using lowercase zero padded digits
-separated by dashes, e.g.: 01-02-03-04-aa-bb Note that resolving MAC
-addresses is only possible if the client is in the local network or obtained
-a DHCP lease from dnsmasq.
+For instance, if @option{--tftp-root} is @samp{/tftp} and client
+@samp{1.2.3.4} requests file @file{myfile} then the effective path will
+be @file{/tftp/1.2.3.4/myfile} if @file{/tftp/1.2.3.4} exists or
+@file{/tftp/myfile} otherwise. When @samp{=mac} is specified it will
+append the MAC address instead, using lowercase zero padded digits
+separated by dashes, e.g.: @samp{01-02-03-04-aa-bb}. Note that
+resolving MAC addresses is only possible if the client is in the local
+network or obtained a DHCP lease from dnsmasq.
@end table
@end deftp
The @code{(gnu services vpn)} module provides services related to
@dfn{virtual private networks} (VPNs). It provides a @emph{client} service for
your machine to connect to a VPN, and a @emph{server} service for your machine
-to host a VPN. Both services use @uref{https://openvpn.net/, OpenVPN}.
+to host a VPN@. Both services use @uref{https://openvpn.net/, OpenVPN}.
@deffn {Scheme Procedure} openvpn-client-service @
[#:config (openvpn-client-configuration)]
@end deftypevr
-@deftypevr {@code{openvpn-client-configuration} parameter} string ca
+If you do not have some of these files (eg.@: you use a username and
+password), you can disable any of the following three fields by setting
+it to @code{'disabled}.
+
+@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string ca
The certificate authority to check connections against.
Defaults to @samp{"/etc/openvpn/ca.crt"}.
@end deftypevr
-@deftypevr {@code{openvpn-client-configuration} parameter} string cert
+@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string cert
The certificate of the machine the daemon is running on. It should be
signed by the authority given in @code{ca}.
@end deftypevr
-@deftypevr {@code{openvpn-client-configuration} parameter} string key
+@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string key
The key of the machine the daemon is running on. It must be the key whose
certificate is @code{cert}.
@end deftypevr
-@deftypevr {@code{openvpn-server-configuration} parameter} string ca
+If you do not have some of these files (eg.@: you use a username and
+password), you can disable any of the following three fields by setting
+it to @code{'disabled}.
+
+@deftypevr {@code{openvpn-server-configuration} parameter} maybe-string ca
The certificate authority to check connections against.
Defaults to @samp{"/etc/openvpn/ca.crt"}.
@end deftypevr
-@deftypevr {@code{openvpn-server-configuration} parameter} string cert
+@deftypevr {@code{openvpn-server-configuration} parameter} maybe-string cert
The certificate of the machine the daemon is running on. It should be
signed by the authority given in @code{ca}.
@end deftypevr
-@deftypevr {@code{openvpn-server-configuration} parameter} string key
+@deftypevr {@code{openvpn-server-configuration} parameter} maybe-string key
The key of the machine the daemon is running on. It must be the key whose
certificate is @code{cert}.
Location of the log file used by the web interface.
@item @code{queries-log-file} (default: @code{#f})
-Location of the SQL queries log file. By default, SQL queries logging is
+Location of the SQL queries log file. By default, SQL queries logging is
disabled.
@item @code{web-queries-log-file} (default: @code{#f})
-Location of the web SQL queries log file. By default, web SQL queries
+Location of the web SQL queries log file. By default, web SQL queries
logging is disabled.
@item @code{cache-directory} (default: @code{"/var/cache/cuirass"})
Number of seconds between the poll of the repositories followed by the
Cuirass jobs.
+@item @code{queue-size} (default: @code{1})
+Size of the database writer queue.
+
@item @code{database} (default: @code{"/var/lib/cuirass/cuirass.db"})
Location of sqlite database which contains the build results and previously
added specifications.
@end deftypevr
@deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-ac
-Set CPU performance versus energy saving policy on AC. Alternatives are
+Set CPU performance versus energy saving policy on AC@. Alternatives are
performance, normal, powersave.
Defaults to @samp{"performance"}.
@item @code{always-on?} (default: @code{#f})
If set to @code{#t}, then MPD attempts to keep this audio output always
-open. This may be useful for streaming servers, when you don’t want to
+open. This may be useful for streaming servers, when you don’t want to
disconnect all listeners even when playback is accidentally stopped.
@item @code{mixer-type}
@subsubheading Libvirt daemon
@code{libvirtd} is the server side daemon component of the libvirt
-virtualization management system. This daemon runs on host servers
+virtualization management system. This daemon runs on host servers
and performs required management tasks for virtualized guests.
@deffn {Scheme Variable} libvirt-service-type
@end deftypevr
@deftypevr {@code{libvirt-configuration} parameter} optional-string host-uuid
-Host UUID. UUID must not have all digits be the same.
+Host UUID@. UUID must not have all digits be the same.
Defaults to @samp{""}.
used to manage logs from virtual machine consoles.
This daemon is not used directly by libvirt client applications, rather it
-is called on their behalf by @code{libvirtd}. By maintaining the logs in a
+is called on their behalf by @code{libvirtd}. By maintaining the logs in a
standalone daemon, the main @code{libvirtd} daemon can be restarted without
-risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec()
+risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec()
itself upon receiving @code{SIGUSR1}, to allow live upgrades without downtime.
@deffn {Scheme Variable} virtlog-service-type
The list of emulated QEMU platforms. Each item must be a @dfn{platform
object} as returned by @code{lookup-qemu-platforms} (see below).
-@item @code{guix-support?} (default: @code{#f})
+@item @code{guix-support?} (default: @code{#t})
When it is true, QEMU and all its dependencies are added to the build
environment of @command{guix-daemon} (@pxref{Invoking guix-daemon,
@option{--chroot-directory} option}). This allows the @code{binfmt_misc}
@noindent
and it will build Inkscape for ARMv7 @emph{as if it were a native
-build}, transparently using QEMU to emulate the ARMv7 CPU. Pretty handy
+build}, transparently using QEMU to emulate the ARMv7 CPU@. Pretty handy
if you'd like to test a package build for an architecture you don't have
access to!
+When @code{guix-support?} is set to @code{#f}, programs for other
+architectures can still be executed transparently, but invoking commands
+like @command{guix build -s armhf-linux @dots{}} will fail.
+
@item @code{qemu} (default: @code{qemu})
The QEMU package to use.
@end table
@deftp {Data Type} git-http-configuration
Data type representing the configuration for a future
@code{git-http-service-type}; can currently be used to configure Nginx
-trough @code{git-http-nginx-location-configuration}.
+through @code{git-http-nginx-location-configuration}.
@table @asis
@item @code{package} (default: @var{git})
This example assumes that you are using Let's Encrypt to get your TLS
certificate. @xref{Certificate Services}. The default @code{certbot}
service will redirect all HTTP traffic on @code{git.my-host.org} to
-HTTPS. You will also need to add an @code{fcgiwrap} proxy to your
+HTTPS@. You will also need to add an @code{fcgiwrap} proxy to your
system services. @xref{Web Services}.
@end deffn
contents.
A value like @code{#o0027} will give read access to the group used by Gitolite
-(by default: @code{git}). This is necessary when using Gitolite with software
+(by default: @code{git}). This is necessary when using Gitolite with software
like cgit or gitweb.
@item @code{git-config-keys} (default: @code{""})
-Gitolite allows you to set git config values using the @samp{config} keyword. This
-setting allows control over the config keys to accept.
+Gitolite allows you to set git config values using the @samp{config}
+keyword. This setting allows control over the config keys to accept.
@item @code{roles} (default: @code{'(("READERS" . 1) ("WRITERS" . ))})
Set the role names allowed to be used by users running the perms command.
@end quotation
The Guix Build Coordinator consists of one @dfn{coordinator}, and one or
-more connected @dfn{agent} processes. The coordinator process handles
-clients submitting builds, and allocating builds to agents. The agent
+more connected @dfn{agent} processes. The coordinator process handles
+clients submitting builds, and allocating builds to agents. The agent
processes talk to a build daemon to actually perform the builds, then
send the results back to the coordinator.
A file containing the password to use when connecting to the
coordinator.
-@item @code{systems} (default: @var{#f})
+@item @code{systems} (default: @code{#f})
The systems for which this agent should fetch builds. The agent process
will use the current system it's running on as the default.
@item @code{max-parallel-builds} (default: @code{1})
The number of builds to perform in parallel.
-@item @code{derivation-substitute-urls} (default: @code{1})
+@item @code{derivation-substitute-urls} (default: @code{#f})
URLs from which to attempt to fetch substitutes for derivations, if the
derivations aren't already available.
-@item @code{non-derivation-substitute-urls} (default: @code{1})
+@item @code{non-derivation-substitute-urls} (default: @code{#f})
URLs from which to attempt to fetch substitutes for build inputs, if the
input store items aren't already available.
The @code{(gnu services security-token)} module provides the following service
to run @command{pcscd}, the PC/SC Smart Card Daemon. @command{pcscd} is the
-daemon program for pcsc-lite and the MuscleCard framework. It is a resource
+daemon program for pcsc-lite and the MuscleCard framework. It is a resource
manager that coordinates communications with smart card readers, smart cards
and cryptographic tokens that are connected to the system.
@item @code{pcsc-lite} (default: @code{pcsc-lite})
The pcsc-lite package that provides pcscd.
@item @code{usb-drivers} (default: @code{(list ccid)})
-List of packages that provide USB drivers to pcscd. Drivers are expected to be
+List of packages that provide USB drivers to pcscd. Drivers are expected to be
under @file{pcsc/drivers} in the store directory of the package.
@end table
@end deftp
@itemx rpc
@itemx services
@itemx shadow
-The system databases handled by the NSS. Each of these fields must be a
+The system databases handled by the NSS@. Each of these fields must be a
list of @code{<name-service>} objects (see below).
@end table
@end deftp
The @code{base-initrd} procedure is built from @code{raw-initrd} procedure.
Unlike @code{base-initrd}, @code{raw-initrd} doesn't do anything high-level,
such as trying to guess which kernel modules and packages should be included
-to the initrd. An example use of @code{raw-initrd} is when a user has
+to the initrd. An example use of @code{raw-initrd} is when a user has
a custom Linux kernel configuration and default kernel modules included by
@code{base-initrd} are not available.
@var{linux-modules} is a list of kernel modules to be loaded at boot time.
@var{mapped-devices} is a list of device mappings to realize before
@var{file-systems} are mounted (@pxref{Mapped Devices}).
-@var{helper-packages} is a list of packages to be copied in the initrd. It may
+@var{helper-packages} is a list of packages to be copied in the initrd.
+ It may
include @code{e2fsck/static} or other packages needed by the initrd to check
the root file system.
@cindex EFI, bootloader
@cindex UEFI, bootloader
@cindex BIOS, bootloader
-The bootloader to use, as a @code{bootloader} object. For now
+The bootloader to use, as a @code{bootloader} object. For now
@code{grub-bootloader}, @code{grub-efi-bootloader},
@code{grub-efi-netboot-bootloader}, @code{extlinux-bootloader} and
@code{u-boot-bootloader} are supported.
@vindex grub-efi-netboot-bootloader
@code{grub-efi-netboot-bootloader} allows you to boot your system over network
-through TFTP. In combination with an NFS root file system this allows you to
+through TFTP@. In combination with an NFS root file system this allows you to
build a diskless Guix system.
The installation of the @code{grub-efi-netboot-bootloader} generates the content
It is important to note that symlinks pointing outside the TFTP root directory
may need to be allowed in the configuration of your TFTP server. Further the
-store link exposes the whole store through TFTP. Both points need to be
+store link exposes the whole store through TFTP@. Both points need to be
considered carefully for security aspects.
Beside the @code{grub-efi-netboot-bootloader}, the already mentioned TFTP and
@cindex System images, creation in various formats
@cindex Creating system images in various formats
@item vm-image
-@itemx disk-image
+@itemx image
@itemx docker-image
Return a virtual machine, disk image, or Docker image of the operating
system declared in @var{file} that stands alone. By default,
the @option{--image-size} option is ignored in the case of
@code{docker-image}.
-The @code{disk-image} command can produce various image types. The
-image type can be selected using the @command{--image-type} option. It
-defaults to @code{raw}. When its value is @code{iso9660}, the
+@cindex image, creating disk images
+The @code{image} command can produce various image types. The
+image type can be selected using the @option{--image-type} option. It
+defaults to @code{efi-raw}. When its value is @code{iso9660}, the
@option{--label} option can be used to specify a volume ID with
-@code{disk-image}.
+@code{image}. By default, the root file system of a disk image is
+mounted non-volatile; the @option{--volatile} option can be provided to
+make it volatile instead. When using @code{image}, the bootloader
+installed on the generated image is taken from the provided
+@code{operating-system} definition. The following example demonstrates
+how to generate an image that uses the @code{grub-efi-bootloader}
+bootloader and boot it with QEMU:
-When using the @code{raw} image type, a raw disk image is produced; it
-can be copied as is to a USB stick, for instance. Assuming
+@example
+image=$(guix system image --image-type=qcow2 \
+ gnu/system/examples/lightweight-desktop.tmpl)
+cp $image /tmp/my-image.qcow2
+chmod +w /tmp/my-image.qcow2
+qemu-system-x86_64 -enable-kvm -hda /tmp/my-image.qcow2 -m 1000 \
+ -bios $(guix build ovmf)/share/firmware/ovmf_x64.bin
+@end example
+
+When using the @code{efi-raw} image type, a raw disk image is produced;
+it can be copied as is to a USB stick, for instance. Assuming
@code{/dev/sdc} is the device corresponding to a USB stick, one can copy
the image to it using the following command:
@example
-# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc status=progress
+# dd if=$(guix system image my-os.scm) of=/dev/sdc status=progress
@end example
The @code{--list-image-types} command lists all the available image
types.
+@cindex vm-image, creating virtual machine images
When using @code{vm-image}, the returned image is in qcow2 format, which
-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.
-
+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. The
+@code{grub-bootloader} bootloader is always used independently of what
+is declared in the @code{operating-system} file passed as argument.
+This is to make it easier to work with QEMU, which uses the SeaBIOS BIOS
+by default, expecting a bootloader to be installed in the Master Boot
+Record (MBR).
+
+@cindex docker-image, creating docker images
When using @code{docker-image}, a Docker image is produced. Guix builds
the image from scratch, not from a pre-existing Docker base image. As a
result, it contains @emph{exactly} what you define in the operating
@item --image-type=@var{type}
@itemx -t @var{type}
-For the @code{disk-image} action, create an image with given @var{type}.
+For the @code{image} action, create an image with given @var{type}.
-When this option is omitted, @command{guix system} uses the @code{raw}
-image type.
+When this option is omitted, @command{guix system} uses the
+@code{efi-raw} image type.
@cindex ISO-9660 format
@cindex CD image format
for burning on CDs and DVDs.
@item --image-size=@var{size}
-For the @code{vm-image} and @code{disk-image} actions, create an image
+For the @code{vm-image} and @code{image} actions, create an image
of the given @var{size}. @var{size} may be a number of bytes, or it may
include a unit as a suffix (@pxref{Block size, size specifications,,
coreutils, GNU Coreutils}).
@table @code
@item extension-graph
-Emit in Dot/Graphviz format to standard output the @dfn{service
+Emit to standard output the @dfn{service
extension graph} of the operating system defined in @var{file}
(@pxref{Service Composition}, for more information on service
-extensions).
+extensions). By default the output is in Dot/Graphviz format, but you
+can choose a different format with @option{--graph-backend}, as with
+@command{guix graph} (@pxref{Invoking guix graph, @option{--backend}}):
The command:
@anchor{system-shepherd-graph}
@item shepherd-graph
-Emit in Dot/Graphviz format to standard output the @dfn{dependency
+Emit to standard output the @dfn{dependency
graph} of shepherd services of the operating system defined in
@var{file}. @xref{Shepherd Services}, for more information and for an
example graph.
+Again, the default output format is Dot/Graphviz, but you can pass
+@option{--graph-backend} to select a different one.
+
@end table
@node Invoking guix deploy
@table @asis
@item @code{ssh-key}
The path to the SSH private key to use to authenticate with the remote
-host. In the future, this field may not exist.
+host. In the future, this field may not exist.
@item @code{tags}
-A list of string ``tags'' that uniquely identify the machine. Must be given
+A list of string ``tags'' that uniquely identify the machine. Must be given
such that no two machines in the deployment have the same set of tags.
@item @code{region}
A Digital Ocean region slug, such as @code{"nyc3"}.
@command{qemu}. See previous section for further information on how to do this.
Spice also allows you to do some nice stuff like share your clipboard with your
-VM. To enable that you'll also have to pass the following flags to @command{qemu}:
+VM@. To enable that you'll also have to pass the following flags to @command{qemu}:
@example
-device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5
This is the service type that extensions target when they want to create
shepherd services (@pxref{Service Types and Services}, for an example).
-Each extension must pass a list of @code{<shepherd-service>}.
+Each extension must pass a list of @code{<shepherd-service>}. Its
+value must be a @code{shepherd-configuration}, as described below.
@end defvr
+@deftp {Data Type} shepherd-configuration
+This data type represents the Shepherd's configuration.
+
+@table @code
+@item shepherd (default: @code{shepherd})
+The Shepherd package to use.
+
+@item services (default: @code{'()})
+A list of @code{<shepherd-service>} to start.
+You should probably use the service extension
+mechanism instead (@pxref{Shepherd Services}).
+@end table
+@end deftp
+
@defvr {Scheme Variable} %shepherd-root-service
This service represents PID@tie{}1.
@end defvr
The problem with debugging information is that is takes up a fair amount
of disk space. For example, debugging information for the GNU C Library
-weighs in at more than 60 MiB. Thus, as a user, keeping all the
+weighs in at more than 60 MiB@. Thus, as a user, keeping all the
debugging info of all the installed programs is usually not an option.
Yet, space savings should not come at the cost of an impediment to
debugging---especially in the GNU system, which should make it easier
``from nothing''. Remember that the build environment of a derivation
contains nothing but its declared inputs (@pxref{Introduction}). So
there's an obvious chicken-and-egg problem: how does the first package
-get built? How does the first compiler get compiled? Note that this is
-a question of interest only to the curious hacker, not to the regular
-user, so you can shamelessly skip this section if you consider yourself
-a ``regular user''.
+get built? How does the first compiler get compiled?
+
+It is tempting to think of this question as one that only die-hard
+hackers may care about. However, while the answer to that question is
+technical in nature, its implications are wide-ranging. How the
+distribution is bootstrapped defines the extent to which we, as
+individuals and as a collective of users and hackers, can trust the
+software we run. It is a central concern from the standpoint of
+@emph{security} and from a @emph{user freedom} viewpoint.
@cindex bootstrap binaries
The GNU system is primarily made of C code, with libc at its core. The
HCoop / jackhill / guix / guix.git / blobdiff