From 917cc8082bbd1d380ddf7cdc8ae40606a7de0bfd Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 17 Dec 2019 13:47:21 +0100 Subject: man: document systemd-repart --- man/systemd-repart.xml | 269 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 man/systemd-repart.xml (limited to 'man/systemd-repart.xml') diff --git a/man/systemd-repart.xml b/man/systemd-repart.xml new file mode 100644 index 0000000000..cffcb5403a --- /dev/null +++ b/man/systemd-repart.xml @@ -0,0 +1,269 @@ + + + + + + + + systemd-repart + systemd + + + + systemd-repart + 8 + + + + systemd-repart + systemd-repart.service + Automatically grow and add partitions + + + + + systemd-repart + OPTIONS + BLOCKDEVICE + + + systemd-repart.service + + + + Description + + systemd-repart grows and adds partitions to a partition table, based on the + configuration files described in + repart.d5. + + + If invoked with no arguments, it operates on the block device backing the root file system partition + of the OS, thus growing and adding partitions of the booted OS image itself. When called in the initial + RAM disk it operates on the block device backing /sysroot/ instead, i.e. on the + block device the system will soon transition into. The systemd-repart.service + service is generally run at boot in the initial RAM disk, in order to augment the partition table of the + OS before its partitions are mounted. systemd-repart (mostly) operates in a purely + incremental mode: it only grows existing and adds new partitions; it does not shrink, delete or move + existing partitions. The service is intended to be run on every boot, but when it detects that the + partition table already matches the installed repart.d/*.conf configuration + files, it executes no operation. + + systemd-repart is intended to be used when deploying OS images, to automatically + adjust them to the system they are running on, during first boot. This way the deployed image can be + minimal in size and may be augmented automatically at boot when needed, taking possession of disk space + available but not yet used. Specifically the following use cases are among those covered: + + + The root partition may be grown to cover the whole available disk space + A /home/, swap or /srv partition can be added in + A second (or third, …) root partition may be added in, to cover A/B style setups + where a second version of the root file system is alternatingly used for implementing update + schemes. The deployed image would carry only a single partition ("A") but on first boot a second + partition ("B") for this purpose is automatically created. + + + The algorithm executed by systemd-repart is roughly as follows: + + + The repart.d/*.conf configuration files are loaded and parsed, + and ordered by filename (without the directory suffix). + + The partition table already existing on the block device is loaded and + parsed. + + The existing partitions in the partition table are matched up with the + repart.d/*.conf files by GPT partition type UUID. The first existing partition + of a specific type is assigned the first configuration file declaring the same type. The second + existing partition of a specific type is then assigned the second configuration file declaring the same + type, and so on. After this iterative assigning is complete any left-over existing partitions that have + no matching configuration file are considered "foreign" and left as they are. And any configuration + files for which no partition currently exists are understood as a request to create such a + partition. + + Taking the size constraints and weights declared in the configuration files into + account, all partitions that shall be created are now allocated to the disk, taking up all free space, + always respecting the size and padding requests. Similar, existing partitions that are determined to + grow are grown. New partitions are always appended to the end of the existing partition table, taking + the first partition table slot whose index is greater than the indexes of all existing + partitions. Partition table slots are never reordered and thus partition numbers are ensured to remain + stable. Note that this allocation happens in RAM only, the partition table on disk is not updated + yet. + + All existing partitions for which configuration files exist and which currently have no + GPT partition label set will be assigned a label, either explicitly configured in the configuration or + (if that's missing) derived automatically from the partition type. The same is done for all partitions + that are newly created. These assignments are done in RAM only, too, the disk is not updated + yet. + + Similarly, all existing partitions for which configuration files exist and which + currently have an all-zero identifying UUID will be assigned a new UUID. This UUID is cryptographically + hashed from a common seed value together with the partition type UUID (and a counter in case multiple + partitions of the same type are defined), see below. The same is done for all partitions that are + created anew. These assignments are done in RAM only, too, the disk is not updated + yet. + + Similarly, if the disk's volume UUID is all zeroes it is also initialized, also + cryptographically hashed from the same common seed value. Also, in RAM only, too. + + The disk space assigned to new partitions (i.e. what was previously considered free + space but is no longer) is now erased. Specifically, all file system signatures are removed, and if the + device supports it the BLKDISCARD I/O control command is issued to inform the + hardware that the space is empty now. In addition any "padding" between partitions and at the end of + the device is similarly erased. + + The new partition table is finally written to disk. The kernel is asked to reread the + partition table. + + + As exception to the normally strictly incremental operation, when called in a special "factory + reset" mode systemd-repart may also be used to erase select existing partitions to + reset an installation back to vendor defaults. This mode of operation is used when either the + switch is passed on the tool's command line, or the + option specified on the kernel command line, or the + FactoryReset EFI variable (vendor UUID + 8cf2644b-4b0b-428f-9387-6d876050dc67) is set to "yes". It alters the algorithm above + slightly: between the 3rd and the 4th step above the any partition marked explicitly via the + FactoryReset= boolean is deleted, and the algorithm restarted, thus immediately + re-creating these partitions anew empty. + + Note that systemd-repart only changes partition tables, it does not create or + resize any file systems within these partitions. A separate mechanism should be used for that, for + example + systemd-growfs8 and + systemd-makefs. + + The UUIDs identifying the new partitions created (or assigned to existing partitions that have no + UUID yet), as well as the disk as a whole are hashed cryptographically from a common seed value. This + seed value is usually the + machine-id5 of the + system, so that the machine ID reproducibly determines the UUIDs assigned to all partitions. If the + machine ID cannot be read (or the user passes , see below) the seed is + generated randomly instead, so that the partition UUIDs are also effectively random. The seed value may + also be set explicitly, formatted as UUID via the option. By hashing these UUIDs + from a common seed images prepared with this tool become reproducible and the result of the algorithm + above deterministic. + + + + Options + + The following options are understood: + + + + + Takes a boolean. If this switch is not specified is + the implied default. Controls whether systemd-repart executes the requested + re-partition operations or whether it should only show what it would do. Unless + is specified systemd-repart will not actually + touch the device's partition table. + + + + + Takes one of refuse, allow, + require or force. Controls how to operate on block devices that + are entirely empty, i.e. carry no partition table/disk label yet. If this switch is not specified the + implied default is refuse. + + If refuse systemd-repart requires that the block device + it shall operate on already carries a partition table and refuses operation if none is found. If + allow the command will extend an existing partition table or create a new one if + none exists. If require the command will create a new partition table if none + exists so far, and refuse operation if one already exists. If force it will create + a fresh partition table unconditionally, erasing the disk fully in effect. If + force no existing partitions will be taken into account or survive the + operation. Hence: use with care, this is a great way to lose all your data. + + + + + + Takes a boolean. If this switch is not specified is + the implied default. Controls whether to issue the BLKDISCARD I/O control + command on the space taken up by any added partitions or on the space in between them. Usually, it's + a good idea to issue this request since it tells the underlying hardware that the covered blocks + shall be considered empty, improving performance. + + + + + + Takes boolean. If this switch is not specified is + the implied default. Controls whether to operate in "factory reset" mode, see above. If set to true + this will remove all existing partitions marked with FactoryReset= set to yes + early while executing the re-partitioning algorithm. Use with care, this is a great way to lose all + your data. Note that partition files need to explicitly turn FactoryReset= on, as + the option defaults to off. If no partitions are marked for factory reset this switch has no + effect. Note that there are two other methods to request factory reset operation: via the kernel + command line and via an EFI variable, see above. + + + + + + If this switch is specified the disk is not re-partitioned. Instead it is determined + if any existing partitions are marked with FactoryReset=. If there are the tool + will exit with exit status zero, otherwise non-zero. This switch may be used to quickly determine + whether the running system supports a factory reset mechanism built on + systemd-repart. + + + + + + Takes a path to a directory to use as root file system when searching for + repart.d/*.conf files and for the machine ID file to use as seed. By default + when invoked on the regular system this defaults to the host's root file system + /. If invoked from the initial RAM disk this defaults to + /sysroot/, so that the tool operates on the configuration and machine ID stored + in the root file system later transitioned into itself. + + + + + + Takes a UUID as argument or the special value random. If a UUID + is specified the UUIDs to assign to partitions and the partition table itself are derived via + cryptographic hashing from it. If not specified it is attempted to read the machine ID from the host + (or more precisely, the root directory configured via ) and use it as seed + instead, falling back to a randomized seed otherwise. Use to force a + randomized seed. Explicitly specifying the seed may be used to generated strictly reproducible + partition tables. + + + + + + Takes a boolean argument. If this switch is not specified, it defaults to on when + called from an interactive terminal and off otherwise. Controls whether to show a user friendly table + and graphic illustrating the changes applied. + + + + + + Takes a file system path. If specified the *.conf are directly + read from the specified directory instead of searching in + /usr/lib/repart.d/*.conf, /etc/repart.d/*.conf, + /run/repart.d/*.conf. + + + + + + + + + See Also + + systemd1, + repart.d5, + machine-id5 + + + + -- cgit v1.2.1