ay_grub_bootloader.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1
[
  <!ENTITY % entities SYSTEM "generic-entities.ent">
    %entities;
]>
<sect1 version="5.0"
  xml:id="CreateProfile-Bootloader"
  xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>The &grub; boot loader</title>

  <info>
    <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
      <dm:bugtracker></dm:bugtracker>
      <dm:translation>yes</dm:translation>
    </dm:docmanager>
  </info>

  <para>
    This documentation is for <command>yast2-bootloader</command> and applies
    to &grub;. For older product versions shipping with legacy GRUB, refer to
    the documentation that comes with your distribution in
    <filename>/usr/share/doc/packages/autoyast2/</filename>
  </para>

  <para>
    By default, &ay; proposes the same booting mechanism as used by the booting
    medium. For example, if you boot using EFI, the GRUB 2 for EFI is
    installed. Therefore, you can omit this section unless you have specific
    requirements. As the EFI boot requires specific partitioning, we
    recommend using the automatic partitioning as described in
    <xref linkend="CreateProfile-Automatic-Partitioning"/>, which will create
    all needed partitions automatically.
  </para>

  <para>
    If you need to adapt the default, use the
    <literal>&lt;bootloader&gt;</literal> part. Its general structure
    looks like the following snippet:
  </para>

<screen>&lt;bootloader&gt;
  &lt;loader_type&gt;
    &lt;!-- boot loader type (grub2 or grub2-efi) --&gt;
  &lt;/loader_type&gt;
  &lt;global&gt;
    &lt;!--
      entries defining the installation settings for &grub; and
      the generic boot code
    --&gt;
  &lt;/global&gt;
  &lt;device_map config:type="list"&gt;
    &lt;!-- entries defining the order of devices --&gt;
  &lt;/device_map&gt;
 &lt;/bootloader&gt;</screen>
 <para>
  You do not need to fill out all settings. Rather, you only need to define 
  those that you need to change. &ay; will then merge the default values 
  with those specified in the profile.
 </para>

 <sect2 xml:id="CreateProfile-Bootloader-type-Grub">
  <title>Loader type</title>
  <para>
   This defines which boot loader (UEFI or BIOS/legacy) to use. Not all
   architectures support both legacy and EFI variants of the boot loader. The
   safest (<literal>default</literal>) option is to leave the decision up to
   the installer.
  </para>
<screen>&lt;loader_type&gt;<replaceable>LOADER_TYPE</replaceable>&lt;/loader_type&gt;</screen>
    <para>
      Possible values for <replaceable>LOADER_TYPE</replaceable> are:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <literal>default</literal>: The installer chooses the correct boot
          loader. This is the default when no option is defined.
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>grub2</literal>: Use the legacy BIOS boot loader.
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>grub2-efi</literal>: Use the EFI boot loader.
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>none</literal>: The boot process is not managed and
          configured by the installer.
        </para>
      </listitem>
    </itemizedlist>
  </sect2>

 <sect2 xml:id="CreateProfile-Bootloader-globals-Grub">
  <title>Globals</title>
  <para>
   This is an important if optional part. Define here where to install &grub;
   and how the boot process will work. Again,
   <command>yast2-bootloader</command> will propose a configuration if you do not
   define one. Usually the &ay; control file includes only this part and all
   other parts are added automatically during installation by
   <command>yast2-bootloader</command>. Unless you have some special
   requirements, do not specify the boot loader configuration in the XML file.
  </para>
  <tip>
    <title>Hibernation</title>
    <para>
      This is an important if optional part. Define here where to install
      &grub; and how the boot process will work. Again,
      <command>yast2-bootloader</command> proposes a configuration if you do
      not define one. Usually, the &ay; control file includes only this part, and
      all other parts are added automatically during installation by
      <command>yast2-bootloader</command>. Unless you have some special
      requirements, do not specify the boot loader configuration in the XML
      file.
    </para>
  </tip>
    <tip>
      <title>Hibernation</title>
      <para>
        If there is a need for specific hibernation settings, then
        <literal>resume</literal> or <literal>noresume</literal> in the
        <literal>append</literal> configuration can be used.
      </para>
      <para>
        To disable hibernation regardless of what the installer proposes,
        specify <literal>noresume</literal> as a kernel parameter in the
        <literal>append</literal> section.
      </para>
      <para>
        To specify the hibernation device, use the <literal>resume</literal>
        key with the device path. The recommended way to get stable results is
        configuring your own partitioning and having a swap device with a
        label:
      </para>
