From 51be3372ec8ba07ef68a409956ea0eefa89fe7c5 Mon Sep 17 00:00:00 2001

From: Nicholas Vinson <nvinson234@gmail.com>

Date: Mon, 16 Apr 2018 22:36:26 -0700

Subject: [PATCH] templates: Update grub script template files

Update grub-mkconfig.in and 10_linux.in to support grub-probe's new

partuuid target.  Update grub.texi documentation.  The following table

shows how GRUB_DISABLE_LINUX_UUID, GRUB_DISABLE_LINUX_PARTUUID, and

initramfs detection interact:

Initramfs  GRUB_DISABLE_LINUX_PARTUUID  GRUB_DISABLE_LINUX_UUID  Linux Root

detected   Set                          Set                      ID Method

false      false                        false                    part UUID

false      false                        true                     part UUID

false      true                         false                    dev name

false      true                         true                     dev name

true       false                        false                    fs UUID

true       false                        true                     part UUID

true       true                         false                    fs UUID

true       true                         true                     dev name

Note: GRUB_DISABLE_LINUX_PARTUUID and GRUB_DISABLE_LINUX_UUID equate to

      'false' when unset or set to any value other than 'true'.

      GRUB_DISABLE_LINUX_PARTUUID defaults to 'true'.

Signed-off-by: Nicholas Vinson <nvinson234@gmail.com>

Reviewed-by: Daniel Kiper <daniel.kiper@oracle.com>

---

 docs/grub.texi              | 67 ++++++++++++++++++++++++++++++++++++++++++---

 util/grub-mkconfig.in       |  3 ++

 util/grub.d/10_linux.in     | 22 +++++++++++++--

 util/grub.d/20_linux_xen.in | 22 +++++++++++++--

 4 files changed, 104 insertions(+), 10 deletions(-)

diff --git a/docs/grub.texi b/docs/grub.texi

index 0f2ab91fc69..2adfa97bee8 100644

--- a/docs/grub.texi

+++ b/docs/grub.texi

@@ -1214,10 +1214,11 @@ GRUB is configured using @file{grub.cfg}, usually located under

 need to write the whole thing by hand.

 @menu

-* Simple configuration::        Recommended for most users

-* Shell-like scripting::        For power users and developers

-* Multi-boot manual config::    For non-standard multi-OS scenarios

-* Embedded configuration::      Embedding a configuration file into GRUB

+* Simple configuration::            Recommended for most users

+* Root Identifcation Heuristics::   Summary on how the root file system is identified.

+* Shell-like scripting::            For power users and developers

+* Multi-boot manual config::        For non-standard multi-OS scenarios

+* Embedded configuration::          Embedding a configuration file into GRUB

 @end menu

@@ -1425,6 +1426,17 @@ the Linux kernel, using a @samp{root=UUID=...} kernel parameter.  This is

 usually more reliable, but in some cases it may not be appropriate.  To

 disable the use of UUIDs, set this option to @samp{true}.

+@item GRUB_DISABLE_LINUX_PARTUUID

+If @command{grub-mkconfig} cannot identify the root filesystem via its

+universally-unique indentifier (UUID), @command{grub-mkconfig} can use the UUID

+of the partition containing the filesystem to identify the root filesystem to

+the Linux kernel via a @samp{root=PARTUUID=...} kernel parameter.  This is not

+as reliable as using the filesystem UUID, but is more reliable than using the

+Linux device names. When @samp{GRUB_DISABLE_LINUX_PARTUUID} is set to

+@samp{false}, the Linux kernel version must be 2.6.37 (3.10 for systems using

+the MSDOS partition scheme) or newer.  This option defaults to @samp{true}.  To

+enable the use of partition UUIDs, set this option to @samp{false}.

+

 @item GRUB_DISABLE_RECOVERY

 If this option is set to @samp{true}, disable the generation of recovery

 mode menu entries.

@@ -1556,6 +1568,53 @@ edit the scripts in @file{/etc/grub.d} directly.

 menu entries; simply type the menu entries you want to add at the end of

 that file, making sure to leave at least the first two lines intact.

+@node Root Identifcation Heuristics

+@section Root Identifcation Heuristics

+If the target operating system uses the Linux kernel, @command{grub-mkconfig}

+attempts to identify the root file system via a heuristic algoirthm.  This

+algorithm selects the identification method of the root file system by

+considering three factors.  The first is if an initrd for the target operating

+system is also present.  The second is @samp{GRUB_DISABLE_LINUX_UUID} and if set

+to @samp{true}, prevents @command{grub-mkconfig} from identifying the root file

+system by its UUID.  The third is @samp{GRUB_DISABLE_LINUX_PARTUUID} and if set

+to @samp{true}, prevents @command{grub-mkconfig} from identifying the root file

+system via the UUID of its enclosing partition.  If the variables are assigned

+any other value, that value is considered equivalent to @samp{false}.  The

+variables are also considered to be set to @samp{false} if they are not set.

+

+When booting, the Linux kernel will delegate the task of mounting the root

+filesystem to the initrd.  Most initrd images determine the root file system by

