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