<screen>
        &lt;append&gt;quiet resume=/dev/disk/by-label/my_swap&lt;/append&gt;
      </screen>
      <para>
        If you do not use <literal>resume</literal> or
        <literal>noresume</literal>, or if <literal>resume</literal> specifies
        a device that will not exist on the installed system, then the
        installer may propose a correct value for <literal>resume</literal>, or
        it may remove the hibernation parameter completely, depending on
        installer logic.
      </para>
    </tip>
<screen>&lt;global&gt;
  &lt;activate&gt;true&lt;/activate&gt;
  &lt;timeout config:type="integer"&gt;10&lt;/timeout&gt;
  &lt;terminal&gt;gfxterm&lt;/terminal&gt;
  &lt;gfxmode&gt;1280x1024x24&lt;/gfxmode&gt;
&lt;/global&gt;</screen>
    <variablelist>
      <title>Boot loader global options</title>
      <varlistentry>
        <term>activate</term>
        <listitem>
          <para>
            Set the boot flag on the boot partition. The boot partition can be
            <filename>/</filename> if there is no separate
            <filename>/boot</filename> partition. If the boot partition is on a
            logical partition, the boot flag is set to the extended partition.
          </para>
<screen>&lt;activate&gt;true&lt;/activate&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>append</term>
        <listitem>
          <para>
            Kernel parameters added at the end of boot entries for normal and
            recovery mode.
          </para>
<screen>&lt;append&gt;nomodeset vga=0x317&lt;/append&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>boot_boot</term>
        <listitem>
          <para>
            Write &grub; to a separate <filename>/boot</filename> partition. If
            no separate <filename>/boot</filename> partition exists, &grub;
            will be written to <filename>/</filename>.
          </para>
<screen>&lt;boot_boot&gt;false&lt;/boot_boot&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>boot_custom</term>
        <listitem>
          <para>
            Write &grub; to a custom device.
          </para>
<screen>&lt;boot_custom&gt;/dev/sda3&lt;/boot_custom&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>boot_extended</term>
        <listitem>
          <para>
            Write &grub; to the extended partition (important if you want to
            use generic boot code and the <filename>/boot</filename> partition
            is logical). Note: if the boot partition is logical, you should use
            <literal>boot_mbr</literal> (write &grub; to MBR) rather than
            <literal>generic_mbr</literal>.
          </para>
<screen>&lt;boot_extended&gt;false&lt;/boot_extended&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>boot_mbr</term>
        <listitem>
          <para>
            Write &grub; to the MBR of the first disk in the order.
            (<filename>device.map</filename> includes the order of the disks.)
          </para>
<screen>&lt;boot_mbr&gt;false&lt;/boot_mbr&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>boot_root</term>
        <listitem>
          <para>
            Write &grub; to <filename>/</filename> partition.
          </para>
