x86: Administering the GRUB Configuration by Using the bootadm Command

The following procedures are provided in this section:

• x86: How to List GRUB Menu Entries

• x86: How to Manually Regenerate the GRUB Menu

• x86: How to Maintain the GRUB Menu

• x86: How to Set Attributes for a Specified Boot Entry in the GRUB Menu

• x86: How to Add a Boot Entry to the GRUB Menu

• x86: How to Remove a Boot Entry From the GRUB Menu

On systems that support GRUB Legacy, the GRUB configuration and the GRUB menu is primarily managed by editing the menu.lst file. On systems that support GRUB 2, the grub.cfg file is used. However, this file is not manually edited. Instead, the file is managed by using the boot administration interface, bootadm. The bootadm command can be used to administer most of the tasks that were previously done by editing the menu.lst file. These tasks include administering boot loader settings, the GRUB menu, as well as individual attributes of a particular boot entry.

The following bootadm subcommands have been modified to support the administration of the GRUB 2 configuration:

list-menu

Displays the current boot entries in the GRUB menu.

A new -P option supports displaying boot entries for a specified root pool.

View individual menu entries by title or entry number, as follows:

# bootadm list-menu -i 0
the location of the boot loader configuration files is: /rpool/boot/grub
     title: Oracle Solaris 11 FCS
     kernel: /platform/i86pc/kernel/$ISADIR/unix
     kernel arguments: -B $ZFS-BOOTFS -v
     boot archive: /platform/i86pc/$ISADIR/boot_archive
     ZFS root pool: rpool

set-menu

Maintains the GRUB menu. This subcommand is used to set a particular GRUB menu entry as the default and to set other menu options and boot loader options.

A new -P option supports changing menus on multiple root pools.

The following bootadm subcommands are new:

add-entry

Adds a boot entry to the GRUB menu.

change-entry

Changes the attributes of a specified boot entry in the GRUB menu.

generate-menu

Generates a new boot loader configuration file.

install-bootloader

Installs the system boot loader. This subcommand applies to both x86 and SPARC platforms.

remove-entry

Removes a boot entry from the GRUB menu.

The following procedures describe how to use the bootadm command to manage the GRUB configuration and the GRUB menu. For more complete information, see the bootadm(1M) man page.

x86: How to List GRUB Menu Entries

Use the list-menu subcommand of the bootadm command to list the GRUB menu entries that are currently on the system. This information is supplied by the grub.cfg file. The output of the command also includes the location boot loader configuration files, the default boot entry number, the autoboot-timeout value, and the title of each boot entry.

• List the contents of the grub.cfg file.

  $ bootadm list-menu

  For example:

  $ bootadm list-menu
  the location of the boot loader configuration files is: /rpool/boot/grub
  default 0
  console graphics
  timeout 30
  0 Oracle Solaris 11 FCS
  1 Oracle Solaris backup-1
  2 Oracle Solaris 11 11.1 

  If you specify an entry title or entry number when running the command, that information is also displayed.

  $ bootadm list-menu -i entry-number

  For example:

  $ bootadm list-menu -i 0
       the location of the boot loader configuration files is: /rpool/boot/grub
       title: Oracle Solaris 11 FCS
       kernel: /platform/i86pc/kernel/$ISADIR/unix
       kernel arguments: -B $ZFS-BOOTFS -v
       boot archive: /platform/i86pc/$ISADIR/boot_archive
       ZFS root pool: rpool

x86: How to Manually Regenerate the GRUB Menu

Use the bootadm generate-menu command to manually regenerate a grub.cfg file that contains the OS instances that are currently installed on a system.

Information from the /usr/lib/grub2/bios/etc/default/grub or the /usr/lib/grub2/uefi64/etc/default/grub file, combined with information from GRUB meta configuration file, rpool/boot/grub/menu.conf, is used to generate the final grub.cfg file.

1. Assume the root role.

   See How to Use Your Assigned Administrative Rights in Oracle Solaris 11.1 Administration: Security Services.

2. Generate the grub.cfg file.

   # bootadm generate-menu

   • If the grub.cfg file already exists, use the -f option to overwrite the existing file.

     # bootadm generate-menu -f

   • Generate a new GRUB menu for a root pool other than the current root pool, as follows:

     # bootadm generate-menu -P pool-name

