Previous: Invoking guix pull, 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.
In particular, it allows store files to be transferred from one machine
to another machine’s store. For example, 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 target
machine’s store. The --missing
option can help figure out which
items are missing from the target’s store.
Archives are stored in the “Nix archive” or “Nar” format, which is comparable in spirit to ‘tar’, but with a few noteworthy differences that make it more appropriate for our purposes. First, rather than recording all Unix meta-data 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.
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 daemons. This is a prerequisite before
archives can be exported with --export
. Note that this operation
usually takes time, because it needs to gather enough entropy to
generate the key pair.
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.
Alternately, parameters can specify
genkey
parameters suitable for Libgcrypt (see gcry_pk_genkey
in The
Libgcrypt Reference Manual).
--authorize
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 hydra.gnu.org
to /tmp/emacs:
$ wget -O - \ http://hydra.gnu.org/nar/…-emacs-24.5 \ | bunzip2 | 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.
To export store files as an archive to the 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
same options that can be passed to the guix build
command
(see common build options).
Previous: Invoking guix pull, Up: Package Management [Contents][Index]