From: Sam Leonard <sam.leonard@codethink.co.uk>
Date: Mon, 4 Dec 2023 17:33:12 +0000 (+0000)
Subject: vmspawn: document --directory and --private-users
X-Git-Tag: v256-rc1~899^2~1
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=7fe9c9909db0b49d4b915cffdda25c10addf504d;p=thirdparty%2Fsystemd.git

vmspawn: document --directory and --private-users
---

diff --git a/man/systemd-vmspawn.xml b/man/systemd-vmspawn.xml
index b84cc9c0629..184ba6e590c 100644
--- a/man/systemd-vmspawn.xml
+++ b/man/systemd-vmspawn.xml
@@ -69,6 +69,20 @@
     <refsect2>
       <title>Image Options</title>
 
+      <varlistentry>
+        <term><option>-D</option></term>
+        <term><option>--directory=</option></term>
+
+        <listitem><para>Directory to use as file system root for the virtual machine.</para>
+
+        <para>One of either <option>--directory=</option> or <option>--image=</option> must be specified.</para>
+        <para>Note: If mounting a non-root owned directory you may require <option>--private-users=</option>
+              to map into the user's subuid namespace.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/>
+        </listitem>
+      </varlistentry>
+
       <variablelist>
         <varlistentry>
           <term><option>-i</option></term>
@@ -249,7 +263,34 @@
         </varlistentry>
       </variablelist>
 
-    </refsect2><refsect2>
+    </refsect2>
+
+    <refsect2>
+      <title>User Namespacing Options</title>
+
+      <variablelist>
+        <varlistentry>
+          <term><option>--private-users=</option><replaceable>UID_SHIFT[:UID_RANGE]</replaceable></term>
+
+          <listitem><para>Controls user namespacing under <option>--directory=</option>.
+          If enabled, <citerefentry project='man-pages'><refentrytitle>virtiofsd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+          is instructed to map user and group ids (UIDs and GIDs). This involves mapping the private UIDs/GIDs used in the virtual machine
+          (starting with the virtual machine's root user 0 and up) to a range of UIDs/GIDs on the host that are not used for other
+          purposes (usually in the range beyond the host's UID/GID 65536).</para>
+
+          <para>If one or two colon-separated numbers are specified, user namespacing is turned on. <replaceable>UID_SHIFT</replaceable>
+          specifies the first host UID/GID to map, <replaceable>UID_RANGE</replaceable> is optional and specifies number of host
+          UIDs/GIDs to assign to the virtual machine. If <replaceable>UID_RANGE</replaceable> is omitted, 65536 UIDs/GIDs are assigned.</para>
+
+          <para>When user namespaces are used, the GID range assigned to each virtual machine is always chosen identical to the
+          UID range.</para>
+
+          <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+
+    <refsect2>
       <title>Credentials</title>
 
       <variablelist>