1REPART.D(5) repart.d REPART.D(5)
2
6 repart.d - Partition Definition Files for Automatic Boot-Time
7 Repartitioning
8
10 /etc/repart.d/*.conf
11 /run/repart.d/*.conf
12 /usr/lib/repart.d/*.conf
13
16 repart.d/*.conf files describe basic properties of partitions of block
17 devices of the local system. They may be used to declare types, names
18 and sizes of partitions that shall exist. The systemd-repart(8) service
19 reads these files and attempts to add new partitions currently missing
20 and enlarge existing partitions according to these definitions.
21 Operation is generally incremental, i.e. when applied, what exists
22 already is left intact, and partitions are never shrunk, moved or
23 deleted.
24 These definition files are useful for implementing operating system
26 images that are prepared and delivered with minimally sized images (for
27 example lacking any state or swap partitions), and which on first boot
28 automatically take possession of any remaining disk space following a
29 few basic rules.
30 Currently, support for partition definition files is only implemented
32 for GPT partitition tables.
33 Partition files are generally matched against any partitions already
35 existing on disk in a simple algorithm: the partition files are sorted
36 by their filename (ignoring the directory prefix), and then compared in
37 order against existing partitions matching the same partition type
38 UUID. Specifically, the first existing partition with a specific
39 partition type UUID is assigned the first definition file with the same
40 partition type UUID, and the second existing partition with a specific
41 type UUID the second partition file with the same type UUID, and so on.
42 Any left-over partition files that have no matching existing partition
43 are assumed to define new partition that shall be created. Such
44 partitions are appended to the end of the partition table, in the order
45 defined by their names utilizing the first partition slot greater than
46 the highest slot number currently in use. Any existing partitions that
47 have no matching partition file are left as they are.
48 Note that these partition definition files do not describe the contents
50 of the partitions, such as the file system used. Separate mechanisms,
51 such as systemd-growfs(8) and systemd-makefs maybe be used to
52 initialize or grow the file systems inside of these partitions.
53
55 Type=
56 The GPT partition type UUID to match. This may be a GPT partition
57 type UUID such as 4f68bce3-e8cd-4db1-96e7-fbcaf984b709, or one of
58 the following special identifiers:
59 Table 1. GPT partition type identifiers
61 ┌──────────────────────┬────────────────────────────┐
62 │Identifier │ Explanation │
63 ├──────────────────────┼────────────────────────────┤
64 │esp │ EFI System Partition │
65 ├──────────────────────┼────────────────────────────┤
66 │xbootldr │ Extended Boot Loader │
67 │ │ Partition │
68 ├──────────────────────┼────────────────────────────┤
69 │swap │ Swap partition │
70 ├──────────────────────┼────────────────────────────┤
71 │home │ Home (/home/) partition │
72 ├──────────────────────┼────────────────────────────┤
73 │srv │ Server data (/srv/) │
74 │ │ partition │
75 ├──────────────────────┼────────────────────────────┤
76 │var │ Variable data (/var/) │
77 │ │ partition │
78 ├──────────────────────┼────────────────────────────┤
79 │tmp │ Temporary data (/var/tmp/) │
80 │ │ partition │
81 ├──────────────────────┼────────────────────────────┤
82 │linux-generic │ Generic Linux file system │
83 │ │ partition │
84 ├──────────────────────┼────────────────────────────┤
85 │root │ Root file system partition │
86 │ │ type appropriate for the │
87 │ │ local architecture (an │
88 │ │ alias for an architecture │
89 │ │ root file system partition │
90 │ │ type listed below, e.g. │
91 │ │ root-x86-64) │
92 ├──────────────────────┼────────────────────────────┤
93 │root-verity │ Verity data for the root │
94 │ │ file system partition for │
95 │ │ the local architecture │
96 ├──────────────────────┼────────────────────────────┤
97 │root-secondary │ Root file system partition │
98 │ │ of the secondary │
99 │ │ architecture of the local │
100 │ │ architecture (usually the │
101 │ │ matching 32bit │
102 │ │ architecture for the local │
103 │ │ 64bit architecture) │
104 ├──────────────────────┼────────────────────────────┤
105 │root-secondary-verity │ Verity data for the root │
106 │ │ file system partition of │
107 │ │ the secondary architecture │
108 ├──────────────────────┼────────────────────────────┤
109 │root-x86 │ Root file system partition │
110 │ │ for the x86 (32bit, aka │
111 │ │ i386) architecture │
112 ├──────────────────────┼────────────────────────────┤
113 │root-x86-verity │ Verity data for the x86 │
114 │ │ (32bit) root file system │
115 │ │ partition │
116 ├──────────────────────┼────────────────────────────┤
117 │root-x86-64 │ Root file system partition │
118 │ │ for the x86_64 (64bit, aka │
119 │ │ amd64) architecture │
120 ├──────────────────────┼────────────────────────────┤
121 │root-x86-64-verity │ Verity data for the x86_64 │
122 │ │ (64bit) root file system │
123 │ │ partition │
124 ├──────────────────────┼────────────────────────────┤
125 │root-arm │ Root file system partition │
126 │ │ for the ARM (32bit) │
127 │ │ architecture │
128 ├──────────────────────┼────────────────────────────┤
129 │root-arm-verity │ Verity data for the ARM │
130 │ │ (32bit) root file system │
131 │ │ partition │
132 ├──────────────────────┼────────────────────────────┤
133 │root-arm64 │ Root file system partition │
134 │ │ for the ARM (64bit, aka │
135 │ │ aarch64) architecture │
136 ├──────────────────────┼────────────────────────────┤
137 │root-arm64-verity │ Verity data for the ARM │
138 │ │ (64bit, aka aarch64) root │
139 │ │ file system partition │
140 ├──────────────────────┼────────────────────────────┤
141 │root-ia64 │ Root file system partition │
142 │ │ for the ia64 architecture │
143 ├──────────────────────┼────────────────────────────┤
144 │root-ia64-verity │ Verity data for the ia64 │
145 │ │ root file system partition │
146 └──────────────────────┴────────────────────────────┘
147 This setting defaults to linux-generic.
148 Most of the partition type UUIDs listed above are defined in the
150 Discoverable Partitions Specification[1].
151 Label=
153 The textual label to assign to the partition if none is assigned
154 yet. Note that this setting is not used for matching. It is also
155 not used when a label is already set for an existing partition. It
156 is thus only used when a partition is newly created or when an
157 existing one had a no label set (that is: an empty label). If not
158 specified a label derived from the partition type is automatically
159 used. Simple specifier expansion is supported, see below.
160 UUID=
162 The UUID to assign to the partition if none is assigned yet. Note
163 that this setting is not used for matching. It is also not used
164 when a UUID is already set for an existing partition. It is thus
165 only used when a partition is newly created or when an existing one
166 had a all-zero UUID set. If not specified a UUID derived from the
167 partition type is automatically used.
168 Priority=
170 A numeric priority to assign to this partition, in the range
171 -2147483648...2147483647, with smaller values indicating higher
172 priority, and higher values indicating smaller priority. This
173 priority is used in case the configured size constraints on the
174 defined partitions do not permit fitting all partitions onto the
175 available disk space. If the partitions do not fit, the highest
176 numeric partition priority of all defined partitions is determined,
177 and all defined partitions with this priority are removed from the
178 list of new partitions to create (which may be multiple, if the
179 same priority is used for multiple partitions). The fitting
180 algorithm is then tried again. If the partitions still do not fit,
181 the now highest numeric partition priority is determined, and the
182 matching partitions removed too, and so on. Partitions of a
183 priority of 0 or lower are never removed. If all partitions with a
184 priority above 0 are removed and the partitions still do not fit on
185 the device the operation fails. Note that this priority has no
186 effect on ordering partitions, for that use the alphabetical order
187 of the filenames of the partition definition files. Defaults to 0.
188 Weight=
190 A numeric weight to assign to this partition in the range
191 0...1000000. Available disk space is assigned the defined
192 partitions according to their relative weights (subject to the size
193 constraints configured with SizeMinBytes=, SizeMaxBytes=), so that
194 a partition with weight 2000 gets double the space as one with
195 weight 1000, and a partition with weight 333 a third of that.
196 Defaults to 1000.
197 The Weight= setting is used to distribute available disk space in
199 an "elastic" fashion, based on the disk size and existing
200 partitions. If a partition shall have a fixed size use both
201 SizeMinBytes= and SizeMaxBytes= with the same value in order to
202 fixate the size to one value, in which case the weight has no
203 effect.
204 PaddingWeight=
206 Similar to Weight= but sets a weight for the free space after the
207 partition (the "padding"). When distributing available space the
208 weights of all partitions and all defined padding is summed, and
209 then each partition and padding gets the fraction defined by its
210 weight. Defaults to 0, i.e. by default no padding is applied.
211 Padding is useful if empty space shall be left for later additions
213 or a safety margin at the end of the device or between partitions.
214 SizeMinBytes=, SizeMaxBytes=
216 Specifies minimum and maximum size constraints in bytes. Takes the
217 usual K, M, G, T, ... suffixes (to the base of 1024). If
218 SizeMinBytes= is specified the partition is created at or grown to
219 at least the specified size. If SizeMaxBytes= is specified the
220 partition is created at or grown to at most the specified size. The
221 precise size is determined through the weight value value
222 configured with Weight=, see above. When SizeMinBytes= is set equal
223 to SizeMaxBytes= the configured weight has no effect as the
224 partition is explicitly sized to the specified fixed value. Note
225 that partitions are never created smaller than 4096 bytes, and
226 since partitions are never shrunk the previous size of the
227 partition (in case the partition already exists) is also enforced
228 as lower bound for the new size. The values should be specified as
229 multiples of 4096 bytes, and are rounded upwards (in case of
230 SizeMinBytes=) or downwards (in case of SizeMaxBytes=) otherwise.
231 If the backing device does not provide enough space to fulfill the
232 constraints placing the partition will fail. For partitions that
233 shall be created, depending on the setting of Priority= (see above)
234 the partition might be dropped and the placing algorithm restarted.
235 By default a minimum size constraint of 10M and no maximum size
236 constraint is set.
237 PaddingMinBytes=, PaddingMaxBytes=
239 Specifies minimum and maximum size constraints in bytes for the
240 free space after the partition (the "padding"). Semantics are
241 similar to SizeMinBytes= and SizeMaxBytes=, except that unlike
242 partition sizes free space can be shrunk and can be as small as
243 zero. By default no size constraints on padding are set, so that
244 only PaddingWeight= determines the size of the padding applied.
245 CopyBlocks=
247 Takes a path to a regular file, block device node or directory. If
248 specified and the partition is newly created the data from the
249 specified path is written to the newly created partition, on the
250 block level. If a directory is specified the backing block device
251 of the file system the directory is on is determined and the data
252 read directly from that. This option is useful to efficiently
253 replicate existing file systems on the block level on a new
254 partition, for example to build a simple OS installer or OS image
255 builder.
256 The file specified here must have a size that is a multiple of the
258 basic block size 512 and not be empty. If this option is used, the
259 size allocation algorithm is slightly altered: the partition is
260 created as least as big as required to fit the data in, i.e. the
261 data size is an additional minimum size value taken into
262 consideration for the allocation algorithm, similar to and in
263 addition to the SizeMin= value configured above.
264 This option has no effect if the partition it is declared for
266 already exists, i.e. existing data is never overwritten. Note that
267 the data is copied in before the partition table is updated, i.e.
268 before the partition actually is persistently created. This
269 provides robustness: it is guaranteed that the partition either
270 doesn't exist or exists fully populated; it is not possible that
271 the partition exists but is not or only partially populated.
272 FactoryReset=
274 Takes a boolean argument. If specified the partition is marked for
275 removal during a factory reset operation. This functionality is
276 useful to implement schemes where images can be reset into their
277 original state by removing partitions and creating them anew.
278 Defaults to off.
279
281 Specifiers may be used in the Label= setting. The following expansions
282 are understood:
283 Table 2. Specifiers available
285 ┌──────────┬─────────────────────┬────────────────────────┐
286 │Specifier │ Meaning │ Details │
287 ├──────────┼─────────────────────┼────────────────────────┤
288 │"%a" │ Architecture │ A short string │
289 │ │ │ identifying the │
290 │ │ │ architecture of the │
291 │ │ │ local system. A │
292 │ │ │ string such as x86, │
293 │ │ │ x86-64 or arm64. │
294 │ │ │ See the │
295 │ │ │ architectures │
296 │ │ │ defined for │
297 │ │ │ ConditionArchitecture= │
298 │ │ │ in systemd.unit(5) │
299 │ │ │ for a full list. │
300 ├──────────┼─────────────────────┼────────────────────────┤
301 │"%b" │ Boot ID │ The boot ID of the │
302 │ │ │ running system, │
303 │ │ │ formatted as string. │
304 │ │ │ See random(4) for more │
305 │ │ │ information. │
306 ├──────────┼─────────────────────┼────────────────────────┤
307 │"%B" │ Operating system │ The operating system │
308 │ │ build ID │ build identifier of │
309 │ │ │ the running system, as │
310 │ │ │ read from the │
311 │ │ │ BUILD_ID= field of │
312 │ │ │ /etc/os-release. If │
313 │ │ │ not set, resolves to │
314 │ │ │ an empty string. See │
315 │ │ │ os-release(5) for more │
316 │ │ │ information. │
317 ├──────────┼─────────────────────┼────────────────────────┤
318 │"%H" │ Host name │ The hostname of the │
319 │ │ │ running system. │
320 ├──────────┼─────────────────────┼────────────────────────┤
321 │"%l" │ Short host name │ The hostname of the │
322 │ │ │ running system, │
323 │ │ │ truncated at the first │
324 │ │ │ dot to remove any │
325 │ │ │ domain component. │
326 ├──────────┼─────────────────────┼────────────────────────┤
327 │"%m" │ Machine ID │ The machine ID of the │
328 │ │ │ running system, │
329 │ │ │ formatted as string. │
330 │ │ │ See machine-id(5) for │
331 │ │ │ more information. │
332 ├──────────┼─────────────────────┼────────────────────────┤
333 │"%o" │ Operating system ID │ The operating system │
334 │ │ │ identifier of the │
335 │ │ │ running system, as │
336 │ │ │ read from the ID= │
337 │ │ │ field of │
338 │ │ │ /etc/os-release. See │
339 │ │ │ os-release(5) for more │
340 │ │ │ information. │
341 ├──────────┼─────────────────────┼────────────────────────┤
342 │"%v" │ Kernel release │ Identical to uname -r │
343 │ │ │ output. │
344 ├──────────┼─────────────────────┼────────────────────────┤
345 │"%w" │ Operating system │ The operating system │
346 │ │ version ID │ version identifier of │
347 │ │ │ the running system, as │
348 │ │ │ read from the │
349 │ │ │ VERSION_ID= field of │
350 │ │ │ /etc/os-release. If │
351 │ │ │ not set, resolves to │
352 │ │ │ an empty string. See │
353 │ │ │ os-release(5) for more │
354 │ │ │ information. │
355 ├──────────┼─────────────────────┼────────────────────────┤
356 │"%W" │ Operating system │ The operating system │
357 │ │ variant ID │ variant identifier of │
358 │ │ │ the running system, as │
359 │ │ │ read from the │
360 │ │ │ VARIANT_ID= field of │
361 │ │ │ /etc/os-release. If │
362 │ │ │ not set, resolves to │
363 │ │ │ an empty string. See │
364 │ │ │ os-release(5) for more │
365 │ │ │ information. │
366 ├──────────┼─────────────────────┼────────────────────────┤
367 │"%%" │ Single percent sign │ Use "%%" in place of │
368 │ │ │ "%" to specify a │
369 │ │ │ single percent sign. │
370 └──────────┴─────────────────────┴────────────────────────┘
371
373 Example 1. Grow the root partition to the full disk size at first boot
374 With the following file the root partition is automatically grown to
376 the full disk if possible during boot.
377 # /usr/lib/repart.d/50-root.conf
379 [Partition]
380 Type=root
381 Example 2. Create a swap and home partition automatically on boot, if
384 missing
385 The home partition gets all available disk space while the swap
387 partition gets 1G at most and 64M at least. We set a priority > 0 on
388 the swap partition to ensure the swap partition is not used if not
389 enough space is available. For every three bytes assigned to the home
390 partition the swap partition gets assigned one.
391 # /usr/lib/repart.d/60-home.conf
393 [Partition]
394 Type=home
395 # /usr/lib/repart.d/70-swap.conf
397 [Partition]
398 Type=swap
399 SizeMinBytes=64M
400 SizeMaxBytes=1G
401 Priority=1
402 Weight=333
403 Example 3. Create B partitions in an A/B Verity setup, if missing
406 Let's say the vendor intends to update OS images in an A/B setup, i.e.
408 with two root partitions (and two matching Verity partitions) that
409 shall be used alternatingly during upgrades. To minimize image sizes
410 the original image is shipped only with one root and one Verity
411 partition (the "A" set), and the second root and Verity partitions (the
412 "B" set) shall be created on first boot on the free space on the
413 medium.
414 # /usr/lib/repart.d/50-root.conf
416 [Partition]
417 Type=root
418 SizeMinBytes=512M
419 SizeMaxBytes=512M
420 # /usr/lib/repart.d/60-root-verity.conf
422 [Partition]
423 Type=root-verity
424 SizeMinBytes=64M
425 SizeMaxBytes=64M
426 The definitions above cover the "A" set of root partition (of a fixed
428 512M size) and Verity partition for the root partition (of a fixed 64M
429 size). Let's use symlinks to create the "B" set of partitions, since
430 after all they shall have the same properties and sizes as the "A" set.
431 # ln -s 50-root.conf /usr/lib/repart.d/70-root-b.conf
433 # ln -s 60-root-verity.conf /usr/lib/repart.d/80-root-verity-b.conf
434
437 systemd(1), systemd-repart(8), sfdisk(8)
438
440 1. Discoverable Partitions Specification
441 https://systemd.io/DISCOVERABLE_PARTITIONS
442systemd 246 REPART.D(5)