+checking the Linux kernel's command-line for the @samp{root} key and use its

+value as the identification method of the root file system.  To improve the

+reliability of booting, most initrd images also allow the root file system to be

+identified by its UUID.  Because of this behavior, the @command{grub-mkconfig}

+command will set @samp{root} to @samp{root=UUID=...} to provide the initrd with

+the filesystem UUID of the root file system.

+

+If no initrd is detected or @samp{GRUB_DISABLE_LINUX_UUID} is set to @samp{true}

+then @command{grub-command} will identify the root filesystem by setting the

+kernel command-line variable @samp{root} to @samp{root=PARTUUID=...} unless

+@samp{GRUB_DISABLE_LINUX_PARTUUID} is also set to @samp{true}.  If

+@samp{GRUB_DISABLE_LINUX_PARTUUID} is also set to @samp{true},

+@command{grub-command} will identify by its Linux device name.

+

+The following table summarizes the behavior of the @command{grub-mkconfig}

+command.

+

+@multitable {detected} {GRUB_DISABLE_LINUX_PARTUUID} {GRUB_DISABLE_LINUX_UUID} {Linux Root}

+@headitem Initrd detected @tab GRUB_DISABLE_LINUX_PARTUUID Set To @tab GRUB_DISABLE_LINUX_UUID Set To @tab Linux Root ID Method

+@item false         @tab false                       @tab false                   @tab part UUID

+@item false         @tab false                       @tab true                    @tab part UUID

+@item false         @tab true                        @tab false                   @tab dev name

+@item false         @tab true                        @tab true                    @tab dev name

+@item true          @tab false                       @tab false                   @tab fs UUID

+@item true          @tab false                       @tab true                    @tab part UUID

+@item true          @tab true                        @tab false                   @tab fs UUID

+@item true          @tab true                        @tab true                    @tab dev name

+@end multitable

+

+Remember, @samp{GRUB_DISABLE_LINUX_PARTUUID} and @samp{GRUB_DISABLE_LINUX_UUID}

+are also considered to be set to @samp{false} when they are unset.

 @node Shell-like scripting

 @section Writing full configuration files directly

diff --git a/util/grub-mkconfig.in b/util/grub-mkconfig.in

index 35ef583b05f..33332360eec 100644

--- a/util/grub-mkconfig.in

+++ b/util/grub-mkconfig.in

@@ -134,6 +134,7 @@ fi

 # Device containing our userland.  Typically used for root= parameter.

 GRUB_DEVICE="`${grub_probe} --target=device /`"

 GRUB_DEVICE_UUID="`${grub_probe} --device ${GRUB_DEVICE} --target=fs_uuid 2> /dev/null`" || true

+GRUB_DEVICE_PARTUUID="`${grub_probe} --device ${GRUB_DEVICE} --target=partuuid 2> /dev/null`" || true

 # Device containing our /boot partition.  Usually the same as GRUB_DEVICE.

 GRUB_DEVICE_BOOT="`${grub_probe} --target=device /boot`"

