Debian Codegraph @

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

raw
1 '\" t
2 .TH "SYSTEMD\-REPART" "8" "" "systemd 261~rc3" "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...] [BLOCKDEVICE]
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)\&. It operates on the block device or file image specified on the command line\&.
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 If the block device is specified as
53 "\-"
54 (or as an empty string),
55 \fBsystemd\-repart\fR
56 will not operate on any block device or image file, and instead determine and output the minimum disk/image size for the specified partition configuration, taking all configured size constraints into account\&.
57 .PP
58 \fBsystemd\-repart\fR
59 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
60 repart\&.d/*\&.conf
61 configuration files, it executes no operation\&.
62 .PP
63 The following use cases are among those covered:
64 .sp
65 .RS 4
66 .ie n \{\
67 \h'-04'\(bu\h'+03'\c
68 .\}
69 .el \{\
70 .sp -1
71 .IP \(bu 2.3
72 .\}
73 The root partition may be grown to cover the whole available disk space\&.
74 .RE
75 .sp
76 .RS 4
77 .ie n \{\
78 \h'-04'\(bu\h'+03'\c
79 .\}
80 .el \{\
81 .sp -1
82 .IP \(bu 2.3
83 .\}
84 A
85 /home/, swap, or
86 /srv/
87 partition can be added\&.
88 .RE
89 .sp
90 .RS 4
91 .ie n \{\
92 \h'-04'\(bu\h'+03'\c
93 .\}
94 .el \{\
95 .sp -1
96 .IP \(bu 2.3
97 .\}
98 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\&.
99 .RE
100 .PP
101 The algorithm executed by
102 \fBsystemd\-repart\fR
103 is roughly as follows:
104 .sp
105 .RS 4
106 .ie n \{\
107 \h'-04' 1.\h'+01'\c
108 .\}
109 .el \{\
110 .sp -1
111 .IP " 1." 4.2
112 .\}
113 The
114 repart\&.d/*\&.conf
115 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\&.
116 .RE
117 .sp
118 .RS 4
119 .ie n \{\
120 \h'-04' 2.\h'+01'\c
121 .\}
122 .el \{\
123 .sp -1
124 .IP " 2." 4.2
125 .\}
126 The partition table on the block device is loaded and parsed, if present\&.
127 .RE
128 .sp
129 .RS 4
130 .ie n \{\
131 \h'-04' 3.\h'+01'\c
132 .\}
133 .el \{\
134 .sp -1
135 .IP " 3." 4.2
136 .\}
137 The existing partitions in the partition table are matched with the
138 repart\&.d/*\&.conf
139 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\&.
140 .RE
141 .sp
142 .RS 4
143 .ie n \{\
144 \h'-04' 4.\h'+01'\c
145 .\}
146 .el \{\
147 .sp -1
148 .IP " 4." 4.2
149 .\}
150 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\&.
151 .RE
152 .sp
153 .RS 4
154 .ie n \{\
155 \h'-04' 5.\h'+01'\c
156 .\}
157 .el \{\
158 .sp -1
159 .IP " 5." 4.2
160 .\}
161 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\&.
162 .RE
163 .sp
164 .RS 4
165 .ie n \{\
166 \h'-04' 6.\h'+01'\c
167 .\}
168 .el \{\
169 .sp -1
170 .IP " 6." 4.2
171 .\}
172 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\&.
173 .RE
174 .sp
175 .RS 4
176 .ie n \{\
177 \h'-04' 7.\h'+01'\c
178 .\}
179 .el \{\
180 .sp -1
181 .IP " 7." 4.2
182 .\}
183 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\&.
184 .RE
185 .sp
186 .RS 4
187 .ie n \{\
188 \h'-04' 8.\h'+01'\c
189 .\}
190 .el \{\
191 .sp -1
192 .IP " 8." 4.2
193 .\}
194 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
195 \fBBLKDISCARD\fR
196 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\&.
197 .RE
198 .sp
199 .RS 4
200 .ie n \{\
201 \h'-04' 9.\h'+01'\c
202 .\}
203 .el \{\
204 .sp -1
205 .IP " 9." 4.2
206 .\}
207 The new partition table is finally written to disk\&. The kernel is asked to reread the partition table\&.
208 .RE
209 .PP
210 As an exception to the normal incremental operation, when called in a special "factory reset" mode,
211 \fBsystemd\-repart\fR
212 may be used to erase existing partitions to reset an installation back to vendor defaults\&. This mode of operation is used when either the
213 \fB\-\-factory\-reset=yes\fR
214 switch is passed on the tool\*(Aqs command line, or the
215 \fBsystemd\&.factory_reset=yes\fR
216 option is specified on the kernel command line, or the
217 \fIFactoryResetRequest\fR
218 EFI variable (vendor UUID
219 \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
220 \fIFactoryReset=\fR
221 boolean is deleted, and the algorithm restarted, thus immediately re\-creating these partitions anew empty\&.
222 .PP
223 Note that
224 \fBsystemd\-repart\fR
225 by default only changes partition tables, it does not create or resize any file systems within these partitions, unless the
226 \fIFormat=\fR
227 configuration option is specified\&. Also note that there are also separate mechanisms available for this purpose, for example
228 \fBsystemd-growfs\fR(8)
229 and
230 \fBsystemd\-makefs\fR\&.
231 .PP
232 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
233 \fBmachine-id\fR(5)
234 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
235 \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
236 \fB\-\-seed=\fR
237 option\&. By hashing these UUIDs from a common seed images prepared with this tool become reproducible and the result of the algorithm above deterministic\&.
238 .PP
239 The positional argument should specify the block device or a regular file to operate on\&. If
240 \fB\-\-empty=create\fR
241 is specified, the specified path is created as regular file, which is useful for generating disk images from scratch\&.
242 .SH "OPTIONS"
243 .PP
244 The following options are understood:
245 .PP
246 \fB\-\-dry\-run=\fR
247 .RS 4
248 Takes a boolean\&. If this switch is not specified,
249 \fB\-\-dry\-run=yes\fR
250 is the implied default\&. Controls whether
251 systemd\-repart
252 executes the requested re\-partition operations or whether it should only show what it would do\&. Unless
253 \fB\-\-dry\-run=no\fR
254 is specified
255 systemd\-repart
256 will not actually touch the device\*(Aqs partition table\&.
257 .sp
258 Added in version 245\&.
259 .RE
260 .PP
261 \fB\-\-empty=\fR
262 .RS 4
263 Takes one of
264 "refuse",
265 "allow",
266 "require",
267 "force"
268 or
269 "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
270 "refuse"\&.
271 .sp
272 If
273 "refuse"
274 \fBsystemd\-repart\fR
275 requires that the block device it shall operate on already carries a partition table and refuses operation if none is found\&. If
276 "allow"
277 the command will extend an existing partition table or create a new one if none exists\&. If
278 "require"
279 the command will create a new partition table if none exists so far, and refuse operation if one already exists\&. If
280 "force"
281 it will create a fresh partition table unconditionally, erasing the disk fully in effect\&. If
282 "force"
283 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
284 "create"
285 a new loopback file is create under the path passed via the device node parameter, of the size indicated with
286 \fB\-\-size=\fR, see below\&.
287 .sp
288 Added in version 245\&.
289 .RE
290 .PP
291 \fB\-\-discard=\fR
292 .RS 4
293 Takes a boolean\&. If this switch is not specified ,\fB\-\-discard=yes\fR
294 is the implied default\&. Controls whether to issue the
295 \fBBLKDISCARD\fR
296 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\&.
297 .sp
298 Added in version 245\&.
299 .RE
300 .PP
301 \fB\-\-size=\fR
302 .RS 4
303 Takes a size in bytes, using the usual K, M, G, T suffixes, or the special value
304 "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
305 "auto"
306 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
307 \fB\-\-empty=create\fR
308 this specifies the initial size of the loopback file to create\&.
309 .sp
310 The
311 \fB\-\-size=auto\fR
312 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\&.
313 .sp
314 Also note that the automatic size determination does not take files or directories specified with
315 \fBCopyFiles=\fR
316 into account: operation might fail if the specified files or directories require more disk space then the configured per\-partition minimal size limit\&.
317 .sp
318 Added in version 246\&.
319 .RE
320 .PP
321 \fB\-\-factory\-reset=\fR
322 .RS 4
323 Takes boolean\&. If this switch is not specified,
324 \fB\-\-factory\-reset=no\fR
325 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
326 \fIFactoryReset=\fR
327 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
328 \fIFactoryReset=\fR
329 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\&.
330 .sp
331 Added in version 245\&.
332 .RE
333 .PP
334 \fB\-\-can\-factory\-reset\fR
335 .RS 4
336 If this switch is specified the disk is not re\-partitioned\&. Instead it is determined if any existing partitions are marked with
337 \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
338 \fBsystemd\-repart\fR\&.
339 .sp
340 Added in version 245\&.
341 .RE
342 .PP
343 \fB\-\-root=\fR
344 .RS 4
345 Takes a path to a directory to use as root file system when searching for
346 repart\&.d/*\&.conf
347 files, for the machine ID file to use as seed and for the
348 \fICopyFiles=\fR
349 and
350 \fICopyBlocks=\fR
351 source files and directories\&. By default when invoked on the regular system this defaults to the host\*(Aqs root file system
352 /\&. If invoked from the initrd this defaults to
353 /sysroot/, so that the tool operates on the configuration and machine ID stored in the root file system later transitioned into itself\&.
354 .sp
355 See
356 \fB\-\-copy\-source=\fR
357 for a more restricted option that only affects
358 \fICopyFiles=\fR\&.
359 .sp
360 Added in version 245\&.
361 .RE
362 .PP
363 \fB\-\-image=\fR
364 .RS 4
365 Takes a path to a disk image file or device to mount and use in a similar fashion to
366 \fB\-\-root=\fR, see above\&.
367 .sp
368 Added in version 249\&.
369 .RE
370 .PP
371 \fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
372 .RS 4
373 Takes an image policy string as argument, as per
374 \fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on the disk image specified via
375 \fB\-\-image=\fR, see above\&. If not specified, defaults to the
376 "*"
377 policy, i\&.e\&. all recognized file systems in the image are used\&.
378 .RE
379 .PP
380 \fB\-\-seed=\fR
381 .RS 4
382 Takes a UUID as argument or the special value
383 \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
384 \fB\-\-root=\fR) and use it as seed instead, falling back to a randomized seed otherwise\&. Use
385 \fB\-\-seed=random\fR
386 to force a randomized seed\&. Explicitly specifying the seed may be used to generated strictly reproducible partition tables\&.
387 .sp
388 Added in version 245\&.
389 .RE
390 .PP
391 \fB\-\-pretty=\fR
392 .RS 4
393 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\&.
394 .sp
395 Added in version 245\&.
396 .RE
397 .PP
398 \fB\-\-definitions=\fR
399 .RS 4
400 Takes a file system path\&. If specified the
401 *\&.conf
402 files are read from the specified directory instead of searching in
403 /usr/lib/repart\&.d/*\&.conf,
404 /etc/repart\&.d/*\&.conf,
405 /run/repart\&.d/*\&.conf\&.
406 .sp
407 This parameter can be specified multiple times\&.
408 .sp
409 Added in version 245\&.
410 .RE
411 .PP
412 \fB\-\-key\-file=\fR
413 .RS 4
414 Takes a file system path\&. Configures the encryption key to use when setting up LUKS2 volumes configured with the
415 \fIEncrypt=key\-file\fR
416 setting in partition files\&. Should refer to a regular file containing the key, or an
417 \fBAF_UNIX\fR
418 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, and no
419 \fIKeyFile=\fR
420 is specified in the partition file, 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\&.
421 .sp
422 Added in version 247\&.
423 .RE
424 .PP
425 \fB\-\-private\-key=\fR
426 .RS 4
427 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
428 \fIVerity=signature\fR
429 setting in partition files\&.
430 .sp
431 Added in version 252\&.
432 .RE
433 .PP
434 \fB\-\-private\-key\-source=\fR
435 .RS 4
436 Takes one of
437 "file",
438 "engine"
439 or
440 "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
441 \fIVerity=signature\fR
442 setting in partition files\&.
443 .sp
444 Added in version 256\&.
445 .RE
446 .PP
447 \fB\-\-certificate=\fR
448 .RS 4
449 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
450 \fIVerity=signature\fR
451 setting in partition files\&.
452 .sp
453 Added in version 252\&.
454 .RE
455 .PP
456 \fB\-\-certificate\-source=\fR
457 .RS 4
458 Takes one of
459 "file", or
460 "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
461 \fIVerity=signature\fR
462 setting in partition files\&.
463 .sp
464 Added in version 257\&.
465 .RE
466 .PP
467 \fB\-\-join\-signature=\fR
468 .RS 4
469 Specifies a colon\-separated tuple with a hex\-encoded top\-level Verity hash of a
470 \fIVerity=hash\fR
471 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
472 "base64:"\&. To be used on a pre\-existing image that was created with a parameter such as
473 \fB\-\-defer\-partitions=root\-verity\-sig\fR, in order to allow implementing offline signing of the verity signature partition\&.
474 .sp
475 This is an alternative to online signing using parameters such as
476 \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\&.
477 .sp
478 Added in version 258\&.
479 .RE
480 .PP
481 \fB\-\-tpm2\-device=\fR, \fB\-\-tpm2\-pcrs=\fR
482 .RS 4
483 Configures the TPM2 device and list of PCRs to use for LUKS2 volumes configured with the
484 \fIEncrypt=tpm2\fR
485 option\&. These options take the same parameters as the identically named options to
486 \fBsystemd-cryptenroll\fR(1)
487 and have the same effect on partitions where TPM2 enrollment is requested\&.
488 .sp
489 Added in version 248\&.
490 .RE
491 .PP
492 \fB\-\-tpm2\-device\-key=\fR\fB\fIPATH\fR\fR, \fB\-\-tpm2\-seal\-key\-handle=\fR\fB\fIHANDLE\fR\fR
493 .RS 4
494 Configures a TPM2 SRK key to bind encryption to\&. See
495 \fBsystemd-cryptenroll\fR(1)
496 for details on this option\&.
497 .sp
498 Added in version 255\&.
499 .RE
500 .PP
501 \fB\-\-tpm2\-public\-key=\fR\fB\fIPATH\fR\fR, \fB\-\-tpm2\-public\-key\-pcrs=\fR\fB\fIPCR\fR\fI[+PCR\&.\&.\&.]\fR\fR
502 .RS 4
503 Configures a TPM2 signed PCR policy to bind encryption to\&. See
504 \fBsystemd-cryptenroll\fR(1)
505 for details on these two options\&.
506 .sp
507 Added in version 252\&.
508 .RE
509 .PP
510 \fB\-\-tpm2\-pcrlock=\fR\fB\fIPATH\fR\fR
511 .RS 4
512 Configures a TPM2 pcrlock policy to bind encryption to\&. See
513 \fBsystemd-cryptenroll\fR(1)
514 for details on this option\&.
515 .sp
516 Added in version 255\&.
517 .RE
518 .PP
519 \fB\-\-split=\fR\fB\fIBOOL\fR\fR
520 .RS 4
521 Enables generation of split artifacts from partitions configured with
522 \fISplitName=\fR\&. If enabled, for each partition with
523 \fISplitName=\fR
524 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
525 \fISplitName=\fR\&. If the loopback filename ends with
526 "\&.raw", the suffix is inserted before the
527 "\&.raw"
528 extension instead\&.
529 .sp
530 Note that
531 \fB\-\-split\fR
532 is independent from
533 \fB\-\-dry\-run\fR\&. Even if
534 \fB\-\-dry\-run\fR
535 is enabled, split artifacts will still be generated from an existing image if
536 \fB\-\-split\fR
537 is enabled\&.
538 .sp
539 Added in version 252\&.
540 .RE
541 .PP
542 \fB\-\-include\-partitions=\fR\fB\fIPARTITIONS\fR\fR, \fB\-\-exclude\-partitions=\fR\fB\fIPARTITIONS\fR\fR
543 .RS 4
544 These options specify which partition types
545 \fBsystemd\-repart\fR
546 should operate on\&. If
547 \fB\-\-include\-partitions=\fR
548 is used, all partitions that are not specified are excluded\&. If
549 \fB\-\-exclude\-partitions=\fR
550 is used, all partitions that are specified are excluded\&. Both options take a comma separated list of GPT partition type UUIDs or identifiers (see
551 \fIType=\fR
552 in
553 \fBrepart.d\fR(5))\&.
554 .sp
555 Added in version 253\&.
556 .RE
557 .PP
558 \fB\-\-defer\-partitions=\fR\fB\fIPARTITIONS\fR\fR
559 .RS 4
560 This option specifies for which partition types
561 \fBsystemd\-repart\fR
562 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
563 \fBsystemd\-repart\fR
564 again without this option, the missing partitions will be added as if they had not been deferred the first time
565 \fBsystemd\-repart\fR
566 was executed\&.
567 .sp
568 Added in version 253\&.
569 .RE
570 .PP
571 \fB\-\-defer\-partitions\-empty=yes\fR
572 .RS 4
573 This is very similar to
574 \fB\-\-defer\-partitions=\fR
575 but automatically selects all partitions for deferral that have
576 \fBFormat=empty\fR
577 set and do not configure a custom label, or which set
578 \fBLabel=_empty\fR\&. It may be used in conjunction with
579 \fB\-\-defer\-partitions=\fR
580 or
581 \fB\-\-defer\-partitions\-factory\-reset=yes\fR, in which case all matching partitions are deferred\&.
582 .sp
583 Added in version 259\&.
584 .RE
585 .PP
586 \fB\-\-defer\-partitions\-factory\-reset=yes\fR
587 .RS 4
588 This is very similar to
589 \fB\-\-defer\-partitions=\fR
590 but automatically selects all partitions for deferral that have
591 \fBFactoryReset=yes\fR
592 set\&. It may be used in conjunction with
593 \fB\-\-defer\-partitions=\fR
594 or
595 \fB\-\-defer\-partitions\-empty=yes\fR, in which case all matching partitions are deferred\&.
596 .sp
597 Added in version 259\&.
598 .RE
599 .PP
600 \fB\-\-sector\-size=\fR\fB\fIBYTES\fR\fR
601 .RS 4
602 This option allows configuring the sector size of the image produced by
603 \fBsystemd\-repart\fR\&. It takes a value that is a power of
604 "2"
605 between
606 "512"
607 and
608 "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\&.
609 .sp
610 Added in version 253\&.
611 .RE
612 .PP
613 \fB\-\-grain\-size=\fR\fB\fIBYTES\fR\fR
614 .RS 4
615 This option controls the partition alignment granularity used when placing partitions\&. It takes a power\-of\-2 value that is at least the sector size\&. All partition start offsets will be rounded up to a multiple of this value\&. Defaults to
616 \fBMAX(4096, sector_size)\fR, matching the conventional 4 KiB alignment\&. Setting this to
617 "1M"
618 ensures proper alignment for modern storage devices even after small fixed\-size partitions such as a verity signature partition\&.
619 .sp
620 Added in version 261\&.
621 .RE
622 .PP
623 \fB\-\-architecture=\fR\fB\fIARCH\fR\fR
624 .RS 4
625 This option allows overriding the architecture used for architecture specific partition types\&. For example, if set to
626 "arm64"
627 a partition type of
628 "root\-x86\-64"
629 referenced in
630 repart\&.d/
631 drop\-ins will be patched dynamically to refer to
632 "root\-arm64"
633 instead\&. Takes one of
634 "alpha",
635 "arc",
636 "arm",
637 "arm64",
638 "ia64",
639 "loongarch64",
640 "mips\-le",
641 "mips64\-le",
642 "parisc",
643 "ppc",
644 "ppc64",
645 "ppc64\-le",
646 "riscv32",
647 "riscv64",
648 "s390",
649 "s390x",
650 "tilegx",
651 "x86"
652 or
653 "x86\-64"\&.
654 .sp
655 Added in version 254\&.
656 .RE
657 .PP
658 \fB\-\-offline=\fR\fB\fIBOOL\fR\fR
659 .RS 4
660 Instructs
661 \fBsystemd\-repart\fR
662 to build the image offline\&. Takes a boolean or
663 "auto"\&. Defaults to
664 "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
665 "auto",
666 \fBsystemd\-repart\fR
667 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\&.
668 .sp
669 Added in version 254\&.
670 .RE
671 .PP
672 \fB\-\-copy\-from=\fR\fB\fIPATH\fR\fR
673 .RS 4
674 Instructs
675 \fBsystemd\-repart\fR
676 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\&.
677 .sp
678 Added in version 255\&.
679 .RE
680 .PP
681 \fB\-\-copy\-source=\fR\fB\fIPATH\fR\fR, \fB\-s\fR \fIPATH\fR
682 .RS 4
683 Specifies a source directory all
684 \fICopyFiles=\fR
685 source paths shall be considered relative to\&. This is similar to
686 \fB\-\-root=\fR, but exclusively applies to the
687 \fICopyFiles=\fR
688 setting\&. If
689 \fB\-\-root=\fR
690 and
691 \fB\-\-copy\-source=\fR
692 are used in combination the former applies as usual, except for
693 \fICopyFiles=\fR
694 where the latter takes precedence\&.
695 .sp
696 Added in version 255\&.
697 .RE
698 .PP
699 \fB\-\-make\-ddi=\fR\fB\fITYPE\fR\fR
700 .RS 4
701 Takes one of
702 "sysext",
703 "confext"
704 or
705 "portable"\&. Generates a Discoverable Disk Image (DDI) for a system extension (sysext, see
706 \fBsystemd-sysext\fR(8)
707 for details), configuration extension (confext) or
708 \m[blue]\fBPortable Services\fR\m[]\&\s-2\u[1]\d\s+2\&. The generated image will consist of a signed Verity
709 "erofs"
710 file system as root partition\&. In this mode of operation the partition definitions in
711 /usr/lib/repart\&.d/*\&.conf
712 and related directories are not read, and
713 \fB\-\-definitions=\fR
714 is not supported, as appropriate definitions for the selected DDI class will be chosen automatically\&.
715 .sp
716 Must be used in conjunction with
717 \fB\-\-copy\-source=\fR
718 to specify the file hierarchy to populate the DDI with\&. The specified directory should contain an
719 etc/
720 subdirectory if
721 "confext"
722 is selected\&. If
723 "sysext"
724 is selected it should contain either a
725 usr/
726 or
727 opt/
728 directory, or both\&. If
729 "portable"
730 is used a full OS file hierarchy can be provided\&.
731 .sp
732 This option implies
733 \fB\-\-empty=create\fR,
734 \fB\-\-size=auto\fR
735 and
736 \fB\-\-seed=random\fR
737 (the latter two can be overridden)\&.
738 .sp
739 The private key and certificate for signing the DDI must be specified via the
740 \fB\-\-private\-key=\fR
741 and
742 \fB\-\-certificate=\fR
743 switches\&.
744 .sp
745 Added in version 255\&.
746 .RE
747 .PP
748 \fB\-S\fR, \fB\-C\fR, \fB\-P\fR
749 .RS 4
750 Shortcuts for
751 \fB\-\-make\-ddi=sysext\fR,
752 \fB\-\-make\-ddi=confext\fR,
753 \fB\-\-make\-ddi=portable\fR, respectively\&.
754 .sp
755 Added in version 255\&.
756 .RE
757 .PP
758 \fB\-\-append\-fstab=\fR
759 .RS 4
760 Takes one of
761 "no",
762 "auto"
763 or
764 "replace"\&. Controls how the generated
765 \fBfstab\fR(5)
766 file by
767 \fB\-\-generate\-fstab=\fR
768 will behave in case that there is a previously existing file\&.
769 .sp
770 If
771 "no"
772 \fBsystemd\-repart\fR
773 will complain and abort in case that there is a file\&. This is the default behaviour\&. If
774 "replace"
775 the file will be silently replaced with the new generated one\&.
776 .sp
777 If
778 "auto"
779 \fBsystemd\-repart\fR
780 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
781 "# Start section ↓ of automatically generated fstab by systemd\-repart"
782 and
783 "# 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\&.
784 .sp
785 Added in version 258\&.
786 .RE
787 .PP
788 \fB\-\-generate\-fstab=\fR\fB\fIPATH\fR\fR
789 .RS 4
790 Specifies a path where to write
791 \fBfstab\fR(5)
792 entries for the mountpoints configured with
793 \fBMountPoint=\fR
794 in the root directory specified with
795 \fB\-\-copy\-source=\fR
796 or
797 \fB\-\-root=\fR
798 or in the host\*(Aqs root directory if neither is specified\&. Disabled by default\&.
799 .sp
800 Added in version 256\&.
801 .RE
802 .PP
803 \fB\-\-generate\-crypttab=\fR\fB\fIPATH\fR\fR
804 .RS 4
805 Specifies a path where to write crypttab entries for the encrypted volumes configured with
806 \fBEncryptedVolume=\fR
807 in the root directory specified with
808 \fB\-\-copy\-source=\fR
809 or
810 \fB\-\-root=\fR
811 or in the host\*(Aqs root directory if neither is specified\&. Disabled by default\&.
812 .sp
813 Added in version 256\&.
814 .RE
815 .PP
816 \fB\-\-list\-devices\fR
817 .RS 4
818 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\&.
819 .sp
820 Added in version 257\&.
821 .RE
822 .PP
823 \fB\-\-el\-torito=\fR\fB\fIBOOL\fR\fR
824 .RS 4
825 Write a minimal ISO9660 header with El Torito boot catalog\&. That will boot the ESP on EFI firmware\&.
826 .sp
827 The ISO9660 filesystem created by it will be empty\&. The initramfs is expected to create a partitionable loop device on top of the device to change the block size and enable GPT partitions\&.
828 .sp
829 The disk requires at least one partition with
830 \fIType=esp\fR\&. The first one will be the one referenced in the boot catalog\&.
831 .sp
832 Added in version 261\&.
833 .RE
834 .PP
835 \fB\-\-el\-torito\-system=\fR\fB\fISTRING\fR\fR
836 .RS 4
837 When creating an ISO9660 header, this value will be used as the system identifier\&. This is useful for the media to be matched against osinfo db\&.
838 .sp
839 The value is limited to 32 characters\&.
840 .sp
841 Added in version 261\&.
842 .RE
843 .PP
844 \fB\-\-el\-torito\-volume=\fR\fB\fISTRING\fR\fR
845 .RS 4
846 When creating an ISO9660 header, this value will be used as volume identifier\&. This is useful for the media to be matched against osinfo db\&.
847 .sp
848 The value is limited to 32 characters\&.
849 .sp
850 Added in version 261\&.
851 .RE
852 .PP
853 \fB\-\-el\-torito\-publisher=\fR\fB\fISTRING\fR\fR
854 .RS 4
855 When creating an ISO9660 header, this value will be used as publisher identifier\&. This is useful for the media to be matched against osinfo db\&.
856 .sp
857 The value is limited to 128 characters\&.
858 .sp
859 Added in version 261\&.
860 .RE
861 .PP
862 \fB\-h\fR, \fB\-\-help\fR
863 .RS 4
864 Print a short help text and exit\&.
865 .RE
866 .PP
867 \fB\-\-version\fR
868 .RS 4
869 Print a short version string and exit\&.
870 .RE
871 .PP
872 \fB\-\-no\-pager\fR
873 .RS 4
874 Do not pipe output into a pager\&.
875 .RE
876 .PP
877 \fB\-\-no\-legend\fR
878 .RS 4
879 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
880 .RE
881 .PP
882 \fB\-\-json=\fR\fB\fIMODE\fR\fR
883 .RS 4
884 Shows output formatted as JSON\&. Expects one of
885 "short"
886 (for the shortest possible output without any redundant whitespace or line breaks),
887 "pretty"
888 (for a pretty version of the same, with indentation and line breaks) or
889 "off"
890 (to turn off JSON output, the default)\&.
891 .RE
892 .SH "EXIT STATUS"
893 .PP
894 On success, 0 is returned, and a non\-zero failure code otherwise\&.
895 .SH "EXAMPLE"
896 .PP
897 \fBExample\ \&1.\ \&Generate a configuration extension image\fR
898 .PP
899 The following creates a configuration extension DDI (confext) for an
900 /etc/motd
901 update:
902 .sp
903 .if n \{\
904 .RS 4
905 .\}
906 .nf
907 mkdir \-p tree/etc/extension\-release\&.d
908 echo "Hello World" >tree/etc/motd
909 cat >tree/etc/extension\-release\&.d/extension\-release\&.my\-motd <<EOF
910 ID=fedora
911 VERSION_ID=38
912 IMAGE_ID=my\-motd
913 IMAGE_VERSION=7
914 EOF
915 systemd\-repart \-C \e
916 \-\-private\-key=verity\-private\-key\&.pem \e
917 \-\-certificate=verity\-certificate\&.pem \e
918 \-s tree/ \e
919 /var/lib/confexts/my\-motd\&.confext\&.raw
920 systemd\-confext refresh
921 .fi
922 .if n \{\
923 .RE
924 .\}
925 .PP
926 The DDI generated that way may be applied to the system with
927 \fBsystemd-confext\fR(1)\&.
928 .PP
929 \fBExample\ \&2.\ \&Generate a system extension image and sign it via PKCS11\fR
930 .PP
931 The following creates a system extension DDI (sysext) for an
932 /usr/foo
933 update and signs it with a hardware token via PKCS11:
934 .sp
935 .if n \{\
936 .RS 4
937 .\}
938 .nf
939 mkdir \-p tree/usr/lib/extension\-release\&.d
940 echo "Hello World" >tree/usr/foo
941 cat >tree/usr/lib/extension\-release\&.d/extension\-release\&.my\-foo <<EOF
942 ID=fedora
943 VERSION_ID=38
944 IMAGE_ID=my\-foo
945 IMAGE_VERSION=7
946 EOF
947 systemd\-repart \-\-make\-ddi=sysext \e
948 \-\-private\-key\-source=engine:pkcs11 \e
949 \-\-private\-key="pkcs11:model=PKCS%2315%20emulated;manufacturer=piv_II;serial=0123456789abcdef;token=Some%20Cert" \e
950 \-\-certificate=verity\-certificate\&.pem \e
951 \-s tree/ \e
952 /var/lib/extensions/my\-foo\&.sysext\&.raw
953 systemd\-sysext refresh
954 .fi
955 .if n \{\
956 .RE
957 .\}
958 .PP
959 The DDI generated that way may be applied to the system with
960 \fBsystemd-sysext\fR(8)\&.
961 .PP
962 \fBExample\ \&3.\ \&Generate a dm\-verity signature offline and append it to a pre\-built image\fR
963 .PP
964 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:
965 .sp
966 .if n \{\
967 .RS 4
968 .\}
969 .nf
970 mkdir \-p repart\&.d/ /tmp/tree/usr/lib/
971
972 cat >/tmp/tree/usr/lib/os\-release <<EOF
973 ID=debian
974 VERSION_ID=13
975 EOF
976
977 cat >repart\&.d/10\-root\&.conf <<EOF
978 [Partition]
979 Type=root
980 Format=erofs
981 SizeMinBytes=100M
982 SizeMaxBytes=100M
983 Verity=data
984 VerityMatchKey=root
985 EOF
986
987 cat >repart\&.d/11\-root\-verity\&.conf <<EOF
988 [Partition]
989 Type=root\-verity
990 Label=%o_%w_verity
991 Verity=hash
992 VerityMatchKey=root
993 SizeMinBytes=400M
994 SizeMaxBytes=400M
995 EOF
996
997 cat >repart\&.d/12\-root\-verity\-sig\&.conf <<EOF
998 [Partition]
999 Type=root\-verity\-sig
1000 Label=%o_%w_verity_sig
1001 Verity=signature
1002 VerityMatchKey=root
1003 EOF
1004
1005 systemd\-repart \-\-definitions repart\&.d \e
1006 \-\-defer\-partitions=root\-verity\-sig \e
1007 \-\-copy\-source=/tmp/tree/ \e
1008 \-\-empty=create \-\-size=600M \e
1009 \-\-json=short \e
1010 /tmp/img\&.raw | jq \-\-raw\-output0 "\&.[\-1]\&.roothash" > /tmp/img\&.roothash
1011
1012 openssl smime \-sign \-in /tmp/img\&.roothash \e
1013 \-inkey verity\-private\-key\&.pem \e
1014 \-signer verity\-certificate\&.pem \e
1015 \-noattr \-binary \-outform der \e
1016 \-out /tmp/img\&.roothash\&.p7s
1017
1018 systemd\-repart \-\-definitions repart\&.d \e
1019 \-\-dry\-run=no \-\-root=/tmp/tree/ \e
1020 \-\-join\-signature="$(cat /tmp/img\&.roothash):/tmp/img\&.roothash\&.p7s" \e
1021 \-\-certificate=verity\-certificate\&.pem \e
1022 /tmp/img\&.raw
1023 .fi
1024 .if n \{\
1025 .RE
1026 .\}
1027 .SH "SEE ALSO"
1028 .PP
1029 \fBsystemd\fR(1), \fBrepart.d\fR(5), \fBmachine-id\fR(5), \fBsystemd-cryptenroll\fR(1), \fBportablectl\fR(1), \fBsystemd-sysext\fR(8)
1030 .SH "NOTES"
1031 .IP " 1." 4
1032 Portable Services
1033 .RS 4
1034 \%https://systemd.io/PORTABLE_SERVICES
1035 .RE