1SYSTEMD-REPART(8)               systemd-repart               SYSTEMD-REPART(8)
2
3
4

NAME

6       systemd-repart, systemd-repart.service - Automatically grow and add
7       partitions
8

SYNOPSIS

10       systemd-repart [OPTIONS...] [[BLOCKDEVICE]...]
11
12       systemd-repart.service
13

DESCRIPTION

15       systemd-repart grows and adds partitions to a partition table, based on
16       the configuration files described in repart.d(5).
17
18       If invoked with no arguments, it operates on the block device backing
19       the root file system partition of the running OS, thus growing and
20       adding partitions of the booted OS image itself. If --image= is used it
21       will operate on the specified image file. When called in the "initrd"
22       it operates on the block device backing /sysroot/ instead, i.e. on the
23       block device the system will soon transition into. The
24       systemd-repart.service service is generally run at boot in the initial
25       RAM disk, in order to augment the partition table of the OS before its
26       partitions are mounted.  systemd-repart (mostly) operates in a purely
27       incremental mode: it only grows existing and adds new partitions; it
28       does not shrink, delete or move existing partitions. The service is
29       intended to be run on every boot, but when it detects that the
30       partition table already matches the installed repart.d/*.conf
31       configuration files, it executes no operation.
32
33       systemd-repart is intended to be used when deploying OS images, to
34       automatically adjust them to the system they are running on, during
35       first boot. This way the deployed image can be minimal in size and may
36       be augmented automatically at boot when needed, taking possession of
37       disk space available but not yet used. Specifically the following use
38       cases are among those covered:
39
40       •   The root partition may be grown to cover the whole available disk
41           space.
42
43       •   A /home/, swap or /srv/ partition can be added.
44
45       •   A second (or third, ...) root partition may be added, to cover A/B
46           style setups where a second version of the root file system is
47           alternatingly used for implementing update schemes. The deployed
48           image would carry only a single partition ("A") but on first boot a
49           second partition ("B") for this purpose is automatically created.
50
51       The algorithm executed by systemd-repart is roughly as follows:
52
53        1. The repart.d/*.conf configuration files are loaded and parsed, and
54           ordered by filename (without the directory prefix).
55
56        2. The partition table already existing on the block device is loaded
57           and parsed.
58
59        3. The existing partitions in the partition table are matched up with
60           the repart.d/*.conf files by GPT partition type UUID. The first
61           existing partition of a specific type is assigned the first
62           configuration file declaring the same type. The second existing
63           partition of a specific type is then assigned the second
64           configuration file declaring the same type, and so on. After this
65           iterative assigning is complete any left-over existing partitions
66           that have no matching configuration file are considered "foreign"
67           and left as they are. And any configuration files for which no
68           partition currently exists are understood as a request to create
69           such a partition.
70
71        4. Taking the size constraints and weights declared in the
72           configuration files into account, all partitions that shall be
73           created are now allocated to the disk, taking up all free space,
74           always respecting the size and padding requests. Similar, existing
75           partitions that are determined to grow are grown. New partitions
76           are always appended to the end of the existing partition table,
77           taking the first partition table slot whose index is greater than
78           the indexes of all existing partitions. Partition table slots are
79           never reordered and thus partition numbers are ensured to remain
80           stable. Note that this allocation happens in RAM only, the
81           partition table on disk is not updated yet.
82
83        5. All existing partitions for which configuration files exist and
84           which currently have no GPT partition label set will be assigned a
85           label, either explicitly configured in the configuration or (if
86           that's missing) derived automatically from the partition type. The
87           same is done for all partitions that are newly created. These
88           assignments are done in RAM only, too, the disk is not updated yet.
89
90        6. Similarly, all existing partitions for which configuration files
91           exist and which currently have an all-zero identifying UUID will be
92           assigned a new UUID. This UUID is cryptographically hashed from a
93           common seed value together with the partition type UUID (and a
94           counter in case multiple partitions of the same type are defined),
95           see below. The same is done for all partitions that are created
96           anew. These assignments are done in RAM only, too, the disk is not
97           updated yet.
98
99        7. Similarly, if the disk's volume UUID is all zeroes it is also
100           initialized, also cryptographically hashed from the same common
101           seed value. Also, in RAM only, too.
102
103        8. The disk space assigned to new partitions (i.e. what was previously
104           considered free space but is no longer) is now erased.
105           Specifically, all file system signatures are removed, and if the
106           device supports it the BLKDISCARD I/O control command is issued to
107           inform the hardware that the space is empty now. In addition any
108           "padding" between partitions and at the end of the device is
109           similarly erased.
110
111        9. The new partition table is finally written to disk. The kernel is
112           asked to reread the partition table.
113
114       As exception to the normally strictly incremental operation, when
115       called in a special "factory reset" mode, systemd-repart may also be
116       used to erase existing partitions to reset an installation back to
117       vendor defaults. This mode of operation is used when either the
118       --factory-reset=yes switch is passed on the tool's command line, or the
119       systemd.factory_reset=yes option specified on the kernel command line,
120       or the FactoryReset EFI variable (vendor UUID
121       8cf2644b-4b0b-428f-9387-6d876050dc67) is set to "yes". It alters the
122       algorithm above slightly: between the 3rd and the 4th step above any
123       partition marked explicitly via the FactoryReset= boolean is deleted,
124       and the algorithm restarted, thus immediately re-creating these
125       partitions anew empty.
126
127       Note that systemd-repart only changes partition tables, it does not
128       create or resize any file systems within these partitions. A separate
129       mechanism should be used for that, for example systemd-growfs(8) and
130       systemd-makefs.
131
132       The UUIDs identifying the new partitions created (or assigned to
133       existing partitions that have no UUID yet), as well as the disk as a
134       whole are hashed cryptographically from a common seed value. This seed
135       value is usually the machine-id(5) of the system, so that the machine
136       ID reproducibly determines the UUIDs assigned to all partitions. If the
137       machine ID cannot be read (or the user passes --seed=random, see below)
138       the seed is generated randomly instead, so that the partition UUIDs are
139       also effectively random. The seed value may also be set explicitly,
140       formatted as UUID via the --seed= option. By hashing these UUIDs from a
141       common seed images prepared with this tool become reproducible and the
142       result of the algorithm above deterministic.
143
144       The positional argument should specify the block device to operate on.
145       Instead of a block device node path a regular file may be specified
146       too, in which case the command operates on it like it would if a
147       loopback block device node was specified with the file attached. If
148       --empty=create is specified the specified path is created as regular
149       file, which is useful for generating disk images from scratch.
150

OPTIONS

152       The following options are understood:
153
154       --dry-run=
155           Takes a boolean. If this switch is not specified --dry-run=yes is
156           the implied default. Controls whether systemd-repart executes the
157           requested re-partition operations or whether it should only show
158           what it would do. Unless --dry-run=no is specified systemd-repart
159           will not actually touch the device's partition table.
160
161       --empty=
162           Takes one of "refuse", "allow", "require", "force" or "create".
163           Controls how to operate on block devices that are entirely empty,
164           i.e. carry no partition table/disk label yet. If this switch is not
165           specified the implied default is "refuse".
166
167           If "refuse" systemd-repart requires that the block device it shall
168           operate on already carries a partition table and refuses operation
169           if none is found. If "allow" the command will extend an existing
170           partition table or create a new one if none exists. If "require"
171           the command will create a new partition table if none exists so
172           far, and refuse operation if one already exists. If "force" it will
173           create a fresh partition table unconditionally, erasing the disk
174           fully in effect. If "force" no existing partitions will be taken
175           into account or survive the operation. Hence: use with care, this
176           is a great way to lose all your data. If "create" a new loopback
177           file is create under the path passed via the device node parameter,
178           of the size indicated with --size=, see below.
179
180       --discard=
181           Takes a boolean. If this switch is not specified --discard=yes is
182           the implied default. Controls whether to issue the BLKDISCARD I/O
183           control command on the space taken up by any added partitions or on
184           the space in between them. Usually, it's a good idea to issue this
185           request since it tells the underlying hardware that the covered
186           blocks shall be considered empty, improving performance. If
187           operating on a regular file instead of a block device node, a
188           sparse file is generated.
189
190       --size=
191           Takes a size in bytes, using the usual K, M, G, T suffixes, or the
192           special value "auto". If used the specified device node path must
193           refer to a regular file, which is then grown to the specified size
194           if smaller, before any change is made to the partition table. If
195           specified as "auto" the minimal size for the disk image is
196           automatically determined (i.e. the minimal sizes of all partitions
197           are summed up, taking space for additional metadata into account).
198           This switch is not supported if the specified node is a block
199           device. This switch has no effect if the file is already as large
200           as the specified size or larger. The specified size is implicitly
201           rounded up to multiples of 4096. When used with --empty=create this
202           specifies the initial size of the loopback file to create.
203
204           The --size=auto option takes the sizes of pre-existing partitions
205           into account. However, it does not accommodate for partition tables
206           that are not tightly packed: the configured partitions might still
207           not fit into the backing device if empty space exists between
208           pre-existing partitions (or before the first partition) that cannot
209           be fully filled by partitions to grow or create.
210
211           Also note that the automatic size determination does not take files
212           or directories specified with CopyFiles= into account: operation
213           might fail if the specified files or directories require more disk
214           space then the configured per-partition minimal size limit.
215
216       --factory-reset=
217           Takes boolean. If this switch is not specified --factory=reset=no
218           is the implied default. Controls whether to operate in "factory
219           reset" mode, see above. If set to true this will remove all
220           existing partitions marked with FactoryReset= set to yes early
221           while executing the re-partitioning algorithm. Use with care, this
222           is a great way to lose all your data. Note that partition files
223           need to explicitly turn FactoryReset= on, as the option defaults to
224           off. If no partitions are marked for factory reset this switch has
225           no effect. Note that there are two other methods to request factory
226           reset operation: via the kernel command line and via an EFI
227           variable, see above.
228
229       --can-factory-reset
230           If this switch is specified the disk is not re-partitioned. Instead
231           it is determined if any existing partitions are marked with
232           FactoryReset=. If there are the tool will exit with exit status
233           zero, otherwise non-zero. This switch may be used to quickly
234           determine whether the running system supports a factory reset
235           mechanism built on systemd-repart.
236
237       --root=
238           Takes a path to a directory to use as root file system when
239           searching for repart.d/*.conf files, for the machine ID file to use
240           as seed and for the CopyFiles= and CopyBlocks= source files and
241           directories. By default when invoked on the regular system this
242           defaults to the host's root file system /. If invoked from the
243           initial RAM disk this defaults to /sysroot/, so that the tool
244           operates on the configuration and machine ID stored in the root
245           file system later transitioned into itself.
246
247       --image=
248           Takes a path to a disk image file or device to mount and use in a
249           similar fashion to --root=, see above.
250
251       --seed=
252           Takes a UUID as argument or the special value random. If a UUID is
253           specified the UUIDs to assign to partitions and the partition table
254           itself are derived via cryptographic hashing from it. If not
255           specified it is attempted to read the machine ID from the host (or
256           more precisely, the root directory configured via --root=) and use
257           it as seed instead, falling back to a randomized seed otherwise.
258           Use --seed=random to force a randomized seed. Explicitly specifying
259           the seed may be used to generated strictly reproducible partition
260           tables.
261
262       --pretty=
263           Takes a boolean argument. If this switch is not specified, it
264           defaults to on when called from an interactive terminal and off
265           otherwise. Controls whether to show a user friendly table and
266           graphic illustrating the changes applied.
267
268       --definitions=
269           Takes a file system path. If specified the *.conf files are read
270           from the specified directory instead of searching in
271           /usr/lib/repart.d/*.conf, /etc/repart.d/*.conf,
272           /run/repart.d/*.conf.
273
274       --key-file=
275           Takes a file system path. Configures the encryption key to use when
276           setting up LUKS2 volumes configured with the Encrypt=key-file
277           setting in partition files. Should refer to a regular file
278           containing the key, or an AF_UNIX stream socket in the file system.
279           In the latter case a connection is made to it and the key read from
280           it. If this switch is not specified the empty key (i.e. zero length
281           key) is used. This behaviour is useful for setting up encrypted
282           partitions during early first boot that receive their user-supplied
283           password only in a later setup step.
284
285       --tpm2-device=, --tpm2-pcrs=
286           Configures the TPM2 device and list of PCRs to use for LUKS2
287           volumes configured with the Encrypt=tpm2 option. These options take
288           the same parameters as the identically named options to systemd-
289           cryptenroll(1) and have the same effect on partitions where TPM2
290           enrollment is requested.
291
292       -h, --help
293           Print a short help text and exit.
294
295       --version
296           Print a short version string and exit.
297
298       --no-pager
299           Do not pipe output into a pager.
300
301       --no-legend
302           Do not print the legend, i.e. column headers and the footer with
303           hints.
304
305       --json=MODE
306           Shows output formatted as JSON. Expects one of "short" (for the
307           shortest possible output without any redundant whitespace or line
308           breaks), "pretty" (for a pretty version of the same, with
309           indentation and line breaks) or "off" (to turn off JSON output, the
310           default).
311

EXIT STATUS

313       On success, 0 is returned, a non-zero failure code otherwise.
314

SEE ALSO

316       systemd(1), repart.d(5), machine-id(5), systemd-cryptenroll(1)
317
318
319
320systemd 250                                                  SYSTEMD-REPART(8)
Impressum