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 Cuirass, the software behind the
ci.guix.gnu.org build farm.
For security, each substitute is signed, allowing recipients to check their
authenticity and integrity (see substitutes). Because
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 调用guix archive).
When the --advertise option is passed, the server advertises its availability on the local network using multicast DNS (mDNS) and DNS service discovery (DNS-SD), currently via Guile-Avahi (see Using Avahi in Guile Scheme Programs).
The general syntax is:
guix publish options…
guix publish without any additional arguments will spawn
an HTTP server on port 8080:
guix publish can also be started following the systemd “socket
activation” protocol (see
make-systemd-constructor in The GNU Shepherd Manual).
Once a publishing server has been authorized, the daemon may download substitutes from it. See Getting Substitutes from Other Servers.
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 details. The
guix weather command provides a handy way to check what a server
provides (see 调用guix weather).
As a bonus,
guix publish also serves as a content-addressed mirror
for source files referenced in
origin records (see origin参考手册). For instance, assuming
guix publish is running on
example.org, the following URL returns the raw
hello-2.10.tar.gz file with the given SHA256 hash (represented in
nix-base32 format, see 调用guix hash):
Obviously, these URLs only work for files that are in the store; in other cases, they return 404 (“Not Found”).
Build logs are available from
/log URLs like:
guix-daemon is configured to save compressed build logs, as
is the case by default (see 调用guix-daemon),
return the compressed log as-is, with an appropriate
Content-Encoding header. We recommend running
guix-daemon with --log-compression=gzip since Web
browsers can automatically decompress it, which is not the case with Bzip2
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 method and level. method is
gzip; when method is
gzip is used.
When level is zero, disable compression. The range 1 to 9 corresponds to different compression levels: 1 is the fastest, and 9 is the best (CPU-intensive). The default is 3.
lzip compresses noticeably better than
gzip for a
small increase in CPU usage; see
benchmarks on the lzip Web
lzip achieves low decompression throughput (on the
order of 50 MiB/s on modern hardware), which can be a bottleneck for
someone who downloads over a fast network connection.
The compression ratio of
zstd is between that of
lzip and that
gzip; its main advantage is a
high decompression speed.
Unless --cache is used, compression occurs on the fly and the
compressed streams are not cached. Thus, to reduce load on the machine that
guix publish, it may be a good idea to choose a low
compression level, to run
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
This option can be repeated, in which case every substitute gets compressed using all the selected methods, and all of them are advertised. This is useful when users may not support all the compression methods: they can select the one they support.
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) 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.
.narinfo request nonetheless returns 200, provided the
requested store item is “small enough”, below the cache bypass
threshold—see --cache-bypass-threshold below. That way, clients
do not have to wait until the archive is baked. For larger store items, the
.narinfo request returns 404, meaning that clients have to wait
until the archive is baked.
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
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.
Cache-Control HTTP headers to advertise the
time-to-live (TTL) of negative lookups—missing store items, for
which the HTTP 404 code is returned. By default, no negative TTL is
This parameter can help adjust server load and substitute latency by instructing cooperating clients to be more or less patient when a store item is missing.
When used in conjunction with --cache, store items smaller than
size are immediately available, even when they are not yet in cache.
size is a size in bytes, or it can be suffixed by
megabytes and so on. The default is
“Cache bypass” allows you to reduce the publication delay for clients at the expense of possibly additional I/O and CPU use on the server side: depending on the client access patterns, those store items can end up being baked several times until a copy is available in cache.
Increasing the threshold may be useful for sites that have few users, or to guarantee that users get substitutes even for store items that are not popular.
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 change
/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 调用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 Guix System is a one-liner: just
guix-publish-service-type service in the
services field of the
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