Previous: , Up: Package Management   [Contents][Index]


3.8 Invoking 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 emacs | ssh the-machine guix archive --import

However, note that, in this example, all of emacs and its dependencies are transferred, 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.

--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, 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).

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: , Up: Package Management   [Contents][Index]