ostree_ext/tar/
mod.rs

1//! # Losslessly export and import ostree commits as tar archives
2//!
3//! Convert an ostree commit into a tarball stream, and import it again, including
4//! support for OSTree signature verification.
5//!
6//! In the current libostree C library, while it supports export to tar, this
7//! process is lossy - commit metadata is discarded.  Further, re-importing
8//! requires recalculating all of the object checksums, and tying these
9//! together, it does not support verifying ostree level cryptographic signatures
10//! such as GPG/ed25519.
11//!
12//! # Tar stream layout
13//!
14//! In order to solve these problems, this new tar serialization format effectively
15//! combines *both* a `/sysroot/ostree/repo/objects` directory and a checkout in `/usr`,
16//! where the latter are hardlinks to the former.
17//!
18//! The exported stream will have the ostree metadata first; in particular the commit object.
19//! Following the commit object is the `.commitmeta` object, which contains any cryptographic
20//! signatures.
21//!
22//! This library then supports verifying the pair of (commit, commitmeta) using an ostree
23//! remote, in the same way that `ostree pull` will do.
24//!
25//! The remainder of the stream is a breadth-first traversal of dirtree/dirmeta objects and the
26//! content objects they reference.
27//!
28//! # `bare-split-xattrs` repository mode
29//!
30//! In format version 1, the tar stream embeds a proper ostree repository using a tailored
31//! `bare-split-xattrs` mode.
32//!
33//! This is because extended attributes (xattrs) are a complex subject for tar, which has
34//! many variants.
35//! Further, when exporting bootable ostree commits to container images, it is not actually
36//! desired to have the container runtime try to unpack and apply those.
37//!
38//! For these reasons, extended attributes (xattrs) get serialized into detached objects
39//! which are associated with the relevant content objects.
40//!
41//! At a low level, two dedicated object types are used:
42//!  * `file-xattrs` as regular files storing (and de-duplicating) xattrs content.
43//!  * `file-xattrs-link` as hardlinks which associate a `file` object to its corresponding
44//!    `file-xattrs` object.
45
46mod import;
47pub use import::*;
48mod export;
49pub use export::*;
50mod write;
51pub use write::*;