Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, July 27, 2022



bootadm - manage boot configuration


/usr/sbin/bootadm update-archive [-v] [
-f | -n] [-R altroot]
/usr/sbin/bootadm list-archive [-vn] [-R altroot]
/usr/sbin/bootadm install-bootloader [-fv] [
-P pool] [-R 
     [device1 ... deviceN]
/usr/sbin/bootadm boot-pool {
     [{add|remove} [-P rpool] <device list>] |
     list [-P rpool] |
     resync [-P rpool] [-vA] [<BE_list>] |
     set [-P rpool] <param>=<value> ... }
x86 only
/usr/sbin/bootadm install-bootloader [-BGMfrsv] [-P pool] [-R path]
 	    [device1 ... deviceN]
/usr/sbin/bootadm set-menu [-P 
pool] [-R altroot]
     {key=value [
key=value ...]}
/usr/sbin/bootadm set-menu-password [-P pool] [-R altroot]
          [-f <path to file>] | -s] | [-r] | [-l -t [-i entry_number] | -g]
/usr/sbin/bootadm list-menu [-P 
pool] [-R altroot]
     [[-i entry_number] | 
/usr/sbin/bootadm generate-menu [-P 
pool] [-f]
/usr/sbin/bootadm show-entry [-P pool] <entry_name> | -i <index>
/usr/sbin/bootadm add-entry [-P 
pool] [-i entry_number] 
/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


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 set-menu-password subcommand sets the password to protect the GRUB menu from being seen. To set, use –f <path to file>; if –s is used, will prompt for the password twice; –r removes the password; –l lists whether there is a global menu password lock, and the menu entry userlist –l –t lists the menu entry userlist in parsable output; if –l –t –i <entry number>, list the userlist for that list of entry numbers in parsable output; if –l –t –g, list whether there is a global menu password lock in parsable output.

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 supporting installation of GRUB2's bootloader on x86.

When an active boot pool is present, bootable datasets are maintained, each corresponding to one boot environment and storing that boot environment's bootable artifacts (such as the boot_archive (x64 and SPARC platforms) and the UNIX kernel executable (x64 platforms only)). The boot-pool subcommand allows an administrator to manage aspects of the boot pool, including device membership (with the add/remove subcommands), manual synchronization of boot artifacts (with the resync subcommand), and setting boot pool attributes (with the set subcommand).

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 show-entry, add-entry, change-entry and remove-entry subcommands provide options to show, add, change, or remove an entry from the GRUB menu. The change-entry also provides options to add security protection to an entry.

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.


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 [–v] [–f | –n] [–R altroot]

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

list-archive [–vn] [–R altroot]

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

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

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


Possible values are:


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


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.


Sets the type of console used for GRUB.

Possible values are:


Selects a high resolution console.


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 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 Oracle Solaris' kernel default console device. However, GRUB's console will not be changed to serial (it will be 'text').


Adds or deletes the username to the list of authorized user. Will prompt for the password twice. Password is stored in hashed form. Username does not have to be the same as the Solaris username.

[auth-file]=<file path>

Adds username and password in <file path> to the list of authorized users. <file path> is a file with <username>=<password> pairs.


Adds or deletes username to the list of superusers. Username must already exist in the list of authorized users.

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:


...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.


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

Possible values are true or false.


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


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.


Sets the background color. See foreground for possible values.

set-menu-password [–R altroot] [–f <path to file> | –s] [–r]
[–l –t [–i entry_number[,entry_number]...]|–g]

Sets and deletes the password to protect the GRUB menu from being seen. Also, lists whether the entire GRUB menu password is set and the userlist for each menu entry.

list-menu [–P pool] [–R altroot]

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.

bootadm show-entry [–P pool] <entry_name> | –i <index>

Show the entry found by name <entry_name> or index from the menu. Both entry_name and index may also be a comma-separated list of entries/indices.

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:


The new title for the entry (or entries).


Path to the kernel. Example:


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


The path to the boot archive.


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


Grant or ungrant username the privilege to boot an entry title or entry index.

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 [–BGMfrsv] [–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.

x86 with legacy BIOS firmware only

By default, the bootloader and MBR are installed on the primary boot disk. This is the same as specifying –M and –f (–fM).

To disable installation of the MBR, the –B option must be specified.

To disable installation of bootloader, the –G option must be specified.

x86 with UEFI firmware only

By default, the Secure Boot is disabled.

To install the Secure Boot, use the –s option.

To uninstall the Secure Boot, use the –r option.

Note -  After the uninstall operation, disable the Secure Boot in the UEFI BIOS setup on reboot.
boot-pool {
[{add|remove} [–P rpool] <device list>] |
list [–P rpool] |
resync [–P rpool] [-vA] [<BE_list>] |
set [–P rpool] <param>=<value> ... }

The boot-pool subcommand manipulates the active boot pool (if the system was installed with a boot pool enabled). Certain platform define the set of devices that should be included in the boot pool. Others may require the administrator to select a set of devices at installation time to comprise the boot pool. After installation, the set of devices in the boot pool can be changed and inspected, and the behavior of the boot pool can be changed. Each device in the boot pool will be automatically re-added to the pool if it is faulted and subsequently replaced, so as long as the set of devices in the boot pool is specified, no administrator interaction is required when the pool is rebuilt when devices are replaced.

Each subcommand accepts the –P argument where a root pool can be specifically selected.

If no –P argument is given, the root pool is derived from the pool on which the root filesystem's dataset is located.

add [–P rpool] <device list>

Adds devices to the boot pool. Devices are added immediately. It's essential that any system restart be deferred until the newly-added devices are resilvered to ensure they can be independently bootable (since the boot pool is a mirror, the boot loader is installed onto each device in the mirror AFTER the resilvering process is complete.)

remove [–P rpool] <device list>

Removes devices from the boot pool immediately.

list [–P rpool]

Outputs details regarding the boot pool's configuration and settings.

resync [–P rpool] [-vA] {<BE_list>}

Resynchronize the boot pool (rebuilding it, if necessary, using the set of devices previously configured) and creates bootable datasets on the boot pool for the specified boot environment(s) (if any). Command options are as follows:


Repopulates the entire boot pool with the most recently booted/created boot environments.


Verbose output during the resynchronization

set [–P rpool] <param>=<value> ...

Sets the specified boot pool parameter to the specified value.

The following parameter is supported:


The eviction_algorithm can have either none or lru as its value. By default, the value is set to lru.

When eviction_algorithm is set to none and a boot environment's bootable files need to be copied to the boot pool, if there is insufficient space on the boot pool, the copy operation will fail. NOTE that the boot pool will not be allowed to exceed 85% of its maximum capacity to ensure maximum system performance.

When eviction_algorithm is set to lru, the bootable datasets that correspond to the least recently-used boot environments will be evicted until sufficient space exists for the copy operation to succeed. Note that the noevict BE policy (settable on a per-BE basis changes this behavior and stops those BEs from being evicted (if enough BEs are marked noevict, it's possible for bootable dataset creation to fail, since the system would not be able to find enough free space by evicting datasets.))


The bootadm command has the following options:


For update-archive, forces an update to the boot archive, even if that archive is current.

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. This is the default behavior.

–B [x86 systems with legacy BIOS firmware only]

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


For install-bootloader installation, do not install the bootloader. Also, you must do versioning check for the bootloader on the system.


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

–M [x86 systems with legacy BIOS firmware only]

This is the default behavior in an install-bootloader operation on x86 systems with legacy BIOS firmware. By default, install the boot loader into the Master Boot Record (MBR), making it the system boot loader. This option is obsolete and may be removed in a future release.


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.

–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(7).
–v verbose mode

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.


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


# 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 Showing a Menu Entry

The following command shows the information of a menu entry with the title "Solaris10".

# bootadm show-entry "Solaris10"

The following command shows the information of entries at position 0 and 2 in the GRUB menu.

# bootadm show-entry -i 0,2
Example 6 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 7 Installing Bootloader on a Second Root Pool

The following command installs the bootloader on the pool secondrpool.

# bootadm install-bootloader -P secondrpool
Example 8 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
Example 9 Showing information about the active boot pool
# bootadm boot-pool list
Boot pool name: bpool
Parameters: eviction_algorithm=lru
Current: /dev/dsk/c1t0d0, /dev/dsk/c1t1d0
Pending: /dev/dsk/c1t0d0, /dev/dsk/c1t1d0
Platform-specified devices excluded: /dev/dsk/c1t2d0
Platform-specified (auto-added, unless excluded): /dev/dsk/c1t0d0,

In this example, the platform has specified three boot pool devices, but the system is using only two of them. The list of current boot pool devices is identical to the list of pending boot pool devices, so no boot pool membership changes are pending. Note that if there is no active boot pool, the following output would have been returned:

bootadm: Boot pool operations are not applicable to root pool rpool.

Exit Status

The following exit values are returned:


The command completed successfully.


The command exited due to an error.


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

Interface Stability


bootadm defaults to /var/tmp to store temporary files, regardless of TMPDIR settings.

See Also

attributes(7), grub(7), boot(8), kernel(8), zpool(8)