ostree/doc/overview.xml

<?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>