1SYSTEMD-REPART(8)               systemd-repart               SYSTEMD-REPART(8)
2
3
4

NAME

6       systemd-repart, systemd-repart.service - Automatically grow and add
7       partitions
8

SYNOPSIS

10       systemd-repart [OPTIONS...] [[BLOCKDEVICE]...]
11
12       systemd-repart.service
13

DESCRIPTION

15       systemd-repart grows and adds partitions to a partition table, based on
16       the configuration files described in repart.d(5).
17
18       If invoked with no arguments, it operates on the block device backing
19       the root file system partition of the OS, thus growing and adding
20       partitions of the booted OS image itself. When called in the initial
21       RAM disk it operates on the block device backing /sysroot/ instead,
22       i.e. on the block device the system will soon transition into. The
23       systemd-repart.service service is generally run at boot in the initial
24       RAM disk, in order to augment the partition table of the OS before its
25       partitions are mounted.  systemd-repart (mostly) operates in a purely
26       incremental mode: it only grows existing and adds new partitions; it
27       does not shrink, delete or move existing partitions. The service is
28       intended to be run on every boot, but when it detects that the
29       partition table already matches the installed repart.d/*.conf
30       configuration files, it executes no operation.
31
32       systemd-repart is intended to be used when deploying OS images, to
33       automatically adjust them to the system they are running on, during
34       first boot. This way the deployed image can be minimal in size and may
35       be augmented automatically at boot when needed, taking possession of
36       disk space available but not yet used. Specifically the following use
37       cases are among those covered:
38
39       •   The root partition may be grown to cover the whole available disk
40           space.
41
42       •   A /home/, swap or /srv/ partition can be added.
43
44       •   A second (or third, ...) root partition may be added, to cover A/B
45           style setups where a second version of the root file system is
46           alternatingly used for implementing update schemes. The deployed
47           image would carry only a single partition ("A") but on first boot a
48           second partition ("B") for this purpose is automatically created.
49
50       The algorithm executed by systemd-repart is roughly as follows:
51
52        1. The repart.d/*.conf configuration files are loaded and parsed, and
53           ordered by filename (without the directory prefix).
54
55        2. The partition table already existing on the block device is loaded
56           and parsed.
57
58        3. The existing partitions in the partition table are matched up with
59           the repart.d/*.conf files by GPT partition type UUID. The first
60           existing partition of a specific type is assigned the first
61           configuration file declaring the same type. The second existing
62           partition of a specific type is then assigned the second
63           configuration file declaring the same type, and so on. After this
64           iterative assigning is complete any left-over existing partitions
65           that have no matching configuration file are considered "foreign"
66           and left as they are. And any configuration files for which no
67           partition currently exists are understood as a request to create
68           such a partition.
69
70        4. Taking the size constraints and weights declared in the
71           configuration files into account, all partitions that shall be
72           created are now allocated to the disk, taking up all free space,
73           always respecting the size and padding requests. Similar, existing
74           partitions that are determined to grow are grown. New partitions
75           are always appended to the end of the existing partition table,
76           taking the first partition table slot whose index is greater than
77           the indexes of all existing partitions. Partition table slots are
78           never reordered and thus partition numbers are ensured to remain
79           stable. Note that this allocation happens in RAM only, the
80           partition table on disk is not updated yet.
81
82        5. All existing partitions for which configuration files exist and
83           which currently have no GPT partition label set will be assigned a
84           label, either explicitly configured in the configuration or (if
85           that's missing) derived automatically from the partition type. The
86           same is done for all partitions that are newly created. These
87           assignments are done in RAM only, too, the disk is not updated yet.
88
89        6. Similarly, all existing partitions for which configuration files
90           exist and which currently have an all-zero identifying UUID will be
91           assigned a new UUID. This UUID is cryptographically hashed from a
92           common seed value together with the partition type UUID (and a
93           counter in case multiple partitions of the same type are defined),
94           see below. The same is done for all partitions that are created
95           anew. These assignments are done in RAM only, too, the disk is not
96           updated yet.
97
98        7. Similarly, if the disk's volume UUID is all zeroes it is also
99           initialized, also cryptographically hashed from the same common
100           seed value. Also, in RAM only, too.
101
102        8. The disk space assigned to new partitions (i.e. what was previously
103           considered free space but is no longer) is now erased.
104           Specifically, all file system signatures are removed, and if the
105           device supports it the BLKDISCARD I/O control command is issued to
106           inform the hardware that the space is empty now. In addition any
107           "padding" between partitions and at the end of the device is
108           similarly erased.
109
110        9. The new partition table is finally written to disk. The kernel is
111           asked to reread the partition table.
112
113       As exception to the normally strictly incremental operation, when
114       called in a special "factory reset" mode, systemd-repart may also be
115       used to erase existing partitions to reset an installation back to
116       vendor defaults. This mode of operation is used when either the
117       --factory-reset=yes switch is passed on the tool's command line, or the
118       systemd.factory_reset=yes option specified on the kernel command line,
119       or the FactoryReset EFI variable (vendor UUID
120       8cf2644b-4b0b-428f-9387-6d876050dc67) is set to "yes". It alters the
121       algorithm above slightly: between the 3rd and the 4th step above any
122       partition marked explicitly via the FactoryReset= boolean is deleted,
123       and the algorithm restarted, thus immediately re-creating these
124       partitions anew empty.
125
126       Note that systemd-repart only changes partition tables, it does not
127       create or resize any file systems within these partitions. A separate
128       mechanism should be used for that, for example systemd-growfs(8) and
129       systemd-makefs.
130
131       The UUIDs identifying the new partitions created (or assigned to
132       existing partitions that have no UUID yet), as well as the disk as a
133       whole are hashed cryptographically from a common seed value. This seed
134       value is usually the machine-id(5) of the system, so that the machine
135       ID reproducibly determines the UUIDs assigned to all partitions. If the
136       machine ID cannot be read (or the user passes --seed=random, see below)
137       the seed is generated randomly instead, so that the partition UUIDs are
138       also effectively random. The seed value may also be set explicitly,
139       formatted as UUID via the --seed= option. By hashing these UUIDs from a
140       common seed images prepared with this tool become reproducible and the
141       result of the algorithm above deterministic.
142
143       The positional argument should specify the block device to operate on.
144       Instead of a block device node path a regular file may be specified
145       too, in which case the command operates on it like it would if a
146       loopback block device node was specified with the file attached. If
147       --empty=create is specified the specified path is created as regular
148       file, which is useful for generating disk images from scratch.
149

OPTIONS

151       The following options are understood:
152
153       --dry-run=
154           Takes a boolean. If this switch is not specified --dry-run=yes is
155           the implied default. Controls whether systemd-repart executes the
156           requested re-partition operations or whether it should only show
157           what it would do. Unless --dry-run=no is specified systemd-repart
158           will not actually touch the device's partition table.
159
160       --empty=
161           Takes one of "refuse", "allow", "require", "force" or "create".
162           Controls how to operate on block devices that are entirely empty,
163           i.e. carry no partition table/disk label yet. If this switch is not
164           specified the implied default is "refuse".
165
166           If "refuse" systemd-repart requires that the block device it shall
167           operate on already carries a partition table and refuses operation
168           if none is found. If "allow" the command will extend an existing
169           partition table or create a new one if none exists. If "require"
170           the command will create a new partition table if none exists so
171           far, and refuse operation if one already exists. If "force" it will
172           create a fresh partition table unconditionally, erasing the disk
173           fully in effect. If "force" no existing partitions will be taken
174           into account or survive the operation. Hence: use with care, this
175           is a great way to lose all your data. If "create" a new loopback
176           file is create under the path passed via the device node parameter,
177           of the size indicated with --size=, see below.
178
179       --discard=
180           Takes a boolean. If this switch is not specified --discard=yes is
181           the implied default. Controls whether to issue the BLKDISCARD I/O
182           control command on the space taken up by any added partitions or on
183           the space in between them. Usually, it's a good idea to issue this
184           request since it tells the underlying hardware that the covered
185           blocks shall be considered empty, improving performance. If
186           operating on a regular file instead of a block device node, a
187           sparse file is generated.
188
189       --size=
190           Takes a size in bytes, using the usual K, M, G, T suffixes, or the
191           special value "auto". If used the specified device node path must
192           refer to a regular file, which is then grown to the specified size
193           if smaller, before any change is made to the partition table. If
194           specified as "auto" the minimal size for the disk image is
195           automatically determined (i.e. the minimal sizes of all partitions
196           are summed up, taking space for additional metadata into account).
197           This switch is not supported if the specified node is a block
198           device. This switch has no effect if the file is already as large
199           as the specified size or larger. The specified size is implicitly
200           rounded up to multiples of 4096. When used with --empty=create this
201           specifies the initial size of the loopback file to create.
202
203           The --size=auto option takes the sizes of pre-existing partitions
204           into account. However, it does not accommodate for partition tables
205           that are not tightly packed: the configured partitions might still
206           not fit into the backing device if empty space exists between
207           pre-existing partitions (or before the first partition) that cannot
208           be fully filled by partitions to grow or create.
209
210           Also note that the automatic size determination does not take files
211           or directories specified with CopyFiles= into account: operation
212           might fail if the specified files or directories require more disk
213           space then the configured per-partition minimal size limit.
214
215       --factory-reset=
216           Takes boolean. If this switch is not specified --factory=reset=no
217           is the implied default. Controls whether to operate in "factory
218           reset" mode, see above. If set to true this will remove all
219           existing partitions marked with FactoryReset= set to yes early
220           while executing the re-partitioning algorithm. Use with care, this
221           is a great way to lose all your data. Note that partition files
222           need to explicitly turn FactoryReset= on, as the option defaults to
223           off. If no partitions are marked for factory reset this switch has
224           no effect. Note that there are two other methods to request factory
225           reset operation: via the kernel command line and via an EFI
226           variable, see above.
227
228       --can-factory-reset
229           If this switch is specified the disk is not re-partitioned. Instead
230           it is determined if any existing partitions are marked with
231           FactoryReset=. If there are the tool will exit with exit status
232           zero, otherwise non-zero. This switch may be used to quickly
233           determine whether the running system supports a factory reset
234           mechanism built on systemd-repart.
235
236       --root=
237           Takes a path to a directory to use as root file system when
238           searching for repart.d/*.conf files and for the machine ID file to
239           use as seed. By default when invoked on the regular system this
240           defaults to the host's root file system /. If invoked from the
241           initial RAM disk this defaults to /sysroot/, so that the tool
242           operates on the configuration and machine ID stored in the root
243           file system later transitioned into itself.
244
245       --seed=
246           Takes a UUID as argument or the special value random. If a UUID is
247           specified the UUIDs to assign to partitions and the partition table
248           itself are derived via cryptographic hashing from it. If not
249           specified it is attempted to read the machine ID from the host (or
250           more precisely, the root directory configured via --root=) and use
251           it as seed instead, falling back to a randomized seed otherwise.
252           Use --seed=random to force a randomized seed. Explicitly specifying
253           the seed may be used to generated strictly reproducible partition
254           tables.
255
256       --pretty=
257           Takes a boolean argument. If this switch is not specified, it
258           defaults to on when called from an interactive terminal and off
259           otherwise. Controls whether to show a user friendly table and
260           graphic illustrating the changes applied.
261
262       --definitions=
263           Takes a file system path. If specified the *.conf files are read
264           from the specified directory instead of searching in
265           /usr/lib/repart.d/*.conf, /etc/repart.d/*.conf,
266           /run/repart.d/*.conf.
267
268       --key-file=
269           Takes a file system path. Configures the encryption key to use when
270           setting up LUKS2 volumes configured with the Encrypt=key-file
271           setting in partition files. Should refer to a regular file
272           containing the key, or an AF_UNIX stream socket in the file system.
273           In the latter case a connection is made to it and the key read from
274           it. If this switch is not specified the empty key (i.e. zero length
275           key) is used. This behaviour is useful for setting up encrypted
276           partitions during early first boot that receive their user-supplied
277           password only in a later setup step.
278
279       --tpm2-device=, --tpm2-pcrs=
280           Configures the TPM2 device and list of PCRs to use for LUKS2
281           volumes configured with the Encrypt=tpm2 option. These options take
282           the same parameters as the identically named options to systemd-
283           cryptenroll(1) and have the same effect on partitions where TPM2
284           enrollment is requested.
285
286       -h, --help
287           Print a short help text and exit.
288
289       --version
290           Print a short version string and exit.
291
292       --no-pager
293           Do not pipe output into a pager.
294
295       --no-legend
296           Do not print the legend, i.e. column headers and the footer with
297           hints.
298
299       --json=MODE
300           Shows output formatted as JSON. Expects one of "short" (for the
301           shortest possible output without any redundant whitespace or line
302           breaks), "pretty" (for a pretty version of the same, with
303           indentation and line breaks) or "off" (to turn off JSON output, the
304           default).
305

EXIT STATUS

307       On success, 0 is returned, a non-zero failure code otherwise.
308

SEE ALSO

310       systemd(1), repart.d(5), machine-id(5), systemd-cryptenroll(1)
311
312
313
314systemd 248                                                  SYSTEMD-REPART(8)
Impressum