packaging/ostree
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

build: Rename doc/ -> apidoc/

Browse Source 
This is preparation for introducing a `mkdocs` manual under `doc/`
which should be significantly more useful for the world at large than
the minimal manual that exists there now.
This commit is contained in:
Colin Walters committed 2016-01-28 09:31:34 -05:00
1 parent 313b4720e8
commit 32c360b5a0
11 files changed
+4 -3
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

apidoc/.gitignore
+2
View File
@@ -0,0 +1,2 @@
ostree*.1
ostree*.5
apidoc/Makefile.am
+132
View File
@@ -0,0 +1,132 @@
# 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)
apidoc/adapting-existing.xml
+267
View File
@@ -0,0 +1,267 @@
<?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>
apidoc/atomic-upgrades.xml
+181
View File
@@ -0,0 +1,181 @@
<?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>
apidoc/deployment.xml
+158
View File
@@ -0,0 +1,158 @@
<?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>
apidoc/ostree-docs.xml
+43
View File
@@ -0,0 +1,43 @@
<?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>
apidoc/ostree-sections.txt
+435
View File
@@ -0,0 +1,435 @@
<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>
apidoc/overview.xml
+155
View File
@@ -0,0 +1,155 @@
<?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>
apidoc/repo.xml
+127
View File
@@ -0,0 +1,127 @@
<?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>