1SYSTEMD-REPART(8) systemd-repart SYSTEMD-REPART(8)
2
6 systemd-repart, systemd-repart.service - Automatically grow and add
7 partitions
8
10 systemd-repart [OPTIONS...] [[BLOCKDEVICE]...]
11 systemd-repart.service
13
15 systemd-repart grows and adds partitions to a partition table, based on
16 the configuration files described in repart.d(5).
17 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 it
22 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 initrd,
25 in order to augment the partition table of the OS before its partitions
26 are mounted. systemd-repart (mostly) operates in a purely incremental
27 mode: it only grows existing and adds new partitions; it does not
28 shrink, delete or move existing partitions. The service is intended to
29 be run on every boot, but when it detects that the partition table
30 already matches the installed repart.d/*.conf configuration files, it
31 executes no operation.
32 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 • The root partition may be grown to cover the whole available disk
41 space.
42 • A /home/, swap or /srv/ partition can be added.
44 • 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 The algorithm executed by systemd-repart is roughly as follows:
52 1. The repart.d/*.conf configuration files are loaded and parsed, and
54 ordered by filename (without the directory prefix). For each
55 configuration file, drop-in files are looked for in directories
56 with same name as the configuration file with a suffix ".d" added.
57 2. The partition table already existing on the block device is loaded
59 and parsed.
60 3. The existing partitions in the partition table are matched up with
62 the repart.d/*.conf files by GPT partition type UUID. The first
63 existing partition of a specific type is assigned the first
64 configuration file declaring the same type. The second existing
65 partition of a specific type is then assigned the second
66 configuration file declaring the same type, and so on. After this
67 iterative assigning is complete any left-over existing partitions
68 that have no matching configuration file are considered "foreign"
69 and left as they are. And any configuration files for which no
70 partition currently exists are understood as a request to create
71 such a partition.
72 4. Partitions that shall be created are now allocated on the disk,
74 taking the size constraints and weights declared in the
75 configuration files into account. Free space is used within the
76 limits set by size and padding requests. In addition, existing
77 partitions that should be grown are grown. New partitions are
78 always appended to the end of the partition table, taking the first
79 partition table slot whose index is greater than the indexes of all
80 existing partitions. Partitions are never reordered and thus
81 partition numbers remain stable. When partitions are created, they
82 are placed in the smallest area of free space that is large enough
83 to satisfy the size and padding limits. This means that partitions
84 might have different order on disk than in the partition table.
85 Note that this allocation happens in memory only, the partition
86 table on disk is not updated yet.
87 5. All existing partitions for which configuration files exist and
89 which currently have no GPT partition label set will be assigned a
90 label, either explicitly configured in the configuration or — if
91 that's missing — derived automatically from the partition type. The
92 same is done for all partitions that are newly created. These
93 assignments are done in memory only, too, the disk is not updated
94 yet.
95 6. Similarly, all existing partitions for which configuration files
97 exist and which currently have an all-zero identifying UUID will be
98 assigned a new UUID. This UUID is cryptographically hashed from a
99 common seed value together with the partition type UUID (and a
100 counter in case multiple partitions of the same type are defined),
101 see below. The same is done for all partitions that are created
102 anew. These assignments are done in memory only, too, the disk is
103 not updated yet.
104 7. Similarly, if the disk's volume UUID is all zeroes it is also
106 initialized, also cryptographically hashed from the same common
107 seed value. This is done in memory only too.
108 8. The disk space assigned to new partitions (i.e. what was previously
110 free space) is now erased. Specifically, all file system signatures
111 are removed, and if the device supports it, the BLKDISCARD I/O
112 control command is issued to inform the hardware that the space is
113 now empty. In addition any "padding" between partitions and at the
114 end of the device is similarly erased.
115 9. The new partition table is finally written to disk. The kernel is
117 asked to reread the partition table.
118 As exception to the normally strictly incremental operation, when
120 called in a special "factory reset" mode, systemd-repart may also be
121 used to erase existing partitions to reset an installation back to
122 vendor defaults. This mode of operation is used when either the
123 --factory-reset=yes switch is passed on the tool's command line, or the
124 systemd.factory_reset=yes option specified on the kernel command line,
125 or the FactoryReset EFI variable (vendor UUID
126 8cf2644b-4b0b-428f-9387-6d876050dc67) is set to "yes". It alters the
127 algorithm above slightly: between the 3rd and the 4th step above any
128 partition marked explicitly via the FactoryReset= boolean is deleted,
129 and the algorithm restarted, thus immediately re-creating these
130 partitions anew empty.
131 Note that systemd-repart only changes partition tables, it does not
133 create or resize any file systems within these partitions. A separate
134 mechanism should be used for that, for example systemd-growfs(8) and
135 systemd-makefs.
136 The UUIDs identifying the new partitions created (or assigned to
138 existing partitions that have no UUID yet), as well as the disk as a
139 whole are hashed cryptographically from a common seed value. This seed
140 value is usually the machine-id(5) of the system, so that the machine
141 ID reproducibly determines the UUIDs assigned to all partitions. If the
142 machine ID cannot be read (or the user passes --seed=random, see below)
143 the seed is generated randomly instead, so that the partition UUIDs are
144 also effectively random. The seed value may also be set explicitly,
145 formatted as UUID via the --seed= option. By hashing these UUIDs from a
146 common seed images prepared with this tool become reproducible and the
147 result of the algorithm above deterministic.
148 The positional argument should specify the block device to operate on.
150 Instead of a block device node path a regular file may be specified
151 too, in which case the command operates on it like it would if a
152 loopback block device node was specified with the file attached. If
153 --empty=create is specified the specified path is created as regular
154 file, which is useful for generating disk images from scratch.
155
157 The following options are understood:
158 --dry-run=
160 Takes a boolean. If this switch is not specified --dry-run=yes is
161 the implied default. Controls whether systemd-repart executes the
162 requested re-partition operations or whether it should only show
163 what it would do. Unless --dry-run=no is specified systemd-repart
164 will not actually touch the device's partition table.
165 --empty=
167 Takes one of "refuse", "allow", "require", "force" or "create".
168 Controls how to operate on block devices that are entirely empty,
169 i.e. carry no partition table/disk label yet. If this switch is not
170 specified the implied default is "refuse".
171 If "refuse" systemd-repart requires that the block device it shall
173 operate on already carries a partition table and refuses operation
174 if none is found. If "allow" the command will extend an existing
175 partition table or create a new one if none exists. If "require"
176 the command will create a new partition table if none exists so
177 far, and refuse operation if one already exists. If "force" it will
178 create a fresh partition table unconditionally, erasing the disk
179 fully in effect. If "force" no existing partitions will be taken
180 into account or survive the operation. Hence: use with care, this
181 is a great way to lose all your data. If "create" a new loopback
182 file is create under the path passed via the device node parameter,
183 of the size indicated with --size=, see below.
184 --discard=
186 Takes a boolean. If this switch is not specified --discard=yes is
187 the implied default. Controls whether to issue the BLKDISCARD I/O
188 control command on the space taken up by any added partitions or on
189 the space in between them. Usually, it's a good idea to issue this
190 request since it tells the underlying hardware that the covered
191 blocks shall be considered empty, improving performance. If
192 operating on a regular file instead of a block device node, a
193 sparse file is generated.
194 --size=
196 Takes a size in bytes, using the usual K, M, G, T suffixes, or the
197 special value "auto". If used the specified device node path must
198 refer to a regular file, which is then grown to the specified size
199 if smaller, before any change is made to the partition table. If
200 specified as "auto" the minimal size for the disk image is
201 automatically determined (i.e. the minimal sizes of all partitions
202 are summed up, taking space for additional metadata into account).
203 This switch is not supported if the specified node is a block
204 device. This switch has no effect if the file is already as large
205 as the specified size or larger. The specified size is implicitly
206 rounded up to multiples of 4096. When used with --empty=create this
207 specifies the initial size of the loopback file to create.
208 The --size=auto option takes the sizes of pre-existing partitions
210 into account. However, it does not accommodate for partition tables
211 that are not tightly packed: the configured partitions might still
212 not fit into the backing device if empty space exists between
213 pre-existing partitions (or before the first partition) that cannot
214 be fully filled by partitions to grow or create.
215 Also note that the automatic size determination does not take files
217 or directories specified with CopyFiles= into account: operation
218 might fail if the specified files or directories require more disk
219 space then the configured per-partition minimal size limit.
220 --factory-reset=
222 Takes boolean. If this switch is not specified --factory=reset=no
223 is the implied default. Controls whether to operate in "factory
224 reset" mode, see above. If set to true this will remove all
225 existing partitions marked with FactoryReset= set to yes early
226 while executing the re-partitioning algorithm. Use with care, this
227 is a great way to lose all your data. Note that partition files
228 need to explicitly turn FactoryReset= on, as the option defaults to
229 off. If no partitions are marked for factory reset this switch has
230 no effect. Note that there are two other methods to request factory
231 reset operation: via the kernel command line and via an EFI
232 variable, see above.
233 --can-factory-reset
235 If this switch is specified the disk is not re-partitioned. Instead
236 it is determined if any existing partitions are marked with
237 FactoryReset=. If there are the tool will exit with exit status
238 zero, otherwise non-zero. This switch may be used to quickly
239 determine whether the running system supports a factory reset
240 mechanism built on systemd-repart.
241 --root=
243 Takes a path to a directory to use as root file system when
244 searching for repart.d/*.conf files, for the machine ID file to use
245 as seed and for the CopyFiles= and CopyBlocks= source files and
246 directories. By default when invoked on the regular system this
247 defaults to the host's root file system /. If invoked from the
248 initrd this defaults to /sysroot/, so that the tool operates on the
249 configuration and machine ID stored in the root file system later
250 transitioned into itself.
251 --image=
253 Takes a path to a disk image file or device to mount and use in a
254 similar fashion to --root=, see above.
255 --image-policy=policy
257 Takes an image policy string as argument, as per systemd.image-
258 policy(7). The policy is enforced when operating on the disk image
259 specified via --image=, see above. If not specified defaults to the
260 "*" policy, i.e. all recognized file systems in the image are used.
261 --seed=
263 Takes a UUID as argument or the special value random. If a UUID is
264 specified the UUIDs to assign to partitions and the partition table
265 itself are derived via cryptographic hashing from it. If not
266 specified it is attempted to read the machine ID from the host (or
267 more precisely, the root directory configured via --root=) and use
268 it as seed instead, falling back to a randomized seed otherwise.
269 Use --seed=random to force a randomized seed. Explicitly specifying
270 the seed may be used to generated strictly reproducible partition
271 tables.
272 --pretty=
274 Takes a boolean argument. If this switch is not specified, it
275 defaults to on when called from an interactive terminal and off
276 otherwise. Controls whether to show a user friendly table and
277 graphic illustrating the changes applied.
278 --definitions=
280 Takes a file system path. If specified the *.conf files are read
281 from the specified directory instead of searching in
282 /usr/lib/repart.d/*.conf, /etc/repart.d/*.conf,
283 /run/repart.d/*.conf.
284 This parameter can be specified multiple times.
286 --key-file=
288 Takes a file system path. Configures the encryption key to use when
289 setting up LUKS2 volumes configured with the Encrypt=key-file
290 setting in partition files. Should refer to a regular file
291 containing the key, or an AF_UNIX stream socket in the file system.
292 In the latter case a connection is made to it and the key read from
293 it. If this switch is not specified the empty key (i.e. zero length
294 key) is used. This behaviour is useful for setting up encrypted
295 partitions during early first boot that receive their user-supplied
296 password only in a later setup step.
297 --private-key=
299 Takes a file system path. Configures the signing key to use when
300 creating verity signature partitions with the Verity=signature
301 setting in partition files.
302 --certificate=
304 Takes a file system path. Configures the PEM encoded X.509
305 certificate to use when creating verity signature partitions with
306 the Verity=signature setting in partition files.
307 --tpm2-device=, --tpm2-pcrs=
309 Configures the TPM2 device and list of PCRs to use for LUKS2
310 volumes configured with the Encrypt=tpm2 option. These options take
311 the same parameters as the identically named options to systemd-
312 cryptenroll(1) and have the same effect on partitions where TPM2
313 enrollment is requested.
314 --tpm2-public-key= [PATH], --tpm2-public-key-pcrs= [PCR...]
316 Configures a TPM2 signed PCR policy to bind encryption to. See
317 systemd-cryptenroll(1) for details on these two options.
318 --split= [BOOL]
320 Enables generation of split artifacts from partitions configured
321 with SplitName=. If enabled, for each partition with SplitName=
322 set, a separate output file containing just the contents of that
323 partition is generated. The output filename consists of the
324 loopback filename suffixed with the name configured with
325 SplitName=. If the loopback filename ends with ".raw", the suffix
326 is inserted before the ".raw" extension instead.
327 Note that --split is independent from --dry-run. Even if --dry-run
329 is enabled, split artifacts will still be generated from an
330 existing image if --split is enabled.
331 --include-partitions= [PARTITION...], --exclude-partitions=
333 [PARTITION...]
334 These options specify which partition types systemd-repart should
335 operate on. If --include-partitions= is used, all partitions that
336 aren't specified are excluded. If --exclude-partitions= is used,
337 all partitions that are specified are excluded. Both options take a
338 comma separated list of GPT partition type UUIDs or identifiers
339 (see Type= in repart.d(5)).
340 --defer-partitions= [PARTITION...]
342 This option specifies for which partition types systemd-repart
343 should defer. All partitions that are deferred using this option
344 are still taken into account when calculating the sizes and offsets
345 of other partitions, but aren't actually written to the disk image.
346 The net effect of this option is that if you run systemd-repart
347 again without this option, the missing partitions will be added as
348 if they had not been deferred the first time systemd-repart was
349 executed.
350 --sector-size= [BYTES]
352 This option allows configuring the sector size of the image
353 produced by systemd-repart. It takes a value that is a power of "2"
354 between "512" and "4096". This option is useful when building
355 images for disks that use a different sector size as the disk on
356 which the image is produced.
357 --architecture= [ARCH]
359 This option allows overriding the architecture used for
360 architecture specific partition types. For example, if set to
361 "arm64" a partition type of "root-x86-64" referenced in repart.d/
362 drop-ins will be patched dynamically to refer to "root-arm64"
363 instead. Takes one of "alpha", "arc", "arm", "arm64", "ia64",
364 "loongarch64", "mips-le", "mips64-le", "parisc", "ppc", "ppc64",
365 "ppc64-le", "riscv32", "riscv64", "s390", "s390x", "tilegx", "x86"
366 or "x86-64".
367 --offline= [BOOL]
369 Instructs systemd-repart to build the image offline. Takes a
370 boolean or "auto". Defaults to "auto". If enabled, the image is
371 built without using loop devices. This is useful to build images
372 unprivileged or when loop devices are not available. If disabled,
373 the image is always built using loop devices. If "auto",
374 systemd-repart will build the image online if possible and fall
375 back to building the image offline if loop devices are not
376 available or cannot be accessed due to missing permissions.
377 -h, --help
379 Print a short help text and exit.
380 --version
382 Print a short version string and exit.
383 --no-pager
385 Do not pipe output into a pager.
386 --no-legend
388 Do not print the legend, i.e. column headers and the footer with
389 hints.
390 --json=MODE
392 Shows output formatted as JSON. Expects one of "short" (for the
393 shortest possible output without any redundant whitespace or line
394 breaks), "pretty" (for a pretty version of the same, with
395 indentation and line breaks) or "off" (to turn off JSON output, the
396 default).
397
399 On success, 0 is returned, a non-zero failure code otherwise.
400
402 systemd(1), repart.d(5), machine-id(5), systemd-cryptenroll(1)
403systemd 254 SYSTEMD-REPART(8)