]>
Commit | Line | Data |
---|---|---|
917cc808 LP |
1 | <?xml version='1.0'?> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
f4d74c61 LB |
4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
5 | ||
e031166e LP |
6 | <refentry id="repart.d" conditional='ENABLE_REPART' |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
917cc808 LP |
8 | |
9 | <refentryinfo> | |
10 | <title>repart.d</title> | |
11 | <productname>systemd</productname> | |
12 | </refentryinfo> | |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>repart.d</refentrytitle> | |
16 | <manvolnum>5</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>repart.d</refname> | |
21 | <refpurpose>Partition Definition Files for Automatic Boot-Time Repartitioning</refpurpose> | |
22 | </refnamediv> | |
23 | ||
24 | <refsynopsisdiv> | |
25 | <para><literallayout><filename>/etc/repart.d/*.conf</filename> | |
26 | <filename>/run/repart.d/*.conf</filename> | |
27 | <filename>/usr/lib/repart.d/*.conf</filename> | |
28 | </literallayout></para> | |
29 | </refsynopsisdiv> | |
30 | ||
31 | <refsect1> | |
32 | <title>Description</title> | |
33 | ||
34 | <para><filename>repart.d/*.conf</filename> files describe basic properties of partitions of block | |
35 | devices of the local system. They may be used to declare types, names and sizes of partitions that shall | |
36 | exist. The | |
37 | <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
38 | service reads these files and attempts to add new partitions currently missing and enlarge existing | |
39 | partitions according to these definitions. Operation is generally incremental, i.e. when applied, what | |
40 | exists already is left intact, and partitions are never shrunk, moved or deleted.</para> | |
41 | ||
42 | <para>These definition files are useful for implementing operating system images that are prepared and | |
43 | delivered with minimally sized images (for example lacking any state or swap partitions), and which on | |
44 | first boot automatically take possession of any remaining disk space following a few basic rules.</para> | |
45 | ||
46 | <para>Currently, support for partition definition files is only implemented for GPT partitition | |
47 | tables.</para> | |
48 | ||
49 | <para>Partition files are generally matched against any partitions already existing on disk in a simple | |
50 | algorithm: the partition files are sorted by their filename (ignoring the directory prefix), and then | |
51 | compared in order against existing partitions matching the same partition type UUID. Specifically, the | |
52 | first existing partition with a specific partition type UUID is assigned the first definition file with | |
53 | the same partition type UUID, and the second existing partition with a specific type UUID the second | |
54 | partition file with the same type UUID, and so on. Any left-over partition files that have no matching | |
55 | existing partition are assumed to define new partition that shall be created. Such partitions are | |
56 | appended to the end of the partition table, in the order defined by their names utilizing the first | |
57 | partition slot greater than the highest slot number currently in use. Any existing partitions that have | |
58 | no matching partition file are left as they are.</para> | |
59 | ||
1c41c1dc | 60 | <para>Note that these definitions may only be used to create and initialize new partitions or to grow |
dfb4d0ae LP |
61 | existing ones. In the latter case it will not grow the contained files systems however; separate |
62 | mechanisms, such as | |
63 | <citerefentry><refentrytitle>systemd-growfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> may be | |
1c41c1dc LP |
64 | used to grow the file systems inside of these partitions. Partitions may also be marked for automatic |
65 | growing via the <varname>GrowFileSystem=</varname> setting, in which case the file system is grown on | |
66 | first mount by tools that respect this flag. See below for details.</para> | |
917cc808 LP |
67 | </refsect1> |
68 | ||
69 | <refsect1> | |
70 | <title>[Partition] Section Options</title> | |
71 | ||
72 | <variablelist> | |
73 | <varlistentry> | |
74 | <term><varname>Type=</varname></term> | |
75 | ||
76 | <listitem><para>The GPT partition type UUID to match. This may be a GPT partition type UUID such as | |
77 | <constant>4f68bce3-e8cd-4db1-96e7-fbcaf984b709</constant>, or one of the following special | |
78 | identifiers:</para> | |
79 | ||
80 | <table> | |
81 | <title>GPT partition type identifiers</title> | |
82 | ||
83 | <tgroup cols='2' align='left' colsep='1' rowsep='1'> | |
84 | <colspec colname="name" /> | |
85 | <colspec colname="explanation" /> | |
86 | ||
87 | <thead> | |
88 | <row> | |
89 | <entry>Identifier</entry> | |
90 | <entry>Explanation</entry> | |
91 | </row> | |
92 | </thead> | |
93 | ||
94 | <tbody> | |
95 | <row> | |
96 | <entry><constant>esp</constant></entry> | |
97 | <entry>EFI System Partition</entry> | |
98 | </row> | |
99 | ||
100 | <row> | |
101 | <entry><constant>xbootldr</constant></entry> | |
102 | <entry>Extended Boot Loader Partition</entry> | |
103 | </row> | |
104 | ||
105 | <row> | |
106 | <entry><constant>swap</constant></entry> | |
107 | <entry>Swap partition</entry> | |
108 | </row> | |
109 | ||
110 | <row> | |
111 | <entry><constant>home</constant></entry> | |
112 | <entry>Home (<filename>/home/</filename>) partition</entry> | |
113 | </row> | |
114 | ||
115 | <row> | |
116 | <entry><constant>srv</constant></entry> | |
117 | <entry>Server data (<filename>/srv/</filename>) partition</entry> | |
118 | </row> | |
119 | ||
120 | <row> | |
121 | <entry><constant>var</constant></entry> | |
122 | <entry>Variable data (<filename>/var/</filename>) partition</entry> | |
123 | </row> | |
124 | ||
125 | <row> | |
126 | <entry><constant>tmp</constant></entry> | |
127 | <entry>Temporary data (<filename>/var/tmp/</filename>) partition</entry> | |
128 | </row> | |
129 | ||
130 | <row> | |
131 | <entry><constant>linux-generic</constant></entry> | |
132 | <entry>Generic Linux file system partition</entry> | |
133 | </row> | |
134 | ||
135 | <row> | |
136 | <entry><constant>root</constant></entry> | |
137 | <entry>Root file system partition type appropriate for the local architecture (an alias for an architecture root file system partition type listed below, e.g. <constant>root-x86-64</constant>)</entry> | |
138 | </row> | |
139 | ||
140 | <row> | |
141 | <entry><constant>root-verity</constant></entry> | |
142 | <entry>Verity data for the root file system partition for the local architecture</entry> | |
143 | </row> | |
144 | ||
145 | <row> | |
146 | <entry><constant>root-secondary</constant></entry> | |
f4e1a425 | 147 | <entry>Root file system partition of the secondary architecture of the local architecture (usually the matching 32bit architecture for the local 64bit architecture)</entry> |
917cc808 LP |
148 | </row> |
149 | ||
150 | <row> | |
151 | <entry><constant>root-secondary-verity</constant></entry> | |
152 | <entry>Verity data for the root file system partition of the secondary architecture</entry> | |
153 | </row> | |
154 | ||
155 | <row> | |
156 | <entry><constant>root-x86</constant></entry> | |
157 | <entry>Root file system partition for the x86 (32bit, aka i386) architecture</entry> | |
158 | </row> | |
159 | ||
160 | <row> | |
161 | <entry><constant>root-x86-verity</constant></entry> | |
162 | <entry>Verity data for the x86 (32bit) root file system partition</entry> | |
163 | </row> | |
164 | ||
165 | <row> | |
166 | <entry><constant>root-x86-64</constant></entry> | |
167 | <entry>Root file system partition for the x86_64 (64bit, aka amd64) architecture</entry> | |
168 | </row> | |
169 | ||
170 | <row> | |
171 | <entry><constant>root-x86-64-verity</constant></entry> | |
172 | <entry>Verity data for the x86_64 (64bit) root file system partition</entry> | |
173 | </row> | |
174 | ||
175 | <row> | |
176 | <entry><constant>root-arm</constant></entry> | |
177 | <entry>Root file system partition for the ARM (32bit) architecture</entry> | |
178 | </row> | |
179 | ||
180 | <row> | |
181 | <entry><constant>root-arm-verity</constant></entry> | |
182 | <entry>Verity data for the ARM (32bit) root file system partition</entry> | |
183 | </row> | |
184 | ||
185 | <row> | |
186 | <entry><constant>root-arm64</constant></entry> | |
187 | <entry>Root file system partition for the ARM (64bit, aka aarch64) architecture</entry> | |
188 | </row> | |
189 | ||
190 | <row> | |
191 | <entry><constant>root-arm64-verity</constant></entry> | |
192 | <entry>Verity data for the ARM (64bit, aka aarch64) root file system partition</entry> | |
193 | </row> | |
194 | ||
195 | <row> | |
196 | <entry><constant>root-ia64</constant></entry> | |
197 | <entry>Root file system partition for the ia64 architecture</entry> | |
198 | </row> | |
199 | ||
200 | <row> | |
201 | <entry><constant>root-ia64-verity</constant></entry> | |
202 | <entry>Verity data for the ia64 root file system partition</entry> | |
203 | </row> | |
329cde79 | 204 | |
4e767154 WX |
205 | <row> |
206 | <entry><constant>root-loongarch64</constant></entry> | |
207 | <entry>Root file system partition for the LoongArch 64-bit architecture</entry> | |
208 | </row> | |
209 | ||
210 | <row> | |
211 | <entry><constant>root-loongarch64-verity</constant></entry> | |
212 | <entry>Verity data for the LoongArch 64-bit root file system partition</entry> | |
213 | </row> | |
214 | ||
499f0f82 DJL |
215 | <row> |
216 | <entry><constant>root-riscv32</constant></entry> | |
217 | <entry>Root file system partition for the RISC-V 32-bit architecture</entry> | |
218 | </row> | |
219 | ||
220 | <row> | |
221 | <entry><constant>root-riscv32-verity</constant></entry> | |
222 | <entry>Verity data for the RISC-V 32-bit root file system partition</entry> | |
223 | </row> | |
224 | ||
225 | <row> | |
226 | <entry><constant>root-riscv64</constant></entry> | |
227 | <entry>Root file system partition for the RISC-V 64-bit architecture</entry> | |
228 | </row> | |
229 | ||
230 | <row> | |
231 | <entry><constant>root-riscv64-verity</constant></entry> | |
232 | <entry>Verity data for the RISC-V 64-bit root file system partition</entry> | |
233 | </row> | |
234 | ||
329cde79 LP |
235 | <row> |
236 | <entry><constant>usr</constant></entry> | |
237 | <entry><filename>/usr/</filename> file system partition type appropriate for the local architecture (an alias for an architecture <filename>/usr/</filename> file system partition type listed below, e.g. <constant>usr-x86-64</constant>)</entry> | |
238 | </row> | |
239 | ||
240 | <row> | |
241 | <entry><constant>usr-verity</constant></entry> | |
242 | <entry>Verity data for the <filename>/usr/</filename> file system partition for the local architecture</entry> | |
243 | </row> | |
244 | ||
245 | <row> | |
246 | <entry><constant>usr-secondary</constant></entry> | |
247 | <entry><filename>/usr/</filename> file system partition of the secondary architecture of the local architecture (usually the matching 32bit architecture for the local 64bit architecture)</entry> | |
248 | </row> | |
249 | ||
250 | <row> | |
251 | <entry><constant>usr-secondary-verity</constant></entry> | |
252 | <entry>Verity data for the <filename>/usr/</filename> file system partition of the secondary architecture</entry> | |
253 | </row> | |
254 | ||
255 | <row> | |
256 | <entry><constant>usr-x86</constant></entry> | |
257 | <entry><filename>/usr/</filename> file system partition for the x86 (32bit, aka i386) architecture</entry> | |
258 | </row> | |
259 | ||
260 | <row> | |
261 | <entry><constant>usr-x86-verity</constant></entry> | |
262 | <entry>Verity data for the x86 (32bit) <filename>/usr/</filename> file system partition</entry> | |
263 | </row> | |
264 | ||
265 | <row> | |
266 | <entry><constant>usr-x86-64</constant></entry> | |
267 | <entry><filename>/usr/</filename> file system partition for the x86_64 (64bit, aka amd64) architecture</entry> | |
268 | </row> | |
269 | ||
270 | <row> | |
271 | <entry><constant>usr-x86-64-verity</constant></entry> | |
272 | <entry>Verity data for the x86_64 (64bit) <filename>/usr/</filename> file system partition</entry> | |
273 | </row> | |
274 | ||
275 | <row> | |
276 | <entry><constant>usr-arm</constant></entry> | |
277 | <entry><filename>/usr/</filename> file system partition for the ARM (32bit) architecture</entry> | |
278 | </row> | |
279 | ||
280 | <row> | |
281 | <entry><constant>usr-arm-verity</constant></entry> | |
282 | <entry>Verity data for the ARM (32bit) <filename>/usr/</filename> file system partition</entry> | |
283 | </row> | |
284 | ||
285 | <row> | |
286 | <entry><constant>usr-arm64</constant></entry> | |
287 | <entry><filename>/usr/</filename> file system partition for the ARM (64bit, aka aarch64) architecture</entry> | |
288 | </row> | |
289 | ||
290 | <row> | |
291 | <entry><constant>usr-arm64-verity</constant></entry> | |
292 | <entry>Verity data for the ARM (64bit, aka aarch64) <filename>/usr/</filename> file system partition</entry> | |
293 | </row> | |
294 | ||
295 | <row> | |
296 | <entry><constant>usr-ia64</constant></entry> | |
297 | <entry><filename>/usr/</filename> file system partition for the ia64 architecture</entry> | |
298 | </row> | |
299 | ||
300 | <row> | |
301 | <entry><constant>usr-ia64-verity</constant></entry> | |
302 | <entry>Verity data for the ia64 <filename>/usr/</filename> file system partition</entry> | |
303 | </row> | |
499f0f82 | 304 | |
4e767154 WX |
305 | <row> |
306 | <entry><constant>usr-loongarch64</constant></entry> | |
307 | <entry><filename>/usr/</filename> file system partition for the LoongArch 64-bit architecture</entry> | |
308 | </row> | |
309 | ||
310 | <row> | |
311 | <entry><constant>usr-loongarch64-verity</constant></entry> | |
312 | <entry>Verity data for the LoongArch 64-bit <filename>/usr/</filename> file system partition</entry> | |
313 | </row> | |
314 | ||
499f0f82 DJL |
315 | <row> |
316 | <entry><constant>usr-riscv32</constant></entry> | |
317 | <entry><filename>/usr/</filename> file system partition for the RISC-V 32-bit architecture</entry> | |
318 | </row> | |
319 | ||
320 | <row> | |
321 | <entry><constant>usr-riscv32-verity</constant></entry> | |
322 | <entry>Verity data for the RISC-V 32-bit <filename>/usr/</filename> file system partition</entry> | |
323 | </row> | |
324 | ||
325 | <row> | |
326 | <entry><constant>usr-riscv64</constant></entry> | |
327 | <entry><filename>/usr/</filename> file system partition for the RISC-V 64-bit architecture</entry> | |
328 | </row> | |
329 | ||
330 | <row> | |
331 | <entry><constant>usr-riscv64-verity</constant></entry> | |
332 | <entry>Verity data for the RISC-V 64-bit <filename>/usr/</filename> file system partition</entry> | |
333 | </row> | |
917cc808 LP |
334 | </tbody> |
335 | </tgroup> | |
336 | </table> | |
337 | ||
338 | <para>This setting defaults to <constant>linux-generic</constant>.</para> | |
339 | ||
340 | <para>Most of the partition type UUIDs listed above are defined in the <ulink | |
341 | url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions | |
342 | Specification</ulink>.</para></listitem> | |
343 | </varlistentry> | |
344 | ||
345 | <varlistentry> | |
346 | <term><varname>Label=</varname></term> | |
347 | ||
348 | <listitem><para>The textual label to assign to the partition if none is assigned yet. Note that this | |
349 | setting is not used for matching. It is also not used when a label is already set for an existing | |
350 | partition. It is thus only used when a partition is newly created or when an existing one had a no | |
351 | label set (that is: an empty label). If not specified a label derived from the partition type is | |
e031166e | 352 | automatically used. Simple specifier expansion is supported, see below.</para></listitem> |
917cc808 LP |
353 | </varlistentry> |
354 | ||
12963533 TH |
355 | <varlistentry> |
356 | <term><varname>UUID=</varname></term> | |
357 | ||
358 | <listitem><para>The UUID to assign to the partition if none is assigned yet. Note that this | |
359 | setting is not used for matching. It is also not used when a UUID is already set for an existing | |
360 | partition. It is thus only used when a partition is newly created or when an existing one had a | |
361 | all-zero UUID set. If not specified a UUID derived from the partition type is automatically | |
362 | used.</para></listitem> | |
363 | </varlistentry> | |
364 | ||
917cc808 LP |
365 | <varlistentry> |
366 | <term><varname>Priority=</varname></term> | |
367 | ||
368 | <listitem><para>A numeric priority to assign to this partition, in the range -2147483648…2147483647, | |
369 | with smaller values indicating higher priority, and higher values indicating smaller priority. This | |
370 | priority is used in case the configured size constraints on the defined partitions do not permit | |
371 | fitting all partitions onto the available disk space. If the partitions do not fit, the highest | |
372 | numeric partition priority of all defined partitions is determined, and all defined partitions with | |
373 | this priority are removed from the list of new partitions to create (which may be multiple, if the | |
374 | same priority is used for multiple partitions). The fitting algorithm is then tried again. If the | |
375 | partitions still do not fit, the now highest numeric partition priority is determined, and the | |
376 | matching partitions removed too, and so on. Partitions of a priority of 0 or lower are never | |
377 | removed. If all partitions with a priority above 0 are removed and the partitions still do not fit on | |
378 | the device the operation fails. Note that this priority has no effect on ordering partitions, for | |
379 | that use the alphabetical order of the filenames of the partition definition files. Defaults to | |
380 | 0.</para></listitem> | |
381 | </varlistentry> | |
382 | ||
383 | <varlistentry> | |
384 | <term><varname>Weight=</varname></term> | |
385 | ||
386 | <listitem><para>A numeric weight to assign to this partition in the range 0…1000000. Available disk | |
387 | space is assigned the defined partitions according to their relative weights (subject to the size | |
388 | constraints configured with <varname>SizeMinBytes=</varname>, <varname>SizeMaxBytes=</varname>), so | |
389 | that a partition with weight 2000 gets double the space as one with weight 1000, and a partition with | |
390 | weight 333 a third of that. Defaults to 1000.</para> | |
391 | ||
392 | <para>The <varname>Weight=</varname> setting is used to distribute available disk space in an | |
393 | "elastic" fashion, based on the disk size and existing partitions. If a partition shall have a fixed | |
394 | size use both <varname>SizeMinBytes=</varname> and <varname>SizeMaxBytes=</varname> with the same | |
395 | value in order to fixate the size to one value, in which case the weight has no | |
396 | effect.</para></listitem> | |
397 | </varlistentry> | |
398 | ||
399 | <varlistentry> | |
400 | <term><varname>PaddingWeight=</varname></term> | |
401 | ||
15102ced | 402 | <listitem><para>Similar to <varname>Weight=</varname>, but sets a weight for the free space after the |
917cc808 LP |
403 | partition (the "padding"). When distributing available space the weights of all partitions and all |
404 | defined padding is summed, and then each partition and padding gets the fraction defined by its | |
405 | weight. Defaults to 0, i.e. by default no padding is applied.</para> | |
406 | ||
407 | <para>Padding is useful if empty space shall be left for later additions or a safety margin at the | |
408 | end of the device or between partitions.</para></listitem> | |
409 | </varlistentry> | |
410 | ||
411 | <varlistentry> | |
412 | <term><varname>SizeMinBytes=</varname></term> | |
413 | <term><varname>SizeMaxBytes=</varname></term> | |
414 | ||
415 | <listitem><para>Specifies minimum and maximum size constraints in bytes. Takes the usual K, M, G, T, | |
416 | … suffixes (to the base of 1024). If <varname>SizeMinBytes=</varname> is specified the partition is | |
417 | created at or grown to at least the specified size. If <varname>SizeMaxBytes=</varname> is specified | |
418 | the partition is created at or grown to at most the specified size. The precise size is determined | |
84b10e53 | 419 | through the weight value configured with <varname>Weight=</varname>, see above. When |
917cc808 LP |
420 | <varname>SizeMinBytes=</varname> is set equal to <varname>SizeMaxBytes=</varname> the configured |
421 | weight has no effect as the partition is explicitly sized to the specified fixed value. Note that | |
422 | partitions are never created smaller than 4096 bytes, and since partitions are never shrunk the | |
423 | previous size of the partition (in case the partition already exists) is also enforced as lower bound | |
424 | for the new size. The values should be specified as multiples of 4096 bytes, and are rounded upwards | |
425 | (in case of <varname>SizeMinBytes=</varname>) or downwards (in case of | |
426 | <varname>SizeMaxBytes=</varname>) otherwise. If the backing device does not provide enough space to | |
427 | fulfill the constraints placing the partition will fail. For partitions that shall be created, | |
428 | depending on the setting of <varname>Priority=</varname> (see above) the partition might be dropped | |
fb08381c LP |
429 | and the placing algorithm restarted. By default a minimum size constraint of 10M and no maximum size |
430 | constraint is set.</para></listitem> | |
917cc808 LP |
431 | </varlistentry> |
432 | ||
433 | <varlistentry> | |
434 | <term><varname>PaddingMinBytes=</varname></term> | |
435 | <term><varname>PaddingMaxBytes=</varname></term> | |
436 | ||
757bc2e4 | 437 | <listitem><para>Specifies minimum and maximum size constraints in bytes for the free space after the |
917cc808 LP |
438 | partition (the "padding"). Semantics are similar to <varname>SizeMinBytes=</varname> and |
439 | <varname>SizeMaxBytes=</varname>, except that unlike partition sizes free space can be shrunk and can | |
440 | be as small as zero. By default no size constraints on padding are set, so that only | |
441 | <varname>PaddingWeight=</varname> determines the size of the padding applied.</para></listitem> | |
442 | </varlistentry> | |
443 | ||
757bc2e4 LP |
444 | <varlistentry> |
445 | <term><varname>CopyBlocks=</varname></term> | |
446 | ||
5c08da58 LP |
447 | <listitem><para>Takes a path to a regular file, block device node or directory, or the special value |
448 | <literal>auto</literal>. If specified and the partition is newly created, the data from the specified | |
449 | path is written to the newly created partition, on the block level. If a directory is specified, the | |
450 | backing block device of the file system the directory is on is determined, and the data read directly | |
451 | from that. This option is useful to efficiently replicate existing file systems onto new partitions | |
452 | on the block level — for example to build a simple OS installer or an OS image builder.</para> | |
453 | ||
454 | <para>If the special value <literal>auto</literal> is specified, the source to copy from is | |
455 | automatically picked up from the running system (or the image specified with | |
456 | <option>--image=</option> — if used). A partition that matches both the configured partition type (as | |
be0d27ee ZJS |
457 | declared with <varname>Type=</varname> described above), and the currently mounted directory |
458 | appropriate for that partition type is determined. For example, if the partition type is set to | |
5c08da58 LP |
459 | <literal>root</literal> the partition backing the root directory (<filename>/</filename>) is used as |
460 | source to copy from — if its partition type is set to <literal>root</literal> as well. If the | |
461 | declared type is <literal>usr</literal> the partition backing <filename>/usr/</filename> is used as | |
462 | source to copy blocks from — if its partition type is set to <literal>usr</literal> too. The logic is | |
3d62af7d | 463 | capable of automatically tracking down the backing partitions for encrypted and Verity-enabled |
5c08da58 LP |
464 | volumes. <literal>CopyBlocks=auto</literal> is useful for implementing "self-replicating" systems, |
465 | i.e. systems that are their own installer.</para> | |
757bc2e4 LP |
466 | |
467 | <para>The file specified here must have a size that is a multiple of the basic block size 512 and not | |
468 | be empty. If this option is used, the size allocation algorithm is slightly altered: the partition is | |
469 | created as least as big as required to fit the data in, i.e. the data size is an additional minimum | |
470 | size value taken into consideration for the allocation algorithm, similar to and in addition to the | |
471 | <varname>SizeMin=</varname> value configured above.</para> | |
472 | ||
473 | <para>This option has no effect if the partition it is declared for already exists, i.e. existing | |
474 | data is never overwritten. Note that the data is copied in before the partition table is updated, | |
475 | i.e. before the partition actually is persistently created. This provides robustness: it is | |
476 | guaranteed that the partition either doesn't exist or exists fully populated; it is not possible that | |
dfb4d0ae LP |
477 | the partition exists but is not or only partially populated.</para> |
478 | ||
479 | <para>This option cannot be combined with <varname>Format=</varname> or | |
480 | <varname>CopyFiles=</varname>.</para></listitem> | |
481 | </varlistentry> | |
482 | ||
483 | <varlistentry> | |
484 | <term><varname>Format=</varname></term> | |
485 | ||
486 | <listitem><para>Takes a file system name, such as <literal>ext4</literal>, <literal>btrfs</literal>, | |
487 | <literal>xfs</literal> or <literal>vfat</literal>, or the special value <literal>swap</literal>. If | |
488 | specified and the partition is newly created it is formatted with the specified file system (or as | |
489 | swap device). The file system UUID and label are automatically derived from the partition UUID and | |
490 | label. If this option is used, the size allocation algorithm is slightly altered: the partition is | |
491 | created as least as big as required for the minimal file system of the specified type (or 4KiB if the | |
492 | minimal size is not known).</para> | |
493 | ||
494 | <para>This option has no effect if the partition already exists.</para> | |
495 | ||
15102ced ZJS |
496 | <para>Similarly to the behaviour of <varname>CopyBlocks=</varname>, the file system is formatted |
497 | before the partition is created, ensuring that the partition only ever exists with a fully | |
498 | initialized file system.</para> | |
dfb4d0ae LP |
499 | |
500 | <para>This option cannot be combined with <varname>CopyBlocks=</varname>.</para></listitem> | |
501 | </varlistentry> | |
502 | ||
503 | <varlistentry> | |
504 | <term><varname>CopyFiles=</varname></term> | |
505 | ||
506 | <listitem><para>Takes a pair of colon separated absolute file system paths. The first path refers to | |
507 | a source file or directory on the host, the second path refers to a target in the file system of the | |
508 | newly created partition and formatted file system. This setting may be used to copy files or | |
509 | directories from the host into the file system that is created due to the <varname>Format=</varname> | |
510 | option. If <varname>CopyFiles=</varname> is used without <varname>Format=</varname> specified | |
511 | explicitly, <literal>Format=</literal> with a suitable default is implied (currently | |
512 | <literal>ext4</literal>, but this may change in the future). This option may be used multiple times | |
513 | to copy multiple files or directories from host into the newly formatted file system. The colon and | |
514 | second path may be omitted in which case the source path is also used as the target path (relative to | |
515 | the root of the newly created file system). If the source path refers to a directory it is copied | |
516 | recursively.</para> | |
517 | ||
518 | <para>This option has no effect if the partition already exists: it cannot be used to copy additional | |
519 | files into an existing partition, it may only be used to populate a file system created anew.</para> | |
520 | ||
521 | <para>The copy operation is executed before the file system is registered in the partition table, | |
522 | thus ensuring that a file system populated this way only ever exists fully initialized.</para> | |
523 | ||
252d6267 LP |
524 | <para>This option cannot be combined with <varname>CopyBlocks=</varname>.</para> |
525 | ||
526 | <para>When <command>systemd-repart</command> is invoked with the <option>--image=</option> or | |
527 | <option>--root=</option> command line switches the source paths specified are taken relative to the | |
528 | specified root directory or disk image root.</para></listitem> | |
dfb4d0ae LP |
529 | </varlistentry> |
530 | ||
d83d8048 LP |
531 | <varlistentry> |
532 | <term><varname>MakeDirectories=</varname></term> | |
533 | ||
be0d27ee | 534 | <listitem><para>Takes one or more absolute paths, separated by whitespace, each declaring a directory |
d83d8048 LP |
535 | to create within the new file system. Behaviour is similar to <varname>CopyFiles=</varname>, but |
536 | instead of copying in a set of files this just creates the specified directories with the default | |
537 | mode of 0755 owned by the root user and group, plus all their parent directories (with the same | |
538 | ownership and access mode). To configure directories with different ownership or access mode, use | |
539 | <varname>CopyFiles=</varname> and specify a source tree to copy containing appropriately | |
540 | owned/configured directories. This option may be used more than once to create multiple | |
541 | directories. When <varname>CopyFiles=</varname> and <varname>MakeDirectories=</varname> are used | |
542 | together the former is applied first. If a directory listed already exists no operation is executed | |
543 | (in particular, the ownership/access mode of the directories is left as is).</para> | |
544 | ||
545 | <para>The primary usecase for this option is to create a minimal set of directories that may be | |
546 | mounted over by other partitions contained in the same disk image. For example, a disk image where | |
547 | the root file system is formatted at first boot might want to automatically pre-create | |
548 | <filename>/usr/</filename> in it this way, so that the <literal>usr</literal> partition may | |
549 | over-mount it.</para> | |
550 | ||
551 | <para>Consider using | |
552 | <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
553 | with its <option>--image=</option> option to pre-create other, more complex directory hierarchies (as | |
554 | well as other inodes) with fine-grained control of ownership, access modes and other file | |
555 | attributes.</para></listitem> | |
556 | </varlistentry> | |
557 | ||
dfb4d0ae LP |
558 | <varlistentry> |
559 | <term><varname>Encrypt=</varname></term> | |
560 | ||
cf1e172d LP |
561 | <listitem><para>Takes one of <literal>off</literal>, <literal>key-file</literal>, |
562 | <literal>tpm2</literal> and <literal>key-file+tpm2</literal> (alternatively, also accepts a boolean | |
563 | value, which is mapped to <literal>off</literal> when false, and <literal>key-file</literal> when | |
564 | true). Defaults to <literal>off</literal>. If not <literal>off</literal> the partition will be | |
dfb4d0ae LP |
565 | formatted with a LUKS2 superblock, before the blocks configured with <varname>CopyBlocks=</varname> |
566 | are copied in or the file system configured with <varname>Format=</varname> is created.</para> | |
567 | ||
cf1e172d | 568 | <para>The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion. If |
be0d27ee ZJS |
569 | <literal>key-file</literal> or <literal>key-file+tpm2</literal> is used, a key is added to the LUKS2 |
570 | superblock, configurable with the <option>--key-file=</option> option to | |
cf1e172d | 571 | <command>systemd-repart</command>. If <literal>tpm2</literal> or <literal>key-file+tpm2</literal> is |
be0d27ee | 572 | used, a key is added to the LUKS2 superblock that is enrolled to the local TPM2 chip, as configured |
cf1e172d | 573 | with the <option>--tpm2-device=</option> and <option>--tpm2-pcrs=</option> options to |
dfb4d0ae LP |
574 | <command>systemd-repart</command>.</para> |
575 | ||
576 | <para>When used this slightly alters the size allocation logic as the implicit, minimal size limits | |
577 | of <varname>Format=</varname> and <varname>CopyBlocks=</varname> are increased by the space necessary | |
578 | for the LUKS2 superblock (see above).</para> | |
579 | ||
580 | <para>This option has no effect if the partition already exists.</para></listitem> | |
757bc2e4 LP |
581 | </varlistentry> |
582 | ||
917cc808 LP |
583 | <varlistentry> |
584 | <term><varname>FactoryReset=</varname></term> | |
585 | ||
586 | <listitem><para>Takes a boolean argument. If specified the partition is marked for removal during a | |
587 | factory reset operation. This functionality is useful to implement schemes where images can be reset | |
588 | into their original state by removing partitions and creating them anew. Defaults to off.</para></listitem> | |
589 | </varlistentry> | |
e73309c5 LP |
590 | |
591 | <varlistentry> | |
592 | <term><varname>Flags=</varname></term> | |
593 | ||
ff0771bf | 594 | <listitem><para>Configures the 64bit GPT partition flags field to set for the partition when creating |
e73309c5 | 595 | it. This option has no effect if the partition already exists. If not specified the flags values is |
ff0771bf LP |
596 | set to all zeroes, except for the three bits that can also be configured via |
597 | <varname>NoAuto=</varname>, <varname>ReadOnly=</varname> and <varname>GrowFileSystem=</varname>; see | |
598 | below for details on the defaults for these three flags. Specify the flags value in hexadecimal (by | |
599 | prefixing it with <literal>0x</literal>), binary (prefix <literal>0b</literal>) or decimal (no | |
600 | prefix).</para></listitem> | |
e73309c5 LP |
601 | </varlistentry> |
602 | ||
603 | <varlistentry> | |
ff0771bf | 604 | <term><varname>NoAuto=</varname></term> |
e73309c5 | 605 | <term><varname>ReadOnly=</varname></term> |
1c41c1dc LP |
606 | <term><varname>GrowFileSystem=</varname></term> |
607 | ||
ff0771bf LP |
608 | <listitem><para>Configures the No-Auto, Read-Only and Grow-File-System partition flags (bit 63, 60 |
609 | and 59) of the partition table entry, as defined by the <ulink | |
1c41c1dc | 610 | url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions Specification</ulink>. Only |
ff0771bf LP |
611 | available for partition types supported by the specification. This option is a friendly way to set |
612 | bits 63, 60 and 59 of the partition flags value without setting any of the other bits, and may be set | |
613 | via <varname>Flags=</varname> too, see above.</para> | |
1c41c1dc | 614 | |
ff0771bf LP |
615 | <para>If <varname>Flags=</varname> is used in conjunction with one or more of |
616 | <varname>NoAuto=</varname>/<varname>ReadOnly=</varname>/<varname>GrowFileSystem=</varname> the latter | |
617 | control the value of the relevant flags, i.e. the high-level settings | |
618 | <varname>NoAuto=</varname>/<varname>ReadOnly=</varname>/<varname>GrowFileSystem=</varname> override | |
619 | the relevant bits of the low-level setting <varname>Flags=</varname>.</para> | |
1c41c1dc | 620 | |
ff0771bf | 621 | <para>Note that the three flags affect only automatic partition mounting, as implemented by |
1c41c1dc LP |
622 | <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
623 | or the <option>--image=</option> option of various commands (such as | |
624 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>). It | |
625 | has no effect on explicit mounts, such as those done via <citerefentry | |
626 | project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> or | |
627 | <citerefentry | |
be0d27ee | 628 | project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> |
1c41c1dc LP |
629 | |
630 | <para>If both bit 50 and 59 are set for a partition (i.e. the partition is marked both read-only and | |
631 | marked for file system growing) the latter is typically without effect: the read-only flag takes | |
632 | precedence in most tools reading these flags, and since growing the file system involves writing to | |
633 | the partition it is consequently ignored.</para> | |
634 | ||
ff0771bf LP |
635 | <para><varname>NoAuto=</varname> defaults to off. <varname>ReadOnly=</varname> defaults to on for |
636 | Verity partition types, and off for all others. <varname>GrowFileSystem=</varname> defaults to on for | |
637 | all partition types that support it, except if the partition is marked read-only (and thus | |
638 | effectively, defaults to off for Verity partitions).</para></listitem> | |
e73309c5 | 639 | </varlistentry> |
917cc808 LP |
640 | </variablelist> |
641 | </refsect1> | |
642 | ||
e031166e LP |
643 | <refsect1> |
644 | <title>Specifiers</title> | |
645 | ||
b3e22322 LP |
646 | <para>Specifiers may be used in the <varname>Label=</varname>, <varname>CopyBlocks=</varname>, |
647 | <varname>CopyFiles=</varname>, <varname>MakeDirectories=</varname> settings. The following expansions are | |
648 | understood:</para> | |
e031166e LP |
649 | <table class='specifiers'> |
650 | <title>Specifiers available</title> | |
651 | <tgroup cols='3' align='left' colsep='1' rowsep='1'> | |
652 | <colspec colname="spec" /> | |
653 | <colspec colname="mean" /> | |
654 | <colspec colname="detail" /> | |
655 | <thead> | |
656 | <row> | |
657 | <entry>Specifier</entry> | |
658 | <entry>Meaning</entry> | |
659 | <entry>Details</entry> | |
660 | </row> | |
661 | </thead> | |
662 | <tbody> | |
663 | <xi:include href="standard-specifiers.xml" xpointer="a"/> | |
9a515f0a | 664 | <xi:include href="standard-specifiers.xml" xpointer="A"/> |
e031166e LP |
665 | <xi:include href="standard-specifiers.xml" xpointer="b"/> |
666 | <xi:include href="standard-specifiers.xml" xpointer="B"/> | |
667 | <xi:include href="standard-specifiers.xml" xpointer="H"/> | |
668 | <xi:include href="standard-specifiers.xml" xpointer="l"/> | |
669 | <xi:include href="standard-specifiers.xml" xpointer="m"/> | |
9a515f0a | 670 | <xi:include href="standard-specifiers.xml" xpointer="M"/> |
e031166e LP |
671 | <xi:include href="standard-specifiers.xml" xpointer="o"/> |
672 | <xi:include href="standard-specifiers.xml" xpointer="v"/> | |
673 | <xi:include href="standard-specifiers.xml" xpointer="w"/> | |
674 | <xi:include href="standard-specifiers.xml" xpointer="W"/> | |
b3e22322 LP |
675 | <xi:include href="standard-specifiers.xml" xpointer="T"/> |
676 | <xi:include href="standard-specifiers.xml" xpointer="V"/> | |
e031166e LP |
677 | <xi:include href="standard-specifiers.xml" xpointer="percent"/> |
678 | </tbody> | |
679 | </tgroup> | |
680 | </table> | |
681 | </refsect1> | |
682 | ||
917cc808 LP |
683 | <refsect1> |
684 | <title>Examples</title> | |
685 | ||
686 | <example> | |
687 | <title>Grow the root partition to the full disk size at first boot</title> | |
688 | ||
689 | <para>With the following file the root partition is automatically grown to the full disk if possible during boot.</para> | |
690 | ||
691 | <para><programlisting># /usr/lib/repart.d/50-root.conf | |
692 | [Partition] | |
693 | Type=root | |
694 | </programlisting></para> | |
695 | </example> | |
696 | ||
697 | <example> | |
698 | <title>Create a swap and home partition automatically on boot, if missing</title> | |
699 | ||
700 | <para>The home partition gets all available disk space while the swap partition gets 1G at most and 64M | |
701 | at least. We set a priority > 0 on the swap partition to ensure the swap partition is not used if not | |
702 | enough space is available. For every three bytes assigned to the home partition the swap partition gets | |
703 | assigned one.</para> | |
704 | ||
705 | <para><programlisting># /usr/lib/repart.d/60-home.conf | |
706 | [Partition] | |
707 | Type=home | |
708 | </programlisting></para> | |
709 | ||
710 | <para><programlisting># /usr/lib/repart.d/70-swap.conf | |
711 | [Partition] | |
712 | Type=swap | |
713 | SizeMinBytes=64M | |
714 | SizeMaxBytes=1G | |
715 | Priority=1 | |
716 | Weight=333 | |
717 | </programlisting></para> | |
718 | </example> | |
719 | ||
720 | <example> | |
721 | <title>Create B partitions in an A/B Verity setup, if missing</title> | |
722 | ||
723 | <para>Let's say the vendor intends to update OS images in an A/B setup, i.e. with two root partitions | |
724 | (and two matching Verity partitions) that shall be used alternatingly during upgrades. To minimize | |
725 | image sizes the original image is shipped only with one root and one Verity partition (the "A" set), | |
726 | and the second root and Verity partitions (the "B" set) shall be created on first boot on the free | |
727 | space on the medium.</para> | |
728 | ||
729 | <para><programlisting># /usr/lib/repart.d/50-root.conf | |
730 | [Partition] | |
731 | Type=root | |
732 | SizeMinBytes=512M | |
733 | SizeMaxBytes=512M | |
734 | </programlisting></para> | |
735 | ||
736 | <para><programlisting># /usr/lib/repart.d/60-root-verity.conf | |
737 | [Partition] | |
738 | Type=root-verity | |
739 | SizeMinBytes=64M | |
740 | SizeMaxBytes=64M | |
741 | </programlisting></para> | |
742 | ||
743 | <para>The definitions above cover the "A" set of root partition (of a fixed 512M size) and Verity | |
744 | partition for the root partition (of a fixed 64M size). Let's use symlinks to create the "B" set of | |
745 | partitions, since after all they shall have the same properties and sizes as the "A" set.</para> | |
746 | ||
747 | <para><programlisting># ln -s 50-root.conf /usr/lib/repart.d/70-root-b.conf | |
748 | # ln -s 60-root-verity.conf /usr/lib/repart.d/80-root-verity-b.conf | |
749 | </programlisting></para> | |
750 | </example> | |
751 | ||
752 | </refsect1> | |
753 | ||
754 | <refsect1> | |
755 | <title>See Also</title> | |
756 | <para> | |
757 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
758 | <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
cf1e172d LP |
759 | <citerefentry project='man-pages'><refentrytitle>sfdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
760 | <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
917cc808 LP |
761 | </para> |
762 | </refsect1> | |
763 | ||
764 | </refentry> |