From 75cd17d9d9e75f06e67788c0db9315a353c0e913 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Sat, 17 Aug 2013 09:22:08 -0400 Subject: [PATCH] docs: Add an overview section, migrate some content from the wiki --- doc/Makefile.am | 8 +- doc/{libostree-docs.xml => ostree-docs.xml} | 4 +- ...stree-sections.txt => ostree-sections.txt} | 0 doc/overview.xml | 131 ++++++++++++++++++ 4 files changed, 139 insertions(+), 4 deletions(-) rename doc/{libostree-docs.xml => ostree-docs.xml} (90%) rename doc/{libostree-sections.txt => ostree-sections.txt} (100%) create mode 100644 doc/overview.xml diff --git a/doc/Makefile.am b/doc/Makefile.am index 38bc5ded..b5acad6f 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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: diff --git a/doc/libostree-docs.xml b/doc/ostree-docs.xml similarity index 90% rename from doc/libostree-docs.xml rename to doc/ostree-docs.xml index 5fdd3d8f..71561acc 100644 --- a/doc/libostree-docs.xml +++ b/doc/ostree-docs.xml @@ -7,10 +7,12 @@ ]> - libostree + OSTree Manual for OSTree &version; + + API Reference diff --git a/doc/libostree-sections.txt b/doc/ostree-sections.txt similarity index 100% rename from doc/libostree-sections.txt rename to doc/ostree-sections.txt diff --git a/doc/overview.xml b/doc/overview.xml new file mode 100644 index 00000000..2c8e9576 --- /dev/null +++ b/doc/overview.xml @@ -0,0 +1,131 @@ + + +]> + + OSTree Overview + + Introduction + + 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. + + + + While it takes over some of the roles of tradtional "package + managers" like dpkg and rpm, it is not 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. + + + + Comparison with "package managers" + + 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. + + + In contrast, OSTree only supports recording and deploying + complete (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. + + + 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. + + + 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. + + + + + Comparison with block/image replication + + 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 reliable + and predictable. + + + But unlike many default image-based deployments, OSTree + supports a persistent, writable /etc that + is preserved across upgrades. + + + 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. + + + + + Atomic transitions between parallel-installable read-only filesystem trees + + Another deeply fundamental difference between both package + managers and image-based replication is that OSTree is + designed to parallel-install multiple + versions of multiple + independent operating systems. OSTree + relies on a new toplevel ostree directory; it can in fact + parallel install inside an existing OS or distribution + occupying the physical / root. + + + On each client machine, there is an OSTree repository stored + in /ostree/repo, and a + set of "deployments" stored in /ostree/deploy/OSNAME/CHECKSUM. + 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. + + + The model OSTree emphasizes is that the OS read-only content + is kept in the classic Unix /usr; it comes with code to + create a Linux read-only bind mount to prevent inadvertent + corruption. There is exactly one /var 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. + + + Finally, each deployment has its own writable copy of the + configuration store /etc. On upgrade, OSTree will + perform a basic 3-way diff, and apply any local changes to the + new copy, while leaving the old untouched. + + + +