Debian Codegraph @

upstream/mageia-cauldron/man8/systemd-repart.8

raw
1 '\" t
2 .TH "SYSTEMD\-REPART" "8" "" "systemd 258.7" "systemd-repart"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-repart, systemd-repart.service \- Automatically grow and add partitions, and generate disk images (DDIs)
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-repart\fR\ 'u
26 \fBsystemd\-repart\fR [OPTIONS...] [\fI[BLOCKDEVICE]\fR...]
27 .PP
28 systemd\-repart\&.service
29 .SH "DESCRIPTION"
30 .PP
31 \fBsystemd\-repart\fR
32 creates partition tables, and adds or grows partitions, based on the configuration files described in
33 \fBrepart.d\fR(5)\&.
34 .PP
35 \fBsystemd\-repart\fR
36 is used when
37 \fIbuilding\fR
38 OS images, and also when
39 \fIdeploying\fR
40 images to automatically adjust them, during boot, to the system they are running on\&. This way the image can be minimal in size and may be augmented automatically at boot, taking possession of the disk space available\&.
41 .PP
42 If invoked with no arguments,
43 \fBsystemd\-repart\fR
44 operates on the block device backing the root file system partition of the running OS, thus adding and growing partitions of the booted OS itself\&. When called in the initrd, it operates on the block device backing
45 /sysroot/
46 instead, i\&.e\&. on the block device the system will soon transition into\&. If
47 \fI\-\-image=\fR
48 is used, it will operate on the specified device or image file\&. The
49 systemd\-repart\&.service
50 service is generally run at boot in the initrd, in order to augment the partition table of the OS before its partitions are mounted\&.
51 .PP
52 \fBsystemd\-repart\fR
53 operations are mostly incremental: it grows existing partitions or adds new ones, but 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
54 repart\&.d/*\&.conf
55 configuration files, it executes no operation\&.
56 .PP
57 The following use cases are among those covered:
58 .sp
59 .RS 4
60 .ie n \{\
61 \h'-04'\(bu\h'+03'\c
62 .\}
63 .el \{\
64 .sp -1
65 .IP \(bu 2.3
66 .\}
67 The root partition may be grown to cover the whole available disk space\&.
68 .RE
69 .sp
70 .RS 4
71 .ie n \{\
72 \h'-04'\(bu\h'+03'\c
73 .\}
74 .el \{\
75 .sp -1
76 .IP \(bu 2.3
77 .\}
78 A
79 /home/, swap, or
80 /srv/
81 partition can be added\&.
82 .RE
83 .sp
84 .RS 4
85 .ie n \{\
86 \h'-04'\(bu\h'+03'\c
87 .\}
88 .el \{\
89 .sp -1
90 .IP \(bu 2.3
91 .\}
92 A second (or third, \&...) root partition may be added, 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\&.
93 .RE
94 .PP
95 The algorithm executed by
96 \fBsystemd\-repart\fR
97 is roughly as follows:
98 .sp
99 .RS 4
100 .ie n \{\
101 \h'-04' 1.\h'+01'\c
102 .\}
103 .el \{\
104 .sp -1
105 .IP " 1." 4.2
106 .\}
107 The
108 repart\&.d/*\&.conf
109 configuration files are loaded and parsed, and ordered by filename (without the directory prefix)\&. For each configuration file, drop\-in files are loaded from directories with same name as the configuration file with the suffix "\&.d" added\&.
110 .RE
111 .sp
112 .RS 4
113 .ie n \{\
114 \h'-04' 2.\h'+01'\c
115 .\}
116 .el \{\
117 .sp -1
118 .IP " 2." 4.2
119 .\}
120 The partition table on the block device is loaded and parsed, if present\&.
121 .RE
122 .sp
123 .RS 4
124 .ie n \{\
125 \h'-04' 3.\h'+01'\c
126 .\}
127 .el \{\
128 .sp -1
129 .IP " 3." 4.2
130 .\}
131 The existing partitions in the partition table are matched with the
132 repart\&.d/*\&.conf
133 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 existing partitions that have no matching configuration file are considered "foreign" and left as they are\&. And any configuration files for which no partition was matched are treated as requests to create a partition\&.
134 .RE
135 .sp
136 .RS 4
137 .ie n \{\
138 \h'-04' 4.\h'+01'\c
139 .\}
140 .el \{\
141 .sp -1
142 .IP " 4." 4.2
143 .\}
144 Partitions that shall be created are now allocated on the disk, taking the size constraints and weights declared in the configuration files into account\&. Free space is used within the limits set by size and padding requests\&. In addition, existing partitions that should be grown are grown\&. New partitions are always appended to the end of the partition table, taking the first partition table slot whose index is greater than the indexes of all existing partitions\&. Partitions are never reordered and thus partition numbers remain stable\&. When partitions are created, they are placed in the smallest area of free space that is large enough to satisfy the size and padding limits\&. This means that partitions might have different order on disk than in the partition table\&. Note that this allocation happens in memory only, the partition table on disk is not updated yet\&.
145 .RE
146 .sp
147 .RS 4
148 .ie n \{\
149 \h'-04' 5.\h'+01'\c
150 .\}
151 .el \{\
152 .sp -1
153 .IP " 5." 4.2
154 .\}
155 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 \(em if that\*(Aqs missing \(em derived automatically from the partition type\&. The same is done for all partitions that are newly created\&. These assignments are done in memory only, too, the disk is not updated yet\&.
156 .RE
157 .sp
158 .RS 4
159 .ie n \{\
160 \h'-04' 6.\h'+01'\c
161 .\}
162 .el \{\
163 .sp -1
164 .IP " 6." 4.2
165 .\}
166 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 memory only, too, the disk is not updated yet\&.
167 .RE
168 .sp
169 .RS 4
170 .ie n \{\
171 \h'-04' 7.\h'+01'\c
172 .\}
173 .el \{\
174 .sp -1
175 .IP " 7." 4.2
176 .\}
177 Similarly, if the disk\*(Aqs volume UUID is all zeroes it is also initialized, also cryptographically hashed from the same common seed value\&. This is done in memory only too\&.
178 .RE
179 .sp
180 .RS 4
181 .ie n \{\
182 \h'-04' 8.\h'+01'\c
183 .\}
184 .el \{\
185 .sp -1
186 .IP " 8." 4.2
187 .\}
188 The disk space assigned to new partitions (i\&.e\&. what was previously free space) is now erased\&. Specifically, all file system signatures are removed, and if the device supports it, the
189 \fBBLKDISCARD\fR
190 I/O control command is issued to inform the hardware that the space is now empty\&. In addition any "padding" between partitions and at the end of the device is similarly erased\&.
191 .RE
192 .sp
193 .RS 4
194 .ie n \{\
195 \h'-04' 9.\h'+01'\c
196 .\}
197 .el \{\
198 .sp -1
199 .IP " 9." 4.2
200 .\}
201 The new partition table is finally written to disk\&. The kernel is asked to reread the partition table\&.
202 .RE
203 .PP
204 As an exception to the normal incremental operation, when called in a special "factory reset" mode,
205 \fBsystemd\-repart\fR
206 may be used to erase existing partitions to reset an installation back to vendor defaults\&. This mode of operation is used when either the
207 \fB\-\-factory\-reset=yes\fR
208 switch is passed on the tool\*(Aqs command line, or the
209 \fBsystemd\&.factory_reset=yes\fR
210 option is specified on the kernel command line, or the
211 \fIFactoryResetRequest\fR
212 EFI variable (vendor UUID
213 \fB8cf2644b\-4b0b\-428f\-9387\-6d876050dc67\fR) is set to "yes"\&. It alters the algorithm above slightly: between the 3rd and the 4th step above any partition marked explicitly via the
214 \fIFactoryReset=\fR
215 boolean is deleted, and the algorithm restarted, thus immediately re\-creating these partitions anew empty\&.
216 .PP
217 Note that
218 \fBsystemd\-repart\fR
219 by default only changes partition tables, it does not create or resize any file systems within these partitions, unless the
220 \fIFormat=\fR
221 configuration option is specified\&. Also note that there are also separate mechanisms available for this purpose, for example
222 \fBsystemd-growfs\fR(8)
223 and
224 \fBsystemd\-makefs\fR\&.
225 .PP
226 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
227 \fBmachine-id\fR(5)
228 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
229 \fB\-\-seed=random\fR, 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
230 \fB\-\-seed=\fR
231 option\&. By hashing these UUIDs from a common seed images prepared with this tool become reproducible and the result of the algorithm above deterministic\&.
232 .PP
233 The positional argument should specify the block device or a regular file to operate on\&. If
234 \fB\-\-empty=create\fR
235 is specified, the specified path is created as regular file, which is useful for generating disk images from scratch\&.
236 .SH "OPTIONS"
237 .PP
238 The following options are understood:
239 .PP
240 \fB\-\-dry\-run=\fR
241 .RS 4
242 Takes a boolean\&. If this switch is not specified,
243 \fB\-\-dry\-run=yes\fR
244 is the implied default\&. Controls whether
245 systemd\-repart
246 executes the requested re\-partition operations or whether it should only show what it would do\&. Unless
247 \fB\-\-dry\-run=no\fR
248 is specified
249 systemd\-repart
250 will not actually touch the device\*(Aqs partition table\&.
251 .sp
252 Added in version 245\&.
253 .RE
254 .PP
255 \fB\-\-empty=\fR
256 .RS 4
257 Takes one of
258 "refuse",
259 "allow",
260 "require",
261 "force"
262 or
263 "create"\&. 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
264 "refuse"\&.
265 .sp
266 If
267 "refuse"
268 \fBsystemd\-repart\fR
269 requires that the block device it shall operate on already carries a partition table and refuses operation if none is found\&. If
270 "allow"
271 the command will extend an existing partition table or create a new one if none exists\&. If
272 "require"
273 the command will create a new partition table if none exists so far, and refuse operation if one already exists\&. If
274 "force"
275 it will create a fresh partition table unconditionally, erasing the disk fully in effect\&. If
276 "force"
277 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\&. If
278 "create"
279 a new loopback file is create under the path passed via the device node parameter, of the size indicated with
280 \fB\-\-size=\fR, see below\&.
281 .sp
282 Added in version 245\&.
283 .RE
284 .PP
285 \fB\-\-discard=\fR
286 .RS 4
287 Takes a boolean\&. If this switch is not specified ,\fB\-\-discard=yes\fR
288 is the implied default\&. Controls whether to issue the
289 \fBBLKDISCARD\fR
290 I/O control command on the space taken up by any added partitions or on the space in between them\&. Usually, it is a good idea to issue this request since it tells the underlying hardware that the covered blocks shall be considered empty, improving performance\&. If operating on a regular file instead of a block device node, a sparse file is generated\&.
291 .sp
292 Added in version 245\&.
293 .RE
294 .PP
295 \fB\-\-size=\fR
296 .RS 4
297 Takes a size in bytes, using the usual K, M, G, T suffixes, or the special value
298 "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
299 "auto"
300 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
301 \fB\-\-empty=create\fR
302 this specifies the initial size of the loopback file to create\&.
303 .sp
304 The
305 \fB\-\-size=auto\fR
306 option takes the sizes of pre\-existing partitions into account\&. However, it does not accommodate 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\&.
307 .sp
308 Also note that the automatic size determination does not take files or directories specified with
309 \fBCopyFiles=\fR
310 into account: operation might fail if the specified files or directories require more disk space then the configured per\-partition minimal size limit\&.
311 .sp
312 Added in version 246\&.
313 .RE
314 .PP
315 \fB\-\-factory\-reset=\fR
316 .RS 4
317 Takes boolean\&. If this switch is not specified,
318 \fB\-\-factory\-reset=no\fR
319 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
320 \fIFactoryReset=\fR
321 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
322 \fIFactoryReset=\fR
323 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\&.
324 .sp
325 Added in version 245\&.
326 .RE
327 .PP
328 \fB\-\-can\-factory\-reset\fR
329 .RS 4
330 If this switch is specified the disk is not re\-partitioned\&. Instead it is determined if any existing partitions are marked with
331 \fIFactoryReset=\fR\&. 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
332 \fBsystemd\-repart\fR\&.
333 .sp
334 Added in version 245\&.
335 .RE
336 .PP
337 \fB\-\-root=\fR
338 .RS 4
339 Takes a path to a directory to use as root file system when searching for
340 repart\&.d/*\&.conf
341 files, for the machine ID file to use as seed and for the
342 \fICopyFiles=\fR
343 and
344 \fICopyBlocks=\fR
345 source files and directories\&. By default when invoked on the regular system this defaults to the host\*(Aqs root file system
346 /\&. If invoked from the initrd this defaults to
347 /sysroot/, so that the tool operates on the configuration and machine ID stored in the root file system later transitioned into itself\&.
348 .sp
349 See
350 \fB\-\-copy\-source=\fR
351 for a more restricted option that only affects
352 \fICopyFiles=\fR\&.
353 .sp
354 Added in version 245\&.
355 .RE
356 .PP
357 \fB\-\-image=\fR
358 .RS 4
359 Takes a path to a disk image file or device to mount and use in a similar fashion to
360 \fB\-\-root=\fR, see above\&.
361 .sp
362 Added in version 249\&.
363 .RE
364 .PP
365 \fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
366 .RS 4
367 Takes an image policy string as argument, as per
368 \fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
369 \fB\-\-image=\fR, see above\&. If not specified, defaults to the
370 "*"
371 policy, i\&.e\&. all recognized file systems in the image are used\&.
372 .RE
373 .PP
374 \fB\-\-seed=\fR
375 .RS 4
376 Takes a UUID as argument or the special value
377 \fBrandom\fR\&. 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
378 \fB\-\-root=\fR) and use it as seed instead, falling back to a randomized seed otherwise\&. Use
379 \fB\-\-seed=random\fR
380 to force a randomized seed\&. Explicitly specifying the seed may be used to generated strictly reproducible partition tables\&.
381 .sp
382 Added in version 245\&.
383 .RE
384 .PP
385 \fB\-\-pretty=\fR
386 .RS 4
387 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\&.
388 .sp
389 Added in version 245\&.
390 .RE
391 .PP
392 \fB\-\-definitions=\fR
393 .RS 4
394 Takes a file system path\&. If specified the
395 *\&.conf
396 files are read from the specified directory instead of searching in
397 /usr/lib/repart\&.d/*\&.conf,
398 /etc/repart\&.d/*\&.conf,
399 /run/repart\&.d/*\&.conf\&.
400 .sp
401 This parameter can be specified multiple times\&.
402 .sp
403 Added in version 245\&.
404 .RE
405 .PP
406 \fB\-\-key\-file=\fR
407 .RS 4
408 Takes a file system path\&. Configures the encryption key to use when setting up LUKS2 volumes configured with the
409 \fIEncrypt=key\-file\fR
410 setting in partition files\&. Should refer to a regular file containing the key, or an
411 \fBAF_UNIX\fR
412 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\&.
413 .sp
414 Added in version 247\&.
415 .RE
416 .PP
417 \fB\-\-private\-key=\fR
418 .RS 4
419 Takes a file system path or an engine or provider specific designation\&. Configures the signing key to use when creating verity signature partitions with the
420 \fIVerity=signature\fR
421 setting in partition files\&.
422 .sp
423 Added in version 252\&.
424 .RE
425 .PP
426 \fB\-\-private\-key\-source=\fR
427 .RS 4
428 Takes one of
429 "file",
430 "engine"
431 or
432 "provider"\&. In the latter two cases, it is followed by the name of a provider or engine, separated by colon, that will be passed to OpenSSL\*(Aqs "engine" or "provider" logic\&. Configures how to load the private key to use when creating verity signature partitions with the
433 \fIVerity=signature\fR
434 setting in partition files\&.
435 .sp
436 Added in version 256\&.
437 .RE
438 .PP
439 \fB\-\-certificate=\fR
440 .RS 4
441 Takes a file system path or a provider specific designation\&. Configures the PEM encoded X\&.509 certificate to use when creating verity signature partitions with the
442 \fIVerity=signature\fR
443 setting in partition files\&.
444 .sp
445 Added in version 252\&.
446 .RE
447 .PP
448 \fB\-\-certificate\-source=\fR
449 .RS 4
450 Takes one of
451 "file", or
452 "provider"\&. In the latter case, it is followed by the name of a provider, separated by colon, that will be passed to OpenSSL\*(Aqs "provider" logic\&. Configures how to load the X\&.509 certificate to use when creating verity signature partitions with the
453 \fIVerity=signature\fR
454 setting in partition files\&.
455 .sp
456 Added in version 257\&.
457 .RE
458 .PP
459 \fB\-\-join\-signature=\fR
460 .RS 4
461 Specifies a colon\-separated tuple with a hex\-encoded top\-level Verity hash of a
462 \fIVerity=hash\fR
463 partition as first element, and a PKCS7 signature of the roothash as a path to a DER\-encoded signature file, or as an ASCII base64 string encoding of a DER\-encoded signature prefixed by
464 "base64:"\&. To be used on a pre\-existing image that was created with a parameter such as
465 \fB\-\-defer\-partitions=root\-verity\-sig\fR, in order to allow implementing offline signing of the verity signature partition\&.
466 .sp
467 This is an alternative to online signing using parameters such as
468 \fB\-\-private\-key=\fR, for build systems where the private key for production signing is not available in the same context where content is created\&.
469 .sp
470 Added in version 258\&.
471 .RE
472 .PP
473 \fB\-\-tpm2\-device=\fR, \fB\-\-tpm2\-pcrs=\fR
474 .RS 4
475 Configures the TPM2 device and list of PCRs to use for LUKS2 volumes configured with the
476 \fIEncrypt=tpm2\fR
477 option\&. These options take the same parameters as the identically named options to
478 \fBsystemd-cryptenroll\fR(1)
479 and have the same effect on partitions where TPM2 enrollment is requested\&.
480 .sp
481 Added in version 248\&.
482 .RE
483 .PP
484 \fB\-\-tpm2\-device\-key=\fR\fB\fIPATH\fR\fR, \fB\-\-tpm2\-seal\-key\-handle=\fR\fB\fIHANDLE\fR\fR
485 .RS 4
486 Configures a TPM2 SRK key to bind encryption to\&. See
487 \fBsystemd-cryptenroll\fR(1)
488 for details on this option\&.
489 .sp
490 Added in version 255\&.
491 .RE
492 .PP
493 \fB\-\-tpm2\-public\-key=\fR\fB\fIPATH\fR\fR, \fB\-\-tpm2\-public\-key\-pcrs=\fR\fB\fIPCR\fR\fI[+PCR\&.\&.\&.]\fR\fR
494 .RS 4
495 Configures a TPM2 signed PCR policy to bind encryption to\&. See
496 \fBsystemd-cryptenroll\fR(1)
497 for details on these two options\&.
498 .sp
499 Added in version 252\&.
500 .RE
501 .PP
502 \fB\-\-tpm2\-pcrlock=\fR\fB\fIPATH\fR\fR
503 .RS 4
504 Configures a TPM2 pcrlock policy to bind encryption to\&. See
505 \fBsystemd-cryptenroll\fR(1)
506 for details on this option\&.
507 .sp
508 Added in version 255\&.
509 .RE
510 .PP
511 \fB\-\-split=\fR\fB\fIBOOL\fR\fR
512 .RS 4
513 Enables generation of split artifacts from partitions configured with
514 \fISplitName=\fR\&. If enabled, for each partition with
515 \fISplitName=\fR
516 set, a separate output file containing just the contents of that partition is generated\&. The output filename consists of the loopback filename suffixed with the name configured with
517 \fISplitName=\fR\&. If the loopback filename ends with
518 "\&.raw", the suffix is inserted before the
519 "\&.raw"
520 extension instead\&.
521 .sp
522 Note that
523 \fB\-\-split\fR
524 is independent from
525 \fB\-\-dry\-run\fR\&. Even if
526 \fB\-\-dry\-run\fR
527 is enabled, split artifacts will still be generated from an existing image if
528 \fB\-\-split\fR
529 is enabled\&.
530 .sp
531 Added in version 252\&.
532 .RE
533 .PP
534 \fB\-\-include\-partitions=\fR\fB\fIPARTITIONS\fR\fR, \fB\-\-exclude\-partitions=\fR\fB\fIPARTITIONS\fR\fR
535 .RS 4
536 These options specify which partition types
537 \fBsystemd\-repart\fR
538 should operate on\&. If
539 \fB\-\-include\-partitions=\fR
540 is used, all partitions that are not specified are excluded\&. If
541 \fB\-\-exclude\-partitions=\fR
542 is used, all partitions that are specified are excluded\&. Both options take a comma separated list of GPT partition type UUIDs or identifiers (see
543 \fIType=\fR
544 in
545 \fBrepart.d\fR(5))\&.
546 .sp
547 Added in version 253\&.
548 .RE
549 .PP
550 \fB\-\-defer\-partitions=\fR\fB\fIPARTITIONS\fR\fR
551 .RS 4
552 This option specifies for which partition types
553 \fBsystemd\-repart\fR
554 should defer\&. All partitions that are deferred using this option are still taken into account when calculating the sizes and offsets of other partitions, but are not actually written to the disk image\&. The net effect of this option is that if you run
555 \fBsystemd\-repart\fR
556 again without this option, the missing partitions will be added as if they had not been deferred the first time
557 \fBsystemd\-repart\fR
558 was executed\&.
559 .sp
560 Added in version 253\&.
561 .RE
562 .PP
563 \fB\-\-sector\-size=\fR\fB\fIBYTES\fR\fR
564 .RS 4
565 This option allows configuring the sector size of the image produced by
566 \fBsystemd\-repart\fR\&. It takes a value that is a power of
567 "2"
568 between
569 "512"
570 and
571 "4096"\&. This option is useful when building images for disks that use a different sector size as the disk on which the image is produced\&.
572 .sp
573 Added in version 253\&.
574 .RE
575 .PP
576 \fB\-\-architecture=\fR\fB\fIARCH\fR\fR
577 .RS 4
578 This option allows overriding the architecture used for architecture specific partition types\&. For example, if set to
579 "arm64"
580 a partition type of
581 "root\-x86\-64"
582 referenced in
583 repart\&.d/
584 drop\-ins will be patched dynamically to refer to
585 "root\-arm64"
586 instead\&. Takes one of
587 "alpha",
588 "arc",
589 "arm",
590 "arm64",
591 "ia64",
592 "loongarch64",
593 "mips\-le",
594 "mips64\-le",
595 "parisc",
596 "ppc",
597 "ppc64",
598 "ppc64\-le",
599 "riscv32",
600 "riscv64",
601 "s390",
602 "s390x",
603 "tilegx",
604 "x86"
605 or
606 "x86\-64"\&.
607 .sp
608 Added in version 254\&.
609 .RE
610 .PP
611 \fB\-\-offline=\fR\fB\fIBOOL\fR\fR
612 .RS 4
613 Instructs
614 \fBsystemd\-repart\fR
615 to build the image offline\&. Takes a boolean or
616 "auto"\&. Defaults to
617 "auto"\&. If enabled, the image is built without using loop devices\&. This is useful to build images unprivileged or when loop devices are not available\&. If disabled, the image is always built using loop devices\&. If
618 "auto",
619 \fBsystemd\-repart\fR
620 will build the image online if possible and fall back to building the image offline if loop devices are not available or cannot be accessed due to missing permissions\&.
621 .sp
622 Added in version 254\&.
623 .RE
624 .PP
625 \fB\-\-copy\-from=\fR\fB\fIPATH\fR\fR
626 .RS 4
627 Instructs
628 \fBsystemd\-repart\fR
629 to synthesize partition definitions from the partition table in the given image or device\&. This option can be specified multiple times to synthesize definitions from each of the given images or devices\&. The generated definitions will copy the partitions into the destination partition table\&. The copied partitions will have the same size, metadata and contents but might have a different partition number and might be located at a different offset in the destination partition table\&. These definitions can be combined with partition definitions read from regular partition definition files\&. The synthesized definitions take precedence over the definitions read from partition definition files\&.
630 .sp
631 Added in version 255\&.
632 .RE
633 .PP
634 \fB\-\-copy\-source=\fR\fB\fIPATH\fR\fR, \fB\-s\fR \fIPATH\fR
635 .RS 4
636 Specifies a source directory all
637 \fICopyFiles=\fR
638 source paths shall be considered relative to\&. This is similar to
639 \fB\-\-root=\fR, but exclusively applies to the
640 \fICopyFiles=\fR
641 setting\&. If
642 \fB\-\-root=\fR
643 and
644 \fB\-\-copy\-source=\fR
645 are used in combination the former applies as usual, except for
646 \fICopyFiles=\fR
647 where the latter takes precedence\&.
648 .sp
649 Added in version 255\&.
650 .RE
651 .PP
652 \fB\-\-make\-ddi=\fR\fB\fITYPE\fR\fR
653 .RS 4
654 Takes one of
655 "sysext",
656 "confext"
657 or
658 "portable"\&. Generates a Discoverable Disk Image (DDI) for a system extension (sysext, see
659 \fBsystemd-sysext\fR(8)
660 for details), configuration extension (confext) or
661 \m[blue]\fBPortable Services\fR\m[]\&\s-2\u[1]\d\s+2\&. The generated image will consist of a signed Verity
662 "erofs"
663 file system as root partition\&. In this mode of operation the partition definitions in
664 /usr/lib/repart\&.d/*\&.conf
665 and related directories are not read, and
666 \fB\-\-definitions=\fR
667 is not supported, as appropriate definitions for the selected DDI class will be chosen automatically\&.
668 .sp
669 Must be used in conjunction with
670 \fB\-\-copy\-source=\fR
671 to specify the file hierarchy to populate the DDI with\&. The specified directory should contain an
672 etc/
673 subdirectory if
674 "confext"
675 is selected\&. If
676 "sysext"
677 is selected it should contain either a
678 usr/
679 or
680 opt/
681 directory, or both\&. If
682 "portable"
683 is used a full OS file hierarchy can be provided\&.
684 .sp
685 This option implies
686 \fB\-\-empty=create\fR,
687 \fB\-\-size=auto\fR
688 and
689 \fB\-\-seed=random\fR
690 (the latter two can be overridden)\&.
691 .sp
692 The private key and certificate for signing the DDI must be specified via the
693 \fB\-\-private\-key=\fR
694 and
695 \fB\-\-certificate=\fR
696 switches\&.
697 .sp
698 Added in version 255\&.
699 .RE
700 .PP
701 \fB\-S\fR, \fB\-C\fR, \fB\-P\fR
702 .RS 4
703 Shortcuts for
704 \fB\-\-make\-ddi=sysext\fR,
705 \fB\-\-make\-ddi=confext\fR,
706 \fB\-\-make\-ddi=portable\fR, respectively\&.
707 .sp
708 Added in version 255\&.
709 .RE
710 .PP
711 \fB\-\-append\-fstab=\fR
712 .RS 4
713 Takes one of
714 "no",
715 "auto"
716 or
717 "replace"\&. Controls how the generated
718 \fBfstab\fR(5)
719 file by
720 \fB\-\-generate\-fstab=\fR
721 will behave in case that there is a previously existing file\&.
722 .sp
723 If
724 "no"
725 \fBsystemd\-repart\fR
726 will complain and abort in case that there is a file\&. This is the default behaviour\&. If
727 "replace"
728 the file will be silently replaced with the new generated one\&.
729 .sp
730 If
731 "auto"
732 \fBsystemd\-repart\fR
733 will search in the pre\-existing file the section that belong to the automatically generated content and will replace it with the newer generated content, and keep the user provided section if there is one\&. The generated section is identified looking for the automatic content surrounded by
734 "# Start section ↓ of automatically generated fstab by systemd\-repart"
735 and
736 "# End section ↑ of automatically generated fstab by systemd\-repart"\&. The content that is before and after those comments are considered user provided, and kept in the new file\&.
737 .sp
738 Added in version 258\&.
739 .RE
740 .PP
741 \fB\-\-generate\-fstab=\fR\fB\fIPATH\fR\fR
742 .RS 4
743 Specifies a path where to write
744 \fBfstab\fR(5)
745 entries for the mountpoints configured with
746 \fBMountPoint=\fR
747 in the root directory specified with
748 \fB\-\-copy\-source=\fR
749 or
750 \fB\-\-root=\fR
751 or in the host\*(Aqs root directory if neither is specified\&. Disabled by default\&.
752 .sp
753 Added in version 256\&.
754 .RE
755 .PP
756 \fB\-\-generate\-crypttab=\fR\fB\fIPATH\fR\fR
757 .RS 4
758 Specifies a path where to write crypttab entries for the encrypted volumes configured with
759 \fBEncryptedVolume=\fR
760 in the root directory specified with
761 \fB\-\-copy\-source=\fR
762 or
763 \fB\-\-root=\fR
764 or in the host\*(Aqs root directory if neither is specified\&. Disabled by default\&.
765 .sp
766 Added in version 256\&.
767 .RE
768 .PP
769 \fB\-\-list\-devices\fR
770 .RS 4
771 Show a list of candidate block devices this command may operate on\&. Specifically, this enumerates block devices currently present that support partition tables, and shows their device node paths along with any of their symlinks\&.
772 .sp
773 Added in version 257\&.
774 .RE
775 .PP
776 \fB\-h\fR, \fB\-\-help\fR
777 .RS 4
778 Print a short help text and exit\&.
779 .RE
780 .PP
781 \fB\-\-version\fR
782 .RS 4
783 Print a short version string and exit\&.
784 .RE
785 .PP
786 \fB\-\-no\-pager\fR
787 .RS 4
788 Do not pipe output into a pager\&.
789 .RE
790 .PP
791 \fB\-\-no\-legend\fR
792 .RS 4
793 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
794 .RE
795 .PP
796 \fB\-\-json=\fR\fB\fIMODE\fR\fR
797 .RS 4
798 Shows output formatted as JSON\&. Expects one of
799 "short"
800 (for the shortest possible output without any redundant whitespace or line breaks),
801 "pretty"
802 (for a pretty version of the same, with indentation and line breaks) or
803 "off"
804 (to turn off JSON output, the default)\&.
805 .RE
806 .SH "EXIT STATUS"
807 .PP
808 On success, 0 is returned, and a non\-zero failure code otherwise\&.
809 .SH "EXAMPLE"
810 .PP
811 \fBExample\ \&1.\ \&Generate a configuration extension image\fR
812 .PP
813 The following creates a configuration extension DDI (confext) for an
814 /etc/motd
815 update:
816 .sp
817 .if n \{\
818 .RS 4
819 .\}
820 .nf
821 mkdir \-p tree/etc/extension\-release\&.d
822 echo "Hello World" >tree/etc/motd
823 cat >tree/etc/extension\-release\&.d/extension\-release\&.my\-motd <<EOF
824 ID=fedora
825 VERSION_ID=38
826 IMAGE_ID=my\-motd
827 IMAGE_VERSION=7
828 EOF
829 systemd\-repart \-C \e
830 \-\-private\-key=verity\-private\-key\&.pem \e
831 \-\-certificate=verity\-certificate\&.pem \e
832 \-s tree/ \e
833 /var/lib/confexts/my\-motd\&.confext\&.raw
834 systemd\-confext refresh
835 .fi
836 .if n \{\
837 .RE
838 .\}
839 .PP
840 The DDI generated that way may be applied to the system with
841 \fBsystemd-confext\fR(1)\&.
842 .PP
843 \fBExample\ \&2.\ \&Generate a system extension image and sign it via PKCS11\fR
844 .PP
845 The following creates a system extension DDI (sysext) for an
846 /usr/foo
847 update and signs it with a hardware token via PKCS11:
848 .sp
849 .if n \{\
850 .RS 4
851 .\}
852 .nf
853 mkdir \-p tree/usr/lib/extension\-release\&.d
854 echo "Hello World" >tree/usr/foo
855 cat >tree/usr/lib/extension\-release\&.d/extension\-release\&.my\-foo <<EOF
856 ID=fedora
857 VERSION_ID=38
858 IMAGE_ID=my\-foo
859 IMAGE_VERSION=7
860 EOF
861 systemd\-repart \-\-make\-ddi=sysext \e
862 \-\-private\-key\-source=engine:pkcs11 \e
863 \-\-private\-key="pkcs11:model=PKCS%2315%20emulated;manufacturer=piv_II;serial=0123456789abcdef;token=Some%20Cert" \e
864 \-\-certificate=verity\-certificate\&.pem \e
865 \-s tree/ \e
866 /var/lib/extensions/my\-foo\&.sysext\&.raw
867 systemd\-sysext refresh
868 .fi
869 .if n \{\
870 .RE
871 .\}
872 .PP
873 The DDI generated that way may be applied to the system with
874 \fBsystemd-sysext\fR(8)\&.
875 .PP
876 \fBExample\ \&3.\ \&Generate a dm\-verity signature offline and append it to a pre\-built image\fR
877 .PP
878 The following creates an image with dm\-verity metadata, signs it separately to simulate an offline signing system, and then appends the signature to the image:
879 .sp
880 .if n \{\
881 .RS 4
882 .\}
883 .nf
884 mkdir \-p repart\&.d/ /tmp/tree/usr/lib/
885
886 cat >/tmp/tree/usr/lib/os\-release <<EOF
887 ID=debian
888 VERSION_ID=13
889 EOF
890
891 cat >repart\&.d/10\-root\&.conf <<EOF
892 [Partition]
893 Type=root
894 Format=erofs
895 SizeMinBytes=100M
896 SizeMaxBytes=100M
897 Verity=data
898 VerityMatchKey=root
899 EOF
900
901 cat >repart\&.d/11\-root\-verity\&.conf <<EOF
902 [Partition]
903 Type=root\-verity
904 Label=%o_%w_verity
905 Verity=hash
906 VerityMatchKey=root
907 SizeMinBytes=400M
908 SizeMaxBytes=400M
909 EOF
910
911 cat >repart\&.d/12\-root\-verity\-sig\&.conf <<EOF
912 [Partition]
913 Type=root\-verity\-sig
914 Label=%o_%w_verity_sig
915 Verity=signature
916 VerityMatchKey=root
917 EOF
918
919 systemd\-repart \-\-definitions repart\&.d \e
920 \-\-defer\-partitions=root\-verity\-sig \e
921 \-\-copy\-source=/tmp/tree/ \e
922 \-\-empty=create \-\-size=600M \e
923 \-\-json=short \e
924 /tmp/img\&.raw | | jq \-\-raw\-output0 \&.[\-1]\&.roothash > /tmp/img\&.roothash
925
926 openssl smime \-sign \-in /tmp/img\&.roothash \e
927 \-inkey verity\-private\-key\&.pem \e
928 \-signer verity\-certificate\&.pem \e
929 \-noattr \-binary \-outform der \e
930 \-out /tmp/img\&.roothash\&.p7s
931
932 systemd\-repart \-\-definitions repart\&.d \e
933 \-\-dry\-run=no \-\-root=/tmp/tree/ \e
934 \-\-join\-signature="$(cat /tmp/img\&.roothash):/tmp/img\&.roothash\&.p7s" \e
935 \-\-certificate=verity\-certificate\&.pem \e
936 /tmp/img\&.raw
937 .fi
938 .if n \{\
939 .RE
940 .\}
941 .SH "SEE ALSO"
942 .PP
943 \fBsystemd\fR(1), \fBrepart.d\fR(5), \fBmachine-id\fR(5), \fBsystemd-cryptenroll\fR(1), \fBportablectl\fR(1), \fBsystemd-sysext\fR(8)
944 .SH "NOTES"
945 .IP " 1." 4
946 Portable Services
947 .RS 4
948 \%https://systemd.io/PORTABLE_SERVICES
949 .RE