ostree/doc/deployment.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="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>