man/systemd-gpt-auto-generator.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.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-gpt-auto-generator" conditional='HAVE_BLKID'>
   7
   8   <refentryinfo>
   9     <title>systemd-gpt-auto-generator</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>systemd-gpt-auto-generator</refentrytitle>
  15     <manvolnum>8</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>systemd-gpt-auto-generator</refname>
  20     <refpurpose>Generator for automatically discovering and mounting root, <filename>/home/</filename>,
  21     <filename>/srv/</filename>, <filename>/var/</filename> and <filename>/var/tmp/</filename> partitions, as
  22     well as discovering and enabling swap partitions, based on GPT partition type GUIDs</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <para><filename>/usr/lib/systemd/system-generators/systemd-gpt-auto-generator</filename></para>
  27   </refsynopsisdiv>
  28
  29   <refsect1>
  30     <title>Description</title>
  31
  32     <para><filename>systemd-gpt-auto-generator</filename> is a unit generator that automatically discovers
  33     the root partition, <filename>/home/</filename>, <filename>/srv/</filename>, <filename>/var/</filename>,
  34     <filename>/var/tmp/</filename>, the EFI System Partition, the Extended Boot Loader Partition, and swap
  35     partitions and creates mount and swap units for them, based on the partition type GUIDs of GUID partition
  36     tables (GPT). See <ulink url="https://uefi.org/specifications">UEFI Specification</ulink>, chapter 5 for
  37     more details. It implements the <ulink
  38     url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
  39     Partitions Specification</ulink>.</para>
  40
  41     <para>Note that this generator has no effect on non-GPT systems. It will also not create mount point
  42     configuration for directories which already contain files or if the mount point is explicitly configured
  43     in <citerefentry
  44     project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>. If
  45     the units this generator creates are overridden, for example by units in directories with higher
  46     precedence, drop-ins and additional dependencies created by this generator might still be used.</para>
  47
  48     <para>This generator will only look for the root partition on the same physical disk where the EFI System
  49     Partition (ESP) is located. Note that support from the boot loader is required: the EFI variable
  50     <varname>LoaderDevicePartUUID</varname> of the <constant>4a67b082-0a4c-41cf-b6c7-440b29bb8c4f</constant>
  51     vendor UUID is used to determine from which partition, and hence the disk, from which the system was
  52     booted. If the boot loader does not set this variable, this generator will not be able to detect the root
  53     partition. See the <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>
  54     for details.</para>
  55
  56     <para>Similarly, this generator will only look for the other partitions on the same physical disk as the
  57     root partition. In this case, boot loader support is not required. These partitions will not be searched
  58     for on systems where the root file system is distributed on multiple disks, for example via btrfs RAID.
  59     </para>
  60
  61     <para><filename>systemd-gpt-auto-generator</filename> is useful for centralizing file system
  62     configuration in the partition table and making configuration in <filename>/etc/fstab</filename> or on
  63     the kernel command line unnecessary.</para>
  64
  65     <para>This generator looks for the partitions based on their
  66     partition type GUID. The following partition type GUIDs are
  67     identified:</para>
  68
  69     <table>
  70       <title>Partition Type GUIDs</title>
  71       <tgroup cols='3' align='left' colsep='1' rowsep='1'>
  72         <colspec colname="guid" />
  73         <colspec colname="name" />
  74         <colspec colname="where" />
  75         <colspec colname="explanation" />
  76         <thead>
  77           <row>
  78             <entry>Partition Type GUID</entry>
  79             <entry>Name</entry>
  80             <entry>Mount Point</entry>
  81             <entry>Explanation</entry>
  82           </row>
  83         </thead>
  84         <tbody>
  85           <row>
  86             <entry><constant>SD_GPT_ROOT_X86_64</constant> <constant>4f68bce3-e8cd-4db1-96e7-fbcaf984b709</constant></entry>
  87             <entry><filename>Root Partition (x86-64)</filename></entry>
  88             <entry><filename>/</filename></entry>
  89             <entry>The first partition with this type UUID, located on the same disk as the ESP, is used as the root file system <filename>/</filename> on AMD64 / 64-bit x86 systems.</entry>
  90           </row>
  91           <row>
  92             <entry><constant>SD_GPT_ROOT_ARM64</constant> <constant>b921b045-1df0-41c3-af44-4c6f280d3fae</constant></entry>
  93             <entry><filename>Root Partition (64-bit ARM)</filename></entry>
  94             <entry><filename>/</filename></entry>
  95             <entry>The first partition with this type UUID, located on the same disk as the ESP, is used as the root file system <filename>/</filename> on AArch64 / 64-bit ARM systems.</entry>
  96           </row>
  97           <row>
  98             <entry>
  99               <constant>SD_GPT_ROOT_ALPHA</constant> <constant>SD_GPT_ROOT_ARC</constant> <constant>SD_GPT_ROOT_ARM</constant> <constant>SD_GPT_ROOT_ARM64</constant> <constant>SD_GPT_ROOT_IA64</constant> <constant>SD_GPT_ROOT_LOONGARCH64</constant> <constant>SD_GPT_ROOT_MIPS_LE</constant> <constant>SD_GPT_ROOT_MIPS64_LE</constant> <constant>SD_GPT_ROOT_PARISC</constant> <constant>SD_GPT_ROOT_PPC</constant> <constant>SD_GPT_ROOT_PPC64</constant> <constant>SD_GPT_ROOT_PPC64_LE</constant> <constant>SD_GPT_ROOT_RISCV32</constant> <constant>SD_GPT_ROOT_RISCV64</constant> <constant>SD_GPT_ROOT_S390</constant> <constant>SD_GPT_ROOT_S390X</constant> <constant>SD_GPT_ROOT_TILEGX</constant> <constant>SD_GPT_ROOT_X86</constant> <constant>SD_GPT_ROOT_X86_64</constant> <constant>SD_GPT_USR_ALPHA</constant> <constant>SD_GPT_USR_ARC</constant> <constant>SD_GPT_USR_ARM</constant> <constant>SD_GPT_USR_IA64</constant> <constant>SD_GPT_USR_LOONGARCH64</constant> <constant>SD_GPT_USR_MIPS_LE</constant> <constant>SD_GPT_USR_MIPS64_LE</constant> <constant>SD_GPT_USR_PARISC</constant> <constant>SD_GPT_USR_PPC</constant> <constant>SD_GPT_USR_PPC64</constant> <constant>SD_GPT_USR_PPC64_LE</constant> <constant>SD_GPT_USR_RISCV32</constant> <constant>SD_GPT_USR_RISCV64</constant> <constant>SD_GPT_USR_S390</constant> <constant>SD_GPT_USR_S390X</constant> <constant>SD_GPT_USR_TILEGX</constant> <constant>SD_GPT_USR_X86</constant>
 100             </entry>
 101             <entry>root partitions for other architectures</entry>
 102             <entry><filename>/</filename></entry>
 103             <entry>The first partition with the type UUID matching the architecture, located on the same disk as the ESP, is used as the root file system <filename>/</filename>. For the full list and constant values, see <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>.</entry>
 104           </row>
 105           <row>
 106             <entry><constant>SD_GPT_HOME</constant> <constant>933ac7e1-2eb4-4f13-b844-0e14e2aef915</constant></entry>
 107             <entry>Home Partition</entry>
 108             <entry><filename>/home/</filename></entry>
 109             <entry>The first partition with this type UUID on the same disk as the ESP is mounted to <filename>/home/</filename>.</entry>
 110           </row>
 111           <row>
 112             <entry><constant>SD_GPT_SRV</constant> <constant>3b8f8425-20e0-4f3b-907f-1a25a76f98e8</constant></entry>
 113             <entry>Server Data Partition</entry>
 114             <entry><filename>/srv/</filename></entry>
 115             <entry>The first partition with this type UUID on the same disk as the ESP is mounted to <filename>/srv/</filename>.</entry>
 116           </row>
 117           <row>
 118             <entry><constant>SD_GPT_VAR</constant> <constant>4d21b016-b534-45c2-a9fb-5c16e091fd2d</constant></entry>
 119             <entry>Variable Data Partition</entry>
 120             <entry><filename>/var/</filename></entry>
 121             <entry>The first partition with this type UUID on the same disk as the ESP is mounted to <filename>/var/</filename> — under the condition its partition UUID matches the first 128 bit of the HMAC-SHA256 of the GPT type uuid of this partition keyed by the machine ID of the installation stored in <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</entry>
 122           </row>
 123           <row>
 124             <entry><constant>SD_GPT_TMP</constant> <constant>7ec6f557-3bc5-4aca-b293-16ef5df639d1</constant></entry>
 125             <entry>Temporary Data Partition</entry>
 126             <entry><filename>/var/tmp/</filename></entry>
 127             <entry>The first partition with this type UUID on the same disk as the ESP is mounted to <filename>/var/tmp/</filename>.</entry>
 128           </row>
 129           <row>
 130             <entry><constant>SD_GPT_SWAP</constant> <constant>0657fd6d-a4ab-43c4-84e5-0933c84b4f4f</constant></entry>
 131             <entry>Swap</entry>
 132             <entry>n/a</entry>
 133             <entry>All partitions with this type UUID on the same disk as the ESP are used as swap.</entry>
 134           </row>
 135           <row>
 136             <entry><constant>SD_GPT_ESP</constant> <constant>c12a7328-f81f-11d2-ba4b-00a0c93ec93b</constant></entry>
 137             <entry>EFI System Partition (ESP)</entry>
 138             <entry><filename>/efi/</filename> or <filename>/boot/</filename></entry>
 139             <entry>The first partition with this type UUID located on the same disk as the root partition is mounted to <filename>/boot/</filename> or <filename>/efi/</filename>, see below.</entry>
 140           </row>
 141           <row>
 142             <entry><constant>SD_GPT_XBOOTLDR</constant> <constant>bc13c2ff-59e6-4262-a352-b275fd6f7172</constant></entry>
 143             <entry>Extended Boot Loader Partition</entry>
 144             <entry><filename>/boot/</filename></entry>
 145             <entry>The first partition with this type UUID located on the same disk as the root partition is mounted to <filename>/boot/</filename>, see below.</entry>
 146           </row>
 147         </tbody>
 148       </tgroup>
 149     </table>
 150
 151     <para>This generator understands the following attribute flags for partitions:</para>
 152
 153     <table>
 154       <title>Partition Attribute Flags</title>
 155       <tgroup cols='3' align='left' colsep='1' rowsep='1'>
 156         <colspec colname="flag" />
 157         <colspec colname="where" />
 158         <colspec colname="explanation" />
 159         <thead>
 160           <row>
 161             <entry>Flag</entry>
 162             <entry>Applicable to</entry>
 163             <entry>Explanation</entry>
 164           </row>
 165         </thead>
 166         <tbody>
 167           <row>
 168             <entry><constant>SD_GPT_FLAG_READ_ONLY</constant> <constant>0x1000000000000000</constant></entry>
 169             <entry><filename>/</filename>, <filename>/home/</filename>, <filename>/srv/</filename>, <filename>/var/</filename>, <filename>/var/tmp/</filename>, Extended Boot Loader Partition</entry>
 170             <entry>Partition is mounted read-only</entry>
 171           </row>
 172
 173           <row>
 174             <entry><constant>SD_GPT_FLAG_NO_AUTO</constant> <constant>0x8000000000000000</constant></entry>
 175             <entry><filename>/</filename>, <filename>/home/</filename>, <filename>/srv/</filename>, <filename>/var/</filename>, <filename>/var/tmp/</filename>, Extended Boot Loader Partition</entry>
 176             <entry>Partition is not mounted automatically</entry>
 177           </row>
 178
 179           <row>
 180             <entry><constant>SD_GPT_FLAG_NO_BLOCK_IO_PROTOCOL</constant> <constant>0x0000000000000002</constant></entry>
 181             <entry>EFI System Partition (ESP)</entry>
 182             <entry>Partition is not mounted automatically</entry>
 183           </row>
 184         </tbody>
 185       </tgroup>
 186     </table>
 187
 188     <para>The <filename>/home/</filename>, <filename>/srv/</filename>, <filename>/var/</filename>,
 189     <filename>/var/tmp/</filename> and swap partitions may be encrypted in LUKS format. In this case, a
 190     device mapper device is set up under the names <filename>/dev/mapper/home</filename>,
 191     <filename>/dev/mapper/srv</filename>, <filename>/dev/mapper/var</filename>,
 192     <filename>/dev/mapper/tmp</filename> or <filename>/dev/mapper/swap</filename>. Note that this might
 193     create conflicts if the same partition is listed in <filename>/etc/crypttab</filename> with a different
 194     device mapper device name.</para>
 195
 196     <para>When systemd is running in the initrd the <filename>/</filename> partition may be encrypted with
 197     LUKS as well. In this case, a device mapper device is set up under the name
 198     <filename>/dev/mapper/root</filename>, and a <filename>sysroot.mount</filename> is set up that mounts the
 199     device under <filename>/sysroot</filename>. For more information, see
 200     <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 201     </para>
 202
 203     <para>The root partition can be specified by symlinking <filename>/run/systemd/volatile-root</filename>
 204     to <filename>/dev/block/$major:$minor</filename>. This is especially useful if the root mount has been
 205     replaced by some form of volatile file system (overlayfs).
 206     </para>
 207
 208     <para>Mount and automount units for the EFI System Partition (ESP) and Extended Boot Loader Partition
 209     (XBOOTLDR) are generated on EFI systems. If the disk contains an XBOOTLDR partition, as defined in the
 210     <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
 211     Specification</ulink>, it is made available at <filename>/boot/</filename>. This generator creates an
 212     automount unit; the mount will only be activated on-demand when accessed. The mount point will be created
 213     if necessary.</para>
 214
 215     <para>The ESP is mounted to <filename>/boot/</filename> if that directory exists and is not used for
 216     XBOOTLDR, and otherwise to <filename>/efi/</filename>. Same as for <filename>/boot/</filename>, an
 217     automount unit is used. The mount point will be created if necessary.</para>
 218
 219     <para>No configuration is created for mount points that are configured in <citerefentry
 220     project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> or when
 221     the target directory contains files.</para>
 222
 223     <para>When using this generator in conjunction with btrfs file
 224     systems, make sure to set the correct default subvolumes on them,
 225     using <command>btrfs subvolume set-default</command>.</para>
 226
 227     <para>If the system was booted via
 228     <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> and the
 229     stub reported to userspace that the kernel image was measured to a TPM2 PCR, then any discovered root and
 230     <filename>/var/</filename> volume identifiers (and volume encryption key in case it is encrypted) will be
 231     automatically measured into PCR 15 on activation, via
 232     <citerefentry><refentrytitle>systemd-pcrfs@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 233
 234     <para><filename>systemd-gpt-auto-generator</filename> implements
 235     <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 236   </refsect1>
 237
 238   <refsect1>
 239     <title>Kernel Command Line</title>
 240
 241     <para><filename>systemd-gpt-auto-generator</filename> understands the following kernel command line
 242     parameters:</para>
 243
 244     <variablelist class='kernel-commandline-options'>
 245
 246       <varlistentry>
 247         <term><varname>systemd.gpt_auto</varname></term>
 248         <term><varname>rd.systemd.gpt_auto</varname></term>
 249
 250         <listitem><para>Those options take an optional boolean argument, and default to yes.
 251         The generator is enabled by default, and a false value may be used to disable it
 252         (e.g. <literal>systemd.gpt_auto=0</literal>).
 253         </para></listitem>
 254       </varlistentry>
 255
 256       <varlistentry>
 257         <term><varname>systemd.image_policy=</varname></term>
 258         <term><varname>rd.systemd.image_policy=</varname></term>
 259
 260         <listitem><para>Takes an image dissection policy string as argument (as per
 261         <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
 262         and allows enforcing a policy on dissection and use of the automatically discovered GPT partition
 263         table entries.</para></listitem>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term><varname>root=</varname></term>
 268         <term><varname>rootfstype=</varname></term>
 269         <term><varname>rootflags=</varname></term>
 270
 271         <listitem><para>When <varname>root=</varname> is used with the special value
 272         <literal>gpt-auto</literal> (or if the parameter is not used at all), automatic discovery of the root
 273         partition based on the GPT partition type is enabled. Any other value disables this
 274         logic.</para>
 275
 276         <para>The <varname>rootfstype=</varname> and <varname>rootflags=</varname> are used to select the
 277         file system type and options when the root file system is automatically discovered.</para></listitem>
 278       </varlistentry>
 279
 280       <varlistentry>
 281         <term><varname>rw</varname></term>
 282         <term><varname>ro</varname></term>
 283
 284         <listitem><para>Mount the root partition read-write or read-only <emphasis>initially</emphasis>.</para>
 285
 286         <para>Note that unlike most kernel command line options these settings do not override configuration
 287         in the file system, and the file system may be remounted later. See
 288         <citerefentry><refentrytitle>systemd-remount-fs.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 289         </para></listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term><varname>systemd.swap=</varname></term>
 294
 295         <listitem><para>Takes a boolean argument or enables the option if specified without an argument.
 296         If disabled, automatic discovery of swap partition(s) based on GPT partition type is disabled.
 297         Defaults to enabled.</para></listitem>
 298       </varlistentry>
 299     </variablelist>
 300   </refsect1>
 301
 302   <refsect1>
 303     <title>See Also</title>
 304     <para>
 305       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 306       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 307       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 308       <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 309       <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 310       <citerefentry><refentrytitle>systemd-pcrfs@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 311       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 312       <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 313       <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 314       <citerefentry project='man-pages'><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 315     </para>
 316   </refsect1>
 317
 318 </refentry>