man: document new repart features

poettering · poettering · commit dfb4d0ae0d07 · 2020-08-24T22:00:52.000+02:00
diff --git a/man/repart.d.xml b/man/repart.d.xml
@@ -55,11 +55,11 @@
     partition slot greater than the highest slot number currently in use. Any existing partitions that have
     no matching partition file are left as they are.</para>
 
-    <para>Note that these partition definition files do not describe the contents of the partitions, such as
-    the file system used. Separate mechanisms, such as
-    <citerefentry><refentrytitle>systemd-growfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> and
-    <command>systemd-makefs</command> maybe be used to initialize or grow the file systems inside of these
-    partitions.</para>
+    <para>Note that these definitions may only be used to created and initialize new partitions or grow
+    existing ones. In the latter case it will not grow the contained files systems however; separate
+    mechanisms, such as
+    <citerefentry><refentrytitle>systemd-growfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> may be
+    used to grow the file systems inside of these partitions.</para>
   </refsect1>
 
   <refsect1>
@@ -327,7 +327,72 @@
         data is never overwritten. Note that the data is copied in before the partition table is updated,
         i.e. before the partition actually is persistently created. This provides robustness: it is
         guaranteed that the partition either doesn't exist or exists fully populated; it is not possible that
-        the partition exists but is not or only partially populated.</para></listitem>
+        the partition exists but is not or only partially populated.</para>
+
+        <para>This option cannot be combined with <varname>Format=</varname> or
+        <varname>CopyFiles=</varname>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>Format=</varname></term>
+
+        <listitem><para>Takes a file system name, such as <literal>ext4</literal>, <literal>btrfs</literal>,
+        <literal>xfs</literal> or <literal>vfat</literal>, or the special value <literal>swap</literal>. If
+        specified and the partition is newly created it is formatted with the specified file system (or as
+        swap device). The file system UUID and label are automatically derived from the partition UUID and
+        label. If this option is used, the size allocation algorithm is slightly altered: the partition is
+        created as least as big as required for the minimal file system of the specified type (or 4KiB if the
+        minimal size is not known).</para>
+
+        <para>This option has no effect if the partition already exists.</para>
+
+        <para>Similar to the behaviour of <varname>CopyBlocks=</varname> the file system is formatted before
+        the partition is created, ensuring that the partition only ever exists with a fully initialized
+        file system.</para>
+
+        <para>This option cannot be combined with <varname>CopyBlocks=</varname>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>CopyFiles=</varname></term>
+
+        <listitem><para>Takes a pair of colon separated absolute file system paths. The first path refers to
+        a source file or directory on the host, the second path refers to a target in the file system of the
+        newly created partition and formatted file system. This setting may be used to copy files or
+        directories from the host into the file system that is created due to the <varname>Format=</varname>
+        option. If <varname>CopyFiles=</varname> is used without <varname>Format=</varname> specified
+        explicitly, <literal>Format=</literal> with a suitable default is implied (currently
+        <literal>ext4</literal>, but this may change in the future). This option may be used multiple times
+        to copy multiple files or directories from host into the newly formatted file system. The colon and
+        second path may be omitted in which case the source path is also used as the target path (relative to
+        the root of the newly created file system). If the source path refers to a directory it is copied
+        recursively.</para>
+
+        <para>This option has no effect if the partition already exists: it cannot be used to copy additional
+        files into an existing partition, it may only be used to populate a file system created anew.</para>
+
+        <para>The copy operation is executed before the file system is registered in the partition table,
+        thus ensuring that a file system populated this way only ever exists fully initialized.</para>
+
+        <para>This option cannot be combined with <varname>CopyBlocks=</varname>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>Encrypt=</varname></term>
+
+        <listitem><para>Takes a boolean parameter, defaulting to false. If true the partition will be
+        formatted with a LUKS2 superblock, before the blocks configured with <varname>CopyBlocks=</varname>
+        are copied in or the file system configured with <varname>Format=</varname> is created.</para>
+
+        <para>The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion. A single
+        key is added to the LUKS2 superblock, configurable with the <option>--key-file=</option> switch to
+        <command>systemd-repart</command>.</para>
+
+        <para>When used this slightly alters the size allocation logic as the implicit, minimal size limits
+        of <varname>Format=</varname> and <varname>CopyBlocks=</varname> are increased by the space necessary
+        for the LUKS2 superblock (see above).</para>
+
+        <para>This option has no effect if the partition already exists.</para></listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/systemd-repart.xml b/man/systemd-repart.xml
@@ -202,13 +202,26 @@
       <varlistentry>
         <term><option>--size=</option></term>
 
-        <listitem><para>Takes a size in bytes, using the usual K, M, G, T suffixes. If used the specified
-        device node path must refer to a regular file, which is then grown to the specified size if smaller,
-        before any change is made to the partition table. This is not supported if the specified node is a
-        block device. This switch has no effect if the file is already as large as the specified size or
-        larger. The specified size is implicitly rounded up to multiples of 4096. When used with
-        <option>--empty=create</option> this specifies the initial size of the loopback file to
-        create.</para></listitem>
+        <listitem><para>Takes a size in bytes, using the usual K, M, G, T suffixes, or the special value
+        <literal>auto</literal>. If used the specified device node path must refer to a regular file, which
+        is then grown to the specified size if smaller, before any change is made to the partition table. If
+        specified as <literal>auto</literal> the minimal size for the disk image is automatically determined
+        (i.e. the minimal sizes of all partitions are summed up, taking space for additional metadata into
+        account). This switch is not supported if the specified node is a block device. This switch has no
+        effect if the file is already as large as the specified size or larger. The specified size is
+        implicitly rounded up to multiples of 4096. When used with <option>--empty=create</option> this
+        specifies the initial size of the loopback file to create.</para>
+
+        <para>The <option>--size=auto</option> option takes the sizes of pre-existing partitions into
+        account. However, it does not accomodate for partition tables that are not tightly packed: the
+        configured partitions might still not fit into the backing device if empty space exists between
+        pre-existing partitions (or before the first partition) that cannot be fully filled by partitions to
+        grow or create.</para>
+
+        <para>Also note that the automatic size determination does not take files or directories specified
+        with <option>CopyFiles=</option> into account: operation might fail if the specified files or
+        directories require more disk space then the configured per-partition minimal size
+        limit.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -283,6 +296,18 @@
         <filename>/run/repart.d/*.conf</filename>.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>--key-file=</option></term>
+
+        <listitem><para>Takes a file system path. Configures the encryption key to use when setting up LUKS2
+        volumes configured with the <varname>Encrypt=</varname> setting in partition files. Should refer to a
+        regular file containing the key, or an <constant>AF_UNIX</constant> stream socket in the file
+        system. In the latter case a connection is made to it and the key read from it. If this switch is not
+        specified the empty key (i.e. zero length key) is used. This behaviour is useful for setting up encrypted
+        partitions during early first boot that receive their user-supplied password only in a later setup
+        step.</para></listitem>
+      </varlistentry>
+
       <xi:include href="standard-options.xml" xpointer="help" />
       <xi:include href="standard-options.xml" xpointer="version" />
     </variablelist>
