From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id uFftB3pSkF/TOQAA0tVLHw (envelope-from ) for ; Wed, 21 Oct 2020 15:23:38 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1 with LMTPS id gH2fA3pSkF+zXwAAbx9fmQ (envelope-from ) for ; Wed, 21 Oct 2020 15:23:38 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 9B5359404C9 for ; Wed, 21 Oct 2020 15:23:37 +0000 (UTC) Received: from localhost ([::1]:54842 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kVFxg-0001z5-HN for larch@yhetil.org; Wed, 21 Oct 2020 11:23:36 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:32982) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kVFja-0007io-Mk for bug-guix@gnu.org; Wed, 21 Oct 2020 11:09:02 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:38671) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kVFja-0000tn-8w for bug-guix@gnu.org; Wed, 21 Oct 2020 11:09:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1kVFja-0004FW-4G for bug-guix@gnu.org; Wed, 21 Oct 2020 11:09:02 -0400 X-Loop: help-debbugs@gnu.org Subject: bug#39819: [PATCH 2/2] doc: Add "Getting Substitutes from Other Servers" section. Resent-From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: bug-guix@gnu.org Resent-Date: Wed, 21 Oct 2020 15:09:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 39819 X-GNU-PR-Package: guix X-GNU-PR-Keywords: To: 39819@debbugs.gnu.org Received: via spool by 39819-submit@debbugs.gnu.org id=B39819.160329293416311 (code B ref 39819); Wed, 21 Oct 2020 15:09:02 +0000 Received: (at 39819) by debbugs.gnu.org; 21 Oct 2020 15:08:54 +0000 Received: from localhost ([127.0.0.1]:50216 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kVFjS-0004Ev-65 for submit@debbugs.gnu.org; Wed, 21 Oct 2020 11:08:54 -0400 Received: from eggs.gnu.org ([209.51.188.92]:54316) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kVFjQ-0004EX-6B for 39819@debbugs.gnu.org; Wed, 21 Oct 2020 11:08:53 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:50687) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kVFjK-0000rX-V6; Wed, 21 Oct 2020 11:08:46 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=43788 helo=gnu.org) by fencepost.gnu.org with esmtpsa (TLS1.2:DHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kVFjK-00063Y-GK; Wed, 21 Oct 2020 11:08:46 -0400 From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Date: Wed, 21 Oct 2020 17:08:23 +0200 Message-Id: <20201021150823.20508-2-ludo@gnu.org> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201021150823.20508-1-ludo@gnu.org> References: <87v9fhf3my.fsf@inria.fr> <20201021150823.20508-1-ludo@gnu.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-Spam-Score: -3.3 (---) X-BeenThere: bug-guix@gnu.org List-Id: Bug reports for GNU Guix List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: guix-devel@gnu.org Errors-To: bug-guix-bounces+larch=yhetil.org@gnu.org Sender: "bug-Guix" X-Scanner: scn0 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of bug-guix-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=bug-guix-bounces@gnu.org X-Spam-Score: 3.49 X-TUID: IX4us7m1mV7g * 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. --- doc/guix.texi | 122 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 115 insertions(+), 7 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 50d2d9a730..a3534b5939 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 -- 2.28.0