OSTree Manual |
|---|
for OSTree 2013.6
Table of Contents
OSTree is best summarized in a single sentence as "git for operating system binaries". At its core architecture is a userspace content-addressed filesystem, and layered on top of that is an administrative layer that is designed to atomically parallel install multiple bootable Unix-like operating systems.
While it takes over some of the roles of tradtional "package managers" like dpkg and rpm, it is not a package system; nor is it a tool for managing full disk images. Instead, OSTree sits between those levels, offering a blend of the advantages (and disadvantages) of both.
Because OSTree is designed for deploying core operating systems, a comparison with traditional "package managers" such as dpkg and rpm is illustrative. Packages are traditionally composed of partial filesystem trees with metadata and scripts attached, and these are dynamically assembled on the client machine, after a process of dependency resolution.
In contrast, OSTree only supports recording and deploying complete (bootable) filesystem trees. It has no built-in knowledge of how a given filesystem tree was generated or the origin of individual files, or dependencies, descriptions of individual components. This means that, for example, if you are distributing software which is licensed under the GNU General Public License, the burden lies with the tool generating these filesystem trees to ensure sufficent metadata is included for compliance.
The OSTree core emphasizes replicating read-only OS trees via
HTTP, and where the OS includes (if desired) an entirely
separate mechanism to install applications, stored in /var if they're system global, or
/home for per-user
application installation.
However, it is entirely possible to use OSTree underneath a
package system, where the contents of /usr are computed on the client.
For example, when installing a package, rather than mutating the
currently running filesystem, the package manager could assemble
a new filesystem tree that includes the new package, record it
in the local OSTree repository, and then set it up for the next
boot. To support this model, OSTree provides an
(introspectable) C shared library.
OSTree shares some similarity with "dumb" replication and stateless deployments, such as the model common in "cloud" deployments where nodes are booted from an (effectively) readonly disk, and user data is kept on a different volumes. The advantage of "dumb" replication, shared by both OSTree and the cloud model, is that it's reliable and predictable.
But unlike many default image-based deployments, OSTree supports
exactly two persistent writable directories that are preserved
across upgrades: /etc and
/var.
Because OSTree operates at the Unix filesystem layer, it works on top of any filesystem or block storage layout; it's possible to replicate a given filesystem tree from an OSTree repository into plain ext4, BTRFS, XFS, or in general any Unix-compatible filesystem that supports hard links. Note: OSTree will transparently take advantage of some BTRFS features if deployed on it.
Another deeply fundamental difference between both package
managers and image-based replication is that OSTree is
designed to parallel-install multiple
versions of multiple
independent operating systems. OSTree
relies on a new toplevel ostree directory; it can in fact
parallel install inside an existing OS or distribution
occupying the physical / root.
On each client machine, there is an OSTree repository stored
in /ostree/repo, and a
set of "deployments" stored in /ostree/deploy/.
Each deployment is primarily composed of a set of hardlinks
into the repository. This means each version is deduplicated;
an upgrade process only costs disk space proportional to the
new files, plus some constant overhead.
OSNAME/CHECKSUM
The model OSTree emphasizes is that the OS read-only content
is kept in the classic Unix /usr; it comes with code to
create a Linux read-only bind mount to prevent inadvertent
corruption. There is exactly one /var writable directory shared
between each deployment for a given OS. The OSTree core code
does not touch content in this directory; it is up to the code
in each operating system for how to manage and upgrade state.
Finally, each deployment has its own writable copy of the
configuration store /etc. On upgrade, OSTree will
perform a basic 3-way diff, and apply any local changes to the
new copy, while leaving the old untouched.
Table of Contents
OSTree is deeply inspired by git; the core layer is a userspace content-addressed versioning filesystem. It is worth taking some time to familiarize yourself with Git Internals, as this section will assume some knowledge of how git works.
Its object types are similar to git; it has commit objects and content objects. Git has "tree" objects, whereas OSTree splits them into "dirtree" and "dirmeta" objects. But unlike git, OSTree's checksums are SHA256. And most crucially, its content objects include uid, gid, and extended attributes (but still no timestamps).
A commit object contains metadata such as a timestamp, a log message, and most importantly, a reference to a dirtree/dirmeta pair of checksums which describe the root directory of the filesystem.
Also like git, each commit in OSTree can have a parent. It is designed to store a history of your binary builds, just like git stores a history of source control. However, OSTree also makes it easy to delete data, under the assumption that you can regenerate it from source code.
A dirtree contains a sorted array of (filename, checksum) pairs for content objects, and a second sorted array of (filename, dirtree checksum, dirmeta checksum), which are subdirectories.
In git, tree objects contain the metadata such as permissions for their children. But OSTree splits this into a separate object to avoid duplicating extended attribute listings.
Unlike the first three object types which are metadata,
designed to be mmap()ed, the content object
has a separate internal header and payload sections. The
header contains uid, gid, mode, and symbolic link target (for
symlinks), as well as extended attributes. After the header,
for regular files, the content follows.
Also unlike git, an OSTree repository can be in one of two
separate modes: bare and
archive-z2. A bare repository is one where
content files are just stored as regular files; it's designed to
be the source of a "hardlink farm", where each operating system
checkout is merely links into it. If you want to store files
owned by e.g. root in this mode, you must run OSTree as root.
In contrast, the archive-z2 mode is designed
for serving via plain HTTP. Like tar files, it can be
read/written by non-root users.
On an OSTree-deployed system, the "system repository" is
/ostree/repo. It can be
read by any uid, but only written by root. Unless the
--repo argument is given to the
ostree command, it will operate on the system
repository.
Like git, OSTree uses "refs" to which are text files that point
to particular commits (i.e. filesystem trees). For example, the
gnome-ostree operating system creates trees named like
gnome-ostree/buildmaster/x86_64-runtime and
gnome-ostree/buildmaster/x86_64-devel-debug.
These two refs point to two different generated filesystem
trees. In this example, the "runtime" tree contains just enough
to run a basic GNOME system, and "devel-debug" contains all of
the developer tools.
The ostree supports a simple syntax using the
carat ^ to refer to the parent of a given
commit. For example,
gnome-ostree/buildmaster/x86_64-runtime^
refers to the previous build, and
gnome-ostree/buildmaster/x86_64-runtime^^
refers to the one before that.
Table of Contents
Built on top of the OSTree versioning filesystem core is a layer that knows how to deploy, parallel install, and manage Unix-like operating systems (accessible via ostree admin). The core content of these operating systems are treated as read-only, but they transparently share storage.
A deployment is physically located at a path of the form
/ostree/deploy/.
OSTree is designed to boot directly into exactly one deployment
at a time; each deployment is intended to be a target for
osname/deploy/checksumchroot() or equivalent.
Each deployment is grouped in exactly one "osname". From
above, you can see that an osname is physically represented in
the /ostree/deploy/
directory. For example, OSTree can allow parallel installing
Debian in osname/ostree/deploy/debian and Red Hat
Enterprise Linux in /ostree/deploy/rhel (subject to
operating system support, present released versions of these
operating systems may not support this).
Each osname has exactly one copy of the traditional Unix
/var, stored physically
in /ostree/deploy/.
OSTree provides support tools for systemd
to create a Linux bind mount that ensures the booted
deployment sees the shared copy of osname/var/var.
OSTree does not touch the contents of /var. Operating system components
such as daemon services are required to create any directories
they require there at runtime (e.g. /var/cache/),
and to manage upgrading data formats inside those directories.
daemonname
A deployment begins with a specific commit (represented as a
SHA256 hash) in the OSTree repository in /ostree/repo. This commit refers
to a filesystem tree that represents the underlying basis of a
deployment. For short, we will call this the "tree", to
distinguish it from the concept of a deployment.
First, the tree must include a kernel stored as /boot/vmlinuz-.
The checksum should be a SHA256 hash of the kernel contents;
it must be pre-computed before storing the kernel in the
repository. Optionally, the tree can contain an initramfs,
stored as checksum/boot/initramfs-.
If this exists, the checksum must include both the kernel and
initramfs contents. OSTree will use this to determine which
kernels are shared. The rationale for this is to avoid
computing checksums on the client by default.
checksum
The deployment should not have a traditional UNIX /etc; instead, it should include
/usr/etc. This is the
"default configuration". When OSTree creates a deployment, it
performs a 3-way merge using the old
default configuration, the active system's /etc, and the new default
configuration. In the final filesystem tree for a deployment
then, /etc is a regular
writable directory.
Besides the exceptions of /var and /etc then, the rest of the
contents of the tree are checked out as hard links into the
repository. It's strongly recommended that operating systems
ship all of their content in /usr, but this is not a hard
requirement.
Finally, a deployment may have a .origin file, stored next to its
directory. This file tells ostree admin
upgrade how to upgrade it. At the moment, OSTree only
supports upgrading a single refspec. However, in the future
OSTree may support a syntax for composing layers of trees, for
example.
While OSTree parallel installs deployments cleanly inside the
/ostree directory,
ultimately it has to control the system's /boot directory. The way this
works is via the boot
loader specification, which is a standard for
bootloader-independent drop-in configuration files.
When a tree is deployed, it will have a configuration file
generated of the form /boot/loader/entries/ostree-.
This configuration file will include a special
osname-checksum.serial.confostree= kernel argument that allows the
initramfs to find (and chroot() into) the
specified deployment.
At present, not all bootloaders implement the BootLoaderSpec,
so OSTree contains code for some of these to regenerate native
config files (such as
/boot/syslinux/syslinux.conf based on the
entries.
Table of Contents
At the time of this writing, it's common for released versions of mainstream operating systems (the Playstation OS, Microsoft Windows, Debian GNU/Linux, and Red Hat Enterprise Linux) to have non-atomic upgrades; that is, the good ones pop up a screen that says "Please do not turn off the power". The bad ones don't even tell you that it's unsafe. The really bad ones actually mutate your running filesystem without taking precautions to prevent corrupting running processes.
In contrast, OSTree is designed to implement fully atomic and safe upgrades; more generally, atomic transitions between lists of bootable deployments. If the system crashes or you pull the power, you will have either the old system, or the new one.
First, the most basic model OSTree supports is one where it
replicates pre-generated filesystem trees from a server over
HTTP, tracking exactly one ref, which is stored in the .origin file for the deployment.
The command ostree admin upgrade implements
this.
To begin a simple upgrade, OSTree fetches the contents of the
ref from the remote server. Suppose we're tracking a ref named
gnome-ostree/buildmaster/x86_64-runtime.
OSTree fetches the URL
http://,
which contains a SHA256 checksum. This determines the tree to
deploy, and example.com/repo/refs/gnome-ostree/buildmaster/x86_64-runtime/etc will be
merged from currently booted tree.
If we do not have this commit, then, then we perform a pull
process. At present (without static deltas), this involves
quite simply just fetching each individual object that we do not
have, asynchronously. Put in other words, we only download
changed files (zlib-compressed). Each object has its checksum
validated and is stored in /ostree/repo/objects/.
Once the pull is complete, we have all the objects locally we need to perform a deployment.
As mentioned in the introduction, OSTree is also designed to allow a model where filesystem trees are computed on the client. It is completely agnostic as to how those trees are generated; they could be computed with traditional packages, packages with post-deployment scripts on top, or built by developers directly from revision control locally, etc.
At a practical level, most package managers today (dpkg and rpm) operate "live" on the currently booted filesystem. The way they could work with OSTree is instead to take the list of installed packages in the currently booted tree, and compute a new filesystem from that. A later chapter describes in more details how this could work: Part V, “Adapting existing mainstream distributions”.
For the purposes of this section, let's assume that we have a newly generated filesystem tree stored in the repo (which shares storage with the existing booted tree). We can then move on to checking it back out of the repo into a deployment.
Given a commit to deploy, OSTree first allocates a directory for
it. This is of the form /boot/loader/entries/ostree-.
The osname-checksum.serial.confserial is normally 0, but if a
given commit is deployed more than once, it will be incremented.
This is supported because the previous deployment may have
configuration in /etc
that we do not want to use or overwrite.
Now that we have a deployment directory, a 3-way merge is
performed between the (by default) currently booted deployment's
/etc, its default
configuration, and the new deployment (based on its /usr/etc).
At this point, a new deployment directory has been created as a hardlink farm; the running system is untouched, and the bootloader configuration is untouched. We want to add this deployment to the "deployment list".
To support a more general case, OSTree supports atomic transitioning between arbitrary sets of deployments, with the restriction that the currently booted deployment must always be in the new set. In the normal case, we have exactly one deployment, which is the booted one, and we want to add the new deployment to the list. A more complex command might allow creating 100 deployments as part of one atomic transaction, so that one can set up an automated system to bisect across them.
OSTree allows swapping between boot configurations by
implementing the "swapped directory pattern" in /boot. This means it is a
symbolic link to one of two directories /ostree/boot..
To swap the contents atomically, if the current version is
[0|1]0, we create /ostree/boot.1, populate it with
the new contents, then atomically swap the symbolic link. Finally,
the old contents can be garbage collected at any point.
However, we want to optimize for the case where we the set of
kernel/initramfs pairs is the same between both the old and
new deployment lists. This happens when doing an upgrade that
does not include the kernel; think of a simple translation
update. OSTree optimizes for this case because on some
systems /boot may be on
a separate medium such as flash storage not optimized for
significant amounts of write traffic.
To implement this, OSTree also maintains the directory
/ostree/boot.,
which is a set of symbolic links to the deployment
directories. The bootversionbootversion here
must match the version of /boot. However, in order to
allow atomic transitions of this
directory, this is also a swapped directory, so just like
/boot, it has a version
of 0 or 1 appended.
Each bootloader entry has a special ostree=
argument which refers to one of these symbolic links. This is
parsed at runtime in the initramfs.
Table of Contents
First, OSTree encourages systems to implement UsrMove.
This is simply to avoid the need for more bind mounts. By
default OSTree's dracut hook creates a read-only bind mount over
/usr; you can of course
generate individual bind-mounts for /bin, all the /lib variants, etc. So it is not
intended to be a hard requirement.
Remember, because by default the system is booted into a
chroot equivalent, there has to be some way
to refer to the actual physical root filesystem. Therefore,
your operating system tree should contain an empty /sysroot directory; at boot time,
OSTree will make this a bind mount to the physical / root
directory. There is precedent for this name in the initramfs
context. You should furthermore make a toplevel symbolic link
/ostree which points to
/sysroot/ostree, so that
the OSTree tool at runtime can consistently find the system data
regardless of whether it's operating on a physical root or
inside a deployment.
Because OSTree only preserves /var across upgrades (each
deployment's chroot directory will be garbage collected
eventually), you will need to choose how to handle other
toplevel writable directories specified by the Filesystem Hierarchy
Standard. Your operating system may of course choose
not to support some of these such as /usr/local, but following is the
recommended set:
/home to /var/home
/opt to /var/opt
/srv to /var/srv
/root to /var/roothome
/usr/local to /var/local
/mnt to /var/mnt
/tmp to /sysroot/tmp
Furthermore, since /var
is empty by default, your operating system will need to
dynamically create the targets of these at
boot. A good way to do this is using
systemd-tmpfiles, if your OS uses systemd.
For example:
d /var/log/journal 0755 root root -
L /var/home - - - - ../sysroot/home
d /var/opt 0755 root root -
d /var/srv 0755 root root -
d /var/roothome 0700 root root -
d /var/usrlocal 0755 root root -
d /var/usrlocal/bin 0755 root root -
d /var/usrlocal/etc 0755 root root -
d /var/usrlocal/games 0755 root root -
d /var/usrlocal/include 0755 root root -
d /var/usrlocal/lib 0755 root root -
d /var/usrlocal/man 0755 root root -
d /var/usrlocal/sbin 0755 root root -
d /var/usrlocal/share 0755 root root -
d /var/usrlocal/src 0755 root root -
d /var/mnt 0755 root root -
d /run/media 0755 root root -
Particularly note here the double indirection of /home. By default, each
deployment will share the global toplevel /home directory on the physical
root filesystem. It is then up to higher levels of management
tools to keep /etc/passwd or equivalent
synchronized between operating systems.
Each deployment can easily be reconfigured to have its own home
directory set simply by making /var/home a real directory.
OSTree comes with optional dracut+systemd integration code that
parses the ostree= kernel command line
argument in the initramfs, and then sets up the read-only bind
mount on /usr, a bind
mount on the deployment's /sysroot to the physical /, and then finally uses
mount(MS_MOVE) to make the deployment root appear to be the
root filesystem before telling systemd to switch root.
If you are not using dracut or systemd, using OSTree should still be possible, but you will have to write the integration code. Patches to support other initramfs technologies and init systems, if sufficiently clean, will likely be accepted upstream.
A further specific note regarding sysvinit:
OSTree used to support recording device files such the
/dev/initctl FIFO, but no longer does.
It's recommended to just patch your initramfs to create this at
boot.
In order to ship an OS that contains both system users and users
dynamically created on client machines, you will need to choose
a solution for /etc/passwd. The core
problem is that if you add a user to the system for a daemon,
the OSTree upgrade process for /etc will simply notice that
because /etc/passwd differs from the
previous default, it will keep the modified config file, and
your new OS user will not be visible.
The solution chosen for the gnome-ostree
operating system is to create /lib/passwd,
and to include a NSS module nss-altfiles
which instructs glibc to read from it. Then, the build system places
all system users there, freeing up /etc/passwd
to be purely a database of local users.
The largest endeavor is likely to be redesigning your
distribution's package manager to be on top of OSTree,
particularly if you want to keep compatibility with the "old
way" of installing into the physical /. This section will use examples
from both dpkg and rpm as
the author has familiarity with both; but the abstract concepts
should apply to most traditional package managers.
There are many levels of possible integration; initially, we will describe the most naive implementation which is the simplest but also the least efficient. We will assume here that the admin is booted into an OSTree-enabled system, and wants to add a set of packages.
Many package managers store their state in /var; but since in the OSTree model
that directory is shared between independent versions, the
package database must first be found in the per-deployment
/usr directory. It
becomes read-only; remember, all upgrades involve constructing a
new filesystem tree, so your package manager will also need to
create a copy of its database. Most likely, if you want to
continue supporting non-OSTree deployments, simply have your
package manager fall back to the legacy /var location if the one in
/usr is not found.
To install a set of new packages (without removing any existing ones), enumerate the set of packages in the currently booted deployment, and perform dependency resolution to compute the complete set of new packages. Download and unpack these new packages to a temporary directory.
Now, because we are merely installing new packages and not
removing anything, we can make the major optimization of reusing
our existing filesystem tree, and merely
layering the composed filesystem tree of
these new packages on top. A command lke this: ostree
commit -b osname/releasename/description
--tree=ref=osname/releasenamename/description
--tree=dir=/var/tmp/newpackages.13A8D0/ will create a
new commit in the
osname/releasename/description
branch. The OSTree SHA256 checksum of all the files in
/var/tmp/newpackages.13A8D0/ will be computed, but we will not
re-checksum the present existing tree. In this layering model,
earlier directories will take precedence, but files in later
layers will silently override earlier layers.
Then to actually deploy this tree for the next boot:
ostree admin deploy
osname/releasenamename/description
Core repository-independent functionsCore repository-independent functions — Create, validate, and convert core data types |
#define OSTREE_MAX_METADATA_SIZE #define OSTREE_MAX_RECURSION enum OstreeObjectType; #define OSTREE_OBJECT_TYPE_IS_META (t) #define OSTREE_OBJECT_TYPE_LAST #define OSTREE_FILE_HEADER_GVARIANT_FORMAT #define OSTREE_DIRMETA_GVARIANT_FORMAT #define OSTREE_TREE_GVARIANT_FORMAT #define OSTREE_COMMIT_GVARIANT_FORMAT #define OSTREE_ZLIB_FILE_HEADER_GVARIANT_FORMAT const GVariantType * ostree_metadata_variant_type (OstreeObjectType objtype); gboolean ostree_validate_checksum_string (const char *sha256,GError **error); guchar * ostree_checksum_to_bytes (const char *checksum); GVariant * ostree_checksum_to_bytes_v (const char *checksum); char * ostree_checksum_from_bytes (const guchar *csum); char * ostree_checksum_from_bytes_v (GVariant *csum_v); void ostree_checksum_inplace_from_bytes (const guchar *csum,char *buf); void ostree_checksum_inplace_to_bytes (const char *checksum,guchar *buf); const guchar * ostree_checksum_bytes_peek (GVariant *bytes); int ostree_cmp_checksum_bytes (const guchar *a,const guchar *b); gboolean ostree_validate_rev (const char *rev,GError **error); gboolean ostree_parse_refspec (const char *refspec,char **out_remote,char **out_ref,GError **error); void ostree_checksum_update_meta (GChecksum *checksum,GFileInfo *file_info,GVariant *xattrs); const char * ostree_object_type_to_string (OstreeObjectType objtype); OstreeObjectType ostree_object_type_from_string (const char *str); guint ostree_hash_object_name (gconstpointer a); GVariant * ostree_object_name_serialize (const char *checksum,OstreeObjectType objtype); void ostree_object_name_deserialize (GVariant *variant,const char **out_checksum,OstreeObjectType *out_objtype); char * ostree_object_to_string (const char *checksum,OstreeObjectType objtype); void ostree_object_from_string (const char *str,gchar **out_checksum,OstreeObjectType *out_objtype); char * ostree_get_relative_object_path (const char *checksum,OstreeObjectType type,gboolean compressed); gboolean ostree_get_xattrs_for_file (GFile *f,GVariant **out_xattrs,GCancellable *cancellable,GError **error); gboolean ostree_set_xattrs (GFile *f,GVariant *xattrs,GCancellable *cancellable,GError **error); gboolean ostree_map_metadata_file (GFile *file,OstreeObjectType expected_type,GVariant **out_variant,GError **error); gboolean ostree_write_variant_with_size (GOutputStream *output,GVariant *variant,guint64 alignment_offset,gsize *out_bytes_written,GChecksum *checksum,GCancellable *cancellable,GError **error); GVariant * ostree_file_header_new (GFileInfo *file_info,GVariant *xattrs); GVariant * ostree_zlib_file_header_new (GFileInfo *file_info,GVariant *xattrs); gboolean ostree_file_header_parse (GVariant *metadata,GFileInfo **out_file_info,GVariant **out_xattrs,GError **error); gboolean ostree_zlib_file_header_parse (GVariant *metadata,GFileInfo **out_file_info,GVariant **out_xattrs,GError **error); gboolean ostree_content_stream_parse (gboolean compressed,GInputStream *input,guint64 input_length,gboolean trusted,GInputStream **out_input,GFileInfo **out_file_info,GVariant **out_xattrs,GCancellable *cancellable,GError **error); gboolean ostree_content_file_parse (gboolean compressed,GFile *content_path,gboolean trusted,GInputStream **out_input,GFileInfo **out_file_info,GVariant **out_xattrs,GCancellable *cancellable,GError **error); gboolean ostree_write_file_header_update_checksum (GOutputStream *out,GVariant *variant,GChecksum *checksum,GCancellable *cancellable,GError **error); gboolean ostree_raw_file_to_content_stream (GInputStream *input,GFileInfo *file_info,GVariant *xattrs,GInputStream **out_input,guint64 *out_length,GCancellable *cancellable,GError **error); gboolean ostree_checksum_file_from_input (GFileInfo *file_info,GVariant *xattrs,GInputStream *in,OstreeObjectType objtype,guchar **out_csum,GCancellable *cancellable,GError **error); gboolean ostree_checksum_file (GFile *f,OstreeObjectType objtype,guchar **out_csum,GCancellable *cancellable,GError **error); void ostree_checksum_file_async (GFile *f,OstreeObjectType objtype,int io_priority,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data); gboolean ostree_checksum_file_async_finish (GFile *f,GAsyncResult *result,guchar **out_csum,GError **error); GVariant * ostree_create_directory_metadata (GFileInfo *dir_info,GVariant *xattrs); gboolean ostree_create_file_from_input (GFile *dest_file,GFileInfo *finfo,GVariant *xattrs,GInputStream *input,GCancellable *cancellable,GError **error); gboolean ostree_create_temp_file_from_input (GFile *dir,const char *prefix,const char *suffix,GFileInfo *finfo,GVariant *xattrs,GInputStream *input,GFile **out_file,GCancellable *cancellable,GError **error); gboolean ostree_create_temp_dir (GFile *dir,const char *prefix,const char *suffix,GFile **out_file,GCancellable *cancellable,GError **error); gboolean ostree_validate_structureof_objtype (guchar objtype,GError **error); gboolean ostree_validate_structureof_csum_v (GVariant *checksum,GError **error); gboolean ostree_validate_structureof_checksum_string (const char *checksum,GError **error); gboolean ostree_validate_structureof_file_mode (guint32 mode,GError **error); gboolean ostree_validate_structureof_commit (GVariant *commit,GError **error); gboolean ostree_validate_structureof_dirtree (GVariant *dirtree,GError **error); gboolean ostree_validate_structureof_dirmeta (GVariant *dirmeta,GError **error); gchar * ostree_commit_get_parent (GVariant *commit_variant);
These functions implement repository-independent algorithms for operating on the core OSTree data formats, such as converting GFileInfo into a GVariant.
There are 4 types of objects; file, dirmeta, tree, and commit. The last 3 are metadata, and the file object is the only content object type.
All metadata objects are stored as GVariant (big endian). The rationale for this is the same as that of the ext{2,3,4} family of filesystems; most developers will be using LE, and so it's better to continually test the BE->LE swap.
The file object is a custom format in order to support streaming.
#define OSTREE_MAX_METADATA_SIZE (1 << 26)
Maximum permitted size in bytes of metadata objects.
typedef enum {
OSTREE_OBJECT_TYPE_FILE = 1, /* .file */
OSTREE_OBJECT_TYPE_DIR_TREE = 2, /* .dirtree */
OSTREE_OBJECT_TYPE_DIR_META = 3, /* .dirmeta */
OSTREE_OBJECT_TYPE_COMMIT = 4 /* .commit */
} OstreeObjectType;
Enumeration for core object types; OSTREE_OBJECT_TYPE_FILE is for
content, the other types are metadata.
#define OSTREE_OBJECT_TYPE_IS_META(t) (t >= 2 && t <= 4)
|
An OstreeObjectType |
Returns : |
TRUE if object type is metadata |
#define OSTREE_OBJECT_TYPE_LAST OSTREE_OBJECT_TYPE_COMMIT
Last valid object type; use this to validate ranges.
#define OSTREE_FILE_HEADER_GVARIANT_FORMAT G_VARIANT_TYPE ("(uuuusa(ayay))")
File objects are stored as a stream, with one GVariant header, followed by content.
The file header is of the following form:
<BE guint32 containing variant length> u - uid u - gid u - mode u - rdev s - symlink target a(ayay) - xattrs
Then the rest of the stream is data.
#define OSTREE_DIRMETA_GVARIANT_FORMAT G_VARIANT_TYPE ("(uuua(ayay))")
u - uid u - gid u - mode a(ayay) - xattrs
#define OSTREE_TREE_GVARIANT_FORMAT G_VARIANT_TYPE ("(a(say)a(sayay))")
a(say) - array of (filename, checksum) for files a(sayay) - array of (dirname, tree_checksum, meta_checksum) for directories
#define OSTREE_COMMIT_GVARIANT_FORMAT G_VARIANT_TYPE ("(a{sv}aya(say)sstayay)")
a{sv} - Metadata ay - parent checksum (empty string for initial) a(say) - Related objects s - subject s - body t - Timestamp in seconds since the epoch (UTC) ay - Root tree contents ay - Root tree metadata
#define OSTREE_ZLIB_FILE_HEADER_GVARIANT_FORMAT G_VARIANT_TYPE ("(tuuuusa(ayay))")
This is a variation on OSTREE_FILE_HEADER_GVARIANT_FORMAT, used for
storing zlib-compressed content objects.
<BE guint32 containing variant length> t - size u - uid u - gid u - mode u - rdev s - symlink target a(ayay) - xattrs --- zlib-compressed data
const GVariantType * ostree_metadata_variant_type (OstreeObjectType objtype);
gboolean ostree_validate_checksum_string (const char *sha256,GError **error);
Use this function to see if input strings are checksums.
|
SHA256 hex string |
|
Error |
Returns : |
TRUE if sha256 is a valid checksum string, FALSE otherwise |
guchar * ostree_checksum_to_bytes (const char *checksum);
|
An ASCII checksum |
Returns : |
Binary checksum from checksum of length 32; free with g_free(). [transfer full][array fixed-size=32]
|
GVariant * ostree_checksum_to_bytes_v (const char *checksum);
|
An ASCII checksum |
Returns : |
New GVariant of type ay with length 32. [transfer full] |
char * ostree_checksum_from_bytes (const guchar *csum);
|
An binary checksum of length 32. [array fixed-size=32] |
Returns : |
String form of csum. [transfer full]
|
char * ostree_checksum_from_bytes_v (GVariant *csum_v);
|
GVariant of type ay |
Returns : |
String form of csum_bytes. [transfer full]
|
void ostree_checksum_inplace_from_bytes (const guchar *csum,char *buf);
Overwrite the contents of buf with stringified version of csum.
|
An binary checksum of length 32. [array fixed-size=32] |
|
Output location, must be at least 65 bytes in length |
void ostree_checksum_inplace_to_bytes (const char *checksum,guchar *buf);
Convert checksum from a string to binary in-place, without
allocating memory. Use this function in hot code paths.
|
a SHA256 string |
|
Output buffer with at least 32 bytes of space |
const guchar * ostree_checksum_bytes_peek (GVariant *bytes);
|
GVariant of type ay |
Returns : |
Binary checksum data in bytes; do not free. [transfer none]
|
int ostree_cmp_checksum_bytes (const guchar *a,const guchar *b);
Compare two binary checksums, using memcmp().
|
A binary checksum |
|
A binary checksum |
gboolean ostree_validate_rev (const char *rev,GError **error);
|
A revision string |
|
Error |
Returns : |
TRUE if rev is a valid ref string |
gboolean ostree_parse_refspec (const char *refspec,char **out_remote,char **out_ref,GError **error);
Split a refspec like "gnome-ostree:gnome-ostree/buildmaster" into
two parts; out_remote will be set to "gnome-ostree", and out_ref
will be "gnome-ostree/buildmaster".
If refspec refers to a local ref, out_remote will be NULL.
|
A "refspec" string |
|
The remote name, or NULL if the refspec refs to a local ref. [out][allow-none]
|
|
Name of ref. [out][allow-none] |
|
Error |
void ostree_checksum_update_meta (GChecksum *checksum,GFileInfo *file_info,GVariant *xattrs);
const char * ostree_object_type_to_string (OstreeObjectType objtype);
Serialize objtype to a string; this is used for file extensions.
|
an OstreeObjectType |
OstreeObjectType ostree_object_type_from_string (const char *str);
The reverse of ostree_object_type_to_string().
|
A stringified version of OstreeObjectType |
guint ostree_hash_object_name (gconstpointer a);
Use this function with GHashTable and ostree_object_name_serialize().
|
A GVariant containing a serialized object |
GVariant * ostree_object_name_serialize (const char *checksum,OstreeObjectType objtype);
|
An ASCII checksum |
|
An object type |
Returns : |
A new floating GVariant containing checksum string and objtype. [transfer floating] |
void ostree_object_name_deserialize (GVariant *variant,const char **out_checksum,OstreeObjectType *out_objtype);
Reverse ostree_object_name_serialize(). Note that out_checksum is
only valid for the lifetime of variant, and must not be freed.
|
A GVariant of type (su) |
|
Pointer into string memory of variant with checksum. [out][transfer none]
|
|
Return object type. [out] |
char * ostree_object_to_string (const char *checksum,OstreeObjectType objtype);
|
An ASCII checksum |
|
Object type |
Returns : |
A string containing both checksum and a stringifed version of objtype
|
void ostree_object_from_string (const char *str,gchar **out_checksum,OstreeObjectType *out_objtype);
Reverse ostree_object_to_string().
|
An ASCII checksum |
|
Parsed checksum. [out][transfer full] |
|
Parsed object type. [out] |
char * ostree_get_relative_object_path (const char *checksum,OstreeObjectType type,gboolean compressed);
|
ASCII checksum string |
|
Object type |
|
Whether or not the repository object is compressed |
Returns : |
Relative path for a loose object. [transfer full] |
gboolean ostree_get_xattrs_for_file (GFile *f,GVariant **out_xattrs,GCancellable *cancellable,GError **error);
Read all extended attributes of f in a canonical sorted order, and
set out_xattrs with the result.
If the filesystem does not support extended attributes, out_xattrs
will have 0 elements, and this function will return successfully.
|
a GFile |
|
A new GVariant containing the extended attributes. [out] |
|
Cancellable |
|
Error |
gboolean ostree_set_xattrs (GFile *f,GVariant *xattrs,GCancellable *cancellable,GError **error);
For each attribute in xattrs, replace the value (if any) of f for
that attribute. This function does not clear other existing
attributes.
|
a file |
|
Extended attribute list |
|
Cancellable |
|
Error |
gboolean ostree_map_metadata_file (GFile *file,OstreeObjectType expected_type,GVariant **out_variant,GError **error);
gboolean ostree_write_variant_with_size (GOutputStream *output,GVariant *variant,guint64 alignment_offset,gsize *out_bytes_written,GChecksum *checksum,GCancellable *cancellable,GError **error);
Use this function for serializing a chain of 1 or more variants
into a stream; the alignment_offset parameter is used to ensure
that each variant begins on an 8-byte alignment so it can be safely
accessed.
|
Stream |
|
A variant |
|
Used to determine whether or not we should write padding bytes |
|
Number of bytes written. [out] |
|
If provided, update with written data. [allow-none] |
|
Cancellable |
|
Error |
GVariant * ostree_file_header_new (GFileInfo *file_info,GVariant *xattrs);
GVariant * ostree_zlib_file_header_new (GFileInfo *file_info,GVariant *xattrs);
|
a GFileInfo |
|
Optional extended attribute array. [allow-none] |
Returns : |
A new GVariant containing file header for an archive-z2 repository. [transfer full] |
gboolean ostree_file_header_parse (GVariant *metadata,GFileInfo **out_file_info,GVariant **out_xattrs,GError **error);
Load file header information into standard Gio GFileInfo object,
along with extended attributes tored in out_xattrs.
|
A metadata variant of type OSTREE_FILE_HEADER_GVARIANT_FORMAT
|
|
Parsed file information. [out] |
|
Parsed extended attribute set. [out] |
|
Error |
gboolean ostree_zlib_file_header_parse (GVariant *metadata,GFileInfo **out_file_info,GVariant **out_xattrs,GError **error);
Like ostree_file_header_parse(), but operates on zlib-compressed
content.
|
A metadata variant of type OSTREE_FILE_HEADER_GVARIANT_FORMAT
|
|
Parsed file information. [out] |
|
Parsed extended attribute set. [out] |
|
Error |
gboolean ostree_content_stream_parse (gboolean compressed,GInputStream *input,guint64 input_length,gboolean trusted,GInputStream **out_input,GFileInfo **out_file_info,GVariant **out_xattrs,GCancellable *cancellable,GError **error);
The reverse of ostree_raw_file_to_content_stream(); this function
converts an object content stream back into components.
|
Whether or not the stream is zlib-compressed |
|
Object content stream |
|
Length of stream |
|
If TRUE, assume the content has been validated |
|
The raw file content stream. [out] |
|
Normal metadata. [out] |
|
Extended attributes. [out] |
|
Cancellable |
|
Error |
gboolean ostree_content_file_parse (gboolean compressed,GFile *content_path,gboolean trusted,GInputStream **out_input,GFileInfo **out_file_info,GVariant **out_xattrs,GCancellable *cancellable,GError **error);
A thin wrapper for ostree_content_stream_parse(); this function
converts an object content stream back into components.
|
Whether or not the stream is zlib-compressed |
|
Path to file containing content |
|
If TRUE, assume the content has been validated |
|
The raw file content stream. [out] |
|
Normal metadata. [out] |
|
Extended attributes. [out] |
|
Cancellable |
|
Error |
gboolean ostree_write_file_header_update_checksum (GOutputStream *out,GVariant *variant,GChecksum *checksum,GCancellable *cancellable,GError **error);
Write a file header variant to the provided out stream, optionally
updating checksum.
|
Stream |
|
A variant, should be a file header |
|
If provided, update with written data. [allow-none] |
|
Cancellable |
|
Error |
gboolean ostree_raw_file_to_content_stream (GInputStream *input,GFileInfo *file_info,GVariant *xattrs,GInputStream **out_input,guint64 *out_length,GCancellable *cancellable,GError **error);
Convert from a "bare" file representation into an OSTREE_OBJECT_TYPE_FILE stream. This is a fundamental operation for writing data to an OstreeRepo.
|
File raw content stream |
|
A file info |
|
Optional extended attributes. [allow-none] |
|
Serialized object stream. [out] |
|
Length of stream. [out] |
|
Cancellable |
|
Error |
gboolean ostree_checksum_file_from_input (GFileInfo *file_info,GVariant *xattrs,GInputStream *in,OstreeObjectType objtype,guchar **out_csum,GCancellable *cancellable,GError **error);
Compute the OSTree checksum for a given input.
|
File information |
|
Optional extended attributes. [allow-none] |
|
File content, should be NULL for symbolic links. [allow-none]
|
|
Object type |
|
Return location for binary checksum. [out][array fixed-size=32] |
|
Cancellable |
|
Error |
gboolean ostree_checksum_file (GFile *f,OstreeObjectType objtype,guchar **out_csum,GCancellable *cancellable,GError **error);
Compute the OSTree checksum for a given file.
void ostree_checksum_file_async (GFile *f,OstreeObjectType objtype,int io_priority,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously compute the OSTree checksum for a given file;
complete with ostree_checksum_file_async_finish().
|
File path |
|
Object type |
|
Priority for operation, see G_IO_PRIORITY_DEFAULT
|
|
Cancellable |
|
Invoked when operation is complete |
|
Data for callback
|
gboolean ostree_checksum_file_async_finish (GFile *f,GAsyncResult *result,guchar **out_csum,GError **error);
Finish computing the OSTree checksum for a given file; see
ostree_checksum_file_async().
GVariant * ostree_create_directory_metadata (GFileInfo *dir_info,GVariant *xattrs);
|
a GFileInfo containing directory information |
|
Optional extended attributes. [allow-none] |
Returns : |
A new GVariant containing OSTREE_OBJECT_TYPE_DIR_META. [transfer full]
|
gboolean ostree_create_file_from_input (GFile *dest_file,GFileInfo *finfo,GVariant *xattrs,GInputStream *input,GCancellable *cancellable,GError **error);
Create a directory, regular file, or symbolic link, based on
finfo. Append extended attributes from xattrs if provided. For
G_FILE_TYPE_REGULAR, set content based on input.
|
Destination; must not exist |
|
File information |
|
Optional extended attributes. [allow-none] |
|
Optional file content, must be NULL for symbolic links. [allow-none]
|
|
Cancellable |
|
Error |
gboolean ostree_create_temp_file_from_input (GFile *dir,const char *prefix,const char *suffix,GFileInfo *finfo,GVariant *xattrs,GInputStream *input,GFile **out_file,GCancellable *cancellable,GError **error);
Like ostree_create_file_from_input(), but securely allocates a
randomly-named target in dir. This is a unified version of
mkstemp()/mkdtemp() that also supports symbolic links.
|
Target directory |
|
Optional prefix |
|
Optional suffix |
|
File information |
|
Optional extended attributes. [allow-none] |
|
Optional file content, must be NULL for symbolic links. [allow-none]
|
|
Path for newly created directory, file, or symbolic link. [out] |
|
Cancellable |
|
Error |
gboolean ostree_create_temp_dir (GFile *dir,const char *prefix,const char *suffix,GFile **out_file,GCancellable *cancellable,GError **error);
Securely create a randomly-named temporary subdirectory of dir.
|
Use this as temporary base |
|
Optional prefix. [allow-none] |
|
Optional suffix. [allow-none] |
|
Path for newly created directory, file, or symbolic link. [out] |
|
Cancellable |
|
Error |
gboolean ostree_validate_structureof_objtype (guchar objtype,GError **error);
|
Error |
Returns : |
TRUE if objtype represents a valid object type |
gboolean ostree_validate_structureof_csum_v (GVariant *checksum,GError **error);
|
a GVariant of type "ay" |
|
Error |
Returns : |
TRUE if checksum is a valid binary SHA256 checksum |
gboolean ostree_validate_structureof_checksum_string (const char *checksum,GError **error);
|
an ASCII string |
|
Error |
Returns : |
TRUE if checksum is a valid ASCII SHA256 checksum |
gboolean ostree_validate_structureof_file_mode (guint32 mode,GError **error);
|
A Unix filesystem mode |
|
Error |
Returns : |
TRUE if mode represents a valid file type and permissions |
gboolean ostree_validate_structureof_commit (GVariant *commit,GError **error);
Use this to validate the basic structure of commit, independent of
any other objects it references.
|
A commit object, OSTREE_OBJECT_TYPE_COMMIT
|
|
Error |
Returns : |
TRUE if commit is structurally valid |
gboolean ostree_validate_structureof_dirtree (GVariant *dirtree,GError **error);
Use this to validate the basic structure of dirtree, independent of
any other objects it references.
|
A dirtree object, OSTREE_OBJECT_TYPE_DIR_TREE
|
|
Error |
Returns : |
TRUE if dirtree is structurally valid |
gboolean ostree_validate_structureof_dirmeta (GVariant *dirmeta,GError **error);
Use this to validate the basic structure of dirmeta.
|
A dirmeta object, OSTREE_OBJECT_TYPE_DIR_META
|
|
Error |
Returns : |
TRUE if dirmeta is structurally valid |
gchar * ostree_commit_get_parent (GVariant *commit_variant);
|
Variant of type OSTREE_OBJECT_TYPE_COMMIT
|
Returns : |
Binary checksum with parent of commit_variant, or NULL if none |
Content-addressed object storeContent-addressed object store — A git-like storage system for operating system binaries |
enum OstreeRepoMode; OstreeRepo * ostree_repo_new (GFile *path); gboolean ostree_repo_check (OstreeRepo *self,GError **error); GFile * ostree_repo_get_path (OstreeRepo *self); OstreeRepoMode ostree_repo_get_mode (OstreeRepo *self); gboolean ostree_repo_mode_from_string (const char *mode,OstreeRepoMode *out_mode,GError **error); GKeyFile * ostree_repo_get_config (OstreeRepo *self); GKeyFile * ostree_repo_copy_config (OstreeRepo *self); OstreeRepo * ostree_repo_get_parent (OstreeRepo *self); gboolean ostree_repo_write_config (OstreeRepo *self,GKeyFile *new_config,GError **error); gboolean ostree_repo_prepare_transaction (OstreeRepo *self,gboolean enable_commit_hardlink_scan,gboolean *out_transaction_resume,GCancellable *cancellable,GError **error); gboolean ostree_repo_commit_transaction (OstreeRepo *self,GCancellable *cancellable,GError **error); gboolean ostree_repo_commit_transaction_with_stats (OstreeRepo *self,guint *out_metadata_objects_total,guint *out_metadata_objects_written,guint *out_content_objects_total,guint *out_content_objects_written,guint64 *out_content_bytes_written,GCancellable *cancellable,GError **error); gboolean ostree_repo_abort_transaction (OstreeRepo *self,GCancellable *cancellable,GError **error); gboolean ostree_repo_has_object (OstreeRepo *self,OstreeObjectType objtype,const char *checksum,gboolean *out_have_object,GCancellable *cancellable,GError **error); gboolean ostree_repo_stage_metadata (OstreeRepo *self,OstreeObjectType objtype,const char *expected_checksum,GVariant *object,guchar **out_csum,GCancellable *cancellable,GError **error); void ostree_repo_stage_metadata_async (OstreeRepo *self,OstreeObjectType objtype,const char *expected_checksum,GVariant *object,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data); gboolean ostree_repo_stage_metadata_finish (OstreeRepo *self,GAsyncResult *result,guchar **out_csum,GError **error); gboolean ostree_repo_stage_metadata_trusted (OstreeRepo *self,OstreeObjectType objtype,const char *checksum,GVariant *variant,GCancellable *cancellable,GError **error); gboolean ostree_repo_stage_content (OstreeRepo *self,const char *expected_checksum,GInputStream *object_input,guint64 length,guchar **out_csum,GCancellable *cancellable,GError **error); gboolean ostree_repo_stage_content_trusted (OstreeRepo *self,const char *checksum,GInputStream *object_input,guint64 length,GCancellable *cancellable,GError **error); void ostree_repo_stage_content_async (OstreeRepo *self,const char *expected_checksum,GInputStream *object,guint64 length,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data); gboolean ostree_repo_stage_content_finish (OstreeRepo *self,GAsyncResult *result,guchar **out_csum,GError **error); gboolean ostree_repo_resolve_rev (OstreeRepo *self,const char *refspec,gboolean allow_noent,char **out_rev,GError **error); gboolean ostree_repo_write_ref (OstreeRepo *self,const char *remote,const char *name,const char *rev,GError **error); gboolean ostree_repo_write_refspec (OstreeRepo *self,const char *refspec,const char *rev,GError **error); gboolean ostree_repo_list_refs (OstreeRepo *self,const char *refspec_prefix,GHashTable **out_all_refs,GCancellable *cancellable,GError **error); gboolean ostree_repo_load_variant_c (OstreeRepo *self,OstreeObjectType objtype,const guchar *csum,GVariant **out_variant,GError **error); gboolean ostree_repo_load_variant (OstreeRepo *self,OstreeObjectType objtype,const char *sha256,GVariant **out_variant,GError **error); gboolean ostree_repo_load_variant_if_exists (OstreeRepo *self,OstreeObjectType objtype,const char *sha256,GVariant **out_variant,GError **error); gboolean ostree_repo_load_file (OstreeRepo *self,const char *checksum,GInputStream **out_input,GFileInfo **out_file_info,GVariant **out_xattrs,GCancellable *cancellable,GError **error); gboolean ostree_repo_load_object_stream (OstreeRepo *self,OstreeObjectType objtype,const char *checksum,GInputStream **out_input,guint64 *out_size,GCancellable *cancellable,GError **error); gboolean ostree_repo_query_object_storage_size (OstreeRepo *self,OstreeObjectType objtype,const char *sha256,guint64 *out_size,GCancellable *cancellable,GError **error); gboolean ostree_repo_delete_object (OstreeRepo *self,OstreeObjectType objtype,const char *sha256,GCancellable *cancellable,GError **error); enum OstreeRepoCommitFilterResult; OstreeRepoCommitFilterResult (*OstreeRepoCommitFilter) (OstreeRepo *repo,const char *path,GFileInfo *file_info,gpointer user_data); typedef OstreeRepoCommitModifier; OstreeRepoCommitModifier * ostree_repo_commit_modifier_new (OstreeRepoCommitModifierFlags flags,OstreeRepoCommitFilter commit_filter,gpointer user_data); OstreeRepoCommitModifier * ostree_repo_commit_modifier_ref (OstreeRepoCommitModifier *modifier); void ostree_repo_commit_modifier_unref (OstreeRepoCommitModifier *modifier); gboolean ostree_repo_stage_directory_to_mtree (OstreeRepo *self,GFile *dir,OstreeMutableTree *mtree,OstreeRepoCommitModifier *modifier,GCancellable *cancellable,GError **error); gboolean ostree_repo_stage_archive_to_mtree (OstreeRepo *self,GFile *archive,OstreeMutableTree *tree,OstreeRepoCommitModifier *modifier,gboolean autocreate_parents,GCancellable *cancellable,GError **error); gboolean ostree_repo_stage_mtree (OstreeRepo *self,OstreeMutableTree *mtree,char **out_contents_checksum,GCancellable *cancellable,GError **error); gboolean ostree_repo_stage_commit (OstreeRepo *self,const char *branch,const char *parent,const char *subject,const char *body,const char *root_contents_checksum,const char *root_metadata_checksum,char **out_commit,GCancellable *cancellable,GError **error); enum OstreeRepoCheckoutMode; enum OstreeRepoCheckoutOverwriteMode; gboolean ostree_repo_checkout_tree (OstreeRepo *self,OstreeRepoCheckoutMode mode,OstreeRepoCheckoutOverwriteMode overwrite_mode,GFile *destination,OstreeRepoFile *source,GFileInfo *source_info,GCancellable *cancellable,GError **error); gboolean ostree_repo_checkout_gc (OstreeRepo *self,GCancellable *cancellable,GError **error); gboolean ostree_repo_read_commit (OstreeRepo *self,const char *rev,GFile **out_root,GCancellable *cancellable,GError **error); enum OstreeRepoListObjectsFlags; #define OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE gboolean ostree_repo_list_objects (OstreeRepo *self,OstreeRepoListObjectsFlags flags,GHashTable **out_objects,GCancellable *cancellable,GError **error); GHashTable * ostree_repo_traverse_new_reachable (void); gboolean ostree_repo_traverse_dirtree (OstreeRepo *repo,const char *commit_checksum,GHashTable *inout_reachable,GCancellable *cancellable,GError **error); gboolean ostree_repo_traverse_commit (OstreeRepo *repo,const char *commit_checksum,int maxdepth,GHashTable *inout_reachable,GCancellable *cancellable,GError **error); enum OstreeRepoPruneFlags; gboolean ostree_repo_prune (OstreeRepo *self,OstreeRepoPruneFlags flags,gint depth,gint *out_objects_total,gint *out_objects_pruned,guint64 *out_pruned_object_size_total,GCancellable *cancellable,GError **error); enum OstreeRepoPullFlags; gboolean ostree_repo_pull (OstreeRepo *self,const char *remote_name,char **refs_to_fetch,OstreeRepoPullFlags flags,GCancellable *cancellable,GError **error);
The OstreeRepo is like git, a content-addressed object store. Unlike git, it records uid, gid, and extended attributes.
There are two possible "modes" for an OstreeRepo;
OSTREE_REPO_MODE_BARE is very simple - content files are
represented exactly as they are, and checkouts are just hardlinks.
A OSTREE_REPO_MODE_ARCHIVE_Z2 repository in contrast stores
content files zlib-compressed. It is suitable for non-root-owned
repositories that can be served via a static HTTP server.
To store content in the repo, first start a transaction with
ostree_repo_prepare_transaction(). Then create a
OstreeMutableTree, and apply functions such as
ostree_repo_stage_directory_to_mtree() to traverse a physical
filesystem and stage content, possibly multiple times.
Once the OstreeMutableTree is complete, stage all of its metadata
with ostree_repo_stage_mtree(), and finally create a commit with
ostree_repo_stage_commit().
typedef enum {
OSTREE_REPO_MODE_BARE,
OSTREE_REPO_MODE_ARCHIVE_Z2
} OstreeRepoMode;
See the documentation of OstreeRepo for more information about the possible modes.
OstreeRepo * ostree_repo_new (GFile *path);
|
Path to a repository |
Returns : |
An accessor object for an OSTree repository located at path. [transfer full]
|
GFile * ostree_repo_get_path (OstreeRepo *self);
Returns : |
Path to repo. [transfer none] |
gboolean ostree_repo_mode_from_string (const char *mode,OstreeRepoMode *out_mode,GError **error);
GKeyFile * ostree_repo_get_config (OstreeRepo *self);
Returns : |
The repository configuration; do not modify. [transfer none] |
GKeyFile * ostree_repo_copy_config (OstreeRepo *self);
Returns : |
A newly-allocated copy of the repository config. [transfer full] |
OstreeRepo * ostree_repo_get_parent (OstreeRepo *self);
Before this function can be used, ostree_repo_init() must have been
called.
|
Repo |
Returns : |
Parent repository, or NULL if none. [transfer none]
|
gboolean ostree_repo_write_config (OstreeRepo *self,GKeyFile *new_config,GError **error);
Save new_config in place of this repository's config file. Note
that new_config should not be modified after - this function
simply adds a reference.
|
Repo |
|
Overwrite the config file with this data. Do not change later! |
|
a GError |
gboolean ostree_repo_prepare_transaction (OstreeRepo *self,gboolean enable_commit_hardlink_scan,gboolean *out_transaction_resume,GCancellable *cancellable,GError **error);
gboolean ostree_repo_commit_transaction (OstreeRepo *self,GCancellable *cancellable,GError **error);
gboolean ostree_repo_commit_transaction_with_stats (OstreeRepo *self,guint *out_metadata_objects_total,guint *out_metadata_objects_written,guint *out_content_objects_total,guint *out_content_objects_written,guint64 *out_content_bytes_written,GCancellable *cancellable,GError **error);
gboolean ostree_repo_abort_transaction (OstreeRepo *self,GCancellable *cancellable,GError **error);
gboolean ostree_repo_has_object (OstreeRepo *self,OstreeObjectType objtype,const char *checksum,gboolean *out_have_object,GCancellable *cancellable,GError **error);
Set out_have_object to TRUE if self contains the given object;
FALSE otherwise.
|
Repo |
|
Object type |
|
ASCII SHA256 checksum |
|
TRUE if repository contains object. [out]
|
|
Cancellable |
|
Error |
Returns : |
FALSE if an unexpected error occurred, TRUE otherwise |
gboolean ostree_repo_stage_metadata (OstreeRepo *self,OstreeObjectType objtype,const char *expected_checksum,GVariant *object,guchar **out_csum,GCancellable *cancellable,GError **error);
Store the metadata object variant. Return the checksum
as out_csum.
If expected_checksum is not NULL, verify it against the
computed checksum.
|
Repo |
|
Object type |
|
If provided, validate content against this checksum. [allow-none] |
|
Metadata |
|
Binary checksum. [out][array fixed-size=32][allow-none] |
|
Cancellable |
|
Error |
void ostree_repo_stage_metadata_async (OstreeRepo *self,OstreeObjectType objtype,const char *expected_checksum,GVariant *object,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously store the metadata object variant. If provided,
the checksum expected_checksum will be verified.
|
Repo |
|
Object type |
|
If provided, validate content against this checksum. [allow-none] |
|
Metadata |
|
Cancellable |
|
Invoked when metadata is staged |
|
Data for callback
|
gboolean ostree_repo_stage_metadata_finish (OstreeRepo *self,GAsyncResult *result,guchar **out_csum,GError **error);
gboolean ostree_repo_stage_metadata_trusted (OstreeRepo *self,OstreeObjectType objtype,const char *checksum,GVariant *variant,GCancellable *cancellable,GError **error);
Store the metadata object variant; the provided checksum is
trusted.
|
Repo |
|
Object type |
|
Store object with this ASCII SHA256 checksum |
|
Metadata object |
|
Cancellable |
|
Error |
gboolean ostree_repo_stage_content (OstreeRepo *self,const char *expected_checksum,GInputStream *object_input,guint64 length,guchar **out_csum,GCancellable *cancellable,GError **error);
Store the content object streamed as object_input,
with total length length. The actual checksum will
be returned as out_csum.
|
Repo |
|
If provided, validate content against this checksum. [allow-none] |
|
Content object stream |
|
Length of object_input
|
|
Binary checksum. [out][array fixed-size=32][allow-none] |
|
Cancellable |
|
Error |
gboolean ostree_repo_stage_content_trusted (OstreeRepo *self,const char *checksum,GInputStream *object_input,guint64 length,GCancellable *cancellable,GError **error);
Store the content object streamed as object_input, with total
length length. The given checksum will be treated as trusted.
This function should be used when importing file objects from local disk, for example.
|
Repo |
|
Store content using this ASCII SHA256 checksum |
|
Content stream |
|
Length of object_input
|
|
Cancellable |
|
Data for callback
|
void ostree_repo_stage_content_async (OstreeRepo *self,const char *expected_checksum,GInputStream *object,guint64 length,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Asynchronously store the content object object. If provided, the
checksum expected_checksum will be verified.
|
Repo |
|
If provided, validate content against this checksum. [allow-none] |
|
Input |
|
Length of object
|
|
Cancellable |
|
Invoked when content is staged |
|
User data for callback
|
gboolean ostree_repo_stage_content_finish (OstreeRepo *self,GAsyncResult *result,guchar **out_csum,GError **error);
Completes an invocation of ostree_repo_stage_content_async().
|
a OstreeRepo |
|
a GAsyncResult |
|
A binary SHA256 checksum of the content object. [out][transfer full] |
|
a GError |
gboolean ostree_repo_resolve_rev (OstreeRepo *self,const char *refspec,gboolean allow_noent,char **out_rev,GError **error);
Look up the given refspec, returning the checksum it references in
the parameter out_rev.
|
Repo |
|
A refspec |
|
Do not throw an error if refspec does not exist |
|
A checksum,or NULL if allow_noent is true and it does not exist. [out][transfer full]
|
|
Error |
gboolean ostree_repo_write_ref (OstreeRepo *self,const char *remote,const char *name,const char *rev,GError **error);
If rev is not NULL, then it as the target of ref named name; if
remote is provided, the ref will appear originate from that
remote.
Otherwise, if rev is NULL, then delete the ref name if it exists.
This function merely changes the ref target; it is possible to use it to target earlier commits.
|
Repo |
|
Optional remote name. [allow-none] |
|
Name of ref, e.g. foo/bar/baz |
|
(allow-none); ASCII SHA256 checksum; if NULL, then delete name
|
|
Error |
gboolean ostree_repo_write_refspec (OstreeRepo *self,const char *refspec,const char *rev,GError **error);
Like ostree_repo_write_ref(), but takes concatenated refspec
format as input instead of separate remote and name arguments.
|
Repo |
|
Optional remote with name of ref, e.g. remotename:foo/bar/baz |
|
(allow-none); ASCII SHA256 checksum; if NULL, then delete refspec
|
|
Error |
gboolean ostree_repo_list_refs (OstreeRepo *self,const char *refspec_prefix,GHashTable **out_all_refs,GCancellable *cancellable,GError **error);
If refspec_prefix is NULL, list all local and remote refspecs,
with their current values in out_all_refs. Otherwise, only list
refspecs which have refspec_prefix as a prefix.
|
Repo |
|
Only list refs which match this prefix. [allow-none] |
|
Mapping from ref to checksum. [out][element-type utf8 utf8] |
|
Cancellable |
|
Error |
gboolean ostree_repo_load_variant_c (OstreeRepo *self,OstreeObjectType objtype,const guchar *csum,GVariant **out_variant,GError **error);
Load the metadata object csum of type objtype, storing the
result in out_variant.
|
Repo |
|
Expected object type |
|
Binary checksum |
|
(transfer full): Metadata object. [out] |
|
Error |
gboolean ostree_repo_load_variant (OstreeRepo *self,OstreeObjectType objtype,const char *sha256,GVariant **out_variant,GError **error);
Load the metadata object sha256 of type objtype, storing the
result in out_variant.
|
Repo |
|
Expected object type |
|
Checksum string |
|
(transfer full): Metadata object. [out] |
|
Error |
gboolean ostree_repo_load_variant_if_exists (OstreeRepo *self,OstreeObjectType objtype,const char *sha256,GVariant **out_variant,GError **error);
Attempt to load the metadata object sha256 of type objtype if it
exists, storing the result in out_variant. If it doesn't exist,
NULL is returned.
|
Repo |
|
Object type |
|
ASCII checksum |
|
Metadata. [out][transfer full] |
|
Error |
gboolean ostree_repo_load_file (OstreeRepo *self,const char *checksum,GInputStream **out_input,GFileInfo **out_file_info,GVariant **out_xattrs,GCancellable *cancellable,GError **error);
Load content object, decomposing it into three parts: the actual content (for regular files), the metadata, and extended attributes.
|
Repo |
|
ASCII SHA256 checksum |
|
File content. [out][allow-none] |
|
File information. [out][allow-none] |
|
Extended attributes. [out][allow-none] |
|
Cancellable |
|
Error |
gboolean ostree_repo_load_object_stream (OstreeRepo *self,OstreeObjectType objtype,const char *checksum,GInputStream **out_input,guint64 *out_size,GCancellable *cancellable,GError **error);
Load object as a stream; useful when copying objects between repositories.
gboolean ostree_repo_query_object_storage_size (OstreeRepo *self,OstreeObjectType objtype,const char *sha256,guint64 *out_size,GCancellable *cancellable,GError **error);
Return the size in bytes of object with checksum sha256, after any
compression has been applied.
|
Repo |
|
Object type |
|
Checksum |
|
Size in bytes object occupies physically. [out] |
|
Cancellable |
|
Error |
gboolean ostree_repo_delete_object (OstreeRepo *self,OstreeObjectType objtype,const char *sha256,GCancellable *cancellable,GError **error);
Remove the object of type objtype with checksum sha256
from the repository. An error of type G_IO_ERROR_NOT_FOUND
is thrown if the object does not exist.
|
Repo |
|
Object type |
|
Checksum |
|
Cancellable |
|
Error |
typedef enum {
OSTREE_REPO_COMMIT_FILTER_ALLOW,
OSTREE_REPO_COMMIT_FILTER_SKIP
} OstreeRepoCommitFilterResult;
OstreeRepoCommitFilterResult (*OstreeRepoCommitFilter) (OstreeRepo *repo,const char *path,GFileInfo *file_info,gpointer user_data);
|
Repo |
|
Path to file |
|
File information |
|
User data |
Returns : |
OstreeRepoCommitFilterResult saying whether or not to commit this file |
typedef struct OstreeRepoCommitModifier OstreeRepoCommitModifier;
A structure allowing control over commits.
OstreeRepoCommitModifier * ostree_repo_commit_modifier_new (OstreeRepoCommitModifierFlags flags,OstreeRepoCommitFilter commit_filter,gpointer user_data);
|
Control options for filter |
|
Function that can inspect individual files. [allow-none] |
|
User data. [allow-none] |
Returns : |
A new commit modifier. [transfer full] |
OstreeRepoCommitModifier * ostree_repo_commit_modifier_ref
(OstreeRepoCommitModifier *modifier);
void ostree_repo_commit_modifier_unref (OstreeRepoCommitModifier *modifier);
gboolean ostree_repo_stage_directory_to_mtree (OstreeRepo *self,GFile *dir,OstreeMutableTree *mtree,OstreeRepoCommitModifier *modifier,GCancellable *cancellable,GError **error);
Store objects for dir and all children into the repository self,
overlaying the resulting filesystem hierarchy into mtree.
|
Repo |
|
Path to a directory |
|
Overlay directory contents into this tree |
|
Optional modifier. [allow-none] |
|
Cancellable |
|
Error |
gboolean ostree_repo_stage_archive_to_mtree (OstreeRepo *self,GFile *archive,OstreeMutableTree *tree,OstreeRepoCommitModifier *modifier,gboolean autocreate_parents,GCancellable *cancellable,GError **error);
gboolean ostree_repo_stage_mtree (OstreeRepo *self,OstreeMutableTree *mtree,char **out_contents_checksum,GCancellable *cancellable,GError **error);
Write all metadata objects for mtree to repo; the resulting
out_contents_checksum contains the checksum for the
OSTREE_OBJECT_TYPE_DIR_TREE object.
|
Repo |
|
Mutable tree |
|
Return location for ASCII checksum. [out] |
|
Cancellable |
|
Error |
gboolean ostree_repo_stage_commit (OstreeRepo *self,const char *branch,const char *parent,const char *subject,const char *body,const char *root_contents_checksum,const char *root_metadata_checksum,char **out_commit,GCancellable *cancellable,GError **error);
Write a commit metadata object, referencing root_contents_checksum
and root_metadata_checksum.
|
Repo |
|
Name of ref |
|
ASCII SHA256 checksum for parent, or NULL for none. [allow-none]
|
|
Subject |
|
Body |
|
ASCII SHA256 checksum for OSTREE_OBJECT_TYPE_DIR_TREE
|
|
ASCII SHA256 checksum for OSTREE_OBJECT_TYPE_DIR_META
|
|
Resulting ASCII SHA256 checksum for commit. [out] |
|
Cancellable |
|
Error |
typedef enum {
OSTREE_REPO_CHECKOUT_MODE_NONE = 0,
OSTREE_REPO_CHECKOUT_MODE_USER = 1
} OstreeRepoCheckoutMode;
typedef enum {
OSTREE_REPO_CHECKOUT_OVERWRITE_NONE = 0,
OSTREE_REPO_CHECKOUT_OVERWRITE_UNION_FILES = 1
} OstreeRepoCheckoutOverwriteMode;
gboolean ostree_repo_checkout_tree (OstreeRepo *self,OstreeRepoCheckoutMode mode,OstreeRepoCheckoutOverwriteMode overwrite_mode,GFile *destination,OstreeRepoFile *source,GFileInfo *source_info,GCancellable *cancellable,GError **error);
Check out source into destination, which must live on the
physical filesystem. source may be any subdirectory of a given
commit. The mode and overwrite_mode allow control over how the
files are checked out.
|
Repo |
|
Options controlling all files |
|
Whether or not to overwrite files |
|
Place tree here |
|
Source tree |
|
Source info |
|
Cancellable |
|
Error |
gboolean ostree_repo_checkout_gc (OstreeRepo *self,GCancellable *cancellable,GError **error);
Call this after finishing a succession of checkout operations; it will delete any currently-unused uncompressed objects from the cache.
|
Repo |
|
Cancellable |
|
Error |
gboolean ostree_repo_read_commit (OstreeRepo *self,const char *rev,GFile **out_root,GCancellable *cancellable,GError **error);
Load the content for rev into out_root.
|
Repo |
|
Revision (ref or ASCII checksum) |
|
An OstreeRepoFile corresponding to the root. [out] |
|
Cancellable |
|
Error |
typedef enum {
OSTREE_REPO_LIST_OBJECTS_LOOSE = (1 << 0),
OSTREE_REPO_LIST_OBJECTS_PACKED = (1 << 1),
OSTREE_REPO_LIST_OBJECTS_ALL = (1 << 2)
} OstreeRepoListObjectsFlags;
#define OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE (G_VARIANT_TYPE ("(bas)")
b - TRUE if object is available "loose"
as - List of pack file checksums in which this object appears
gboolean ostree_repo_list_objects (OstreeRepo *self,OstreeRepoListObjectsFlags flags,GHashTable **out_objects,GCancellable *cancellable,GError **error);
This function synchronously enumerates all objects in the
repository, returning data in out_objects. out_objects
maps from keys returned by ostree_object_name_serialize()
to GVariant values of type OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE.
|
Repo |
|
Flags controlling enumeration |
|
Map of serialized object name to variant data. [out] |
|
Cancellable |
|
Error |
Returns : |
TRUE on success, FALSE on error, and error will be set |
GHashTable * ostree_repo_traverse_new_reachable (void);
This hash table is a set of GVariant which can be accessed via
ostree_object_name_deserialize().
Returns : |
A new hash table. [transfer full][element-type GVariant GVariant] |
gboolean ostree_repo_traverse_dirtree (OstreeRepo *repo,const char *commit_checksum,GHashTable *inout_reachable,GCancellable *cancellable,GError **error);
gboolean ostree_repo_traverse_commit (OstreeRepo *repo,const char *commit_checksum,int maxdepth,GHashTable *inout_reachable,GCancellable *cancellable,GError **error);
typedef enum {
OSTREE_REPO_PRUNE_FLAGS_NONE,
OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE,
OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY
} OstreeRepoPruneFlags;
gboolean ostree_repo_prune (OstreeRepo *self,OstreeRepoPruneFlags flags,gint depth,gint *out_objects_total,gint *out_objects_pruned,guint64 *out_pruned_object_size_total,GCancellable *cancellable,GError **error);
Delete content from the repository. By default, this function will only delete "orphaned" objects not referred to by any commit. This can happen during a local commit operation, when we have written content objects but not saved the commit referencing them.
However, if OSTREE_REPO_PRUNE_FLAGS_REFS_ONLY is provided, instead
of traversing all commits, only refs will be used. Particularly
when combined with depth, this is a convenient way to delete
history from the repository.
Use the OSTREE_REPO_PRUNE_FLAGS_NO_PRUNE to just determine
statistics on objects that would be deleted, without actually
deleting them.
|
Repo |
|
Options controlling prune process |
|
Stop traversal after this many iterations (-1 for unlimited) |
|
Number of objects found. [out] |
|
Number of objects deleted. [out] |
|
Storage size in bytes of objects deleted. [out] |
|
Cancellable |
|
Error |
gboolean ostree_repo_pull (OstreeRepo *self,const char *remote_name,char **refs_to_fetch,OstreeRepoPullFlags flags,GCancellable *cancellable,GError **error);
Connect to the remote repository, fetching the specified set of
refs refs_to_fetch. For each ref that is changed, download the
commit, all metadata, and all content objects, storing them safely
on disk in self.
|
Repo |
|
Name of remote |
|
Optional list of refs; if NULL, fetch all configured refs. [array zero-terminated=1][element-type utf8][allow-none]
|
|
Options controlling fetch behavior |
|
Cancellable |
|
Error |