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