summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2020-10-21 17:06:07 +0200
committerLudovic Courtès <ludo@gnu.org>2020-10-25 01:06:10 +0200
commitc6ef627c97e5e6a94688baf20892ae3429f86897 (patch)
tree06371cade36103f55a1cd249a4330373fc22167b
parent3b6e4e5fd05e72b8a32ff1a2d5e21464260e21e6 (diff)
doc: Add "Getting Substitutes from Other Servers" section.
* doc/guix.texi (Getting Substitutes from Other Servers): New node. (Invoking guix-daemon): Add cross-reference. (Substitute Server Authorization): Clarify that this is unnecessary on Guix System. (Invoking guix publish): Add cross-reference.
-rw-r--r--doc/guix.texi122
1 files changed, 115 insertions, 7 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index f2fc567865..efb4ea1c47 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -222,6 +222,7 @@ Substitutes
* Official Substitute Server:: 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.
* Proxy Settings:: How to get substitutes via proxy.
* Substitution Failure:: What happens when substitution fails.
@@ -1467,8 +1468,8 @@ When the daemon runs with @option{--no-substitutes}, clients can still
explicitly enable substitution @i{via} the @code{set-build-options}
remote procedure call (@pxref{The Store}).
-@item --substitute-urls=@var{urls}
@anchor{daemon-substitute-urls}
+@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.
@@ -1476,6 +1477,9 @@ source URLs. When this option is omitted,
This means that substitutes may be downloaded from @var{urls}, as long
as they are signed by a trusted signature (@pxref{Substitutes}).
+@xref{Getting Substitutes from Other Servers}, for more information on
+how to configure the daemon to get substitutes from other servers.
+
@cindex offloading
@item --no-offload
Do not use offload builds to other machines (@pxref{Daemon Offload
@@ -3554,6 +3558,7 @@ also result from derivation builds, can be available as substitutes.
@menu
* Official Substitute Server:: 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.
* Proxy Settings:: How to get substitutes via proxy.
* Substitution Failure:: What happens when substitution fails.
@@ -3603,6 +3608,11 @@ imports, using the @command{guix archive} command (@pxref{Invoking guix
archive}). Doing so implies that you trust @code{@value{SUBSTITUTE-SERVER}} to not
be compromised and to serve genuine substitutes.
+@quotation Note
+If you are using Guix System, you can skip this section: Guix System
+authorizes substitutes from @code{@value{SUBSTITUTE-SERVER}} 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,
@@ -3653,6 +3663,108 @@ guix-daemon}). It can also be disabled temporarily by passing the
@option{--no-substitutes} option to @command{guix package},
@command{guix build}, and other command-line tools.
+@node Getting Substitutes from Other Servers
+@subsection Getting Substitutes from Other Servers
+
+@cindex substitute servers, adding more
+Guix can look up and fetch substitutes from several servers. This is
+useful when you are using packages from additional channels for which
+the official server does not have substitutes but another server
+provides them. Another situation where this is useful is when you would
+prefer to download from your organization's substitute server, resorting
+to the official server only as a fallback or dismissing it altogether.
+
+You can give Guix a list of substitute server URLs and it will check
+them in the specified order. You also need to explicitly authorize the
+public keys of substitute servers to instruct Guix to accept the
+substitutes they sign.
+
+On Guix System, this is achieved by modifying the configuration of the
+@code{guix} service. Since the @code{guix} service is part of 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 URLs and substitute keys that you want
+(@pxref{Service Reference, @code{modify-services}}).
+
+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:
+
+@lisp
+(operating-system
+ ;; @dots{}
+ (services
+ ;; Assume we're starting from '%desktop-services'. Replace it
+ ;; with the list of services you're actually using.
+ (modify-services %desktop-services
+ (guix-service-type config =>
+ (guix-configuration
+ (inherit config)
+ (substitute-urls
+ (append (list "https://guix.example.org")
+ %default-substitute-urls))
+ (authorized-keys
+ (append (list (local-file "./key.pub"))
+ %default-authorized-guix-keys)))))))
+@end lisp
+
+This assumes that the file @file{key.pub} contains the signing key of
+@code{guix.example.org}. With this change in place in your operating
+system configuration file (say @file{/etc/config.scm}), you can
+reconfigure and restart the @code{guix-daemon} service or reboot so the
+changes take effect:
+
+@example
+$ sudo guix system reconfigure /etc/config.scm
+$ sudo herd restart guix-daemon
+@end example
+
+If you're running Guix on a ``foreign distro'', you would instead take
+the following steps to get substitutes from additional servers:
+
+@enumerate
+@item
+Edit the service configuration file for @code{guix-daemon}; when using
+systemd, this is normally
+@file{/etc/systemd/system/guix-daemon.service}. Add the
+@option{--substitute-urls} option on the @command{guix-daemon} command
+line and list the URLs of interest (@pxref{daemon-substitute-urls,
+@code{guix-daemon --substitute-urls}}):
+
+@example
+@dots{} --substitute-urls='https://guix.example.org https://@value{SUBSTITUTE-SERVER}'
+@end example
+
+@item
+Restart the daemon. For systemd, it goes like this:
+
+@example
+systemctl daemon-reload
+systemctl restart guix-daemon.service
+@end example
+
+@item
+Authorize the key of the new server (@pxref{Invoking guix archive}):
+
+@example
+guix archive --authorize < key.pub
+@end example
+
+Again this assumes @file{key.pub} contains the public key that
+@code{guix.example.org} uses to sign substitutes.
+@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.
+
+Note that there are also situations where one may want to add the URL of
+a substitute server @emph{without} authorizing its key.
+@xref{Substitute Authentication}, to understand this fine point.
+
@node Substitute Authentication
@subsection Substitute Authentication
@@ -11873,12 +11985,8 @@ spawn an HTTP server on port 8080:
guix publish
@end example
-Once a publishing server has been authorized (@pxref{Invoking guix
-archive}), the daemon may download substitutes from it:
-
-@example
-guix-daemon --substitute-urls=http://example.org:8080
-@end example
+Once a publishing server has been authorized, the daemon may download
+substitutes from it. @xref{Getting Substitutes from Other Servers}.
By default, @command{guix publish} compresses archives on the fly as it
serves them. This ``on-the-fly'' mode is convenient in that it requires