x86 Legacy BIOS Boot Loader (GRUB2)

This section describes how ONIE on legacy BIOS firmware platforms uses GRUB2 and how the disk is partitioned.

Note

For UEFI firmware systems see x86 UEFI Firmware Support.

Note

For legacy BIOS systems, the philosophy is that the NOS owns the boot loader and the NOS must install its own GRUB (or some other boot loader) itself.

The ONIE kernel and initramfs reside in a single, self-contained partition. The installed NOS controls how it manages the MBR and GRUB.

Disk Partition Layout

The disk partition layout plays a critical role in how ONIE and the installed NOS cooperate. This section describes the layout and lays down the guidelines by which ONIE and the NOS must abide.

All of the steps described in this section are exercised by the Demo OS Installer and Demo OS Runtime that ships with ONIE. See the Demo OS Installer and OS Runtime section for more about the Demo OS.

Disk Partition Type

Each machine can choose whether to use GUID Partition Table (GPT) or MS-DOS disk labels. The choice is made in the $MACHINE/machine.make file by setting PARTITION_TYPE to msdos or gpt.

The choice is up to the hardware vendor. The onie-sysinfo -t command reports the disk label used by the running machine. An NOS installer can use this command to determine how to partition the disk for itself.

If not specified, the default partition table type is GPT.

Initial ONIE Install (embed)

When ONIE is initially installed in the factory, the hard disk is blank. Assume PXE boot (or a USB stick) was used to install ONIE for the first time.

The below examples use GPT as the disk label. The mechanics for MS-DOS disk labels are nearly the same, the only difference being GPT needs to create the “BIOS GRUB” partition while MS-DOS does not.

For example, assume the hard disk is available as /dev/sda from Linux.

After embedding ONIE, the disk layout looks like:

+========================+
|                        |
|  Sector LBA 0 aka MBR  |  <-- 1st stage boot loader in LBA-0.  Installed by ONIE
|                        |      during grub-install.  Loads additional code from
|  1st stage boot loader |      /dev/sda1 and configuration from /dev/sda2.
|                        |
+========================+
|                        |
|  /dev/sda1 GRUB        |  <-- Additional data stored and used by GRUB for GPT disk
|                        |      labels.  Installed by ONIE during grub-install.
|  BIOS GRUB             |      MS-DOS partition type does not have this.
|                        |
+========================+
|                        |
|  /dev/sda2 ONIE-BOOT   |  <-- ONIE partition.  Installed by ONIE.  Contains
|                        |      kernel and initramfs.  The GRUB 1st stage loader is
|  ONIE Installs GRUB    |      *also* installed on this partition.
|                        |
+========================+
|                        |
|                        |
/  Free Space            /
|                        |
|                        |
+========================+

During the initial disk provisioning the ONIE installer does the following:

1. Since the disk is blank we are embedding ONIE and need to create the partition table. The installer creates a disk label (either msdos or gpt depending on machine config). gpt is used in this example.
2. Creates needed partitions (two for gpt, one for msdos). The ONIE-BOOT partition is created in either case.
3. Installs ONIE kernel+initramfs into the ONIE-BOOT partition.
4. Installs GRUB into /dev/sda, using /dev/sda2 as the GRUB --boot-directory. This allows the system to boot initially with no NOS installed.
5. Installs GRUB again into /dev/sda2, the ONIE-BOOT partition. This facilitates chainloading ONIE.

An OS normally installs the GRUB 1st stage loader into /dev/sda (and for GPT also in /dev/sda1). The GRUB configuration and related files go into /dev/sda2, typically mounted as /boot.

Another supported option is to install the GRUB 1st stage loader into a partition, like /dev/sda2. Using this approach you can chainload the ONIE OS from the NOS’s GRUB menu.

When ONIE is installed in the factory, the ONIE installer installs the GRUB 1st stage loader into both /dev/sda and /dev/sda2. The 1st stage loader in /dev/sda is “disposable” and is over written by the NOS when it installs GRUB. The disposable 1st stage loader is only used to get ONIE started the first time, then the NOS installer will take over.

Note

The philosophy here is that the installed NOS owns the /dev/sda MBR for installing the GRUB 1st stage loader. ONIE owns everything in /dev/sda2. As long as the NOS installer leaves /dev/sda2 intact, we are good.

Note

For GPT disk labels, the ONIE-BOOT partition type GUID is 7412F7D5-A156-4B13-81DC-867174929325. This GUID is recognized by the gdisk and sgdisk utilities from the GPT fdisk package. See commit b784e0c95a11 for details.

The initial GRUB menu looks like this:

     GNU GRUB  version 2.02~beta2+e4a1fe391