3. Verify that the menu has been updated to reflect the changes.

   # bootadm list-menu

   ---

   Note - If you do not see your changes, check the grub.cfg file to verify that the change was made.

   ---

x86: How to Maintain the GRUB Menu

Use the set-menu subcommand of the bootadm command to maintain the GRUB menu. For example, you can use the command to change the menu timeout and the default boot entry in the GRUB menu.

1. Assume the root role.

   See How to Use Your Assigned Administrative Rights in Oracle Solaris 11.1 Administration: Security Services.

2. (Optional) List the GRUB menu entries.

   # bootadm list-menu

3. Make the necessary changes to the GRUB menu.

   # bootadm set-menu [-P pool] [-R altroot [-p platform]] key=value

   For more information about each value that can you can specify by using the set-menu subcommand, see the bootadm(1M) man page. Examples of common ways that you can use the set-menu subcommand follow this procedure.

4. Verify that the changes have been made.

   # bootadm list-menu

   ---

   Note - If you do not see your changes, check the grub.cfg file to verify that the change was made.

   ---

Example 2-1 Changing the Default Boot Entry in the GRUB Menu

Use the bootadm set-menu command with the appropriate key=value option to set the default entry number (for example, 0, 1, or 2) in the GRUB menu. This number designates which operating system is booted when the timer expires.

For example, the output of the following bootadm list-menu command shows the default boot entry as 2, which is Oracle Solaris 11_test:

# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 2
console graphics
timeout 30
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1
2 Oracle Solaris 11_test

In this example, the console is set to graphics mode. Other modes that you can set the console to include text and serial.

You can set the default boot entry to 1, as follows:

# bootadm set-menu default=1
# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 1
console graphics
timeout 30
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1
2 GRUB2

In this example, the default menu entry is now 1. When the system is rebooted, it will automatically boot the new Oracle Solaris entry after the default timer expires.

You can also set the default entry in the GRUB menu by using the change-entry subcommand. See x86: How to Set Attributes for a Specified Boot Entry in the GRUB Menu.

Example 2-2 Changing the Menu Timeout Value in the GRUB Menu

Use the bootadm set-menu command with the appropriate key=value option to set the menu timeout value.

In the following example, the output of the bootadm list-menu command shows a default timeout value of 30 seconds that has been changed to 45 seconds. The change takes effect the next time the system is booted.

# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 2
console graphics
timeout 30
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1
2 Oracle Solaris 11_test
# bootadm set-menu timeout=45
# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 2
console graphics
timeout 45
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1
2 Oracle Solaris 11_test

Example 2-3 Setting the GRUB Console Type

One value that you can set by using the set-menu subcommand of the bootadm command is the console type. Changing the console type in this way persists over system reboots.

For example, you would set the console type to serial in the grub.cfg file, as follows:

# bootadm set-menu console=serial

You can also set the console type to text for plain text console. Choose this option if you are using BIOS serial redirection. Or, you can set the console type to graphics. This option provides a more graphical menu, and a background image is used.

When you set the console type to serial, you can configure the serial parameters that GRUB 2 uses when initializing the serial port at boot time. If you do not specify a serial_params value, the default is to use serial port 0 (COM1/ttya) and to not specify a speed. Note that if a speed is not specified and only a port is specified, for example, serial_params=0, then the speed that is used is undefined and will be whatever speed the serial port was initialized to before GRUB executes. If you to ensure a specific speed is used, they need to explicitly set it with serial_params.

Add the serial_params key value to the bootadm command line, as follows:

# bootadm set-menu console=serial serial_params=port[,speed[,data bits[,parity[,stop bits]]]]

port

Is the port number. Any number from 0 to 3 (usually 0 is used for ttya or COM1) can be used to specify ports ttya through ttyd, or COM1 through COM4, respectively.

speed

Is the speed that the serial port uses. If this value is omitted, GRUB 2 uses whatever speed the serial port has been initialized to use. If the serial port has not been initialized, failure to specify the speed might cause unpredictable output. If you are not sure if the serial port has been initialized, and you are not using BIOS console redirection, it is best to specify a speed value.

data bits

Is specified with a value of either 7 or 8.

parity

Is specified as e, o, n (for even, odd, or none), respectively.

stop bits

Is specified with a value of 0 or 1.

All of the serial parameters, with the exception of the port parameter, are optional.

x86: How to Set Attributes for a Specified Boot Entry in the GRUB Menu

