docs: Various updates and fixes

I went through the docs and cleaned some things up, fixed
some missing content, etc.

Also a patch to `xtask` to make it so that `cargo xtask manpages`
works even when $PWD is in `docs`.

Signed-off-by: Colin Walters <walters@verbum.org>

docs/src/SUMMARY.md

@@ -20,7 +20,8 @@
 - [`man bootc status`](man/bootc-status.md)
 - [`man bootc upgrade`](man/bootc-upgrade.md)
 - [`man bootc switch`](man/bootc-switch.md)
-- [`man bootc usroverlay`](man/bootc-usr-overlay.md)
+- [`man bootc rollback`](man/bootc-rollback.md)
+- [`man bootc usr-overlay`](man/bootc-usr-overlay.md)
 - [`man bootc-fetch-apply-updates.service`](man-md/bootc-fetch-apply-updates-service.md)
 
 # Using `bootc install`

docs/src/bootc-install.md

@@ -128,58 +128,7 @@ The bootc project aims to support generic/general-purpose operating
 systems and distributions that will ship unconfigured images. An
 unconfigured image does not have a default password or SSH key, etc.
 
-There are two fundamental ways to handle this:
-
-### Using cloud-init type flows
-
-Some operating systems may come with `cloud-init` or similar tools
-that know how to e.g. inject SSH keys or external configuration.
-
-Other tools in this space are:
-
-- [systemd-firstboot](https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html)
-- [gnome-initial-setup](https://gitlab.gnome.org/GNOME/gnome-initial-setup)
-
-The general idea here is that things like users, passwords and ssh keys
-are dynamically created on first boot (and in general managed per-system);
-the configuration comes from a place *external* to the image.
-
-### Injecting configuration into a custom image
-
-But a new super-power with `bootc` is that you can also easily
-create a derived container that injects your desired configuration,
-alongside any additional executable code (binaries, packages, scripts, etc).
-
-The expectation is that most operating systems will be designed such
-that user state i.e. `/root` and `/home` will be on a separate, persistent data store.
-For example, in the default ostree model, `/root` is `/var/roothome`
-and `/home` is `/var/home`. Content in `/var` cannot be shipped
-in the image - it is per machine state.
-
-#### Injecting SSH keys in a container image
-
-In the following example, we will configure OpenSSH to read the
-set of authorized keys for the root user from content
-that lives in `/usr` (i.e. is owned by the container image).
-We will also create a `/usr/etc-system` directory which is intentionally distinct
-from the default ostree `/etc` which may be locally writable.
-
-The `AuthorizedKeysFile` invocation below then configures sshd to look
-for keys in this location.
-
-```Dockerfile
-FROM <image>
-RUN mkdir -p /usr/etc-system/ && \
- echo 'AuthorizedKeysFile /usr/etc-system/%u.keys' >> /etc/ssh/sshd_config.d/30-auth-system.conf && \
- echo 'ssh-ed25519 AAAAC3Nza... root@example.com' > /usr/etc-system/root.keys && chmod 0600 /usr/etc-system/root.keys && \
- ostree container commit
-```
-
-A key point here is that now the set of authorized keys is "owned"
-by the container image - it will be read-only at runtime because
-the files are underneath `/usr`. To rotate or change the set of keys,
-one would build a new container image. Client systems using `bootc upgrade`
-will transactionally update to this new system state.
+For more information, see [Image building and configuration guidance](building/guidance.md).
 
 ## More advanced installation with `to-filesystem`
 

docs/src/man-md/bootc-fetch-apply-updates-service.md

@@ -1 +1,10 @@
 # man bootc-fetch-apply-updates.service
+
+This systemd service and associated `.timer` unit simply invoke
+`bootc upgrade --apply`. It is a minimal demonstration of
+an "upgrade agent".
+
+More information: [bootc-upgrade](../man/bootc-upgrade.md).
+
+The systemd unit is not enabled by default upstream, but it
+may be enabled in some operating systems.

docs/src/man/bootc-edit.md

@@ -40,4 +40,4 @@ Only changes to the \`spec\` section are honored.
 
 # VERSION
 
-v0.1.0
+v0.1.9

docs/src/man/bootc-install-print-configuration.md

@@ -31,4 +31,4 @@ string-valued filesystem name suitable for passing to \`mkfs.\$type\`.
 
 # VERSION
 
-v0.1.0
+v0.1.9

docs/src/man/bootc-install-to-disk.md

@@ -139,4 +139,4 @@ firmware will be skipped
 
 # VERSION
 
-v0.1.0
+v0.1.9

docs/src/man/bootc-install-to-existing-root.md

@@ -123,4 +123,4 @@ firmware will be skipped
 
 # VERSION
 
-v0.1.0
+v0.1.9

docs/src/man/bootc-install-to-filesystem.md

@@ -139,4 +139,4 @@ mounting. To override this, use \`\--root-mount-spec\`.
 
 # VERSION
 
-v0.1.0
+v0.1.9

docs/src/man/bootc-install.md

@@ -11,9 +11,23 @@ bootc-install - Install the running container to a target
 
 Install the running container to a target.
 
-This has two main sub-commands \`to-disk\` (which expects an empty block
-device) and \`to-filesystem\` which supports installation to an already
-extant filesystem.
+## Understanding installations
+
+OCI containers are effectively layers of tarballs with JSON for
+metadata; they cannot be booted directly. The \`bootc install\` flow is
+a highly opinionated method to take the contents of the container image
+and install it to a target block device (or an existing filesystem) in
+such a way that it can be booted.
+
+For example, a Linux partition table and filesystem is used, and the
+bootloader and kernel embedded in the container image are also prepared.
+
+A bootc installed container currently uses OSTree as a backend, and this
+sets it up such that a subsequent \`bootc upgrade\` can perform in-place
+updates.
+
+An installation is not simply a copy of the container filesystem, but
+includes other setup and metadata.
 
 # OPTIONS
 
@@ -51,4 +65,4 @@ bootc-install-help(8)
 
 # VERSION
 
-v0.1.0
+v0.1.9

docs/src/man/bootc-rollback.md

@@ -0,0 +1,41 @@
+# NAME
+
+bootc-rollback - Change the bootloader entry ordering; the deployment
+under \`rollback\` will be queued for the next boot, and the current
+will become rollback. If there is a \`staged\` entry (an unapplied,
+queued upgrade) then it will be discarded
+
+# SYNOPSIS
+
+**bootc-rollback** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\]
+
+# DESCRIPTION
+
+Change the bootloader entry ordering; the deployment under \`rollback\`
+will be queued for the next boot, and the current will become rollback.
+If there is a \`staged\` entry (an unapplied, queued upgrade) then it
+will be discarded.
+
+Note that absent any additional control logic, if there is an active
+agent doing automated upgrades (such as the default
+\`bootc-fetch-apply-updates.timer\` and associated \`.service\`) the
+change here may be reverted. Its recommended to only use this in concert
+with an agent that is in active control.
+
+A systemd journal message will be logged with
+\`MESSAGE_ID=26f3b1eb24464d12aa5e7b544a6b5468\` in order to detect a
+rollback invocation.
+
+# OPTIONS
+
+**-h**, **\--help**
+
+: Print help (see a summary with -h)
+
+**-V**, **\--version**
+
+: Print version
+
+# VERSION
+
+v0.1.9

docs/src/man/bootc-status.md

@@ -37,4 +37,4 @@ The exact API format is not currently declared stable.
 
 # VERSION
 
-v0.1.0
+v0.1.9

docs/src/man/bootc-switch.md

@@ -13,8 +13,17 @@ bootc-switch - Target a new container image reference to boot
 
 Target a new container image reference to boot.
 
-This operates in a very similar fashion to \`upgrade\`, but changes the
-container image reference instead.
+This is almost exactly the same operation as \`upgrade\`, but
+additionally changes the container image reference instead.
+
+## Usage
+
+A common pattern is to have a management agent control operating system
+updates via container image tags; for example,
+\`quay.io/exampleos/someuser:v1.0\` and
+\`quay.io/exampleos/someuser:v1.1\` where some machines are tracking
+\`:v1.0\`, and as a rollout progresses, machines can be switched to
+\`v:1.1\`.
 
 # OPTIONS
 
@@ -56,4 +65,4 @@ includes a default policy which requires signatures.
 
 # VERSION
 
-v0.1.0
+v0.1.9

docs/src/man/bootc-upgrade.md

@@ -22,7 +22,8 @@ upgrade \--apply\` verb which will automatically take action (rebooting)
 if the system has changed.
 
 However, in the future this is likely to change such that reboots
-outside of a \`bootc upgrade \--apply\` do \*not\* upgrade.
+outside of a \`bootc upgrade \--apply\` do \*not\* automatically apply
+the update.
 
 # OPTIONS
 
@@ -55,4 +56,4 @@ userspace-only restart.
 
 # VERSION
 
-v0.1.0
+v0.1.9

docs/src/man/bootc-usr-overlay.md

@@ -1,6 +1,6 @@
 # NAME
 
-bootc-usr-overlay - Add a transient writable overlayfs on \`/usr\` that
+bootc-usr-overlay - Adds a transient writable overlayfs on \`/usr\` that
 will be discarded on reboot
 
 # SYNOPSIS
@@ -9,19 +9,40 @@ will be discarded on reboot
 
 # DESCRIPTION
 
-Add a transient writable overlayfs on \`/usr\` that will be discarded on
-reboot
+Adds a transient writable overlayfs on \`/usr\` that will be discarded
+on reboot.
+
+(`usroverlay` is an alias for this command)
+
+## Use cases
+
+A common pattern is wanting to use tracing/debugging tools, such as
+\`strace\` that may not be in the base image. A system package manager
+such as \`apt\` or \`dnf\` can apply changes into this transient overlay
+that will be discarded on reboot.
+
+## /etc and /var
+
+However, this command has no effect on \`/etc\` and \`/var\` - changes
+written there will persist. It is common for package installations to
+modify these directories.
+
+## Unmounting
+
+Almost always, a system process will hold a reference to the open mount
+point. You can however invoke \`umount -l /usr\` to perform a \"lazy
+unmount\".
 
 # OPTIONS
 
 **-h**, **\--help**
 
-: Print help
+: Print help (see a summary with -h)
 
 **-V**, **\--version**
 
 : Print version
 
 # VERSION
 
-v0.1.0
+v0.1.9

docs/src/man/bootc.md

@@ -5,7 +5,8 @@ images
 
 # SYNOPSIS
 
-**bootc** \[**-h**\|**\--help**\] \<*subcommands*\>
+**bootc** \[**-h**\|**\--help**\] \[**-V**\|**\--version**\]
+\<*subcommands*\>
 
 # DESCRIPTION
 
@@ -25,6 +26,10 @@ Changes in \`/etc\` and \`/var\` persist.
 
 : Print help (see a summary with -h)
 
+**-V**, **\--version**
+
+: Print version
+
 # SUBCOMMANDS
 
 bootc-upgrade(8)
@@ -35,6 +40,13 @@ bootc-switch(8)
 
 : Target a new container image reference to boot
 
+bootc-rollback(8)
+
+: Change the bootloader entry ordering; the deployment under
+ \`rollback\` will be queued for the next boot, and the current will
+ become rollback. If there is a \`staged\` entry (an unapplied,
+ queued upgrade) then it will be discarded
+
 bootc-edit(8)
 
 : Apply full changes to the host specification
@@ -45,7 +57,7 @@ bootc-status(8)
 
 bootc-usr-overlay(8)
 
-: Add a transient writable overlayfs on \`/usr\` that will be
+: Adds a transient writable overlayfs on \`/usr\` that will be
  discarded on reboot
 
 bootc-install(8)
@@ -55,3 +67,7 @@ bootc-install(8)
 bootc-help(8)
 
 : Print this message or the help of the given subcommand(s)
+
+# VERSION
+
+v0.1.9

docs/src/upgrades.md

@@ -18,21 +18,34 @@ There is also an opinionated `bootc-fetch-apply-updates.timer` and corresponding
 service available in upstream for operating systems and distributions
 to enable.
 
+Man page: [bootc-upgrade](man/bootc-upgrade.md).
+
 ## Changing the container image source
 
 Another useful pattern to implement can be to use a management agent
-to invoke `bootc switch` to implement e.g. blue/green deployments,
+to invoke `bootc switch` (or declaratively via `bootc edit`)
+to implement e.g. blue/green deployments,
 where some hosts are rolled onto a new image independently of others.
 
 ```shell
-bootc switch quay.io/examplecorp/os-prod-blue:lastest
+bootc switch quay.io/examplecorp/os-prod-blue:latest
 ```
 
+`bootc switch` has the same effect as `bootc upgrade`; there is no
+semantic difference between the two other than changing the
+container image being tracked.
+
 This will preserve existing state in `/etc` and `/var` - for example,
 host SSH keys and home directories.
 
+Man page: [bootc-switch](man/bootc-switch.md).
+
 ## Rollback
 
-At the current time, bootc does not ship with an opinionated integrated
-rollback flow. However, bootc always maintains (by default) a
-`rollback` container image that is accessible via `bootc status`.
+There is a `bootc rollback` verb, and associated declarative interface
+accessible to tools via `bootc edit`. This will swap the bootloader
+ordering to the previous boot entry.
+
+Man page: [bootc-rollback](man/bootc-rollback.md).
+
+