me
/
guix
Archived
1
0
Fork 0

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.
Ludovic Courtès 2020-10-21 17:06:07 +02:00
parent 3b6e4e5fd0
commit c6ef627c97
No known key found for this signature in database
GPG Key ID: 090B11993D9AEBB5
1 changed files with 115 additions and 7 deletions

View File

@ -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