diff --git a/Makefile-man.am b/Makefile-man.am
index d3ea98471e..5df392caca 100644
--- a/Makefile-man.am
+++ b/Makefile-man.am
@@ -36,7 +36,7 @@ ostree-config.1 ostree-diff.1 ostree-find-remotes.1 ostree-fsck.1 \
ostree-init.1 ostree-log.1 ostree-ls.1 ostree-prune.1 ostree-pull-local.1 \
ostree-pull.1 ostree-refs.1 ostree-remote.1 ostree-reset.1 \
ostree-rev-parse.1 ostree-show.1 ostree-sign.1 ostree-summary.1 \
-ostree-static-delta.1
+ostree-static-delta.1 ostree-prepare-root.1
if BUILDOPT_FUSE
man1_files += rofiles-fuse.1
diff --git a/man/index.xml b/man/index.xml
index e20ae871d5..b5054c92da 100644
--- a/man/index.xml
+++ b/man/index.xml
@@ -192,6 +192,10 @@ License along with this library. If not, see .
ostree-summary1
+
+ ostree-prepare-root1
+
+
ostree-trivial-httpd1
diff --git a/man/ostree-prepare-root.xml b/man/ostree-prepare-root.xml
new file mode 100644
index 0000000000..8b42113a74
--- /dev/null
+++ b/man/ostree-prepare-root.xml
@@ -0,0 +1,122 @@
+
+
+
+
+
+
+
+
+ ostree prepare-root
+ OSTree
+
+
+
+ Developer
+ Colin
+ Walters
+ walters@verbum.org
+
+ g
+
+
+
+ ostree prepare-root
+ 1
+
+
+
+ ostree-prepare-root
+ Change the view of a mounted root filesystem to an ostree deployment
+
+
+
+
+ ostree prepare-root TARGET
+
+
+
+
+ Description
+
+
+ At its core, ostree operates on an existing mounted filesystem. Tooling such
+ as ostree admin deploy will create a new directory that can be
+ used as a bootable target. This tool is designed to run in an initramfs and
+ set up "remapping" mounts as a view into that filesystem.
+
+
+
+ As of more recently, this tool also has optional support for composefs, which
+ creates a distinct mount point layered on top of the underlying filesystem.
+
+
+
+ The most common pattern today is to use systemd in an initramfs. The systemd
+ unit shipped upstream is ordered in this way:
+
+ After=sysroot.mount and Before=initrd-root-fs.target
+
+
+
+ When it runs, the mounted filesystem at the provided TARGET (usually /sysroot)
+ will be changed such that what appears at /sysroot is actually the
+ "deployment root" - i.e. a particular versioned subdirectory. What was formerly the
+ "physical root" i.e. the real root of the filesystem will appear as /sysroot/sysroot.
+
+
+
+ For /var, by default a bind mount is created from the deployment root to /sysroot/var.
+
+
+
+ A read-only bind mount is created over /sysroot/usr. The immutable bit is set on the deployment
+ root, so this provides basic protection for filesystem mutation. If the sysroot.readonly
+ option is enabled, instead a writable bind mount for /sysroot/etc, and everything else
+ is mounted read-only.
+
+
+
+ Finally, when higher level tooling such as systemd performs a switch-root operation, what
+ was /sysroot becomes / and after the transition into
+ the real root, the system will be booted into the "deployment", which is a versioned immutable
+ filesystem tree. The ostree tooling running in the real root thereafter performs further changes
+ by operating on /sysroot which is now the "physical root".
+
+
+
+
+ systemd
+
+
+ As mentioned above, this tool comes with a systemd unit file ostree-prepare-root.service
+ and it is primarily expected to be invoked this way.
+
+
+
+
+ Composefs
+
+
+ The default for ostree is to create a plain hardlinked filesystem tree.
+ composefs support is currently experimental; see the upstream doc/composefs.md
+ for more information on using it.
+
+
+
+