Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
-Copyright @copyright{} 2015, 2016, 2017, 2019, 2020 Leo Famulari@*
+Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari@*
Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
-Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
-Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Efraim Flashner@*
+Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@*
+Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016, 2017 Nikita Gillmann@*
Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@*
Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
-Copyright @copyright{} 2016, 2017, 2018, 2019 Christopher Baines@*
+Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 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 humanitiesNerd@*
-Copyright @copyright{} 2017 Christopher Allan Webber@*
+Copyright @copyright{} 2017, 2021 Christopher Lemmer Webber@*
Copyright @copyright{} 2017, 2018, 2019, 2020 Marius Bakke@*
Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
-Copyright @copyright{} 2017, 2019, 2020 Maxim Cournoyer@*
-Copyright @copyright{} 2017, 2018, 2019, 2020 Tobias Geerinckx-Rice@*
+Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@*
+Copyright @copyright{} 2017, 2018, 2019, 2020, 2021 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
Copyright @copyright{} 2017, 2018, 2019, 2020 Arun Isaac@*
Copyright @copyright{} 2020 Pierre Langlois@*
Copyright @copyright{} 2020 pinoaffe@*
Copyright @copyright{} 2020 André Batista@*
-Copyright @copyright{} 2020 Alexandru-Sergiu Marton@*
+Copyright @copyright{} 2020, 2021 Alexandru-Sergiu Marton@*
Copyright @copyright{} 2020 raingloom@*
Copyright @copyright{} 2020 Daniel Brooks@*
Copyright @copyright{} 2020 John Soo@*
Copyright @copyright{} 2020 Jonathan Brielmaier@*
+Copyright @copyright{} 2020 Edgar Vincent@*
+Copyright @copyright{} 2021 Maxime Devos@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
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?
* Using a Custom Guix Channel:: Using a customized Guix.
* Replicating Guix:: Running the @emph{exact same} Guix.
* Channel Authentication:: How Guix verifies what it fetches.
+* Channels with Substitutes:: Using channels with available substitutes.
* Creating a Channel:: How to write your custom channel.
* Package Modules in a Sub-directory:: Specifying the channel's package modules location.
* Declaring Channel Dependencies:: How to depend on other channels.
* DNS Services:: DNS daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
-* Continuous Integration:: The Cuirass service.
+* Continuous Integration:: Cuirass and Laminar services.
* Power Management Services:: Extending battery life.
* Audio Services:: The MPD.
* Virtualization Services:: Virtualization services.
architecture still works. Should someone decide they wish to revive this
architecture then the code is still available.
+@item powerpc64le-linux
+little-endian 64-bit Power ISA processors, Linux-Libre kernel. This
+includes POWER9 systems such as the
+@uref{https://www.fsf.org/news/talos-ii-mainboard-and-talos-ii-lite-mainboard-now-fsf-certified-to-respect-your-freedom,
+RYF Talos II mainboard}. This platform is available as a "technology
+preview": although it is supported, substitutes are not yet available
+from the build farm (@pxref{Substitutes}), and some packages may fail to
+build (@pxref{Tracking Bugs and Patches}). That said, the Guix
+community is actively working on improving this support, and now is a
+great time to try it and get involved!
+
@end table
With Guix@tie{}System, you @emph{declare} all aspects of the operating system
graphical environment or system services of your choice.
Guix System is available on all the above platforms except
-@code{mips64el-linux}.
+@code{mips64el-linux} and @code{powerpc64le-linux}.
@noindent
For information on porting to other architectures or kernels,
then run this command to import it:
@example
-$ wget @value{OPENPGP-SIGNING-KEY-URL} \
+$ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
-qO - | gpg --import -
@end example
@item
@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
or later;
-@item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib};
+@item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib},
+version 0.1.0 or later;
@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.
+@c FIXME: We need the #:fetch-options parameter of 'submodule-update',
+@c which appeared in 0.5.0. Change below after string freeze.
@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.3.0
or later;
@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
version 0.13.0 or later.
+@item
+@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
+@uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for
+the @code{go} importer (@pxref{Invoking guix import}) and for some of
+the ``updaters'' (@pxref{Invoking guix refresh}).
+
@item
When @url{http://www.bzip.org, libbz2} is available,
@command{guix-daemon} can use it to compress build logs.
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
+
+The @option{--show-duration=yes} option can be used to print the
+duration of the individual test cases, when used in combination with
+@option{--brief=no}:
+
+@example
+make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes"
+@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
@c for why `-G' is needed.
@example
# groupadd --system guixbuild
-# for i in `seq -w 1 10`;
+# for i in $(seq -w 1 10);
do
useradd -g guixbuild -G guixbuild \
- -d /var/empty -s `which nologin` \
+ -d /var/empty -s $(which nologin) \
-c "Guix build user $i" --system \
guixbuilder$i;
done
@code{guix_daemon_socket_t} isn’t actually used. None of the socket
operations involve contexts that have anything to do with
@code{guix_daemon_socket_t}. It doesn’t hurt to have this unused label,
-but it would be preferrable to define socket rules for only this label.
+but it would be preferable to define socket rules for only this label.
@item
@code{guix gc} cannot access arbitrary links to profiles. By design,
The build directory is automatically deleted upon completion, unless the
build failed and the client specified @option{--keep-failed}
-(@pxref{Invoking guix build, @option{--keep-failed}}).
+(@pxref{Common Build Options, @option{--keep-failed}}).
The daemon listens for connections and spawns one sub-process for each session
started by a client (one of the @command{guix} sub-commands). The
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}
@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}.
explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.
The difference matters here, because @command{guix pull} updates
-the @command{guix} command and package definitions only for the user it is ran
+the @command{guix} command and package definitions only for the user it is run
as. This means that if you choose to use @command{guix system reconfigure} in
root's login shell, you'll need to @command{guix pull} separately.
@end quotation
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
guix install emacs
@end example
-You've installed your first package, congrats! In the process, you've
+@cindex profile
+You've installed your first package, congrats! The package is now
+visible in your default @dfn{profile}, @file{$HOME/.guix-profile}---a
+profile is a directory containing installed packages.
+In the process, you've
probably noticed that Guix downloaded pre-built binaries; or, if you
explicitly chose to @emph{not} use pre-built binaries, then probably
Guix is still building software (@pxref{Substitutes}, for more info).
@cindex removing packages
@cindex package installation
@cindex package removal
+@cindex profile
The @command{guix package} command is the tool that allows users to
install, upgrade, and remove packages, as well as rolling back to
-previous configurations. It operates only on the user's own profile,
+previous configurations. These operations work on a user
+@dfn{profile}---a directory of installed packages. Each user has a
+default profile in @file{$HOME/.guix-profile}.
+The command operates only on the user's own profile,
and works with normal user privileges (@pxref{Features}). Its syntax
is:
@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
@file{bar} would lead to that recommendation.
+@cindex profile, choosing
@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.
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
For example, this command:
@example
-guix gc --derivers `guix package -I ^emacs$ | cut -f4`
+guix gc --derivers $(guix package -I ^emacs$ | cut -f4)
@end example
@noindent
Inferior packages can be used transparently like any other package or
file-like object in G-expressions (@pxref{G-Expressions}). They are also
transparently handled by the @code{packages->manifest} procedure, which is
-commonly use in manifests (@pxref{Invoking guix package, the
+commonly used in manifests (@pxref{Invoking guix package, the
@option{--manifest} option of @command{guix package}}). Thus you can insert
an inferior package pretty much anywhere you would insert a regular package:
in manifests, in the @code{packages} field of your @code{operating-system}
* Using a Custom Guix Channel:: Using a customized Guix.
* Replicating Guix:: Running the @emph{exact same} Guix.
* Channel Authentication:: How Guix verifies what it fetches.
+* Channels with Substitutes:: Using channels with available substitutes.
* Creating a Channel:: How to write your custom channel.
* Package Modules in a Sub-directory:: Specifying the channel's package modules location.
* Declaring Channel Dependencies:: How to depend on other channels.
If you're curious about the authentication mechanics, read on!
+@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.
+
@node Creating a Channel
@section Creating a Channel
(version 0)
(dependencies
(channel
- (name 'some-collection)
+ (name some-collection)
(url "https://example.org/first-collection.git")
;; The 'introduction' bit below is optional: you would
(commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
(signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
(channel
- (name 'some-other-collection)
+ (name some-other-collection)
(url "https://example.org/second-collection.git")
(branch "testing"))))
@end lisp
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.
-
@c *********************************************************************
@node Development
@chapter Development
log-in shells. @xref{Bash Startup Files,,, bash, The GNU Bash Reference
Manual}, for details on Bash start-up files.}.
+Exiting from a Guix environment is the same as exiting from the shell,
+and will place the user back in the old environment before @command{guix
+environment} was invoked. The next garbage collection (@pxref{Invoking
+guix gc}) will clean up packages that were installed from within the
+environment and are no longer used outside of it.
+
@vindex GUIX_ENVIRONMENT
@command{guix environment} defines the @env{GUIX_ENVIRONMENT}
variable in the shell it spawns; its value is the file name of the
@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
In a nutshell, packages using it are configured, built, and installed with
the usual @code{./configure && make && make check && make install}
command sequence. In practice, a few additional steps are often needed.
-All these steps are split up in separate @dfn{phases},
-notably@footnote{Please see the @code{(guix build gnu-build-system)}
-modules for more details about the build phases.}:
-
-@table @code
-@item unpack
-Unpack the source tarball, and change the current directory to the
-extracted source tree. If the source is actually a directory, copy it
-to the build tree, and enter that directory.
-
-@item patch-source-shebangs
-Patch shebangs encountered in source files so they refer to the right
-store file names. For instance, this changes @code{#!/bin/sh} to
-@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
-
-@item configure
-Run the @file{configure} script with a number of default options, such
-as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified
-by the @code{#:configure-flags} argument.
-
-@item build
-Run @code{make} with the list of flags specified with
-@code{#:make-flags}. If the @code{#:parallel-build?} argument is true
-(the default), build with @code{make -j}.
-
-@item check
-Run @code{make check}, or some other target specified with
-@code{#:test-target}, unless @code{#:tests? #f} is passed. If the
-@code{#:parallel-tests?} argument is true (the default), run @code{make
-check -j}.
-
-@item install
-Run @code{make install} with the flags listed in @code{#:make-flags}.
-
-@item patch-shebangs
-Patch shebangs on the installed executable files.
-
-@item strip
-Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
-is false), copying them to the @code{debug} output when available
-(@pxref{Installing Debugging Files}).
-@end table
-
-@vindex %standard-phases
-The build-side module @code{(guix build gnu-build-system)} defines
-@code{%standard-phases} as the default list of build phases.
-@code{%standard-phases} is a list of symbol/procedure pairs, where the
-procedure implements the actual phase.
-
+All these steps are split up in separate @dfn{phases}.
@xref{Build Phases}, for more info on build phases and ways to customize
them.
build-system gnu)} module for a complete list). We call these the
@dfn{implicit inputs} of a package, because package definitions do not
have to mention them.
+
+This build system supports a number of keyword arguments, which can be
+passed @i{via} the @code{arguments} field of a package. Here are some
+of the main parameters:
+
+@table @code
+@item #:phases
+This argument specifies build-side code that evaluates to an alist of
+build phases. @xref{Build Phases}, for more information.
+
+@item #:configure-flags
+This is a list of flags (strings) passed to the @command{configure}
+script. @xref{Defining Packages}, for an example.
+
+@item #:make-flags
+This list of strings contains flags passed as arguments to
+@command{make} invocations in the @code{build}, @code{check}, and
+@code{install} phases.
+
+@item #:out-of-source?
+This Boolean, @code{#f} by default, indicates whether to run builds in a
+build directory separate from the source tree.
+
+When it is true, the @code{configure} phase creates a separate build
+directory, changes to that directory, and runs the @code{configure}
+script from there. This is useful for packages that require it, such as
+@code{glibc}.
+
+@item #:tests?
+This Boolean, @code{#t} by default, indicates whether the @code{check}
+phase should run the package's test suite.
+
+@item #:test-target
+This string, @code{"check"} by default, gives the name of the makefile
+target used by the @code{check} phase.
+
+@item #:parallel-build?
+@itemx #:parallel-tests?
+These Boolean values specify whether to build, respectively run the test
+suite, in parallel, with the @code{-j} flag of @command{make}. When
+they are true, @code{make} is passed @code{-j@var{n}}, where @var{n} is
+the number specified as the @option{--cores} option of
+@command{guix-daemon} or that of the @command{guix} client command
+(@pxref{Common Build Options, @option{--cores}}).
+
+@cindex RUNPATH, validation
+@item #:validate-runpath?
+This Boolean, @code{#t} by default, determines whether to ``validate''
+the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well
+as executables) previously installed by the @code{install} phase.
+
+This validation step consists in making sure that all the shared
+libraries needed by an ELF binaries, which are listed as
+@code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the
+@code{DT_RUNPATH} entry of that binary. In other words, it ensures that
+running or using those binaries will not result in a ``file not found''
+error at run time. @xref{Options, @option{-rpath},, ld, The GNU
+Linker}, for more information on @code{RUNPATH}.
+
+@item #:substitutable?
+This Boolean, @code{#t} by default, tells whether the package outputs
+should be substitutable---i.e., whether users should be able to obtain
+substitutes for them instead of building locally (@pxref{Substitutes}).
+
+@item #:allowed-references
+@itemx #:disallowed-references
+When true, these arguments must be a list of dependencies that must not
+appear among the references of the build results. If, upon build
+completion, some of these references are retained, the build process
+fails.
+
+This is useful to ensure that a package does not erroneously keep a
+reference to some of it build-time inputs, in cases where doing so
+would, for example, unnecessarily increase its size (@pxref{Invoking
+guix size}).
+@end table
+
+Most other build systems support these keyword arguments.
@end defvr
Other @code{<build-system>} objects are defined to support other
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.
It adds @code{rustc} and @code{cargo} to the set of inputs.
A different Rust package can be specified with the @code{#:rust} parameter.
-Regular cargo dependencies should be added to the package definition via the
-@code{#:cargo-inputs} parameter as a list of name and spec pairs, where the
+Regular cargo dependencies should be added to the package definition similarly
+to other packages; those needed only at build time to native-inputs, others to
+inputs. If you need to add source-only crates then you should add them to via
+the @code{#:cargo-inputs} parameter as a list of name and spec pairs, where the
spec can be a package or a source definition. Note that the spec must
evaluate to a path to a gzipped tarball which includes a @code{Cargo.toml}
file at its root, or it will be ignored. Similarly, cargo dev-dependencies
specified in the @code{#:cargo-inputs} and @code{#:cargo-development-inputs}
parameters available to cargo. It will also remove an included
@code{Cargo.lock} file to be recreated by @code{cargo} during the
-@code{build} phase. The @code{install} phase installs the binaries
-defined by the crate.
+@code{build} phase. The @code{package} phase will run @code{cargo package}
+to create a source crate for future use. The @code{install} phase installs
+the binaries defined by the crate. Unless @code{install-source? #f} is
+defined it will also install a source crate repository of itself and unpacked
+sources, to ease in future hacking on rust packages.
@end defvr
@defvr {Scheme Variable} chicken-build-system
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}.
+
+The Julia package name is read from the file @file{Project.toml}. This
+value can be overridden by passing the argument @code{#:julia-package-name}
+(which must be correctly capitalized).
-Julia packages require the source @code{file-name} to be the real name of the
-package, correctly capitalized.
+Julia packages usually manage their binary dependencies via
+@code{JLLWrappers.jl}, a Julia package that creates a module (named
+after the wrapped library followed by @code{_jll.jl}.
-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
-variable = /gnu/store/library.so} for each dependency, plus a void function
-@code{check_deps() = nothing}.
+To add the binary path @code{_jll.jl} packages, you need to patch the
+files under @file{src/wrappers/}, replacing the call to the macro
+@code{JLLWrappers.@@generate_wrapper_header}, adding as a second
+argument containing the store path the binary.
+
+As an example, in the MbedTLS Julia package, we add a build phase
+(@pxref{Build Phases}) to insert the absolute file name of the wrapped
+MbedTLS package:
+
+@lisp
+(add-after 'unpack 'override-binary-path
+ (lambda* (#:key inputs #:allow-other-keys)
+ (for-each (lambda (wrapper)
+ (substitute* wrapper
+ (("generate_wrapper_header.*")
+ (string-append
+ "generate_wrapper_header(\"MbedTLS\", \""
+ (assoc-ref inputs "mbedtls-apache") "\")\n"))))
+ ;; There's a Julia file for each platform, override them all.
+ (find-files "src/wrappers/" "\\.jl$"))))
+@end lisp
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}
Which Perl package is used can be specified with @code{#:perl}.
@end defvr
+@defvr {Scheme Variable} renpy-build-system
+This variable is exported by @code{(guix build-system renpy)}. It implements
+the more or less standard build procedure used by Ren'py games, which consists
+of loading @code{#:game} once, thereby creating bytecode for it.
+
+It further creates a wrapper script in @code{bin/} and a desktop entry in
+@code{share/applications}, both of which can be used to launch the game.
+
+Which Ren'py package is used can be specified with @code{#:renpy}.
+Games can also be installed in outputs other than ``out'' by using
+@code{#:output}.
+@end defvr
+
@defvr {Scheme Variable} qt-build-system
This variable is exported by @code{(guix build-system qt)}. It
is intended for use with applications using Qt or KDE.
(@pxref{Build Systems}).
As discussed in the previous section, those build systems provide a
-standard list of phases. For @code{gnu-build-system}, the standard
-phases include an @code{unpack} phase to unpack the source code tarball,
-a @command{configure} phase to run @code{./configure}, a @code{build}
-phase to run @command{make}, and (among others) an @code{install} phase
-to run @command{make install}; @pxref{Build Systems}, for a more
-detailed view of these phases. Likewise, @code{cmake-build-system}
-inherits these phases, but its @code{configure} phase runs
-@command{cmake} instead of @command{./configure}. Other build systems,
-such as @code{python-build-system}, have a wholly different list of
-standard phases. All this code runs on the @dfn{build side}: it is
+standard list of phases. For @code{gnu-build-system}, the main build
+phases are the following:
+
+@table @code
+@item unpack
+Unpack the source tarball, and change the current directory to the
+extracted source tree. If the source is actually a directory, copy it
+to the build tree, and enter that directory.
+
+@item patch-source-shebangs
+Patch shebangs encountered in source files so they refer to the right
+store file names. For instance, this changes @code{#!/bin/sh} to
+@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
+
+@item configure
+Run the @file{configure} script with a number of default options, such
+as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified
+by the @code{#:configure-flags} argument.
+
+@item build
+Run @code{make} with the list of flags specified with
+@code{#:make-flags}. If the @code{#:parallel-build?} argument is true
+(the default), build with @code{make -j}.
+
+@item check
+Run @code{make check}, or some other target specified with
+@code{#:test-target}, unless @code{#:tests? #f} is passed. If the
+@code{#:parallel-tests?} argument is true (the default), run @code{make
+check -j}.
+
+@item install
+Run @code{make install} with the flags listed in @code{#:make-flags}.
+
+@item patch-shebangs
+Patch shebangs on the installed executable files.
+
+@item strip
+Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
+is false), copying them to the @code{debug} output when available
+(@pxref{Installing Debugging Files}).
+@end table
+
+Other build systems have similar phases, with some variations. For
+example, @code{cmake-build-system} has same-named phases but its
+@code{configure} phases runs @code{cmake} instead of @code{./configure}.
+Others, such as @code{python-build-system}, have a wholly different list
+of standard phases. All this code runs on the @dfn{build side}: it is
evaluated when you actually build the package, in a dedicated build
process spawned by the build daemon (@pxref{Invoking guix-daemon}).
convention, those procedures receive information about the build in the
form of @dfn{keyword parameters}, which they can use or ignore.
+@vindex %standard-phases
For example, here is how @code{(guix build gnu-build-system)} defines
@code{%standard-phases}, the variable holding its alist of build
phases@footnote{We present a simplified view of those build phases, but
@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
@example
guix build --quiet --keep-going \
- `guix package -A | cut -f1,2 --output-delimiter=@@`
+ $(guix package -A | cut -f1,2 --output-delimiter=@@)
@end example
@var{package-or-derivation} may be either the name of a package found in
@cindex build logs, verbosity
@item -v @var{level}
@itemx --verbosity=@var{level}
-Use the given verbosity @var{level}, an integer. Choosing 0 means that no
-output is produced, 1 is for quiet output, and 2 shows all the build log
-output on standard error.
+Use the given verbosity @var{level}, an integer. Choosing 0 means that
+no output is produced, 1 is for quiet output; 2 is similar to 1 but it
+additionally displays download URLs; 3 shows all the build log output on
+standard error.
@item --cores=@var{n}
@itemx -c @var{n}
@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.
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
instance, the following invocations are equivalent:
@example
-guix build --log-file `guix build -d guile`
-guix build --log-file `guix build guile`
+guix build --log-file $(guix build -d guile)
+guix build --log-file $(guix build guile)
guix build --log-file guile
guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
@end example
To that end, the first thing to do is to use the @option{--keep-failed}
or @option{-K} option of @command{guix build}, which will keep the
failed build tree in @file{/tmp} or whatever directory you specified as
-@env{TMPDIR} (@pxref{Invoking guix build, @option{--keep-failed}}).
+@env{TMPDIR} (@pxref{Common Build Options, @option{--keep-failed}}).
From there on, you can @command{cd} to the failed build tree and source
the @file{environment-variables} file, which contains all the
guix import json hello.json
@end example
-@item nix
-Import metadata from a local copy of the source of the
-@uref{https://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
-relies on the @command{nix-instantiate} command of
-@uref{https://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
-typically written in a mixture of Nix-language and Bash code. This
-command only imports the high-level package structure that is written in
-the Nix language. It normally includes all the basic fields of a
-package definition.
-
-When importing a GNU package, the synopsis and descriptions are replaced
-by their canonical upstream variant.
-
-Usually, you will first need to do:
-
-@example
-export NIX_REMOTE=daemon
-@end example
-
-@noindent
-so that @command{nix-instantiate} does not try to open the Nix database.
-
-As an example, the command below imports the package definition of
-LibreOffice (more precisely, it imports the definition of the package
-bound to the @code{libreoffice} top-level attribute):
-
-@example
-guix import nix ~/path/to/nixpkgs libreoffice
-@end example
-
@item hackage
@cindex hackage
Import metadata from the Haskell community's central package archive
of coq packages.
@end itemize
@end table
+
+@item go
+@cindex go
+Import metadata for a Go module using
+@uref{https://proxy.golang.org, proxy.golang.org}.
+
+@example
+guix import go gopkg.in/yaml.v2
+@end example
+
+It is possible to use a package specification with a @code{@@VERSION}
+suffix to import a specific version.
+
+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 --pin-versions
+When using this option, the importer preserves the exact versions of the
+Go modules dependencies instead of using their latest available
+versions. This can be useful when attempting to import packages that
+recursively depend on former versions of themselves to build. When
+using this mode, the symbol of the package is made by appending the
+version to its name, so that multiple versions of the same package can
+coexist.
+@end table
@end table
The structure of the @command{guix import} code is modular. It would be
@section Invoking @command{guix refresh}
@cindex @command {guix refresh}
-The primary audience of the @command{guix refresh} command is developers
-of the GNU software distribution. By default, it reports any packages
-provided by the distribution that are outdated compared to the latest
-upstream version, like this:
+The primary audience of the @command{guix refresh} command is packagers.
+As a user, you may be interested in the @option{--with-latest} option,
+which can bring you package update superpowers built upon @command{guix
+refresh} (@pxref{Package Transformation Options,
+@option{--with-latest}}). By default, @command{guix refresh} reports
+any packages provided by the distribution that are outdated compared to
+the latest upstream version, like this:
@example
$ guix refresh
@example
$ guix refresh --recursive coreutils
-gnu/packages/acl.scm:35:2: warning: no updater for acl
-gnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4
+gnu/packages/acl.scm:40:13: acl would be upgraded from 2.2.53 to 2.3.1
+gnu/packages/m4.scm:30:12: 1.4.18 is already the latest version of m4
gnu/packages/xml.scm:68:2: warning: no updater for expat
-gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest version of gmp
+gnu/packages/multiprecision.scm:40:12: 6.1.2 is already the latest version of gmp
@dots{}
@end example
the updater for GNU packages;
@item savannah
the updater for packages hosted at @uref{https://savannah.gnu.org, Savannah};
+@item sourceforge
+the updater for packages hosted at @uref{https://sourceforge.net, SourceForge};
@item gnome
the updater for GNOME packages;
@item kde
the updater for @uref{https://crates.io, Crates} packages.
@item launchpad
the updater for @uref{https://launchpad.net, Launchpad} packages.
+@item generic-html
+a generic updater that crawls the HTML page where the source tarball of
+the package is hosted, when applicable.
@end table
For instance, the following command only checks for updates of Emacs
gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
@end example
+@item --list-updaters
+@itemx -L
+List available updaters and exit (see @option{--type} above).
+
+For each updater, display the fraction of packages it covers; at the
+end, display the fraction of packages covered by all these updaters.
@end table
In addition, @command{guix refresh} can be passed one or more package
@noindent
The command above specifically updates the @code{emacs} and
@code{idutils} packages. The @option{--select} option would have no
-effect in this case.
+effect in this case. You might also want to update definitions that
+correspond to the packages installed in your profile:
+
+@example
+$ ./pre-inst-env guix refresh -u \
+ $(guix package --list-installed | cut -f1)
+@end example
When considering whether to upgrade a package, it is sometimes
convenient to know which packages would be affected by the upgrade and
@table @code
-@item --list-updaters
-@itemx -L
-List available updaters and exit (see @option{--type} above).
-
-For each updater, display the fraction of packages it covers; at the
-end, display the fraction of packages covered by all these updaters.
-
@item --list-dependent
@itemx -l
List top-level dependent packages that would need to be rebuilt as a
--recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example
-@ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
+@xref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
Privacy Guard}, for more information on GPG's @option{--keyring} option.
@item --key-download=@var{policy}
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
name instead of a package name, as in:
@example
-guix graph -t derivation `guix system build -d my-config.scm`
+guix graph -t derivation $(guix system build -d my-config.scm)
@end example
@item module
(which can be big!):
@example
-guix graph -t references `readlink -f ~/.guix-profile`
+guix graph -t references $(readlink -f ~/.guix-profile)
@end example
@item referrers
@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
@example
guix copy --to=@var{user}@@@var{host} \
- coreutils `readlink -f ~/.guix-profile`
+ coreutils $(readlink -f ~/.guix-profile)
@end example
If some of the items to be copied are already present on @var{host},
%desktop-services)
@end lisp
+Alternatively, the @code{modify-services} macro can be used:
+
+@lisp
+(modify-services %desktop-services
+ (delete avahi-service-type))
+@end lisp
+
+
@unnumberedsubsec Instantiating the System
Assuming the @code{operating-system} declaration
@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.
@lisp
(mapped-device
(source "vg0")
- (target (list "vg0-alpha" "vg0-beta"))
+ (targets (list "vg0-alpha" "vg0-beta"))
(type lvm-device-mapping))
@end lisp
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Messaging Services:: Messaging services.
* Telephony Services:: Telephony services.
+* File-Sharing Services:: File-sharing services.
* Monitoring Services:: Monitoring services.
* Kerberos Services:: Kerberos services.
* LDAP Services:: LDAP services.
* DNS Services:: DNS daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
-* Continuous Integration:: The Cuirass service.
+* Continuous Integration:: Cuirass and Laminar services.
* Power Management Services:: Extending battery life.
* Audio Services:: The MPD.
* Virtualization Services:: Virtualization services.
@item @code{hardware-acceleration?} (default: #f)
Whether to use hardware acceleration.
+@item @code{font-engine} (default: @code{"pango"})
+Font engine used in Kmscon.
+
+@item @code{font-size} (default: @code{12})
+Font size used in Kmscon.
+
@item @code{kmscon} (default: @var{kmscon})
The Kmscon package to use.
@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))})
+@item @code{compression} (default: @code{'(("gzip" 3) ("zstd" 3))})
This is a list of compression method/level tuple used when compressing
substitutes. For example, to compress all substitutes with @emph{both} lzip
at level 7 and gzip at level 9, write:
@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.
@cindex priority
@cindex realtime
@cindex jackd
+@cindex nofile
+@cindex open file descriptors
@deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]
Return a service that installs a configuration file for the
@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,
@code{pam_limits} module}. The procedure optionally takes a list of
@code{pam-limits-entry} values, which can be used to specify
-@code{ulimit} limits and nice priority limits to user sessions.
+@code{ulimit} limits and @code{nice} priority limits to user sessions.
The following limits definition sets two hard and soft limits for all
login sessions of users in the @code{realtime} group:
non-privileged processes; the second entry lifts any restriction of the
maximum address space that can be locked in memory. These settings are
commonly used for real-time audio systems.
+
+Another useful example is raising the maximum number of open file
+descriptors that can be used:
+
+@lisp
+(pam-limits-service
+ (list
+ (pam-limits-entry "*" 'both 'nofile 100000)))
+@end lisp
+
+In the above example, the asterisk means the limit should apply to any
+user. It is important to ensure the chosen value doesn't exceed the
+maximum system value visible in the @file{/proc/sys/fs/file-max} file,
+else the users would be prevented from login in. For more information
+about the Pluggable Authentication Module (PAM) limits, refer to the
+@samp{pam_limits} man page from the @code{linux-pam} package.
@end deffn
@node Scheduled Job Execution
arptables and ebtables framework. It provides a new packet filtering
framework, a new user-space utility @command{nft}, and a compatibility layer
for iptables. This service comes with a default ruleset
-@code{%default-nftables-ruleset} that rejecting all incomming connections
+@code{%default-nftables-ruleset} that rejecting all incoming connections
except those to the ssh port 22. To use it, simply write:
@lisp
(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
@code{socks-socket-type} at its default value of @code{'tcp} and use
@code{config-file} to override the default by providing your own
@code{SocksPort} option.
+
+@item @code{control-socket?} (default: @code{#f})
+Whether or not to provide a ``control socket'' by which Tor can be
+controlled to, for instance, dynamically instantiate tor onion services.
+If @code{#t}, Tor will listen for control commands on the UNIX domain socket
+@file{/var/run/tor/control-sock}, which will be made writable by members of the
+@code{tor} group.
+
@end table
@end deftp
List of command-line arguments passing to @code{syncthing} binary.
@item @code{logflags} (default: @var{0})
-Sum of loging flags, see
+Sum of logging flags, see
@uref{https://docs.syncthing.net/users/syncthing.html#cmdoption-logflags, Syncthing documentation logflags}.
@item @code{user} (default: @var{#f})
@end table
@end deftp
+@cindex IPFS
+@defvr {Scheme Variable} ipfs-service-type
+The service type for connecting to the @uref{https://ipfs.io,IPFS network},
+a global, versioned, peer-to-peer file system. Pass it a
+@code{ipfs-configuration} to change the ports used for the gateway and API.
+
+Here's an example configuration, using some non-standard ports:
+
+@lisp
+(service ipfs-service-type
+ (ipfs-configuration
+ (gateway "/ip4/127.0.0.1/tcp/8880")
+ (api "/ip4/127.0.0.1/tcp/8881")))
+@end lisp
+@end defvr
+
+@deftp {Data Type} ipfs-configuration
+Data type representing the configuration of IPFS.
+
+@table @asis
+@item @code{package} (default: @code{go-ipfs})
+Package object of IPFS.
+
+@item @code{gateway} (default: @code{"/ip4/127.0.0.1/tcp/8082"})
+Address of the gateway, in ‘multiaddress’ format.
+
+@item @code{api} (default: @code{"/ip4/127.0.0.1/tcp/5001"})
+Address of the API endpoint, in ‘multiaddress’ format.
+@end table
+@end deftp
+
@cindex keepalived
@deffn {Scheme Variable} keepalived-service-type
This is the type for the @uref{https://www.keepalived.org/, Keepalived}
(service slim-service-type (slim-configuration
(display ":1")
(vt "vt8")))
- (remove (lambda (service)
- (eq? (service-kind service) gdm-service-type))
- %desktop-services))))
+ (modify-services %desktop-services
+ (delete gdm-service-type)))))
@end lisp
@end defvr
@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
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.
site} for more information.
@end deffn
+@cindex scanner access
+@defvr {Scheme Variable} sane-service-type
+This service provides access to scanners @i{via}
+@uref{http://www.sane-project.org, SANE} by installing the necessary
+udev rules. It is included in @code{%desktop-services} (@pxref{Desktop
+Services}) and relies by default on @code{sane-backends-minimal} package
+(see below) for hardware support.
+@end defvr
+
+@defvr {Scheme Variable} sane-backends-minimal
+The default package which the @code{sane-service-type} installs. It
+supports many recent scanners.
+@end defvr
+
+@defvr {Scheme Variable} sane-backends
+This package includes support for all scanners that
+@code{sane-backends-minimal} supports, plus older Hewlett-Packard
+scanners supported by @code{hplip} package. In order to use this on
+a system which relies on @code{%desktop-services}, you may use
+@code{modify-services} (@pxref{Service Reference,
+@code{modify-services}}) as illustrated below:
+
+@lisp
+(use-modules (gnu))
+(use-service-modules
+ @dots{}
+ desktop)
+(use-package-modules
+ @dots{}
+ scanner)
+
+(define %my-desktop-services
+ ;; List of desktop services that supports a broader range of scanners.
+ (modify-services %desktop-services
+ (sane-service-type _ => sane-backends)))
+
+(operating-system
+ @dots{}
+ (services %my-desktop-services)
+@end lisp
+@end defvr
+
@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
Return a configuration allowing an application to access GeoClue
location data. @var{name} is the Desktop ID of the application, without
means that all users are allowed.
@end deffn
-@cindex scanner access
-@deffn {Scheme Procedure} sane-service-type
-This service provides access to scanners @i{via}
-@uref{http://www.sane-project.org, SANE} by installing the necessary udev
-rules.
-@end deffn
-
@defvr {Scheme Variable} %standard-geoclue-applications
The standard list of well-known GeoClue application configurations,
granting authority to the GNOME date-and-time utility to ask for the
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{#false})
+Specifies the directory of the Unix-domain socket(s) on which PostgreSQL
+is to listen for connections from client applications. If set to
+@code{""} PostgreSQL does not listen on any Unix-domain sockets, in
+which case only TCP/IP sockets can be used to connect to the server.
+
+By default, the @code{#false} value means the PostgreSQL default value
+will be used, which is currently @samp{/tmp}.
+
@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
+
+@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.
+
+@lisp
+(service postgresql-role-service-type
+ (postgresql-role-configuration
+ (roles
+ (list (postgresql-role
+ (name "test")
+ (create-database? #t))))))
+@end lisp
+
+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
@end table
@end deftp
-@subsubheading MongoDB
-
-@defvr {Scheme Variable} mongodb-service-type
-This is the service type for @uref{https://www.mongodb.com/, MongoDB}.
-The value for the service type is a @code{mongodb-configuration} object.
-@end defvr
-
-@lisp
-(service mongodb-service-type)
-@end lisp
-
-@deftp {Data Type} mongodb-configuration
-Data type representing the configuration of mongodb.
-
-@table @asis
-@item @code{mongodb} (default: @code{mongodb})
-The MongoDB package to use.
-
-@item @code{config-file} (default: @code{%default-mongodb-configuration-file})
-The configuration file for MongoDB.
-
-@item @code{data-directory} (default: @code{"/var/lib/mongodb"})
-This value is used to create the directory, so that it exists and is
-owned by the mongodb user. It should match the data-directory which
-MongoDB is configured to use through the configuration file.
-@end table
-@end deftp
-
@subsubheading Redis
@defvr {Scheme Variable} redis-service-type
@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}.
@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
+@node File-Sharing Services
+@subsection File-Sharing Services
+
+The @code{(gnu services file-sharing)} module provides services that
+assist with transferring files over peer-to-peer file-sharing networks.
+
+@subsubheading Transmission Daemon Service
+
+@uref{https://transmissionbt.com/, Transmission} is a flexible
+BitTorrent client that offers a variety of graphical and command-line
+interfaces. A @code{transmission-daemon-service-type} service provides
+Transmission's headless variant, @command{transmission-daemon}, as a
+system service, allowing users to share files via BitTorrent even when
+they are not logged in.
+
+@deffn {Scheme Variable} transmission-daemon-service-type
+The service type for the Transmission Daemon BitTorrent client. Its
+value must be a @code{transmission-daemon-configuration} object as in
+this example:
+
+@lisp
+(service transmission-daemon-service-type
+ (transmission-daemon-configuration
+ ;; Restrict access to the RPC ("control") interface
+ (rpc-authentication-required? #t)
+ (rpc-username "transmission")
+ (rpc-password
+ (transmission-password-hash
+ "transmission" ; desired password
+ "uKd1uMs9")) ; arbitrary salt value
+
+ ;; Accept requests from this and other hosts on the
+ ;; local network
+ (rpc-whitelist-enabled? #t)
+ (rpc-whitelist '("::1" "127.0.0.1" "192.168.0.*"))
+
+ ;; Limit bandwidth use during work hours
+ (alt-speed-down (* 1024 2)) ; 2 MB/s
+ (alt-speed-up 512) ; 512 kB/s
+
+ (alt-speed-time-enabled? #t)
+ (alt-speed-time-day 'weekdays)
+ (alt-speed-time-begin
+ (+ (* 60 8) 30)) ; 8:30 am
+ (alt-speed-time-end
+ (+ (* 60 (+ 12 5)) 30)))) ; 5:30 pm
+@end lisp
+@end deffn
+
+Once the service is started, users can interact with the daemon through
+its Web interface (at @code{http://localhost:9091/}) or by using the
+@command{transmission-remote} command-line tool, available in the
+@code{transmission} package. (Emacs users may want to also consider the
+@code{emacs-transmission} package.) Both communicate with the daemon
+through its remote procedure call (RPC) interface, which by default is
+available to all users on the system; you may wish to change this by
+assigning values to the @code{rpc-authentication-required?},
+@code{rpc-username} and @code{rpc-password} settings, as shown in the
+example above and documented further below.
+
+The value for @code{rpc-password} must be a password hash of the type
+generated and used by Transmission clients. This can be copied verbatim
+from an existing @file{settings.json} file, if another Transmission
+client is already being used. Otherwise, the
+@code{transmission-password-hash} and @code{transmission-random-salt}
+procedures provided by this module can be used to obtain a suitable hash
+value.
+
+@deffn {Scheme Procedure} transmission-password-hash @var{password} @var{salt}
+Returns a string containing the result of hashing @var{password}
+together with @var{salt}, in the format recognized by Transmission
+clients for their @code{rpc-password} configuration setting.
+
+@var{salt} must be an eight-character string. The
+@code{transmission-random-salt} procedure can be used to generate a
+suitable salt value at random.
+@end deffn
+
+@deffn {Scheme Procedure} transmission-random-salt
+Returns a string containing a random, eight-character salt value of the
+type generated and used by Transmission clients, suitable for passing to
+the @code{transmission-password-hash} procedure.
+@end deffn
+
+These procedures are accessible from within a Guile REPL started with
+the @command{guix repl} command (@pxref{Invoking guix repl}). This is
+useful for obtaining a random salt value to provide as the second
+parameter to `transmission-password-hash`, as in this example session:
+
+@example
+$ guix repl
+scheme@@(guix-user)> ,use (gnu services file-sharing)
+scheme@@(guix-user)> (transmission-random-salt)
+$1 = "uKd1uMs9"
+@end example
+
+Alternatively, a complete password hash can generated in a single step:
+
+@example
+scheme@@(guix-user)> (transmission-password-hash "transmission"
+(transmission-random-salt))
+$2 = "@{c8bbc6d1740cd8dc819a6e25563b67812c1c19c9VtFPfdsX"
+@end example
+
+The resulting string can be used as-is for the value of
+@code{rpc-password}, allowing the password to be kept hidden even in the
+operating-system configuration.
+
+Torrent files downloaded by the daemon are directly accessible only to
+users in the ``transmission'' user group, who receive read-only access
+to the directory specified by the @code{download-dir} configuration
+setting (and also the directory specified by @code{incomplete-dir}, if
+@code{incomplete-dir-enabled?} is @code{#t}). Downloaded files can be
+moved to another directory or deleted altogether using
+@command{transmission-remote} with its @code{--move} and
+@code{--remove-and-delete} options.
+
+If the @code{watch-dir-enabled?} setting is set to @code{#t}, users in
+the ``transmission'' group are able also to place @file{.torrent} files
+in the directory specified by @code{watch-dir} to have the corresponding
+torrents added by the daemon. (The @code{trash-original-torrent-files?}
+setting controls whether the daemon deletes these files after processing
+them.)
+
+Some of the daemon's configuration settings can be changed temporarily
+by @command{transmission-remote} and similar tools. To undo these
+changes, use the service's @code{reload} action to have the daemon
+reload its settings from disk:
+
+@example
+# herd reload transmission-daemon
+@end example
+
+The full set of available configuration settings is defined by the
+@code{transmission-daemon-configuration} data type.
+
+@deftp {Data Type} transmission-daemon-configuration
+The data type representing configuration settings for Transmission
+Daemon. These correspond directly to the settings recognized by
+Transmission clients in their @file{settings.json} file.
+@end deftp
+
+@c The following documentation was initially generated by
+@c (generate-transmission-daemon-documentation) in (gnu services
+@c file-sharing). Manually maintained documentation is better, so we
+@c shouldn't hesitate to edit below as needed. However if the change
+@c you want to make to this documentation can be done in an automated
+@c way, it's probably easier to change (generate-documentation) than to
+@c make it below and have to deal with the churn as Transmission Daemon
+@c updates.
+
+@c %start of fragment
+
+Available @code{transmission-daemon-configuration} fields are:
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} package transmission
+The Transmission package to use.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer stop-wait-period
+The period, in seconds, to wait when stopping the service for
+@command{transmission-daemon} to exit before killing its process. This
+allows the daemon time to complete its housekeeping and send a final
+update to trackers as it shuts down. On slow hosts, or hosts with a
+slow network connection, this value may need to be increased.
+
+Defaults to @samp{10}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string download-dir
+The directory to which torrent files are downloaded.
+
+Defaults to @samp{"/var/lib/transmission-daemon/downloads"}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean incomplete-dir-enabled?
+If @code{#t}, files will be held in @code{incomplete-dir} while their
+torrent is being downloaded, then moved to @code{download-dir} once the
+torrent is complete. Otherwise, files for all torrents (including those
+still being downloaded) will be placed in @code{download-dir}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string incomplete-dir
+The directory in which files from incompletely downloaded torrents will
+be held when @code{incomplete-dir-enabled?} is @code{#t}.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} umask umask
+The file mode creation mask used for downloaded files. (See the
+@command{umask} man page for more information.)
+
+Defaults to @samp{18}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rename-partial-files?
+When @code{#t}, ``.part'' is appended to the name of partially
+downloaded files.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} preallocation-mode preallocation
+The mode by which space should be preallocated for downloaded files, one
+of @code{none}, @code{fast} (or @code{sparse}) and @code{full}.
+Specifying @code{full} will minimize disk fragmentation at a cost to
+file-creation speed.
+
+Defaults to @samp{fast}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean watch-dir-enabled?
+If @code{#t}, the directory specified by @code{watch-dir} will be
+watched for new @file{.torrent} files and the torrents they describe
+added automatically (and the original files removed, if
+@code{trash-original-torrent-files?} is @code{#t}).
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string watch-dir
+The directory to be watched for @file{.torrent} files indicating new
+torrents to be added, when @code{watch-dir-enabled} is @code{#t}.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean trash-original-torrent-files?
+When @code{#t}, @file{.torrent} files will be deleted from the watch
+directory once their torrent has been added (see
+@code{watch-directory-enabled?}).
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-down-enabled?
+When @code{#t}, the daemon's download speed will be limited to the rate
+specified by @code{speed-limit-down}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-down
+The default global-maximum download speed, in kilobytes per second.
+
+Defaults to @samp{100}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-up-enabled?
+When @code{#t}, the daemon's upload speed will be limited to the rate
+specified by @code{speed-limit-up}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-up
+The default global-maximum upload speed, in kilobytes per second.
+
+Defaults to @samp{100}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-enabled?
+When @code{#t}, the alternate speed limits @code{alt-speed-down} and
+@code{alt-speed-up} are used (in place of @code{speed-limit-down} and
+@code{speed-limit-up}, if they are enabled) to constrain the daemon's
+bandwidth usage. This can be scheduled to occur automatically at
+certain times during the week; see @code{alt-speed-time-enabled?}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-down
+The alternate global-maximum download speed, in kilobytes per second.
+
+Defaults to @samp{50}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-up
+The alternate global-maximum upload speed, in kilobytes per second.
+
+Defaults to @samp{50}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-time-enabled?
+When @code{#t}, the alternate speed limits @code{alt-speed-down} and
+@code{alt-speed-up} will be enabled automatically during the periods
+specified by @code{alt-speed-time-day}, @code{alt-speed-time-begin} and
+@code{alt-time-speed-end}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} day-list alt-speed-time-day
+The days of the week on which the alternate-speed schedule should be
+used, specified either as a list of days (@code{sunday}, @code{monday},
+and so on) or using one of the symbols @code{weekdays}, @code{weekends}
+or @code{all}.
+
+Defaults to @samp{all}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-begin
+The time of day at which to enable the alternate speed limits, expressed
+as a number of minutes since midnight.
+
+Defaults to @samp{540}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-end
+The time of day at which to disable the alternate speed limits,
+expressed as a number of minutes since midnight.
+
+Defaults to @samp{1020}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv4
+The IP address at which to listen for peer connections, or ``0.0.0.0''
+to listen at all available IP addresses.
+
+Defaults to @samp{"0.0.0.0"}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv6
+The IPv6 address at which to listen for peer connections, or ``::'' to
+listen at all available IPv6 addresses.
+
+Defaults to @samp{"::"}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean peer-port-random-on-start?
+If @code{#t}, when the daemon starts it will select a port at random on
+which to listen for peer connections, from the range specified
+(inclusively) by @code{peer-port-random-low} and
+@code{peer-port-random-high}. Otherwise, it listens on the port
+specified by @code{peer-port}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-low
+The lowest selectable port number when @code{peer-port-random-on-start?}
+is @code{#t}.
+
+Defaults to @samp{49152}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-high
+The highest selectable port number when @code{peer-port-random-on-start}
+is @code{#t}.
+
+Defaults to @samp{65535}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port
+The port on which to listen for peer connections when
+@code{peer-port-random-on-start?} is @code{#f}.
+
+Defaults to @samp{51413}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean port-forwarding-enabled?
+If @code{#t}, the daemon will attempt to configure port-forwarding on an
+upstream gateway automatically using @acronym{UPnP} and
+@acronym{NAT-PMP}.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} encryption-mode encryption
+The encryption preference for peer connections, one of
+@code{prefer-unencrypted-connections},
+@code{prefer-encrypted-connections} or
+@code{require-encrypted-connections}.
+
+Defaults to @samp{prefer-encrypted-connections}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm
+The TCP congestion-control algorithm to use for peer connections,
+specified using a string recognized by the operating system in calls to
+@code{setsockopt} (or set to @code{disabled}, in which case the
+operating-system default is used).
+
+Note that on GNU/Linux systems, the kernel must be configured to allow
+processes to use a congestion-control algorithm not in the default set;
+otherwise, it will deny these requests with ``Operation not permitted''.
+To see which algorithms are available on your system and which are
+currently permitted for use, look at the contents of the files
+@file{tcp_available_congestion_control} and
+@file{tcp_allowed_congestion_control} in the @file{/proc/sys/net/ipv4}
+directory.
+
+As an example, to have Transmission Daemon use
+@uref{http://www-ece.rice.edu/networks/TCP-LP/,the TCP Low Priority
+congestion-control algorithm}, you'll need to modify your kernel
+configuration to build in support for the algorithm, then update your
+operating-system configuration to allow its use by adding a
+@code{sysctl-service-type} service (or updating the existing one's
+configuration) with lines like the following:
+
+@lisp
+(service sysctl-service-type
+ (sysctl-configuration
+ (settings
+ ("net.ipv4.tcp_allowed_congestion_control" .
+ "reno cubic lp"))))
+@end lisp
+
+The Transmission Daemon configuration can then be updated with
+
+@lisp
+(peer-congestion-algorithm "lp")
+@end lisp
+
+and the system reconfigured to have the changes take effect.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} tcp-type-of-service peer-socket-tos
+The type of service to request in outgoing @acronym{TCP} packets, one of
+@code{default}, @code{low-cost}, @code{throughput}, @code{low-delay} and
+@code{reliability}.
+
+Defaults to @samp{default}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-global
+The global limit on the number of connected peers.
+
+Defaults to @samp{200}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-per-torrent
+The per-torrent limit on the number of connected peers.
+
+Defaults to @samp{50}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer upload-slots-per-torrent
+The maximum number of peers to which the daemon will upload data
+simultaneously for each torrent.
+
+Defaults to @samp{14}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-id-ttl-hours
+The maximum lifespan, in hours, of the peer ID associated with each
+public torrent before it is regenerated.
+
+Defaults to @samp{6}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean blocklist-enabled?
+When @code{#t}, the daemon will ignore peers mentioned in the blocklist
+it has most recently downloaded from @code{blocklist-url}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string blocklist-url
+The URL of a peer blocklist (in @acronym{P2P}-plaintext or eMule
+@file{.dat} format) to be periodically downloaded and applied when
+@code{blocklist-enabled?} is @code{#t}.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean download-queue-enabled?
+If @code{#t}, the daemon will be limited to downloading at most
+@code{download-queue-size} non-stalled torrents simultaneously.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer download-queue-size
+The size of the daemon's download queue, which limits the number of
+non-stalled torrents it will download at any one time when
+@code{download-queue-enabled?} is @code{#t}.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean seed-queue-enabled?
+If @code{#t}, the daemon will be limited to seeding at most
+@code{seed-queue-size} non-stalled torrents simultaneously.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer seed-queue-size
+The size of the daemon's seed queue, which limits the number of
+non-stalled torrents it will seed at any one time when
+@code{seed-queue-enabled?} is @code{#t}.
+
+Defaults to @samp{10}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean queue-stalled-enabled?
+When @code{#t}, the daemon will consider torrents for which it has not
+shared data in the past @code{queue-stalled-minutes} minutes to be
+stalled and not count them against its @code{download-queue-size} and
+@code{seed-queue-size} limits.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer queue-stalled-minutes
+The maximum period, in minutes, a torrent may be idle before it is
+considered to be stalled, when @code{queue-stalled-enabled?} is
+@code{#t}.
+
+Defaults to @samp{30}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean ratio-limit-enabled?
+When @code{#t}, a torrent being seeded will automatically be paused once
+it reaches the ratio specified by @code{ratio-limit}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-rational ratio-limit
+The ratio at which a torrent being seeded will be paused, when
+@code{ratio-limit-enabled?} is @code{#t}.
+
+Defaults to @samp{2.0}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean idle-seeding-limit-enabled?
+When @code{#t}, a torrent being seeded will automatically be paused once
+it has been idle for @code{idle-seeding-limit} minutes.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer idle-seeding-limit
+The maximum period, in minutes, a torrent being seeded may be idle
+before it is paused, when @code{idle-seeding-limit-enabled?} is
+@code{#t}.
+
+Defaults to @samp{30}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean dht-enabled?
+Enable @uref{http://bittorrent.org/beps/bep_0005.html,the distributed
+hash table (@acronym{DHT}) protocol}, which supports the use of
+trackerless torrents.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean lpd-enabled?
+Enable @uref{https://en.wikipedia.org/wiki/Local_Peer_Discovery,local
+peer discovery} (@acronym{LPD}), which allows the discovery of peers on
+the local network and may reduce the amount of data sent over the public
+Internet.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean pex-enabled?
+Enable @uref{https://en.wikipedia.org/wiki/Peer_exchange,peer exchange}
+(@acronym{PEX}), which reduces the daemon's reliance on external
+trackers and may improve its performance.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean utp-enabled?
+Enable @uref{http://bittorrent.org/beps/bep_0029.html,the micro
+transport protocol} (@acronym{uTP}), which aims to reduce the impact of
+BitTorrent traffic on other users of the local network while maintaining
+full utilization of the available bandwidth.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-enabled?
+If @code{#t}, enable the remote procedure call (@acronym{RPC})
+interface, which allows remote control of the daemon via its Web
+interface, the @command{transmission-remote} command-line client, and
+similar tools.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-bind-address
+The IP address at which to listen for @acronym{RPC} connections, or
+``0.0.0.0'' to listen at all available IP addresses.
+
+Defaults to @samp{"0.0.0.0"}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} port-number rpc-port
+The port on which to listen for @acronym{RPC} connections.
+
+Defaults to @samp{9091}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-url
+The path prefix to use in the @acronym{RPC}-endpoint @acronym{URL}.
+
+Defaults to @samp{"/transmission/"}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-authentication-required?
+When @code{#t}, clients must authenticate (see @code{rpc-username} and
+@code{rpc-password}) when using the @acronym{RPC} interface. Note this
+has the side effect of disabling host-name whitelisting (see
+@code{rpc-host-whitelist-enabled?}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string rpc-username
+The username required by clients to access the @acronym{RPC} interface
+when @code{rpc-authentication-required?} is @code{#t}.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-transmission-password-hash rpc-password
+The password required by clients to access the @acronym{RPC} interface
+when @code{rpc-authentication-required?} is @code{#t}. This must be
+specified using a password hash in the format recognized by Transmission
+clients, either copied from an existing @file{settings.json} file or
+generated using the @code{transmission-password-hash} procedure.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-whitelist-enabled?
+When @code{#t}, @acronym{RPC} requests will be accepted only when they
+originate from an address specified in @code{rpc-whitelist}.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-whitelist
+The list of IP and IPv6 addresses from which @acronym{RPC} requests will
+be accepted when @code{rpc-whitelist-enabled?} is @code{#t}. Wildcards
+may be specified using @samp{*}.
+
+Defaults to @samp{("127.0.0.1" "::1")}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-host-whitelist-enabled?
+When @code{#t}, @acronym{RPC} requests will be accepted only when they
+are addressed to a host named in @code{rpc-host-whitelist}. Note that
+requests to ``localhost'' or ``localhost.'', or to a numeric address,
+are always accepted regardless of these settings.
+
+Note also this functionality is disabled when
+@code{rpc-authentication-required?} is @code{#t}.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-host-whitelist
+The list of host names recognized by the @acronym{RPC} server when
+@code{rpc-host-whitelist-enabled?} is @code{#t}.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} message-level message-level
+The minimum severity level of messages to be logged (to
+@file{/var/log/transmission.log}) by the daemon, one of @code{none} (no
+logging), @code{error}, @code{info} and @code{debug}.
+
+Defaults to @samp{info}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean start-added-torrents?
+When @code{#t}, torrents are started as soon as they are added;
+otherwise, they are added in ``paused'' state.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean script-torrent-done-enabled?
+When @code{#t}, the script specified by
+@code{script-torrent-done-filename} will be invoked each time a torrent
+completes.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} maybe-file-object script-torrent-done-filename
+A file name or file-like object specifying a script to run each time a
+torrent completes, when @code{script-torrent-done-enabled?} is
+@code{#t}.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean scrape-paused-torrents-enabled?
+When @code{#t}, the daemon will scrape trackers for a torrent even when
+the torrent is paused.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer cache-size-mb
+The amount of memory, in megabytes, to allocate for the daemon's
+in-memory cache. A larger value may increase performance by reducing
+the frequency of disk I/O.
+
+Defaults to @samp{4}.
+
+@end deftypevr
+
+@deftypevr {@code{transmission-daemon-configuration} parameter} boolean prefetch-enabled?
+When @code{#t}, the daemon will try to improve I/O performance by
+hinting to the operating system which data is likely to be read next
+from disk to satisfy requests from peers.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+
+@c %end of fragment
+
+
+
@node Monitoring Services
@subsection Monitoring Services
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
@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},
@end table
@end deftp
+@subsubheading Agate
+
+@cindex agate
+The @uref{gemini://qwertqwefsday.eu/agate.gmi, Agate}
+(@uref{https://github.com/mbrubeck/agate, GitHub page over HTTPS})
+program is a simple @uref{https://gemini.circumlunar.space/, Gemini}
+protocol server written in Rust.
+
+@deffn {Scheme Variable} agate-service-type
+This is the type of the agate service, whose value should be an
+@code{agate-service-type} object, as in this example:
+
+@lisp
+(service agate-service-type
+ (agate-configuration
+ (content "/srv/gemini")
+ (cert "/srv/cert.pem")
+ (key "/srv/key.rsa")))
+@end lisp
+
+The example above represents the minimal tweaking necessary to get Agate
+up and running. Specifying the path to the certificate and key is
+always necessary, as the Gemini protocol requires TLS by default.
+
+To obtain a certificate and a key, you could, for example, use OpenSSL,
+running a command similar to the following example:
+
+@example
+openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \
+ -days 3650 -nodes -subj "/CN=example.com"
+@end example
+
+Of course, you'll have to replace @i{example.com} with your own domain
+name, and then point the Agate configuration towards the path of the
+generated key and certificate.
+
+@end deffn
+
+@deftp {Data Type} agate-configuration
+Data type representing the configuration of Agate.
+
+@table @asis
+@item @code{package} (default: @code{agate})
+The package object of the Agate server.
+
+@item @code{content} (default: @file{"/srv/gemini"})
+The directory from which Agate will serve files.
+
+@item @code{cert} (default: @code{#f})
+The path to the TLS certificate PEM file to be used for encrypted
+connections. Must be filled in with a value from the user.
+
+@item @code{key} (default: @code{#f})
+The path to the PKCS8 private key file to be used for encrypted
+connections. Must be filled in with a value from the user.
+
+@item @code{addr} (default: @code{'("0.0.0.0:1965" "[::]:1965")})
+A list of the addresses to listen on.
+
+@item @code{hostname} (default: @code{#f})
+The domain name of this Gemini server. Optional.
+
+@item @code{lang} (default: @code{#f})
+RFC 4646 language code(s) for text/gemini documents. Optional.
+
+@item @code{silent?} (default: @code{#f})
+Set to @code{#t} to disable logging output.
+
+@item @code{serve-secret?} (default: @code{#f})
+Set to @code{#t} to serve secret files (files/directories starting with
+a dot).
+
+@item @code{log-ip?} (default: @code{#t})
+Whether or not to output IP addresses when logging.
+
+@item @code{user} (default: @code{"agate"})
+Owner of the @code{agate} process.
+
+@item @code{group} (default: @code{"agate"})
+Owner's group of the @code{agate} process.
+
+@item @code{log-file} (default: @file{"/var/log/agate.log"})
+The file which should store the logging output of Agate.
+
+@end table
+@end deftp
+
@node Certificate Services
@subsection Certificate Services
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
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}.
and check again that it still exists.
@item @code{nx} (default: @code{3600})
-Default TTL of inexistant records. This delay is usually short because you want
+Default TTL of inexistent records. This delay is usually short because you want
your new domains to reach everyone quickly.
@end table
@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})
@cindex virtual private network (VPN)
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}.
+@dfn{virtual private networks} (VPNs).
+
+@subsubheading OpenVPN
+
+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@.
@deffn {Scheme Procedure} openvpn-client-service @
[#:config (openvpn-client-configuration)]
@c %end of automatic openvpn-server documentation
+@subsubheading Wireguard
+
+@defvr {Scheme Variable} wireguard-service-type
+A service type for a Wireguard tunnel interface. Its value must be a
+@code{wireguard-configuration} record as in this example:
+
+@lisp
+(service wireguard-service-type
+ (wireguard-configuration
+ (peers
+ (list
+ (wireguard-peer
+ (name "my-peer")
+ (endpoint "my.wireguard.com:51820")
+ (public-key "hzpKg9X1yqu1axN6iJp0mWf6BZGo8m1wteKwtTmDGF4=")
+ (allowed-ips '("10.0.0.2/32")))))))
+@end lisp
+
+@end defvr
+
+@deftp {Data Type} wireguard-configuration
+Data type representing the configuration of the Wireguard service.
+
+@table @asis
+@item @code{wireguard}
+The wireguard package to use for this service.
+
+@item @code{interface} (default: @code{"wg0"})
+The interface name for the VPN.
+
+@item @code{addresses} (default: @code{'("10.0.0.1/32")})
+The IP addresses to be assigned to the above interface.
+
+@item @code{private-key} (default: @code{"/etc/wireguard/private.key"})
+The private key file for the interface. It is automatically generated if
+the file does not exist.
+
+@item @code{peers} (default: @code{'()})
+The authorized peers on this interface. This is a list of
+@var{wireguard-peer} records.
+
+@end table
+@end deftp
+
+@deftp {Data Type} wireguard-peer
+Data type representing a Wireguard peer attached to a given interface.
+
+@table @asis
+@item @code{name}
+The peer name.
+
+@item @code{endpoint} (default: @code{#f})
+The optional endpoint for the peer, such as
+@code{"demo.wireguard.com:51820"}.
+
+@item @code{public-key}
+The peer public-key represented as a base64 string.
+
+@item @code{allowed-ips}
+A list of IP addresses from which incoming traffic for this peer is
+allowed and to which incoming traffic for this peer is directed.
+
+@end table
+@end deftp
@node Network File System
@subsection Network File System
@subsection Continuous Integration
@cindex continuous integration
-@uref{https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, Cuirass} is a
-continuous integration tool for Guix. It can be used both for development and
-for providing substitutes to others (@pxref{Substitutes}).
+@uref{https://guix.gnu.org/cuirass/, Cuirass} is a continuous
+integration tool for Guix. It can be used both for development and for
+providing substitutes to others (@pxref{Substitutes}).
The @code{(gnu services cuirass)} module provides the following service.
@code{cuirass-configuration} object, as described below.
@end defvr
-To add build jobs, you have to set the @code{specifications} field of the
-configuration. Here is an example of a service that polls the Guix repository
-and builds the packages from a manifest. Some of the packages are defined in
-the @code{"custom-packages"} input, which is the equivalent of
-@env{GUIX_PACKAGE_PATH}.
+To add build jobs, you have to set the @code{specifications} field of
+the configuration. For instance, the following example will build all
+the packages provided by the @code{my-channel} channel.
+
+@lisp
+(define %cuirass-specs
+ #~(list (specification
+ (name "my-channel")
+ (build '(channels my-channel))
+ (channels
+ (cons (channel
+ (name 'my-channel)
+ (url "https://my-channel.git"))
+ %default-channels)))))
+
+(service cuirass-service-type
+ (cuirass-configuration
+ (specifications %cuirass-specs)))
+@end lisp
+
+To build the @code{linux-libre} package defined by the default Guix
+channel, one can use the following configuration.
@lisp
(define %cuirass-specs
- #~(list
- '((#:name . "my-manifest")
- (#:load-path-inputs . ("guix"))
- (#:package-path-inputs . ("custom-packages"))
- (#:proc-input . "guix")
- (#:proc-file . "build-aux/cuirass/gnu-system.scm")
- (#:proc . cuirass-jobs)
- (#:proc-args . ((subset . "manifests")
- (systems . ("x86_64-linux"))
- (manifests . (("config" . "guix/manifest.scm")))))
- (#:inputs . (((#:name . "guix")
- (#:url . "git://git.savannah.gnu.org/guix.git")
- (#:load-path . ".")
- (#:branch . "master")
- (#:no-compile? . #t))
- ((#:name . "config")
- (#:url . "https://git.example.org/config.git")
- (#:load-path . ".")
- (#:branch . "master")
- (#:no-compile? . #t))
- ((#:name . "custom-packages")
- (#:url . "https://git.example.org/custom-packages.git")
- (#:load-path . ".")
- (#:branch . "master")
- (#:no-compile? . #t)))))))
+ #~(list (specification
+ (name "my-linux")
+ (build '(packages "linux-libre")))))
(service cuirass-service-type
(cuirass-configuration
(specifications %cuirass-specs)))
@end lisp
+The other configuration possibilities, as well as the specification
+record itself are described in the Cuirass manual
+(@pxref{Specifications,,, cuirass, Cuirass}).
+
While information related to build jobs is located directly in the
specifications, global settings for the @command{cuirass} process are
accessible in other @code{cuirass-configuration} fields.
Data type representing the configuration of Cuirass.
@table @asis
+@item @code{cuirass} (default: @code{cuirass})
+The Cuirass package to use.
+
@item @code{log-file} (default: @code{"/var/log/cuirass.log"})
Location of the log file.
@item @code{web-log-file} (default: @code{"/var/log/cuirass-web.log"})
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
-disabled.
-
-@item @code{web-queries-log-file} (default: @code{#f})
-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"})
Location of the repository cache.
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{parameters} (default: @code{#f})
+Read parameters from the given @var{parameters} file. The supported
+parameters are described here (@pxref{Parameters,,, cuirass, Cuirass}).
-@item @code{database} (default: @code{"/var/lib/cuirass/cuirass.db"})
-Location of sqlite database which contains the build results and previously
-added specifications.
+@item @code{remote-server} (default: @code{#f})
+A @code{cuirass-remote-server-configuration} record to use the build
+remote mechanism or @code{#f} to use the default build mechanism.
-@item @code{ttl} (default: @code{(* 30 24 3600)})
-Specifies the time-to-live (TTL) in seconds of garbage collector roots that
-are registered for build results. This means that build results are protected
-from garbage collection for at least @var{ttl} seconds.
+@item @code{database} (default: @code{"dbname=cuirass host=/var/run/postgresql"})
+Use @var{database} as the database containing the jobs and the past
+build results. Since Cuirass uses PostgreSQL as a database engine,
+@var{database} must be a string such as @code{"dbname=cuirass
+host=localhost"}.
@item @code{port} (default: @code{8081})
Port number used by the HTTP server.
accept connections from localhost.
@item @code{specifications} (default: @code{#~'()})
-A gexp (@pxref{G-Expressions}) that evaluates to a list of specifications,
-where a specification is an association list
-(@pxref{Associations Lists,,, guile, GNU Guile Reference Manual}) whose
-keys are keywords (@code{#:keyword-example}) as shown in the example
-above.
+A gexp (@pxref{G-Expressions}) that evaluates to a list of
+specifications records. The specification record is described in the
+Cuirass manual (@pxref{Specifications,,, cuirass, Cuirass}).
@item @code{use-substitutes?} (default: @code{#f})
This allows using substitutes to avoid building every dependencies of a job
@item @code{extra-options} (default: @code{'()})
Extra options to pass when running the Cuirass processes.
+@end table
+@end deftp
+
+@cindex remote build
+@subsubheading Cuirass remote building
+
+Cuirass supports two mechanisms to build derivations.
+
+@itemize
+@item Using the local Guix daemon.
+This is the default build mechanism. Once the build jobs are
+evaluated, they are sent to the local Guix daemon. Cuirass then
+listens to the Guix daemon output to detect the various build events.
+
+@item Using the remote build mechanism.
+The build jobs are not submitted to the local Guix daemon. Instead, a
+remote server dispatches build requests to the connect remote workers,
+according to the build priorities.
+
+@end itemize
+
+To enable this build mode a @code{cuirass-remote-server-configuration}
+record must be passed as @code{remote-server} argument of the
+@code{cuirass-configuration} record. The
+@code{cuirass-remote-server-configuration} record is described below.
+
+This build mode scales way better than the default build mode. This is
+the build mode that is used on the GNU Guix build farm at
+@url{https://ci.guix.gnu.org}. It should be preferred when using
+Cuirass to build large amount of packages.
+
+@deftp {Data Type} cuirass-remote-server-configuration
+Data type representing the configuration of the Cuirass remote-server.
+
+@table @asis
+@item @code{backend-port} (default: @code{5555})
+The TCP port for communicating with @code{remote-worker} processes
+using ZMQ. It defaults to @code{5555}.
+
+@item @code{log-port} (default: @code{5556})
+The TCP port of the log server. It defaults to @code{5556}.
+
+@item @code{publish-port} (default: @code{5557})
+The TCP port of the publish server. It defaults to @code{5557}.
+
+@item @code{log-file} (default: @code{"/var/log/cuirass-remote-server.log"})
+Location of the log file.
+
+@item @code{cache} (default: @code{"/var/cache/cuirass/remote"})
+Use @var{cache} directory to cache build log files.
+
+@item @code{trigger-url} (default: @code{#f})
+Once a substitute is successfully fetched, trigger substitute baking at
+@var{trigger-url}.
+
+@item @code{public-key}
+@item @code{private-key}
+Use the specific @var{file}s as the public/private key pair used to sign
+the store items being published.
+
+@end table
+@end deftp
+
+At least one remote worker must also be started on any machine of the
+local network to actually perform the builds and report their status.
+
+@deftp {Data Type} cuirass-remote-worker-configuration
+Data type representing the configuration of the Cuirass remote-worker.
+
+@table @asis
@item @code{cuirass} (default: @code{cuirass})
The Cuirass package to use.
+
+@item @code{workers} (default: @code{1})
+Start @var{workers} parallel workers.
+
+@item @code{server} (default: @code{#f})
+Do not use Avahi discovery and connect to the given @code{server} IP
+address instead.
+
+@item @code{systems} (default: @code{(list (%current-system))})
+Only request builds for the given @var{systems}.
+
+@item @code{log-file} (default: @code{"/var/log/cuirass-remote-worker.log"})
+Location of the log file.
+
+@item @code{publish-port} (default: @code{5558})
+The TCP port of the publish server. It defaults to @code{5558}.
+
+@item @code{public-key}
+@item @code{private-key}
+Use the specific @var{file}s as the public/private key pair used to sign
+the store items being published.
+
+@end table
+@end deftp
+
+@subsubheading Laminar
+
+@uref{https://laminar.ohwg.net/, Laminar} is a lightweight and modular
+Continuous Integration service. It doesn't have a configuration web UI
+instead uses version-controllable configuration files and scripts.
+
+Laminar encourages the use of existing tools such as bash and cron
+instead of reinventing them.
+
+@defvr {Scheme Procedure} laminar-service-type
+The type of the Laminar service. Its value must be a
+@code{laminar-configuration} object, as described below.
+
+All configuration values have defaults, a minimal configuration to get
+Laminar running is shown below. By default, the web interface is
+available on port 8080.
+
+@lisp
+(service laminar-service-type)
+@end lisp
+@end defvr
+
+@deftp {Data Type} laminar-configuration
+Data type representing the configuration of Laminar.
+
+@table @asis
+@item @code{laminar} (default: @code{laminar})
+The Laminar package to use.
+
+@item @code{home-directory} (default: @code{"/var/lib/laminar"})
+The directory for job configurations and run directories.
+
+@item @code{bind-http} (default: @code{"*:8080"})
+The interface/port or unix socket on which laminard should listen for
+incoming connections to the web frontend.
+
+@item @code{bind-rpc} (default: @code{"unix-abstract:laminar"})
+The interface/port or unix socket on which laminard should listen for
+incoming commands such as build triggers.
+
+@item @code{title} (default: @code{"Laminar"})
+The page title to show in the web frontend.
+
+@item @code{keep-rundirs} (default: @code{0})
+Set to an integer defining how many rundirs to keep per job. The
+lowest-numbered ones will be deleted. The default is 0, meaning all run
+dirs will be immediately deleted.
+
+@item @code{archive-url} (default: @code{#f})
+The web frontend served by laminard will use this URL to form links to
+artefacts archived jobs.
+
+@item @code{base-url} (default: @code{#f})
+Base URL to use for links to laminar itself.
+
@end table
@end deftp
@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"}.
@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{""}.
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})
-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}
-handlers to be used within the build environment, which in turn means
-that you can transparently build programs for another architecture.
-
For example, let's suppose you're on an x86_64 machine and you have this
service:
@lisp
(service qemu-binfmt-service-type
(qemu-binfmt-configuration
- (platforms (lookup-qemu-platforms "arm"))
- (guix-support? #t)))
+ (platforms (lookup-qemu-platforms "arm"))))
@end lisp
You can run:
@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!
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
@item @code{coordinator} (default: @code{"http://localhost:8745"})
The URI to use when connecting to the coordinator.
-@item @code{uuid}
-The UUID of the agent. This should be generated by the coordinator
-process, stored in the coordinator database, and used by the intended
-agent.
-
-@item @code{password} (default: @code{#f})
-The password to use when connecting to the coordinator. A file to read
-the password from can also be specified, and this is more secure.
-
-@item @code{password-file} (default: @code{#f})
-A file containing the password to use when connecting to the
-coordinator.
+@item @code{authentication}
+Record describing how this agent should authenticate with the
+coordinator. Possible record types are described below.
@item @code{systems} (default: @code{#f})
The systems for which this agent should fetch builds. The agent process
@end table
@end deftp
+@deftp {Data Type} guix-build-coordinator-agent-password-auth
+Data type representing an agent authenticating with a coordinator via a
+UUID and password.
+
+@table @asis
+@item @code{uuid}
+The UUID of the agent. This should be generated by the coordinator
+process, stored in the coordinator database, and used by the intended
+agent.
+
+@item @code{password}
+The password to use when connecting to the coordinator.
+
+@end table
+@end deftp
+
+@deftp {Data Type} guix-build-coordinator-agent-password-file-auth
+Data type representing an agent authenticating with a coordinator via a
+UUID and password read from a file.
+
+@table @asis
+@item @code{uuid}
+The UUID of the agent. This should be generated by the coordinator
+process, stored in the coordinator database, and used by the intended
+agent.
+
+@item @code{password-file}
+A file containing the password to use when connecting to the
+coordinator.
+
+@end table
+@end deftp
+
+@deftp {Data Type} guix-build-coordinator-agent-dynamic-auth
+Data type representing an agent authenticating with a coordinator via a
+dynamic auth token and agent name.
+
+@table @asis
+@item @code{agent-name}
+Name of an agent, this is used to match up to an existing entry in the
+database if there is one. When no existing entry is found, a new entry
+is automatically added.
+
+@item @code{token}
+Dynamic auth token, this is created and stored in the coordinator
+database, and is used by the agent to authenticate.
+
+@end table
+@end deftp
+
+@deftp {Data Type} guix-build-coordinator-agent-dynamic-auth-with-file
+Data type representing an agent authenticating with a coordinator via a
+dynamic auth token read from a file and agent name.
+
+@table @asis
+@item @code{agent-name}
+Name of an agent, this is used to match up to an existing entry in the
+database if there is one. When no existing entry is found, a new entry
+is automatically added.
+
+@item @code{token-file}
+File containing the dynamic auth token, this is created and stored in
+the coordinator database, and is used by the agent to authenticate.
+
+@end table
+@end deftp
+
The Guix Build Coordinator package contains a script to query an
instance of the Guix Data Service for derivations to build, and then
submit builds for those derivations to the coordinator. The service
(sysctl-configuration
(settings '(("net.ipv4.ip_forward" . "1")))))
@end lisp
+
+Since @code{sysctl-service-type} is used in the default lists of
+services, @code{%base-services} and @code{%desktop-services}, you can
+use @code{modify-services} to change its configuration and add the
+kernel parameters that you want (@pxref{Service Reference,
+@code{modify-services}}).
+
+@lisp
+(modify-services %base-services
+ (sysctl-service-type config =>
+ (sysctl-configuration
+ (settings (append '(("net.ipv4.ip_forward" . "1"))
+ %default-sysctl-settings)))))
+@end lisp
+
@end defvr
@deftp {Data Type} sysctl-configuration
@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
The @command{sysctl} executable to use.
-@item @code{settings} (default: @code{'()})
+@item @code{settings} (default: @code{%default-sysctl-settings})
An association list specifies kernel parameters and their values.
@end table
@end deftp
+@defvr {Scheme Variable} %default-sysctl-settings
+An association list specifying the default @command{sysctl} parameters
+on Guix System.
+@end defvr
+
@cindex pcscd
@subsubheading PC/SC Smart Card Daemon Service
@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
@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
+@item 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}.
-@cindex disk-image, creating disk images
-The @code{disk-image} command can produce various image types. 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{raw}. When its value is @code{iso9660}, the
+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}. By default, the root file system of a disk image is
+@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{disk-image}, the bootloader
+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:
@example
-image=$(guix system disk-image --image-type=qcow2 \
- gnu/system/examples/lightweight-desktop.tmpl)
+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{raw} image type, a raw disk image is produced; it
-can be copied as is to a USB stick, for instance. Assuming
+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
-@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 creating virtual machine images
+When using the @code{qcow2} image type, 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 @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
Docker container using commands like the following:
@example
-image_id="`docker load < guix-system-docker-image.tar.gz`"
-container_id="`docker create $image_id`"
+image_id="$(docker load < guix-system-docker-image.tar.gz)"
+container_id="$(docker create $image_id)"
docker start $container_id
@end example
can run:
@example
-guix system vm-image --save-provenance config.scm
+guix system image -t qcow2 --save-provenance config.scm
@end example
That way, the resulting image will effectively ``embed its own source''
@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
-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}).
+For the @code{image} action, 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}).
When this option is omitted, @command{guix system} computes an estimate
of the image size as a function of the size of the system declared in
before you can use it. When invoking QEMU, you must choose a system
emulator that is suitable for your hardware platform. Here is a minimal
QEMU invocation that will boot the result of @command{guix system
-vm-image} on x86_64 hardware:
+image -t qcow2} on x86_64 hardware:
@example
$ qemu-system-x86_64 \
@command{guix system vm} does not add a @command{-nic user} flag by default.
To get network access from within the vm add the @code{(dhcp-client-service)}
to your system definition and start the VM using
-@command{`guix system vm config.scm` -nic user}. An important caveat of using
+@command{$(guix system vm config.scm) -nic user}. An important caveat of using
@command{-nic user} for networking is that @command{ping} will not work, because
it uses the ICMP protocol. You'll have to use a different command to check for
network connectivity, for example @command{guix download}.
22 by default, to the host. You can do this with
@example
-`guix system vm config.scm` -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
+$(guix system vm config.scm) -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
@end example
To connect to the VM you can run
@example
-ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022
+ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 localhost
@end example
The @command{-p} tells @command{ssh} the port you want to connect to.
@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
@end table
@end deftp
+The example below defines a Shepherd service that spawns
+@command{syslogd}, the system logger from the GNU Networking Utilities
+(@pxref{syslogd invocation, @command{syslogd},, inetutils, GNU
+Inetutils}):
+
+@example
+(let ((config (plain-file "syslogd.conf" "@dots{}")))
+ (shepherd-service
+ (documentation "Run the syslog daemon (syslogd).")
+ (provision '(syslogd))
+ (requirement '(user-processes))
+ (start #~(make-forkexec-constructor
+ (list #$(file-append inetutils "/libexec/syslogd")
+ "--rcfile" #$config)
+ #:pid-file "/var/run/syslog.pid"))
+ (stop #~(make-kill-destructor))))
+@end example
+
+Key elements in this example are the @code{start} and @code{stop}
+fields: they are @dfn{staged} code snippets that use the
+@code{make-forkexec-constructor} procedure provided by the Shepherd and
+its dual, @code{make-kill-destructor} (@pxref{Service De- and
+Constructors,,, shepherd, The GNU Shepherd Manual}). The @code{start}
+field will have @command{shepherd} spawn @command{syslogd} with the
+given option; note that we pass @code{config} after @option{--rcfile},
+which is a configuration file declared above (contents of this file are
+omitted). Likewise, the @code{stop} field tells how this service is to
+be stopped; in this case, it is stopped by making the @code{kill} system
+call on its PID@. Code staging is achieved using G-expressions:
+@code{#~} stages code, while @code{#$} ``escapes'' back to host code
+(@pxref{G-Expressions}).
+
@deftp {Data Type} shepherd-action
This is the data type that defines additional actions implemented by a
Shepherd service (see above).
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
+
+The following example specifies the Shepherd package for the operating
+system:
+
+@lisp
+(operating-system
+ ;; ...
+ (services (append (list openssh-service-type))
+ ;; ...
+ %desktop-services)
+ ;; ...
+ ;; Use own Shepherd package.
+ (essential-services
+ (modify-services (operating-system-default-essential-services
+ this-operating-system)
+ (shepherd-root-service-type config => (shepherd-configuration
+ (inherit config)
+ (shepherd my-shepherd))))))
+@end lisp
+
@defvr {Scheme Variable} %shepherd-root-service
This service represents PID@tie{}1.
@end defvr
@cindex man pages
@cindex manual pages
In most cases packages installed with Guix come with documentation.
-There are two main documentation formats: ``Info'', a browseable
+There are two main documentation formats: ``Info'', a browsable
hypertext format used for GNU software, and ``manual pages'' (or ``man
pages''), the linear documentation format traditionally found on Unix.
Info manuals are accessed with the @command{info} command or with Emacs,
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
(@pxref{Invoking guix gc}):
@example
-guix gc -R `readlink -f ~/.guix-profile` | grep bash
+guix gc -R $(readlink -f ~/.guix-profile) | grep bash
@end example
@noindent
Likewise for a complete Guix system generation:
@example
-guix gc -R `guix system build my-config.scm` | grep bash
+guix gc -R $(guix system build my-config.scm) | grep bash
@end example
Lastly, to check which Bash running processes are using, you can use the
Gzip, Sed, and Tar. The rest of the bootstrap binary seeds that were
removed are now built from source.
-Building the GNU System from source is currently only possibly by adding
+Building the GNU System from source is currently only possible by adding
some historical GNU packages as intermediate steps@footnote{Packages
such as @code{gcc-2.95.3}, @code{binutils-2.14}, @code{glibc-2.2.5},
@code{gzip-1.2.4}, @code{tar-1.22}, and some others. For details, see
The only significant binary bootstrap seeds that remain@footnote{
Ignoring the 68KB @code{mescc-tools}; that will be removed later,
-together with @code{mes}.} are a Scheme intepreter and a Scheme
+together with @code{mes}.} are a Scheme interpreter and a Scheme
compiler: GNU Mes and GNU Guile@footnote{Not shown in this graph are the
static binaries for @file{bash}, @code{tar}, and @code{xz} that are used
to get Guile running.}.
HCoop / jackhill / guix / guix.git / blobdiff