Module tar 

Losslessly export and import ostree commits as tar archives

Convert an ostree commit into a tarball stream, and import it again, including support for OSTree signature verification.

In the current libostree C library, while it supports export to tar, this process is lossy - commit metadata is discarded. Further, re-importing requires recalculating all of the object checksums, and tying these together, it does not support verifying ostree level cryptographic signatures such as GPG/ed25519.

Tar stream layout

In order to solve these problems, this new tar serialization format effectively combines both a /sysroot/ostree/repo/objects directory and a checkout in /usr, where the latter are hardlinks to the former.

The exported stream will have the ostree metadata first; in particular the commit object. Following the commit object is the .commitmeta object, which contains any cryptographic signatures.

This library then supports verifying the pair of (commit, commitmeta) using an ostree remote, in the same way that ostree pull will do.

The remainder of the stream is a breadth-first traversal of dirtree/dirmeta objects and the content objects they reference.

bare-split-xattrs repository mode

In format version 1, the tar stream embeds a proper ostree repository using a tailored bare-split-xattrs mode.

This is because extended attributes (xattrs) are a complex subject for tar, which has many variants. Further, when exporting bootable ostree commits to container images, it is not actually desired to have the container runtime try to unpack and apply those.

For these reasons, extended attributes (xattrs) get serialized into detached objects which are associated with the relevant content objects.

At a low level, two dedicated object types are used:

• file-xattrs as regular files storing (and de-duplicating) xattrs content.
• file-xattrs-link as hardlinks which associate a file object to its corresponding file-xattrs object.

Modules

export 🔒

APIs for creating container images from OSTree commits

import 🔒

APIs for extracting OSTree commits from container images

write 🔒

APIs to write a tarball stream into an OSTree commit.

Structs

ExportOptions

Configuration for tar export.

TarImportOptions

Configuration for tar import.

WriteTarOptions

Configuration for tar layer commits.

WriteTarResult

The result of writing a tar stream.

Constants

BARE_SPLIT_XATTRS_MODE

The repository mode generated by a tar export stream.

Functions

export_commit

Export an ostree commit to an (uncompressed) tar archive stream.

import_tar

Read the contents of a tarball and import the ostree commit inside. Returns the sha256 of the imported commit.

import_tar_objects

Read the contents of a tarball and import the content objects inside. Generates a synthetic commit object referencing them.

update_detached_metadata

Replace the detached metadata in an tar stream which is an export of an OSTree commit.

write_tar

Write the contents of a tarball as an ostree commit.