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