Previous: Invoking guix describe
, Up: Package Management [Contents][Index]
guix archive
The guix archive
command allows users to export files
from the store into a single archive, and to later import them on
a machine that runs Guix.
In particular, it allows store files to be transferred from one machine
to the store on another machine.
Note: If you’re looking for a way to produce archives in a format suitable for tools other than Guix, see Invoking
guix pack
.
To export store files as an archive to standard output, run:
guix archive --export options specifications...
specifications may be either store file names or package
specifications, as for guix package
(see Invoking guix package
). For instance, the following command creates an archive
containing the gui
output of the git
package and the main
output of emacs
:
guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
If the specified packages are not built yet, guix archive
automatically builds them. The build process may be controlled with the
common build options (see Common Build Options).
To transfer the emacs
package to a machine connected over SSH,
one would run:
guix archive --export -r emacs | ssh the-machine guix archive --import
Similarly, a complete user profile may be transferred from one machine to another like this:
guix archive --export -r $(readlink -f ~/.guix-profile) | \ ssh the-machine guix archive --import
However, note that, in both examples, all of emacs
and the
profile as well as all of their dependencies are transferred (due to
-r), regardless of what is already available in the store on
the target machine. The --missing option can help figure out
which items are missing from the target store. The guix copy
command simplifies and optimizes this whole process, so this is probably
what you should use in this case (see Invoking guix copy
).
Each store item is written in the normalized archive or nar
format (described below), and the output of guix archive
--export
(and input of guix archive --import
) is a nar
bundle.
The nar format is comparable in spirit to ‘tar’, but with differences that make it more appropriate for our purposes. First, rather than recording all Unix metadata for each file, the nar format only mentions the file type (regular, directory, or symbolic link); Unix permissions and owner/group are dismissed. Second, the order in which directory entries are stored always follows the order of file names according to the C locale collation order. This makes archive production fully deterministic.
That nar bundle format is essentially the concatenation of zero or more nars along with metadata for each store item it contains: its file name, references, corresponding derivation, and a digital signature.
When exporting, the daemon digitally signs the contents of the archive, and that digital signature is appended. When importing, the daemon verifies the signature and rejects the import in case of an invalid signature or if the signing key is not authorized.
The main options are:
--export
Export the specified store files or packages (see below). Write the resulting archive to the standard output.
Dependencies are not included in the output, unless --recursive is passed.
-r
--recursive
When combined with --export, this instructs guix archive
to include dependencies of the given items in the archive. Thus, the
resulting archive is self-contained: it contains the closure of the
exported store items.
--import
Read an archive from the standard input, and import the files listed therein into the store. Abort if the archive has an invalid digital signature, or if it is signed by a public key not among the authorized keys (see --authorize below).
--missing
Read a list of store file names from the standard input, one per line, and write on the standard output the subset of these files missing from the store.
--generate-key[=parameters]
¶Generate a new key pair for the daemon. This is a prerequisite before
archives can be exported with --export. This
operation is usually instantaneous but it can take time if the system’s
entropy pool needs to be refilled. On Guix System,
guix-service-type
takes care of generating this key pair the
first boot.
The generated key pair is typically stored under /etc/guix, in
signing-key.pub (public key) and signing-key.sec (private
key, which must be kept secret). When parameters is omitted,
an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
versions before 1.6.0, it is a 4096-bit RSA key.
Alternatively, parameters can specify
genkey
parameters suitable for Libgcrypt (see gcry_pk_genkey
in The
Libgcrypt Reference Manual).
Authorize imports signed by the public key passed on standard input. The public key must be in “s-expression advanced format”—i.e., the same format as the signing-key.pub file.
The list of authorized keys is kept in the human-editable file /etc/guix/acl. The file contains “advanced-format s-expressions” and is structured as an access-control list in the Simple Public-Key Infrastructure (SPKI).
--extract=directory
-x directory
Read a single-item archive as served by substitute servers (see Substitutes) and extract it to directory. This is a low-level operation needed in only very narrow use cases; see below.
For example, the following command extracts the substitute for Emacs
served by ci.guix.gnu.org
to /tmp/emacs:
$ wget -O - \ https://ci.guix.gnu.org/nar/gzip/…-emacs-24.5 \ | gunzip | guix archive -x /tmp/emacs
Single-item archives are different from multiple-item archives produced
by guix archive --export
; they contain a single store item,
and they do not embed a signature. Thus this operation does
no signature verification and its output should be considered
unsafe.
The primary purpose of this operation is to facilitate inspection of
archive contents coming from possibly untrusted substitute servers
(see Invoking guix challenge
).
--list
-t
Read a single-item archive as served by substitute servers (see Substitutes) and print the list of files it contains, as in this example:
$ wget -O - \ https://ci.guix.gnu.org/nar/lzip/…-emacs-26.3 \ | lzip -d | guix archive -t
Previous: Invoking guix describe
, Up: Package Management [Contents][Index]