bootadm

- manage boot configuration

Synopsis

/usr/sbin/bootadm update-archive [-vn] [-R altroot [-p platform]]

/usr/sbin/bootadm list-archive [-vn] [-R altroot [-p platform]]

/usr/sbin/bootadm install-bootloader [-Mfv] [-P pool] [-R path]
     [device1 ... deviceN]

x86 only

/usr/sbin/bootadm set-menu [-P pool] [-R altroot [-p platform]]
     {key=value [key=value ...]}

/usr/sbin/bootadm list-menu [-P pool] [-R altroot [-p platform]]
     [[-i entry_number] | entry_title]

/usr/sbin/bootadm generate-menu [-P pool] [-f]

/usr/sbin/bootadm add-entry [-P pool] [-i entry_number] entry_title

/usr/sbin/bootadm change-entry [-P pool] {[entry_title[,entry_title...]
| -i entry_number[,entry_number]...]} {key=value [key=value ...]
| set-default }

/usr/sbin/bootadm remove-entry [-P pool] {[entry_title[,entry_title...]
| -i entry_number[,entry_number]...]}

Description

The bootadm command manages the boot archive and, with x86 boot environments, the GRUB (GRand Unified Bootloader) menu. For x86, both Legacy GRUB and GRUB2 are supported (but not concurrently).

The update–archive option provides a way for user to update the boot archive as a preventative measure or as part of a recovery procedure.

The set-menu subcommand allows you to switch the auto-boot timeout and default boot entry in the GRUB menu.

The list-menu subcommand displays the current GRUB menu entries, or, optionally, details about a specific entry identified by an index (if -i is used) or a title string (if -i is omitted).

The install-bootloader subcommand installs the system bootloader. It supersedes the functionality of installgrub(1M) on x86 and installboot(1M) on SPARC, as well as supporting installation of GRUB2's bootloader on x86.

The generate-menu subcommand provides a way to create a new menu configuration file for Solaris entries. If boot loader configuration files already exist, -f must be passed to force this subcommand to overwrite those files.

The add-entry, change-entry and remove-entry subcommands provide options to add, change, or remove an entry from the GRUB menu.

Note that OpenBoot PROM (OBP)-based machines, such as SPARC systems, do not use GRUB and have no boot menu manageable by bootadm.

The bootadm command determines dynamically the options supported by the image to be managed, so that bootadm invoked on one platform can be used to manage diskless clients of a different platform type.

SUBCOMMANDS

For the subcommands that support specifying entry_title, entry_title is a string that can be either double- or single-quoted.

An entry_number is a non-negative integer number representing the index of the menu entry in the GRUB menu.

The bootadm command has the following subcommands:

update-archive [-vn] [-R altroot [-p platform]]

Updates current boot archive if required. Applies to both SPARC and x86 platforms.

list-archive [-vn] [-R altroot [-p platform]]

Lists the files and directories to be included in the boot archive. Applies to both SPARC and x86 platforms.

set-menu [-vn] [-R altroot [-p platform]] {key=value [key=value]...}

Maintain the GRUB menu. A space-separated list of key-value pairs can be specified.

key=value

Possible values are:

default=entry_number

The entry number (for example, 0, 1, or 2) in the GRUB menu designating the operating system to boot when the timer expires.

timeout=seconds

The number of seconds before the operating system designated by the default item number is booted. If the value is -1, auto boot is disabled.

console=GRUB_console_type

Sets the type of console used for GRUB.

Possible values are:

'text'

Selects a high resolution console.

'graphics'

Selects a high resolution console which additionally leads to graphical boot. If BIOS console redirection is enabled, graphics must not be used to set console.

'serial'

Serial console for GRUB bootloader. Please see serial_params below for specific settings of serial parameters.

If BIOS console redirection is enabled, 'serial' must not be used to set console.

When a system is installed by booting with a serial console, that serial console will become the Solaris's kernel default console device. However, GRUB's console will not be changed to serial (it will be 'text').

serial_params='port[,speed[,databits[,parity[,stopbits[,flowcontrol]]]]]'

Specifies the serial parameters for the serial console.

port is a number specifying the serial port number.

speed is a number specifying the data rate for the connection in bits/second.

databits is the number of data bits in each character.

parity specifies the method for detecting transmission errors. Possible values are:

• N for no parity

• O for odd parity

• E for even parity

Values for parity are not case-sensitive.

stopbits specifies the stop bit sent for the character transmission. Possible values are 0 or 1.

flowcontrol specifies the flow control. Possible values are:

• H for hardware flow control

• S for software flow control

• N for no flow control

If serial_params is not set, the default is:

0,9600,8,N,1,N

...which makes the first serial port (COM1), using 9600 bits/sec baud rate, no parity checking, with databits of 8 bits per character, stop bit of 1, and no flow control to be the default.

quiet

Specifies whether printing informative messages to the console should be suppressed. By default its value is false.

Possible values are true or false.

splashimage

Specifies the path to the file used as an image to appear during boot.

foreground

Sets the foreground color. It is a string of hex values with a format of RRGGBB, where RR is for Red, GG for Green and BB for Blue.

background

Sets the background color. See foreground for possible values.

