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