Debian Codegraph @

upstream/debian-trixie/man5/repart.d.5

raw
1 '\" t
2 .TH "REPART\&.D" "5" "" "systemd 257.13" "repart.d"
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 repart.d \- Partition Definition Files for Automatic Boot\-Time Repartitioning
24 .SH "SYNOPSIS"
25 .PP
26 .RS 4
27 /etc/repart\&.d/*\&.conf
28 .RE
29 .RS 4
30 /run/repart\&.d/*\&.conf
31 .RE
32 .RS 4
33 /usr/local/lib/repart\&.d/*\&.conf
34 .RE
35 .RS 4
36 /usr/lib/repart\&.d/*\&.conf
37 .RE
38 .SH "DESCRIPTION"
39 .PP
40 repart\&.d/*\&.conf
41 files describe basic properties of partitions of block devices of the local system\&. They may be used to declare types, names and sizes of partitions that shall exist\&. The
42 \fBsystemd-repart\fR(8)
43 service reads these files and attempts to add new partitions currently missing and enlarge existing partitions according to these definitions\&. Operation is generally incremental, i\&.e\&. when applied, what exists already is left intact, and partitions are never shrunk, moved or deleted\&.
44 .PP
45 These definition files are useful for implementing operating system images that are prepared and delivered with minimally sized images (for example lacking any state or swap partitions), and which on first boot automatically take possession of any remaining disk space following a few basic rules\&.
46 .PP
47 Currently, support for partition definition files is only implemented for GPT partition tables\&.
48 .PP
49 Partition files are generally matched against any partitions already existing on disk in a simple algorithm: the partition files are sorted by their filename (ignoring the directory prefix), and then compared in order against existing partitions matching the same partition type UUID\&. Specifically, the first existing partition with a specific partition type UUID is assigned the first definition file with the same partition type UUID, and the second existing partition with a specific type UUID the second partition file with the same type UUID, and so on\&. Any left\-over partition files that have no matching existing partition are assumed to define new partition that shall be created\&. Such partitions are appended to the end of the partition table, in the order defined by their names utilizing the first partition slot greater than the highest slot number currently in use\&. Any existing partitions that have no matching partition file are left as they are\&.
50 .PP
51 Note that these definitions may only be used to create and initialize new partitions or to grow existing ones\&. In the latter case, it will not grow the contained files systems however; separate mechanisms, such as
52 \fBsystemd-growfs\fR(8)
53 may be used to grow the file systems inside of these partitions\&. Partitions may also be marked for automatic growing via the
54 \fIGrowFileSystem=\fR
55 setting, in which case the file system is grown on first mount by tools that respect this flag\&. See below for details\&.
56 .SH "[PARTITION] SECTION OPTIONS"
57 .PP
58 \fIType=\fR
59 .RS 4
60 The GPT partition type UUID to match\&. This may be a GPT partition type UUID such as
61 \fB4f68bce3\-e8cd\-4db1\-96e7\-fbcaf984b709\fR, or an identifier\&.
62 .sp
63 The supported identifiers are:
64 .sp
65 .it 1 an-trap
66 .nr an-no-space-flag 1
67 .nr an-break-flag 1
68 .br
69 .B Table\ \&1.\ \&GPT partition type identifiers
70 .TS
71 allbox tab(:);
72 lB lB.
73 T{
74 Identifier
75 T}:T{
76 Explanation
77 T}
78 .T&
79 l l
80 l l
81 l l
82 l l
83 l l
84 l l
85 l l
86 l l
87 l l
88 l l
89 l l
90 l l
91 l l
92 l l
93 l l
94 l l
95 l l
96 l l
97 l l
98 l l
99 l l
100 l l
101 l l
102 l l
103 l l
104 l l.
105 T{
106 \fBesp\fR
107 T}:T{
108 EFI System Partition
109 T}
110 T{
111 \fBxbootldr\fR
112 T}:T{
113 Extended Boot Loader Partition
114 T}
115 T{
116 \fBswap\fR
117 T}:T{
118 Swap partition
119 T}
120 T{
121 \fBhome\fR
122 T}:T{
123 Home (/home/) partition
124 T}
125 T{
126 \fBsrv\fR
127 T}:T{
128 Server data (/srv/) partition
129 T}
130 T{
131 \fBvar\fR
132 T}:T{
133 Variable data (/var/) partition
134 T}
135 T{
136 \fBtmp\fR
137 T}:T{
138 Temporary data (/var/tmp/) partition
139 T}
140 T{
141 \fBlinux\-generic\fR
142 T}:T{
143 Generic Linux file system partition
144 T}
145 T{
146 \fBroot\fR
147 T}:T{
148 Root file system partition type appropriate for the local architecture (an alias for an architecture root file system partition type listed below, e\&.g\&. \fBroot\-x86\-64\fR)
149 T}
150 T{
151 \fBroot\-verity\fR
152 T}:T{
153 Verity data for the root file system partition for the local architecture
154 T}
155 T{
156 \fBroot\-verity\-sig\fR
157 T}:T{
158 Verity signature data for the root file system partition for the local architecture
159 T}
160 T{
161 \fBroot\-secondary\fR
162 T}:T{
163 Root file system partition of the secondary architecture of the local architecture (usually the matching 32\-bit architecture for the local 64\-bit architecture)
164 T}
165 T{
166 \fBroot\-secondary\-verity\fR
167 T}:T{
168 Verity data for the root file system partition of the secondary architecture
169 T}
170 T{
171 \fBroot\-secondary\-verity\-sig\fR
172 T}:T{
173 Verity signature data for the root file system partition of the secondary architecture
174 T}
175 T{
176 \fBroot\-{arch}\fR
177 T}:T{
178 Root file system partition of the given architecture (such as \fBroot\-x86\-64\fR or \fBroot\-riscv64\fR)
179 T}
180 T{
181 \fBroot\-{arch}\-verity\fR
182 T}:T{
183 Verity data for the root file system partition of the given architecture
184 T}
185 T{
186 \fBroot\-{arch}\-verity\-sig\fR
187 T}:T{
188 Verity signature data for the root file system partition of the given architecture
189 T}
190 T{
191 \fBusr\fR
192 T}:T{
193 /usr/ file system partition type appropriate for the local architecture (an alias for an architecture /usr/ file system partition type listed below, e\&.g\&. \fBusr\-x86\-64\fR)
194 T}
195 T{
196 \fBusr\-verity\fR
197 T}:T{
198 Verity data for the /usr/ file system partition for the local architecture
199 T}
200 T{
201 \fBusr\-verity\-sig\fR
202 T}:T{
203 Verity signature data for the /usr/ file system partition for the local architecture
204 T}
205 T{
206 \fBusr\-secondary\fR
207 T}:T{
208 /usr/ file system partition of the secondary architecture of the local architecture (usually the matching 32\-bit architecture for the local 64\-bit architecture)
209 T}
210 T{
211 \fBusr\-secondary\-verity\fR
212 T}:T{
213 Verity data for the /usr/ file system partition of the secondary architecture
214 T}
215 T{
216 \fBusr\-secondary\-verity\-sig\fR
217 T}:T{
218 Verity signature data for the /usr/ file system partition of the secondary architecture
219 T}
220 T{
221 \fBusr\-{arch}\fR
222 T}:T{
223 /usr/ file system partition of the given architecture
224 T}
225 T{
226 \fBusr\-{arch}\-verity\fR
227 T}:T{
228 Verity data for the /usr/ file system partition of the given architecture
229 T}
230 T{
231 \fBusr\-{arch}\-verity\-sig\fR
232 T}:T{
233 Verity signature data for the /usr/ file system partition of the given architecture
234 T}
235 .TE
236 .sp 1
237 Architecture specific partition types can use one of these architecture identifiers:
238 \fBalpha\fR,
239 \fBarc\fR,
240 \fBarm\fR
241 (32\-bit),
242 \fBarm64\fR
243 (64\-bit, aka aarch64),
244 \fBia64\fR,
245 \fBloongarch64\fR,
246 \fBmips\-le\fR,
247 \fBmips64\-le\fR,
248 \fBparisc\fR,
249 \fBppc\fR,
250 \fBppc64\fR,
251 \fBppc64\-le\fR,
252 \fBriscv32\fR,
253 \fBriscv64\fR,
254 \fBs390\fR,
255 \fBs390x\fR,
256 \fBtilegx\fR,
257 \fBx86\fR
258 (32\-bit, aka i386) and
259 \fBx86\-64\fR
260 (64\-bit, aka amd64)\&.
261 .sp
262 Most of the partition type UUIDs listed above are defined in the
263 \m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&.
264 .sp
265 Added in version 245\&.
266 .RE
267 .PP
268 \fILabel=\fR
269 .RS 4
270 The textual label to assign to the partition if none is assigned yet\&. Note that this setting is not used for matching\&. It is also not used when a label is already set for an existing partition\&. It is thus only used when a partition is newly created or when an existing one had a no label set (that is: an empty label)\&. If not specified, a label derived from the partition type is automatically used\&. Simple specifier expansion is supported, see below\&.
271 .sp
272 Added in version 245\&.
273 .RE
274 .PP
275 \fIUUID=\fR
276 .RS 4
277 The UUID to assign to the partition if none is assigned yet\&. Note that this setting is not used for matching\&. It is also not used when a UUID is already set for an existing partition\&. It is thus only used when a partition is newly created or when an existing one had a all\-zero UUID set\&. If set to
278 "null", the UUID is set to all zeroes\&. If not specified a UUID derived from the partition type is automatically used\&.
279 .sp
280 Added in version 246\&.
281 .RE
282 .PP
283 \fIPriority=\fR
284 .RS 4
285 A numeric priority to assign to this partition, in the range \-2147483648\&...2147483647, with smaller values indicating higher priority, and higher values indicating smaller priority\&. This priority is used in case the configured size constraints on the defined partitions do not permit fitting all partitions onto the available disk space\&. If the partitions do not fit, the highest numeric partition priority of all defined partitions is determined, and all defined partitions with this priority are removed from the list of new partitions to create (which may be multiple, if the same priority is used for multiple partitions)\&. The fitting algorithm is then tried again\&. If the partitions still do not fit, the now highest numeric partition priority is determined, and the matching partitions removed too, and so on\&. Partitions of a priority of 0 or lower are never removed\&. If all partitions with a priority above 0 are removed and the partitions still do not fit on the device the operation fails\&. Note that this priority has no effect on ordering partitions, for that use the alphabetical order of the filenames of the partition definition files\&. Defaults to 0\&.
286 .sp
287 Added in version 245\&.
288 .RE
289 .PP
290 \fIWeight=\fR
291 .RS 4
292 A numeric weight to assign to this partition in the range 0\&...1000000\&. Available disk space is assigned the defined partitions according to their relative weights (subject to the size constraints configured with
293 \fISizeMinBytes=\fR,
294 \fISizeMaxBytes=\fR), so that a partition with weight 2000 gets double the space as one with weight 1000, and a partition with weight 333 a third of that\&. Defaults to 1000\&.
295 .sp
296 The
297 \fIWeight=\fR
298 setting is used to distribute available disk space in an "elastic" fashion, based on the disk size and existing partitions\&. If a partition shall have a fixed size use both
299 \fISizeMinBytes=\fR
300 and
301 \fISizeMaxBytes=\fR
302 with the same value in order to fixate the size to one value, in which case the weight has no effect\&.
303 .sp
304 Added in version 245\&.
305 .RE
306 .PP
307 \fIPaddingWeight=\fR
308 .RS 4
309 Similar to
310 \fIWeight=\fR, but sets a weight for the free space after the partition (the "padding")\&. When distributing available space the weights of all partitions and all defined padding is summed, and then each partition and padding gets the fraction defined by its weight\&. Defaults to 0, i\&.e\&. by default no padding is applied\&.
311 .sp
312 Padding is useful if empty space shall be left for later additions or a safety margin at the end of the device or between partitions\&.
313 .sp
314 Added in version 245\&.
315 .RE
316 .PP
317 \fISizeMinBytes=\fR, \fISizeMaxBytes=\fR
318 .RS 4
319 Specifies minimum and maximum size constraints in bytes\&. Takes the usual K, M, G, T, \&... suffixes (to the base of 1024)\&. If
320 \fISizeMinBytes=\fR
321 is specified the partition is created at or grown to at least the specified size\&. If
322 \fISizeMaxBytes=\fR
323 is specified the partition is created at or grown to at most the specified size\&. The precise size is determined through the weight value configured with
324 \fIWeight=\fR, see above\&. When
325 \fISizeMinBytes=\fR
326 is set equal to
327 \fISizeMaxBytes=\fR
328 the configured weight has no effect as the partition is explicitly sized to the specified fixed value\&. Note that partitions are never created smaller than 4096 bytes, and since partitions are never shrunk the previous size of the partition (in case the partition already exists) is also enforced as lower bound for the new size\&. The values should be specified as multiples of 4096 bytes, and are rounded upwards (in case of
329 \fISizeMinBytes=\fR) or downwards (in case of
330 \fISizeMaxBytes=\fR) otherwise\&. If the backing device does not provide enough space to fulfill the constraints placing the partition will fail\&. For partitions that shall be created, depending on the setting of
331 \fIPriority=\fR
332 (see above) the partition might be dropped and the placing algorithm restarted\&. By default, a minimum size constraint of 10M and no maximum size constraint is set\&.
333 .sp
334 Added in version 245\&.
335 .RE
336 .PP
337 \fIPaddingMinBytes=\fR, \fIPaddingMaxBytes=\fR
338 .RS 4
339 Specifies minimum and maximum size constraints in bytes for the free space after the partition (the "padding")\&. Semantics are similar to
340 \fISizeMinBytes=\fR
341 and
342 \fISizeMaxBytes=\fR, except that unlike partition sizes free space can be shrunk and can be as small as zero\&. By default, no size constraints on padding are set, so that only
343 \fIPaddingWeight=\fR
344 determines the size of the padding applied\&.
345 .sp
346 Added in version 245\&.
347 .RE
348 .PP
349 \fICopyBlocks=\fR
350 .RS 4
351 Takes a path to a regular file, block device node, char device node or directory, or the special value
352 "auto"\&. If specified and the partition is newly created, the data from the specified path is written to the newly created partition, on the block level\&. If a directory is specified, the backing block device of the file system the directory is on is determined, and the data read directly from that\&. This option is useful to efficiently replicate existing file systems onto new partitions on the block level \(em for example to build a simple OS installer or an OS image builder\&. Specify
353 /dev/urandom
354 as value to initialize a partition with random data\&.
355 .sp
356 If the special value
357 "auto"
358 is specified, the source to copy from is automatically picked up from the running system (or the image specified with
359 \fB\-\-image=\fR
360 \(em if used)\&. A partition that matches both the configured partition type (as declared with
361 \fIType=\fR
362 described above), and the currently mounted directory appropriate for that partition type is determined\&. For example, if the partition type is set to
363 "root"
364 the partition backing the root directory (/) is used as source to copy from \(em if its partition type is set to
365 "root"
366 as well\&. If the declared type is
367 "usr"
368 the partition backing
369 /usr/
370 is used as source to copy blocks from \(em if its partition type is set to
371 "usr"
372 too\&. The logic is capable of automatically tracking down the backing partitions for encrypted and Verity\-enabled volumes\&.
373 "CopyBlocks=auto"
374 is useful for implementing "self\-replicating" systems, i\&.e\&. systems that are their own installer\&.
375 .sp
376 The file specified here must have a size that is a multiple of the basic block size 512 and not be empty\&. If this option is used, the size allocation algorithm is slightly altered: the partition is created at least as big as required to fit the data in, i\&.e\&. the data size is an additional minimum size value taken into consideration for the allocation algorithm, similar to and in addition to the
377 \fISizeMin=\fR
378 value configured above\&.
379 .sp
380 This option has no effect if the partition it is declared for already exists, i\&.e\&. existing data is never overwritten\&. Note that the data is copied in before the partition table is updated, i\&.e\&. before the partition actually is persistently created\&. This provides robustness: it is guaranteed that the partition either does not exist or exists fully populated; it is not possible that the partition exists but is not or only partially populated\&.
381 .sp
382 This option cannot be combined with
383 \fIFormat=\fR
384 or
385 \fICopyFiles=\fR\&.
386 .sp
387 Added in version 246\&.
388 .RE
389 .PP
390 \fIFormat=\fR
391 .RS 4
392 Takes a file system name, such as
393 "ext4",
394 "btrfs",
395 "xfs",
396 "vfat",
397 "erofs",
398 "squashfs"
399 or the special value
400 "swap"\&. If specified and the partition is newly created it is formatted with the specified file system (or as swap device)\&. The file system UUID and label are automatically derived from the partition UUID and label\&. If this option is used, the size allocation algorithm is slightly altered: the partition is created at least as big as required for the minimal file system of the specified type (or 4KiB if the minimal size is not known)\&.
401 .sp
402 This option has no effect if the partition already exists\&.
403 .sp
404 Similarly to the behaviour of
405 \fICopyBlocks=\fR, the file system is formatted before the partition is created, ensuring that the partition only ever exists with a fully initialized file system\&.
406 .sp
407 This option cannot be combined with
408 \fICopyBlocks=\fR\&.
409 .sp
410 Added in version 247\&.
411 .RE
412 .PP
413 \fICopyFiles=\fR
414 .RS 4
415 Takes a pair of colon separated absolute file system paths\&. The first path refers to a source file or directory on the host, the second path refers to a target in the file system of the newly created partition and formatted file system\&. This setting may be used to copy files or directories from the host into the file system that is created due to the
416 \fIFormat=\fR
417 option\&. If
418 \fICopyFiles=\fR
419 is used without
420 \fIFormat=\fR
421 specified explicitly,
422 "Format="
423 with a suitable default is implied (currently
424 "vfat"
425 for
426 "ESP"
427 and
428 "XBOOTLDR"
429 partitions, and
430 "ext4"
431 otherwise, but this may change in the future)\&. This option may be used multiple times to copy multiple files or directories from host into the newly formatted file system\&. The colon and second path may be omitted in which case the source path is also used as the target path (relative to the root of the newly created file system)\&. If the source path refers to a directory it is copied recursively\&.
432 .sp
433 This option has no effect if the partition already exists: it cannot be used to copy additional files into an existing partition, it may only be used to populate a file system created anew\&.
434 .sp
435 The copy operation is executed before the file system is registered in the partition table, thus ensuring that a file system populated this way only ever exists fully initialized\&.
436 .sp
437 Note that
438 \fICopyFiles=\fR
439 will skip copying files that are not supported by the target filesystem (e\&.g symlinks, fifos, sockets and devices on vfat)\&. When an unsupported file type is encountered,
440 \fBsystemd\-repart\fR
441 will skip copying this file and write a log message about it\&.
442 .sp
443 Note that
444 \fBsystemd\-repart\fR
445 does not change the UIDs/GIDs of any copied files and directories\&. When running
446 \fBsystemd\-repart\fR
447 as an unprivileged user to build an image of files and directories owned by the same user, you can run
448 \fBsystemd\-repart\fR
449 in a user namespace with the current user mapped to the root user to make sure the files and directories in the image are owned by the root user\&.
450 .sp
451 Note that when populating XFS filesystems with
452 \fBsystemd\-repart\fR
453 and loop devices are not available, populating XFS filesystems with files containing spaces, tabs or newlines might fail on old versions of
454 \fBmkfs.xfs\fR(8)
455 due to limitations of its protofile format\&.
456 .sp
457 Note that when populating XFS filesystems with
458 \fBsystemd\-repart\fR
459 and loop devices are not available, extended attributes will not be copied into generated XFS filesystems due to limitations
460 \fBmkfs.xfs\fR(8)\*(Aqs protofile format\&.
461 .sp
462 This option cannot be combined with
463 \fICopyBlocks=\fR\&.
464 .sp
465 When
466 \fBsystemd-repart\fR(8)
467 is invoked with the
468 \fB\-\-copy\-source=\fR
469 command line switch the file paths are taken relative to the specified directory\&. If
470 \fB\-\-copy\-source=\fR
471 is not used, but the
472 \fB\-\-image=\fR
473 or
474 \fB\-\-root=\fR
475 switches are used, the source paths are taken relative to the specified root directory or disk image root\&.
476 .sp
477 Added in version 247\&.
478 .RE
479 .PP
480 \fIExcludeFiles=\fR, \fIExcludeFilesTarget=\fR
481 .RS 4
482 Takes one or more absolute paths, separated by whitespace, each referring to a source file or directory on the host\&. This setting may be used to exclude files or directories from the host from being copied into the file system when
483 \fICopyFiles=\fR
484 is used\&. This option may be used multiple times to exclude multiple files or directories from host from being copied into the newly formatted file system\&.
485 .sp
486 If the path is a directory and ends with
487 "/", only the directory\*(Aqs contents are excluded but not the directory itself\&. If the path is a directory and does not end with
488 "/", both the directory and its contents are excluded\&.
489 .sp
490 \fIExcludeFilesTarget=\fR
491 is like
492 \fIExcludeFiles=\fR
493 except that instead of excluding the path on the host from being copied into the partition, it excludes any files and directories from being copied into the given path in the partition\&.
494 .sp
495 When
496 \fBsystemd-repart\fR(8)
497 is invoked with the
498 \fB\-\-image=\fR
499 or
500 \fB\-\-root=\fR
501 command line switches the paths specified are taken relative to the specified root directory or disk image root\&.
502 .sp
503 Added in version 254\&.
504 .RE
505 .PP
506 \fIMakeDirectories=\fR
507 .RS 4
508 Takes one or more absolute paths, separated by whitespace, each declaring a directory to create within the new file system\&. Behaviour is similar to
509 \fICopyFiles=\fR, but instead of copying in a set of files this just creates the specified directories with the default mode of 0755 owned by the root user and group, plus all their parent directories (with the same ownership and access mode)\&. To configure directories with different ownership or access mode, use
510 \fICopyFiles=\fR
511 and specify a source tree to copy containing appropriately owned/configured directories\&. This option may be used more than once to create multiple directories\&. When
512 \fICopyFiles=\fR
513 and
514 \fIMakeDirectories=\fR
515 are used together the former is applied first\&. If a directory listed already exists no operation is executed (in particular, the ownership/access mode of the directories is left as is)\&.
516 .sp
517 The primary use case for this option is to create a minimal set of directories that may be mounted over by other partitions contained in the same disk image\&. For example, a disk image where the root file system is formatted at first boot might want to automatically pre\-create
518 /usr/
519 in it this way, so that the
520 "usr"
521 partition may over\-mount it\&.
522 .sp
523 Consider using
524 \fBsystemd-tmpfiles\fR(8)
525 with its
526 \fB\-\-image=\fR
527 option to pre\-create other, more complex directory hierarchies (as well as other inodes) with fine\-grained control of ownership, access modes and other file attributes\&.
528 .sp
529 Added in version 249\&.
530 .RE
531 .PP
532 \fIMakeSymlinks=\fR
533 .RS 4
534 Takes one or more arguments, separated by whitespace, each declaring a symlink to create within the new file system\&. Each argument is a pair of symlink source and target paths, separated by a colon\&. This option may be used more than once to create multiple symlinks\&. When
535 \fICopyFiles=\fR
536 and
537 \fIMakeSymlinks=\fR
538 are used together the former is applied first\&.
539 .sp
540 The primary use case for this option is to create symlinks that need to exist before
541 \fBsystemd-tmpfiles\fR(8)
542 is executed\&. For example, when using
543 \fBsystemd-confext\fR(8), this setting can be used to create symlinks in
544 /var/lib/extensions\&.mutable
545 to redirect writes to mutable confexts to a custom location\&.
546 .sp
547 Consider using
548 \fBsystemd-tmpfiles\fR(8)
549 with its
550 \fB\-\-image=\fR
551 option to pre\-create other symlinks (as well as other inodes) with fine\-grained control of ownership, access modes and other file attributes\&.
552 .sp
553 Added in version 257\&.
554 .RE
555 .PP
556 \fISubvolumes=\fR
557 .RS 4
558 Takes one or more absolute paths, separated by whitespace, each declaring a directory that should be a subvolume within the new file system\&. Each path may optionally be followed by a colon and a list of comma\-separated subvolume flags\&. The following flags are understood:
559 .sp
560 .it 1 an-trap
561 .nr an-no-space-flag 1
562 .nr an-break-flag 1
563 .br
564 .B Table\ \&2.\ \&Subvolume Flags
565 .TS
566 allbox tab(:);
567 lB lB.
568 T{
569 Flag
570 T}:T{
571 Purpose
572 T}
573 .T&
574 l l.
575 T{
576 "ro"
577 T}:T{
578 Make this subvolume read\-only\&.
579 T}
580 .TE
581 .sp 1
582 Note that this option does not create the directories themselves, that can be configured with
583 \fIMakeDirectories=\fR
584 and
585 \fICopyFiles=\fR\&.
586 .sp
587 Note that this option only takes effect if the target filesystem supports subvolumes, such as
588 \fBbtrfs\fR(8)\&.
589 .sp
590 Note that this option is only supported in combination with
591 \fB\-\-offline=yes\fR
592 since
593 btrfs\-progs
594 6\&.12 or newer\&.
595 .sp
596 Added in version 255\&.
597 .RE
598 .PP
599 \fIDefaultSubvolume=\fR
600 .RS 4
601 Takes an absolute path specifying the default subvolume within the new filesystem\&. Note that this setting does not create the subvolume itself, that can be configured with
602 \fISubvolumes=\fR\&.
603 .sp
604 Note that this option only takes effect if the target filesystem supports subvolumes, such as
605 \fBbtrfs\fR(8)\&.
606 .sp
607 Note that this option is only supported in combination with
608 \fB\-\-offline=yes\fR
609 since
610 btrfs\-progs
611 6\&.12 or newer\&.
612 .sp
613 Added in version 256\&.
614 .RE
615 .PP
616 \fIEncrypt=\fR
617 .RS 4
618 Takes one of
619 "off",
620 "key\-file",
621 "tpm2"
622 and
623 "key\-file+tpm2"
624 (alternatively, also accepts a boolean value, which is mapped to
625 "off"
626 when false, and
627 "key\-file"
628 when true)\&. Defaults to
629 "off"\&. If not
630 "off"
631 the partition will be formatted with a LUKS2 superblock, before the blocks configured with
632 \fICopyBlocks=\fR
633 are copied in or the file system configured with
634 \fIFormat=\fR
635 is created\&.
636 .sp
637 The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion\&. If
638 "key\-file"
639 or
640 "key\-file+tpm2"
641 is used, a key is added to the LUKS2 superblock, configurable with the
642 \fB\-\-key\-file=\fR
643 option to
644 \fBsystemd\-repart\fR\&. If
645 "tpm2"
646 or
647 "key\-file+tpm2"
648 is used, a key is added to the LUKS2 superblock that is enrolled to the local TPM2 chip, as configured with the
649 \fB\-\-tpm2\-device=\fR
650 and
651 \fB\-\-tpm2\-pcrs=\fR
652 options to
653 \fBsystemd\-repart\fR\&.
654 .sp
655 When used this slightly alters the size allocation logic as the implicit, minimal size limits of
656 \fIFormat=\fR
657 and
658 \fICopyBlocks=\fR
659 are increased by the space necessary for the LUKS2 superblock (see above)\&.
660 .sp
661 This option has no effect if the partition already exists\&.
662 .sp
663 Added in version 247\&.
664 .RE
665 .PP
666 \fIVerity=\fR
667 .RS 4
668 Takes one of
669 "off",
670 "data",
671 "hash"
672 or
673 "signature"\&. Defaults to
674 "off"\&. If set to
675 "off"
676 or
677 "data", the partition is populated with content as specified by
678 \fICopyBlocks=\fR
679 or
680 \fICopyFiles=\fR\&. If set to
681 "hash", the partition will be populated with verity hashes from the matching verity data partition\&. If set to
682 "signature", the partition will be populated with a JSON object containing a signature of the verity root hash of the matching verity hash partition\&.
683 .sp
684 A matching verity partition is a partition with the same verity match key (as configured with
685 \fIVerityMatchKey=\fR)\&.
686 .sp
687 If not explicitly configured, the data partition\*(Aqs UUID will be set to the first 128 bits of the verity root hash\&. Similarly, if not configured, the hash partition\*(Aqs UUID will be set to the final 128 bits of the verity root hash\&. The verity root hash itself will be included in the output of
688 \fBsystemd\-repart\fR\&.
689 .sp
690 This option has no effect if the partition already exists\&.
691 .sp
692 Usage of this option in combination with
693 \fIEncrypt=\fR
694 is not supported\&.
695 .sp
696 For each unique
697 \fIVerityMatchKey=\fR
698 value, a single verity data partition ("Verity=data") and a single verity hash partition ("Verity=hash") must be defined\&.
699 .sp
700 Added in version 252\&.
701 .RE
702 .PP
703 \fIVerityMatchKey=\fR
704 .RS 4
705 Takes a short, user\-chosen identifier string\&. This setting is used to find sibling verity partitions for the current verity partition\&. See the description for
706 \fIVerity=\fR\&.
707 .sp
708 Added in version 252\&.
709 .RE
710 .PP
711 \fIVerityDataBlockSizeBytes=\fR
712 .RS 4
713 Configures the data block size of the generated verity hash partition\&. Must be between 512 and 4096 bytes and must be a power of 2\&. Defaults to the sector size if configured explicitly, or the underlying block device sector size, or 4K if
714 \fBsystemd\-repart\fR
715 is not operating on a block device\&.
716 .sp
717 Added in version 255\&.
718 .RE
719 .PP
720 \fIVerityHashBlockSizeBytes=\fR
721 .RS 4
722 Configures the hash block size of the generated verity hash partition\&. Must be between 512 and 4096 bytes and must be a power of 2\&. Defaults to the sector size if configured explicitly, or the underlying block device sector size, or 4K if
723 \fBsystemd\-repart\fR
724 is not operating on a block device\&.
725 .sp
726 Added in version 255\&.
727 .RE
728 .PP
729 \fIFactoryReset=\fR
730 .RS 4
731 Takes a boolean argument\&. If specified the partition is marked for removal during a factory reset operation\&. This functionality is useful to implement schemes where images can be reset into their original state by removing partitions and creating them anew\&. Defaults to off\&.
732 .sp
733 Added in version 245\&.
734 .RE
735 .PP
736 \fIFlags=\fR
737 .RS 4
738 Configures the 64\-bit GPT partition flags field to set for the partition when creating it\&. This option has no effect if the partition already exists\&. If not specified, the flags value is set to all zeroes, except for the three bits that can also be configured via
739 \fINoAuto=\fR,
740 \fIReadOnly=\fR
741 and
742 \fIGrowFileSystem=\fR; see below for details on the defaults for these three flags\&. Specify the flags value in hexadecimal (by prefixing it with
743 "0x"), binary (prefix
744 "0b") or decimal (no prefix)\&.
745 .sp
746 Added in version 249\&.
747 .RE
748 .PP
749 \fINoAuto=\fR, \fIReadOnly=\fR, \fIGrowFileSystem=\fR
750 .RS 4
751 Configures the No\-Auto, Read\-Only and Grow\-File\-System partition flags (bit 63, 60 and 59) of the partition table entry, as defined by the
752 \m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. Only available for partition types supported by the specification\&. This option is a friendly way to set bits 63, 60 and 59 of the partition flags value without setting any of the other bits, and may be set via
753 \fIFlags=\fR
754 too, see above\&.
755 .sp
756 If
757 \fIFlags=\fR
758 is used in conjunction with one or more of
759 \fINoAuto=\fR/\fIReadOnly=\fR/\fIGrowFileSystem=\fR
760 the latter control the value of the relevant flags, i\&.e\&. the high\-level settings
761 \fINoAuto=\fR/\fIReadOnly=\fR/\fIGrowFileSystem=\fR
762 override the relevant bits of the low\-level setting
763 \fIFlags=\fR\&.
764 .sp
765 Note that the three flags affect only automatic partition mounting, as implemented by
766 \fBsystemd-gpt-auto-generator\fR(8)
767 or the
768 \fB\-\-image=\fR
769 option of various commands (such as
770 \fBsystemd-nspawn\fR(1))\&. It has no effect on explicit mounts, such as those done via
771 \fBmount\fR(8)
772 or
773 \fBfstab\fR(5)\&.
774 .sp
775 If both bit 60 and 59 are set for a partition (i\&.e\&. the partition is marked both read\-only and marked for file system growing) the latter is typically without effect: the read\-only flag takes precedence in most tools reading these flags, and since growing the file system involves writing to the partition it is consequently ignored\&.
776 .sp
777 \fINoAuto=\fR
778 defaults to off\&.
779 \fIReadOnly=\fR
780 defaults to on for Verity partition types, and off for all others\&.
781 \fIGrowFileSystem=\fR
782 defaults to on for all partition types that support it, except if the partition is marked read\-only (and thus effectively, defaults to off for Verity partitions)\&.
783 .sp
784 Added in version 249\&.
785 .RE
786 .PP
787 \fISplitName=\fR
788 .RS 4
789 Configures the suffix to append to split artifacts when the
790 \fB\-\-split\fR
791 option of
792 \fBsystemd-repart\fR(8)
793 is used\&. Simple specifier expansion is supported, see below\&. Defaults to
794 "%t"\&. To disable split artifact generation for a partition, set
795 \fISplitName=\fR
796 to
797 "\-"\&.
798 .sp
799 Added in version 252\&.
800 .RE
801 .PP
802 \fIMinimize=\fR
803 .RS 4
804 Takes one of
805 "off",
806 "best", and
807 "guess"
808 (alternatively, also accepts a boolean value, which is mapped to
809 "off"
810 when false, and
811 "best"
812 when true)\&. Defaults to
813 "off"\&. If set to
814 "best", the partition will have the minimal size required to store the sources configured with
815 \fICopyFiles=\fR\&.
816 "best"
817 is currently only supported for read\-only filesystems\&. If set to
818 "guess", the partition is created at least as big as required to store the sources configured with
819 \fICopyFiles=\fR\&. Note that unless the filesystem is a read\-only filesystem,
820 \fBsystemd\-repart\fR
821 will have to populate the filesystem twice to guess the minimal required size, so enabling this option might slow down repart when populating large partitions\&.
822 .sp
823 Added in version 253\&.
824 .RE
825 .PP
826 \fIMountPoint=\fR
827 .RS 4
828 Specifies where and how the partition should be mounted\&. Takes at least one and at most two fields separated with a colon (":")\&. The first field specifies where the partition should be mounted\&. The second field specifies extra mount options to append to the default mount options\&. These fields correspond to the second and fourth column of the
829 \fBfstab\fR(5)
830 format\&. As a colon is used for separating fields, each field needs to be quoted when it contains colons\&. E\&.g\&.
831 .sp
832 .if n \{\
833 .RS 4
834 .\}
835 .nf
836 MountPoint="/path/with:colon":"zstd:1,noatime,lazytime"
837 .fi
838 .if n \{\
839 .RE
840 .\}
841 .sp
842 This setting may be specified multiple times to mount the partition multiple times\&. This can be used to add mounts for different
843 \fBbtrfs\fR(8)
844 subvolumes located on the same btrfs partition\&.
845 .sp
846 Note that this setting is only taken into account when
847 \fB\-\-generate\-fstab=\fR
848 is specified on the
849 \fBsystemd\-repart\fR
850 command line\&.
851 .sp
852 Added in version 256\&.
853 .RE
854 .PP
855 \fIEncryptedVolume=\fR
856 .RS 4
857 Specifies how the encrypted partition should be set up\&. Takes at least one and at most three fields separated with a colon (":")\&. The first field specifies the encrypted volume name under
858 /dev/mapper/\&. If not specified,
859 "luks\-UUID"
860 will be used where
861 "UUID"
862 is the LUKS UUID\&. The second field specifies the keyfile to use following the same format as specified in crypttab\&. The third field specifies a comma\-delimited list of crypttab options\&. These fields correspond to the first, third and fourth column of the
863 \fBcrypttab\fR(5)
864 format\&.
865 .sp
866 Note that this setting is only taken into account when
867 \fB\-\-generate\-crypttab=\fR
868 is specified on the
869 \fBsystemd\-repart\fR
870 command line\&.
871 .sp
872 Added in version 256\&.
873 .RE
874 .PP
875 \fICompression=\fR
876 .RS 4
877 Specifies the compression algorithm to use for the filesystem configured with
878 \fIFormat=\fR\&. Takes a single argument specifying the compression algorithm\&.
879 .sp
880 Note that this setting is only taken into account when the filesystem configured with
881 \fIFormat=\fR
882 supports compression (
883 \fBbtrfs\fR(8), squashfs,
884 \fBerofs\fR(5))\&. Here\*(Aqs an incomplete list of compression algorithms supported by the filesystems known to
885 \fBsystemd\-repart\fR:
886 .sp
887 .it 1 an-trap
888 .nr an-no-space-flag 1
889 .nr an-break-flag 1
890 .br
891 .B Table\ \&3.\ \&File System Compression Algorithms
892 .TS
893 allbox tab(:);
894 lB lB lB.
895 T{
896 File System
897 T}:T{
898 Compression Algorithms
899 T}:T{
900 Documentation
901 T}
902 .T&
903 l l l
904 l l l.
905 T{
906 \fBsquashfs\fR
907 T}:T{
908 gzip, lzo, lz4, xz, zstd, lzma
909 T}:T{
910 \fBmksquashfs\fR(1)
911 T}
912 T{
913 \fBerofs\fR
914 T}:T{
915 lz4, lz4hc, lzma, deflate, libdeflate, zstd
916 T}:T{
917 \fBmkfs.erofs\fR(1)
918 T}
919 .TE
920 .sp 1
921 Added in version 257\&.
922 .RE
923 .PP
924 \fICompressionLevel=\fR
925 .RS 4
926 Specifies the compression level to use for the filesystem configured with
927 \fIFormat=\fR\&. Takes a single argument specifying the compression level to use for the configured compression algorithm\&. The possible compression levels and their meaning are filesystem specific (refer to the filesystem\*(Aqs documentation for the exact meaning of a particular compression level)\&.
928 .sp
929 Note that this setting is only taken into account when the filesystem configured with
930 \fIFormat=\fR
931 supports compression and the
932 \fICompression=\fR
933 setting is configured explicitly\&.
934 .sp
935 Added in version 257\&.
936 .RE
937 .PP
938 \fISupplementFor=\fR
939 .RS 4
940 Takes a partition definition name, such as
941 "10\-esp"\&. If specified,
942 \fBsystemd\-repart\fR
943 will avoid creating this partition and instead prefer to partially merge the two definitions\&. However, depending on the existing layout of partitions on disk,
944 \fBsystemd\-repart\fR
945 may be forced to fall back onto un\-merging the definitions and using them as originally written, potentially creating this partition\&. Specifically,
946 \fBsystemd\-repart\fR
947 will fall back if this partition is found to already exist on disk, or if the target partition already exists on disk but is too small, or if it cannot allocate space for the merged partition for some other reason\&.
948 .sp
949 The following fields are merged into the target definition in the specified ways:
950 \fIWeight=\fR
951 and
952 \fIPaddingWeight=\fR
953 are simply overwritten;
954 \fISizeMinBytes=\fR
955 and
956 \fIPaddingMinBytes=\fR
957 use the larger of the two values;
958 \fISizeMaxBytes=\fR
959 and
960 \fIPaddingMaxBytes=\fR
961 use the smaller value; and
962 \fICopyFiles=\fR,
963 \fIExcludeFiles=\fR,
964 \fIExcludeFilesTarget=\fR,
965 \fIMakeDirectories=\fR, and
966 \fISubvolumes=\fR
967 are concatenated\&.
968 .sp
969 Usage of this option in combination with
970 \fICopyBlocks=\fR,
971 \fIEncrypt=\fR, or
972 \fIVerity=\fR
973 is not supported\&. The target definition cannot set these settings either\&. A definition cannot simultaneously be a supplement and act as a target for some other supplement definition\&. A target cannot have more than one supplement partition associated with it\&.
974 .sp
975 For example, distributions can use this to implement
976 \fI$BOOT\fR
977 as defined in the
978 \m[blue]\fBBoot Loader Specification\fR\m[]\&\s-2\u[2]\d\s+2\&. Distributions may prefer to use the ESP as
979 \fI$BOOT\fR
980 whenever possible, but to adhere to the spec XBOOTLDR must sometimes be used instead\&. So, they should create two definitions: the first defining an ESP big enough to hold just the bootloader, and a second for the XBOOTLDR that\*(Aqs sufficiently large to hold kernels and configured as a supplement for the ESP\&. Whenever possible,
981 \fBsystemd-repart\fR(8)
982 will try to merge the two definitions to create one large ESP, but if that\*(Aqs not allowable due to the existing conditions on disk a small ESP and a large XBOOTLDR will be created instead\&.
983 .sp
984 As another example, distributions can also use this to seamlessly share a single
985 /home
986 partition in a multi\-boot scenario, while preferring to keep
987 /home
988 on the root partition by default\&. Having a
989 /home
990 partition separated from the root partition entails some extra complexity: someone has to decide how to split the space between the two partitions\&. On the other hand, it allows a user to share their home area between multiple installed OSs (i\&.e\&. via
991 \fBsystemd-homed.service\fR(8))\&. Distributions should create two definitions: the first for a root partition that takes up some relatively small percentage of the disk, and the second as a supplement for the first to create a
992 /home
993 partition that takes up all the remaining free space\&. On first boot, if
994 \fBsystemd\-repart\fR
995 finds an existing
996 /home
997 partition on disk, it\*(Aqll un\-merge the definitions and create just a small root partition\&. Otherwise, the definitions will be merged and a single large root partition will be created\&.
998 .sp
999 Added in version 257\&.
1000 .RE
1001 .SH "SPECIFIERS"
1002 .PP
1003 Specifiers may be used in the
1004 \fILabel=\fR,
1005 \fICopyBlocks=\fR,
1006 \fICopyFiles=\fR,
1007 \fIMakeDirectories=\fR,
1008 \fISplitName=\fR
1009 settings\&. The following expansions are understood:
1010 .sp
1011 .it 1 an-trap
1012 .nr an-no-space-flag 1
1013 .nr an-break-flag 1
1014 .br
1015 .B Table\ \&4.\ \&Specifiers available
1016 .TS
1017 allbox tab(:);
1018 lB lB lB.
1019 T{
1020 Specifier
1021 T}:T{
1022 Meaning
1023 T}:T{
1024 Details
1025 T}
1026 .T&
1027 l l l
1028 l l l
1029 l l l
1030 l l l
1031 l l l
1032 l l l
1033 l l l
1034 l l l
1035 l l l
1036 l l l
1037 l l l
1038 l l l
1039 l l l
1040 l l l
1041 l l l
1042 l l l.
1043 T{
1044 "%a"
1045 T}:T{
1046 Architecture
1047 T}:T{
1048 A short string identifying the architecture of the local system\&. A string such as \fBx86\fR, \fBx86\-64\fR or \fBarm64\fR\&. See the architectures defined for \fIConditionArchitecture=\fR in \fBsystemd.unit\fR(5) for a full list\&.
1049 T}
1050 T{
1051 "%A"
1052 T}:T{
1053 Operating system image version
1054 T}:T{
1055 The operating system image version identifier of the running system, as read from the \fIIMAGE_VERSION=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
1056 T}
1057 T{
1058 "%b"
1059 T}:T{
1060 Boot ID
1061 T}:T{
1062 The boot ID of the running system, formatted as string\&. See \fBrandom\fR(4) for more information\&.
1063 T}
1064 T{
1065 "%B"
1066 T}:T{
1067 Operating system build ID
1068 T}:T{
1069 The operating system build identifier of the running system, as read from the \fIBUILD_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
1070 T}
1071 T{
1072 "%H"
1073 T}:T{
1074 Host name
1075 T}:T{
1076 The hostname of the running system\&.
1077 T}
1078 T{
1079 "%l"
1080 T}:T{
1081 Short host name
1082 T}:T{
1083 The hostname of the running system, truncated at the first dot to remove any domain component\&.
1084 T}
1085 T{
1086 "%m"
1087 T}:T{
1088 Machine ID
1089 T}:T{
1090 The machine ID of the running system, formatted as string\&. See \fBmachine-id\fR(5) for more information\&.
1091 T}
1092 T{
1093 "%M"
1094 T}:T{
1095 Operating system image identifier
1096 T}:T{
1097 The operating system image identifier of the running system, as read from the \fIIMAGE_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
1098 T}
1099 T{
1100 "%o"
1101 T}:T{
1102 Operating system ID
1103 T}:T{
1104 The operating system identifier of the running system, as read from the \fIID=\fR field of /etc/os\-release\&. See \fBos-release\fR(5) for more information\&.
1105 T}
1106 T{
1107 "%q"
1108 T}:T{
1109 Pretty host name
1110 T}:T{
1111 The pretty hostname of the running system, as read from the \fIPRETTY_HOSTNAME=\fR field of /etc/machine\-info\&. If not set, resolves to the short hostname\&. See \fBmachine-info\fR(5) for more information\&.
1112 T}
1113 T{
1114 "%v"
1115 T}:T{
1116 Kernel release
1117 T}:T{
1118 Identical to \fBuname \-r\fR output\&.
1119 T}
1120 T{
1121 "%w"
1122 T}:T{
1123 Operating system version ID
1124 T}:T{
1125 The operating system version identifier of the running system, as read from the \fIVERSION_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
1126 T}
1127 T{
1128 "%W"
1129 T}:T{
1130 Operating system variant ID
1131 T}:T{
1132 The operating system variant identifier of the running system, as read from the \fIVARIANT_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
1133 T}
1134 T{
1135 "%T"
1136 T}:T{
1137 Directory for temporary files
1138 T}:T{
1139 This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.)
1140 T}
1141 T{
1142 "%V"
1143 T}:T{
1144 Directory for larger and persistent temporary files
1145 T}:T{
1146 This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.)
1147 T}
1148 T{
1149 "%%"
1150 T}:T{
1151 Single percent sign
1152 T}:T{
1153 Use "%%" in place of "%" to specify a single percent sign\&.
1154 T}
1155 .TE
1156 .sp 1
1157 .PP
1158 Additionally, for the
1159 \fISplitName=\fR
1160 setting, the following specifiers are also understood:
1161 .sp
1162 .it 1 an-trap
1163 .nr an-no-space-flag 1
1164 .nr an-break-flag 1
1165 .br
1166 .B Table\ \&5.\ \&Specifiers available
1167 .TS
1168 allbox tab(:);
1169 lB lB lB.
1170 T{
1171 Specifier
1172 T}:T{
1173 Meaning
1174 T}:T{
1175 Details
1176 T}
1177 .T&
1178 l l l
1179 l l l
1180 l l l
1181 l l l.
1182 T{
1183 "%T"
1184 T}:T{
1185 Partition Type UUID
1186 T}:T{
1187 The partition type UUID, as configured with \fIType=\fR
1188 T}
1189 T{
1190 "%t"
1191 T}:T{
1192 Partition Type Identifier
1193 T}:T{
1194 The partition type identifier corresponding to the partition type UUID
1195 T}
1196 T{
1197 "%U"
1198 T}:T{
1199 Partition UUID
1200 T}:T{
1201 The partition UUID, as configured with \fIUUID=\fR
1202 T}
1203 T{
1204 "%n"
1205 T}:T{
1206 Partition Number
1207 T}:T{
1208 The partition number assigned to the partition
1209 T}
1210 .TE
1211 .sp 1
1212 .SH "ENVIRONMENT"
1213 .PP
1214 Extra filesystem formatting options can be provided using filesystem\-specific environment variables:
1215 \fI$SYSTEMD_REPART_MKFS_OPTIONS_BTRFS\fR,
1216 \fI$SYSTEMD_REPART_MKFS_OPTIONS_XFS\fR,
1217 \fI$SYSTEMD_REPART_MKFS_OPTIONS_VFAT\fR,
1218 \fI$SYSTEMD_REPART_MKFS_OPTIONS_EROFS\fR, and
1219 \fI$SYSTEMD_REPART_MKFS_OPTIONS_SQUASHFS\fR\&. Each variable accepts valid
1220 \fBmkfs\&.\fR\fB\fIfilesystem\fR\fR
1221 command\-line arguments\&. The content of those variables is passed as\-is to the command, without any verification\&.
1222 .SH "EXAMPLES"
1223 .PP
1224 \fBExample\ \&1.\ \&Grow the root partition to the full disk size at first boot\fR
1225 .PP
1226 With the following file the root partition is automatically grown to the full disk if possible during boot\&.
1227 .PP
1228 .if n \{\
1229 .RS 4
1230 .\}
1231 .nf
1232 # /usr/lib/repart\&.d/50\-root\&.conf
1233 [Partition]
1234 Type=root
1235 .fi
1236 .if n \{\
1237 .RE
1238 .\}
1239
1240 .PP
1241 \fBExample\ \&2.\ \&Create a swap and home partition automatically on boot, if missing\fR
1242 .PP
1243 The home partition gets all available disk space while the swap partition gets 1G at most and 64M at least\&. We set a priority > 0 on the swap partition to ensure the swap partition is not used if not enough space is available\&. For every three bytes assigned to the home partition the swap partition gets assigned one\&.
1244 .PP
1245 .if n \{\
1246 .RS 4
1247 .\}
1248 .nf
1249 # /usr/lib/repart\&.d/60\-home\&.conf
1250 [Partition]
1251 Type=home
1252 .fi
1253 .if n \{\
1254 .RE
1255 .\}
1256 .PP
1257 .if n \{\
1258 .RS 4
1259 .\}
1260 .nf
1261 # /usr/lib/repart\&.d/70\-swap\&.conf
1262 [Partition]
1263 Type=swap
1264 SizeMinBytes=64M
1265 SizeMaxBytes=1G
1266 Priority=1
1267 Weight=333
1268 .fi
1269 .if n \{\
1270 .RE
1271 .\}
1272
1273 .PP
1274 \fBExample\ \&3.\ \&Create B partitions in an A/B Verity setup, if missing\fR
1275 .PP
1276 Let\*(Aqs say the vendor intends to update OS images in an A/B setup, i\&.e\&. with two root partitions (and two matching Verity partitions) that shall be used alternatingly during upgrades\&. To minimize image sizes the original image is shipped only with one root and one Verity partition (the "A" set), and the second root and Verity partitions (the "B" set) shall be created on first boot on the free space on the medium\&.
1277 .PP
1278 .if n \{\
1279 .RS 4
1280 .\}
1281 .nf
1282 # /usr/lib/repart\&.d/50\-root\&.conf
1283 [Partition]
1284 Type=root
1285 SizeMinBytes=512M
1286 SizeMaxBytes=512M
1287 .fi
1288 .if n \{\
1289 .RE
1290 .\}
1291 .PP
1292 .if n \{\
1293 .RS 4
1294 .\}
1295 .nf
1296 # /usr/lib/repart\&.d/60\-root\-verity\&.conf
1297 [Partition]
1298 Type=root\-verity
1299 SizeMinBytes=64M
1300 SizeMaxBytes=64M
1301 .fi
1302 .if n \{\
1303 .RE
1304 .\}
1305 .PP
1306 The definitions above cover the "A" set of root partition (of a fixed 512M size) and Verity partition for the root partition (of a fixed 64M size)\&. Let\*(Aqs use symlinks to create the "B" set of partitions, since after all they shall have the same properties and sizes as the "A" set\&.
1307 .PP
1308 .if n \{\
1309 .RS 4
1310 .\}
1311 .nf
1312 # ln \-s 50\-root\&.conf /usr/lib/repart\&.d/70\-root\-b\&.conf
1313 # ln \-s 60\-root\-verity\&.conf /usr/lib/repart\&.d/80\-root\-verity\-b\&.conf
1314 .fi
1315 .if n \{\
1316 .RE
1317 .\}
1318
1319 .PP
1320 \fBExample\ \&4.\ \&Create a data partition and corresponding verity partitions from a OS tree\fR
1321 .PP
1322 Assuming we have an OS tree at
1323 /var/tmp/os\-tree
1324 that we want to package in a root partition together with matching verity partitions, we can do so as follows:
1325 .PP
1326 .if n \{\
1327 .RS 4
1328 .\}
1329 .nf
1330 # 50\-root\&.conf
1331 [Partition]
1332 Type=root
1333 CopyFiles=/var/tmp/os\-tree
1334 Verity=data
1335 VerityMatchKey=root
1336 Minimize=guess
1337 .fi
1338 .if n \{\
1339 .RE
1340 .\}
1341 .PP
1342 .if n \{\
1343 .RS 4
1344 .\}
1345 .nf
1346 # 60\-root\-verity\&.conf
1347 [Partition]
1348 Type=root\-verity
1349 Verity=hash
1350 VerityMatchKey=root
1351 # Explicitly set the hash and data block size to 4K
1352 VerityDataBlockSizeBytes=4096
1353 VerityHashBlockSizeBytes=4096
1354 Minimize=best
1355 .fi
1356 .if n \{\
1357 .RE
1358 .\}
1359 .PP
1360 .if n \{\
1361 .RS 4
1362 .\}
1363 .nf
1364 # 70\-root\-verity\-sig\&.conf
1365 [Partition]
1366 Type=root\-verity\-sig
1367 Verity=signature
1368 VerityMatchKey=root
1369 .fi
1370 .if n \{\
1371 .RE
1372 .\}
1373
1374 .SH "SEE ALSO"
1375 .PP
1376 \fBsystemd\fR(1), \fBsystemd-repart\fR(8), \fBsfdisk\fR(8), \fBsystemd-cryptenroll\fR(1)
1377 .SH "NOTES"
1378 .IP " 1." 4
1379 Discoverable Partitions Specification
1380 .RS 4
1381 \%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
1382 .RE
1383 .IP " 2." 4
1384 Boot Loader Specification
1385 .RS 4
1386 \%https://uapi-group.org/specifications/specs/boot_loader_specification/
1387 .RE