list-menu [-P pool] [-R altroot [-p platform]]

Lists the current GRUB menu entries. This includes the autoboot-timeout, the default entry number, and the title of each entry. Applies to x86 platforms only. If an entry title or entry index is supplied, details about that specific entry are printed.

generate-menu [-P pool]

Create a new menu configuration that contains only the Solaris entries currently installed on the system.

add-entry [-P pool] [-i entry_number] entry_title

Create a new entry in the menu with given entry title.

If entry_number is specified, the new entry will be inserted at the given position, or added as the last entry if the given entry_number is more than current number of entries.

change-entry [-P pool] {[entry_title[,entry_title...] | -i entry_number[,entry_number]...]} { key=value [ key=value ...] | set-default }

Modify the contents of a given entry or a comma-separated list of entries. An entry is specified either by an entry title or by an entry number. If there are multiple entries with the same title, all will be affected.

The special property, set-default, sets the entry to be the default entry to boot from when the timer expires. Only one entry in the subcommand can be specified when specifying this property.

A space separated list of key value pairs can be specified: key=value

Possible values are:

title=entry_title

The new title for the entry (or entries).

kernel=path_to_kernel

Path to the kernel. Example:

/platform/i86pc/kernel/amd64/unix

kargs=kernel_arguments

Argument or a list of arguments passed to kernel during boot. Please refer to kernel(1M) for possible options. If there are any spaces in the list, value of the key should be enclosed in quotes or double quotes.

boot_archive=path_to_boot_archive

The path to the boot archive.

bootfs=bootfs

The bootfs property value. Please refer to zpool(1M) for further information.

remove-entry [-P pool] [{entry_title [,entry_title...] | -i entry_number[,entry_number...]}

Remove a given entry or a comma-separated list of entries. If there are multiple entries with the same specified title, all will be removed.

install-bootloader [-Mfv] [-P pool] [-R path] [device1 ... deviceN]

Install the system bootloader. If a list of devices is specified, the bootloader will be installed only on the given devices. Otherwise the bootloader will be installed on a list of devices that is automatically extracted from system configuration.

The device is the name of a raw character device of a slice or partition on the disk on which the root file system resides.

Options

The bootadm command has the following options:

-f

In install-bootloader installation, forces the installation of the bootloader and bypasses any versioning checks for not downgrading the version of the bootloader on the system.

-i

Entry number or a list of comma-separated entry numbers to which to japply the specified operation.

-M [x86 systems with BIOS firmware only]

In an install-bootloader operation on x86 systems, installs the boot loader into the Master Boot Record (MBR), making it the system boot loader. The default (on systems with BIOS firmware) is to install the boot loader into the Partition Boot Record (PBR).

-n

In an update-archive operation, archive content is checked but not updated.

-P pool

The boot configuration associated with the specified pool to be used. When this option is not used, the current pool from which the system was booted is used for boot configuration.

-p platform

The platform, or machine hardware class, of the client. The platform type can only be specified together with -R, and is generally useful only for managing a diskless client where the client is of a different platform class than the server. Platform must be one of i86pc, sun4u, or sun4v.

-R altroot

Operation is applied to the path or alternate root path.

---

Note - The root file system of any non-global zones must not be referenced with the -R option. Doing so might damage the global zone's file system, might compromise the security of the global zone, and might damage the non-global zone's file system. See zones(5).

---

-v

In an update-archive operation, stale files are displayed on stderr. In an install-bootloader operation, enables verbose mode to print more information about the process.

Examples

Example 1 Updating the Current Boot Archive

The following command updates the current boot archive:

# bootadm update-archive

Example 2 Updating the Boot Archive on an Alternate Root

The following command updates the boot archive on an alternate root:

# bootadm update-archive -R /a

Example 3 Switching Default Boot Entry

The following command refers to the menu displayed in the previous example. The user selects Linux (item 2).

# bootadm set-menu default=2

or

# bootadm change-entry -i 2 set-default

Example 4 Listing GRUB Menu Entries

The following command lists the GRUB menu entries:

# bootadm list-menu
The location for the active GRUB menu is: /stubboot/boot/grub/menu.lst
default 0
timeout 10
0 Solaris10
1 Solaris10 failsafe
2 Linux

Example 5 Adding and Changing a Menu Entry

The following command adds a menu entry with the title “New Solaris Entry” at position 8 in the GRUB menu.

# bootadm  add-entry -i 8  "New Solaris Entry"

The following command changes the just-added entry with the kernel argument of -s to boot into level s.

# bootadm  change-entry "New Solaris Entry" kargs="-s"

Example 6 Installing Bootloader on a Second Root Pool

The following command installs the bootloader on the pool secondrpool.

# bootadm install-bootloader -P secondrpool

Example 7 Setting Foreground and Background Color

The following command sets the foreground color to be red and the background color to blue.

# bootadm set-menu splashimage=/boot/grub/splash.xpm.gz \
foreground=ff0000 background=0000ff

Exit Status

The following exit values are returned:

0

The command completed successfully.

1

The command exited due to an error.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

boot(1M), installboot(1M), installgrub(1M), kernel(1M), zpool(1M), attributes(5), grub(5)

Consult the GRUB home page, under:

http://www.gnu.org/