diff --git a/doc/Makefile.am b/doc/Makefile.am index 2748a70a..edb04843 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -78,6 +78,7 @@ content_files= \ repo.xml \ deployment.xml \ atomic-upgrades.xml \ + adapting-existing.xml \ $(NULL) # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded diff --git a/doc/adapting-existing.xml b/doc/adapting-existing.xml new file mode 100644 index 00000000..f6514791 --- /dev/null +++ b/doc/adapting-existing.xml @@ -0,0 +1,204 @@ + + +]> + + Adapating existing mainstream distributions + + System layout + + First, OSTree encourages systems to implement UsrMove. + This is simply to avoid the need for more bind mounts. By + default OSTree's dracut hook creates a read-only bind mount over + /usr; you can of course + generate individual bind-mounts for /bin, all the /lib variants, etc. So it is not + intended to be a hard requirement. + + + + The /sysroot directory is + a new OS-level directory that OSTree expects to use as a bind + mount target to the physical / root directory. Remember, + because by default the system is booted into a + chroot equivalent, there has to be some way + to refer to the actual physical root filesystem, and there is + precedent for this name in the initramfs context. This + directory must exist; for example, the OSTree tool at runtime + expects that /sysroot/ostree/repo refers to the + system repository. + + + + Because OSTree only preserves /var across upgrades, it is very + strongly recommended for systems which want to preserve + compatibility with the Filesystem Hierarchy + Standard to create the following symbolic links: + + + + /home to /var/home + + + + + /opt to /var/opt + + + + + /usr/local to /var/local + + + + + /mnt to /var/mnt + + + + + /tmp to /sysroot/tmp + + + + + + + Furthermore, since /var + is empty by default, your operating system will need to + dynamically create these directories at boot. A good way to do + this is using systemd-tmpfiles, if your OS + uses systemd. For example: + + + + + + + + + Booting and initramfs technology + + OSTree comes with optional dracut+systemd integration code that + parses the ostree= kernel command line + argument in the initramfs, and then sets up the read-only bind + mount on /usr, a bind + mount on the deployment's /sysroot to the physical /, and then finally uses + mount(MS_MOVE) to make the deployment root appear to be the + root filesystem before telling systemd to switch root. + + + + If you are not using dracut or systemd, using OSTree should still + be possible, but you will have to write the integration code. Patches + to support other initramfs technologies and init systems, if sufficiently + clean, will likely be accepted upstream. + + + + A further specific note regarding sysvinit: + OSTree used to support recording device files such the + /dev/initctl FIFO, but no longer does. + It's recommended to just patch your initramfs to create this at + boot. + + + + + Adapting existing package managers + + The largest endeavor is likely to be redesigning your + distribution's package manager to be on top of OSTree, + particularly if you want to keep compatibility with the "old + way" of installing into the physical /. This section will use examples + from both dpkg and rpm as + the author has familiarity with both; but the abstract concepts + should apply to most traditional package managers. + + + + There are many levels of possible integration; initially, we + will describe the most naive implementation which is the + simplest but also the least efficient. We will assume here that + the admin is booted into an OSTree-enabled system, and wants to + add a set of packages. + + + + Many package managers store their state in /var; but since in the OSTree model + that directory is shared between independent versions, the + package database must first be found in the per-deployment + /usr directory. It + becomes read-only; remember, all upgrades involve constructing a + new filesystem tree, so your package manager will also need to + create a copy of its database. Most likely, if you want to + continue supporting non-OSTree deployments, simply have your + package manager fall back to the legacy /var location if the one in + /usr is not found. + + + + To install a set of new packages (without removing any existing + ones), enumerate the set of packages in the currently booted + deployment, and perform dependency resolution to compute the + complete set of new packages. Download and unpack these new + packages to a temporary directory. + + + + Now, because we are merely installing new packages and not + removing anything, we can make the major optimization of reusing + our existing filesystem tree, and merely + layering the composed filesystem tree of + these new packages on top. A command lke this: ostree + commit -b osname/releasename/description + --tree=ref=osname/releasenamename/description + --tree=dir=/var/tmp/newpackages.13A8D0/ will create a + new commit in the + osname/releasename/description + branch. The OSTree SHA256 checksum of all the files in + /var/tmp/newpackages.13A8D0/ will be computed, but we will not + re-checksum the present existing tree. In this layering model, + earlier directories will take precedence, but files in later + layers will silently override earlier layers. + + + + Then to actually deploy this tree for the next boot: + ostree admin deploy + osname/releasenamename/description + + + + + diff --git a/doc/atomic-upgrades.xml b/doc/atomic-upgrades.xml index 9fb20304..1a1be839 100644 --- a/doc/atomic-upgrades.xml +++ b/doc/atomic-upgrades.xml @@ -82,24 +82,15 @@ "live" on the currently booted filesystem. The way they could work with OSTree is instead to take the list of installed packages in the currently booted tree, and compute a new - filesystem from that. + filesystem from that. A later chapter describes in more details + how this could work: . - The most basic implementation of this would be something like - taking the result of rpm -qa, and doing - yum --installroot=/var/tmp/newroot install - package1 - package2 .... Then, - ostree commit -b osname/localtree - --tree=dir=/var/tmp/newroot. This would checksum all - of the input files and store them in local /ostree/repo repository, creating - a new commit. - - - - Now, we can move on to deployment. + For the purposes of this section, let's assume that we have a + newly generated filesystem tree stored in the repo (which shares + storage with the existing booted tree). We can then move on to + checking it back out of the repo into a deployment. diff --git a/doc/ostree-docs.xml b/doc/ostree-docs.xml index cf953c13..ba6e7cdd 100644 --- a/doc/ostree-docs.xml +++ b/doc/ostree-docs.xml @@ -15,6 +15,7 @@ + API Reference