Use the change-entry subcommand of the bootadm command to set certain boot attributes for a specified boot entry, or a comma-separated list of entries, in the GRUB menu. The entry is specified by either an entry title or an entry number. If multiple entries have the same title, all of the entries are affected.

For information about how to set attributes for specific boot entries by editing the GRUB menu at boot time, see x86: Adding Kernel Arguments by Editing the GRUB Menu at Boot Time.

1. Assume the root role.

   See How to Use Your Assigned Administrative Rights in Oracle Solaris 11.1 Administration: Security Services.

2. (Optional) List the GRUB menu entries.

   # bootadm list-menu

3. Set the boot attributes for the specified entry.

   # bootadm change-entry [-P pool] {[entry-title[,entry-title...]}]
       | -i entry-number[,entry-number]...]} { key=value [ key=value ...]
       | set-default }

   When specifying a value that includes white space, you must enclose the value in single or double quotation marks.

   For more information about each value that you can specify by using the change-entry subcommand, see the bootadm(1M) man page. Examples of common ways to use the change-entry subcommand follow this procedure.

4. Verify that the changes have been made to the specified entry.

   # bootadm list-menu

   ---

   Note - If you do not see your changes, check the grub.cfg file to verify that the change was made.

   ---

Example 2-4 Setting the Title for a Specified Boot Entry in the GRUB Menu

You can set the title for a specified boot entry by using the change-entry subcommand of the bootadm command. When setting the title, you can specify either the entry number or the entry title. The following example shows how to set the title for a specified boot entry both ways. If multiple have the same title, all of the entries are affected.

Set the title for a boot entry by specifying the entry number, as follows:

# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 1
console graphics
timeout 30
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1
2 Oracle Solaris 11_test
# bootadm change-entry -i 2 title="Oracle Solaris 11-backup1"
# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 2
console graphics
timeout 45
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1
2 Oracle Solaris 11-backup1

Set the title for a boot entry by specifying the title, as follows:

# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 1
console graphics
timeout 30
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1
2 Oracle Solaris 11_test
# bootadm change-entry "Oracle Solaris 11_test" title="Oracle Solaris 11-backup1"
# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 2
console graphics
timeout 45
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1
2 Oracle Solaris 11-backup1

Example 2-5 Changing a Boot Entry by Specifying Kernel Arguments

The following examples show how to set kernel boot arguments for a specified boot entry by using the change-entry subcommand of the bootadm command.

In this example, boot entry number 1 is set to boot in single-user mode:

# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 1
console graphics
timeout 30
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1
2 Oracle Solaris 11_test
# bootadm change-entry -i 1 kargs=-s
# bootadm list-menu -i 1
The location of the boot loader configuration files is: /rpool/boot/grub
     title: Oracle Solaris 11.1
     kernel: /platform/i86pc/kernel/$ISADIR/unix
     kernel arguments: -s
     boot archive: /platform/i86pc/$ISADIR/boot_archive
     ZFS root pool: rpool

In this example, multiple kernel arguments are specified for boot entry number 2:

# bootadm change-entry -i 2 kargs="-v -s"
# bootadm list-menu -i 2
The location of the boot loader configuration files is: /rpool/boot/grub
     title: Oracle Solaris 11_test
     kernel: /platform/i86pc/kernel/$ISADIR/unix
     kernel arguments: -v -s
     boot archive: /platform/i86pc/$ISADIR/boot_archive
     bootfs: rpool/ROOT/snv_160-nightly-1

In this example, the -v and -s options were specified, which boots the system to a single-user state in verbose mode.

Any time that you set an attribute (or multiple attributes) that include white space, you must enclose the values in single or double quotation marks.

Example 2-6 Changing a Boot Entry by Using the -B Option to Specify Kernel Arguments

The following examples show some of ways that you can set kernel arguments for a specific boot entry by using the -B option.

You would disable the e1000g network driver and load the kernel debugger at boot time, as follows:

# bootadm change-entry -i 0 kargs="-B disable-e1000g=true -k"

You can specify multiple -B options by using the bootadm change-entry command. For example, you would disable the e1000g driver and ACPI at the same time by using either of the following commands:

# bootadm change-entry -i 0 kargs="-B disable-e1000g=true -B acpi-user-options=2"

# bootadm change-entry -i 0 kargs="-B disable-e1000g=true,acpi-user-options=2"

