picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

man: document new repart features

This commit is contained in:
Lennart Poettering 2020-08-05 17:53:39 +02:00
parent f7011e17f1
commit dfb4d0ae0d
2 changed files with 103 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
man/repart.d.xml
View File

@ -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>

39
man/systemd-repart.xml
View File

@ -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>