diff --git a/docs/manual/adapting-existing.md b/docs/manual/adapting-existing.md index 8509d48e..77746e94 100644 --- a/docs/manual/adapting-existing.md +++ b/docs/manual/adapting-existing.md @@ -23,7 +23,7 @@ deployment. Because OSTree only preserves `/var` across upgrades (each deployment's chroot directory will be garbage collected eventually), you will need to choose how to handle other -toplevel writable directories specified by the [Filesystem Hierarchy Standard](http://www.pathname.com/fhs/") +toplevel writable directories specified by the [Filesystem Hierarchy Standard](http://www.pathname.com/fhs/). Your operating system may of course choose not to support some of these such as `/usr/local`, but following is the recommended set: @@ -37,9 +37,9 @@ recommended set: - `/tmp` → `/sysroot/tmp` Furthermore, since `/var` is empty by default, your operating system -will need to dynamically create the targets of -these at boot. A good way to do this is using `systemd-tmpfiles`, if -your OS uses systemd. For example: +will need to dynamically create the *targets* of these at boot. A +good way to do this is using `systemd-tmpfiles`, if your OS uses +systemd. For example: ``` d /var/log/journal 0755 root root - @@ -64,10 +64,10 @@ d /run/media 0755 root root - Particularly note here the double indirection of `/home`. By default, each deployment will share the global toplevel `/home` directory on the physical root filesystem. It is then up to higher levels of -management tools to keep /etc/passwd or -equivalent synchronized between operating systems. Each deployment -can easily be reconfigured to have its own home directory set simply -by making `/var/home` a real directory. +management tools to keep `/etc/passwd` or equivalent synchronized +between operating systems. Each deployment can easily be reconfigured +to have its own home directory set simply by making `/var/home` a real +directory. ## Booting and initramfs technology @@ -144,11 +144,11 @@ these new packages on top. A command like this: ``` ostree commit -b osname/releasename/description ---tree=ref=$osname/releasename/description +--tree=ref=$osname/$releasename/$description --tree=dir=/var/tmp/newpackages.13A8D0/ ``` -will create a new commit in the `$osname/releasename/description` +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, @@ -156,4 +156,4 @@ 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/releasename/description` +`ostree admin deploy $osname/$releasename/$description` diff --git a/docs/manual/atomic-upgrades.md b/docs/manual/atomic-upgrades.md index fa576734..b5f398d6 100644 --- a/docs/manual/atomic-upgrades.md +++ b/docs/manual/atomic-upgrades.md @@ -18,7 +18,7 @@ implements this. To begin a simple upgrade, OSTree fetches the contents of the ref from the remote server. Suppose we're tracking a ref named `exampleos/buildmaster/x86_64-runtime`. OSTree fetches the URL -`http://$example.com/repo/refs/exampleos/buildmaster/x86_64-runtime`, +`http://example.com/repo/refs/exampleos/buildmaster/x86_64-runtime`, which contains a SHA256 checksum. This determines the tree to deploy, and `/etc` will be merged from currently booted tree. @@ -35,7 +35,7 @@ we need to perform a deployment. As mentioned in the introduction, OSTree is also designed to allow a model where filesystem trees are computed on the client. It is -completely agnostic as to how those trees are generated; hey could be +completely agnostic as to how those trees are generated; they could be computed with traditional packages, packages with post-deployment scripts on top, or built by developers directly from revision control locally, etc. @@ -58,7 +58,7 @@ Given a commit to deploy, OSTree first allocates a directory for it. This is of the form `/boot/loader/entries/ostree-$osname-$checksum.$serial.conf`. The `$serial` is normally 0, but if a given commit is deployed more than once, it will be incremented. -his is supported because the previous deployment may have +This is supported because the previous deployment may have configuration in `/etc` that we do not want to use or overwrite. Now that we have a deployment directory, a 3-way merge is @@ -94,7 +94,7 @@ collected at any point. ## The /ostree/boot directory -However, we want to optimize for the case where we the set of +However, we want to optimize for the case where the set of kernel/initramfs pairs is the same between both the old and new deployment lists. This happens when doing an upgrade that does not include the kernel; think of a simple translation update. OSTree @@ -106,11 +106,11 @@ automatically remount read-write just for the portion of time necessary to update the bootloader configuration. To implement this, OSTree also maintains the directory -`/ostree/boot.bootversion`, which is a set +`/ostree/boot.$bootversion`, which is a set of symbolic links to the deployment directories. The -bootversion here must match the version of +`$bootversion` here must match the version of `/boot`. However, in order to allow atomic transitions of -this directory, this is also a swapped directory, +*this* directory, this is also a swapped directory, so just like `/boot`, it has a version of `0` or `1` appended. Each bootloader entry has a special `ostree=` argument which refers to diff --git a/docs/manual/buildsystem-and-repos.md b/docs/manual/buildsystem-and-repos.md index 2da3d8d7..1f14b181 100644 --- a/docs/manual/buildsystem-and-repos.md +++ b/docs/manual/buildsystem-and-repos.md @@ -63,7 +63,7 @@ But let's discuss building our own. If you're just experimenting, it's quite easy to start with the command line. We'll assume for this purpose that you have a build process that outputs a directory tree - we'll call this tool `$pkginstallroot` (which could be `yum ---installroot` or `dbootstrap`, etc.). +--installroot` or `debootstrap`, etc.). Your initial prototype is going to look like: @@ -132,7 +132,7 @@ the desired version). Now, to construct our final tree: ``` -rm exampleos-build -rf +rm -rf exampleos-build for package in bash systemd; do ostree --repo=build-repo checkout -U --union exampleos/x86_64/${package} exampleos-build done diff --git a/docs/manual/deployment.md b/docs/manual/deployment.md index f1172959..dc77809c 100644 --- a/docs/manual/deployment.md +++ b/docs/manual/deployment.md @@ -54,9 +54,9 @@ to avoid computing checksums on the client by default. The deployment should not have a traditional UNIX `/etc`; instead, it should include `/usr/etc`. This is the "default configuration". When OSTree creates a deployment, it performs a 3-way merge using the -old default configuration, the active system's -`/etc`, and the new default configuration. In the final filesystem -tree for a deployment then, `/etc` is a regular writable directory. +*old* default configuration, the active system's `/etc`, and the new +default configuration. In the final filesystem tree for a deployment +then, `/etc` is a regular writable directory. Besides the exceptions of `/var` and `/etc` then, the rest of the contents of the tree are checked out as hard links into the @@ -87,4 +87,4 @@ deployment. At present, not all bootloaders implement the BootLoaderSpec, so OSTree contains code for some of these to regenerate native config -files (such as `/boot/syslinux/syslinux.conf` based on the entries. +files (such as `/boot/syslinux/syslinux.conf`) based on the entries. diff --git a/docs/manual/related-projects.md b/docs/manual/related-projects.md index 48bc3f1c..b53ba792 100644 --- a/docs/manual/related-projects.md +++ b/docs/manual/related-projects.md @@ -18,7 +18,7 @@ date, and relatively agnostic. Broadly speaking, projects in this area fall into two camps; either a tool to snapshot systems on the client side (dpkg/rpm + BTRFS/LVM), or a tool to compose on a server and replicate (ChromiumOS, Clear -Linux). OSTree is flexible enough to do both. +Linux). OSTree is flexible enough to do both. ## Combining dpkg/rpm + (BTRFS/LVM) diff --git a/docs/manual/repo.md b/docs/manual/repo.md index e8d94b4b..d3be549c 100644 --- a/docs/manual/repo.md +++ b/docs/manual/repo.md @@ -87,7 +87,7 @@ two different generated filesystem trees. In this example, the "runtime" tree contains just enough to run a basic system, and "devel-debug" contains all of the developer tools and debuginfo. -The `ostree` supports a simple syntax using the carat `^` to refer to +The `ostree` supports a simple syntax using the caret `^` to refer to the parent of a given commit. For example, `exampleos/buildmaster/x86_64-runtime^` refers to the previous build, and `exampleos/buildmaster/x86_64-runtime^^` refers to the one before