Debian Codegraph @

upstream/debian-trixie/man8/systemd-repart.8

raw
1 '\" t
2 .TH "SYSTEMD\-REPART" "8" "" "systemd 257.13" "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 \fIFactoryReset\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\-\-tpm2\-device=\fR, \fB\-\-tpm2\-pcrs=\fR
460 .RS 4
461 Configures the TPM2 device and list of PCRs to use for LUKS2 volumes configured with the
462 \fIEncrypt=tpm2\fR
463 option\&. These options take the same parameters as the identically named options to
464 \fBsystemd-cryptenroll\fR(1)
465 and have the same effect on partitions where TPM2 enrollment is requested\&.
466 .sp
467 Added in version 248\&.
468 .RE
469 .PP
470 \fB\-\-tpm2\-device\-key=\fR\fB\fIPATH\fR\fR, \fB\-\-tpm2\-seal\-key\-handle=\fR\fB\fIHANDLE\fR\fR
471 .RS 4
472 Configures a TPM2 SRK key to bind encryption to\&. See
473 \fBsystemd-cryptenroll\fR(1)
474 for details on this option\&.
475 .sp
476 Added in version 255\&.
477 .RE
478 .PP
479 \fB\-\-tpm2\-public\-key=\fR\fB\fIPATH\fR\fR, \fB\-\-tpm2\-public\-key\-pcrs=\fR\fB\fIPCR\fR\fI[+PCR\&.\&.\&.]\fR\fR
480 .RS 4
481 Configures a TPM2 signed PCR policy to bind encryption to\&. See
482 \fBsystemd-cryptenroll\fR(1)
483 for details on these two options\&.
484 .sp
485 Added in version 252\&.
486 .RE
487 .PP
488 \fB\-\-tpm2\-pcrlock=\fR\fB\fIPATH\fR\fR
489 .RS 4
490 Configures a TPM2 pcrlock policy to bind encryption to\&. See
491 \fBsystemd-cryptenroll\fR(1)
492 for details on this option\&.
493 .sp
494 Added in version 255\&.
495 .RE
496 .PP
497 \fB\-\-split=\fR\fB\fIBOOL\fR\fR
498 .RS 4
499 Enables generation of split artifacts from partitions configured with
500 \fISplitName=\fR\&. If enabled, for each partition with
501 \fISplitName=\fR
502 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
503 \fISplitName=\fR\&. If the loopback filename ends with
504 "\&.raw", the suffix is inserted before the
505 "\&.raw"
506 extension instead\&.
507 .sp
508 Note that
509 \fB\-\-split\fR
510 is independent from
511 \fB\-\-dry\-run\fR\&. Even if
512 \fB\-\-dry\-run\fR
513 is enabled, split artifacts will still be generated from an existing image if
514 \fB\-\-split\fR
515 is enabled\&.
516 .sp
517 Added in version 252\&.
518 .RE
519 .PP
520 \fB\-\-include\-partitions=\fR\fB\fIPARTITIONS\fR\fR, \fB\-\-exclude\-partitions=\fR\fB\fIPARTITIONS\fR\fR
521 .RS 4
522 These options specify which partition types
523 \fBsystemd\-repart\fR
524 should operate on\&. If
525 \fB\-\-include\-partitions=\fR
526 is used, all partitions that are not specified are excluded\&. If
527 \fB\-\-exclude\-partitions=\fR
528 is used, all partitions that are specified are excluded\&. Both options take a comma separated list of GPT partition type UUIDs or identifiers (see
529 \fIType=\fR
530 in
531 \fBrepart.d\fR(5))\&.
532 .sp
533 Added in version 253\&.
534 .RE
535 .PP
536 \fB\-\-defer\-partitions=\fR\fB\fIPARTITIONS\fR\fR
537 .RS 4
538 This option specifies for which partition types
539 \fBsystemd\-repart\fR
540 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
541 \fBsystemd\-repart\fR
542 again without this option, the missing partitions will be added as if they had not been deferred the first time
543 \fBsystemd\-repart\fR
544 was executed\&.
545 .sp
546 Added in version 253\&.
547 .RE
548 .PP
549 \fB\-\-sector\-size=\fR\fB\fIBYTES\fR\fR
550 .RS 4
551 This option allows configuring the sector size of the image produced by
552 \fBsystemd\-repart\fR\&. It takes a value that is a power of
553 "2"
554 between
555 "512"
556 and
557 "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\&.
558 .sp
559 Added in version 253\&.
560 .RE
561 .PP
562 \fB\-\-architecture=\fR\fB\fIARCH\fR\fR
563 .RS 4
564 This option allows overriding the architecture used for architecture specific partition types\&. For example, if set to
565 "arm64"
566 a partition type of
567 "root\-x86\-64"
568 referenced in
569 repart\&.d/
570 drop\-ins will be patched dynamically to refer to
571 "root\-arm64"
572 instead\&. Takes one of
573 "alpha",
574 "arc",
575 "arm",
576 "arm64",
577 "ia64",
578 "loongarch64",
579 "mips\-le",
580 "mips64\-le",
581 "parisc",
582 "ppc",
583 "ppc64",
584 "ppc64\-le",
585 "riscv32",
586 "riscv64",
587 "s390",
588 "s390x",
589 "tilegx",
590 "x86"
591 or
592 "x86\-64"\&.
593 .sp
594 Added in version 254\&.
595 .RE
596 .PP
597 \fB\-\-offline=\fR\fB\fIBOOL\fR\fR
598 .RS 4
599 Instructs
600 \fBsystemd\-repart\fR
601 to build the image offline\&. Takes a boolean or
602 "auto"\&. Defaults to
603 "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
604 "auto",
605 \fBsystemd\-repart\fR
606 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\&.
607 .sp
608 Added in version 254\&.
609 .RE
610 .PP
611 \fB\-\-copy\-from=\fR\fB\fIIMAGE\fR\fR
612 .RS 4
613 Instructs
614 \fBsystemd\-repart\fR
615 to synthesize partition definitions from the partition table in the given image\&. This option can be specified multiple times to synthesize definitions from each of the given images\&. 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\&.
616 .sp
617 Added in version 255\&.
618 .RE
619 .PP
620 \fB\-\-copy\-source=\fR\fB\fIPATH\fR\fR, \fB\-s\fR \fIPATH\fR
621 .RS 4
622 Specifies a source directory all
623 \fICopyFiles=\fR
624 source paths shall be considered relative to\&. This is similar to
625 \fB\-\-root=\fR, but exclusively applies to the
626 \fICopyFiles=\fR
627 setting\&. If
628 \fB\-\-root=\fR
629 and
630 \fB\-\-copy\-source=\fR
631 are used in combination the former applies as usual, except for
632 \fICopyFiles=\fR
633 where the latter takes precedence\&.
634 .sp
635 Added in version 255\&.
636 .RE
637 .PP
638 \fB\-\-make\-ddi=\fR\fB\fITYPE\fR\fR
639 .RS 4
640 Takes one of
641 "sysext",
642 "confext"
643 or
644 "portable"\&. Generates a Discoverable Disk Image (DDI) for a system extension (sysext, see
645 \fBsystemd-sysext\fR(8)
646 for details), configuration extension (confext) or
647 \m[blue]\fBPortable Services\fR\m[]\&\s-2\u[1]\d\s+2\&. The generated image will consist of a signed Verity
648 "erofs"
649 file system as root partition\&. In this mode of operation the partition definitions in
650 /usr/lib/repart\&.d/*\&.conf
651 and related directories are not read, and
652 \fB\-\-definitions=\fR
653 is not supported, as appropriate definitions for the selected DDI class will be chosen automatically\&.
654 .sp
655 Must be used in conjunction with
656 \fB\-\-copy\-source=\fR
657 to specify the file hierarchy to populate the DDI with\&. The specified directory should contain an
658 etc/
659 subdirectory if
660 "confext"
661 is selected\&. If
662 "sysext"
663 is selected it should contain either a
664 usr/
665 or
666 opt/
667 directory, or both\&. If
668 "portable"
669 is used a full OS file hierarchy can be provided\&.
670 .sp
671 This option implies
672 \fB\-\-empty=create\fR,
673 \fB\-\-size=auto\fR
674 and
675 \fB\-\-seed=random\fR
676 (the latter two can be overridden)\&.
677 .sp
678 The private key and certificate for signing the DDI must be specified via the
679 \fB\-\-private\-key=\fR
680 and
681 \fB\-\-certificate=\fR
682 switches\&.
683 .sp
684 Added in version 255\&.
685 .RE
686 .PP
687 \fB\-S\fR, \fB\-C\fR, \fB\-P\fR
688 .RS 4
689 Shortcuts for
690 \fB\-\-make\-ddi=sysext\fR,
691 \fB\-\-make\-ddi=confext\fR,
692 \fB\-\-make\-ddi=portable\fR, respectively\&.
693 .sp
694 Added in version 255\&.
695 .RE
696 .PP
697 \fB\-\-generate\-fstab=\fR\fB\fIPATH\fR\fR
698 .RS 4
699 Specifies a path where to write
700 \fBfstab\fR(5)
701 entries for the mountpoints configured with
702 \fBMountPoint=\fR
703 in the root directory specified with
704 \fB\-\-copy\-source=\fR
705 or
706 \fB\-\-root=\fR
707 or in the host\*(Aqs root directory if neither is specified\&. Disabled by default\&.
708 .sp
709 Added in version 256\&.
710 .RE
711 .PP
712 \fB\-\-generate\-crypttab=\fR\fB\fIPATH\fR\fR
713 .RS 4
714 Specifies a path where to write crypttab entries for the encrypted volumes configured with
715 \fBEncryptedVolume=\fR
716 in the root directory specified with
717 \fB\-\-copy\-source=\fR
718 or
719 \fB\-\-root=\fR
720 or in the host\*(Aqs root directory if neither is specified\&. Disabled by default\&.
721 .sp
722 Added in version 256\&.
723 .RE
724 .PP
725 \fB\-\-list\-devices\fR
726 .RS 4
727 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\&.
728 .sp
729 Added in version 257\&.
730 .RE
731 .PP
732 \fB\-h\fR, \fB\-\-help\fR
733 .RS 4
734 Print a short help text and exit\&.
735 .RE
736 .PP
737 \fB\-\-version\fR
738 .RS 4
739 Print a short version string and exit\&.
740 .RE
741 .PP
742 \fB\-\-no\-pager\fR
743 .RS 4
744 Do not pipe output into a pager\&.
745 .RE
746 .PP
747 \fB\-\-no\-legend\fR
748 .RS 4
749 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
750 .RE
751 .PP
752 \fB\-\-json=\fR\fB\fIMODE\fR\fR
753 .RS 4
754 Shows output formatted as JSON\&. Expects one of
755 "short"
756 (for the shortest possible output without any redundant whitespace or line breaks),
757 "pretty"
758 (for a pretty version of the same, with indentation and line breaks) or
759 "off"
760 (to turn off JSON output, the default)\&.
761 .RE
762 .SH "EXIT STATUS"
763 .PP
764 On success, 0 is returned, and a non\-zero failure code otherwise\&.
765 .SH "EXAMPLE"
766 .PP
767 \fBExample\ \&1.\ \&Generate a configuration extension image\fR
768 .PP
769 The following creates a configuration extension DDI (confext) for an
770 /etc/motd
771 update:
772 .sp
773 .if n \{\
774 .RS 4
775 .\}
776 .nf
777 mkdir \-p tree/etc/extension\-release\&.d
778 echo "Hello World" >tree/etc/motd
779 cat >tree/etc/extension\-release\&.d/extension\-release\&.my\-motd <<EOF
780 ID=fedora
781 VERSION_ID=38
782 IMAGE_ID=my\-motd
783 IMAGE_VERSION=7
784 EOF
785 systemd\-repart \-C \e
786 \-\-private\-key=privkey\&.pem \e
787 \-\-certificate=cert\&.crt \e
788 \-s tree/ \e
789 /var/lib/confexts/my\-motd\&.confext\&.raw
790 systemd\-confext refresh
791 .fi
792 .if n \{\
793 .RE
794 .\}
795 .PP
796 The DDI generated that way may be applied to the system with
797 \fBsystemd-confext\fR(1)\&.
798 .PP
799 \fBExample\ \&2.\ \&Generate a system extension image and sign it via PKCS11\fR
800 .PP
801 The following creates a system extension DDI (sysext) for an
802 /usr/foo
803 update and signs it with a hardware token via PKCS11:
804 .sp
805 .if n \{\
806 .RS 4
807 .\}
808 .nf
809 mkdir \-p tree/usr/lib/extension\-release\&.d
810 echo "Hello World" >tree/usr/foo
811 cat >tree/usr/lib/extension\-release\&.d/extension\-release\&.my\-foo <<EOF
812 ID=fedora
813 VERSION_ID=38
814 IMAGE_ID=my\-foo
815 IMAGE_VERSION=7
816 EOF
817 systemd\-repart \-\-make\-ddi=sysext \e
818 \-\-private\-key\-source=engine:pkcs11 \e
819 \-\-private\-key="pkcs11:model=PKCS%2315%20emulated;manufacturer=piv_II;serial=0123456789abcdef;token=Some%20Cert" \e
820 \-\-certificate=cert\&.crt \e
821 \-s tree/ \e
822 /var/lib/extensions/my\-foo\&.sysext\&.raw
823 systemd\-sysext refresh
824 .fi
825 .if n \{\
826 .RE
827 .\}
828 .PP
829 The DDI generated that way may be applied to the system with
830 \fBsystemd-sysext\fR(8)\&.
831 .SH "SEE ALSO"
832 .PP
833 \fBsystemd\fR(1), \fBrepart.d\fR(5), \fBmachine-id\fR(5), \fBsystemd-cryptenroll\fR(1), \fBportablectl\fR(1), \fBsystemd-sysext\fR(8)
834 .SH "NOTES"
835 .IP " 1." 4
836 Portable Services
837 .RS 4
838 \%https://systemd.io/PORTABLE_SERVICES
839 .RE