From dfb4d0ae0d0731c5efa0572f6433a2ee80a89dfb Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 5 Aug 2020 17:53:39 +0200 Subject: [PATCH] man: document new repart features --- man/repart.d.xml | 77 ++++++++++++++++++++++++++++++++++++++---- man/systemd-repart.xml | 39 +++++++++++++++++---- 2 files changed, 103 insertions(+), 13 deletions(-) diff --git a/man/repart.d.xml b/man/repart.d.xml index 1b104e76d0..9714a3602a 100644 --- 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. - Note that these partition definition files do not describe the contents of the partitions, such as - the file system used. Separate mechanisms, such as - systemd-growfs8 and - systemd-makefs maybe be used to initialize or grow the file systems inside of these - partitions. + 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 + systemd-growfs8 may be + used to grow the file systems inside of these partitions. @@ -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. + the partition exists but is not or only partially populated. + + This option cannot be combined with Format= or + CopyFiles=. + + + + Format= + + Takes a file system name, such as ext4, btrfs, + xfs or vfat, or the special value swap. 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). + + This option has no effect if the partition already exists. + + Similar to the behaviour of CopyBlocks= the file system is formatted before + the partition is created, ensuring that the partition only ever exists with a fully initialized + file system. + + This option cannot be combined with CopyBlocks=. + + + + CopyFiles= + + 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 Format= + option. If CopyFiles= is used without Format= specified + explicitly, Format= with a suitable default is implied (currently + ext4, 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. + + 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. + + 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. + + This option cannot be combined with CopyBlocks=. + + + + Encrypt= + + Takes a boolean parameter, defaulting to false. If true the partition will be + formatted with a LUKS2 superblock, before the blocks configured with CopyBlocks= + are copied in or the file system configured with Format= is created. + + 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 switch to + systemd-repart. + + When used this slightly alters the size allocation logic as the implicit, minimal size limits + of Format= and CopyBlocks= are increased by the space necessary + for the LUKS2 superblock (see above). + + This option has no effect if the partition already exists. diff --git a/man/systemd-repart.xml b/man/systemd-repart.xml index 6905e99b11..fb0d4c3496 100644 --- a/man/systemd-repart.xml +++ b/man/systemd-repart.xml @@ -202,13 +202,26 @@ - 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 - this specifies the initial size of the loopback file to - create. + Takes a size in bytes, using the usual K, M, G, T suffixes, or the special value + auto. 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 auto 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 this + specifies the initial size of the loopback file to create. + + The 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. + + Also note that the automatic size determination does not take files or directories specified + with into account: operation might fail if the specified files or + directories require more disk space then the configured per-partition minimal size + limit. @@ -283,6 +296,18 @@ /run/repart.d/*.conf. + + + + Takes a file system path. Configures the encryption key to use when setting up LUKS2 + volumes configured with the Encrypt= setting in partition files. Should refer to a + regular file containing the key, or an AF_UNIX 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. + +