The purpose of
guix publish is to enable users to easily share
their store with others, who can then use it as a substitute server
guix publish runs, it spawns an HTTP server which allows
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 Hydra, the software behind
hydra.gnu.org build farm.
For security, each substitute is signed, allowing recipients to check
their authenticity and integrity (see Substitutes). Because
guix publish uses the signing key of the system, which is only
readable by the system administrator, it must be started as root; the
--user option makes it drop root privileges early on.
The signing key pair must be generated before
guix publish is
guix archive --generate-key (see Invoking guix archive).
The general syntax is:
guix publish options…
guix publish without any additional arguments will
spawn an HTTP server on port 8080:
Once a publishing server has been authorized (see Invoking guix archive), the daemon may download substitutes from it:
guix publish compresses archives on the fly as it
serves them. This “on-the-fly” mode is convenient in that it requires
no setup and is immediately available. However, when serving lots of
clients, we recommend using the --cache option, which enables
caching of the archives before they are sent to clients—see below for
guix weather command provides a handy way to
check what a server provides (see Invoking guix weather).
As a bonus,
guix publish also serves as a content-addressed
mirror for source files referenced in
(see origin Reference). For instance, assuming
publish is running on
example.org, the following URL returns the
raw hello-2.10.tar.gz file with the given SHA256 hash
nix-base32 format, see Invoking guix hash):
Obviously, these URLs only work for files that are in the store; in other cases, they return 404 (“Not Found”).
The following options are available:
Listen for HTTP requests on port.
Listen on the network interface for host. The default is to accept connections from any interface.
Change privileges to user as soon as possible—i.e., once the server socket is open and the signing key has been read.
Compress data using the given level. When level is zero, disable compression. The range 1 to 9 corresponds to different gzip compression levels: 1 is the fastest, and 9 is the best (CPU-intensive). The default is 3.
Unless --cache is used, compression occurs on the fly and
the compressed streams are not
cached. Thus, to reduce load on the machine that runs
publish, it may be a good idea to choose a low compression level, to
guix publish behind a caching proxy, or to use
--cache. Using --cache has the advantage that it
guix publish to add
Content-Length HTTP header
to its responses.
Cache archives and meta-data (
.narinfo URLs) to directory
and only serve archives that are in cache.
When this option is omitted, archives and meta-data are created
on-the-fly. This can reduce the available bandwidth, especially when
compression is enabled, since this may become CPU-bound. Another
drawback of the default mode is that the length of archives is not known
in advance, so
guix publish does not add a
Content-Length HTTP header to its responses, which in turn
prevents clients from knowing the amount of data being downloaded.
Conversely, when --cache is used, the first request for a store
item (via a
.narinfo URL) returns 404 and triggers a
background process to bake the archive—computing its
.narinfo and compressing the archive, if needed. Once the
archive is cached in directory, subsequent requests succeed and
are served directly from the cache, which guarantees that clients get
the best possible bandwidth.
The “baking” process is performed by worker threads. By default, one thread per CPU core is created, but this can be customized. See --workers below.
When --ttl is used, cached entries are automatically deleted when they have expired.
When --cache is used, request the allocation of N worker threads to “bake” archives.
Cache-Control HTTP headers that advertise a time-to-live
(TTL) of ttl. ttl must denote a duration:
5d means 5
1m means 1 month, and so on.
This allows the user’s Guix to keep substitute information in cache for
ttl. However, note that
guix publish does not itself
guarantee that the store items it provides will indeed remain available
for as long as ttl.
Additionally, when --cache is used, cached entries that have not been accessed for ttl and that no longer have a corresponding item in the store, may be deleted.
Use path as the prefix for the URLs of “nar” files (see normalized archives).
By default, nars are served at a URL such as
/nar/gzip/…-coreutils-8.25. This option allows you to
/nar part to path.
Use the specific files as the public/private key pair used to sign the store items being published.
The files must correspond to the same key pair (the private key is used
for signing and the public key is merely advertised in the signature
metadata). They must contain keys in the canonical s-expression format
as produced by
guix archive --generate-key (see Invoking guix archive). By default, /etc/guix/signing-key.pub and
/etc/guix/signing-key.sec are used.
Spawn a Guile REPL server (see REPL Servers in GNU Guile
Reference Manual) on port (37146 by default). This is used
primarily for debugging a running
guix publish server.
guix publish on a GuixSD system is a one-liner: just
guix-publish-service-type service in the
operating-system declaration (see
If you are instead running Guix on a “foreign distro”, follow these instructions:”
# ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \ /etc/systemd/system/ # systemctl start guix-publish && systemctl enable guix-publish
# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/ # start guix-publish