@@ -188,6 +189,7 @@ if [ "x${GRUB_ACTUAL_DEFAULT}" = "xsaved" ] ; then GRUB_ACTUAL_DEFAULT="`"${grub

 # override them.

 export GRUB_DEVICE \

   GRUB_DEVICE_UUID \

+  GRUB_DEVICE_PARTUUID \

   GRUB_DEVICE_BOOT \

   GRUB_DEVICE_BOOT_UUID \

   GRUB_FS \

@@ -223,6 +225,7 @@ export GRUB_DEFAULT \

   GRUB_TERMINAL_OUTPUT \

   GRUB_SERIAL_COMMAND \

   GRUB_DISABLE_LINUX_UUID \

+  GRUB_DISABLE_LINUX_PARTUUID \

   GRUB_DISABLE_RECOVERY \

   GRUB_VIDEO_BACKEND \

   GRUB_GFXMODE \

diff --git a/util/grub.d/10_linux.in b/util/grub.d/10_linux.in

index faedf74e14e..146499f22fd 100644

--- a/util/grub.d/10_linux.in

+++ b/util/grub.d/10_linux.in

@@ -43,12 +43,22 @@ case ${GRUB_DEVICE} in

   ;;

 esac

+# Default to disabling partition uuid support to maintian compatibility with

+# older kernels.

+GRUB_DISABLE_LINUX_PARTUUID=${GRUB_DISABLE_LINUX_PARTUUID-true}

+

 # btrfs may reside on multiple devices. We cannot pass them as value of root= parameter

 # and mounting btrfs requires user space scanning, so force UUID in this case.

-if [ "x${GRUB_DEVICE_UUID}" = "x" ] || [ "x${GRUB_DISABLE_LINUX_UUID}" = "xtrue" ] \

-    || ! test -e "/dev/disk/by-uuid/${GRUB_DEVICE_UUID}" \

+if ( [ "x${GRUB_DEVICE_UUID}" = "x" ] && [ "x${GRUB_DEVICE_PARTUUID}" = "x" ) \

+    || ( [ "x${GRUB_DISABLE_LINUX_UUID}" = "xtrue" ] \

+	&& [ "x${GRUB_DISABLE_LINUX_PARTUUID}" = "xtrue" ] ) \

+    || ( ! test -e "/dev/disk/by-uuid/${GRUB_DEVICE_UUID}" \

+	&& ! test -e "/dev/disk/by-partuuid/${GRUB_DEVICE_PARTUUID}" ) \

     || ( test -e "${GRUB_DEVICE}" && uses_abstraction "${GRUB_DEVICE}" lvm ); then

   LINUX_ROOT_DEVICE=${GRUB_DEVICE}

+elif [ "x${GRUB_DEVICE_UUID}" = "x" ] \

+    || [ "x${GRUB_DISABLE_LINUX_UUID}" = "xtrue" ]; then

+  LINUX_ROOT_DEVICE=PARTUUID=${GRUB_DEVICE_PARTUUID}

 else

   LINUX_ROOT_DEVICE=UUID=${GRUB_DEVICE_UUID}

 fi

@@ -242,7 +252,13 @@ while [ "x$list" != "x" ] ; do

   if test -z "${initramfs}" && test -z "${initrd_real}" ; then

     # "UUID=" and "ZFS=" magic is parsed by initrd or initramfs.  Since there's

     # no initrd or builtin initramfs, it can't work here.

-    linux_root_device_thisversion=${GRUB_DEVICE}

+    if [ "x${GRUB_DEVICE_PARTUUID}" = "x" ] \

+	|| [ "x${GRUB_DISABLE_LINUX_PARTUUID}" = "xtrue" ]; then

+

+	linux_root_device_thisversion=${GRUB_DEVICE}

+    else

+	linux_root_device_thisversion=PARTUUID=${GRUB_DEVICE_PARTUUID}

+    fi

   fi

   if [ "x$is_top_level" = xtrue ] && [ "x${GRUB_DISABLE_SUBMENU}" != xy ]; then

diff --git a/util/grub.d/20_linux_xen.in b/util/grub.d/20_linux_xen.in

index 0cb0f4e49b9..e8143b079dc 100644

--- a/util/grub.d/20_linux_xen.in

+++ b/util/grub.d/20_linux_xen.in

@@ -43,12 +43,22 @@ case ${GRUB_DEVICE} in

   ;;

 esac

+# Default to disabling partition uuid support to maintian compatibility with

+# older kernels.

+GRUB_DISABLE_LINUX_PARTUUID=${GRUB_DISABLE_LINUX_PARTUUID-true}

+

 # btrfs may reside on multiple devices. We cannot pass them as value of root= parameter

 # and mounting btrfs requires user space scanning, so force UUID in this case.

-if [ "x${GRUB_DEVICE_UUID}" = "x" ] || [ "x${GRUB_DISABLE_LINUX_UUID}" = "xtrue" ] \

-    || ! test -e "/dev/disk/by-uuid/${GRUB_DEVICE_UUID}" \

+if ( [ "x${GRUB_DEVICE_UUID}" = "x" ] && [ "x${GRUB_DEVICE_PARTUUID}" = "x" ] ) \

+    || ( [ "x${GRUB_DISABLE_LINUX_UUID}" = "xtrue" ] \

+	&& [ "x${GRUB_DISABLE_LINUX_PARTUUID}" = "xtrue" ] ) \

+    || ( ! test -e "/dev/disk/by-uuid/${GRUB_DEVICE_UUID}" \

+	&& ! test -e "/dev/disk/by-partuuid/${GRUB_DEVICE_PARTUUID}" ) \

     || ( test -e "${GRUB_DEVICE}" && uses_abstraction "${GRUB_DEVICE}" lvm ); then

   LINUX_ROOT_DEVICE=${GRUB_DEVICE}

+elif [ "x${GRUB_DEVICE_UUID}" = "x" ] \

+    || [ "x${GRUB_DISABLE_LINUX_UUID}" = "xtrue" ]; then

+  LINUX_ROOT_DEVICE=PARTUUID=${GRUB_DEVICE_PARTUUID}

 else

   LINUX_ROOT_DEVICE=UUID=${GRUB_DEVICE_UUID}

 fi

@@ -246,7 +256,13 @@ while [ "x${xen_list}" != "x" ] ; do

 	    gettext_printf "Found initrd image: %s\n" "${dirname}/${initrd}" >&2

 	else

     # "UUID=" magic is parsed by initrds.  Since there's no initrd, it can't work here.

-	    linux_root_device_thisversion=${GRUB_DEVICE}

+	    if [ "x${GRUB_DEVICE_PARTUUID}" = "x" ] \

+		|| [ "x${GRUB_DISABLE_LINUX_PARTUUID}" = "xtrue" ]; then

+

+		linux_root_device_thisversion=${GRUB_DEVICE}

+	    else

+		linux_root_device_thisversion=PARTUUID=${GRUB_DEVICE_PARTUUID}

+	    fi

 	fi

 	if [ "x$is_top_level" = xtrue ] && [ "x${GRUB_DISABLE_SUBMENU}" != xy ]; then