man: Add ostree-prepare-root

Add an overdue man page that describes this.  Prep for also
documenting composefs things here.

diff --git a/Makefile-man.am b/Makefile-man.am
index d3ea98471eb5d04fb79c73bbc1aa0188ca3b0937..5df392cacaff2bf226203e4490a3d8f406a472ca 100644 (file)
--- 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 e20ae871d5024007bf7a35e053062b940a725635..b5054c92da44cbd52c320e21833f7ac18df06c36 100644 (file)
--- a/man/index.xml
+++ b/man/index.xml
@@ -192,6 +192,10 @@ License along with this library. If not, see <https://www.gnu.org/licenses/>.
         <refentrytitle>ostree-summary</refentrytitle><manvolnum>1</manvolnum>
     </citerefentry></primaryie></indexentry>
 
+    <indexentry><primaryie><citerefentry>
+        <refentrytitle>ostree-prepare-root</refentrytitle><manvolnum>1</manvolnum>
+    </citerefentry></primaryie></indexentry>
+
     <indexentry><primaryie><citerefentry>
         <refentrytitle>ostree-trivial-httpd</refentrytitle><manvolnum>1</manvolnum>
     </citerefentry></primaryie></indexentry>

diff --git a/man/ostree-prepare-root.xml b/man/ostree-prepare-root.xml
new file mode 100644 (file)
index 0000000..8b42113
--- /dev/null
+++ b/man/ostree-prepare-root.xml
@@ -0,0 +1,122 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+SPDX-License-Identifier: LGPL-2.0+
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library. If not, see <https://www.gnu.org/licenses/>.
+-->
+
+<refentry id="ostree">
+
+    <refentryinfo>
+        <title>ostree prepare-root</title>
+        <productname>OSTree</productname>
+
+        <authorgroup>
+            <author>
+                <contrib>Developer</contrib>
+                <firstname>Colin</firstname>
+                <surname>Walters</surname>
+                <email>walters@verbum.org</email>
+            </author>
+        </authorgroup>g
+    </refentryinfo>
+
+    <refmeta>
+        <refentrytitle>ostree prepare-root</refentrytitle>
+        <manvolnum>1</manvolnum>
+    </refmeta>
+
+    <refnamediv>
+        <refname>ostree-prepare-root</refname>
+        <refpurpose>Change the view of a mounted root filesystem to an ostree deployment</refpurpose>
+    </refnamediv>
+
+    <refsynopsisdiv>
+            <cmdsynopsis>
+                <command>ostree prepare-root</command> <arg choice="req">TARGET</arg>
+            </cmdsynopsis>
+    </refsynopsisdiv>
+
+    <refsect1>
+        <title>Description</title>
+
+        <para>
+            At its core, ostree operates on an existing mounted filesystem.  Tooling such
+            as <literal>ostree admin deploy</literal> 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.
+        </para>
+
+        <para>
+            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.
+        </para>
+
+        <para>
+            The most common pattern today is to use systemd in an initramfs.  The systemd
+            unit shipped upstream is ordered in this way:
+
+            <literal>After=sysroot.mount</literal> and <literal>Before=initrd-root-fs.target</literal>
+        </para>
+
+        <para>
+            When it runs, the mounted filesystem at the provided <literal>TARGET</literal> (usually <literal>/sysroot</literal>)
+            will be changed such that what appears at <literal>/sysroot</literal> 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 <literal>/sysroot/sysroot</literal>.
+        </para>
+
+        <para>
+            For <literal>/var</literal>, by default a bind mount is created from the deployment root to <literal>/sysroot/var</literal>.
+        </para>
+
+        <para>
+            A read-only bind mount is created over <literal>/sysroot/usr</literal>.  The immutable bit is set on the deployment
+            root, so this provides basic protection for filesystem mutation.  If the <literal>sysroot.readonly</literal>
+            option is enabled, instead a writable bind mount for <literal>/sysroot/etc</literal>, and everything else
+            is mounted read-only.
+        </para>
+
+        <para>
+            Finally, when higher level tooling such as systemd performs a switch-root operation, what
+            was <literal>/sysroot</literal> becomes <literal>/</literal> 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 <literal>/sysroot</literal> which is now the "physical root".
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>systemd</title>
+
+        <para>
+            As mentioned above, this tool comes with a systemd unit file <literal>ostree-prepare-root.service</literal>
+            and it is primarily expected to be invoked this way.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Composefs</title>
+
+        <para>
+            The default for ostree is to create a plain hardlinked filesystem tree.
+            composefs support is currently experimental; see the upstream <literal>doc/composefs.md</literal>
+            for more information on using it.
+        </para>
+    </refsect1>
+
+</refentry>