@include version.texi
@c Identifier of the OpenPGP key used to sign tarballs and such.
-@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
-@set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=15145
+@set OPENPGP-SIGNING-KEY-ID 27D586A4F8900854329FF09F1260E46482E63562
+@set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=127547
@c Base URL for downloads.
@set BASE-URL https://ftp.gnu.org/gnu/guix
@c The official substitute server used by default.
-@set SUBSTITUTE-SERVER ci.guix.gnu.org
-@set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER}
+@set SUBSTITUTE-SERVER-1 ci.guix.gnu.org
+@set SUBSTITUTE-SERVER-2 bordeaux.guix.gnu.org
+@set SUBSTITUTE-URLS https://@value{SUBSTITUTE-SERVER-1} https://@value{SUBSTITUTE-SERVER-2}
@copying
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ludovic Courtès@*
Copyright @copyright{} 2020 Jakub Kądziołka@*
Copyright @copyright{} 2020 Jack Hill@*
Copyright @copyright{} 2020 Naga Malleswari@*
-Copyright @copyright{} 2020 Brice Waegeneire@*
+Copyright @copyright{} 2020, 2021 Brice Waegeneire@*
Copyright @copyright{} 2020 R Veera Kumar@*
Copyright @copyright{} 2020 Pierre Langlois@*
Copyright @copyright{} 2020 pinoaffe@*
Copyright @copyright{} 2020 Edgar Vincent@*
Copyright @copyright{} 2021 Maxime Devos@*
Copyright @copyright{} 2021 B. Wilson@*
+Copyright @copyright{} 2021 Xinglu Chen@*
+Copyright @copyright{} 2021 Raghav Gururajan@*
+Copyright @copyright{} 2021 Domagoj Stolfa@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
Substitutes
-* Official Substitute Server:: One particular source of substitutes.
+* Official Substitute Servers:: One particular source of substitutes.
* Substitute Server Authorization:: How to enable or disable substitutes.
* Getting Substitutes from Other Servers:: Substitute diversity.
* Substitute Authentication:: How Guix verifies substitutes.
@item
@cindex substitutes, authorization thereof
-To use substitutes from @code{@value{SUBSTITUTE-SERVER}} or one of its mirrors
-(@pxref{Substitutes}), authorize them:
+To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}},
+@code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
+authorize them:
@example
# guix archive --authorize < \
- ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.pub
+ ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
+# guix archive --authorize < \
+ ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
@end example
+@quotation Note
+If you do not enable substitutes, Guix will end up building
+@emph{everything} from source on your machine, making each installation
+and upgrade very expensive. @xref{On Trusting Binaries}, for a
+discussion of reasons why one might want do disable substitutes.
+@end quotation
+
@item
Each user may need to perform a few additional steps to make their Guix
environment ready for use, @pxref{Application Setup}.
GNU Guix depends on the following packages:
@itemize
-@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x or
-2.2.x;
+@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x;
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@item
@item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
@item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
@item
-@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
+@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0
or later;
@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
4.3.0 or later;
@item --substitute-urls=@var{urls}
Consider @var{urls} the default whitespace-separated list of substitute
source URLs. When this option is omitted,
-@indicateurl{https://@value{SUBSTITUTE-SERVER}} is used.
+@indicateurl{@value{SUBSTITUTE-URLS}} is used.
This means that substitutes may be downloaded from @var{urls}, as long
as they are signed by a trusted signature (@pxref{Substitutes}).
An ISO-9660 installation image that can be written to a USB stick or
burnt to a DVD can be downloaded from
-@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.xz},
+@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso},
where you can replace @code{x86_64-linux} with one of:
@table @code
authenticity of the image against it, along these lines:
@example
-$ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.xz.sig
-$ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.xz.sig
+$ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
+$ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
@end example
If that command fails because you do not have the required public key,
@unnumberedsubsec Copying to a USB Stick
-To copy the image to a USB stick, follow these steps:
-
-@enumerate
-@item
-Decompress the image using the @command{xz} command:
-
-@example
-xz -d guix-system-install-@value{VERSION}.x86_64-linux.iso.xz
-@end example
-
-@item
Insert a USB stick of 1@tie{}GiB or more into your machine, and determine
its device name. Assuming that the USB stick is known as @file{/dev/sdX},
copy the image with:
@end example
Access to @file{/dev/sdX} usually requires root privileges.
-@end enumerate
@unnumberedsubsec Burning on a DVD
-To copy the image to a DVD, follow these steps:
-
-@enumerate
-@item
-Decompress the image using the @command{xz} command:
-
-@example
-xz -d guix-system-install-@value{VERSION}.x86_64-linux.iso.xz
-@end example
-
-@item
Insert a blank DVD into your machine, and determine
its device name. Assuming that the DVD drive is known as @file{/dev/srX},
copy the image with:
@end example
Access to @file{/dev/srX} usually requires root privileges.
-@end enumerate
@unnumberedsubsec Booting
@end quotation
Now, @pxref{Getting Started}, and
-join us on @code{#guix} on the Freenode IRC network or on
+join us on @code{#guix} on the Libera Chat IRC network or on
@email{guix-devel@@gnu.org} to share your experience!
also result from derivation builds, can be available as substitutes.
@menu
-* Official Substitute Server:: One particular source of substitutes.
+* Official Substitute Servers:: One particular source of substitutes.
* Substitute Server Authorization:: How to enable or disable substitutes.
* Getting Substitutes from Other Servers:: Substitute diversity.
* Substitute Authentication:: How Guix verifies substitutes.
* On Trusting Binaries:: How can you trust that binary blob?
@end menu
-@node Official Substitute Server
-@subsection Official Substitute Server
+@node Official Substitute Servers
+@subsection Official Substitute Servers
@cindex build farm
-The @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an official build farm
-that builds packages from Guix continuously for some
-architectures, and makes them available as substitutes. This is the
-default source of substitutes; it can be overridden by passing the
+@code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}} are both front-ends to official build
+farms that build packages from Guix continuously for some architectures,
+and make them available as substitutes. These are the default source of
+substitutes; which can be overridden by passing the
@option{--substitute-urls} option either to @command{guix-daemon}
(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
or to client tools such as @command{guix package}
could use the information gathered to determine, for instance, whether
your system has unpatched security vulnerabilities.
-Substitutes from the official build farm are enabled by default when
+Substitutes from the official build farms are enabled by default when
using Guix System (@pxref{GNU Distribution}). However,
they are disabled by default when using Guix on a foreign distribution,
unless you have explicitly enabled them via one of the recommended
@cindex substitutes, authorization thereof
@cindex access control list (ACL), for substitutes
@cindex ACL (access control list), for substitutes
-To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER}} or a
-mirror thereof, you
-must add its public key to the access control list (ACL) of archive
+To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, @code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you
+must add the relevant public key to the access control list (ACL) of archive
imports, using the @command{guix archive} command (@pxref{Invoking guix
-archive}). Doing so implies that you trust @code{@value{SUBSTITUTE-SERVER}} to not
+archive}). Doing so implies that you trust the substitute server to not
be compromised and to serve genuine substitutes.
@quotation Note
If you are using Guix System, you can skip this section: Guix System
-authorizes substitutes from @code{@value{SUBSTITUTE-SERVER}} by default.
+authorizes substitutes from @code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}} by default.
@end quotation
-The public key for @code{@value{SUBSTITUTE-SERVER}} is installed along with Guix, in
-@code{@var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, where @var{prefix} is
-the installation prefix of Guix. If you installed Guix from source,
-make sure you checked the GPG signature of
+The public keys for each of the project maintained substitute servers
+are installed along with Guix, in @code{@var{prefix}/share/guix/}, where
+@var{prefix} is the installation prefix of Guix. If you installed Guix
+from source, make sure you checked the GPG signature of
@file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
Then, you can run something like this:
@example
-# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub
+# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
+# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
@end example
Once this is in place, the output of a command like @code{guix build}
@noindent
The text changed from ``The following derivations would be built'' to
``112.3 MB would be downloaded''. This indicates that substitutes from
-@code{@value{SUBSTITUTE-SERVER}} are usable and will be downloaded, when
-possible, for future builds.
+the configured substitute servers are usable and will be downloaded,
+when possible, for future builds.
@cindex substitutes, how to disable
The substitute mechanism can be disabled globally by running
As an example, suppose you want to fetch substitutes from
@code{guix.example.org} and to authorize the signing key of that server,
-in addition to the default @code{@value{SUBSTITUTE-SERVER}}. The
-resulting operating system configuration will look something like:
+in addition to the default @code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}}. The resulting operating system
+configuration will look something like:
@lisp
(operating-system
@code{guix-daemon --substitute-urls}}):
@example
-@dots{} --substitute-urls='https://guix.example.org https://@value{SUBSTITUTE-SERVER}'
+@dots{} --substitute-urls='https://guix.example.org @value{SUBSTITUTE-URLS}'
@end example
@item
@end enumerate
Now you're all set! Substitutes will be preferably taken from
-@code{https://guix.example.org}, using @code{@value{SUBSTITUTE-SERVER}}
-as a fallback. Of course you can list as many substitute servers as you
-like, with the caveat that substitute lookup can be slowed down if too
-many servers need to be contacted.
+@code{https://guix.example.org}, using
+@code{@value{SUBSTITUTE-SERVER-1}} then
+@code{@value{SUBSTITUTE-SERVER-2}} as fallback options. Of course you
+can list as many substitute servers as you like, with the caveat that
+substitute lookup can be slowed down if too many servers need to be
+contacted.
Note that there are also situations where one may want to add the URL of
a substitute server @emph{without} authorizing its key.
Today, each individual's control over their own computing is at the
mercy of institutions, corporations, and groups with enough power and
determination to subvert the computing infrastructure and exploit its
-weaknesses. While using @code{@value{SUBSTITUTE-SERVER}} substitutes can be
-convenient, we encourage users to also build on their own, or even run
-their own build farm, such that @code{@value{SUBSTITUTE-SERVER}} is less of an
-interesting target. One way to help is by publishing the software you
-build using @command{guix publish} so that others have one more choice
-of server to download substitutes from (@pxref{Invoking guix publish}).
+weaknesses. While using substitutes can be convenient, we encourage
+users to also build on their own, or even run their own build farm, such
+that the project run substitute servers are less of an interesting
+target. One way to help is by publishing the software you build using
+@command{guix publish} so that others have one more choice of server to
+download substitutes from (@pxref{Invoking guix publish}).
Guix has the foundations to maximize build reproducibility
(@pxref{Features}). In most cases, independent builds of a given
low-level operation needed in only very narrow use cases; see below.
For example, the following command extracts the substitute for Emacs
-served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:
+served by @code{@value{SUBSTITUTE-SERVER-1}} to @file{/tmp/emacs}:
@example
$ wget -O - \
- https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \
+ https://@value{SUBSTITUTE-SERVER-1}/nar/gzip/@dots{}-emacs-24.5 \
| gunzip | guix archive -x /tmp/emacs
@end example
@example
$ wget -O - \
- https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \
+ https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-emacs-26.3 \
| lzip -d | guix archive -t
@end example
their dependencies, you can run:
@example
-$ guix pack guile emacs geiser
+$ guix pack guile emacs emacs-geiser
@dots{}
/gnu/store/@dots{}-pack.tar.gz
@end example
@file{/opt/gnu/bin} symlink to the profile:
@example
-guix pack -S /opt/gnu/bin=bin guile emacs geiser
+guix pack -S /opt/gnu/bin=bin guile emacs emacs-geiser
@end example
@noindent
command:
@example
-guix pack -f squashfs bash guile emacs geiser
+guix pack -f squashfs bash guile emacs emacs-geiser
@end example
@noindent
The name of the package, as a string.
@item @code{version}
-The version of the package, as a string.
+The version of the package, as a string. @xref{Version Numbers}, for
+guidelines.
@item @code{source}
An object telling how the source code for the package should be
Some older packages that aren't using @file{Package.toml} yet, will require
this file to be created, too. The function @code{julia-create-package-toml}
helps creating the file. You need to pass the outputs and the source of the
-package, it's name (the same as the @code{file-name} parameter), the package
+package, its name (the same as the @code{file-name} parameter), the package
uuid, the package version, and a list of dependencies specified by their name
and their uuid.
@end defvr
@example
$ guix build --log-file gdb -s aarch64-linux
-https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10
+https://@value{SUBSTITUTE-SERVER-1}/log/@dots{}-gdb-7.10
@end example
You can freely access a huge library of build logs!
version to its name, so that multiple versions of the same package can
coexist.
@end table
+
+@item egg
+@cindex egg
+Import metadata for @uref{https://wiki.call-cc.org/eggs, CHICKEN eggs}.
+The information is taken from @file{PACKAGE.egg} files found in the
+@uref{git://code.call-cc.org/eggs-5-latest, eggs-5-latest} Git
+repository. However, it does not provide all the information that we
+need, there is no ``description'' field, and the licenses used are not
+always precise (BSD is often used instead of BSD-N).
+
+@example
+guix import egg sourcehut
+@end example
+
+Additional options include:
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@end table
@end table
The structure of the @command{guix import} code is modular. It would be
the updater for X.org packages;
@item kernel.org
the updater for packages hosted on kernel.org;
+@item egg
+the updater for @uref{https://wiki.call-cc.org/eggs/, Egg} packages;
@item elpa
the updater for @uref{https://elpa.gnu.org/, ELPA} packages;
@item cran
@example
$ guix refresh --list-dependent flex
Building the following 120 packages would ensure 213 dependent packages are rebuilt:
-hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
+hop@@2.4.0 emacs-geiser@@0.13 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
@end example
The command above lists a set of packages that could be built to check
anyone with network access to obtain substitutes from it. This means
that any machine running Guix can also act as if it were a build farm,
since the HTTP interface is compatible with Cuirass, the software behind
-the @code{@value{SUBSTITUTE-SERVER}} build farm.
+the @code{@value{SUBSTITUTE-SERVER-1}} build farm.
For security, each substitute is signed, allowing recipients to check
their authenticity and integrity (@pxref{Substitutes}). Because
not been accessed for @var{ttl} and that no longer have a corresponding
item in the store, may be deleted.
+@item --negative-ttl=@var{ttl}
+Similarly produce @code{Cache-Control} HTTP headers to advertise the
+time-to-live (TTL) of @emph{negative} lookups---missing store items, for
+which the HTTP 404 code is returned. By default, no negative TTL is
+advertised.
+
+This parameter can help adjust server load and substitute latency by
+instructing cooperating clients to be more or less patient when a store
+item is missing.
+
@item --cache-bypass-threshold=@var{size}
When used in conjunction with @option{--cache}, store items smaller than
@var{size} are immediately available, even when they are not yet in
The command output looks like this:
@smallexample
-$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org"
-updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 100.0%
+$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
+updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
updating list of substitutes from 'https://guix.example.org'... 100.0%
/gnu/store/@dots{}-openssl-1.0.2d contents differ:
local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
- https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
+ https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
differing files:
/lib/libcrypto.so.1.1
/gnu/store/@dots{}-git-2.5.0 contents differ:
local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
- https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
+ https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
differing file:
/libexec/git-core/git-fsck
/gnu/store/@dots{}-pius-2.1.1 contents differ:
local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
- https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
+ https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
differing file:
/share/man/man1/pius.1.gz
@cindex non-determinism, in package builds
As an example, @code{guix.example.org} always gets a different answer.
-Conversely, @code{@value{SUBSTITUTE-SERVER}} agrees with local builds, except in the
+Conversely, @code{@value{SUBSTITUTE-SERVER-1}} agrees with local builds, except in the
case of Git. This might indicate that the build process of Git is
non-deterministic, meaning that its output varies as a function of
various things that Guix does not fully control, in spite of building
@example
guix challenge git \
--diff=diffoscope \
- --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org"
+ --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
@end example
This automatically invokes @command{diffoscope}, which displays detailed
archive}):
@example
-$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-git-2.5.0 \
+$ wget -q -O - https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-git-2.5.0 \
| lzip -d | guix archive -x /tmp/git
$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
@end example
This command shows the difference between the files resulting from the
local build, and the files resulting from the build on
-@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging Files,,
+@code{@value{SUBSTITUTE-SERVER-1}} (@pxref{Overview, Comparing and Merging Files,,
diffutils, Comparing and Merging Files}). The @command{diff} command
works great for text files. When binary files differ, a better option
is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
the problem.
If you are writing packages for Guix, you are encouraged to check
-whether @code{@value{SUBSTITUTE-SERVER}} and other substitute servers obtain the
+whether @code{@value{SUBSTITUTE-SERVER-1}} and other substitute servers obtain the
same build result as you did with:
@example
@var{b} usually lacks substitutes as well. The result looks like this:
@example
-$ guix weather --substitute-urls=@value{SUBSTITUTE-URL} -c 10
+$ guix weather --substitute-urls=@value{SUBSTITUTE-URLS} -c 10
computing 8,983 package derivations for x86_64-linux...
-looking for 9,343 store items on @value{SUBSTITUTE-URL}...
-updating substitutes from '@value{SUBSTITUTE-URL}'... 100.0%
-@value{SUBSTITUTE-URL}
+looking for 9,343 store items on @value{SUBSTITUTE-URLS}...
+updating substitutes from '@value{SUBSTITUTE-URLS}'... 100.0%
+@value{SUBSTITUTE-URLS}
64.7% substitutes available (6,047 out of 9,343)
@dots{}
-2502 packages are missing from '@value{SUBSTITUTE-URL}' for 'x86_64-linux', among which:
+2502 packages are missing from '@value{SUBSTITUTE-URLS}' for 'x86_64-linux', among which:
58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0
46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1
37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008
What this example shows is that @code{kcoreaddons} and presumably the 58
packages that depend on it have no substitutes at
-@code{@value{SUBSTITUTE-SERVER}}; likewise for @code{qgpgme} and the 46
+@code{@value{SUBSTITUTE-SERVER-1}}; likewise for @code{qgpgme} and the 46
packages that depend on it.
If you are a Guix developer, or if you are taking care of this build farm,
(operating-system
;; ...
- (packages (cons (list bind "utils")
+ (packages (cons (list isc-bind "utils")
%base-packages)))
@end lisp
@findex specification->package
-Referring to packages by variable name, like @code{bind} above, has
+Referring to packages by variable name, like @code{isc-bind} above, has
the advantage of being unambiguous; it also allows typos and such to be
diagnosed right away as ``unbound variables''. The downside is that one
needs to know which module defines which package, and to augment the
@item @code{authorize-key?} (default: @code{#t})
@cindex substitutes, authorization thereof
Whether to authorize the substitute keys listed in
-@code{authorized-keys}---by default that of @code{@value{SUBSTITUTE-SERVER}}
+@code{authorized-keys}---by default that of
+@code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}}
(@pxref{Substitutes}).
When @code{authorize-key?} is true, @file{/etc/guix/acl} cannot be
@item @code{authorized-keys} (default: @code{%default-authorized-guix-keys})
The list of authorized key files for archive imports, as a list of
string-valued gexps (@pxref{Invoking guix archive}). By default, it
-contains that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitutes}).
-See @code{substitute-urls} below for an example on how to change it.
+contains that of @code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}} (@pxref{Substitutes}). See
+@code{substitute-urls} below for an example on how to change it.
@item @code{use-substitutes?} (default: @code{#t})
Whether to use substitutes.
The list of URLs where to look for substitutes by default.
Suppose you would like to fetch substitutes from @code{guix.example.org}
-in addition to @code{@value{SUBSTITUTE-SERVER}}. You will need to do
+in addition to @code{@value{SUBSTITUTE-SERVER-1}}. You will need to do
two things: (1) add @code{guix.example.org} to @code{substitute-urls},
and (2) authorize its signing key, having done appropriate checks
(@pxref{Substitute Server Authorization}). The configuration below does
:INPUT ACCEPT
:FORWARD ACCEPT
:OUTPUT ACCEPT
+-A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
-A INPUT -p tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp-port-unreachable
COMMIT
:INPUT ACCEPT
:FORWARD ACCEPT
:OUTPUT ACCEPT
+-A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
-A INPUT -p tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp6-port-unreachable
COMMIT
detailed discussion of each configuration field.
@end deftp
+@cindex opendht, distributed hash table network service
+@cindex dhtproxy, for use with jami
+@defvr {Scheme Variable} opendht-service-type
+This is the type of the service running a @uref{https://opendht.net,
+OpenDHT} node, @command{dhtnode}. The daemon can be used to host your
+own proxy service to the distributed hash table (DHT), for example to
+connect to with Jami, among other applications.
+
+@quotation Important
+When using the OpenDHT proxy server, the IP addresses it ``sees'' from
+the clients should be addresses reachable from other peers. In practice
+this means that a publicly reachable address is best suited for a proxy
+server, outside of your private network. For example, hosting the proxy
+server on a IPv4 private local network and exposing it via port
+forwarding could work for external peers, but peers local to the proxy
+would have their private addresses shared with the external peers,
+leading to connectivity problems.
+@end quotation
+
+The value of this service is a @code{opendht-configuration} object, as
+described below.
+@end defvr
+
+@deftp {Data Type} opendht-configuration
+This is the data type for the OpenDHT service configuration.
+
+@c The fields documentation has been auto-generated using the
+@c configuration->documentation procedure from
+@c (gnu services configuration).
+Available @code{opendht-configuration} fields are:
+
+@deftypevr {@code{opendht-configuration} parameter} package opendht
+The @code{opendht} package to use.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} boolean peer-discovery?
+Whether to enable the multicast local peer discovery mechanism.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} boolean enable-logging?
+Whether to enable logging messages to syslog. It is disabled by default
+as it is rather verbose.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} boolean debug?
+Whether to enable debug-level logging messages. This has no effect if
+logging is disabled.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} maybe-string bootstrap-host
+The node host name that is used to make the first connection to the
+network. A specific port value can be provided by appending the
+@code{:PORT} suffix. By default, it uses the Jami bootstrap nodes, but
+any host can be specified here. It's also possible to disable
+bootsrapping by setting this to the @code{'disabled} symbol.
+
+Defaults to @samp{"bootstrap.jami.net:4222"}.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} maybe-number port
+The UDP port to bind to. When set to @code{'disabled}, an available
+port is automatically selected.
+
+Defaults to @samp{4222}.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port
+Spawn a proxy server listening on the specified port.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+
+@deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port-tls
+Spawn a proxy server listening to TLS connections on the specified port.
+
+Defaults to @samp{disabled}.
+
+@end deftypevr
+@end deftp
+
@cindex Tor
@defvr {Scheme Variable} tor-service-type
This is the type for a service that runs the @uref{https://torproject.org,
(service openssh-service-type
(openssh-configuration
(x11-forwarding? #t)
- (permit-root-login 'without-password)
+ (permit-root-login 'prohibit-password)
(authorized-keys
`(("alice" ,(local-file "alice.pub"))
("bob" ,(local-file "bob.pub"))))))
@item @code{permit-root-login} (default: @code{#f})
This field determines whether and when to allow logins as root. If
@code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
-If it's the symbol @code{'without-password}, then root logins are
+If it's the symbol @code{'prohibit-password}, then root logins are
permitted but not with password-based authentication.
@item @code{allow-empty-passwords?} (default: @code{#f})
Defaults to @samp{#t}.
@end deftypevr
-@deftypevr {@code{cups-configuration} parameter} non-negative-integer keep-alive-timeout
-Specifies how long an idle client connection remains open, in seconds.
-
-Defaults to @samp{30}.
-@end deftypevr
-
@deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
Specifies the maximum size of print files, IPP requests, and HTML form
data. A limit of 0 disables the limit check.
to the printer's requesting-user-name-allowed or
requesting-user-name-denied values. @code{@@OWNER} maps to the job's
owner. @code{@@SYSTEM} maps to the groups listed for the
-@code{system-group} field of the @code{files-config} configuration,
+@code{system-group} field of the @code{files-configuration},
which is reified into the @code{cups-files.conf(5)} file. Other
possible elements of the access list include specific user names, and
@code{@@@var{group}} to indicate members of a specific group. The
@code{@@ACL} maps to the printer's requesting-user-name-allowed or
requesting-user-name-denied values. @code{@@OWNER} maps to the job's
owner. @code{@@SYSTEM} maps to the groups listed for the
-@code{system-group} field of the @code{files-config} configuration,
+@code{system-group} field of the @code{files-configuration},
which is reified into the @code{cups-files.conf(5)} file. Other
possible elements of the access list include specific user names, and
@code{@@@var{group}} to indicate members of a specific group. The
@end deftp
@deffn {Scheme Variable} lxqt-desktop-service-type
-This is the type of the service that runs the @uref{https://lxqt.github.io,
+This is the type of the service that runs the @uref{https://lxqt-project.org,
LXQt desktop environment}. Its value is a @code{lxqt-desktop-configuration}
object (see below).
It defaults to @samp{"/var/run/dovecot/auth-userdb"}.
@end deftypevr
+@deftypevr {@code{protocol-configuration} parameter} boolean imap-metadata?
+Whether to enable the @code{IMAP METADATA} extension as defined in
+@uref{https://tools.ietf.org/html/rfc5464,RFC@tie{}5464}, which provides
+a means for clients to set and retrieve per-mailbox, per-user metadata
+and annotations over IMAP.
+
+If this is @samp{#t}, you must also specify a dictionary @i{via} the
+@code{mail-attribute-dict} setting.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-notify-capabilities
+Which NOTIFY capabilities to report to clients that first connect to
+the ManageSieve service, before authentication. These may differ from the
+capabilities offered to authenticated users. If this field is left empty,
+report what the Sieve interpreter supports by default.
+
+Defaults to @samp{()}.
+@end deftypevr
+
+@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-sieve-capability
+Which SIEVE capabilities to report to clients that first connect to
+the ManageSieve service, before authentication. These may differ from the
+capabilities offered to authenticated users. If this field is left empty,
+report what the Sieve interpreter supports by default.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins
Space separated list of plugins to load.
@end deftypevr
@samp{""}.
@end deftypevr
+@deftypevr {@code{dovecot-configuration} parameter} string mail-attribute-dict
+The location of a dictionary used to store @code{IMAP METADATA}
+as defined by @uref{https://tools.ietf.org/html/rfc5464, RFC@tie{}5464}.
+
+The IMAP METADATA commands are available only if the ``imap''
+protocol configuration's @code{imap-metadata?} field is @samp{#t}.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
Allow full file system access to clients. There's no access checks
other than what the operating system does for the active UID/GID@. It
If set to @samp{0}, getmail will only print warnings and errors. A
value of @samp{1} means that messages will be printed about retrieving
and deleting messages. If set to @samp{2}, getmail will print messages
-about each of it's actions.
+about each of its actions.
Defaults to @samp{1}.
@deftp {Data type} php-fpm-dynamic-process-manager-configuration
Data Type for the @code{dynamic} php-fpm process manager. With the
@code{dynamic} process manager, spare worker processes are kept around
-based on it's configured limits.
+based on its configured limits.
@table @asis
@item @code{max-children} (default: @code{5})
Maximum of worker processes.
and gives Let's Encrypt permission to log the public IP address of the
requesting machine.
+@item @code{csr} (default: @code{#f})
+File name of Certificate Signing Request (CSR) in DER or PEM format.
+If @code{#f} is specified, this argument will not be passed to certbot.
+If a value is specified, certbot will use it to obtain a certificate, instead of
+using a self-generated CSR.
+The domain-name(s) mentioned in @code{domains}, must be consistent with the
+domain-name(s) mentioned in CSR file.
+
@item @code{authentication-hook} (default: @code{#f})
Command to be run in a shell once for each certificate challenge to be
answered. For this command, the shell variable @code{$CERTBOT_DOMAIN}
@end deftypevr
-
@c %end of automatic openvpn-server documentation
+@subheading strongSwan
+
+Currently, the strongSwan service only provides legacy-style configuration with
+@file{ipsec.conf} and @file{ipsec.secrets} files.
+
+@defvr {Scheme Variable} strongswan-service-type
+A service type for configuring strongSwan for IPsec @acronym{VPN,
+Virtual Private Networking}. Its value must be a
+@code{strongswan-configuration} record as in this example:
+
+@lisp
+(service strongswan-service-type
+ (strongswan-configuration
+ (ipsec-conf "/etc/ipsec.conf")
+ (ipsec-secrets "/etc/ipsec.secrets")))
+@end lisp
+
+@end defvr
+
+@deftp {Data Type} strongswan-configuration
+Data type representing the configuration of the StrongSwan service.
+
+@table @asis
+@item @code{strongswan}
+The strongSwan package to use for this service.
+
+@item @code{ipsec-conf} (default: @code{#f})
+The file name of your @file{ipsec.conf}. If not @code{#f}, then this and
+@code{ipsec-secrets} must both be strings.
+
+@item @code{ipsec-secrets} (default @code{#f})
+The file name of your @file{ipsec.secrets}. If not @code{#f}, then this and
+@code{ipsec-conf} must both be strings.
+
+@end table
+@end deftp
+
@subsubheading Wireguard
@defvr {Scheme Variable} wireguard-service-type
;; Ganeti uses SSH to communicate between nodes.
(service openssh-service-type
(openssh-configuration
- (permit-root-login 'without-password)))
+ (permit-root-login 'prohibit-password)))
(service ganeti-service-type
(ganeti-configuration
The kernel module loader service allows one to load loadable kernel
modules at boot. This is especially useful for modules that don't
-autoload and need to be manually loaded, as it's the case with
+autoload and need to be manually loaded, as is the case with
@code{ddcci}.
@deffn {Scheme Variable} kernel-module-loader-service-type
@cindex Platform Reliability, Availability and Serviceability daemon
@subsubheading Rasdaemon Service
-The Rasdaemon service provides a daemon which monitors the platform Reliablity,
-Availability and Serviceability (RAS) reports from the Linux kernel trace
-events, logging them to syslogd.
+The Rasdaemon service provides a daemon which monitors platform
+@acronym{RAS, Reliability@comma{} Availability@comma{} and Serviceability} reports from
+Linux kernel trace events, logging them to syslogd.
Reliability, Availability and Serviceability is a concept used on servers meant
to measure their robustness.
emulated machine:
@example
-$ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -net user,model=virtio-net-pci
+$ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -nic user,model=virtio-net-pci
@end example
The VM shares its store with the host system.
@section Running Guix in a Virtual Machine
@cindex virtual machine
-To run Guix in a virtual machine (VM), one can use the pre-built Guix VM image
-distributed at
-@url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.xz}.
-This image is a compressed image in QCOW format. You will first need to
-decompress with @command{xz -d}, and then you can pass it to an emulator such
-as QEMU (see below for details).
+To run Guix in a virtual machine (VM), one can use the pre-built Guix VM
+image distributed at
+@url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2}.
+This image is a compressed image in QCOW format. You can pass it to an
+emulator such as @uref{https://qemu.org/, QEMU} (see below for details).
This image boots the Xfce graphical environment and it contains some
commonly used tools. You can install more software in the image by running
as @file{/run/current-system/configuration.scm} (@pxref{Using the
Configuration System}).
-Instead of using this pre-built image, one can also build their own virtual
-machine image using @command{guix system vm-image} (@pxref{Invoking guix
-system}). The returned image is in qcow2 format, which the
-@uref{https://qemu.org/, QEMU emulator} can efficiently use.
+Instead of using this pre-built image, one can also build their own
+image using @command{guix system image} (@pxref{Invoking guix system}).
@cindex QEMU
If you built your own image, you must copy it out of the store
@command{-o StrictHostKeyChecking=no} prevents you from having to allow a
connection to an unknown host every time you connect.
+@quotation Note
+If you find the above @samp{hostfwd} example not to be working (e.g.,
+your SSH client hangs attempting to connect to the mapped port of your
+VM), make sure that your Guix System VM has networking support, such as
+by using the @code{dhcp-client-service-type} service type.
+@end quotation
+
@subsection Using @command{virt-viewer} with Spice
As an alternative to the default @command{qemu} graphical client you can
@command{guix system init}, or @command{guix deploy}.
@end defvr
+@defvr {Scheme Variable} linux-loadable-module-service-type
+Type of the service that collects lists of packages containing
+kernel-loadable modules, and adds them to the set of kernel-loadable
+modules.
+
+This service type is intended to be extended by other service types,
+such as below:
+
+@lisp
+(simple-service 'installing-module
+ linux-loadable-module-service-type
+ (list module-to-install-1
+ module-to-install-2))
+@end lisp
+
+This does not actually load modules at bootup, only adds it to the
+kernel profile so that it @emph{can} be loaded by other means.
+@end defvr
+
@node Shepherd Services
@subsection Shepherd Services
HCoop / jackhill / guix / guix.git / blobdiff