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