<screen>&lt;boot_root&gt;false&lt;/boot_root&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>cpu_mitigations</term>
        <listitem>
          <para>
            Lets you select a default setting of kernel boot command-line
            parameters for CPU mitigation (and, at the same time, strike a
            balance between security and performance).
          </para>
          <para>
            Possible values are:
          </para>
          <variablelist>
            <varlistentry>
              <term>auto</term>
              <listitem>
          &kernel_cpu_mitigations_auto;
         </listitem>
            </varlistentry>
            <varlistentry>
              <term>nosmt</term>
              <listitem>
          &kernel_cpu_mitigations_nosmt;
         </listitem>
            </varlistentry>
            <varlistentry>
              <term>off</term>
              <listitem>
          &kernel_cpu_mitigations_off;
         </listitem>
            </varlistentry>
            <varlistentry>
              <term>manual</term>
              <listitem>
          &kernel_cpu_mitigations_manual;
         </listitem>
            </varlistentry>
          </variablelist>
<screen>&lt;cpu_mitigations&gt;auto&lt;/cpu_mitigations&gt;</screen>
          <para>
            If not set in &ay;, the respective settings can be changed via
            kernel command line. By default, the (product-specific) settings in
            the <filename>/control.xml</filename> file on the installation
            medium are used (if nothing else is specified).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>generic_mbr</term>
        <listitem>
          <para>
            Write generic boot code to the MBR (will be ignored if
            <literal>boot_mbr</literal> is set to <literal>true</literal>).
          </para>
<screen>&lt;generic_mbr config:type="boolean"&gt;false&lt;/generic_mbr&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>gfxmode</term>
        <listitem>
          <para>
            Graphical resolution of the &grub; screen (requires
            &lt;terminal&gt; to be set to <literal>gfxterm</literal>).
          </para>
          <para>
            Valid entries are <literal>auto</literal>, <literal><replaceable>
            HORIZONTAL</replaceable>x<replaceable>VERTICAL</replaceable></literal>,
            or
            <literal><replaceable>HORIZONTAL</replaceable>x<replaceable>VERTICAL
            </replaceable>x<replaceable>COLOR DEPTH</replaceable></literal>.
            You can see the screen resolutions supported by &grub; on a
            particular system by using the <command>vbeinfo</command> command
            at the &grub; command line in the running system.
          </para>
<screen>&lt;gfxmode&gt;1280x1024x24&lt;/gfxmode&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>os_prober</term>
        <listitem>
          <para>
            If set to <literal>true</literal>, automatically searches for
            operating systems already installed and generates boot entries for
            them during the installation.
          </para>
<screen>&lt;os_prober&gt;false&lt;/os_prober&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>password</term>
        <listitem>
          <para>
            If this is defined, it protects the boot loader with a password.
            The system will not boot until the password is entered.
          </para>
          <para>
            It has three subelements: <literal>value</literal>,
            <literal>encrypted</literal>, and <literal>unrestricted</literal>.
          </para>
          <para>
            <literal>value</literal> holds the password. It can be either plain
            text, which &yast; will encrypt, or a password already encrypted
            with <command>grub-mkpasswd-pbkdf2</command>. Set
            <literal>encrypted</literal> to <literal>true</literal> when you
            use an already encrypted password.
          </para>
          <para>
            When <literal>unrestricted</literal> is set to
            <literal>false</literal>, users need the password defined by the
            <literal>value</literal> subelement to boot or edit &grub; menu
            entries (by pressing <keycap>E</keycap> on a selected boot menu
            item). When it is set to <literal>true</literal>, users can boot
            the system without a password, but need a password to edit &grub;
            menu entries. If the option is omitted, it defaults to
            <literal>true</literal>.
          </para>
          <para>
            <phrase os="sles;sled">For more information on managing boot
            passwords, see
            <xref linkend="vle-grub2-yast2-boot-password"/>.</phrase>
          </para>
<screen>&lt;password&gt;&lt;value&gt;my_strong_password&lt;/value&gt;&lt;encrypted&gt;false&lt;/encrypted&gt;&lt;unrestricted&gt;false&lt;/unrestricted&gt;&lt;/password&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>suse_btrfs</term>
        <listitem>
          <para>
            Obsolete and no longer used. Booting from Btrfs snapshots is
            automatically enabled.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>serial</term>
        <listitem>
          <para>
            Command to execute if the &grub; terminal mode is set to
            <literal>serial</literal>.
          </para>
