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