SUBDIRS += .
if ENABLE_GTK_DOC
-SUBDIRS += doc
+SUBDIRS += apidoc
endif
EXTRA_DIST += autogen.sh COPYING README.md
--- /dev/null
+ostree*.1
+ostree*.5
--- /dev/null
+# Copyright (C) 2013 Colin Walters <walters@verbum.org>
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the
+# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+
+abs_top_builddir = @abs_top_builddir@
+
+include ../Makefile-libostree-defines.am
+
+NULL =
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=ostree
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk
+DOC_SOURCE_DIR=$(top_srcdir)/src/libostree
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS= --version
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS= --rebuild-types
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS=--sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# MKHTML_OPTIONS=--path="$(builddir)/html $(srcdir)/html"
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS=
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB=$(addprefix $(top_srcdir)/,$(libostree_public_headers))
+CFILE_GLOB=$(top_srcdir)/src/libostree/*.c
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES= \
+ bupsplit.h \
+ ostree-bootloader.h \
+ ostree-bootloader-grub2.h \
+ ostree-bootloader-syslinux.h \
+ ostree-bootloader-uboot.h \
+ ostree-cmdprivate.h \
+ ostree-core-private.h \
+ ostree-fetcher.h \
+ ostree-gpg-verifier.h \
+ ostree-gpg-verify-result-private.h \
+ ostree-kernel-args.h \
+ ostree-libarchive-input-stream.h \
+ ostree-lzma-compressor.h \
+ ostree-lzma-decompressor.h \
+ ostree-metalink.h \
+ ostree-repo-file-enumerator.h \
+ ostree-repo-private.h \
+ ostree-repo-static-delta-private.h \
+ ostree-sysroot-private.h \
+ ostree-tls-cert-interaction.h \
+ $(NULL)
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files= \
+ overview.xml \
+ repo.xml \
+ deployment.xml \
+ atomic-upgrades.xml \
+ adapting-existing.xml \
+ $(NULL)
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files= \
+ version.xml \
+ $(NULL)
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_LIBS=
+
+# Hacks around gtk-doc brokenness for out of tree builds
+ostree-sections.txt: $(srcdir)/ostree-sections.txt
+ cp $< $@
+
+version.xml:
+ echo -n $(VERSION) > "$@"
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+EXTRA_DIST += \
+ version.xml \
+ ostree-sections.txt \
+ $(NULL)
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<part id="adapting-existing">
+ <title>Adapting existing mainstream distributions</title>
+ <chapter id="layout">
+ <title>System layout</title>
+ <para>
+ First, OSTree encourages systems to implement <ulink
+ url="http://www.freedesktop.org/wiki/Software/systemd/TheCaseForTheUsrMerge/">UsrMove</ulink>.
+ This is simply to avoid the need for more bind mounts. By
+ default OSTree's dracut hook creates a read-only bind mount over
+ <filename class='directory'>/usr</filename>; you can of course
+ generate individual bind-mounts for <filename
+ class='directory'>/bin</filename>, all the <filename
+ class='directory'>/lib</filename> variants, etc. So it is not
+ intended to be a hard requirement.
+ </para>
+
+ <para>
+ Remember, because by default the system is booted into a
+ <literal>chroot</literal> equivalent, there has to be some way
+ to refer to the actual physical root filesystem. Therefore,
+ your operating system tree should contain an empty <filename
+ class='directory'>/sysroot</filename> 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
+ <filename class='directory'>/ostree</filename> which points to
+ <filename class='directory'>/sysroot/ostree</filename>, 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.
+ </para>
+
+ <para>
+ Because OSTree only preserves <filename
+ class='directory'>/var</filename> 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 <ulink
+ url="http://www.pathname.com/fhs/">Filesystem Hierarchy
+ Standard</ulink>. Your operating system may of course choose
+ not to support some of these such as <filename
+ class='directory'>/usr/local</filename>, but following is the
+ recommended set:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename class='directory'>/home</filename> to <filename class='directory'>/var/home</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename class='directory'>/opt</filename> to <filename class='directory'>/var/opt</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename class='directory'>/srv</filename> to <filename class='directory'>/var/srv</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename class='directory'>/root</filename> to <filename class='directory'>/var/roothome</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename class='directory'>/usr/local</filename> to <filename class='directory'>/var/local</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename class='directory'>/mnt</filename> to <filename class='directory'>/var/mnt</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename class='directory'>/tmp</filename> to <filename class='directory'>/sysroot/tmp</filename>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Furthermore, since <filename class='directory'>/var</filename>
+ is empty by default, your operating system will need to
+ dynamically create the <emphasis>targets</emphasis> of these at
+ boot. A good way to do this is using
+ <command>systemd-tmpfiles</command>, if your OS uses systemd.
+ For example:
+ </para>
+
+ <programlisting>
+ <![CDATA[
+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 -
+ ]]>
+</programlisting>
+
+ <para>
+ Particularly note here the double indirection of <filename
+ class='directory'>/home</filename>. By default, each
+ deployment will share the global toplevel <filename
+ class='directory'>/home</filename> directory on the physical
+ root filesystem. It is then up to higher levels of management
+ tools to keep <filename>/etc/passwd</filename> or equivalent
+ synchronized between operating systems.
+ </para>
+ <para>
+ Each deployment can easily be reconfigured to have its own home
+ directory set simply by making <filename
+ class='directory'>/var/home</filename> a real directory.
+ </para>
+ </chapter>
+
+ <chapter id="booting">
+ <title>Booting and initramfs technology</title>
+ <para>
+ OSTree comes with optional dracut+systemd integration code that
+ parses the <literal>ostree=</literal> kernel command line
+ argument in the initramfs, and then sets up the read-only bind
+ mount on <filename class='directory'>/usr</filename>, a bind
+ mount on the deployment's <filename
+ class='directory'>/sysroot</filename> to the physical <filename
+ class='directory'>/</filename>, and then finally uses
+ <literal>mount(MS_MOVE)</literal> to make the deployment root appear to be the
+ root filesystem before telling systemd to switch root.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ A further specific note regarding <command>sysvinit</command>:
+ OSTree used to support recording device files such the
+ <filename>/dev/initctl</filename> FIFO, but no longer does.
+ It's recommended to just patch your initramfs to create this at
+ boot.
+ </para>
+ </chapter>
+
+ <chapter id="lib-passwd">
+ <title>/usr/lib/passwd</title>
+ <para>
+ Unlike traditional package systems, OSTree trees contain
+ <emphasis>numeric</emphasis> uid and gids. Furthermore, it does
+ not have a <literal>%post</literal> type mechanism where
+ <filename>useradd</filename> could be invoked. 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 <filename>/etc/passwd</filename>. The core problem is that
+ if you add a user to the system for a daemon, the OSTree upgrade
+ process for <filename class='directory'>/etc</filename> will
+ simply notice that because <filename>/etc/passwd</filename>
+ differs from the previous default, it will keep the modified
+ config file, and your new OS user will not be visible.
+ </para>
+ <para>
+ The solution chosen for the <ulink
+ url="https://live.gnome.org/Projects/GnomeContinuous">gnome-continuous</ulink>
+ operating system is to create
+ <filename>/usr/lib/passwd</filename>, and to include a NSS
+ module <ulink
+ url="https://github.com/aperezdc/nss-altfiles">nss-altfiles</ulink>
+ which instructs glibc to read from it. Then, the build system
+ places all system users there, freeing up
+ <filename>/etc/passwd</filename> to be purely a database of
+ local users. See also a more recent effort from <ulink
+ url="http://0pointer.de/blog/projects/stateless.html">Systemd
+ stateless</ulink>.
+ </para>
+ </chapter>
+
+ <chapter id="adapting-package-manager">
+ <title>Adapting existing package managers</title>
+ <para>
+ 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 <filename
+ class='directory'>/</filename>. This section will use examples
+ from both <command>dpkg</command> and <command>rpm</command> as
+ the author has familiarity with both; but the abstract concepts
+ should apply to most traditional package managers.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ Many package managers store their state in <filename
+ class='directory'>/var</filename>; but since in the OSTree model
+ that directory is shared between independent versions, the
+ package database must first be found in the per-deployment
+ <filename class='directory'>/usr</filename> 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 <filename
+ class='directory'>/var</filename> location if the one in
+ <filename class='directory'>/usr</filename> is not found.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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
+ <emphasis>layering</emphasis> the composed filesystem tree of
+ these new packages on top. A command lke this: <command>ostree
+ commit -b osname/releasename/description
+ --tree=ref=<replaceable>osname/releasenamename/description</replaceable>
+ --tree=dir=/var/tmp/newpackages.13A8D0/</command> will create a
+ new commit in the
+ <replaceable>osname/releasename/description</replaceable>
+ 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.
+ </para>
+
+ <para>
+ Then to actually deploy this tree for the next boot:
+ <command>ostree admin deploy
+ <replaceable>osname/releasenamename/description</replaceable></command>
+ </para>
+
+ </chapter>
+
+</part>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<part id="atomic-upgrades">
+ <title>Atomic Upgrades</title>
+ <chapter id="upgrades-intro">
+ <title>You can turn off the power anytime you want...</title>
+ <para>
+ 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.
+ </para>
+ </chapter>
+
+ <chapter id="simple-http">
+ <title>Simple upgrades via HTTP</title>
+ <para>
+ 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 <filename
+ class='extension'>.origin</filename> file for the deployment.
+ The command <command>ostree admin upgrade</command> implements
+ this.
+ </para>
+
+ <para>
+ To begin a simple upgrade, OSTree fetches the contents of the
+ ref from the remote server. Suppose we're tracking a ref named
+ <literal>exampleos/buildmaster/x86_64-runtime</literal>.
+ OSTree fetches the URL
+ <literal>http://<replaceable>example.com</replaceable>/repo/refs/exampleos/buildmaster/x86_64-runtime</literal>,
+ which contains a SHA256 checksum. This determines the tree to
+ deploy, and <filename class='directory'>/etc</filename> will be
+ merged from currently booted tree.
+ </para>
+
+ <para>
+ 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 <filename
+ class='directory'>/ostree/repo/objects/</filename>.
+ </para>
+
+ <para>
+ Once the pull is complete, we have all the objects locally
+ we need to perform a deployment.
+ </para>
+ </chapter>
+
+ <chapter id="package-manager">
+ <title>Upgrades via external tools (e.g. package managers)</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ At a practical level, most package managers today
+ (<command>dpkg</command> and <command>rpm</command>) 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: <xref linkend="adapting-existing"/>.
+ </para>
+
+ <para>
+ 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.
+ </para>
+ </chapter>
+
+ <chapter id="deployment-dir">
+ <title>Assembling a new deployment directory</title>
+ <para>
+ Given a commit to deploy, OSTree first allocates a directory for
+ it. This is of the form <filename
+ class='directory'>/boot/loader/entries/ostree-<replaceable>osname</replaceable>-<replaceable>checksum</replaceable>.<replaceable>serial</replaceable>.conf</filename>.
+ The <replaceable>serial</replaceable> 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 <filename class='directory'>/etc</filename>
+ that we do not want to use or overwrite.
+ </para>
+
+ <para>
+ Now that we have a deployment directory, a 3-way merge is
+ performed between the (by default) currently booted deployment's
+ <filename class='directory'>/etc</filename>, its default
+ configuration, and the new deployment (based on its <filename
+ class='directory'>/usr/etc</filename>).
+ </para>
+ </chapter>
+
+ <chapter id="swapping-boot">
+ <title>Atomically swapping boot configuration</title>
+ <para>
+ 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".
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <simplesect id="bootversion">
+ <title>The bootversion</title>
+ <para>
+ OSTree allows swapping between boot configurations by
+ implementing the "swapped directory pattern" in <filename
+ class='directory'>/boot</filename>. This means it is a
+ symbolic link to one of two directories <filename
+ class='directory'>/ostree/boot.<replaceable>[0|1]</replaceable></filename>.
+ To swap the contents atomically, if the current version is
+ <literal>0</literal>, we create <filename
+ class='directory'>/ostree/boot.1</filename>, populate it with
+ the new contents, then atomically swap the symbolic link. Finally,
+ the old contents can be garbage collected at any point.
+ </para>
+ </simplesect>
+
+ <simplesect id="ostree-bootversion">
+ <title>The /ostree/boot directory</title>
+ <para>
+ 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 <filename class='directory'>/boot</filename> may be on
+ a separate medium such as flash storage not optimized for
+ significant amounts of write traffic.
+ </para>
+
+ <para>
+ To implement this, OSTree also maintains the directory
+ <filename
+ class='directory'>/ostree/boot.<replaceable>bootversion</replaceable></filename>,
+ which is a set of symbolic links to the deployment
+ directories. The <replaceable>bootversion</replaceable> here
+ must match the version of <filename
+ class='directory'>/boot</filename>. However, in order to
+ allow atomic transitions of <emphasis>this</emphasis>
+ directory, this is also a swapped directory, so just like
+ <filename class='directory'>/boot</filename>, it has a version
+ of <literal>0</literal> or <literal>1</literal> appended.
+ </para>
+
+ <para>
+ Each bootloader entry has a special <literal>ostree=</literal>
+ argument which refers to one of these symbolic links. This is
+ parsed at runtime in the initramfs.
+ </para>
+
+ </simplesect>
+
+ </chapter>
+
+</part>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<part id="deployment">
+ <title>Deployments</title>
+ <chapter id="deployment-intro">
+ <title>Overview</title>
+ <para>
+ 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 <command>ostree
+ admin</command>). The core content of these operating systems
+ are treated as read-only, but they transparently share storage.
+ </para>
+
+ <para>
+ A deployment is physically located at a path of the form
+ <filename
+ class='directory'>/ostree/deploy/<replaceable>osname</replaceable>/deploy/<replaceable>checksum</replaceable></filename>.
+ OSTree is designed to boot directly into exactly one deployment
+ at a time; each deployment is intended to be a target for
+ <literal>chroot()</literal> or equivalent.
+ </para>
+
+ </chapter>
+
+ <chapter id="deployment-osname">
+ <title>"osname": Group of deployments that share /var</title>
+ <para>
+ Each deployment is grouped in exactly one "osname". From
+ above, you can see that an osname is physically represented in
+ the <filename
+ class='directory'>/ostree/deploy/<replaceable>osname</replaceable></filename>
+ directory. For example, OSTree can allow parallel installing
+ Debian in <filename
+ class='directory'>/ostree/deploy/debian</filename> and Red Hat
+ Enterprise Linux in <filename
+ class='directory'>/ostree/deploy/rhel</filename> (subject to
+ operating system support, present released versions of these
+ operating systems may not support this).
+ </para>
+
+ <para>
+ Each osname has exactly one copy of the traditional Unix
+ <filename class='directory'>/var</filename>, stored physically
+ in <filename
+ class='directory'>/ostree/deploy/<replaceable>osname</replaceable>/var</filename>.
+ OSTree provides support tools for <command>systemd</command>
+ to create a Linux bind mount that ensures the booted
+ deployment sees the shared copy of <filename
+ class='directory'>/var</filename>.
+ </para>
+
+ <para>
+ OSTree does not touch the contents of <filename
+ class='directory'>/var</filename>. Operating system components
+ such as daemon services are required to create any directories
+ they require there at runtime (e.g. <filename
+ class='directory'>/var/cache/<replaceable>daemonname</replaceable></filename>),
+ and to manage upgrading data formats inside those directories.
+ </para>
+ </chapter>
+
+ <chapter id="deployment-contents">
+ <title>Contents of a deployment</title>
+ <para>
+ A deployment begins with a specific commit (represented as a
+ SHA256 hash) in the OSTree repository in <filename
+ class='directory'>/ostree/repo</filename>. 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.
+ </para>
+
+ <para>
+ First, the tree must include a kernel stored as <filename
+ class='directory'>/boot/vmlinuz-<replaceable>checksum</replaceable></filename>.
+ 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 <filename
+ class='directory'>/boot/initramfs-<replaceable>checksum</replaceable></filename>.
+ 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.
+ </para>
+
+ <para>
+ The deployment should not have a traditional UNIX <filename
+ class='directory'>/etc</filename>; instead, it should include
+ <filename class='directory'>/usr/etc</filename>. This is the
+ "default configuration". When OSTree creates a deployment, it
+ performs a 3-way merge using the <emphasis>old</emphasis>
+ default configuration, the active system's <filename
+ class='directory'>/etc</filename>, and the new default
+ configuration. In the final filesystem tree for a deployment
+ then, <filename class='directory'>/etc</filename> is a regular
+ writable directory.
+ </para>
+
+ <para>
+ Besides the exceptions of <filename
+ class='directory'>/var</filename> and <filename
+ class='directory'>/etc</filename> 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 <filename
+ class='directory'>/usr</filename>, but this is not a hard
+ requirement.
+ </para>
+
+ <para>
+ Finally, a deployment may have a <filename
+ class='extension'>.origin</filename> file, stored next to its
+ directory. This file tells <command>ostree admin
+ upgrade</command> 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.
+ </para>
+
+ </chapter>
+
+ <chapter id="managing-boot">
+ <title>The system /boot</title>
+ <para>
+ While OSTree parallel installs deployments cleanly inside the
+ <filename class='directory'>/ostree</filename> directory,
+ ultimately it has to control the system's <filename
+ class='directory'>/boot</filename> directory. The way this
+ works is via the <ulink
+ url="http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/">boot
+ loader specification</ulink>, which is a standard for
+ bootloader-independent drop-in configuration files.
+ </para>
+ <para>
+ When a tree is deployed, it will have a configuration file
+ generated of the form <filename
+ class='directory'>/boot/loader/entries/ostree-<replaceable>osname</replaceable>-<replaceable>checksum</replaceable>.<replaceable>serial</replaceable>.conf</filename>.
+ This configuration file will include a special
+ <literal>ostree=</literal> kernel argument that allows the
+ initramfs to find (and <literal>chroot()</literal> into) the
+ specified deployment.
+ </para>
+
+ <para>
+ At present, not all bootloaders implement the BootLoaderSpec,
+ so OSTree contains code for some of these to regenerate native
+ config files (such as
+ <filename>/boot/syslinux/syslinux.conf</filename> based on the
+ entries.
+ </para>
+
+ </chapter>
+</part>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+ <!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index">
+ <bookinfo>
+ <title>OSTree Manual</title>
+ <releaseinfo>for OSTree &version;</releaseinfo>
+ </bookinfo>
+
+ <xi:include href="overview.xml"/>
+ <xi:include href="repo.xml"/>
+ <xi:include href="deployment.xml"/>
+ <xi:include href="atomic-upgrades.xml"/>
+ <xi:include href="adapting-existing.xml"/>
+
+ <chapter xml:id="reference">
+ <title>API Reference</title>
+ <xi:include href="xml/libostree-core.xml"/>
+ <xi:include href="xml/libostree-repo.xml"/>
+ <xi:include href="xml/libostree-mutable-tree.xml"/>
+ <xi:include href="xml/libostree-sysroot.xml"/>
+ <xi:include href="xml/libostree-async-progress.xml"/>
+ <xi:include href="xml/libostree-sepolicy.xml"/>
+ <xi:include href="xml/libostree-sysroot-upgrader.xml"/>
+ <xi:include href="xml/libostree-gpg-verify-result.xml"/>
+ <xi:include href="xml/libostree-bootconfig-parser.xml"/>
+ <xi:include href="xml/libostree-chain-input-stream.xml"/>
+ <xi:include href="xml/libostree-checksum-input-stream.xml"/>
+ <xi:include href="xml/libostree-deployment.xml"/>
+ <xi:include href="xml/libostree-diff.xml"/>
+ <xi:include href="xml/libostree-repo-file.xml"/>
+
+ <index id="api-index-full">
+ <title>API Index</title>
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ </index>
+
+ </chapter>
+</book>
--- /dev/null
+<SECTION>
+<FILE>libostree-async-progress</FILE>
+OstreeAsyncProgress
+ostree_async_progress_new
+ostree_async_progress_new_and_connect
+ostree_async_progress_get_status
+ostree_async_progress_get_uint
+ostree_async_progress_get_uint64
+ostree_async_progress_set_status
+ostree_async_progress_set_uint
+ostree_async_progress_set_uint64
+ostree_async_progress_finish
+<SUBSECTION Standard>
+OSTREE_ASYNC_PROGRESS
+OSTREE_IS_ASYNC_PROGRESS
+OSTREE_TYPE_ASYNC_PROGRESS
+OSTREE_ASYNC_PROGRESS_CLASS
+OSTREE_IS_ASYNC_PROGRESS_CLASS
+OSTREE_ASYNC_PROGRESS_GET_CLASS
+OstreeAsyncProgressClass
+ostree_async_progress_get_type
+</SECTION>
+
+<SECTION>
+<FILE>libostree-bootconfig-parser</FILE>
+OstreeBootconfigParser
+ostree_bootconfig_parser_new
+ostree_bootconfig_parser_clone
+ostree_bootconfig_parser_parse
+ostree_bootconfig_parser_write
+ostree_bootconfig_parser_set
+ostree_bootconfig_parser_get
+<SUBSECTION Standard>
+OSTREE_BOOTCONFIG_PARSER
+OSTREE_IS_BOOTCONFIG_PARSER
+OSTREE_TYPE_BOOTCONFIG_PARSER
+ostree_bootconfig_parser_get_type
+</SECTION>
+
+<SECTION>
+<FILE>libostree-chain-input-stream</FILE>
+OstreeChainInputStream
+ostree_chain_input_stream_new
+<SUBSECTION Standard>
+OSTREE_CHAIN_INPUT_STREAM
+OSTREE_IS_CHAIN_INPUT_STREAM
+OSTREE_TYPE_CHAIN_INPUT_STREAM
+OSTREE_CHAIN_INPUT_STREAM_CLASS
+OSTREE_IS_CHAIN_INPUT_STREAM_CLASS
+OSTREE_CHAIN_INPUT_STREAM_GET_CLASS
+OstreeChainInputStreamClass
+OstreeChainInputStreamPrivate
+ostree_chain_input_stream_get_type
+</SECTION>
+
+<SECTION>
+<FILE>libostree-checksum-input-stream</FILE>
+OstreeChecksumInputStream
+ostree_checksum_input_stream_new
+<SUBSECTION Standard>
+OSTREE_CHECKSUM_INPUT_STREAM
+OSTREE_IS_CHECKSUM_INPUT_STREAM
+OSTREE_TYPE_CHECKSUM_INPUT_STREAM
+OSTREE_CHECKSUM_INPUT_STREAM_CLASS
+OSTREE_IS_CHECKSUM_INPUT_STREAM_CLASS
+OSTREE_CHECKSUM_INPUT_STREAM_GET_CLASS
+OstreeChecksumInputStreamClass
+OstreeChecksumInputStreamPrivate
+ostree_checksum_input_stream_get_type
+</SECTION>
+
+<SECTION>
+<FILE>libostree-core</FILE>
+OSTREE_MAX_METADATA_SIZE
+OSTREE_MAX_METADATA_WARN_SIZE
+OSTREE_MAX_RECURSION
+OstreeObjectType
+OSTREE_OBJECT_TYPE_IS_META
+OSTREE_OBJECT_TYPE_LAST
+OSTREE_DIRMETA_GVARIANT_STRING
+OSTREE_DIRMETA_GVARIANT_FORMAT
+OSTREE_FILEMETA_GVARIANT_STRING
+OSTREE_FILEMETA_GVARIANT_FORMAT
+OSTREE_TREE_GVARIANT_STRING
+OSTREE_TREE_GVARIANT_FORMAT
+OSTREE_COMMIT_GVARIANT_STRING
+OSTREE_COMMIT_GVARIANT_FORMAT
+OSTREE_SUMMARY_GVARIANT_STRING
+OSTREE_SUMMARY_GVARIANT_FORMAT
+ostree_metadata_variant_type
+ostree_validate_checksum_string
+ostree_checksum_to_bytes
+ostree_checksum_to_bytes_v
+ostree_checksum_from_bytes
+ostree_checksum_from_bytes_v
+ostree_checksum_inplace_from_bytes
+ostree_checksum_inplace_to_bytes
+ostree_checksum_bytes_peek
+ostree_checksum_bytes_peek_validate
+ostree_cmp_checksum_bytes
+ostree_validate_rev
+ostree_parse_refspec
+ostree_checksum_update_meta
+ostree_object_type_to_string
+ostree_object_type_from_string
+ostree_hash_object_name
+ostree_object_name_serialize
+ostree_object_name_deserialize
+ostree_object_to_string
+ostree_object_from_string
+ostree_content_stream_parse
+ostree_content_file_parse
+ostree_raw_file_to_content_stream
+ostree_checksum_file_from_input
+ostree_checksum_file
+ostree_checksum_file_async
+ostree_checksum_file_async_finish
+ostree_create_directory_metadata
+ostree_validate_structureof_objtype
+ostree_validate_structureof_csum_v
+ostree_validate_structureof_checksum_string
+ostree_validate_structureof_file_mode
+ostree_validate_structureof_commit
+ostree_validate_structureof_dirtree
+ostree_validate_structureof_dirmeta
+ostree_commit_get_parent
+ostree_commit_get_timestamp
+</SECTION>
+
+<SECTION>
+<FILE>libostree-deployment</FILE>
+OstreeDeployment
+ostree_deployment_hash
+ostree_deployment_equal
+ostree_deployment_new
+ostree_deployment_get_index
+ostree_deployment_get_osname
+ostree_deployment_get_deployserial
+ostree_deployment_get_csum
+ostree_deployment_get_bootcsum
+ostree_deployment_get_bootserial
+ostree_deployment_get_bootconfig
+ostree_deployment_get_origin
+ostree_deployment_set_index
+ostree_deployment_set_bootserial
+ostree_deployment_set_bootconfig
+ostree_deployment_set_origin
+ostree_deployment_clone
+<SUBSECTION Standard>
+OSTREE_DEPLOYMENT
+OSTREE_IS_DEPLOYMENT
+OSTREE_TYPE_DEPLOYMENT
+ostree_deployment_get_type
+</SECTION>
+
+<SECTION>
+<FILE>libostree-diff</FILE>
+OstreeDiffFlags
+OstreeDiffItem
+ostree_diff_item_ref
+ostree_diff_item_unref
+ostree_diff_dirs
+ostree_diff_print
+<SUBSECTION Standard>
+ostree_diff_item_get_type
+</SECTION>
+
+<SECTION>
+<FILE>libostree-gpg-verify-result</FILE>
+OstreeGpgVerifyResult
+OstreeGpgSignatureAttr
+ostree_gpg_verify_result_count_all
+ostree_gpg_verify_result_count_valid
+ostree_gpg_verify_result_lookup
+ostree_gpg_verify_result_get
+ostree_gpg_verify_result_get_all
+OstreeGpgSignatureFormatFlags
+ostree_gpg_verify_result_describe
+ostree_gpg_verify_result_describe_variant
+<SUBSECTION Standard>
+OSTREE_GPG_VERIFY_RESULT
+OSTREE_IS_GPG_VERIFY_RESULT
+OSTREE_TYPE_GPG_VERIFY_RESULT
+ostree_gpg_verify_result_get_type
+</SECTION>
+
+<SECTION>
+<FILE>libostree-mutable-tree</FILE>
+OstreeMutableTree
+ostree_mutable_tree_new
+ostree_mutable_tree_set_metadata_checksum
+ostree_mutable_tree_get_metadata_checksum
+ostree_mutable_tree_set_contents_checksum
+ostree_mutable_tree_get_contents_checksum
+ostree_mutable_tree_replace_file
+ostree_mutable_tree_ensure_dir
+ostree_mutable_tree_lookup
+ostree_mutable_tree_ensure_parent_dirs
+ostree_mutable_tree_walk
+ostree_mutable_tree_get_subdirs
+ostree_mutable_tree_get_files
+<SUBSECTION Standard>
+OSTREE_MUTABLE_TREE
+OSTREE_IS_MUTABLE_TREE
+OSTREE_TYPE_MUTABLE_TREE
+OSTREE_MUTABLE_TREE_CLASS
+OSTREE_IS_MUTABLE_TREE_CLASS
+OSTREE_MUTABLE_TREE_GET_CLASS
+OstreeMutableTreeClass
+ostree_mutable_tree_get_type
+</SECTION>
+
+<SECTION>
+<FILE>libostree-repo</FILE>
+OstreeRepo
+OstreeRepoMode
+ostree_repo_mode_from_string
+ostree_repo_new
+ostree_repo_new_for_sysroot_path
+ostree_repo_new_default
+ostree_repo_open
+ostree_repo_set_disable_fsync
+ostree_repo_get_disable_fsync
+ostree_repo_is_system
+ostree_repo_is_writable
+ostree_repo_create
+ostree_repo_get_path
+ostree_repo_get_mode
+ostree_repo_get_config
+ostree_repo_copy_config
+ostree_repo_remote_add
+ostree_repo_remote_delete
+OstreeRepoRemoteChange
+ostree_repo_remote_change
+ostree_repo_remote_list
+ostree_repo_remote_get_url
+ostree_repo_remote_get_gpg_verify
+ostree_repo_remote_get_gpg_verify_summary
+ostree_repo_remote_gpg_import
+ostree_repo_remote_fetch_summary
+ostree_repo_get_parent
+ostree_repo_write_config
+OstreeRepoTransactionStats
+ostree_repo_scan_hardlinks
+ostree_repo_prepare_transaction
+ostree_repo_commit_transaction
+ostree_repo_abort_transaction
+ostree_repo_transaction_set_refspec
+ostree_repo_transaction_set_ref
+ostree_repo_set_ref_immediate
+ostree_repo_has_object
+ostree_repo_write_metadata
+ostree_repo_write_metadata_async
+ostree_repo_write_metadata_finish
+ostree_repo_write_content
+ostree_repo_write_metadata_trusted
+ostree_repo_write_metadata_stream_trusted
+ostree_repo_write_content_trusted
+ostree_repo_write_content_async
+ostree_repo_write_content_finish
+ostree_repo_resolve_rev
+ostree_repo_list_refs
+ostree_repo_remote_list_refs
+ostree_repo_load_variant
+ostree_repo_load_commit
+ostree_repo_load_variant_if_exists
+ostree_repo_load_file
+ostree_repo_load_object_stream
+ostree_repo_query_object_storage_size
+ostree_repo_import_object_from
+ostree_repo_delete_object
+OstreeRepoCommitFilterResult
+OstreeRepoCommitFilter
+OstreeRepoCommitModifier
+OstreeRepoCommitModifierFlags
+ostree_repo_commit_modifier_new
+OstreeRepoCommitModifierXattrCallback
+ostree_repo_commit_modifier_set_xattr_callback
+ostree_repo_commit_modifier_set_sepolicy
+ostree_repo_commit_modifier_set_devino_cache
+ostree_repo_commit_modifier_ref
+ostree_repo_commit_modifier_unref
+ostree_repo_devino_cache_new
+ostree_repo_devino_cache_ref
+ostree_repo_devino_cache_unref
+ostree_repo_write_directory_to_mtree
+ostree_repo_write_dfd_to_mtree
+ostree_repo_write_archive_to_mtree
+ostree_repo_write_mtree
+ostree_repo_write_commit
+ostree_repo_write_commit_with_time
+ostree_repo_read_commit_detached_metadata
+ostree_repo_write_commit_detached_metadata
+OstreeRepoCheckoutMode
+OstreeRepoCheckoutOverwriteMode
+ostree_repo_checkout_tree
+ostree_repo_checkout_tree_at
+ostree_repo_checkout_gc
+ostree_repo_read_commit
+OstreeRepoListObjectsFlags
+OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE
+ostree_repo_list_objects
+ostree_repo_list_commit_objects_starting_with
+ostree_repo_list_static_delta_names
+OstreeStaticDeltaGenerateOpt
+ostree_repo_static_delta_generate
+ostree_repo_static_delta_execute_offline
+ostree_repo_traverse_new_reachable
+ostree_repo_traverse_commit
+ostree_repo_traverse_commit_union
+OstreeRepoPruneFlags
+ostree_repo_prune
+OstreeRepoPullFlags
+ostree_repo_pull
+ostree_repo_pull_one_dir
+ostree_repo_pull_with_options
+ostree_repo_pull_default_console_progress_changed
+ostree_repo_sign_commit
+ostree_repo_append_gpg_signature
+ostree_repo_verify_commit
+ostree_repo_verify_commit_ext
+ostree_repo_verify_summary
+ostree_repo_regenerate_summary
+<SUBSECTION Standard>
+OSTREE_REPO
+OSTREE_IS_REPO
+OSTREE_TYPE_REPO
+ostree_repo_get_type
+ostree_repo_commit_modifier_get_type
+ostree_repo_transaction_stats_get_type
+</SECTION>
+
+<SECTION>
+<FILE>libostree-repo-file</FILE>
+OstreeRepoFile
+ostree_repo_file_ensure_resolved
+ostree_repo_file_get_xattrs
+ostree_repo_file_get_repo
+ostree_repo_file_get_root
+ostree_repo_file_make_empty_tree
+ostree_repo_file_tree_set_metadata
+ostree_repo_file_tree_get_contents_checksum
+ostree_repo_file_tree_get_metadata_checksum
+ostree_repo_file_tree_get_contents
+ostree_repo_file_tree_get_metadata
+ostree_repo_file_get_checksum
+ostree_repo_file_tree_find_child
+ostree_repo_file_tree_query_child
+<SUBSECTION Standard>
+OSTREE_REPO_FILE
+OSTREE_IS_REPO_FILE
+OSTREE_TYPE_REPO_FILE
+OSTREE_REPO_FILE_CLASS
+OSTREE_IS_REPO_FILE_CLASS
+OSTREE_REPO_FILE_GET_CLASS
+OstreeRepoFileClass
+ostree_repo_file_get_type
+</SECTION>
+
+<SECTION>
+<FILE>libostree-sepolicy</FILE>
+OstreeSePolicy
+ostree_sepolicy_new
+ostree_sepolicy_get_path
+ostree_sepolicy_get_name
+ostree_sepolicy_get_label
+OstreeSePolicyRestoreconFlags
+ostree_sepolicy_restorecon
+<SUBSECTION Standard>
+OSTREE_SEPOLICY
+OSTREE_IS_SEPOLICY
+OSTREE_TYPE_SEPOLICY
+ostree_sepolicy_get_type
+</SECTION>
+
+<SECTION>
+<FILE>libostree-sysroot</FILE>
+OstreeSysroot
+ostree_sysroot_new
+ostree_sysroot_new_default
+ostree_sysroot_get_path
+ostree_sysroot_load
+ostree_sysroot_lock
+ostree_sysroot_try_lock
+ostree_sysroot_lock_async
+ostree_sysroot_lock_finish
+ostree_sysroot_unlock
+ostree_sysroot_get_fd
+ostree_sysroot_ensure_initialized
+ostree_sysroot_get_bootversion
+ostree_sysroot_get_subbootversion
+ostree_sysroot_get_deployments
+ostree_sysroot_get_booted_deployment
+ostree_sysroot_get_deployment_directory
+ostree_sysroot_get_deployment_origin_path
+ostree_sysroot_cleanup
+ostree_sysroot_prepare_cleanup
+ostree_sysroot_get_repo
+ostree_sysroot_deployment_set_kargs
+ostree_sysroot_write_deployments
+ostree_sysroot_deploy_tree
+ostree_sysroot_get_merge_deployment
+ostree_sysroot_origin_new_from_refspec
+OstreeSysrootSimpleWriteDeploymentFlags
+ostree_sysroot_simple_write_deployment
+<SUBSECTION Standard>
+OSTREE_SYSROOT
+OSTREE_IS_SYSROOT
+OSTREE_TYPE_SYSROOT
+ostree_sysroot_get_type
+</SECTION>
+
+<SECTION>
+<FILE>libostree-sysroot-upgrader</FILE>
+OstreeSysrootUpgrader
+ostree_sysroot_upgrader_new
+ostree_sysroot_upgrader_new_for_os
+OstreeSysrootUpgraderFlags
+ostree_sysroot_upgrader_new_for_os_with_flags
+ostree_sysroot_upgrader_get_origin
+ostree_sysroot_upgrader_dup_origin
+ostree_sysroot_upgrader_set_origin
+ostree_sysroot_upgrader_get_origin_description
+ostree_sysroot_upgrader_check_timestamps
+OstreeSysrootUpgraderPullFlags
+ostree_sysroot_upgrader_pull
+ostree_sysroot_upgrader_pull_one_dir
+ostree_sysroot_upgrader_deploy
+<SUBSECTION Standard>
+OSTREE_SYSROOT_UPGRADER
+OSTREE_IS_SYSROOT_UPGRADER
+OSTREE_TYPE_SYSROOT_UPGRADER
+ostree_sysroot_upgrader_get_type
+ostree_sysroot_upgrader_flags_get_type
+</SECTION>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<part id="overview">
+ <title>OSTree Overview</title>
+ <chapter id="ostree-intro">
+ <title>Introduction</title>
+ <para>
+ OSTree an upgrade system for Linux-based operating systems that
+ performs atomic upgrades of complete filesystem trees. It is
+ not a package system; rather, it is intended to complement them.
+ A primary model is composing packages on a server, and then
+ replicating them to clients.
+ </para>
+
+ <para>
+ The underlying architecture might be summarized as "git for
+ operating system binaries". It operates in userspace, and will
+ work on top of any Linux filesystem. At its core is a git-like
+ content-addressed object store, and layered on top of that is
+ bootloader configuration, management of
+ <filename>/etc</filename>, and other functions to perform an
+ upgrade beyond just replicating files.
+ </para>
+
+ <para>
+ You can use OSTree standalone in the pure replication model,
+ but another approach is to add a package manager on top,
+ thus creating a hybrid tree/package system.
+ </para>
+
+ </chapter>
+
+ <chapter id="ostree-package-comparison">
+ <title>Comparison with "package managers"</title>
+ <para>
+ 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.
+ </para>
+
+ <para>
+ In contrast, OSTree only supports recording and deploying
+ <emphasis>complete</emphasis> (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. Put another way, OSTree
+ only handles delivery and deployment; you will likely still want
+ to include inside each tree metadata about the individual
+ components that went into the tree. For example, a system
+ administrator may want to know what version of OpenSSL was
+ included in your tree, so you should support the equivalent of
+ <command>rpm -q</command> or <command>dpkg -L</command>.
+ </para>
+
+ <para>
+ 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 <filename
+ class='directory'>/var</filename> if they're system global, or
+ <filename class='directory'>/home</filename> for per-user
+ application installation. An example application mechanism is
+ <ulink url="http://docker.io/">Docker</ulink>.
+ </para>
+
+ <para>
+ However, it is entirely possible to use OSTree underneath a
+ package system, where the contents of <filename
+ class='directory'>/usr</filename> are computed on the client.
+ For example, when installing a package, rather than changing the
+ currently running filesystem, the package manager could assemble
+ a new filesystem tree that layers the new packages on top of a
+ base tree, 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.
+ </para>
+ </chapter>
+
+ <chapter id="ostree-block-comparison">
+ <title>Comparison with block/image replication</title>
+ <para>
+ 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 <emphasis>reliable</emphasis>
+ and <emphasis>predictable</emphasis>.
+ </para>
+ <para>
+ But unlike many default image-based deployments, OSTree supports
+ exactly two persistent writable directories that are preserved
+ across upgrades: <literal>/etc</literal> and
+ <literal>/var</literal>.
+ </para>
+ <para>
+ 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.
+ </para>
+ </chapter>
+
+ <chapter id="ostree-atomic-parallel-installation">
+ <title>Atomic transitions between parallel-installable read-only filesystem trees</title>
+ <para>
+ Another deeply fundamental difference between both package
+ managers and image-based replication is that OSTree is
+ designed to parallel-install <emphasis>multiple
+ versions</emphasis> of multiple
+ <emphasis>independent</emphasis> operating systems. OSTree
+ relies on a new toplevel <filename
+ class='directory'>ostree</filename> directory; it can in fact
+ parallel install inside an existing OS or distribution
+ occupying the physical <filename
+ class='directory'>/</filename> root.
+ </para>
+ <para>
+ On each client machine, there is an OSTree repository stored
+ in <filename class='directory'>/ostree/repo</filename>, and a
+ set of "deployments" stored in <filename
+ class='directory'>/ostree/deploy/<replaceable>OSNAME</replaceable>/<replaceable>CHECKSUM</replaceable></filename>.
+ 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.
+ </para>
+ <para>
+ The model OSTree emphasizes is that the OS read-only content
+ is kept in the classic Unix <filename
+ class='directory'>/usr</filename>; it comes with code to
+ create a Linux read-only bind mount to prevent inadvertent
+ corruption. There is exactly one <filename
+ class='directory'>/var</filename> 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.
+ </para>
+ <para>
+ Finally, each deployment has its own writable copy of the
+ configuration store <filename
+ class='directory'>/etc</filename>. On upgrade, OSTree will
+ perform a basic 3-way diff, and apply any local changes to the
+ new copy, while leaving the old untouched.
+ </para>
+ </chapter>
+</part>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<part id="repository">
+ <title>Anatomy of an OSTree repository</title>
+ <chapter id="repository-intro">
+ <title>Core object types and data model</title>
+ <para>
+ 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 <ulink
+ url="http://git-scm.com/book/en/Git-Internals">Git
+ Internals</ulink>, as this section will assume some knowledge of
+ how git works.
+ </para>
+
+ <para>
+ 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).
+ </para>
+
+ <simplesect id="commits">
+ <title>Commit objects</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ </simplesect>
+
+ <simplesect id="dirtree">
+ <title>Dirtree objects</title>
+ <para>
+ 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.
+ </para>
+ </simplesect>
+
+ <simplesect id="dirmeta">
+ <title>Dirmeta objects</title>
+ <para>
+ 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.
+ </para>
+ </simplesect>
+
+ <simplesect id="content">
+ <title>Content objects</title>
+ <para>
+ Unlike the first three object types which are metadata,
+ designed to be <literal>mmap()ed</literal>, 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.
+ </para>
+ </simplesect>
+ </chapter>
+
+ <chapter id="repository-types">
+ <title>Repository types and locations</title>
+
+ <para>
+ Also unlike git, an OSTree repository can be in one of two
+ separate modes: <literal>bare</literal> and
+ <literal>archive-z2</literal>. 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 <literal>archive-z2</literal> mode is designed
+ for serving via plain HTTP. Like tar files, it can be
+ read/written by non-root users.
+ </para>
+
+ <para>
+ On an OSTree-deployed system, the "system repository" is
+ <filename class='directory'>/ostree/repo</filename>. It can be
+ read by any uid, but only written by root. Unless the
+ <literal>--repo</literal> argument is given to the
+ <command>ostree</command> command, it will operate on the system
+ repository.
+ </para>
+ </chapter>
+
+ <chapter id="refs">
+ <title>Refs</title>
+ <para>
+ 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
+ <literal>gnome-ostree/buildmaster/x86_64-runtime</literal> and
+ <literal>gnome-ostree/buildmaster/x86_64-devel-debug</literal>.
+ 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.
+ </para>
+
+ <para>
+ The <command>ostree</command> supports a simple syntax using the
+ carat <literal>^</literal> to refer to the parent of a given
+ commit. For example,
+ <literal>gnome-ostree/buildmaster/x86_64-runtime^</literal>
+ refers to the previous build, and
+ <literal>gnome-ostree/buildmaster/x86_64-runtime^^</literal>
+ refers to the one before that.
+ </para>
+ </chapter>
+</part>
AC_CONFIG_FILES([
Makefile
-doc/Makefile
+apidoc/Makefile
src/libostree/ostree-1.pc
])
AC_OUTPUT
SELinux: $with_selinux
libarchive (parse tar files directly): $with_libarchive
static deltas: $enable_static_deltas
- documentation: $enable_gtk_doc
+ man pages (xsltproc): $XSLTPROC
+ api docs (gtk-doc): $enable_gtk_doc
gjs-based tests: $have_gjs
dracut: $with_dracut
mkinitcpio: $with_mkinitcpio"
+++ /dev/null
-ostree*.1
-ostree*.5
+++ /dev/null
-# Copyright (C) 2013 Colin Walters <walters@verbum.org>
-#
-# This library is free software; you can redistribute it and/or
-# modify it under the terms of the GNU Lesser General Public
-# License as published by the Free Software Foundation; either
-# version 2 of the License, or (at your option) any later version.
-#
-# This library is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-# Lesser General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public
-# License along with this library; if not, write to the
-# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-# Boston, MA 02111-1307, USA.
-
-abs_top_builddir = @abs_top_builddir@
-
-include ../Makefile-libostree-defines.am
-
-NULL =
-
-# We require automake 1.6 at least.
-AUTOMAKE_OPTIONS = 1.6
-
-# The name of the module, e.g. 'glib'.
-DOC_MODULE=ostree
-
-# The top-level SGML file. You can change this if you want to.
-DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
-
-# The directory containing the source code. Relative to $(srcdir).
-# gtk-doc will search all .c & .h files beneath here for inline comments
-# documenting the functions and macros.
-# e.g. DOC_SOURCE_DIR=../../../gtk
-DOC_SOURCE_DIR=$(top_srcdir)/src/libostree
-
-# Extra options to pass to gtkdoc-scangobj. Not normally needed.
-SCANGOBJ_OPTIONS= --version
-
-# Extra options to supply to gtkdoc-scan.
-# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
-SCAN_OPTIONS= --rebuild-types
-
-# Extra options to supply to gtkdoc-mkdb.
-# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
-MKDB_OPTIONS=--sgml-mode --output-format=xml
-
-# Extra options to supply to gtkdoc-mktmpl
-# e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS=
-
-# MKHTML_OPTIONS=--path="$(builddir)/html $(srcdir)/html"
-
-# Extra options to supply to gtkdoc-fixref. Not normally needed.
-# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
-FIXXREF_OPTIONS=
-
-# Used for dependencies. The docs will be rebuilt if any of these change.
-# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
-# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
-HFILE_GLOB=$(addprefix $(top_srcdir)/,$(libostree_public_headers))
-CFILE_GLOB=$(top_srcdir)/src/libostree/*.c
-
-# Header files to ignore when scanning.
-# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
-IGNORE_HFILES= \
- bupsplit.h \
- ostree-bootloader.h \
- ostree-bootloader-grub2.h \
- ostree-bootloader-syslinux.h \
- ostree-bootloader-uboot.h \
- ostree-cmdprivate.h \
- ostree-core-private.h \
- ostree-fetcher.h \
- ostree-gpg-verifier.h \
- ostree-gpg-verify-result-private.h \
- ostree-kernel-args.h \
- ostree-libarchive-input-stream.h \
- ostree-lzma-compressor.h \
- ostree-lzma-decompressor.h \
- ostree-metalink.h \
- ostree-repo-file-enumerator.h \
- ostree-repo-private.h \
- ostree-repo-static-delta-private.h \
- ostree-sysroot-private.h \
- ostree-tls-cert-interaction.h \
- $(NULL)
-
-# Images to copy into HTML directory.
-# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
-HTML_IMAGES=
-
-# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
-# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files= \
- overview.xml \
- repo.xml \
- deployment.xml \
- atomic-upgrades.xml \
- adapting-existing.xml \
- $(NULL)
-
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
-# These files must be listed here *and* in content_files
-# e.g. expand_content_files=running.sgml
-expand_content_files= \
- version.xml \
- $(NULL)
-
-# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
-# Only needed if you are using gtkdoc-scangobj to dynamically query widget
-# signals and properties.
-# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
-# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
-GTKDOC_LIBS=
-
-# Hacks around gtk-doc brokenness for out of tree builds
-ostree-sections.txt: $(srcdir)/ostree-sections.txt
- cp $< $@
-
-version.xml:
- echo -n $(VERSION) > "$@"
-
-# This includes the standard gtk-doc make rules, copied by gtkdocize.
-include $(top_srcdir)/gtk-doc.make
-
-EXTRA_DIST += \
- version.xml \
- ostree-sections.txt \
- $(NULL)
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-<!ENTITY version SYSTEM "../version.xml">
-]>
-<part id="adapting-existing">
- <title>Adapting existing mainstream distributions</title>
- <chapter id="layout">
- <title>System layout</title>
- <para>
- First, OSTree encourages systems to implement <ulink
- url="http://www.freedesktop.org/wiki/Software/systemd/TheCaseForTheUsrMerge/">UsrMove</ulink>.
- This is simply to avoid the need for more bind mounts. By
- default OSTree's dracut hook creates a read-only bind mount over
- <filename class='directory'>/usr</filename>; you can of course
- generate individual bind-mounts for <filename
- class='directory'>/bin</filename>, all the <filename
- class='directory'>/lib</filename> variants, etc. So it is not
- intended to be a hard requirement.
- </para>
-
- <para>
- Remember, because by default the system is booted into a
- <literal>chroot</literal> equivalent, there has to be some way
- to refer to the actual physical root filesystem. Therefore,
- your operating system tree should contain an empty <filename
- class='directory'>/sysroot</filename> 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
- <filename class='directory'>/ostree</filename> which points to
- <filename class='directory'>/sysroot/ostree</filename>, 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.
- </para>
-
- <para>
- Because OSTree only preserves <filename
- class='directory'>/var</filename> 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 <ulink
- url="http://www.pathname.com/fhs/">Filesystem Hierarchy
- Standard</ulink>. Your operating system may of course choose
- not to support some of these such as <filename
- class='directory'>/usr/local</filename>, but following is the
- recommended set:
- <itemizedlist>
- <listitem>
- <para>
- <filename class='directory'>/home</filename> to <filename class='directory'>/var/home</filename>
- </para>
- </listitem>
- <listitem>
- <para>
- <filename class='directory'>/opt</filename> to <filename class='directory'>/var/opt</filename>
- </para>
- </listitem>
- <listitem>
- <para>
- <filename class='directory'>/srv</filename> to <filename class='directory'>/var/srv</filename>
- </para>
- </listitem>
- <listitem>
- <para>
- <filename class='directory'>/root</filename> to <filename class='directory'>/var/roothome</filename>
- </para>
- </listitem>
- <listitem>
- <para>
- <filename class='directory'>/usr/local</filename> to <filename class='directory'>/var/local</filename>
- </para>
- </listitem>
- <listitem>
- <para>
- <filename class='directory'>/mnt</filename> to <filename class='directory'>/var/mnt</filename>
- </para>
- </listitem>
- <listitem>
- <para>
- <filename class='directory'>/tmp</filename> to <filename class='directory'>/sysroot/tmp</filename>
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- Furthermore, since <filename class='directory'>/var</filename>
- is empty by default, your operating system will need to
- dynamically create the <emphasis>targets</emphasis> of these at
- boot. A good way to do this is using
- <command>systemd-tmpfiles</command>, if your OS uses systemd.
- For example:
- </para>
-
- <programlisting>
- <![CDATA[
-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 -
- ]]>
-</programlisting>
-
- <para>
- Particularly note here the double indirection of <filename
- class='directory'>/home</filename>. By default, each
- deployment will share the global toplevel <filename
- class='directory'>/home</filename> directory on the physical
- root filesystem. It is then up to higher levels of management
- tools to keep <filename>/etc/passwd</filename> or equivalent
- synchronized between operating systems.
- </para>
- <para>
- Each deployment can easily be reconfigured to have its own home
- directory set simply by making <filename
- class='directory'>/var/home</filename> a real directory.
- </para>
- </chapter>
-
- <chapter id="booting">
- <title>Booting and initramfs technology</title>
- <para>
- OSTree comes with optional dracut+systemd integration code that
- parses the <literal>ostree=</literal> kernel command line
- argument in the initramfs, and then sets up the read-only bind
- mount on <filename class='directory'>/usr</filename>, a bind
- mount on the deployment's <filename
- class='directory'>/sysroot</filename> to the physical <filename
- class='directory'>/</filename>, and then finally uses
- <literal>mount(MS_MOVE)</literal> to make the deployment root appear to be the
- root filesystem before telling systemd to switch root.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- A further specific note regarding <command>sysvinit</command>:
- OSTree used to support recording device files such the
- <filename>/dev/initctl</filename> FIFO, but no longer does.
- It's recommended to just patch your initramfs to create this at
- boot.
- </para>
- </chapter>
-
- <chapter id="lib-passwd">
- <title>/usr/lib/passwd</title>
- <para>
- Unlike traditional package systems, OSTree trees contain
- <emphasis>numeric</emphasis> uid and gids. Furthermore, it does
- not have a <literal>%post</literal> type mechanism where
- <filename>useradd</filename> could be invoked. 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 <filename>/etc/passwd</filename>. The core problem is that
- if you add a user to the system for a daemon, the OSTree upgrade
- process for <filename class='directory'>/etc</filename> will
- simply notice that because <filename>/etc/passwd</filename>
- differs from the previous default, it will keep the modified
- config file, and your new OS user will not be visible.
- </para>
- <para>
- The solution chosen for the <ulink
- url="https://live.gnome.org/Projects/GnomeContinuous">gnome-continuous</ulink>
- operating system is to create
- <filename>/usr/lib/passwd</filename>, and to include a NSS
- module <ulink
- url="https://github.com/aperezdc/nss-altfiles">nss-altfiles</ulink>
- which instructs glibc to read from it. Then, the build system
- places all system users there, freeing up
- <filename>/etc/passwd</filename> to be purely a database of
- local users. See also a more recent effort from <ulink
- url="http://0pointer.de/blog/projects/stateless.html">Systemd
- stateless</ulink>.
- </para>
- </chapter>
-
- <chapter id="adapting-package-manager">
- <title>Adapting existing package managers</title>
- <para>
- 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 <filename
- class='directory'>/</filename>. This section will use examples
- from both <command>dpkg</command> and <command>rpm</command> as
- the author has familiarity with both; but the abstract concepts
- should apply to most traditional package managers.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- Many package managers store their state in <filename
- class='directory'>/var</filename>; but since in the OSTree model
- that directory is shared between independent versions, the
- package database must first be found in the per-deployment
- <filename class='directory'>/usr</filename> 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 <filename
- class='directory'>/var</filename> location if the one in
- <filename class='directory'>/usr</filename> is not found.
- </para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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
- <emphasis>layering</emphasis> the composed filesystem tree of
- these new packages on top. A command lke this: <command>ostree
- commit -b osname/releasename/description
- --tree=ref=<replaceable>osname/releasenamename/description</replaceable>
- --tree=dir=/var/tmp/newpackages.13A8D0/</command> will create a
- new commit in the
- <replaceable>osname/releasename/description</replaceable>
- 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.
- </para>
-
- <para>
- Then to actually deploy this tree for the next boot:
- <command>ostree admin deploy
- <replaceable>osname/releasenamename/description</replaceable></command>
- </para>
-
- </chapter>
-
-</part>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-<!ENTITY version SYSTEM "../version.xml">
-]>
-<part id="atomic-upgrades">
- <title>Atomic Upgrades</title>
- <chapter id="upgrades-intro">
- <title>You can turn off the power anytime you want...</title>
- <para>
- 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.
- </para>
- </chapter>
-
- <chapter id="simple-http">
- <title>Simple upgrades via HTTP</title>
- <para>
- 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 <filename
- class='extension'>.origin</filename> file for the deployment.
- The command <command>ostree admin upgrade</command> implements
- this.
- </para>
-
- <para>
- To begin a simple upgrade, OSTree fetches the contents of the
- ref from the remote server. Suppose we're tracking a ref named
- <literal>exampleos/buildmaster/x86_64-runtime</literal>.
- OSTree fetches the URL
- <literal>http://<replaceable>example.com</replaceable>/repo/refs/exampleos/buildmaster/x86_64-runtime</literal>,
- which contains a SHA256 checksum. This determines the tree to
- deploy, and <filename class='directory'>/etc</filename> will be
- merged from currently booted tree.
- </para>
-
- <para>
- 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 <filename
- class='directory'>/ostree/repo/objects/</filename>.
- </para>
-
- <para>
- Once the pull is complete, we have all the objects locally
- we need to perform a deployment.
- </para>
- </chapter>
-
- <chapter id="package-manager">
- <title>Upgrades via external tools (e.g. package managers)</title>
-
- <para>
- 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.
- </para>
-
- <para>
- At a practical level, most package managers today
- (<command>dpkg</command> and <command>rpm</command>) 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: <xref linkend="adapting-existing"/>.
- </para>
-
- <para>
- 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.
- </para>
- </chapter>
-
- <chapter id="deployment-dir">
- <title>Assembling a new deployment directory</title>
- <para>
- Given a commit to deploy, OSTree first allocates a directory for
- it. This is of the form <filename
- class='directory'>/boot/loader/entries/ostree-<replaceable>osname</replaceable>-<replaceable>checksum</replaceable>.<replaceable>serial</replaceable>.conf</filename>.
- The <replaceable>serial</replaceable> 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 <filename class='directory'>/etc</filename>
- that we do not want to use or overwrite.
- </para>
-
- <para>
- Now that we have a deployment directory, a 3-way merge is
- performed between the (by default) currently booted deployment's
- <filename class='directory'>/etc</filename>, its default
- configuration, and the new deployment (based on its <filename
- class='directory'>/usr/etc</filename>).
- </para>
- </chapter>
-
- <chapter id="swapping-boot">
- <title>Atomically swapping boot configuration</title>
- <para>
- 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".
- </para>
-
- <para>
- 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.
- </para>
-
- <simplesect id="bootversion">
- <title>The bootversion</title>
- <para>
- OSTree allows swapping between boot configurations by
- implementing the "swapped directory pattern" in <filename
- class='directory'>/boot</filename>. This means it is a
- symbolic link to one of two directories <filename
- class='directory'>/ostree/boot.<replaceable>[0|1]</replaceable></filename>.
- To swap the contents atomically, if the current version is
- <literal>0</literal>, we create <filename
- class='directory'>/ostree/boot.1</filename>, populate it with
- the new contents, then atomically swap the symbolic link. Finally,
- the old contents can be garbage collected at any point.
- </para>
- </simplesect>
-
- <simplesect id="ostree-bootversion">
- <title>The /ostree/boot directory</title>
- <para>
- 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 <filename class='directory'>/boot</filename> may be on
- a separate medium such as flash storage not optimized for
- significant amounts of write traffic.
- </para>
-
- <para>
- To implement this, OSTree also maintains the directory
- <filename
- class='directory'>/ostree/boot.<replaceable>bootversion</replaceable></filename>,
- which is a set of symbolic links to the deployment
- directories. The <replaceable>bootversion</replaceable> here
- must match the version of <filename
- class='directory'>/boot</filename>. However, in order to
- allow atomic transitions of <emphasis>this</emphasis>
- directory, this is also a swapped directory, so just like
- <filename class='directory'>/boot</filename>, it has a version
- of <literal>0</literal> or <literal>1</literal> appended.
- </para>
-
- <para>
- Each bootloader entry has a special <literal>ostree=</literal>
- argument which refers to one of these symbolic links. This is
- parsed at runtime in the initramfs.
- </para>
-
- </simplesect>
-
- </chapter>
-
-</part>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-<!ENTITY version SYSTEM "../version.xml">
-]>
-<part id="deployment">
- <title>Deployments</title>
- <chapter id="deployment-intro">
- <title>Overview</title>
- <para>
- 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 <command>ostree
- admin</command>). The core content of these operating systems
- are treated as read-only, but they transparently share storage.
- </para>
-
- <para>
- A deployment is physically located at a path of the form
- <filename
- class='directory'>/ostree/deploy/<replaceable>osname</replaceable>/deploy/<replaceable>checksum</replaceable></filename>.
- OSTree is designed to boot directly into exactly one deployment
- at a time; each deployment is intended to be a target for
- <literal>chroot()</literal> or equivalent.
- </para>
-
- </chapter>
-
- <chapter id="deployment-osname">
- <title>"osname": Group of deployments that share /var</title>
- <para>
- Each deployment is grouped in exactly one "osname". From
- above, you can see that an osname is physically represented in
- the <filename
- class='directory'>/ostree/deploy/<replaceable>osname</replaceable></filename>
- directory. For example, OSTree can allow parallel installing
- Debian in <filename
- class='directory'>/ostree/deploy/debian</filename> and Red Hat
- Enterprise Linux in <filename
- class='directory'>/ostree/deploy/rhel</filename> (subject to
- operating system support, present released versions of these
- operating systems may not support this).
- </para>
-
- <para>
- Each osname has exactly one copy of the traditional Unix
- <filename class='directory'>/var</filename>, stored physically
- in <filename
- class='directory'>/ostree/deploy/<replaceable>osname</replaceable>/var</filename>.
- OSTree provides support tools for <command>systemd</command>
- to create a Linux bind mount that ensures the booted
- deployment sees the shared copy of <filename
- class='directory'>/var</filename>.
- </para>
-
- <para>
- OSTree does not touch the contents of <filename
- class='directory'>/var</filename>. Operating system components
- such as daemon services are required to create any directories
- they require there at runtime (e.g. <filename
- class='directory'>/var/cache/<replaceable>daemonname</replaceable></filename>),
- and to manage upgrading data formats inside those directories.
- </para>
- </chapter>
-
- <chapter id="deployment-contents">
- <title>Contents of a deployment</title>
- <para>
- A deployment begins with a specific commit (represented as a
- SHA256 hash) in the OSTree repository in <filename
- class='directory'>/ostree/repo</filename>. 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.
- </para>
-
- <para>
- First, the tree must include a kernel stored as <filename
- class='directory'>/boot/vmlinuz-<replaceable>checksum</replaceable></filename>.
- 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 <filename
- class='directory'>/boot/initramfs-<replaceable>checksum</replaceable></filename>.
- 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.
- </para>
-
- <para>
- The deployment should not have a traditional UNIX <filename
- class='directory'>/etc</filename>; instead, it should include
- <filename class='directory'>/usr/etc</filename>. This is the
- "default configuration". When OSTree creates a deployment, it
- performs a 3-way merge using the <emphasis>old</emphasis>
- default configuration, the active system's <filename
- class='directory'>/etc</filename>, and the new default
- configuration. In the final filesystem tree for a deployment
- then, <filename class='directory'>/etc</filename> is a regular
- writable directory.
- </para>
-
- <para>
- Besides the exceptions of <filename
- class='directory'>/var</filename> and <filename
- class='directory'>/etc</filename> 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 <filename
- class='directory'>/usr</filename>, but this is not a hard
- requirement.
- </para>
-
- <para>
- Finally, a deployment may have a <filename
- class='extension'>.origin</filename> file, stored next to its
- directory. This file tells <command>ostree admin
- upgrade</command> 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.
- </para>
-
- </chapter>
-
- <chapter id="managing-boot">
- <title>The system /boot</title>
- <para>
- While OSTree parallel installs deployments cleanly inside the
- <filename class='directory'>/ostree</filename> directory,
- ultimately it has to control the system's <filename
- class='directory'>/boot</filename> directory. The way this
- works is via the <ulink
- url="http://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/">boot
- loader specification</ulink>, which is a standard for
- bootloader-independent drop-in configuration files.
- </para>
- <para>
- When a tree is deployed, it will have a configuration file
- generated of the form <filename
- class='directory'>/boot/loader/entries/ostree-<replaceable>osname</replaceable>-<replaceable>checksum</replaceable>.<replaceable>serial</replaceable>.conf</filename>.
- This configuration file will include a special
- <literal>ostree=</literal> kernel argument that allows the
- initramfs to find (and <literal>chroot()</literal> into) the
- specified deployment.
- </para>
-
- <para>
- At present, not all bootloaders implement the BootLoaderSpec,
- so OSTree contains code for some of these to regenerate native
- config files (such as
- <filename>/boot/syslinux/syslinux.conf</filename> based on the
- entries.
- </para>
-
- </chapter>
-</part>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
-[
- <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
- <!ENTITY version SYSTEM "version.xml">
-]>
-<book id="index">
- <bookinfo>
- <title>OSTree Manual</title>
- <releaseinfo>for OSTree &version;</releaseinfo>
- </bookinfo>
-
- <xi:include href="overview.xml"/>
- <xi:include href="repo.xml"/>
- <xi:include href="deployment.xml"/>
- <xi:include href="atomic-upgrades.xml"/>
- <xi:include href="adapting-existing.xml"/>
-
- <chapter xml:id="reference">
- <title>API Reference</title>
- <xi:include href="xml/libostree-core.xml"/>
- <xi:include href="xml/libostree-repo.xml"/>
- <xi:include href="xml/libostree-mutable-tree.xml"/>
- <xi:include href="xml/libostree-sysroot.xml"/>
- <xi:include href="xml/libostree-async-progress.xml"/>
- <xi:include href="xml/libostree-sepolicy.xml"/>
- <xi:include href="xml/libostree-sysroot-upgrader.xml"/>
- <xi:include href="xml/libostree-gpg-verify-result.xml"/>
- <xi:include href="xml/libostree-bootconfig-parser.xml"/>
- <xi:include href="xml/libostree-chain-input-stream.xml"/>
- <xi:include href="xml/libostree-checksum-input-stream.xml"/>
- <xi:include href="xml/libostree-deployment.xml"/>
- <xi:include href="xml/libostree-diff.xml"/>
- <xi:include href="xml/libostree-repo-file.xml"/>
-
- <index id="api-index-full">
- <title>API Index</title>
- <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
- </index>
-
- </chapter>
-</book>
+++ /dev/null
-<SECTION>
-<FILE>libostree-async-progress</FILE>
-OstreeAsyncProgress
-ostree_async_progress_new
-ostree_async_progress_new_and_connect
-ostree_async_progress_get_status
-ostree_async_progress_get_uint
-ostree_async_progress_get_uint64
-ostree_async_progress_set_status
-ostree_async_progress_set_uint
-ostree_async_progress_set_uint64
-ostree_async_progress_finish
-<SUBSECTION Standard>
-OSTREE_ASYNC_PROGRESS
-OSTREE_IS_ASYNC_PROGRESS
-OSTREE_TYPE_ASYNC_PROGRESS
-OSTREE_ASYNC_PROGRESS_CLASS
-OSTREE_IS_ASYNC_PROGRESS_CLASS
-OSTREE_ASYNC_PROGRESS_GET_CLASS
-OstreeAsyncProgressClass
-ostree_async_progress_get_type
-</SECTION>
-
-<SECTION>
-<FILE>libostree-bootconfig-parser</FILE>
-OstreeBootconfigParser
-ostree_bootconfig_parser_new
-ostree_bootconfig_parser_clone
-ostree_bootconfig_parser_parse
-ostree_bootconfig_parser_write
-ostree_bootconfig_parser_set
-ostree_bootconfig_parser_get
-<SUBSECTION Standard>
-OSTREE_BOOTCONFIG_PARSER
-OSTREE_IS_BOOTCONFIG_PARSER
-OSTREE_TYPE_BOOTCONFIG_PARSER
-ostree_bootconfig_parser_get_type
-</SECTION>
-
-<SECTION>
-<FILE>libostree-chain-input-stream</FILE>
-OstreeChainInputStream
-ostree_chain_input_stream_new
-<SUBSECTION Standard>
-OSTREE_CHAIN_INPUT_STREAM
-OSTREE_IS_CHAIN_INPUT_STREAM
-OSTREE_TYPE_CHAIN_INPUT_STREAM
-OSTREE_CHAIN_INPUT_STREAM_CLASS
-OSTREE_IS_CHAIN_INPUT_STREAM_CLASS
-OSTREE_CHAIN_INPUT_STREAM_GET_CLASS
-OstreeChainInputStreamClass
-OstreeChainInputStreamPrivate
-ostree_chain_input_stream_get_type
-</SECTION>
-
-<SECTION>
-<FILE>libostree-checksum-input-stream</FILE>
-OstreeChecksumInputStream
-ostree_checksum_input_stream_new
-<SUBSECTION Standard>
-OSTREE_CHECKSUM_INPUT_STREAM
-OSTREE_IS_CHECKSUM_INPUT_STREAM
-OSTREE_TYPE_CHECKSUM_INPUT_STREAM
-OSTREE_CHECKSUM_INPUT_STREAM_CLASS
-OSTREE_IS_CHECKSUM_INPUT_STREAM_CLASS
-OSTREE_CHECKSUM_INPUT_STREAM_GET_CLASS
-OstreeChecksumInputStreamClass
-OstreeChecksumInputStreamPrivate
-ostree_checksum_input_stream_get_type
-</SECTION>
-
-<SECTION>
-<FILE>libostree-core</FILE>
-OSTREE_MAX_METADATA_SIZE
-OSTREE_MAX_METADATA_WARN_SIZE
-OSTREE_MAX_RECURSION
-OstreeObjectType
-OSTREE_OBJECT_TYPE_IS_META
-OSTREE_OBJECT_TYPE_LAST
-OSTREE_DIRMETA_GVARIANT_STRING
-OSTREE_DIRMETA_GVARIANT_FORMAT
-OSTREE_FILEMETA_GVARIANT_STRING
-OSTREE_FILEMETA_GVARIANT_FORMAT
-OSTREE_TREE_GVARIANT_STRING
-OSTREE_TREE_GVARIANT_FORMAT
-OSTREE_COMMIT_GVARIANT_STRING
-OSTREE_COMMIT_GVARIANT_FORMAT
-OSTREE_SUMMARY_GVARIANT_STRING
-OSTREE_SUMMARY_GVARIANT_FORMAT
-ostree_metadata_variant_type
-ostree_validate_checksum_string
-ostree_checksum_to_bytes
-ostree_checksum_to_bytes_v
-ostree_checksum_from_bytes
-ostree_checksum_from_bytes_v
-ostree_checksum_inplace_from_bytes
-ostree_checksum_inplace_to_bytes
-ostree_checksum_bytes_peek
-ostree_checksum_bytes_peek_validate
-ostree_cmp_checksum_bytes
-ostree_validate_rev
-ostree_parse_refspec
-ostree_checksum_update_meta
-ostree_object_type_to_string
-ostree_object_type_from_string
-ostree_hash_object_name
-ostree_object_name_serialize
-ostree_object_name_deserialize
-ostree_object_to_string
-ostree_object_from_string
-ostree_content_stream_parse
-ostree_content_file_parse
-ostree_raw_file_to_content_stream
-ostree_checksum_file_from_input
-ostree_checksum_file
-ostree_checksum_file_async
-ostree_checksum_file_async_finish
-ostree_create_directory_metadata
-ostree_validate_structureof_objtype
-ostree_validate_structureof_csum_v
-ostree_validate_structureof_checksum_string
-ostree_validate_structureof_file_mode
-ostree_validate_structureof_commit
-ostree_validate_structureof_dirtree
-ostree_validate_structureof_dirmeta
-ostree_commit_get_parent
-ostree_commit_get_timestamp
-</SECTION>
-
-<SECTION>
-<FILE>libostree-deployment</FILE>
-OstreeDeployment
-ostree_deployment_hash
-ostree_deployment_equal
-ostree_deployment_new
-ostree_deployment_get_index
-ostree_deployment_get_osname
-ostree_deployment_get_deployserial
-ostree_deployment_get_csum
-ostree_deployment_get_bootcsum
-ostree_deployment_get_bootserial
-ostree_deployment_get_bootconfig
-ostree_deployment_get_origin
-ostree_deployment_set_index
-ostree_deployment_set_bootserial
-ostree_deployment_set_bootconfig
-ostree_deployment_set_origin
-ostree_deployment_clone
-<SUBSECTION Standard>
-OSTREE_DEPLOYMENT
-OSTREE_IS_DEPLOYMENT
-OSTREE_TYPE_DEPLOYMENT
-ostree_deployment_get_type
-</SECTION>
-
-<SECTION>
-<FILE>libostree-diff</FILE>
-OstreeDiffFlags
-OstreeDiffItem
-ostree_diff_item_ref
-ostree_diff_item_unref
-ostree_diff_dirs
-ostree_diff_print
-<SUBSECTION Standard>
-ostree_diff_item_get_type
-</SECTION>
-
-<SECTION>
-<FILE>libostree-gpg-verify-result</FILE>
-OstreeGpgVerifyResult
-OstreeGpgSignatureAttr
-ostree_gpg_verify_result_count_all
-ostree_gpg_verify_result_count_valid
-ostree_gpg_verify_result_lookup
-ostree_gpg_verify_result_get
-ostree_gpg_verify_result_get_all
-OstreeGpgSignatureFormatFlags
-ostree_gpg_verify_result_describe
-ostree_gpg_verify_result_describe_variant
-<SUBSECTION Standard>
-OSTREE_GPG_VERIFY_RESULT
-OSTREE_IS_GPG_VERIFY_RESULT
-OSTREE_TYPE_GPG_VERIFY_RESULT
-ostree_gpg_verify_result_get_type
-</SECTION>
-
-<SECTION>
-<FILE>libostree-mutable-tree</FILE>
-OstreeMutableTree
-ostree_mutable_tree_new
-ostree_mutable_tree_set_metadata_checksum
-ostree_mutable_tree_get_metadata_checksum
-ostree_mutable_tree_set_contents_checksum
-ostree_mutable_tree_get_contents_checksum
-ostree_mutable_tree_replace_file
-ostree_mutable_tree_ensure_dir
-ostree_mutable_tree_lookup
-ostree_mutable_tree_ensure_parent_dirs
-ostree_mutable_tree_walk
-ostree_mutable_tree_get_subdirs
-ostree_mutable_tree_get_files
-<SUBSECTION Standard>
-OSTREE_MUTABLE_TREE
-OSTREE_IS_MUTABLE_TREE
-OSTREE_TYPE_MUTABLE_TREE
-OSTREE_MUTABLE_TREE_CLASS
-OSTREE_IS_MUTABLE_TREE_CLASS
-OSTREE_MUTABLE_TREE_GET_CLASS
-OstreeMutableTreeClass
-ostree_mutable_tree_get_type
-</SECTION>
-
-<SECTION>
-<FILE>libostree-repo</FILE>
-OstreeRepo
-OstreeRepoMode
-ostree_repo_mode_from_string
-ostree_repo_new
-ostree_repo_new_for_sysroot_path
-ostree_repo_new_default
-ostree_repo_open
-ostree_repo_set_disable_fsync
-ostree_repo_get_disable_fsync
-ostree_repo_is_system
-ostree_repo_is_writable
-ostree_repo_create
-ostree_repo_get_path
-ostree_repo_get_mode
-ostree_repo_get_config
-ostree_repo_copy_config
-ostree_repo_remote_add
-ostree_repo_remote_delete
-OstreeRepoRemoteChange
-ostree_repo_remote_change
-ostree_repo_remote_list
-ostree_repo_remote_get_url
-ostree_repo_remote_get_gpg_verify
-ostree_repo_remote_get_gpg_verify_summary
-ostree_repo_remote_gpg_import
-ostree_repo_remote_fetch_summary
-ostree_repo_get_parent
-ostree_repo_write_config
-OstreeRepoTransactionStats
-ostree_repo_scan_hardlinks
-ostree_repo_prepare_transaction
-ostree_repo_commit_transaction
-ostree_repo_abort_transaction
-ostree_repo_transaction_set_refspec
-ostree_repo_transaction_set_ref
-ostree_repo_set_ref_immediate
-ostree_repo_has_object
-ostree_repo_write_metadata
-ostree_repo_write_metadata_async
-ostree_repo_write_metadata_finish
-ostree_repo_write_content
-ostree_repo_write_metadata_trusted
-ostree_repo_write_metadata_stream_trusted
-ostree_repo_write_content_trusted
-ostree_repo_write_content_async
-ostree_repo_write_content_finish
-ostree_repo_resolve_rev
-ostree_repo_list_refs
-ostree_repo_remote_list_refs
-ostree_repo_load_variant
-ostree_repo_load_commit
-ostree_repo_load_variant_if_exists
-ostree_repo_load_file
-ostree_repo_load_object_stream
-ostree_repo_query_object_storage_size
-ostree_repo_import_object_from
-ostree_repo_delete_object
-OstreeRepoCommitFilterResult
-OstreeRepoCommitFilter
-OstreeRepoCommitModifier
-OstreeRepoCommitModifierFlags
-ostree_repo_commit_modifier_new
-OstreeRepoCommitModifierXattrCallback
-ostree_repo_commit_modifier_set_xattr_callback
-ostree_repo_commit_modifier_set_sepolicy
-ostree_repo_commit_modifier_set_devino_cache
-ostree_repo_commit_modifier_ref
-ostree_repo_commit_modifier_unref
-ostree_repo_devino_cache_new
-ostree_repo_devino_cache_ref
-ostree_repo_devino_cache_unref
-ostree_repo_write_directory_to_mtree
-ostree_repo_write_dfd_to_mtree
-ostree_repo_write_archive_to_mtree
-ostree_repo_write_mtree
-ostree_repo_write_commit
-ostree_repo_write_commit_with_time
-ostree_repo_read_commit_detached_metadata
-ostree_repo_write_commit_detached_metadata
-OstreeRepoCheckoutMode
-OstreeRepoCheckoutOverwriteMode
-ostree_repo_checkout_tree
-ostree_repo_checkout_tree_at
-ostree_repo_checkout_gc
-ostree_repo_read_commit
-OstreeRepoListObjectsFlags
-OSTREE_REPO_LIST_OBJECTS_VARIANT_TYPE
-ostree_repo_list_objects
-ostree_repo_list_commit_objects_starting_with
-ostree_repo_list_static_delta_names
-OstreeStaticDeltaGenerateOpt
-ostree_repo_static_delta_generate
-ostree_repo_static_delta_execute_offline
-ostree_repo_traverse_new_reachable
-ostree_repo_traverse_commit
-ostree_repo_traverse_commit_union
-OstreeRepoPruneFlags
-ostree_repo_prune
-OstreeRepoPullFlags
-ostree_repo_pull
-ostree_repo_pull_one_dir
-ostree_repo_pull_with_options
-ostree_repo_pull_default_console_progress_changed
-ostree_repo_sign_commit
-ostree_repo_append_gpg_signature
-ostree_repo_verify_commit
-ostree_repo_verify_commit_ext
-ostree_repo_verify_summary
-ostree_repo_regenerate_summary
-<SUBSECTION Standard>
-OSTREE_REPO
-OSTREE_IS_REPO
-OSTREE_TYPE_REPO
-ostree_repo_get_type
-ostree_repo_commit_modifier_get_type
-ostree_repo_transaction_stats_get_type
-</SECTION>
-
-<SECTION>
-<FILE>libostree-repo-file</FILE>
-OstreeRepoFile
-ostree_repo_file_ensure_resolved
-ostree_repo_file_get_xattrs
-ostree_repo_file_get_repo
-ostree_repo_file_get_root
-ostree_repo_file_make_empty_tree
-ostree_repo_file_tree_set_metadata
-ostree_repo_file_tree_get_contents_checksum
-ostree_repo_file_tree_get_metadata_checksum
-ostree_repo_file_tree_get_contents
-ostree_repo_file_tree_get_metadata
-ostree_repo_file_get_checksum
-ostree_repo_file_tree_find_child
-ostree_repo_file_tree_query_child
-<SUBSECTION Standard>
-OSTREE_REPO_FILE
-OSTREE_IS_REPO_FILE
-OSTREE_TYPE_REPO_FILE
-OSTREE_REPO_FILE_CLASS
-OSTREE_IS_REPO_FILE_CLASS
-OSTREE_REPO_FILE_GET_CLASS
-OstreeRepoFileClass
-ostree_repo_file_get_type
-</SECTION>
-
-<SECTION>
-<FILE>libostree-sepolicy</FILE>
-OstreeSePolicy
-ostree_sepolicy_new
-ostree_sepolicy_get_path
-ostree_sepolicy_get_name
-ostree_sepolicy_get_label
-OstreeSePolicyRestoreconFlags
-ostree_sepolicy_restorecon
-<SUBSECTION Standard>
-OSTREE_SEPOLICY
-OSTREE_IS_SEPOLICY
-OSTREE_TYPE_SEPOLICY
-ostree_sepolicy_get_type
-</SECTION>
-
-<SECTION>
-<FILE>libostree-sysroot</FILE>
-OstreeSysroot
-ostree_sysroot_new
-ostree_sysroot_new_default
-ostree_sysroot_get_path
-ostree_sysroot_load
-ostree_sysroot_lock
-ostree_sysroot_try_lock
-ostree_sysroot_lock_async
-ostree_sysroot_lock_finish
-ostree_sysroot_unlock
-ostree_sysroot_get_fd
-ostree_sysroot_ensure_initialized
-ostree_sysroot_get_bootversion
-ostree_sysroot_get_subbootversion
-ostree_sysroot_get_deployments
-ostree_sysroot_get_booted_deployment
-ostree_sysroot_get_deployment_directory
-ostree_sysroot_get_deployment_origin_path
-ostree_sysroot_cleanup
-ostree_sysroot_prepare_cleanup
-ostree_sysroot_get_repo
-ostree_sysroot_deployment_set_kargs
-ostree_sysroot_write_deployments
-ostree_sysroot_deploy_tree
-ostree_sysroot_get_merge_deployment
-ostree_sysroot_origin_new_from_refspec
-OstreeSysrootSimpleWriteDeploymentFlags
-ostree_sysroot_simple_write_deployment
-<SUBSECTION Standard>
-OSTREE_SYSROOT
-OSTREE_IS_SYSROOT
-OSTREE_TYPE_SYSROOT
-ostree_sysroot_get_type
-</SECTION>
-
-<SECTION>
-<FILE>libostree-sysroot-upgrader</FILE>
-OstreeSysrootUpgrader
-ostree_sysroot_upgrader_new
-ostree_sysroot_upgrader_new_for_os
-OstreeSysrootUpgraderFlags
-ostree_sysroot_upgrader_new_for_os_with_flags
-ostree_sysroot_upgrader_get_origin
-ostree_sysroot_upgrader_dup_origin
-ostree_sysroot_upgrader_set_origin
-ostree_sysroot_upgrader_get_origin_description
-ostree_sysroot_upgrader_check_timestamps
-OstreeSysrootUpgraderPullFlags
-ostree_sysroot_upgrader_pull
-ostree_sysroot_upgrader_pull_one_dir
-ostree_sysroot_upgrader_deploy
-<SUBSECTION Standard>
-OSTREE_SYSROOT_UPGRADER
-OSTREE_IS_SYSROOT_UPGRADER
-OSTREE_TYPE_SYSROOT_UPGRADER
-ostree_sysroot_upgrader_get_type
-ostree_sysroot_upgrader_flags_get_type
-</SECTION>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-<!ENTITY version SYSTEM "../version.xml">
-]>
-<part id="overview">
- <title>OSTree Overview</title>
- <chapter id="ostree-intro">
- <title>Introduction</title>
- <para>
- OSTree an upgrade system for Linux-based operating systems that
- performs atomic upgrades of complete filesystem trees. It is
- not a package system; rather, it is intended to complement them.
- A primary model is composing packages on a server, and then
- replicating them to clients.
- </para>
-
- <para>
- The underlying architecture might be summarized as "git for
- operating system binaries". It operates in userspace, and will
- work on top of any Linux filesystem. At its core is a git-like
- content-addressed object store, and layered on top of that is
- bootloader configuration, management of
- <filename>/etc</filename>, and other functions to perform an
- upgrade beyond just replicating files.
- </para>
-
- <para>
- You can use OSTree standalone in the pure replication model,
- but another approach is to add a package manager on top,
- thus creating a hybrid tree/package system.
- </para>
-
- </chapter>
-
- <chapter id="ostree-package-comparison">
- <title>Comparison with "package managers"</title>
- <para>
- 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.
- </para>
-
- <para>
- In contrast, OSTree only supports recording and deploying
- <emphasis>complete</emphasis> (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. Put another way, OSTree
- only handles delivery and deployment; you will likely still want
- to include inside each tree metadata about the individual
- components that went into the tree. For example, a system
- administrator may want to know what version of OpenSSL was
- included in your tree, so you should support the equivalent of
- <command>rpm -q</command> or <command>dpkg -L</command>.
- </para>
-
- <para>
- 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 <filename
- class='directory'>/var</filename> if they're system global, or
- <filename class='directory'>/home</filename> for per-user
- application installation. An example application mechanism is
- <ulink url="http://docker.io/">Docker</ulink>.
- </para>
-
- <para>
- However, it is entirely possible to use OSTree underneath a
- package system, where the contents of <filename
- class='directory'>/usr</filename> are computed on the client.
- For example, when installing a package, rather than changing the
- currently running filesystem, the package manager could assemble
- a new filesystem tree that layers the new packages on top of a
- base tree, 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.
- </para>
- </chapter>
-
- <chapter id="ostree-block-comparison">
- <title>Comparison with block/image replication</title>
- <para>
- 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 <emphasis>reliable</emphasis>
- and <emphasis>predictable</emphasis>.
- </para>
- <para>
- But unlike many default image-based deployments, OSTree supports
- exactly two persistent writable directories that are preserved
- across upgrades: <literal>/etc</literal> and
- <literal>/var</literal>.
- </para>
- <para>
- 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.
- </para>
- </chapter>
-
- <chapter id="ostree-atomic-parallel-installation">
- <title>Atomic transitions between parallel-installable read-only filesystem trees</title>
- <para>
- Another deeply fundamental difference between both package
- managers and image-based replication is that OSTree is
- designed to parallel-install <emphasis>multiple
- versions</emphasis> of multiple
- <emphasis>independent</emphasis> operating systems. OSTree
- relies on a new toplevel <filename
- class='directory'>ostree</filename> directory; it can in fact
- parallel install inside an existing OS or distribution
- occupying the physical <filename
- class='directory'>/</filename> root.
- </para>
- <para>
- On each client machine, there is an OSTree repository stored
- in <filename class='directory'>/ostree/repo</filename>, and a
- set of "deployments" stored in <filename
- class='directory'>/ostree/deploy/<replaceable>OSNAME</replaceable>/<replaceable>CHECKSUM</replaceable></filename>.
- 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.
- </para>
- <para>
- The model OSTree emphasizes is that the OS read-only content
- is kept in the classic Unix <filename
- class='directory'>/usr</filename>; it comes with code to
- create a Linux read-only bind mount to prevent inadvertent
- corruption. There is exactly one <filename
- class='directory'>/var</filename> 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.
- </para>
- <para>
- Finally, each deployment has its own writable copy of the
- configuration store <filename
- class='directory'>/etc</filename>. On upgrade, OSTree will
- perform a basic 3-way diff, and apply any local changes to the
- new copy, while leaving the old untouched.
- </para>
- </chapter>
-</part>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-<!ENTITY version SYSTEM "../version.xml">
-]>
-<part id="repository">
- <title>Anatomy of an OSTree repository</title>
- <chapter id="repository-intro">
- <title>Core object types and data model</title>
- <para>
- 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 <ulink
- url="http://git-scm.com/book/en/Git-Internals">Git
- Internals</ulink>, as this section will assume some knowledge of
- how git works.
- </para>
-
- <para>
- 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).
- </para>
-
- <simplesect id="commits">
- <title>Commit objects</title>
- <para>
- 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.
- </para>
- <para>
- 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.
- </para>
- </simplesect>
-
- <simplesect id="dirtree">
- <title>Dirtree objects</title>
- <para>
- 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.
- </para>
- </simplesect>
-
- <simplesect id="dirmeta">
- <title>Dirmeta objects</title>
- <para>
- 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.
- </para>
- </simplesect>
-
- <simplesect id="content">
- <title>Content objects</title>
- <para>
- Unlike the first three object types which are metadata,
- designed to be <literal>mmap()ed</literal>, 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.
- </para>
- </simplesect>
- </chapter>
-
- <chapter id="repository-types">
- <title>Repository types and locations</title>
-
- <para>
- Also unlike git, an OSTree repository can be in one of two
- separate modes: <literal>bare</literal> and
- <literal>archive-z2</literal>. 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 <literal>archive-z2</literal> mode is designed
- for serving via plain HTTP. Like tar files, it can be
- read/written by non-root users.
- </para>
-
- <para>
- On an OSTree-deployed system, the "system repository" is
- <filename class='directory'>/ostree/repo</filename>. It can be
- read by any uid, but only written by root. Unless the
- <literal>--repo</literal> argument is given to the
- <command>ostree</command> command, it will operate on the system
- repository.
- </para>
- </chapter>
-
- <chapter id="refs">
- <title>Refs</title>
- <para>
- 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
- <literal>gnome-ostree/buildmaster/x86_64-runtime</literal> and
- <literal>gnome-ostree/buildmaster/x86_64-devel-debug</literal>.
- 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.
- </para>
-
- <para>
- The <command>ostree</command> supports a simple syntax using the
- carat <literal>^</literal> to refer to the parent of a given
- commit. For example,
- <literal>gnome-ostree/buildmaster/x86_64-runtime^</literal>
- refers to the previous build, and
- <literal>gnome-ostree/buildmaster/x86_64-runtime^^</literal>
- refers to the one before that.
- </para>
- </chapter>
-</part>
projects / ostree.git / commitdiff