<screen>&lt;serial&gt;serial --speed=115200 --unit=0 --word=8 --parity=no --stop=1&lt;/serials&gt;</screen>
        </listitem>
      </varlistentry>
      <!-- secure_boot disable added to SLE 15 SP2 oct 1 2019, not in
        earlier releases yet, see
        https://github.com/SUSE/doc-sle/pull/481 (cjs) -->
      <varlistentry>
        <term>secure_boot</term>
        <listitem>
          <para>
            If set to <literal>false</literal>, then UEFI secure boot is
            disabled. Works only for <literal>grub2-efi</literal> boot loader.
          </para>
<screen>&lt;secure_boot&gt;false&lt;/secure_boot&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>terminal</term>
        <listitem>
          <para>
            Specify the &grub; terminal mode to use. Valid entries are
            <literal>console</literal>, <literal>gfxterm</literal>, and
            <literal>serial</literal>. If set to <literal>serial</literal>, the
            serial command needs to be specified with &lt;serial&gt;, too.
          </para>
<screen>&lt;terminal&gt;serial&lt;/terminal&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>timeout</term>
        <listitem>
          <para>
            The timeout in seconds until the default boot entry is booted
            automatically.
          </para>
<screen>&lt;timeout config:type="integer"&gt;10&lt;/timeout&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>trusted_grub</term>
        <listitem>
          <para>
            If set to <literal>true</literal>, then Trusted GRUB is used.
            Trusted GRUB supports Trusted Platform Module (TPM). Works only for
            <literal>grub2</literal> boot loader.
          </para>
<screen>&lt;trusted_grub"&gt;true&lt;/trusted_grub&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>update_nvram</term>
        <listitem>
          <para>
            If set to <literal>true</literal>, then &ay; adds an NVRAM entry
            for the boot loader in the firmware. This is the desirable behavior
            unless you want to preserve a specific setting or you need to work
            around firmware issues.
          </para>
<screen>&lt;update_nvram&gt;true&lt;/update_nvram&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>vgamode</term>
        <listitem>
          <para>
            Adds the kernel parameter
            <literal>vga=<replaceable>VALUE</replaceable> </literal> to the
            boot entries.
          </para>
<screen>&lt;vgamode&gt;0x317&lt;/vgamode&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>xen_append</term>
        <listitem>
          <para>
            Kernel parameters added at the end of boot entries for &xen;
            guests.
          </para>
<screen>&lt;xen_append&gt;nomodeset vga=0x317&lt;/xen_append&gt;</screen>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>xen_kernel_append</term>
        <listitem>
          <para>
            Kernel parameters added at the end of boot entries for &xen;
            kernels on the &vmhost;.
          </para>
<screen>&lt;xen_kernel_append&gt;dom0_mem=768M&lt;/xen_kernel_append&gt;</screen>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect2>

 <sect2 xml:id="CreateProfile-Bootloader-dev-map-Grub">
  <title>Device map</title>
  <para>
   &grub; avoids mapping problems between BIOS drives and Linux devices by
   using device ID strings (UUIDs) or file system labels when generating its
   configuration files. &grub; utilities create a temporary device map on the
   fly, which is usually sufficient, particularly on single-disk systems.
   However, if you need to override the automatic device mapping mechanism,
   create your custom mapping in this section.
  </para>
<screen>&lt;device_map config:type="list"&gt;
  &lt;device_map_entry&gt;
    &lt;firmware&gt;hd0&lt;/firmware&gt; &lt;!-- order of devices in target map  --&gt;
    &lt;linux&gt;/dev/disk/by-id/ata-ST3500418AS_6VM23FX0&lt;/linux&gt; &lt;!-- name of device (disk)  --&gt;
  &lt;/device_map_entry&gt;
&lt;/device_map&gt;</screen>
 </sect2>
</sect1>