man/systemd-repart.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-repart" conditional='ENABLE_REPART'
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-repart</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-repart</refentrytitle>
  16     <manvolnum>8</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-repart</refname>
  21     <refname>systemd-repart.service</refname>
  22     <refpurpose>Automatically grow and add partitions</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <cmdsynopsis>
  27       <command>systemd-repart</command>
  28       <arg choice="opt" rep="repeat">OPTIONS</arg>
  29       <arg choice="opt" rep="repeat"><replaceable><optional>BLOCKDEVICE</optional></replaceable></arg>
  30     </cmdsynopsis>
  31
  32     <para><filename>systemd-repart.service</filename></para>
  33   </refsynopsisdiv>
  34
  35   <refsect1>
  36     <title>Description</title>
  37
  38     <para><command>systemd-repart</command> grows and adds partitions to a partition table, based on the
  39     configuration files described in
  40     <citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  41     </para>
  42
  43     <para>If invoked with no arguments, it operates on the block device backing the root file system
  44     partition of the running OS, thus growing and adding partitions of the booted OS image itself. If
  45     <varname>--image=</varname> is used it will operate on the specified image file. When called in the
  46     initrd it operates on the block device backing <filename>/sysroot/</filename> instead, i.e. on the block
  47     device the system will soon transition into. The <filename>systemd-repart.service</filename> service is
  48     generally run at boot in the initrd, in order to augment the partition table of the OS before its
  49     partitions are mounted. <command>systemd-repart</command> (mostly) operates in a purely incremental mode:
  50     it only grows existing and adds new partitions; it does not shrink, delete or move existing partitions.
  51     The service is intended to be run on every boot, but when it detects that the partition table already
  52     matches the installed <filename>repart.d/*.conf</filename> configuration files, it executes no
  53     operation.</para>
  54
  55     <para><command>systemd-repart</command> is intended to be used when deploying OS images, to automatically
  56     adjust them to the system they are running on, during first boot. This way the deployed image can be
  57     minimal in size and may be augmented automatically at boot when needed, taking possession of disk space
  58     available but not yet used. Specifically the following use cases are among those covered:</para>
  59
  60     <itemizedlist>
  61       <listitem><para>The root partition may be grown to cover the whole available disk space.</para></listitem>
  62       <listitem><para>A <filename>/home/</filename>, swap or <filename>/srv/</filename> partition can be
  63       added.</para></listitem>
  64       <listitem><para>A second (or third, …) root partition may be added, to cover A/B style setups
  65       where a second version of the root file system is alternatingly used for implementing update
  66       schemes. The deployed image would carry only a single partition ("A") but on first boot a second
  67       partition ("B") for this purpose is automatically created.</para></listitem>
  68     </itemizedlist>
  69
  70     <para>The algorithm executed by <command>systemd-repart</command> is roughly as follows:</para>
  71
  72     <orderedlist>
  73       <listitem><para>The <filename>repart.d/*.conf</filename> configuration files are loaded and parsed,
  74       and ordered by filename (without the directory prefix). For each configuration file,
  75       drop-in files are looked for in directories with same name as the configuration file
  76       with a suffix ".d" added.</para></listitem>
  77
  78       <listitem><para>The partition table already existing on the block device is loaded and
  79       parsed.</para></listitem>
  80
  81       <listitem><para>The existing partitions in the partition table are matched up with the
  82       <filename>repart.d/*.conf</filename> files by GPT partition type UUID. The first existing partition
  83       of a specific type is assigned the first configuration file declaring the same type. The second
  84       existing partition of a specific type is then assigned the second configuration file declaring the same
  85       type, and so on. After this iterative assigning is complete any left-over existing partitions that have
  86       no matching configuration file are considered "foreign" and left as they are. And any configuration
  87       files for which no partition currently exists are understood as a request to create such a partition.
  88       </para></listitem>
  89
  90       <listitem><para>Partitions that shall be created are now allocated on the disk, taking the size
  91       constraints and weights declared in the configuration files into account. Free space is used within the
  92       limits set by size and padding requests. In addition, existing partitions that should be grown are
  93       grown. New partitions are always appended to the end of the partition table, taking the first partition
  94       table slot whose index is greater than the indexes of all existing partitions. Partitions are never
  95       reordered and thus partition numbers remain stable. When partitions are created, they are placed in the
  96       smallest area of free space that is large enough to satisfy the size and padding limits. This means
  97       that partitions might have different order on disk than in the partition table. Note that this
  98       allocation happens in memory only, the partition table on disk is not updated yet.</para></listitem>
  99
 100       <listitem><para>All existing partitions for which configuration files exist and which currently have no
 101       GPT partition label set will be assigned a label, either explicitly configured in the configuration or
 102       — if that's missing — derived automatically from the partition type. The same is done for all
 103       partitions that are newly created. These assignments are done in memory only, too, the disk is not
 104       updated yet.</para></listitem>
 105
 106       <listitem><para>Similarly, all existing partitions for which configuration files exist and which
 107       currently have an all-zero identifying UUID will be assigned a new UUID. This UUID is cryptographically
 108       hashed from a common seed value together with the partition type UUID (and a counter in case multiple
 109       partitions of the same type are defined), see below. The same is done for all partitions that are
 110       created anew. These assignments are done in memory only, too, the disk is not updated yet.
 111       </para></listitem>
 112
 113       <listitem><para>Similarly, if the disk's volume UUID is all zeroes it is also initialized, also
 114       cryptographically hashed from the same common seed value. This is done in memory only too.
 115       </para></listitem>
 116
 117       <listitem><para>The disk space assigned to new partitions (i.e. what was previously free space) is now
 118       erased. Specifically, all file system signatures are removed, and if the device supports it, the
 119       <constant>BLKDISCARD</constant> I/O control command is issued to inform the hardware that the space is
 120       now empty. In addition any "padding" between partitions and at the end of the device is similarly
 121       erased.</para></listitem>
 122
 123       <listitem><para>The new partition table is finally written to disk. The kernel is asked to reread the
 124       partition table.</para></listitem>
 125     </orderedlist>
 126
 127     <para>As exception to the normally strictly incremental operation, when called in a special "factory
 128     reset" mode, <command>systemd-repart</command> may also be used to erase existing partitions to
 129     reset an installation back to vendor defaults. This mode of operation is used when either the
 130     <option>--factory-reset=yes</option> switch is passed on the tool's command line, or the
 131     <option>systemd.factory_reset=yes</option> option specified on the kernel command line, or the
 132     <varname>FactoryReset</varname> EFI variable (vendor UUID
 133     <constant>8cf2644b-4b0b-428f-9387-6d876050dc67</constant>) is set to "yes". It alters the algorithm above
 134     slightly: between the 3rd and the 4th step above any partition marked explicitly via the
 135     <varname>FactoryReset=</varname> boolean is deleted, and the algorithm restarted, thus immediately
 136     re-creating these partitions anew empty.</para>
 137
 138     <para>Note that <command>systemd-repart</command> by default only changes partition tables, it does not
 139     create or resize any file systems within these partitions, unless the <varname>Format=</varname>
 140     configuration option is specified. Also note that there are also separate mechanisms available for this
 141     purpose, for example
 142     <citerefentry><refentrytitle>systemd-growfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> and
 143     <command>systemd-makefs</command>.</para>
 144
 145     <para>The UUIDs identifying the new partitions created (or assigned to existing partitions that have no
 146     UUID yet), as well as the disk as a whole are hashed cryptographically from a common seed value. This
 147     seed value is usually the
 148     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> of the
 149     system, so that the machine ID reproducibly determines the UUIDs assigned to all partitions. If the
 150     machine ID cannot be read (or the user passes <option>--seed=random</option>, see below) the seed is
 151     generated randomly instead, so that the partition UUIDs are also effectively random. The seed value may
 152     also be set explicitly, formatted as UUID via the <option>--seed=</option> option. By hashing these UUIDs
 153     from a common seed images prepared with this tool become reproducible and the result of the algorithm
 154     above deterministic.</para>
 155
 156     <para>The positional argument should specify the block device to operate on. Instead of a block device
 157     node path a regular file may be specified too, in which case the command operates on it like it would if
 158     a loopback block device node was specified with the file attached. If <option>--empty=create</option> is
 159     specified the specified path is created as regular file, which is useful for generating disk images from
 160     scratch.</para>
 161   </refsect1>
 162
 163   <refsect1>
 164     <title>Options</title>
 165
 166     <para>The following options are understood:</para>
 167
 168     <variablelist>
 169       <varlistentry>
 170         <term><option>--dry-run=</option></term>
 171         <listitem><para>Takes a boolean. If this switch is not specified <option>--dry-run=yes</option> is
 172         the implied default. Controls whether <filename>systemd-repart</filename> executes the requested
 173         re-partition operations or whether it should only show what it would do. Unless
 174         <option>--dry-run=no</option> is specified <filename>systemd-repart</filename> will not actually
 175         touch the device's partition table.</para>
 176
 177         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term><option>--empty=</option></term>
 182         <listitem><para>Takes one of <literal>refuse</literal>, <literal>allow</literal>,
 183         <literal>require</literal>, <literal>force</literal> or <literal>create</literal>. Controls how to
 184         operate on block devices that are entirely empty, i.e. carry no partition table/disk label yet. If
 185         this switch is not specified the implied default is <literal>refuse</literal>.</para>
 186
 187         <para>If <literal>refuse</literal> <command>systemd-repart</command> requires that the block device
 188         it shall operate on already carries a partition table and refuses operation if none is found. If
 189         <literal>allow</literal> the command will extend an existing partition table or create a new one if
 190         none exists. If <literal>require</literal> the command will create a new partition table if none
 191         exists so far, and refuse operation if one already exists. If <literal>force</literal> it will create
 192         a fresh partition table unconditionally, erasing the disk fully in effect. If
 193         <literal>force</literal> no existing partitions will be taken into account or survive the
 194         operation. Hence: use with care, this is a great way to lose all your data. If
 195         <literal>create</literal> a new loopback file is create under the path passed via the device node
 196         parameter, of the size indicated with <option>--size=</option>, see below.</para>
 197
 198         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><option>--discard=</option></term>
 203
 204         <listitem><para>Takes a boolean. If this switch is not specified <option>--discard=yes</option> is
 205         the implied default. Controls whether to issue the <constant>BLKDISCARD</constant> I/O control
 206         command on the space taken up by any added partitions or on the space in between them. Usually, it's
 207         a good idea to issue this request since it tells the underlying hardware that the covered blocks
 208         shall be considered empty, improving performance. If operating on a regular file instead of a block
 209         device node, a sparse file is generated.</para>
 210
 211         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term><option>--size=</option></term>
 216
 217         <listitem><para>Takes a size in bytes, using the usual K, M, G, T suffixes, or the special value
 218         <literal>auto</literal>. If used the specified device node path must refer to a regular file, which
 219         is then grown to the specified size if smaller, before any change is made to the partition table. If
 220         specified as <literal>auto</literal> the minimal size for the disk image is automatically determined
 221         (i.e. the minimal sizes of all partitions are summed up, taking space for additional metadata into
 222         account). This switch is not supported if the specified node is a block device. This switch has no
 223         effect if the file is already as large as the specified size or larger. The specified size is
 224         implicitly rounded up to multiples of 4096. When used with <option>--empty=create</option> this
 225         specifies the initial size of the loopback file to create.</para>
 226
 227         <para>The <option>--size=auto</option> option takes the sizes of pre-existing partitions into
 228         account. However, it does not accommodate for partition tables that are not tightly packed: the
 229         configured partitions might still not fit into the backing device if empty space exists between
 230         pre-existing partitions (or before the first partition) that cannot be fully filled by partitions to
 231         grow or create.</para>
 232
 233         <para>Also note that the automatic size determination does not take files or directories specified
 234         with <option>CopyFiles=</option> into account: operation might fail if the specified files or
 235         directories require more disk space then the configured per-partition minimal size
 236         limit.</para>
 237
 238         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 239       </varlistentry>
 240
 241       <varlistentry>
 242         <term><option>--factory-reset=</option></term>
 243
 244         <listitem><para>Takes boolean. If this switch is not specified <option>--factory=reset=no</option> is
 245         the implied default. Controls whether to operate in "factory reset" mode, see above. If set to true
 246         this will remove all existing partitions marked with <varname>FactoryReset=</varname> set to yes
 247         early while executing the re-partitioning algorithm. Use with care, this is a great way to lose all
 248         your data. Note that partition files need to explicitly turn <varname>FactoryReset=</varname> on, as
 249         the option defaults to off. If no partitions are marked for factory reset this switch has no
 250         effect. Note that there are two other methods to request factory reset operation: via the kernel
 251         command line and via an EFI variable, see above.</para>
 252
 253         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 254       </varlistentry>
 255
 256       <varlistentry>
 257         <term><option>--can-factory-reset</option></term>
 258
 259         <listitem><para>If this switch is specified the disk is not re-partitioned. Instead it is determined
 260         if any existing partitions are marked with <varname>FactoryReset=</varname>. If there are the tool
 261         will exit with exit status zero, otherwise non-zero. This switch may be used to quickly determine
 262         whether the running system supports a factory reset mechanism built on
 263         <command>systemd-repart</command>.</para>
 264
 265         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 266       </varlistentry>
 267
 268       <varlistentry>
 269         <term><option>--root=</option></term>
 270
 271         <listitem><para>Takes a path to a directory to use as root file system when searching for
 272         <filename>repart.d/*.conf</filename> files, for the machine ID file to use as seed and for the
 273         <varname>CopyFiles=</varname> and <varname>CopyBlocks=</varname> source files and directories. By
 274         default when invoked on the regular system this defaults to the host's root file system
 275         <filename>/</filename>. If invoked from the initrd this defaults to <filename>/sysroot/</filename>,
 276         so that the tool operates on the configuration and machine ID stored in the root file system later
 277         transitioned into itself.</para>
 278
 279         <para>See <option>--copy-source=</option> for a more restricted option that only affects
 280         <varname>CopyFiles=</varname>.</para>
 281
 282         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 283       </varlistentry>
 284
 285       <varlistentry>
 286         <term><option>--image=</option></term>
 287
 288         <listitem><para>Takes a path to a disk image file or device to mount and use in a similar fashion to
 289         <option>--root=</option>, see above.</para>
 290
 291         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 292       </varlistentry>
 293
 294       <xi:include href="standard-options.xml" xpointer="image-policy-open" />
 295
 296       <varlistentry>
 297         <term><option>--seed=</option></term>
 298
 299         <listitem><para>Takes a UUID as argument or the special value <constant>random</constant>. If a UUID
 300         is specified the UUIDs to assign to partitions and the partition table itself are derived via
 301         cryptographic hashing from it. If not specified it is attempted to read the machine ID from the host
 302         (or more precisely, the root directory configured via <option>--root=</option>) and use it as seed
 303         instead, falling back to a randomized seed otherwise. Use <option>--seed=random</option> to force a
 304         randomized seed. Explicitly specifying the seed may be used to generated strictly reproducible
 305         partition tables.</para>
 306
 307         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 308       </varlistentry>
 309
 310       <varlistentry>
 311         <term><option>--pretty=</option></term>
 312
 313         <listitem><para>Takes a boolean argument. If this switch is not specified, it defaults to on when
 314         called from an interactive terminal and off otherwise. Controls whether to show a user friendly table
 315         and graphic illustrating the changes applied.</para>
 316
 317         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 318       </varlistentry>
 319
 320       <varlistentry>
 321         <term><option>--definitions=</option></term>
 322
 323         <listitem><para>Takes a file system path. If specified the <filename>*.conf</filename> files are read
 324         from the specified directory instead of searching in <filename>/usr/lib/repart.d/*.conf</filename>,
 325         <filename>/etc/repart.d/*.conf</filename>,
 326         <filename>/run/repart.d/*.conf</filename>.</para>
 327
 328         <para>This parameter can be specified multiple times.</para>
 329
 330         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 331       </varlistentry>
 332
 333       <varlistentry>
 334         <term><option>--key-file=</option></term>
 335
 336         <listitem><para>Takes a file system path. Configures the encryption key to use when setting up LUKS2
 337         volumes configured with the <varname>Encrypt=key-file</varname> setting in partition files. Should
 338         refer to a regular file containing the key, or an <constant>AF_UNIX</constant> stream socket in the
 339         file system. In the latter case a connection is made to it and the key read from it. If this switch
 340         is not specified the empty key (i.e. zero length key) is used. This behaviour is useful for setting
 341         up encrypted partitions during early first boot that receive their user-supplied password only in a
 342         later setup step.</para>
 343
 344         <xi:include href="version-info.xml" xpointer="v247"/></listitem>
 345       </varlistentry>
 346
 347       <varlistentry>
 348         <term><option>--private-key=</option></term>
 349
 350         <listitem><para>Takes a file system path. Configures the signing key to use when creating verity
 351         signature partitions with the <varname>Verity=signature</varname> setting in partition files.
 352         </para>
 353
 354         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 355       </varlistentry>
 356
 357       <varlistentry>
 358         <term><option>--private-key-source=</option></term>
 359
 360         <listitem><para>Takes one of <literal>file</literal>, <literal>engine</literal> or
 361         <literal>provider</literal>. In the latter two cases, it is followed by the name of a provider or
 362         engine, separated by colon, that will be passed to OpenSSL's "engine" or "provider" logic.
 363         Configures the signing mechanism to use when creating verity signature partitions with the
 364         <varname>Verity=signature</varname> setting in partition files.</para>
 365
 366         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 367       </varlistentry>
 368
 369       <varlistentry>
 370         <term><option>--certificate=</option></term>
 371
 372         <listitem><para>Takes a file system path. Configures the PEM encoded X.509 certificate to use when
 373         creating verity signature partitions with the <varname>Verity=signature</varname> setting in
 374         partition files.</para>
 375
 376         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 377       </varlistentry>
 378
 379       <varlistentry>
 380         <term><option>--tpm2-device=</option></term>
 381         <term><option>--tpm2-pcrs=</option></term>
 382
 383         <listitem><para>Configures the TPM2 device and list of PCRs to use for LUKS2 volumes configured with
 384         the <varname>Encrypt=tpm2</varname> option. These options take the same parameters as the identically
 385         named options to
 386         <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 387         and have the same effect on partitions where TPM2 enrollment is requested.</para>
 388
 389         <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 390       </varlistentry>
 391
 392       <varlistentry>
 393         <term><option>--tpm2-device-key=<replaceable>PATH</replaceable></option></term>
 394         <term><option>--tpm2-seal-key-handle=<replaceable>HANDLE</replaceable></option></term>
 395
 396         <listitem><para>Configures a TPM2 SRK key to bind encryption to. See
 397         <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 398         for details on this option.</para>
 399
 400         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 401       </varlistentry>
 402
 403       <varlistentry>
 404         <term><option>--tpm2-public-key=<replaceable>PATH</replaceable></option></term>
 405         <term><option>--tpm2-public-key-pcrs=<replaceable>PCR<optional>+PCR...</optional></replaceable></option></term>
 406
 407         <listitem><para>Configures a TPM2 signed PCR policy to bind encryption to. See
 408         <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 409         for details on these two options.</para>
 410
 411         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 412       </varlistentry>
 413
 414       <varlistentry>
 415         <term><option>--tpm2-pcrlock=<replaceable>PATH</replaceable></option></term>
 416
 417         <listitem><para>Configures a TPM2 pcrlock policy to bind encryption to. See
 418         <citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 419         for details on this option.</para>
 420
 421         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 422       </varlistentry>
 423
 424       <varlistentry>
 425         <term><option>--split=<replaceable>BOOL</replaceable></option></term>
 426
 427         <listitem><para>Enables generation of split artifacts from partitions configured with
 428         <varname>SplitName=</varname>. If enabled, for each partition with <varname>SplitName=</varname> set,
 429         a separate output file containing just the contents of that partition is generated. The output
 430         filename consists of the loopback filename suffixed with the name configured with
 431         <varname>SplitName=</varname>. If the loopback filename ends with <literal>.raw</literal>, the suffix
 432         is inserted before the <literal>.raw</literal> extension instead.</para>
 433
 434         <para>Note that <option>--split</option> is independent from <option>--dry-run</option>. Even if
 435         <option>--dry-run</option> is enabled, split artifacts will still be generated from an existing image
 436         if <option>--split</option> is enabled.</para>
 437
 438         <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 439       </varlistentry>
 440
 441       <varlistentry>
 442         <term><option>--include-partitions=<replaceable>PARTITIONS</replaceable></option></term>
 443         <term><option>--exclude-partitions=<replaceable>PARTITIONS</replaceable></option></term>
 444
 445         <listitem><para>These options specify which partition types <command>systemd-repart</command> should
 446         operate on. If <option>--include-partitions=</option> is used, all partitions that aren't specified
 447         are excluded. If <option>--exclude-partitions=</option> is used, all partitions that are specified
 448         are excluded. Both options take a comma separated list of GPT partition type UUIDs or identifiers
 449         (see <varname>Type=</varname> in
 450         <citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 451         </para>
 452
 453         <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 454       </varlistentry>
 455
 456       <varlistentry>
 457         <term><option>--defer-partitions=<replaceable>PARTITIONS</replaceable></option></term>
 458
 459         <listitem><para>This option specifies for which partition types <command>systemd-repart</command>
 460         should defer. All partitions that are deferred using this option are still taken into account when
 461         calculating the sizes and offsets of other partitions, but aren't actually written to the disk image.
 462         The net effect of this option is that if you run <command>systemd-repart</command> again without this
 463         option, the missing partitions will be added as if they had not been deferred the first time
 464         <command>systemd-repart</command> was executed.</para>
 465
 466         <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 467       </varlistentry>
 468
 469       <varlistentry>
 470         <term><option>--sector-size=<replaceable>BYTES</replaceable></option></term>
 471
 472         <listitem><para>This option allows configuring the sector size of the image produced by
 473         <command>systemd-repart</command>. It takes a value that is a power of <literal>2</literal> between
 474         <literal>512</literal> and <literal>4096</literal>. This option is useful when building images for
 475         disks that use a different sector size as the disk on which the image is produced.</para>
 476
 477         <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 478       </varlistentry>
 479
 480       <varlistentry>
 481         <term><option>--architecture=<replaceable>ARCH</replaceable></option></term>
 482
 483         <listitem><para>This option allows overriding the architecture used for architecture specific
 484         partition types. For example, if set to <literal>arm64</literal> a partition type of
 485         <literal>root-x86-64</literal> referenced in <filename>repart.d/</filename> drop-ins will be patched
 486         dynamically to refer to <literal>root-arm64</literal> instead. Takes one of
 487         <literal>alpha</literal>,
 488         <literal>arc</literal>,
 489         <literal>arm</literal>,
 490         <literal>arm64</literal>,
 491         <literal>ia64</literal>,
 492         <literal>loongarch64</literal>,
 493         <literal>mips-le</literal>,
 494         <literal>mips64-le</literal>,
 495         <literal>parisc</literal>,
 496         <literal>ppc</literal>,
 497         <literal>ppc64</literal>,
 498         <literal>ppc64-le</literal>,
 499         <literal>riscv32</literal>,
 500         <literal>riscv64</literal>,
 501         <literal>s390</literal>,
 502         <literal>s390x</literal>,
 503         <literal>tilegx</literal>,
 504         <literal>x86</literal> or
 505         <literal>x86-64</literal>.</para>
 506
 507         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 508       </varlistentry>
 509
 510       <varlistentry>
 511         <term><option>--offline=<replaceable>BOOL</replaceable></option></term>
 512
 513         <listitem><para>Instructs <command>systemd-repart</command> to build the image offline. Takes a
 514         boolean or <literal>auto</literal>. Defaults to <literal>auto</literal>. If enabled, the image is
 515         built without using loop devices. This is useful to build images unprivileged or when loop devices
 516         are not available. If disabled, the image is always built using loop devices. If
 517         <literal>auto</literal>, <command>systemd-repart</command> will build the image online if possible
 518         and fall back to building the image offline if loop devices are not available or cannot be accessed
 519         due to missing permissions.</para>
 520
 521         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 522       </varlistentry>
 523
 524       <varlistentry>
 525         <term><option>--copy-from=<replaceable>IMAGE</replaceable></option></term>
 526
 527         <listitem><para>Instructs <command>systemd-repart</command> to synthesize partition definitions from
 528         the partition table in the given image. This option can be specified multiple times to synthesize
 529         definitions from each of the given images. The generated definitions will copy the partitions into
 530         the destination partition table. The copied partitions will have the same size, metadata and contents
 531         but might have a different partition number and might be located at a different offset in the
 532         destination partition table. These definitions can be combined with partition definitions read from
 533         regular partition definition files. The synthesized definitions take precedence over the definitions
 534         read from partition definition files.</para>
 535
 536         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 537       </varlistentry>
 538
 539       <varlistentry>
 540         <term><option>--copy-source=<replaceable>PATH</replaceable></option></term>
 541         <term><option>-s</option> <replaceable>PATH</replaceable></term>
 542
 543         <listitem><para>Specifies a source directory all <varname>CopyFiles=</varname> source paths shall be
 544         considered relative to. This is similar to <option>--root=</option>, but exclusively applies to the
 545         <varname>CopyFiles=</varname> setting. If <option>--root=</option> and
 546         <option>--copy-source=</option> are used in combination the former applies as usual, except for
 547         <varname>CopyFiles=</varname> where the latter takes precedence.</para>
 548
 549         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 550       </varlistentry>
 551
 552       <varlistentry>
 553         <term><option>--make-ddi=<replaceable>TYPE</replaceable></option></term>
 554
 555         <listitem><para>Takes one of <literal>sysext</literal>, <literal>confext</literal> or
 556         <literal>portable</literal>. Generates a Discoverable Disk Image (DDI) for a system extension
 557         (sysext, see
 558         <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 559         for details), configuration extension (confext) or <ulink
 560         url="https://systemd.io/PORTABLE_SERVICES">portable service</ulink>. The generated image will consist
 561         of a signed Verity <literal>erofs</literal> file system as root partition. In this mode of operation
 562         the partition definitions in <filename>/usr/lib/repart.d/*.conf</filename> and related directories
 563         are not read, and <option>--definitions=</option> is not supported, as appropriate definitions for
 564         the selected DDI class will be chosen automatically.</para>
 565
 566         <para>Must be used in conjunction with <option>--copy-source=</option> to specify the file hierarchy
 567         to populate the DDI with. The specified directory should contain an <filename>etc/</filename>
 568         subdirectory if <literal>confext</literal> is selected. If <literal>sysext</literal> is selected it
 569         should contain either a <filename>usr/</filename> or <filename>opt/</filename> directory, or both. If
 570         <literal>portable</literal> is used a full OS file hierarchy can be provided.</para>
 571
 572         <para>This option implies <option>--empty=create</option>, <option>--size=auto</option> and
 573         <option>--seed=random</option> (the latter two can be overridden).</para>
 574
 575         <para>The private key and certificate for signing the DDI must be specified via the
 576         <option>--private-key=</option> and <option>--certificate=</option> switches.</para>
 577
 578         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 579       </varlistentry>
 580
 581       <varlistentry>
 582         <term><option>-S</option></term>
 583         <term><option>-C</option></term>
 584         <term><option>-P</option></term>
 585
 586         <listitem><para>Shortcuts for <option>--make-ddi=sysext</option>,
 587         <option>--make-ddi=confext</option>, <option>--make-ddi=portable</option>,
 588         respectively.</para>
 589
 590         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 591       </varlistentry>
 592
 593       <varlistentry>
 594         <term><option>--generate-fstab=<replaceable>PATH</replaceable></option></term>
 595
 596         <listitem><para>Specifies a path where to write fstab entries for the mountpoints configured with
 597         <option>MountPoint=</option> in the root directory specified with <option>--copy-source=</option> or
 598         <option>--root=</option> or in the host's root directory if neither is specified. Disabled by
 599         default.</para>
 600
 601         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 602       </varlistentry>
 603
 604       <varlistentry>
 605         <term><option>--generate-crypttab=<replaceable>PATH</replaceable></option></term>
 606
 607         <listitem><para>Specifies a path where to write crypttab entries for the encrypted volumes configured
 608         with <option>EncryptedVolume=</option> in the root directory specified with
 609         <option>--copy-source=</option> or <option>--root=</option> or in the host's root directory if
 610         neither is specified. Disabled by default.</para>
 611
 612         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 613       </varlistentry>
 614
 615       <xi:include href="standard-options.xml" xpointer="help" />
 616       <xi:include href="standard-options.xml" xpointer="version" />
 617       <xi:include href="standard-options.xml" xpointer="no-pager" />
 618       <xi:include href="standard-options.xml" xpointer="no-legend" />
 619       <xi:include href="standard-options.xml" xpointer="json" />
 620     </variablelist>
 621   </refsect1>
 622
 623   <refsect1>
 624     <title>Exit status</title>
 625
 626     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 627   </refsect1>
 628
 629   <refsect1>
 630     <title>Example</title>
 631
 632     <example>
 633       <title>Generate a configuration extension image</title>
 634
 635       <para>The following creates a configuration extension DDI (confext) for an
 636       <filename>/etc/motd</filename> update:</para>
 637
 638       <programlisting>mkdir tree tree/etc tree/etc/extension-release.d
 639 echo "Hello World" > tree/etc/motd
 640 cat > tree/etc/extension-release.d/extension-release.my-motd &lt;&lt;EOF
 641 ID=fedora
 642 VERSION_ID=38
 643 IMAGE_ID=my-motd
 644 IMAGE_VERSION=7
 645 EOF
 646 systemd-repart -C --private-key=privkey.pem --certificate=cert.crt -s tree/ /var/lib/confexts/my-motd.confext.raw
 647 systemd-confext refresh</programlisting>
 648
 649       <para>The DDI generated that way may be applied to the system with
 650       <citerefentry><refentrytitle>systemd-confext</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 651     </example>
 652
 653     <example>
 654       <title>Generate a system extension image and sign it via PKCS11</title>
 655
 656       <para>The following creates a system extension DDI (sysext) for an
 657       <filename>/usr/foo</filename> update and signs it with a hardware token via PKCS11.</para>
 658
 659       <programlisting>mkdir tree tree/usr tree/usr/lib/extension-release.d
 660 echo "Hello World" > tree/usr/foo
 661 cat > tree/usr/lib/extension-release.d/extension-release.my-foo &lt;&lt;EOF
 662 ID=fedora
 663 VERSION_ID=38
 664 IMAGE_ID=my-foo
 665 IMAGE_VERSION=7
 666 EOF
 667 systemd-repart --make-ddi=sysext --private-key-source=engine:pkcs11 --private-key="pkcs11:model=PKCS%2315%20emulated;manufacturer=piv_II;serial=0123456789abcdef;token=Some%20Cert" --certificate=cert.crt -s tree/ /var/lib/extensions/my-foo.sysext.raw
 668 systemd-sysext refresh</programlisting>
 669
 670       <para>The DDI generated that way may be applied to the system with
 671       <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 672     </example>
 673
 674   </refsect1>
 675
 676   <refsect1>
 677     <title>See Also</title>
 678     <para><simplelist type="inline">
 679       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 680       <member><citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 681       <member><citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 682       <member><citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 683       <member><citerefentry><refentrytitle>portablectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 684       <member><citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 685     </simplelist></para>
 686   </refsect1>
 687
 688 </refentry>