man: document /sbin/mount.ddi

2 files changed, 48 insertions, 3 deletions

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 2bf5936d64..ff4794b528 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -902,7 +902,7 @@ manpages = [
  ['systemd-debug-generator', '8', [], ''],
  ['systemd-delta', '1', [], ''],
  ['systemd-detect-virt', '1', [], ''],
- ['systemd-dissect', '1', [], 'HAVE_BLKID'],
+ ['systemd-dissect', '1', ['mount.ddi'], 'HAVE_BLKID'],
  ['systemd-environment-d-generator',
   '8',
   ['30-systemd-environment-d-generator'],
diff --git a/man/systemd-dissect.xml b/man/systemd-dissect.xml
index 6549aa92c8..01eda2702d 100644
--- a/man/systemd-dissect.xml
+++ b/man/systemd-dissect.xml
@@ -18,6 +18,7 @@
 
   <refnamediv>
     <refname>systemd-dissect</refname>
+    <refname>mount.ddi</refname>
     <refpurpose>Dissect Discoverable Disk Images (DDIs)</refpurpose>
   </refnamediv>
 
@@ -99,6 +100,14 @@
     what it operates with when mounting the image. To display the complete list of partitions use a tool such
     as <citerefentry
     project='man-pages'><refentrytitle>fdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+
+    <para>The <command>systemd-dissect</command> command may be invoked as <command>mount.ddi</command> in
+    which case it implements the <citerefentry
+    project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> "external
+    helper" interface. This ensures disk images compatible with <command>systemd-dissect</command> can be
+    mounted directly by <command>mount</command> and <citerefentry
+    project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
+    details see below.</para>
   </refsect1>
 
   <refsect1>
@@ -132,7 +141,13 @@
         <para>All mounted file systems are checked with the appropriate <citerefentry
         project='man-pages'><refentrytitle>fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>
         implementation in automatic fixing mode, unless explicitly turned off (<option>--fsck=no</option>) or
-        read-only operation is requested (<option>--read-only</option>).</para></listitem>
+        read-only operation is requested (<option>--read-only</option>).</para>
+
+        <para>Note that this functionality is also available in <citerefentry
+        project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> via a
+        command such as <command>mount -t ddi myimage.raw targetdir/</command>, as well as in <citerefentry
+        project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
+        details, see below.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -359,6 +374,35 @@
     command is used the exit status of the invoked command is propagated.</para>
   </refsect1>
 
+  <refsect1>
+    <title>Invocation as <command>/sbin/mount.ddi</command></title>
+
+    <para>The <command>systemd-dissect</command> executable may be symlinked to
+    <filename>/sbin/mount.ddi</filename>. If invoked through that it implements <citerefentry
+    project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
+    "external helper" interface for the (pseudo) file system type <literal>ddi</literal>. This means
+    conformant disk images may be mounted directly via</para>
+
+    <programlisting># mount -t ddi myimage.raw targetdir/</programlisting>
+
+    <para>in a fashion mostly equivalent to:</para>
+
+    <programlisting># systemd-dissect --mount myimage.raw targetdir/</programlisting>
+
+    <para>Note that since a single DDI may contain multiple file systems it should later be unmounted with
+    <command>umount -R targetdir/</command>, for recursive operation.</para>
+
+    <para>This functionality is particularly useful to mount DDIs automatically at boot via simple
+    <filename>/etc/fstab</filename> entries. For example:</para>
+
+    <programlisting>/path/to/myimage.raw /images/myimage/ ddi defaults 0 0</programlisting>
+
+    <para>When invoked this way the mount options <literal>ro</literal>, <literal>rw</literal>,
+    <literal>discard</literal>, <literal>nodiscard</literal> map to the corresponding options listed above
+    (i.e. <option>--read-only</option>, <option>--discard=all</option>,
+    <option>--discard=disabled</option>). Mount options are <emphasis>not</emphasis> generically passed on to
+    the file systems inside the images.</para>
+  </refsect1>
 
   <refsect1>
     <title>Examples</title>
@@ -366,7 +410,7 @@
     <example>
       <title>Generate a tarball from an OS disk image</title>
 
-      <programlisting>$ systemd-dissect --with foo.raw tar cz . >foo.tar.gz</programlisting>
+      <programlisting># systemd-dissect --with foo.raw tar cz . >foo.tar.gz</programlisting>
     </example>
   </refsect1>
 
@@ -377,6 +421,7 @@
       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>,
+      <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>fdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     </para>