Go to main content

man pages section 1M: System Administration Commands

Exit Print View

Updated: July 2017



bootadm - manage boot configuration


/usr/sbin/bootadm update-archive [-v] [-f | -n] [-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]
/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 set-menu [-P pool] [-R altroot [-p platform]]
     {key=value [key=value ...]}
/usr/sbin/bootadm set-menu-password [-P pool] [-R altroot [-p platform]]
          [-f <path to file>] | -s] | [-r] | [-l -t [-i entry_number] | -g]
/usr/sbin/bootadm list-menu [-P pool] [-R altroot [-p platform]]
     [[-i entry_number] | entry_title]
/usr/sbin/bootadm use-batch -f file
/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] 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]...]}


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 userlisti –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 use-batch subcommand –f <file> executes bootadm instructions in the file supplied. This is most useful for setting password during installation from a manifest file.

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.

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 subcommmand 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 [–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.


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 Solaris's 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 exists in the list of authorized users.


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 [–p platform]] [–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 menuentry.

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.

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(1M) 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(1M) 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 [–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.

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:


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.


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


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 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 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
Example 8 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(5) for descriptions of the following attributes:

Interface Stability


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

See Also

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

Consult the GRUB home page, under: