x86: Description of the GRUB 2 Configuration

GRUB 2 uses an entirely different configuration than GRUB Legacy. The GRUB Legacy configuration is managed through the menu.lst file, but GRUB 2 does not use a menu.lst file. Instead, GRUB 2 uses a configuration file, grub.cfg, to store the same type of information. Similar to the menu.lst file, the grub.cfg file is located at the top-level of the ZFS dataset for the root pool, /pool-name/boot/grub, for example, /rpool/boot/grub/grub.cfg.

The syntax of the grub.cfg file is based on a subset of bash scripting, which is more complex and powerful than the directive-like language that is used in the menu.lst file that is shown in the following example:

title title
             bootfs pool-name/ROOT/bootenvironment-name
             kernel$ /platform/i86pc/kernel/$ISADIR/unix -B $ZFS-BOOTFS
             module$ /platform/i86pc/$ISADIR/boot_archive

By comparison, the same configuration is stored in the grub.cfg file, as follows:

menuentry "<title>" {
        insmod part_msdos
        insmod part_sunpc
        insmod part_gpt
        insmod zfs
        search --no-floppy --fs-uuid --set=root f3d8ef099730bafa
        zfs-bootfs /ROOT/<BE name>/@/ zfs_bootfs
        set kern=/platform/i86pc/kernel/amd64/unix
        echo -n "Loading ${root}/ROOT/<BE name>/@$kern: "
        $multiboot /ROOT/<BE name>/@/$kern $kern -B $zfs_bootfs
        set gfxpayload="1024x768x32;1024x768x16;800x600x16;640x480x16;640x480x15;640x480x32"
        insmod gzio
        echo -n "Loading ${root}/ROOT/<BE name>/@/platform/i86pc/amd64/boot_archive: "
        $module /ROOT/<BE name>/@/platform/i86pc/amd64/boot_archive
}

Another significant difference between the grub.cfg file and the menu.lst file is that you do not edit the grub.cfg file. The menu.lst file supports user-created menu entries and manual changes to global GRUB configuration file settings and variables, in addition to menu entries that are automatically generated by the system. In contrast, the grub.cfg file is administered by using various bootadm subcommands, many of which are new in this release. The various bootadm subcommands enable you to administer most boot loader administration tasks. See Administering the GRUB Configuration by Using the bootadm Command.

Another feature of the grub.cfg file is that it is autogenerated whenever you make changes to the boot loader configuration. The file is also autogenerated during some operations and when certain boot administration commands are used. If necessary, you can manually generate a new grub.cfg file by running the bootadm command with the new generate-menu subcommand. Use this subcommand to create a new grub.cfg file only if the boot configuration becomes corrupted. See How to Manually Regenerate the GRUB Menu.

For reference, the GRUB 2 configuration is stored in the following files:

• grub.cfg – Is the main configuration file that is used by GRUB 2.

• /pool-name/boot/grub/menu.conf – Is a file that is used by Oracle Solaris to generate the final grub.cfg configuration file.

  The menu.conf file is a separate GRUB meta configuration file that stores the machine-parseable representation of the GRUB 2 configuration.

  ---

  Note - Do not attempt to edit this file.

  ---

• /pool-name/boot/grub/custom.cfg – Is an editable file that resides in the same location as the grub.cfg and menu.conf files. The custom.cfg file is created by the administrator (and not on the system by default). This file is reserved for the purpose of adding more complex constructs (menu entries or other scripting information) to the basic GRUB configuration.

  The custom.cfg file is referenced in the grub.cfg file. If a custom.cfg file exists on the system, the commands or directives that are in that file are then processed by the grub.cfg file. For more information, see Customizing the GRUB Configuration.