1SYSTEMD-REPART(8) systemd-repart SYSTEMD-REPART(8)
2
6 systemd-repart, systemd-repart.service - Automatically grow and add
7 partitions
8
10 systemd-repart [OPTIONS...] [[BLOCKDEVICE]...]
11 systemd-repart.service
13
15 systemd-repart grows and adds partitions to a partition table, based on
16 the configuration files described in repart.d(5).
17 If invoked with no arguments, it operates on the block device backing
19 the root file system partition of the running OS, thus growing and
20 adding partitions of the booted OS image itself. If --image= is used it
21 will operate on the specified image file. When called in the "initrd"
22 it operates on the block device backing /sysroot/ instead, i.e. on the
23 block device the system will soon transition into. The
24 systemd-repart.service service is generally run at boot in the initial
25 RAM disk, in order to augment the partition table of the OS before its
26 partitions are mounted. systemd-repart (mostly) operates in a purely
27 incremental mode: it only grows existing and adds new partitions; it
28 does not shrink, delete or move existing partitions. The service is
29 intended to be run on every boot, but when it detects that the
30 partition table already matches the installed repart.d/*.conf
31 configuration files, it executes no operation.
32 systemd-repart is intended to be used when deploying OS images, to
34 automatically adjust them to the system they are running on, during
35 first boot. This way the deployed image can be minimal in size and may
36 be augmented automatically at boot when needed, taking possession of
37 disk space available but not yet used. Specifically the following use
38 cases are among those covered:
39 • The root partition may be grown to cover the whole available disk
41 space.
42 • A /home/, swap or /srv/ partition can be added.
44 • A second (or third, ...) root partition may be added, to cover A/B
46 style setups where a second version of the root file system is
47 alternatingly used for implementing update schemes. The deployed
48 image would carry only a single partition ("A") but on first boot a
49 second partition ("B") for this purpose is automatically created.
50 The algorithm executed by systemd-repart is roughly as follows:
52 1. The repart.d/*.conf configuration files are loaded and parsed, and
54 ordered by filename (without the directory prefix).
55 2. The partition table already existing on the block device is loaded
57 and parsed.
58 3. The existing partitions in the partition table are matched up with
60 the repart.d/*.conf files by GPT partition type UUID. The first
61 existing partition of a specific type is assigned the first
62 configuration file declaring the same type. The second existing
63 partition of a specific type is then assigned the second
64 configuration file declaring the same type, and so on. After this
65 iterative assigning is complete any left-over existing partitions
66 that have no matching configuration file are considered "foreign"
67 and left as they are. And any configuration files for which no
68 partition currently exists are understood as a request to create
69 such a partition.
70 4. Taking the size constraints and weights declared in the
72 configuration files into account, all partitions that shall be
73 created are now allocated to the disk, taking up all free space,
74 always respecting the size and padding requests. Similar, existing
75 partitions that are determined to grow are grown. New partitions
76 are always appended to the end of the existing partition table,
77 taking the first partition table slot whose index is greater than
78 the indexes of all existing partitions. Partition table slots are
79 never reordered and thus partition numbers are ensured to remain
80 stable. Note that this allocation happens in RAM only, the
81 partition table on disk is not updated yet.
82 5. All existing partitions for which configuration files exist and
84 which currently have no GPT partition label set will be assigned a
85 label, either explicitly configured in the configuration or (if
86 that's missing) derived automatically from the partition type. The
87 same is done for all partitions that are newly created. These
88 assignments are done in RAM only, too, the disk is not updated yet.
89 6. Similarly, all existing partitions for which configuration files
91 exist and which currently have an all-zero identifying UUID will be
92 assigned a new UUID. This UUID is cryptographically hashed from a
93 common seed value together with the partition type UUID (and a
94 counter in case multiple partitions of the same type are defined),
95 see below. The same is done for all partitions that are created
96 anew. These assignments are done in RAM only, too, the disk is not
97 updated yet.
98 7. Similarly, if the disk's volume UUID is all zeroes it is also
100 initialized, also cryptographically hashed from the same common
101 seed value. Also, in RAM only, too.
102 8. The disk space assigned to new partitions (i.e. what was previously
104 considered free space but is no longer) is now erased.
105 Specifically, all file system signatures are removed, and if the
106 device supports it the BLKDISCARD I/O control command is issued to
107 inform the hardware that the space is empty now. In addition any
108 "padding" between partitions and at the end of the device is
109 similarly erased.
110 9. The new partition table is finally written to disk. The kernel is
112 asked to reread the partition table.
113 As exception to the normally strictly incremental operation, when
115 called in a special "factory reset" mode, systemd-repart may also be
116 used to erase existing partitions to reset an installation back to
117 vendor defaults. This mode of operation is used when either the
118 --factory-reset=yes switch is passed on the tool's command line, or the
119 systemd.factory_reset=yes option specified on the kernel command line,
120 or the FactoryReset EFI variable (vendor UUID
121 8cf2644b-4b0b-428f-9387-6d876050dc67) is set to "yes". It alters the
122 algorithm above slightly: between the 3rd and the 4th step above any
123 partition marked explicitly via the FactoryReset= boolean is deleted,
124 and the algorithm restarted, thus immediately re-creating these
125 partitions anew empty.
126 Note that systemd-repart only changes partition tables, it does not
128 create or resize any file systems within these partitions. A separate
129 mechanism should be used for that, for example systemd-growfs(8) and
130 systemd-makefs.
131 The UUIDs identifying the new partitions created (or assigned to
133 existing partitions that have no UUID yet), as well as the disk as a
134 whole are hashed cryptographically from a common seed value. This seed
135 value is usually the machine-id(5) of the system, so that the machine
136 ID reproducibly determines the UUIDs assigned to all partitions. If the
137 machine ID cannot be read (or the user passes --seed=random, see below)
138 the seed is generated randomly instead, so that the partition UUIDs are
139 also effectively random. The seed value may also be set explicitly,
140 formatted as UUID via the --seed= option. By hashing these UUIDs from a
141 common seed images prepared with this tool become reproducible and the
142 result of the algorithm above deterministic.
143 The positional argument should specify the block device to operate on.
145 Instead of a block device node path a regular file may be specified
146 too, in which case the command operates on it like it would if a
147 loopback block device node was specified with the file attached. If
148 --empty=create is specified the specified path is created as regular
149 file, which is useful for generating disk images from scratch.
150
152 The following options are understood:
153 --dry-run=
155 Takes a boolean. If this switch is not specified --dry-run=yes is
156 the implied default. Controls whether systemd-repart executes the
157 requested re-partition operations or whether it should only show
158 what it would do. Unless --dry-run=no is specified systemd-repart
159 will not actually touch the device's partition table.
160 --empty=
162 Takes one of "refuse", "allow", "require", "force" or "create".
163 Controls how to operate on block devices that are entirely empty,
164 i.e. carry no partition table/disk label yet. If this switch is not
165 specified the implied default is "refuse".
166 If "refuse" systemd-repart requires that the block device it shall
168 operate on already carries a partition table and refuses operation
169 if none is found. If "allow" the command will extend an existing
170 partition table or create a new one if none exists. If "require"
171 the command will create a new partition table if none exists so
172 far, and refuse operation if one already exists. If "force" it will
173 create a fresh partition table unconditionally, erasing the disk
174 fully in effect. If "force" no existing partitions will be taken
175 into account or survive the operation. Hence: use with care, this
176 is a great way to lose all your data. If "create" a new loopback
177 file is create under the path passed via the device node parameter,
178 of the size indicated with --size=, see below.
179 --discard=
181 Takes a boolean. If this switch is not specified --discard=yes is
182 the implied default. Controls whether to issue the BLKDISCARD I/O
183 control command on the space taken up by any added partitions or on
184 the space in between them. Usually, it's a good idea to issue this
185 request since it tells the underlying hardware that the covered
186 blocks shall be considered empty, improving performance. If
187 operating on a regular file instead of a block device node, a
188 sparse file is generated.
189 --size=
191 Takes a size in bytes, using the usual K, M, G, T suffixes, or the
192 special value "auto". If used the specified device node path must
193 refer to a regular file, which is then grown to the specified size
194 if smaller, before any change is made to the partition table. If
195 specified as "auto" the minimal size for the disk image is
196 automatically determined (i.e. the minimal sizes of all partitions
197 are summed up, taking space for additional metadata into account).
198 This switch is not supported if the specified node is a block
199 device. This switch has no effect if the file is already as large
200 as the specified size or larger. The specified size is implicitly
201 rounded up to multiples of 4096. When used with --empty=create this
202 specifies the initial size of the loopback file to create.
203 The --size=auto option takes the sizes of pre-existing partitions
205 into account. However, it does not accommodate for partition tables
206 that are not tightly packed: the configured partitions might still
207 not fit into the backing device if empty space exists between
208 pre-existing partitions (or before the first partition) that cannot
209 be fully filled by partitions to grow or create.
210 Also note that the automatic size determination does not take files
212 or directories specified with CopyFiles= into account: operation
213 might fail if the specified files or directories require more disk
214 space then the configured per-partition minimal size limit.
215 --factory-reset=
217 Takes boolean. If this switch is not specified --factory=reset=no
218 is the implied default. Controls whether to operate in "factory
219 reset" mode, see above. If set to true this will remove all
220 existing partitions marked with FactoryReset= set to yes early
221 while executing the re-partitioning algorithm. Use with care, this
222 is a great way to lose all your data. Note that partition files
223 need to explicitly turn FactoryReset= on, as the option defaults to
224 off. If no partitions are marked for factory reset this switch has
225 no effect. Note that there are two other methods to request factory
226 reset operation: via the kernel command line and via an EFI
227 variable, see above.
228 --can-factory-reset
230 If this switch is specified the disk is not re-partitioned. Instead
231 it is determined if any existing partitions are marked with
232 FactoryReset=. If there are the tool will exit with exit status
233 zero, otherwise non-zero. This switch may be used to quickly
234 determine whether the running system supports a factory reset
235 mechanism built on systemd-repart.
236 --root=
238 Takes a path to a directory to use as root file system when
239 searching for repart.d/*.conf files, for the machine ID file to use
240 as seed and for the CopyFiles= and CopyBlocks= source files and
241 directories. By default when invoked on the regular system this
242 defaults to the host's root file system /. If invoked from the
243 initial RAM disk this defaults to /sysroot/, so that the tool
244 operates on the configuration and machine ID stored in the root
245 file system later transitioned into itself.
246 --image=
248 Takes a path to a disk image file or device to mount and use in a
249 similar fashion to --root=, see above.
250 --seed=
252 Takes a UUID as argument or the special value random. If a UUID is
253 specified the UUIDs to assign to partitions and the partition table
254 itself are derived via cryptographic hashing from it. If not
255 specified it is attempted to read the machine ID from the host (or
256 more precisely, the root directory configured via --root=) and use
257 it as seed instead, falling back to a randomized seed otherwise.
258 Use --seed=random to force a randomized seed. Explicitly specifying
259 the seed may be used to generated strictly reproducible partition
260 tables.
261 --pretty=
263 Takes a boolean argument. If this switch is not specified, it
264 defaults to on when called from an interactive terminal and off
265 otherwise. Controls whether to show a user friendly table and
266 graphic illustrating the changes applied.
267 --definitions=
269 Takes a file system path. If specified the *.conf files are read
270 from the specified directory instead of searching in
271 /usr/lib/repart.d/*.conf, /etc/repart.d/*.conf,
272 /run/repart.d/*.conf.
273 --key-file=
275 Takes a file system path. Configures the encryption key to use when
276 setting up LUKS2 volumes configured with the Encrypt=key-file
277 setting in partition files. Should refer to a regular file
278 containing the key, or an AF_UNIX stream socket in the file system.
279 In the latter case a connection is made to it and the key read from
280 it. If this switch is not specified the empty key (i.e. zero length
281 key) is used. This behaviour is useful for setting up encrypted
282 partitions during early first boot that receive their user-supplied
283 password only in a later setup step.
284 --tpm2-device=, --tpm2-pcrs=
286 Configures the TPM2 device and list of PCRs to use for LUKS2
287 volumes configured with the Encrypt=tpm2 option. These options take
288 the same parameters as the identically named options to systemd-
289 cryptenroll(1) and have the same effect on partitions where TPM2
290 enrollment is requested.
291 -h, --help
293 Print a short help text and exit.
294 --version
296 Print a short version string and exit.
297 --no-pager
299 Do not pipe output into a pager.
300 --no-legend
302 Do not print the legend, i.e. column headers and the footer with
303 hints.
304 --json=MODE
306 Shows output formatted as JSON. Expects one of "short" (for the
307 shortest possible output without any redundant whitespace or line
308 breaks), "pretty" (for a pretty version of the same, with
309 indentation and line breaks) or "off" (to turn off JSON output, the
310 default).
311
313 On success, 0 is returned, a non-zero failure code otherwise.
314
316 systemd(1), repart.d(5), machine-id(5), systemd-cryptenroll(1)
317systemd 250 SYSTEMD-REPART(8)