shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-01-10 05:18:17 +03:00
Code

man: document systemd-repart

Browse Source
This commit is contained in:
Lennart Poettering 2019-12-17 13:47:21 +01:00
parent 2f62a8c688
commit 917cc8082b
4 changed files with 660 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

388
man/repart.d.xml Normal file
View File

@ -0,0 +1,388 @@
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<refentry id="repart.d">
<refentryinfo>
<title>repart.d</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>repart.d</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>repart.d</refname>
<refpurpose>Partition Definition Files for Automatic Boot-Time Repartitioning</refpurpose>
</refnamediv>
<refsynopsisdiv>
<para><literallayout><filename>/etc/repart.d/*.conf</filename>
<filename>/run/repart.d/*.conf</filename>
<filename>/usr/lib/repart.d/*.conf</filename>
</literallayout></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><filename>repart.d/*.conf</filename> files describe basic properties of partitions of block
devices of the local system. They may be used to declare types, names and sizes of partitions that shall
exist. The
<citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>
service reads these files and attempts to add new partitions currently missing and enlarge existing
partitions according to these definitions. Operation is generally incremental, i.e. when applied, what
exists already is left intact, and partitions are never shrunk, moved or deleted.</para>
<para>These definition files are useful for implementing operating system images that are prepared and
delivered with minimally sized images (for example lacking any state or swap partitions), and which on
first boot automatically take possession of any remaining disk space following a few basic rules.</para>
<para>Currently, support for partition definition files is only implemented for GPT partitition
tables.</para>
<para>Partition files are generally matched against any partitions already existing on disk in a simple
algorithm: the partition files are sorted by their filename (ignoring the directory prefix), and then
compared in order against existing partitions matching the same partition type UUID. Specifically, the
first existing partition with a specific partition type UUID is assigned the first definition file with
the same partition type UUID, and the second existing partition with a specific type UUID the second
partition file with the same type UUID, and so on. Any left-over partition files that have no matching
existing partition are assumed to define new partition that shall be created. Such partitions are
appended to the end of the partition table, in the order defined by their names utilizing the first
partition slot greater than the highest slot number currently in use. Any existing partitions that have
no matching partition file are left as they are.</para>
<para>Note that these partition definition files do not describe the contents of the partitions, such as
the file system used. Separate mechanisms, such as
<citerefentry><refentrytitle>systemd-growfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> and
<command>systemd-makefs</command> maybe be used to initialize or grow the file systems inside of these
partitions.</para>
</refsect1>
<refsect1>
<title>[Partition] Section Options</title>
<variablelist>
<varlistentry>
<term><varname>Type=</varname></term>
<listitem><para>The GPT partition type UUID to match. This may be a GPT partition type UUID such as
<constant>4f68bce3-e8cd-4db1-96e7-fbcaf984b709</constant>, or one of the following special
identifiers:</para>
<table>
<title>GPT partition type identifiers</title>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
<colspec colname="name" />
<colspec colname="explanation" />
<thead>
<row>
<entry>Identifier</entry>
<entry>Explanation</entry>
</row>
</thead>
<tbody>
<row>
<entry><constant>esp</constant></entry>
<entry>EFI System Partition</entry>
</row>
<row>
<entry><constant>xbootldr</constant></entry>
<entry>Extended Boot Loader Partition</entry>
</row>
<row>
<entry><constant>swap</constant></entry>
<entry>Swap partition</entry>
</row>
<row>
<entry><constant>home</constant></entry>
<entry>Home (<filename>/home/</filename>) partition</entry>
</row>
<row>
<entry><constant>srv</constant></entry>
<entry>Server data (<filename>/srv/</filename>) partition</entry>
</row>
<row>
<entry><constant>var</constant></entry>
<entry>Variable data (<filename>/var/</filename>) partition</entry>
</row>
<row>
<entry><constant>tmp</constant></entry>
<entry>Temporary data (<filename>/var/tmp/</filename>) partition</entry>
</row>
<row>
<entry><constant>linux-generic</constant></entry>
<entry>Generic Linux file system partition</entry>
</row>
<row>
<entry><constant>root</constant></entry>
<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>
</row>
<row>
<entry><constant>root-verity</constant></entry>
<entry>Verity data for the root file system partition for the local architecture</entry>
</row>
<row>
<entry><constant>root-secondary</constant></entry>
<entry>Root file system partition of the secondary architecture of the local architecture; usually the matching 32bit architecture for the local 64bit architecture)</entry>
</row>
<row>
<entry><constant>root-secondary-verity</constant></entry>
<entry>Verity data for the root file system partition of the secondary architecture</entry>
</row>
<row>
<entry><constant>root-x86</constant></entry>
<entry>Root file system partition for the x86 (32bit, aka i386) architecture</entry>
</row>
<row>
<entry><constant>root-x86-verity</constant></entry>
<entry>Verity data for the x86 (32bit) root file system partition</entry>
</row>
<row>
<entry><constant>root-x86-64</constant></entry>
<entry>Root file system partition for the x86_64 (64bit, aka amd64) architecture</entry>
</row>
<row>
<entry><constant>root-x86-64-verity</constant></entry>
<entry>Verity data for the x86_64 (64bit) root file system partition</entry>
</row>
<row>
<entry><constant>root-arm</constant></entry>
<entry>Root file system partition for the ARM (32bit) architecture</entry>
</row>
<row>
<entry><constant>root-arm-verity</constant></entry>
<entry>Verity data for the ARM (32bit) root file system partition</entry>
</row>
<row>
<entry><constant>root-arm64</constant></entry>
<entry>Root file system partition for the ARM (64bit, aka aarch64) architecture</entry>
</row>
<row>
<entry><constant>root-arm64-verity</constant></entry>
<entry>Verity data for the ARM (64bit, aka aarch64) root file system partition</entry>
</row>
<row>
<entry><constant>root-ia64</constant></entry>
<entry>Root file system partition for the ia64 architecture</entry>
</row>
<row>
<entry><constant>root-ia64-verity</constant></entry>
<entry>Verity data for the ia64 root file system partition</entry>
</row>
</tbody>
</tgroup>
</table>
<para>This setting defaults to <constant>linux-generic</constant>.</para>
<para>Most of the partition type UUIDs listed above are defined in the <ulink
url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions
Specification</ulink>.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Label=</varname></term>
<listitem><para>The textual label to assign to the partition if none is assigned yet. Note that this
setting is not used for matching. It is also not used when a label is already set for an existing
partition. It is thus only used when a partition is newly created or when an existing one had a no
label set (that is: an empty label). If not specified a label derived from the partition type is
automatically used.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Priority=</varname></term>
<listitem><para>A numeric priority to assign to this partition, in the range -2147483648…2147483647,
with smaller values indicating higher priority, and higher values indicating smaller priority. This
priority is used in case the configured size constraints on the defined partitions do not permit
fitting all partitions onto the available disk space. If the partitions do not fit, the highest
numeric partition priority of all defined partitions is determined, and all defined partitions with
this priority are removed from the list of new partitions to create (which may be multiple, if the
same priority is used for multiple partitions). The fitting algorithm is then tried again. If the
partitions still do not fit, the now highest numeric partition priority is determined, and the
matching partitions removed too, and so on. Partitions of a priority of 0 or lower are never
removed. If all partitions with a priority above 0 are removed and the partitions still do not fit on
the device the operation fails. Note that this priority has no effect on ordering partitions, for
that use the alphabetical order of the filenames of the partition definition files. Defaults to
0.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>Weight=</varname></term>
<listitem><para>A numeric weight to assign to this partition in the range 0…1000000. Available disk
space is assigned the defined partitions according to their relative weights (subject to the size
constraints configured with <varname>SizeMinBytes=</varname>, <varname>SizeMaxBytes=</varname>), so
that a partition with weight 2000 gets double the space as one with weight 1000, and a partition with
weight 333 a third of that. Defaults to 1000.</para>
<para>The <varname>Weight=</varname> setting is used to distribute available disk space in an
"elastic" fashion, based on the disk size and existing partitions. If a partition shall have a fixed
size use both <varname>SizeMinBytes=</varname> and <varname>SizeMaxBytes=</varname> with the same
value in order to fixate the size to one value, in which case the weight has no
effect.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>PaddingWeight=</varname></term>
<listitem><para>Similar to <varname>Weight=</varname> but sets a weight for the free space after the
partition (the "padding"). When distributing available space the weights of all partitions and all
defined padding is summed, and then each partition and padding gets the fraction defined by its
weight. Defaults to 0, i.e. by default no padding is applied.</para>
<para>Padding is useful if empty space shall be left for later additions or a safety margin at the
end of the device or between partitions.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>SizeMinBytes=</varname></term>
<term><varname>SizeMaxBytes=</varname></term>
<listitem><para>Specifies minimum and maximum size constraints in bytes. Takes the usual K, M, G, T,
… suffixes (to the base of 1024). If <varname>SizeMinBytes=</varname> is specified the partition is
created at or grown to at least the specified size. If <varname>SizeMaxBytes=</varname> is specified
the partition is created at or grown to at most the specified size. The precise size is determined
through the weight value value configured with <varname>Weight=</varname>, see above. When
<varname>SizeMinBytes=</varname> is set equal to <varname>SizeMaxBytes=</varname> the configured
weight has no effect as the partition is explicitly sized to the specified fixed value. Note that
partitions are never created smaller than 4096 bytes, and since partitions are never shrunk the
previous size of the partition (in case the partition already exists) is also enforced as lower bound
for the new size. The values should be specified as multiples of 4096 bytes, and are rounded upwards
(in case of <varname>SizeMinBytes=</varname>) or downwards (in case of
<varname>SizeMaxBytes=</varname>) otherwise. If the backing device does not provide enough space to
fulfill the constraints placing the partition will fail. For partitions that shall be created,
depending on the setting of <varname>Priority=</varname> (see above) the partition might be dropped
and the placing algorithm restarted. By default no size constraints are set.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>PaddingMinBytes=</varname></term>
<term><varname>PaddingMaxBytes=</varname></term>
<listitem><para>Specifies minimum and maximum size constrains in bytes for the free space after the
partition (the "padding"). Semantics are similar to <varname>SizeMinBytes=</varname> and
<varname>SizeMaxBytes=</varname>, except that unlike partition sizes free space can be shrunk and can
be as small as zero. By default no size constraints on padding are set, so that only
<varname>PaddingWeight=</varname> determines the size of the padding applied.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>FactoryReset=</varname></term>
<listitem><para>Takes a boolean argument. If specified the partition is marked for removal during a
factory reset operation. This functionality is useful to implement schemes where images can be reset
into their original state by removing partitions and creating them anew. Defaults to off.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Grow the root partition to the full disk size at first boot</title>
<para>With the following file the root partition is automatically grown to the full disk if possible during boot.</para>
<para><programlisting># /usr/lib/repart.d/50-root.conf
[Partition]
Type=root
</programlisting></para>
</example>
<example>
<title>Create a swap and home partition automatically on boot, if missing</title>
<para>The home partition gets all available disk space while the swap partition gets 1G at most and 64M
at least. We set a priority > 0 on the swap partition to ensure the swap partition is not used if not
enough space is available. For every three bytes assigned to the home partition the swap partition gets
assigned one.</para>
<para><programlisting># /usr/lib/repart.d/60-home.conf
[Partition]
Type=home
</programlisting></para>
<para><programlisting># /usr/lib/repart.d/70-swap.conf
[Partition]
Type=swap
SizeMinBytes=64M
SizeMaxBytes=1G
Priority=1
Weight=333
</programlisting></para>
</example>
<example>
<title>Create B partitions in an A/B Verity setup, if missing</title>
<para>Let's say the vendor intends to update OS images in an A/B setup, i.e. with two root partitions
(and two matching Verity partitions) that shall be used alternatingly during upgrades. To minimize
image sizes the original image is shipped only with one root and one Verity partition (the "A" set),
and the second root and Verity partitions (the "B" set) shall be created on first boot on the free
space on the medium.</para>
<para><programlisting># /usr/lib/repart.d/50-root.conf
[Partition]
Type=root
SizeMinBytes=512M
SizeMaxBytes=512M
</programlisting></para>
<para><programlisting># /usr/lib/repart.d/60-root-verity.conf
[Partition]
Type=root-verity
SizeMinBytes=64M
SizeMaxBytes=64M
</programlisting></para>
<para>The definitions above cover the "A" set of root partition (of a fixed 512M size) and Verity
partition for the root partition (of a fixed 64M size). Let's use symlinks to create the "B" set of
partitions, since after all they shall have the same properties and sizes as the "A" set.</para>
<para><programlisting># ln -s 50-root.conf /usr/lib/repart.d/70-root-b.conf
# ln -s 60-root-verity.conf /usr/lib/repart.d/80-root-verity-b.conf
</programlisting></para>
</example>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>sfdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

2
man/rules/meson.build
View File

@ -47,6 +47,7 @@ manpages = [
['pam_systemd', '8', [], 'HAVE_PAM'],
['portablectl', '1', [], 'ENABLE_PORTABLED'],
['pstore.conf', '5', ['pstore.conf.d'], 'ENABLE_PSTORE'],
['repart.d', '5', [], ''],
['resolvectl', '1', ['resolvconf'], 'ENABLE_RESOLVE'],
['resolved.conf', '5', ['resolved.conf.d'], 'ENABLE_RESOLVE'],
['runlevel', '8', [], ''],
@ -769,6 +770,7 @@ manpages = [
'ENABLE_RANDOMSEED'],
['systemd-rc-local-generator', '8', [], ''],
['systemd-remount-fs.service', '8', ['systemd-remount-fs'], ''],
['systemd-repart', '8', ['systemd-repart.service'], ''],
['systemd-resolved.service', '8', ['systemd-resolved'], 'ENABLE_RESOLVE'],
['systemd-rfkill.service',
'8',

1
man/systemd-makefs@.service.xml
View File

@ -80,6 +80,7 @@
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>mkfs.btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>mkfs.cramfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>mkfs.ext4</refentrytitle><manvolnum>8</manvolnum></citerefentry>,

269
man/systemd-repart.xml Normal file
View File

@ -0,0 +1,269 @@
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="systemd-repart"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd-repart</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>systemd-repart</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd-repart</refname>
<refname>systemd-repart.service</refname>
<refpurpose>Automatically grow and add partitions</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>systemd-repart</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="opt" rep="repeat"><replaceable><optional>BLOCKDEVICE</optional></replaceable></arg>
</cmdsynopsis>
<para><filename>systemd-repart.service</filename></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>systemd-repart</command> grows and adds partitions to a partition table, based on the
configuration files described in
<citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
<para>If invoked with no arguments, it operates on the block device backing the root file system partition
of the OS, thus growing and adding partitions of the booted OS image itself. When called in the initial
RAM disk it operates on the block device backing <filename>/sysroot/</filename> instead, i.e. on the
block device the system will soon transition into. The <filename>systemd-repart.service</filename>
service is generally run at boot in the initial RAM disk, in order to augment the partition table of the
OS before its partitions are mounted. <command>systemd-repart</command> (mostly) operates in a purely
incremental mode: it only grows existing and adds new partitions; it does not shrink, delete or move
existing partitions. The service is intended to be run on every boot, but when it detects that the
partition table already matches the installed <filename>repart.d/*.conf</filename> configuration
files, it executes no operation.</para>
<para><command>systemd-repart</command> is intended to be used when deploying OS images, to automatically
adjust them to the system they are running on, during first boot. This way the deployed image can be
minimal in size and may be augmented automatically at boot when needed, taking possession of disk space
available but not yet used. Specifically the following use cases are among those covered:</para>
<itemizedlist>
<listitem><para>The root partition may be grown to cover the whole available disk space</para></listitem>
<listitem><para>A <filename>/home/</filename>, swap or <filename>/srv</filename> partition can be added in</para></listitem>
<listitem><para>A second (or third, …) root partition may be added in, to cover A/B style setups
where a second version of the root file system is alternatingly used for implementing update
schemes. The deployed image would carry only a single partition ("A") but on first boot a second
partition ("B") for this purpose is automatically created.</para></listitem>
</itemizedlist>
<para>The algorithm executed by <command>systemd-repart</command> is roughly as follows:</para>
<orderedlist>
<listitem><para>The <filename>repart.d/*.conf</filename> configuration files are loaded and parsed,
and ordered by filename (without the directory suffix). </para></listitem>
<listitem><para>The partition table already existing on the block device is loaded and
parsed.</para></listitem>
<listitem><para>The existing partitions in the partition table are matched up with the
<filename>repart.d/*.conf</filename> files by GPT partition type UUID. The first existing partition
of a specific type is assigned the first configuration file declaring the same type. The second
existing partition of a specific type is then assigned the second configuration file declaring the same
type, and so on. After this iterative assigning is complete any left-over existing partitions that have
no matching configuration file are considered "foreign" and left as they are. And any configuration
files for which no partition currently exists are understood as a request to create such a
partition.</para></listitem>
<listitem><para>Taking the size constraints and weights declared in the configuration files into
account, all partitions that shall be created are now allocated to the disk, taking up all free space,
always respecting the size and padding requests. Similar, existing partitions that are determined to
grow are grown. New partitions are always appended to the end of the existing partition table, taking
the first partition table slot whose index is greater than the indexes of all existing
partitions. Partition table slots are never reordered and thus partition numbers are ensured to remain
stable. Note that this allocation happens in RAM only, the partition table on disk is not updated
yet.</para></listitem>
<listitem><para>All existing partitions for which configuration files exist and which currently have no
GPT partition label set will be assigned a label, either explicitly configured in the configuration or
(if that's missing) derived automatically from the partition type. The same is done for all partitions
that are newly created. These assignments are done in RAM only, too, the disk is not updated
yet.</para></listitem>
<listitem><para>Similarly, all existing partitions for which configuration files exist and which
currently have an all-zero identifying UUID will be assigned a new UUID. This UUID is cryptographically
hashed from a common seed value together with the partition type UUID (and a counter in case multiple
partitions of the same type are defined), see below. The same is done for all partitions that are
created anew. These assignments are done in RAM only, too, the disk is not updated
yet.</para></listitem>
<listitem><para>Similarly, if the disk's volume UUID is all zeroes it is also initialized, also
cryptographically hashed from the same common seed value. Also, in RAM only, too.</para></listitem>
<listitem><para>The disk space assigned to new partitions (i.e. what was previously considered free
space but is no longer) is now erased. Specifically, all file system signatures are removed, and if the
device supports it the <constant>BLKDISCARD</constant> I/O control command is issued to inform the
hardware that the space is empty now. In addition any "padding" between partitions and at the end of
the device is similarly erased.</para></listitem>
<listitem><para>The new partition table is finally written to disk. The kernel is asked to reread the
partition table.</para></listitem>
</orderedlist>
<para>As exception to the normally strictly incremental operation, when called in a special "factory
reset" mode <command>systemd-repart</command> may also be used to erase select existing partitions to
reset an installation back to vendor defaults. This mode of operation is used when either the
<option>--factory-reset=yes</option> switch is passed on the tool's command line, or the
<option>systemd.factory_reset=yes</option> option specified on the kernel command line, or the
<varname>FactoryReset</varname> EFI variable (vendor UUID
<constant>8cf2644b-4b0b-428f-9387-6d876050dc67</constant>) is set to "yes". It alters the algorithm above
slightly: between the 3rd and the 4th step above the any partition marked explicitly via the
<varname>FactoryReset=</varname> boolean is deleted, and the algorithm restarted, thus immediately
re-creating these partitions anew empty.</para>
<para>Note that <command>systemd-repart</command> only changes partition tables, it does not create or
resize any file systems within these partitions. A separate mechanism should be used for that, for
example
<citerefentry><refentrytitle>systemd-growfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> and
<command>systemd-makefs</command>.</para>
<para>The UUIDs identifying the new partitions created (or assigned to existing partitions that have no
UUID yet), as well as the disk as a whole are hashed cryptographically from a common seed value. This
seed value is usually the
<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> of the
system, so that the machine ID reproducibly determines the UUIDs assigned to all partitions. If the
machine ID cannot be read (or the user passes <option>--seed=random</option>, see below) the seed is
generated randomly instead, so that the partition UUIDs are also effectively random. The seed value may
also be set explicitly, formatted as UUID via the <option>--seed=</option> option. By hashing these UUIDs
from a common seed images prepared with this tool become reproducible and the result of the algorithm
above deterministic.</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>The following options are understood:</para>
<variablelist>
<varlistentry>
<term><option>--dry-run=</option></term>
<listitem><para>Takes a boolean. If this switch is not specified <option>--dry-run=yes</option> is
the implied default. Controls whether <filename>systemd-repart</filename> executes the requested
re-partition operations or whether it should only show what it would do. Unless
<option>--dry-run=no</option> is specified <filename>systemd-repart</filename> will not actually
touch the device's partition table.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--empty=</option></term>
<listitem><para>Takes one of <literal>refuse</literal>, <literal>allow</literal>,
<literal>require</literal> or <literal>force</literal>. Controls how to operate on block devices that
are entirely empty, i.e. carry no partition table/disk label yet. If this switch is not specified the
implied default is <literal>refuse</literal>.</para>
<para>If <literal>refuse</literal> <command>systemd-repart</command> requires that the block device
it shall operate on already carries a partition table and refuses operation if none is found. If
<literal>allow</literal> the command will extend an existing partition table or create a new one if
none exists. If <literal>require</literal> the command will create a new partition table if none
exists so far, and refuse operation if one already exists. If <literal>force</literal> it will create
a fresh partition table unconditionally, erasing the disk fully in effect. If
<literal>force</literal> no existing partitions will be taken into account or survive the
operation. Hence: use with care, this is a great way to lose all your data.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--discard=</option></term>
<listitem><para>Takes a boolean. If this switch is not specified <option>--discard=yes</option> is
the implied default. Controls whether to issue the <constant>BLKDISCARD</constant> I/O control
command on the space taken up by any added partitions or on the space in between them. Usually, it's
a good idea to issue this request since it tells the underlying hardware that the covered blocks
shall be considered empty, improving performance.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--factory-reset=</option></term>
<listitem><para>Takes boolean. If this switch is not specified <option>--factory=reset=no</option> is
the implied default. Controls whether to operate in "factory reset" mode, see above. If set to true
this will remove all existing partitions marked with <varname>FactoryReset=</varname> set to yes
early while executing the re-partitioning algorithm. Use with care, this is a great way to lose all
your data. Note that partition files need to explicitly turn <varname>FactoryReset=</varname> on, as
the option defaults to off. If no partitions are marked for factory reset this switch has no
effect. Note that there are two other methods to request factory reset operation: via the kernel
command line and via an EFI variable, see above.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--can-factory-reset</option></term>
<listitem><para>If this switch is specified the disk is not re-partitioned. Instead it is determined
if any existing partitions are marked with <varname>FactoryReset=</varname>. If there are the tool
will exit with exit status zero, otherwise non-zero. This switch may be used to quickly determine
whether the running system supports a factory reset mechanism built on
<command>systemd-repart</command>.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--root=</option></term>
<listitem><para>Takes a path to a directory to use as root file system when searching for
<filename>repart.d/*.conf</filename> files and for the machine ID file to use as seed. By default
when invoked on the regular system this defaults to the host's root file system
<filename>/</filename>. If invoked from the initial RAM disk this defaults to
<filename>/sysroot/</filename>, so that the tool operates on the configuration and machine ID stored
in the root file system later transitioned into itself.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--seed=</option></term>
<listitem><para>Takes a UUID as argument or the special value <constant>random</constant>. If a UUID
is specified the UUIDs to assign to partitions and the partition table itself are derived via
cryptographic hashing from it. If not specified it is attempted to read the machine ID from the host
(or more precisely, the root directory configured via <option>--root=</option>) and use it as seed
instead, falling back to a randomized seed otherwise. Use <option>--seed=random</option> to force a
randomized seed. Explicitly specifying the seed may be used to generated strictly reproducible
partition tables.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--pretty=</option></term>
<listitem><para>Takes a boolean argument. If this switch is not specified, it defaults to on when
called from an interactive terminal and off otherwise. Controls whether to show a user friendly table
and graphic illustrating the changes applied.</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--definitions=</option></term>
<listitem><para>Takes a file system path. If specified the <filename>*.conf</filename> are directly
read from the specified directory instead of searching in
<filename>/usr/lib/repart.d/*.conf</filename>, <filename>/etc/repart.d/*.conf</filename>,
<filename>/run/repart.d/*.conf</filename>.</para></listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>