docs: Add an overview section, migrate some content from the wiki
This commit is contained in:
Colin Walters
parent
abe2320039
commit
75cd17d9d9
|
|
@ -25,7 +25,7 @@ NULL =
|
|||
AUTOMAKE_OPTIONS = 1.6
|
||||
|
||||
# The name of the module, e.g. 'glib'.
|
||||
DOC_MODULE=libostree
|
||||
DOC_MODULE=ostree
|
||||
|
||||
# The top-level SGML file. You can change this if you want to.
|
||||
DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
|
||||
|
|
@ -73,7 +73,9 @@ 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=$(NULL)
|
||||
content_files= \
|
||||
overview.xml \
|
||||
$(NULL)
|
||||
|
||||
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
|
||||
# These files must be listed here *and* in content_files
|
||||
|
|
@ -90,7 +92,7 @@ expand_content_files= \
|
|||
GTKDOC_LIBS=
|
||||
|
||||
# Hacks around gtk-doc brokenness for out of tree builds
|
||||
libostree-sections.txt: $(srcdir)/libostree-sections.txt
|
||||
ostree-sections.txt: $(srcdir)/ostree-sections.txt
|
||||
cp $< $@
|
||||
|
||||
version.xml:
|
||||
|
|
|
|||
|
|
@ -7,10 +7,12 @@
|
|||
]>
|
||||
<book id="index">
|
||||
<bookinfo>
|
||||
<title>libostree</title>
|
||||
<title>OSTree Manual</title>
|
||||
<releaseinfo>for OSTree &version;</releaseinfo>
|
||||
</bookinfo>
|
||||
|
||||
<xi:include href="overview.xml"/>
|
||||
|
||||
<chapter xml:id="reference">
|
||||
<title>API Reference</title>
|
||||
<xi:include href="xml/libostree-core.xml"/>
|
||||
|
|
@ -0,0 +1,131 @@
|
|||
<?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 is best summarized in a single sentence as "git for
|
||||
operating system binaries". At its core architecture is a
|
||||
userspace content-addressed filesystem, and layered on top of
|
||||
that is an administrative layer that is designed to atomically
|
||||
parallel install multiple bootable Unix-like operating systems.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
While it takes over some of the roles of tradtional "package
|
||||
managers" like dpkg and rpm, it is <emphasis>not</emphasis> a
|
||||
package system; nor is it a tool for managing full disk
|
||||
images. Instead, OSTree sits between those levels, offering a
|
||||
blend of the advantages (and disadvantages) of both.
|
||||
</para>
|
||||
|
||||
<simplesect 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.
|
||||
</para>
|
||||
<para>
|
||||
The OSTree core emphasizes replicating read-only trees via
|
||||
HTTP. It is designed for the model where a build server
|
||||
assembles one or more trees, and these are replicated to
|
||||
clients, which can choose between fully assembled (and
|
||||
hopefully tested) trees.
|
||||
</para>
|
||||
<para>
|
||||
However, it is entirely possible to use OSTree underneath a
|
||||
package system; For example, when installing a package, rather
|
||||
than mutating the currently running filesystem, the package
|
||||
manager could assemble a new filesystem tree that includes the
|
||||
new package, record it in the local OSTree repository, and
|
||||
then set it up for the next boot. To support this model,
|
||||
OSTree provides an (introspectable) C shared library.
|
||||
</para>
|
||||
</simplesect>
|
||||
|
||||
<simplesect 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 a persistent, writable <literal>/etc</literal> that
|
||||
is preserved across upgrades.
|
||||
</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 both a BTRFS disk and an XFS-on-LVM
|
||||
deployment. Note: OSTree will transparently take advantage of
|
||||
some BTRFS features if deployed on it.
|
||||
</para>
|
||||
</simplesect>
|
||||
|
||||
<simplesect 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>
|
||||
</simplesect>
|
||||
</chapter>
|
||||
</part>
|
||||
Loading…
Reference in New Issue