]>
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 | ||
dc3b5e04 | 46 | <para>Currently, support for partition definition files is only implemented for GPT partition |
917cc808 LP |
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 | |
b45b4f50 P |
77 | <constant>4f68bce3-e8cd-4db1-96e7-fbcaf984b709</constant>, or an identifier. |
78 | Architecture specific partition types can use one of these architecture identifiers: | |
da890466 ZJS |
79 | <constant>alpha</constant>, <constant>arc</constant>, <constant>arm</constant> (32-bit), |
80 | <constant>arm64</constant> (64-bit, aka aarch64), <constant>ia64</constant>, | |
b45b4f50 P |
81 | <constant>loongarch64</constant>, <constant>mips-le</constant>, <constant>mips64-le</constant>, |
82 | <constant>parisc</constant>, <constant>ppc</constant>, <constant>ppc64</constant>, | |
83 | <constant>ppc64-le</constant>, <constant>riscv32</constant>, <constant>riscv64</constant>, | |
84 | <constant>s390</constant>, <constant>s390x</constant>, <constant>tilegx</constant>, | |
da890466 | 85 | <constant>x86</constant> (32-bit, aka i386) and <constant>x86-64</constant> (64-bit, aka amd64). |
6d9829e7 | 86 | </para> |
b45b4f50 | 87 | |
6d9829e7 | 88 | <para>The supported identifiers are:</para> |
917cc808 LP |
89 | |
90 | <table> | |
91 | <title>GPT partition type identifiers</title> | |
92 | ||
93 | <tgroup cols='2' align='left' colsep='1' rowsep='1'> | |
94 | <colspec colname="name" /> | |
95 | <colspec colname="explanation" /> | |
96 | ||
97 | <thead> | |
98 | <row> | |
99 | <entry>Identifier</entry> | |
100 | <entry>Explanation</entry> | |
101 | </row> | |
102 | </thead> | |
103 | ||
104 | <tbody> | |
105 | <row> | |
106 | <entry><constant>esp</constant></entry> | |
107 | <entry>EFI System Partition</entry> | |
108 | </row> | |
109 | ||
110 | <row> | |
111 | <entry><constant>xbootldr</constant></entry> | |
112 | <entry>Extended Boot Loader Partition</entry> | |
113 | </row> | |
114 | ||
115 | <row> | |
116 | <entry><constant>swap</constant></entry> | |
117 | <entry>Swap partition</entry> | |
118 | </row> | |
119 | ||
120 | <row> | |
121 | <entry><constant>home</constant></entry> | |
122 | <entry>Home (<filename>/home/</filename>) partition</entry> | |
123 | </row> | |
124 | ||
125 | <row> | |
126 | <entry><constant>srv</constant></entry> | |
127 | <entry>Server data (<filename>/srv/</filename>) partition</entry> | |
128 | </row> | |
129 | ||
130 | <row> | |
131 | <entry><constant>var</constant></entry> | |
132 | <entry>Variable data (<filename>/var/</filename>) partition</entry> | |
133 | </row> | |
134 | ||
135 | <row> | |
136 | <entry><constant>tmp</constant></entry> | |
137 | <entry>Temporary data (<filename>/var/tmp/</filename>) partition</entry> | |
138 | </row> | |
139 | ||
140 | <row> | |
141 | <entry><constant>linux-generic</constant></entry> | |
142 | <entry>Generic Linux file system partition</entry> | |
143 | </row> | |
144 | ||
145 | <row> | |
146 | <entry><constant>root</constant></entry> | |
147 | <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> | |
148 | </row> | |
149 | ||
150 | <row> | |
151 | <entry><constant>root-verity</constant></entry> | |
152 | <entry>Verity data for the root file system partition for the local architecture</entry> | |
153 | </row> | |
154 | ||
b45b4f50 P |
155 | <row> |
156 | <entry><constant>root-verity-sig</constant></entry> | |
157 | <entry>Verity signature data for the root file system partition for the local architecture</entry> | |
158 | </row> | |
159 | ||
917cc808 LP |
160 | <row> |
161 | <entry><constant>root-secondary</constant></entry> | |
da890466 | 162 | <entry>Root file system partition of the secondary architecture of the local architecture (usually the matching 32-bit architecture for the local 64-bit architecture)</entry> |
917cc808 LP |
163 | </row> |
164 | ||
165 | <row> | |
166 | <entry><constant>root-secondary-verity</constant></entry> | |
167 | <entry>Verity data for the root file system partition of the secondary architecture</entry> | |
168 | </row> | |
169 | ||
170 | <row> | |
b45b4f50 P |
171 | <entry><constant>root-secondary-verity-sig</constant></entry> |
172 | <entry>Verity signature data for the root file system partition of the secondary architecture</entry> | |
499f0f82 DJL |
173 | </row> |
174 | ||
175 | <row> | |
b45b4f50 P |
176 | <entry><constant>root-{arch}</constant></entry> |
177 | <entry>Root file system partition of the given architecture (such as <constant>root-x86-64</constant> or <constant>root-riscv64</constant>)</entry> | |
499f0f82 DJL |
178 | </row> |
179 | ||
180 | <row> | |
b45b4f50 P |
181 | <entry><constant>root-{arch}-verity</constant></entry> |
182 | <entry>Verity data for the root file system partition of the given architecture</entry> | |
499f0f82 DJL |
183 | </row> |
184 | ||
185 | <row> | |
b45b4f50 P |
186 | <entry><constant>root-{arch}-verity-sig</constant></entry> |
187 | <entry>Verity signature data for the root file system partition of the given architecture</entry> | |
499f0f82 DJL |
188 | </row> |
189 | ||
329cde79 LP |
190 | <row> |
191 | <entry><constant>usr</constant></entry> | |
192 | <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> | |
193 | </row> | |
194 | ||
195 | <row> | |
196 | <entry><constant>usr-verity</constant></entry> | |
197 | <entry>Verity data for the <filename>/usr/</filename> file system partition for the local architecture</entry> | |
198 | </row> | |
199 | ||
b45b4f50 P |
200 | <row> |
201 | <entry><constant>usr-verity-sig</constant></entry> | |
202 | <entry>Verity signature data for the <filename>/usr/</filename> file system partition for the local architecture</entry> | |
203 | </row> | |
204 | ||
329cde79 LP |
205 | <row> |
206 | <entry><constant>usr-secondary</constant></entry> | |
da890466 | 207 | <entry><filename>/usr/</filename> file system partition of the secondary architecture of the local architecture (usually the matching 32-bit architecture for the local 64-bit architecture)</entry> |
329cde79 LP |
208 | </row> |
209 | ||
210 | <row> | |
211 | <entry><constant>usr-secondary-verity</constant></entry> | |
212 | <entry>Verity data for the <filename>/usr/</filename> file system partition of the secondary architecture</entry> | |
213 | </row> | |
214 | ||
215 | <row> | |
b45b4f50 P |
216 | <entry><constant>usr-secondary-verity-sig</constant></entry> |
217 | <entry>Verity signature data for the <filename>/usr/</filename> file system partition of the secondary architecture</entry> | |
499f0f82 DJL |
218 | </row> |
219 | ||
220 | <row> | |
b45b4f50 P |
221 | <entry><constant>usr-{arch}</constant></entry> |
222 | <entry><filename>/usr/</filename> file system partition of the given architecture</entry> | |
499f0f82 DJL |
223 | </row> |
224 | ||
225 | <row> | |
b45b4f50 P |
226 | <entry><constant>usr-{arch}-verity</constant></entry> |
227 | <entry>Verity data for the <filename>/usr/</filename> file system partition of the given architecture</entry> | |
499f0f82 DJL |
228 | </row> |
229 | ||
230 | <row> | |
b45b4f50 P |
231 | <entry><constant>usr-{arch}-verity-sig</constant></entry> |
232 | <entry>Verity signature data for the <filename>/usr/</filename> file system partition of the given architecture</entry> | |
499f0f82 | 233 | </row> |
917cc808 LP |
234 | </tbody> |
235 | </tgroup> | |
236 | </table> | |
237 | ||
238 | <para>This setting defaults to <constant>linux-generic</constant>.</para> | |
239 | ||
240 | <para>Most of the partition type UUIDs listed above are defined in the <ulink | |
db811444 | 241 | url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions |
ec07c3c8 AK |
242 | Specification</ulink>.</para> |
243 | ||
244 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
917cc808 LP |
245 | </varlistentry> |
246 | ||
247 | <varlistentry> | |
248 | <term><varname>Label=</varname></term> | |
249 | ||
250 | <listitem><para>The textual label to assign to the partition if none is assigned yet. Note that this | |
251 | setting is not used for matching. It is also not used when a label is already set for an existing | |
252 | partition. It is thus only used when a partition is newly created or when an existing one had a no | |
253 | label set (that is: an empty label). If not specified a label derived from the partition type is | |
ec07c3c8 AK |
254 | automatically used. Simple specifier expansion is supported, see below.</para> |
255 | ||
256 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
917cc808 LP |
257 | </varlistentry> |
258 | ||
12963533 TH |
259 | <varlistentry> |
260 | <term><varname>UUID=</varname></term> | |
261 | ||
262 | <listitem><para>The UUID to assign to the partition if none is assigned yet. Note that this | |
263 | setting is not used for matching. It is also not used when a UUID is already set for an existing | |
264 | partition. It is thus only used when a partition is newly created or when an existing one had a | |
11749b61 | 265 | all-zero UUID set. If set to <literal>null</literal>, the UUID is set to all zeroes. If not specified |
ec07c3c8 AK |
266 | a UUID derived from the partition type is automatically used.</para> |
267 | ||
268 | <xi:include href="version-info.xml" xpointer="v246"/></listitem> | |
12963533 TH |
269 | </varlistentry> |
270 | ||
917cc808 LP |
271 | <varlistentry> |
272 | <term><varname>Priority=</varname></term> | |
273 | ||
274 | <listitem><para>A numeric priority to assign to this partition, in the range -2147483648…2147483647, | |
275 | with smaller values indicating higher priority, and higher values indicating smaller priority. This | |
276 | priority is used in case the configured size constraints on the defined partitions do not permit | |
277 | fitting all partitions onto the available disk space. If the partitions do not fit, the highest | |
278 | numeric partition priority of all defined partitions is determined, and all defined partitions with | |
279 | this priority are removed from the list of new partitions to create (which may be multiple, if the | |
280 | same priority is used for multiple partitions). The fitting algorithm is then tried again. If the | |
281 | partitions still do not fit, the now highest numeric partition priority is determined, and the | |
282 | matching partitions removed too, and so on. Partitions of a priority of 0 or lower are never | |
283 | removed. If all partitions with a priority above 0 are removed and the partitions still do not fit on | |
284 | the device the operation fails. Note that this priority has no effect on ordering partitions, for | |
285 | that use the alphabetical order of the filenames of the partition definition files. Defaults to | |
ec07c3c8 AK |
286 | 0.</para> |
287 | ||
288 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
917cc808 LP |
289 | </varlistentry> |
290 | ||
291 | <varlistentry> | |
292 | <term><varname>Weight=</varname></term> | |
293 | ||
294 | <listitem><para>A numeric weight to assign to this partition in the range 0…1000000. Available disk | |
295 | space is assigned the defined partitions according to their relative weights (subject to the size | |
296 | constraints configured with <varname>SizeMinBytes=</varname>, <varname>SizeMaxBytes=</varname>), so | |
297 | that a partition with weight 2000 gets double the space as one with weight 1000, and a partition with | |
298 | weight 333 a third of that. Defaults to 1000.</para> | |
299 | ||
300 | <para>The <varname>Weight=</varname> setting is used to distribute available disk space in an | |
301 | "elastic" fashion, based on the disk size and existing partitions. If a partition shall have a fixed | |
302 | size use both <varname>SizeMinBytes=</varname> and <varname>SizeMaxBytes=</varname> with the same | |
303 | value in order to fixate the size to one value, in which case the weight has no | |
ec07c3c8 AK |
304 | effect.</para> |
305 | ||
306 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
917cc808 LP |
307 | </varlistentry> |
308 | ||
309 | <varlistentry> | |
310 | <term><varname>PaddingWeight=</varname></term> | |
311 | ||
15102ced | 312 | <listitem><para>Similar to <varname>Weight=</varname>, but sets a weight for the free space after the |
917cc808 LP |
313 | partition (the "padding"). When distributing available space the weights of all partitions and all |
314 | defined padding is summed, and then each partition and padding gets the fraction defined by its | |
315 | weight. Defaults to 0, i.e. by default no padding is applied.</para> | |
316 | ||
317 | <para>Padding is useful if empty space shall be left for later additions or a safety margin at the | |
ec07c3c8 AK |
318 | end of the device or between partitions.</para> |
319 | ||
320 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
917cc808 LP |
321 | </varlistentry> |
322 | ||
323 | <varlistentry> | |
324 | <term><varname>SizeMinBytes=</varname></term> | |
325 | <term><varname>SizeMaxBytes=</varname></term> | |
326 | ||
327 | <listitem><para>Specifies minimum and maximum size constraints in bytes. Takes the usual K, M, G, T, | |
328 | … suffixes (to the base of 1024). If <varname>SizeMinBytes=</varname> is specified the partition is | |
329 | created at or grown to at least the specified size. If <varname>SizeMaxBytes=</varname> is specified | |
330 | the partition is created at or grown to at most the specified size. The precise size is determined | |
84b10e53 | 331 | through the weight value configured with <varname>Weight=</varname>, see above. When |
917cc808 LP |
332 | <varname>SizeMinBytes=</varname> is set equal to <varname>SizeMaxBytes=</varname> the configured |
333 | weight has no effect as the partition is explicitly sized to the specified fixed value. Note that | |
334 | partitions are never created smaller than 4096 bytes, and since partitions are never shrunk the | |
335 | previous size of the partition (in case the partition already exists) is also enforced as lower bound | |
336 | for the new size. The values should be specified as multiples of 4096 bytes, and are rounded upwards | |
337 | (in case of <varname>SizeMinBytes=</varname>) or downwards (in case of | |
338 | <varname>SizeMaxBytes=</varname>) otherwise. If the backing device does not provide enough space to | |
339 | fulfill the constraints placing the partition will fail. For partitions that shall be created, | |
340 | depending on the setting of <varname>Priority=</varname> (see above) the partition might be dropped | |
fb08381c | 341 | and the placing algorithm restarted. By default a minimum size constraint of 10M and no maximum size |
ec07c3c8 AK |
342 | constraint is set.</para> |
343 | ||
344 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
917cc808 LP |
345 | </varlistentry> |
346 | ||
347 | <varlistentry> | |
348 | <term><varname>PaddingMinBytes=</varname></term> | |
349 | <term><varname>PaddingMaxBytes=</varname></term> | |
350 | ||
757bc2e4 | 351 | <listitem><para>Specifies minimum and maximum size constraints in bytes for the free space after the |
917cc808 LP |
352 | partition (the "padding"). Semantics are similar to <varname>SizeMinBytes=</varname> and |
353 | <varname>SizeMaxBytes=</varname>, except that unlike partition sizes free space can be shrunk and can | |
354 | be as small as zero. By default no size constraints on padding are set, so that only | |
ec07c3c8 AK |
355 | <varname>PaddingWeight=</varname> determines the size of the padding applied.</para> |
356 | ||
357 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
917cc808 LP |
358 | </varlistentry> |
359 | ||
757bc2e4 LP |
360 | <varlistentry> |
361 | <term><varname>CopyBlocks=</varname></term> | |
362 | ||
5c08da58 LP |
363 | <listitem><para>Takes a path to a regular file, block device node or directory, or the special value |
364 | <literal>auto</literal>. If specified and the partition is newly created, the data from the specified | |
365 | path is written to the newly created partition, on the block level. If a directory is specified, the | |
366 | backing block device of the file system the directory is on is determined, and the data read directly | |
367 | from that. This option is useful to efficiently replicate existing file systems onto new partitions | |
368 | on the block level — for example to build a simple OS installer or an OS image builder.</para> | |
369 | ||
370 | <para>If the special value <literal>auto</literal> is specified, the source to copy from is | |
371 | automatically picked up from the running system (or the image specified with | |
372 | <option>--image=</option> — if used). A partition that matches both the configured partition type (as | |
be0d27ee ZJS |
373 | declared with <varname>Type=</varname> described above), and the currently mounted directory |
374 | appropriate for that partition type is determined. For example, if the partition type is set to | |
5c08da58 LP |
375 | <literal>root</literal> the partition backing the root directory (<filename>/</filename>) is used as |
376 | source to copy from — if its partition type is set to <literal>root</literal> as well. If the | |
377 | declared type is <literal>usr</literal> the partition backing <filename>/usr/</filename> is used as | |
378 | source to copy blocks from — if its partition type is set to <literal>usr</literal> too. The logic is | |
3d62af7d | 379 | capable of automatically tracking down the backing partitions for encrypted and Verity-enabled |
5c08da58 LP |
380 | volumes. <literal>CopyBlocks=auto</literal> is useful for implementing "self-replicating" systems, |
381 | i.e. systems that are their own installer.</para> | |
757bc2e4 LP |
382 | |
383 | <para>The file specified here must have a size that is a multiple of the basic block size 512 and not | |
384 | be empty. If this option is used, the size allocation algorithm is slightly altered: the partition is | |
385 | created as least as big as required to fit the data in, i.e. the data size is an additional minimum | |
386 | size value taken into consideration for the allocation algorithm, similar to and in addition to the | |
387 | <varname>SizeMin=</varname> value configured above.</para> | |
388 | ||
389 | <para>This option has no effect if the partition it is declared for already exists, i.e. existing | |
390 | data is never overwritten. Note that the data is copied in before the partition table is updated, | |
391 | i.e. before the partition actually is persistently created. This provides robustness: it is | |
392 | guaranteed that the partition either doesn't exist or exists fully populated; it is not possible that | |
86320e62 DDM |
393 | the partition exists but is not or only partially populated.</para> |
394 | ||
395 | <para>This option cannot be combined with <varname>Format=</varname> or | |
ec07c3c8 AK |
396 | <varname>CopyFiles=</varname>.</para> |
397 | ||
398 | <xi:include href="version-info.xml" xpointer="v246"/></listitem> | |
dfb4d0ae LP |
399 | </varlistentry> |
400 | ||
401 | <varlistentry> | |
402 | <term><varname>Format=</varname></term> | |
403 | ||
404 | <listitem><para>Takes a file system name, such as <literal>ext4</literal>, <literal>btrfs</literal>, | |
09e917ea LP |
405 | <literal>xfs</literal>, <literal>vfat</literal>, <literal>erofs</literal>, |
406 | <literal>squashfs</literal> or the special value <literal>swap</literal>. If specified and the partition | |
407 | is newly created it is formatted with the specified file system (or as swap device). The file system | |
408 | UUID and label are automatically derived from the partition UUID and label. If this option is used, | |
409 | the size allocation algorithm is slightly altered: the partition is created as least as big as | |
410 | required for the minimal file system of the specified type (or 4KiB if the minimal size is not | |
411 | known).</para> | |
dfb4d0ae LP |
412 | |
413 | <para>This option has no effect if the partition already exists.</para> | |
414 | ||
15102ced ZJS |
415 | <para>Similarly to the behaviour of <varname>CopyBlocks=</varname>, the file system is formatted |
416 | before the partition is created, ensuring that the partition only ever exists with a fully | |
86320e62 DDM |
417 | initialized file system.</para> |
418 | ||
ec07c3c8 AK |
419 | <para>This option cannot be combined with <varname>CopyBlocks=</varname>.</para> |
420 | ||
421 | <xi:include href="version-info.xml" xpointer="v247"/></listitem> | |
dfb4d0ae LP |
422 | </varlistentry> |
423 | ||
424 | <varlistentry> | |
425 | <term><varname>CopyFiles=</varname></term> | |
426 | ||
427 | <listitem><para>Takes a pair of colon separated absolute file system paths. The first path refers to | |
428 | a source file or directory on the host, the second path refers to a target in the file system of the | |
429 | newly created partition and formatted file system. This setting may be used to copy files or | |
430 | directories from the host into the file system that is created due to the <varname>Format=</varname> | |
431 | option. If <varname>CopyFiles=</varname> is used without <varname>Format=</varname> specified | |
432 | explicitly, <literal>Format=</literal> with a suitable default is implied (currently | |
ab45e83f DDM |
433 | <literal>vfat</literal> for <literal>ESP</literal> and <literal>XBOOTLDR</literal> partitions, and |
434 | <literal>ext4</literal> otherwise, but this may change in the future). This option may be used | |
435 | multiple times to copy multiple files or directories from host into the newly formatted file system. | |
436 | The colon and second path may be omitted in which case the source path is also used as the target | |
437 | path (relative to the root of the newly created file system). If the source path refers to a | |
438 | directory it is copied recursively.</para> | |
dfb4d0ae LP |
439 | |
440 | <para>This option has no effect if the partition already exists: it cannot be used to copy additional | |
441 | files into an existing partition, it may only be used to populate a file system created anew.</para> | |
442 | ||
443 | <para>The copy operation is executed before the file system is registered in the partition table, | |
444 | thus ensuring that a file system populated this way only ever exists fully initialized.</para> | |
445 | ||
336ae0e7 DDM |
446 | <para>Note that <varname>CopyFiles=</varname> will skip copying files that aren't supported by the |
447 | target filesystem (e.g symlinks, fifos, sockets and devices on vfat). When an unsupported file type | |
8fb35004 ZJS |
448 | is encountered, <command>systemd-repart</command> will skip copying this file and write a log message |
449 | about it.</para> | |
336ae0e7 | 450 | |
cd53cc14 DDM |
451 | <para>Note that <command>systemd-repart</command> does not change the UIDs/GIDs of any copied files |
452 | and directories. When running <command>systemd-repart</command> as an unprivileged user to build an | |
453 | image of files and directories owned by the same user, you can run <command>systemd-repart</command> | |
454 | in a user namespace with the current user mapped to the root user to make sure the files and | |
455 | directories in the image are owned by the root user.</para> | |
456 | ||
df005f1e DDM |
457 | <para>Note that when populating XFS filesystems with <command>systemd-repart</command> and loop |
458 | devices are not available, populating XFS filesystems with files containing spaces, tabs or newlines | |
776be596 DDM |
459 | might fail on old versions of |
460 | <citerefentry project='man-pages'><refentrytitle>mkfs.xfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
461 | due to limitations of its protofile format.</para> | |
df005f1e | 462 | |
86320e62 | 463 | <para>This option cannot be combined with <varname>CopyBlocks=</varname>.</para> |
252d6267 | 464 | |
8b9f0921 ZJS |
465 | <para>When |
466 | <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
467 | is invoked with the <option>--image=</option> or <option>--root=</option> command line switches the | |
468 | source paths specified are taken relative to the specified root directory or disk image root. | |
ec07c3c8 AK |
469 | </para> |
470 | ||
471 | <xi:include href="version-info.xml" xpointer="v247"/></listitem> | |
dfb4d0ae LP |
472 | </varlistentry> |
473 | ||
a9af8276 DDM |
474 | <varlistentry> |
475 | <term><varname>ExcludeFiles=</varname></term> | |
600bf76c | 476 | <term><varname>ExcludeFilesTarget=</varname></term> |
a9af8276 DDM |
477 | |
478 | <listitem><para>Takes an absolute file system path referring to a source file or directory on the | |
479 | host. This setting may be used to exclude files or directories from the host from being copied into | |
480 | the file system when <varname>CopyFiles=</varname> is used. This option may be used multiple times to | |
481 | exclude multiple files or directories from host from being copied into the newly formatted file | |
482 | system.</para> | |
483 | ||
b63bd125 DDM |
484 | <para>If the path is a directory and ends with <literal>/</literal>, only the directory's |
485 | contents are excluded but not the directory itself. If the path is a directory and does not end with | |
486 | <literal>/</literal>, both the directory and its contents are excluded.</para> | |
487 | ||
600bf76c DDM |
488 | <para><varname>ExcludeFilesTarget=</varname> is like <varname>ExcludeFiles=</varname> except that |
489 | instead of excluding the path on the host from being copied into the partition, we exclude any files | |
490 | and directories from being copied into the given path in the partition.</para> | |
491 | ||
a9af8276 DDM |
492 | <para>When |
493 | <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
494 | is invoked with the <option>--image=</option> or <option>--root=</option> command line switches the | |
495 | paths specified are taken relative to the specified root directory or disk image root. | |
ec07c3c8 AK |
496 | </para> |
497 | ||
498 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
a9af8276 DDM |
499 | </varlistentry> |
500 | ||
d83d8048 LP |
501 | <varlistentry> |
502 | <term><varname>MakeDirectories=</varname></term> | |
503 | ||
be0d27ee | 504 | <listitem><para>Takes one or more absolute paths, separated by whitespace, each declaring a directory |
d83d8048 LP |
505 | to create within the new file system. Behaviour is similar to <varname>CopyFiles=</varname>, but |
506 | instead of copying in a set of files this just creates the specified directories with the default | |
507 | mode of 0755 owned by the root user and group, plus all their parent directories (with the same | |
508 | ownership and access mode). To configure directories with different ownership or access mode, use | |
509 | <varname>CopyFiles=</varname> and specify a source tree to copy containing appropriately | |
510 | owned/configured directories. This option may be used more than once to create multiple | |
511 | directories. When <varname>CopyFiles=</varname> and <varname>MakeDirectories=</varname> are used | |
512 | together the former is applied first. If a directory listed already exists no operation is executed | |
513 | (in particular, the ownership/access mode of the directories is left as is).</para> | |
514 | ||
515 | <para>The primary usecase for this option is to create a minimal set of directories that may be | |
516 | mounted over by other partitions contained in the same disk image. For example, a disk image where | |
517 | the root file system is formatted at first boot might want to automatically pre-create | |
518 | <filename>/usr/</filename> in it this way, so that the <literal>usr</literal> partition may | |
519 | over-mount it.</para> | |
520 | ||
521 | <para>Consider using | |
522 | <citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
523 | with its <option>--image=</option> option to pre-create other, more complex directory hierarchies (as | |
524 | well as other inodes) with fine-grained control of ownership, access modes and other file | |
ec07c3c8 AK |
525 | attributes.</para> |
526 | ||
527 | <xi:include href="version-info.xml" xpointer="v249"/></listitem> | |
d83d8048 LP |
528 | </varlistentry> |
529 | ||
440f805c DDM |
530 | <varlistentry> |
531 | <term><varname>Subvolumes=</varname></term> | |
532 | ||
533 | <listitem><para>Takes one or more absolute paths, separated by whitespace, each declaring a directory | |
534 | that should be a subvolume within the new file system. This option may be used more than once to | |
535 | specify multiple directories. Note that this setting does not create the directories themselves, that | |
536 | can be configured with <varname>MakeDirectories=</varname> and <varname>CopyFiles=</varname>.</para> | |
537 | ||
538 | <para>Note that this option only takes effect if the target filesystem supports subvolumes, such as | |
539 | <literal>btrfs</literal>.</para> | |
540 | ||
541 | <para>Note that due to limitations of <literal>mkfs.btrfs</literal>, this option is only supported | |
ec07c3c8 AK |
542 | when running with <option>--offline=no</option>.</para> |
543 | ||
544 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
440f805c DDM |
545 | </varlistentry> |
546 | ||
dfb4d0ae LP |
547 | <varlistentry> |
548 | <term><varname>Encrypt=</varname></term> | |
549 | ||
cf1e172d LP |
550 | <listitem><para>Takes one of <literal>off</literal>, <literal>key-file</literal>, |
551 | <literal>tpm2</literal> and <literal>key-file+tpm2</literal> (alternatively, also accepts a boolean | |
552 | value, which is mapped to <literal>off</literal> when false, and <literal>key-file</literal> when | |
553 | true). Defaults to <literal>off</literal>. If not <literal>off</literal> the partition will be | |
dfb4d0ae LP |
554 | formatted with a LUKS2 superblock, before the blocks configured with <varname>CopyBlocks=</varname> |
555 | are copied in or the file system configured with <varname>Format=</varname> is created.</para> | |
556 | ||
cf1e172d | 557 | <para>The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion. If |
be0d27ee ZJS |
558 | <literal>key-file</literal> or <literal>key-file+tpm2</literal> is used, a key is added to the LUKS2 |
559 | superblock, configurable with the <option>--key-file=</option> option to | |
cf1e172d | 560 | <command>systemd-repart</command>. If <literal>tpm2</literal> or <literal>key-file+tpm2</literal> is |
be0d27ee | 561 | used, a key is added to the LUKS2 superblock that is enrolled to the local TPM2 chip, as configured |
cf1e172d | 562 | with the <option>--tpm2-device=</option> and <option>--tpm2-pcrs=</option> options to |
dfb4d0ae LP |
563 | <command>systemd-repart</command>.</para> |
564 | ||
565 | <para>When used this slightly alters the size allocation logic as the implicit, minimal size limits | |
566 | of <varname>Format=</varname> and <varname>CopyBlocks=</varname> are increased by the space necessary | |
567 | for the LUKS2 superblock (see above).</para> | |
568 | ||
ec07c3c8 AK |
569 | <para>This option has no effect if the partition already exists.</para> |
570 | ||
571 | <xi:include href="version-info.xml" xpointer="v247"/></listitem> | |
757bc2e4 LP |
572 | </varlistentry> |
573 | ||
b5b7879a DDM |
574 | <varlistentry> |
575 | <term><varname>Verity=</varname></term> | |
576 | ||
b456191d DDM |
577 | <listitem><para>Takes one of <literal>off</literal>, <literal>data</literal>, |
578 | <literal>hash</literal> or <literal>signature</literal>. Defaults to <literal>off</literal>. If set | |
579 | to <literal>off</literal> or <literal>data</literal>, the partition is populated with content as | |
580 | specified by <varname>CopyBlocks=</varname> or <varname>CopyFiles=</varname>. If set to | |
581 | <literal>hash</literal>, the partition will be populated with verity hashes from the matching verity | |
8b9f0921 | 582 | data partition. If set to <literal>signature</literal>, the partition will be populated with a JSON |
b456191d DDM |
583 | object containing a signature of the verity root hash of the matching verity hash partition.</para> |
584 | ||
585 | <para>A matching verity partition is a partition with the same verity match key (as configured with | |
586 | <varname>VerityMatchKey=</varname>).</para> | |
587 | ||
588 | <para>If not explicitly configured, the data partition's UUID will be set to the first 128 | |
589 | bits of the verity root hash. Similarly, if not configured, the hash partition's UUID will be set to | |
590 | the final 128 bits of the verity root hash. The verity root hash itself will be included in the | |
591 | output of <command>systemd-repart</command>.</para> | |
b5b7879a DDM |
592 | |
593 | <para>This option has no effect if the partition already exists.</para> | |
594 | ||
595 | <para>Usage of this option in combination with <varname>Encrypt=</varname> is not supported.</para> | |
596 | ||
597 | <para>For each unique <varname>VerityMatchKey=</varname> value, a single verity data partition | |
598 | (<literal>Verity=data</literal>) and a single verity hash partition (<literal>Verity=hash</literal>) | |
ec07c3c8 AK |
599 | must be defined.</para> |
600 | ||
601 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
b5b7879a DDM |
602 | </varlistentry> |
603 | ||
604 | <varlistentry> | |
605 | <term><varname>VerityMatchKey=</varname></term> | |
606 | ||
607 | <listitem><para>Takes a short, user-chosen identifier string. This setting is used to find sibling | |
608 | verity partitions for the current verity partition. See the description for | |
ec07c3c8 AK |
609 | <varname>Verity=</varname>.</para> |
610 | ||
611 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
b5b7879a DDM |
612 | </varlistentry> |
613 | ||
c380047b MC |
614 | <varlistentry> |
615 | <term><varname>VerityDataBlockSizeBytes=</varname></term> | |
616 | ||
617 | <listitem><para>Configures the data block size of the generated verity hash partition. Must be between 512 and | |
618 | 4096 bytes and must be a power of 2. Defaults to the sector size if configured explicitly, or the underlying | |
619 | block device sector size, or 4K if systemd-repart is not operating on a block device. | |
ec07c3c8 AK |
620 | </para> |
621 | ||
622 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
c380047b MC |
623 | </varlistentry> |
624 | ||
625 | <varlistentry> | |
626 | <term><varname>VerityHashBlockSizeBytes=</varname></term> | |
627 | ||
628 | <listitem><para>Configures the hash block size of the generated verity hash partition. Must be between 512 and | |
629 | 4096 bytes and must be a power of 2. Defaults to the sector size if configured explicitly, or the underlying | |
630 | block device sector size, or 4K if systemd-repart is not operating on a block device. | |
ec07c3c8 AK |
631 | </para> |
632 | ||
633 | <xi:include href="version-info.xml" xpointer="v255"/></listitem> | |
c380047b MC |
634 | </varlistentry> |
635 | ||
917cc808 LP |
636 | <varlistentry> |
637 | <term><varname>FactoryReset=</varname></term> | |
638 | ||
639 | <listitem><para>Takes a boolean argument. If specified the partition is marked for removal during a | |
640 | factory reset operation. This functionality is useful to implement schemes where images can be reset | |
ec07c3c8 AK |
641 | into their original state by removing partitions and creating them anew. Defaults to off.</para> |
642 | ||
643 | <xi:include href="version-info.xml" xpointer="v245"/></listitem> | |
917cc808 | 644 | </varlistentry> |
e73309c5 LP |
645 | |
646 | <varlistentry> | |
647 | <term><varname>Flags=</varname></term> | |
648 | ||
da890466 | 649 | <listitem><para>Configures the 64-bit GPT partition flags field to set for the partition when creating |
e73309c5 | 650 | it. This option has no effect if the partition already exists. If not specified the flags values is |
ff0771bf LP |
651 | set to all zeroes, except for the three bits that can also be configured via |
652 | <varname>NoAuto=</varname>, <varname>ReadOnly=</varname> and <varname>GrowFileSystem=</varname>; see | |
653 | below for details on the defaults for these three flags. Specify the flags value in hexadecimal (by | |
654 | prefixing it with <literal>0x</literal>), binary (prefix <literal>0b</literal>) or decimal (no | |
ec07c3c8 AK |
655 | prefix).</para> |
656 | ||
657 | <xi:include href="version-info.xml" xpointer="v249"/></listitem> | |
e73309c5 LP |
658 | </varlistentry> |
659 | ||
660 | <varlistentry> | |
ff0771bf | 661 | <term><varname>NoAuto=</varname></term> |
e73309c5 | 662 | <term><varname>ReadOnly=</varname></term> |
1c41c1dc LP |
663 | <term><varname>GrowFileSystem=</varname></term> |
664 | ||
ff0771bf LP |
665 | <listitem><para>Configures the No-Auto, Read-Only and Grow-File-System partition flags (bit 63, 60 |
666 | and 59) of the partition table entry, as defined by the <ulink | |
db811444 | 667 | url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>. Only |
ff0771bf LP |
668 | available for partition types supported by the specification. This option is a friendly way to set |
669 | bits 63, 60 and 59 of the partition flags value without setting any of the other bits, and may be set | |
670 | via <varname>Flags=</varname> too, see above.</para> | |
1c41c1dc | 671 | |
ff0771bf LP |
672 | <para>If <varname>Flags=</varname> is used in conjunction with one or more of |
673 | <varname>NoAuto=</varname>/<varname>ReadOnly=</varname>/<varname>GrowFileSystem=</varname> the latter | |
674 | control the value of the relevant flags, i.e. the high-level settings | |
675 | <varname>NoAuto=</varname>/<varname>ReadOnly=</varname>/<varname>GrowFileSystem=</varname> override | |
676 | the relevant bits of the low-level setting <varname>Flags=</varname>.</para> | |
1c41c1dc | 677 | |
ff0771bf | 678 | <para>Note that the three flags affect only automatic partition mounting, as implemented by |
1c41c1dc LP |
679 | <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> |
680 | or the <option>--image=</option> option of various commands (such as | |
681 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>). It | |
682 | has no effect on explicit mounts, such as those done via <citerefentry | |
683 | project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> or | |
684 | <citerefentry | |
be0d27ee | 685 | project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> |
1c41c1dc LP |
686 | |
687 | <para>If both bit 50 and 59 are set for a partition (i.e. the partition is marked both read-only and | |
688 | marked for file system growing) the latter is typically without effect: the read-only flag takes | |
689 | precedence in most tools reading these flags, and since growing the file system involves writing to | |
690 | the partition it is consequently ignored.</para> | |
691 | ||
ff0771bf LP |
692 | <para><varname>NoAuto=</varname> defaults to off. <varname>ReadOnly=</varname> defaults to on for |
693 | Verity partition types, and off for all others. <varname>GrowFileSystem=</varname> defaults to on for | |
694 | all partition types that support it, except if the partition is marked read-only (and thus | |
ec07c3c8 AK |
695 | effectively, defaults to off for Verity partitions).</para> |
696 | ||
697 | <xi:include href="version-info.xml" xpointer="v249"/></listitem> | |
e73309c5 | 698 | </varlistentry> |
4cee8333 DDM |
699 | |
700 | <varlistentry> | |
701 | <term><varname>SplitName=</varname></term> | |
702 | ||
703 | <listitem><para>Configures the suffix to append to split artifacts when the <option>--split</option> | |
8fb35004 ZJS |
704 | option of |
705 | <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry> is | |
706 | used. Simple specifier expansion is supported, see below. Defaults to <literal>%t</literal>. To | |
707 | disable split artifact generation for a partition, set <varname>SplitName=</varname> to | |
ec07c3c8 AK |
708 | <literal>-</literal>.</para> |
709 | ||
710 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
4cee8333 | 711 | </varlistentry> |
c4a87b76 DDM |
712 | |
713 | <varlistentry> | |
714 | <term><varname>Minimize=</varname></term> | |
715 | ||
5c33b686 DDM |
716 | <listitem><para>Takes one of <literal>off</literal>, <literal>best</literal>, and |
717 | <literal>guess</literal> (alternatively, also accepts a boolean value, which is mapped to | |
718 | <literal>off</literal> when false, and <literal>best</literal> when true). Defaults to | |
719 | <literal>off</literal>. If set to <literal>best</literal>, the partition will have the minimal size | |
720 | required to store the sources configured with <varname>CopyFiles=</varname>. <literal>best</literal> | |
721 | is currently only supported for read-only filesystems. If set to <literal>guess</literal>, the | |
722 | partition is created at least as big as required to store the sources configured with | |
723 | <varname>CopyFiles=</varname>. Note that unless the filesystem is a read-only filesystem, | |
724 | <command>systemd-repart</command> will have to populate the filesystem twice to guess the minimal | |
725 | required size, so enabling this option might slow down repart when populating large partitions. | |
ec07c3c8 AK |
726 | </para> |
727 | ||
728 | <xi:include href="version-info.xml" xpointer="v253"/></listitem> | |
c4a87b76 | 729 | </varlistentry> |
917cc808 LP |
730 | </variablelist> |
731 | </refsect1> | |
732 | ||
e031166e LP |
733 | <refsect1> |
734 | <title>Specifiers</title> | |
735 | ||
b3e22322 | 736 | <para>Specifiers may be used in the <varname>Label=</varname>, <varname>CopyBlocks=</varname>, |
4cee8333 DDM |
737 | <varname>CopyFiles=</varname>, <varname>MakeDirectories=</varname>, <varname>SplitName=</varname> |
738 | settings. The following expansions are understood:</para> | |
e031166e LP |
739 | <table class='specifiers'> |
740 | <title>Specifiers available</title> | |
741 | <tgroup cols='3' align='left' colsep='1' rowsep='1'> | |
742 | <colspec colname="spec" /> | |
743 | <colspec colname="mean" /> | |
744 | <colspec colname="detail" /> | |
745 | <thead> | |
746 | <row> | |
747 | <entry>Specifier</entry> | |
748 | <entry>Meaning</entry> | |
749 | <entry>Details</entry> | |
750 | </row> | |
751 | </thead> | |
752 | <tbody> | |
753 | <xi:include href="standard-specifiers.xml" xpointer="a"/> | |
9a515f0a | 754 | <xi:include href="standard-specifiers.xml" xpointer="A"/> |
e031166e LP |
755 | <xi:include href="standard-specifiers.xml" xpointer="b"/> |
756 | <xi:include href="standard-specifiers.xml" xpointer="B"/> | |
757 | <xi:include href="standard-specifiers.xml" xpointer="H"/> | |
758 | <xi:include href="standard-specifiers.xml" xpointer="l"/> | |
759 | <xi:include href="standard-specifiers.xml" xpointer="m"/> | |
9a515f0a | 760 | <xi:include href="standard-specifiers.xml" xpointer="M"/> |
e031166e LP |
761 | <xi:include href="standard-specifiers.xml" xpointer="o"/> |
762 | <xi:include href="standard-specifiers.xml" xpointer="v"/> | |
763 | <xi:include href="standard-specifiers.xml" xpointer="w"/> | |
764 | <xi:include href="standard-specifiers.xml" xpointer="W"/> | |
b3e22322 LP |
765 | <xi:include href="standard-specifiers.xml" xpointer="T"/> |
766 | <xi:include href="standard-specifiers.xml" xpointer="V"/> | |
e031166e LP |
767 | <xi:include href="standard-specifiers.xml" xpointer="percent"/> |
768 | </tbody> | |
769 | </tgroup> | |
770 | </table> | |
4cee8333 DDM |
771 | |
772 | <para>Additionally, for the <varname>SplitName=</varname> setting, the following specifiers are also | |
773 | understood:</para> | |
774 | <table class='specifiers'> | |
775 | <title>Specifiers available</title> | |
776 | <tgroup cols='3' align='left' colsep='1' rowsep='1'> | |
777 | <colspec colname="spec" /> | |
778 | <colspec colname="mean" /> | |
779 | <colspec colname="detail" /> | |
780 | <thead> | |
781 | <row> | |
782 | <entry>Specifier</entry> | |
783 | <entry>Meaning</entry> | |
784 | <entry>Details</entry> | |
785 | </row> | |
786 | </thead> | |
787 | <tbody> | |
788 | <row id='T'> | |
789 | <entry><literal>%T</literal></entry> | |
790 | <entry>Partition Type UUID</entry> | |
791 | <entry>The partition type UUID, as configured with <varname>Type=</varname></entry> | |
792 | </row> | |
793 | <row id='t'> | |
794 | <entry><literal>%t</literal></entry> | |
795 | <entry>Partition Type Identifier</entry> | |
796 | <entry>The partition type identifier corresponding to the partition type UUID</entry> | |
797 | </row> | |
798 | <row id='U'> | |
799 | <entry><literal>%U</literal></entry> | |
800 | <entry>Partition UUID</entry> | |
801 | <entry>The partition UUID, as configured with <varname>UUID=</varname></entry> | |
802 | </row> | |
803 | <row id='n'> | |
804 | <entry><literal>%n</literal></entry> | |
805 | <entry>Partition Number</entry> | |
806 | <entry>The partition number assigned to the partition</entry> | |
807 | </row> | |
808 | </tbody> | |
809 | </tgroup> | |
810 | </table> | |
e031166e LP |
811 | </refsect1> |
812 | ||
917cc808 LP |
813 | <refsect1> |
814 | <title>Examples</title> | |
815 | ||
816 | <example> | |
817 | <title>Grow the root partition to the full disk size at first boot</title> | |
818 | ||
6d9829e7 ZJS |
819 | <para>With the following file the root partition is automatically grown to the full disk if possible |
820 | during boot.</para> | |
917cc808 LP |
821 | |
822 | <para><programlisting># /usr/lib/repart.d/50-root.conf | |
823 | [Partition] | |
824 | Type=root | |
825 | </programlisting></para> | |
826 | </example> | |
827 | ||
828 | <example> | |
829 | <title>Create a swap and home partition automatically on boot, if missing</title> | |
830 | ||
831 | <para>The home partition gets all available disk space while the swap partition gets 1G at most and 64M | |
832 | at least. We set a priority > 0 on the swap partition to ensure the swap partition is not used if not | |
833 | enough space is available. For every three bytes assigned to the home partition the swap partition gets | |
834 | assigned one.</para> | |
835 | ||
836 | <para><programlisting># /usr/lib/repart.d/60-home.conf | |
837 | [Partition] | |
838 | Type=home | |
839 | </programlisting></para> | |
840 | ||
841 | <para><programlisting># /usr/lib/repart.d/70-swap.conf | |
842 | [Partition] | |
843 | Type=swap | |
844 | SizeMinBytes=64M | |
845 | SizeMaxBytes=1G | |
846 | Priority=1 | |
847 | Weight=333 | |
848 | </programlisting></para> | |
849 | </example> | |
850 | ||
851 | <example> | |
852 | <title>Create B partitions in an A/B Verity setup, if missing</title> | |
853 | ||
854 | <para>Let's say the vendor intends to update OS images in an A/B setup, i.e. with two root partitions | |
855 | (and two matching Verity partitions) that shall be used alternatingly during upgrades. To minimize | |
856 | image sizes the original image is shipped only with one root and one Verity partition (the "A" set), | |
857 | and the second root and Verity partitions (the "B" set) shall be created on first boot on the free | |
858 | space on the medium.</para> | |
859 | ||
860 | <para><programlisting># /usr/lib/repart.d/50-root.conf | |
861 | [Partition] | |
862 | Type=root | |
863 | SizeMinBytes=512M | |
864 | SizeMaxBytes=512M | |
865 | </programlisting></para> | |
866 | ||
867 | <para><programlisting># /usr/lib/repart.d/60-root-verity.conf | |
868 | [Partition] | |
869 | Type=root-verity | |
870 | SizeMinBytes=64M | |
871 | SizeMaxBytes=64M | |
872 | </programlisting></para> | |
873 | ||
874 | <para>The definitions above cover the "A" set of root partition (of a fixed 512M size) and Verity | |
875 | partition for the root partition (of a fixed 64M size). Let's use symlinks to create the "B" set of | |
876 | partitions, since after all they shall have the same properties and sizes as the "A" set.</para> | |
877 | ||
878 | <para><programlisting># ln -s 50-root.conf /usr/lib/repart.d/70-root-b.conf | |
879 | # ln -s 60-root-verity.conf /usr/lib/repart.d/80-root-verity-b.conf | |
b5b7879a DDM |
880 | </programlisting></para> |
881 | </example> | |
882 | ||
883 | <example> | |
799cd310 | 884 | <title>Create a data partition and corresponding verity partitions from a OS tree</title> |
b5b7879a | 885 | |
6d9829e7 ZJS |
886 | <para>Assuming we have an OS tree at <filename index='false'>/var/tmp/os-tree</filename> that we want |
887 | to package in a root partition together with matching verity partitions, we can do so as follows: | |
888 | </para> | |
b5b7879a DDM |
889 | |
890 | <para><programlisting># 50-root.conf | |
891 | [Partition] | |
892 | Type=root | |
893 | CopyFiles=/var/tmp/os-tree | |
894 | Verity=data | |
895 | VerityMatchKey=root | |
799cd310 | 896 | Minimize=guess |
b5b7879a DDM |
897 | </programlisting></para> |
898 | ||
899 | <para><programlisting># 60-root-verity.conf | |
900 | [Partition] | |
901 | Type=root-verity | |
902 | Verity=hash | |
903 | VerityMatchKey=root | |
c380047b MC |
904 | # Explicitly set the hash and data block size to 4K |
905 | VerityDataBlockSizeBytes=4096 | |
906 | VerityHashBlockSizeBytes=4096 | |
799cd310 DDM |
907 | Minimize=best |
908 | </programlisting></para> | |
909 | ||
910 | <para><programlisting># 70-root-verity-sig.conf | |
911 | [Partition] | |
912 | Type=root-verity-sig | |
913 | Verity=signature | |
914 | VerityMatchKey=root | |
917cc808 LP |
915 | </programlisting></para> |
916 | </example> | |
917 | ||
918 | </refsect1> | |
919 | ||
920 | <refsect1> | |
921 | <title>See Also</title> | |
922 | <para> | |
923 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
924 | <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
cf1e172d LP |
925 | <citerefentry project='man-pages'><refentrytitle>sfdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
926 | <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
917cc808 LP |
927 | </para> |
928 | </refsect1> | |
929 | ||
930 | </refentry> |