You can also use the -B option to set certain boot attributes at boot time by editing the specified boot entry. For instructions, see x86: Adding Kernel Arguments by Editing the GRUB Menu at Boot Time.

Example 2-7 Removing Previously Added Kernel Arguments From a Boot Entry

In the following example, a kernel argument (-s) is removed from a specific boot entry:

# bootadm list-menu -i 1
the location of the boot loader configuration files is: /rpool/boot/grub
title: s11.1.backup
kernel: /platform/i86pc/kernel/amd64/unix
kernel arguments: -s
boot archive: /platform/i86pc/amd64/boot_archive
bootfs: rpool/ROOT/s11.1.backup
# bootadm change-entry -i 1 kargs=
# bootadm list-menu -i 1
the location of the boot loader configuration files is: /rpool/boot/grub
title: s11.1.backup
kernel: /platform/i86pc/kernel/amd64/unix
kernel arguments:
boot archive: /platform/i86pc/amd64/boot_archive
bootfs: rpool/ROOT/s11.1.backup

x86: How to Add a Boot Entry to the GRUB Menu

Use the add-entry subcommand of the bootadm command to add a new entry to the GRUB menu with the specified entry title. If you specify an entry number, the new entry is inserted at the given position in the GRUB menu. Or, if the entry number is higher than the current number of entries in the menu, the entry is then added as the last entry in the menu.

1. Assume the root role.

   See How to Use Your Assigned Administrative Rights in Oracle Solaris 11.1 Administration: Security Services.

2. (Optional) List the current boot entries in the GRUB menu.

   # bootadm list-menu

3. Add the new boot entry to the GRUB menu.

   # bootadm add-entry -P pool -i [entry-number] entry-title

4. Set the bootfs property for the newly added entry as follows:

   # bootadm change-entry -i new-entry-number bootfs='pool-name/ROOT/be-name'

   This step ensures that the newly added boot entry does not use the default bootfs value that is set in the root pool, which is specified in the bootfs pool-level property.

5. Verify that the boot entry was added.

   # bootadm list-menu

   ---

   Note - If you do not see your changes, check the grub.cfg file to verify that the change was made.

   ---

Example 2-8 x86: Adding a Boot Entry to the GRUB Menu

The following example shows how to add a menu entry to the GRUB menu by using the bootadm add-entry command. In this example, entry number 2 is added.

# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 2
console graphics
timeout 30
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1
# bootadm add-entry -i 2  Oracle Solaris 11_test
# bootadm change-entry -i 2 bootfs='rpool/ROOT/test'
# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 2
console graphics
timeout 30
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1
2 Oracle Solaris 11_test

View the contents of the new menu entry by specifying the entry number, as follows:

# bootadm list-menu -i 2
     the location of the boot loader configuration files is: /rpool/boot/grub
     title: Oracle Solaris 11_test
     kernel: /platform/i86pc/kernel/amd64/unix
     kernel arguments: -B $ZFS-BOOTFS
     boot archive: /platform/i86pc/amd64/boot_archive
     ZFS root pool: rpool

x86: How to Remove a Boot Entry From the GRUB Menu

Use the remove-entry subcommand of the bootadm command to remove a given entry, or a comma-separated list of entries, from the GRUB menu. If you specify multiple entries with the same title, all of the entries with that title are removed.

1. Assume the root role.

   See How to Use Your Assigned Administrative Rights in Oracle Solaris 11.1 Administration: Security Services.

2. (Optional) List the current boot entries.

   # bootadm list-menu

3. Remove the specified entry from the GRUB menu.

   # bootadm remove-entry [-P pool] [{entry-title [,entry-title...] |
       -i entry-number[,entry-number...]}

4. Verify that the entry has been removed.

   # bootadm list-menu

   ---

   Note - If you do not see your changes, check the grub.cfg file to verify that the change was made.

   ---

Example 2-9 x86: Removing a Boot Entry From the GRUB Menu

The following example shows the removal of entry number 2 from the GRUB menu.

# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 2
console graphics
timeout 30
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1
2 Oracle Solaris 11_test
bootadm remove-entry -i 2
1 entry removed
# bootadm list-menu
The location of the boot loader configuration file is /rpool/boot/grub
default 2
console graphics
timeout 30
0 Oracle Solaris 11/11
1 Oracle Solaris 11.1