5.3.3 Getting Substitutes from Other Servers

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 guix service. Since the guix service is part of the default lists of services, %base-services and %desktop-services, you can use modify-services to change its configuration and add the URLs and substitute keys that you want (see modify-services).

As an example, suppose you want to fetch substitutes from guix.example.org and to authorize the signing key of that server, in addition to the default bordeaux.guix.gnu.org and ci.guix.gnu.org. The resulting operating system configuration will look something like:

(operating-system
  ;; …
  (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)))))))

This assumes that the file key.pub contains the signing key of guix.example.org. With this change in place in your operating system configuration file (say /etc/config.scm), you can reconfigure and restart the guix-daemon service or reboot so the changes take effect:

$ sudo guix system reconfigure /etc/config.scm
$ sudo herd restart guix-daemon

If you’re running Guix on a “foreign distro”, you would instead take the following steps to get substitutes from additional servers:

1. Edit the service configuration file for guix-daemon; when using systemd, this is normally /etc/systemd/system/guix-daemon.service. Add the --substitute-urls option on the guix-daemon command line and list the URLs of interest (see guix-daemon --substitute-urls):

   … --substitute-urls='https://guix.example.org https://bordeaux.guix.gnu.org https://ci.guix.gnu.org'
   

2. Restart the daemon. For systemd, it goes like this:

   systemctl daemon-reload
   systemctl restart guix-daemon.service
   

3. Authorize the key of the new server (see Invoking guix archive):

   guix archive --authorize < key.pub
   

   Again this assumes key.pub contains the public key that guix.example.org uses to sign substitutes.

Now you’re all set! Substitutes will be preferably taken from https://guix.example.org, using bordeaux.guix.gnu.org then ci.guix.gnu.org 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.

Troubleshooting: To diagnose problems, you can run guix weather. For example, running:

guix weather coreutils

not only tells you which of the currently-configured servers has substitutes for the coreutils package, it also reports whether one of these servers is unauthorized. See Invoking guix weather, for more information.

Note that there are also situations where one may want to add the URL of a substitute server without authorizing its key. See Substitute Authentication, to understand this fine point.