Previous: Invocando guix describe
, Up: Gerenciamento de pacote [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.
Nota: If you’re looking for a way to produce archives in a format suitable for tools other than Guix, see Invocando
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 Invocando 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 Opções de compilação comum).
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 Invocando 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 Substitutos) 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 Invocando guix challenge
).
--list
-t
Read a single-item archive as served by substitute servers (see Substitutos) 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: Invocando guix describe
, Up: Gerenciamento de pacote [Contents][Index]