+---------------------------------------------+
|*ONIE: Install OS                            |
| ONIE: Rescue                                |
| ONIE: Uninstall OS                          |
| ONIE: Update ONIE                           |
| ONIE: Embed ONIE                            |
|                                             |
|                                             |
+---------------------------------------------+

After a NOS Installer Runs

Continuing the example above, let’s examine what a NOS installer must do. The NOS installer is going to create partitions and install its own version of GRUB (could even be GRUB legacy or LILO).

As an example assume the user installed CentOS into the remaining free space.

The disk now looks like:

+========================+
|                        |
|  Sector LBA 0 aka MBR  |  <-- 1st stage boot loader in LBA-0.  Installed by CentOS
|                        |      during grub-install.  Loads additional code from
|  1st stage boot loader |      /dev/sda1 and configuration from /dev/sda3.
|                        |
+========================+
|                        |
|  /dev/sda1 GRUB        |  <-- Additional data stored and used by GRUB for GPT disk
|                        |      labels.  Installed by CentOS during grub-install.
|  BIOS GRUB             |      MSDOS partition type does not have this.
|                        |
+========================+
|                        |
|  /dev/sda2 ONIE-BOOT   |  <-- ONIE partition.  Untouched by the CentOS installer.
|                        |
|  ONIE Installs GRUB    |
|                        |
+========================+
|                        |
|                        |
/  /dev/sda3 CentOS      /  <-- CentOS partition.  Installed by CentOS.  Contains
|                        |      kernel, initramfs and GRUB configuration.
|                        |
+========================+

Note

CentOS installed its version of the GRUB 1st stage loader into /dev/sda, overwriting what ONIE installed in the factory. This is OK.

The CentOS GRUB will reference GRUB config files and modules from /dev/sda3. It does not involve ONIE installed on /dev/sda2 at all.

Chainloading and Selecting ONIE Mode

In order to facilitate returning to ONIE from the NOS the NOS adds a GRUB menu entry for chainloading ONIE. A sample file that can be dropped into /etc/grub.d is provided in onie/rootconf/x86_64/sysroot-lib-onie/50_onie_grub.

To select which “mode” to start ONIE in the NOS uses a tool provided by ONIE called onie-boot-mode. See the x86 NOS Interface section for more about the onie-boot-mode command.

The use of grub-reboot is helpful here to reboot and chainload ONIE for one boot, returning to the default GRUB menu entry after that.

With the ONIE chainload menu entry in place, the GRUB menu looks something like this after a reboot:

     GNU GRUB  version 2.02~beta2+e4a1fe391

+-----------------------------------------------+
|*CentOS 6.5-x86_64                             |
| Memory test (memtest86+)                      |
| ONIE                                          |
|                                               |
|                                               |
+-----------------------------------------------+

Installing GRUB and creating an initial grub.cfg file that chainloads ONIE is demonstrated by the Demo OS installer. See the Demo OS Installer and OS Runtime section for more about the Demo OS.

Here is an example of what the ONIE chainload GRUB menu entry looks like:

# Menu entry to chainload ONIE
menuentry ONIE {
        search --no-floppy --label --set=root ONIE-BOOT
        echo    'Loading ONIE ...'
        chainloader +1
}

Here is a example script, run in the context of the NOS, that would reboot the system into ONIE rescue mode:

#!/bin/sh

echo "Rebooting into ONIE rescue mode..."

grub-reboot ONIE
/mnt/onie-boot/onie/tools/bin/onie-boot-mode -q -o rescue

ONIE Boot Commands in GRUB Prompt

At the ONIE GRUB prompt several commands exist for booting ONIE in the various modes:

• onie_install
• onie_rescue
• onie_uninstall
• onie_update
• onie_embed
• diag_bootcmd

These commands would be handy for automated testing to boot specific target directly.

Before performing the command, enter the GRUB prompt by pressing c in the GRUB menu page:

                    GNU GRUB  version 2.02~beta2+e4a1fe391

+----------------------------------------------------------------------------+
|*ONIE: Install OS                                                           |
| ONIE: Rescue                                                               |
| ONIE: Uninstall OS                                                         |
| ONIE: Update ONIE                                                          |
| ONIE: Embed ONIE                                                           |
|                                                                            |
|                                                                            |
|                                                                            |
|                                                                            |
|                                                                            |
|                                                                            |
|                                                                            |
+----------------------------------------------------------------------------+

     Use the ^ and v keys to select which entry is highlighted.
     Press enter to boot the selected OS, `e' to edit the commands
     before booting or `c' for a command-line.

In the GRUB prompt, type the command to boot desired target. Take onie_rescue as an example:

                     GNU GRUB  version 2.02~beta2+e4a1fe391

   Minimal BASH-like line editing is supported. For the first word, TAB
   lists possible command completions. Anywhere else TAB lists possible
   device or file completions. ESC at any time exits.


grub> onie_rescue