man/systemd-gpt-auto-generator.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5 <refentry id="systemd-gpt-auto-generator">
   6
   7   <refentryinfo>
   8     <title>systemd-gpt-auto-generator</title>
   9     <productname>systemd</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>systemd-gpt-auto-generator</refentrytitle>
  14     <manvolnum>8</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>systemd-gpt-auto-generator</refname>
  19     <refpurpose>Generator for automatically discovering
  20     and mounting root, <filename>/home</filename> and
  21     <filename>/srv</filename> partitions, as well as
  22     discovering and enabling swap partitions, based on GPT
  23     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     root, <filename>/home/</filename>, <filename>/srv/</filename>, the EFI System Partition, the Extended
  35     Boot Loader Partition and swap partitions and creates mount and swap units for them, based on the
  36     partition type GUIDs of GUID partition tables (GPT), see <ulink
  37     url="http://www.uefi.org/specifications">UEFI Specification</ulink>, chapter 5.  It implements the <ulink
  38     url="https://www.freedesktop.org/wiki/Specifications/DiscoverablePartitionsSpec/">Discoverable Partitions
  39     Specification</ulink>. Note that this generator has no effect on non-GPT systems, and on specific mount
  40     points that are directories already containing files. Also, on systems where the units are explicitly
  41     configured (for example, listed in <citerefentry
  42     project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>), the
  43     units this generator creates are overridden, but additional implicit dependencies might be
  44     created.</para>
  45
  46     <para>This generator will only look for root partitions on the
  47     same physical disk the EFI System Partition (ESP) is located on.
  48     It will only look for the other partitions on the same physical
  49     disk the root file system is located on. These partitions will not
  50     be searched for on systems where the root file system is distributed
  51     on multiple disks, for example via btrfs RAID.</para>
  52
  53     <para><filename>systemd-gpt-auto-generator</filename> is useful
  54     for centralizing file system configuration in the partition table
  55     and making configuration in <filename>/etc/fstab</filename> unnecessary.
  56     </para>
  57
  58     <para>This generator looks for the partitions based on their
  59     partition type GUID. The following partition type GUIDs are
  60     identified:</para>
  61
  62     <table>
  63       <title>Partition Type GUIDs</title>
  64       <tgroup cols='3' align='left' colsep='1' rowsep='1'>
  65         <colspec colname="guid" />
  66         <colspec colname="name" />
  67         <colspec colname="where" />
  68         <colspec colname="explanation" />
  69         <thead>
  70           <row>
  71             <entry>Partition Type GUID</entry>
  72             <entry>Name</entry>
  73             <entry>Mount Point</entry>
  74             <entry>Explanation</entry>
  75           </row>
  76         </thead>
  77         <tbody>
  78           <row>
  79             <entry>44479540-f297-41b2-9af7-d131d5f0458a</entry>
  80             <entry><filename>Root Partition (x86)</filename></entry>
  81             <entry><filename>/</filename></entry>
  82             <entry>On 32-bit x86 systems, the first x86 root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry>
  83           </row>
  84           <row>
  85             <entry>4f68bce3-e8cd-4db1-96e7-fbcaf984b709</entry>
  86             <entry><filename>Root Partition (x86-64)</filename></entry>
  87             <entry><filename>/</filename></entry>
  88             <entry>On 64-bit x86 systems, the first x86-64 root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry>
  89           </row>
  90           <row>
  91             <entry>69dad710-2ce4-4e3c-b16c-21a1d49abed3</entry>
  92             <entry><filename>Root Partition (32-bit ARM)</filename></entry>
  93             <entry><filename>/</filename></entry>
  94             <entry>On 32-bit ARM systems, the first ARM root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry>
  95           </row>
  96           <row>
  97             <entry>b921b045-1df0-41c3-af44-4c6f280d3fae</entry>
  98             <entry><filename>Root Partition (64-bit ARM)</filename></entry>
  99             <entry><filename>/</filename></entry>
 100             <entry>On 64-bit ARM systems, the first ARM root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry>
 101           </row>
 102           <row>
 103             <entry>993d8d3d-f80e-4225-855a-9daf8ed7ea97</entry>
 104             <entry><filename>Root Partition (Itanium/IA-64)</filename></entry>
 105             <entry><filename>/</filename></entry>
 106             <entry>On Itanium systems, the first Itanium root partition on the disk the EFI ESP is located on is mounted to the root directory <filename>/</filename>.</entry>
 107           </row>
 108           <row>
 109             <entry>933ac7e1-2eb4-4f13-b844-0e14e2aef915</entry>
 110             <entry>Home Partition</entry>
 111             <entry><filename>/home/</filename></entry>
 112             <entry>The first home partition on the disk the root partition is located on is mounted to <filename>/home</filename>.</entry>
 113           </row>
 114           <row>
 115             <entry>3b8f8425-20e0-4f3b-907f-1a25a76f98e8</entry>
 116             <entry>Server Data Partition</entry>
 117             <entry><filename>/srv/</filename></entry>
 118             <entry>The first server data partition on the disk the root partition is located on is mounted to <filename>/srv</filename>.</entry>
 119           </row>
 120           <row>
 121             <entry>0657fd6d-a4ab-43c4-84e5-0933c84b4f4f</entry>
 122             <entry>Swap</entry>
 123             <entry>n/a</entry>
 124             <entry>All swap partitions located on the disk the root partition is located on are enabled.</entry>
 125           </row>
 126           <row>
 127             <entry>c12a7328-f81f-11d2-ba4b-00a0c93ec93b</entry>
 128             <entry>EFI System Partition (ESP)</entry>
 129             <entry><filename>/efi/</filename> or <filename>/boot/</filename></entry>
 130             <entry>The first ESP located on the disk the root partition is located on is mounted to <filename>/boot</filename> or <filename>/efi</filename>, see below.</entry>
 131           </row>
 132           <row>
 133             <entry>bc13c2ff-59e6-4262-a352-b275fd6f7172</entry>
 134             <entry>Extended Boot Loader Partition</entry>
 135             <entry><filename>/boot/</filename></entry>
 136             <entry>The first Extended Boot Loader Partition is mounted to <filename>/boot</filename>, see below.</entry>
 137           </row>
 138         </tbody>
 139       </tgroup>
 140     </table>
 141
 142     <para>This generator understands the following attribute flags for partitions:</para>
 143
 144     <table>
 145       <title>Partition Attributes</title>
 146       <tgroup cols='4' align='left' colsep='1' rowsep='1'>
 147         <colspec colname="attribute" />
 148         <colspec colname="value" />
 149         <colspec colname="where" />
 150         <colspec colname="explanation" />
 151         <thead>
 152           <row>
 153             <entry>Name</entry>
 154             <entry>Value</entry>
 155             <entry>Applicable to</entry>
 156             <entry>Explanation</entry>
 157           </row>
 158         </thead>
 159         <tbody>
 160           <row>
 161             <entry><constant>GPT_FLAG_READ_ONLY</constant></entry>
 162             <entry>0x1000000000000000</entry>
 163             <entry><filename>/</filename>, <filename>/home/</filename>, <filename>/srv/</filename>, Extended Boot Loader Partition</entry>
 164             <entry>Partition is mounted read-only</entry>
 165           </row>
 166
 167           <row>
 168             <entry><constant>GPT_FLAG_NO_AUTO</constant></entry>
 169             <entry>0x8000000000000000</entry>
 170             <entry><filename>/</filename>, <filename>/home/</filename>, <filename>/srv/</filename>, Extended Boot Loader Partition</entry>
 171             <entry>Partition is not mounted automatically</entry>
 172           </row>
 173
 174           <row>
 175             <entry><constant>GPT_FLAG_NO_BLOCK_IO_PROTOCOL</constant></entry>
 176             <entry>0x0000000000000002</entry>
 177             <entry>EFI System Partition (ESP)</entry>
 178             <entry>Partition is not mounted automatically</entry>
 179           </row>
 180         </tbody>
 181       </tgroup>
 182     </table>
 183
 184     <para>The <filename>/home/</filename> and <filename>/srv/</filename> partitions may be encrypted in LUKS
 185     format. In this case, a device mapper device is set up under the names
 186     <filename>/dev/mapper/home</filename> and <filename>/dev/mapper/srv</filename>. Note that this might
 187     create conflicts if the same partition is listed in <filename>/etc/crypttab</filename> with a different
 188     device mapper device name.</para>
 189
 190     <para>Mount and automount units for the EFI System Partition (ESP) are generated on EFI systems. The ESP
 191     is mounted to <filename>/boot/</filename> (except if an Extended Boot Loader partition exists, see
 192     below), unless a mount point directory <filename>/efi/</filename> exists, in which case it is mounted
 193     there. Since this generator creates an automount unit, the mount will only be activated on-demand, when
 194     accessed. On systems where <filename>/boot/</filename> (or <filename>/efi/</filename> if it exists) is an
 195     explicitly configured mount (for example, listed in <citerefentry
 196     project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>) or where
 197     the <filename>/boot/</filename> (or <filename>/efi/</filename>) mount point is non-empty, no mount units
 198     are generated.</para>
 199
 200     <para>If the disk contains an Extended Boot Loader partition, as defined in the <ulink
 201     url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>, it is made
 202     available at <filename>/boot</filename> (by means of an automount point, similar to the ESP, see
 203     above). If both an EFI System Partition and an Extended Boot Loader partition exist the latter is
 204     preferably mounted to <filename>/boot/</filename>. Make sure to create both <filename>/efi/</filename>
 205     and <filename>/boot/</filename> to ensure both partitions are mounted.</para>
 206
 207     <para>When using this generator in conjunction with btrfs file
 208     systems, make sure to set the correct default subvolumes on them,
 209     using <command>btrfs subvolume set-default</command>.</para>
 210
 211     <para><filename>systemd-gpt-auto-generator</filename> implements
 212     <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 213   </refsect1>
 214
 215   <refsect1>
 216     <title>Kernel Command Line</title>
 217
 218     <para><filename>systemd-gpt-auto-generator</filename> understands the following kernel command line
 219     parameters:</para>
 220
 221     <variablelist class='kernel-commandline-options'>
 222
 223       <varlistentry>
 224         <term><varname>systemd.gpt_auto</varname></term>
 225         <term><varname>rd.systemd.gpt_auto</varname></term>
 226
 227         <listitem><para>Those options take an optional boolean argument, and default to yes.
 228         The generator is enabled by default, and a negative value may be used to disable it.
 229         </para></listitem>
 230       </varlistentry>
 231
 232       <varlistentry>
 233         <term><varname>root=</varname></term>
 234
 235         <listitem><para>When used with the special value <literal>gpt-auto</literal>, automatic discovery of
 236         the root parition based on the GPT partition type is enabled.  Any other value disables this
 237         generator.</para></listitem>
 238       </varlistentry>
 239
 240       <varlistentry>
 241         <term><varname>rw</varname></term>
 242         <term><varname>ro</varname></term>
 243
 244         <listitem><para>Mount the root partition read-write or read-only <emphasis>initially</emphasis>.</para>
 245
 246         <para>Note that unlike most kernel command line options these settings do not override configuration
 247         in the file system, and the file system may be remounted later. See
 248         <citerefentry><refentrytitle>systemd-remount-fs.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 249         </para></listitem>
 250       </varlistentry>
 251     </variablelist>
 252   </refsect1>
 253
 254   <refsect1>
 255     <title>See Also</title>
 256     <para>
 257       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 258       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 259       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 260       <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 261       <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 262       <citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 263       <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 264       <citerefentry project='man-pages'><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 265     </para>
 266   </refsect1>
 267
 268 </refentry>