Chapter 13 Managing the Oracle Solaris Boot Archives (Tasks)

This chapter describes how the Oracle Solaris boot archives are managed. Procedures for using the bootadm command are described in detail.

The following is a list of the information that is in this chapter:

• Managing the Oracle Solaris Boot Archives (Task Map)

• Description of the Oracle Solaris Boot Archives

• Managing the boot-archive Service

• Automatic Boot Archive Recovery

• Using the bootadm Command to Manage the Boot Archives

For overview information about the boot process, see Chapter 9, Shutting Down and Booting a System (Overview). For step-by-step instructions on booting a system, see Chapter 12, Booting an Oracle Solaris System (Tasks).

Managing the Oracle Solaris Boot Archives (Task Map)

Description of the Oracle Solaris Boot Archives

When you install Oracle Solaris OS on a system, the bootadm command creates one primary boot archive and one failsafe archive.

A primary boot archive is a subset of a root (/) file system. This boot archive contains all of the kernel modules, driver.conf files, and some configuration files. These files are located in the /etc directory. The files in the boot archive are read by the kernel before the root (/) file system is mounted. After the root (/) file system is mounted, the boot archive is discarded by the kernel from memory. Then, file I/O is performed against the root device.

The files that make up the SPARC boot archives are located in the /platform directory.

The contents of this directory are divided into three groups of files:

• Files that are required for a sun4u boot archive

• Files that are required for a sun4v boot archive

• Files that are required for a sun4us boot archive

The files that make up the x86 boot archives are located in the /platform/i86pc directory.

To list the files and directories that are included in the boot archives, use the bootadm list-archive command.

If any files in the archive are updated, the boot archive must be rebuilt. For modifications to take effect, the rebuild of the archive must take place before the next system reboot.

The failsafe boot archive is the second type of archive that is created when you install the Solaris OS.

A failsafe boot archive has the following benefits and characteristics:

• Is self-sufficient

• Can boot on its own

• Is created by default during installation of the OS

• Requires no maintenance

For more information about booting a system in failsafe mode, see Booting a SPARC Based System in Failsafe Mode and Booting an x86 Based System in Failsafe Mode.

Managing the boot-archive Service

The boot-archive service is controlled by the Service Management Facility (SMF). The boot-archive service instance is svc:/system/boot-archive:default. The svcadm command is used to enable and disable services.

To determine if the boot-archive service is running, use the svcs command.

For more information, see the svcadm(1M) and the svcs(1) man pages.

How to Enable or Disable the boot-archive Service

1. Become superuser or assume an equivalent role.

   Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services.

2. To enable or disable the boot-archive service, type:

   # svcadm enable | disable system/boot-archive

3. To verify the state of the boot-archive service, type:

   % svcs boot-archive

   If the service is running, the output displays an online service state.

   STATE STIME FMRI online 9:02:38 svc:/system/boot-archive:default

   If the service is not running, the output indicates the service is offline.

Troubleshooting

For information about clearing automatic boot archive update failures, see Automatic Boot Archive Recovery.

Automatic Boot Archive Recovery

Starting with the Oracle Solaris 10 9/10 release, boot archive recovery on the SPARC platform is fully automated. On the x86 platform, boot archive recovery is partially automated.

To support auto-recovery of the boot archives on the x86 platform, a new auto-reboot-safe property has been added to the boot configuration SMF service, svc:/system/boot-config:default. By default, this property's value is set to false, which prevents the system from automatically rebooting to an unknown boot device. However, if your system is configured to automatically reboot to the BIOS boot device and default GRUB menu entry that the Oracle Solaris OS is installed on, you can enable automatic recovery of the boot archives by setting this property's value to true. The following procedure describes how to clear automatic boot archive update failures on the x86 platform.

For information about how to clear automatic boot archive update failures by using the bootadm command, see How to Clear Automatic Boot Archive Update Failures by Using the bootadm Command.

x86: How to Clear Automatic Boot Archive Update Failures by Using the auto-reboot-safe Property

On an x86 based systems, during the process of booting the system, if a warning similar to the following is displayed, take action as described in the following procedure.

WARNING: Reboot required.
The system has updated the cache of files (boot archive) that is used
during the early boot sequence. To avoid booting and running the system
with the previously out-of-sync version of these files, reboot the
system from the same device that was previously booted.

The system then enters system maintenance mode.

1. Become superuser or assume an equivalent role.

   Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services.

2. Reboot the system.

   # reboot

   To prevent this type of failure, if the active BIOS boot device and the GRUB menu entries point to the current boot instance, do the following:

3. Set the auto-reboot-safe property of the svc:/system/boot-config SMF service to true, as follows:

   # svccfg -s svc:/system/boot-config:default setprop config/auto-reboot-safe = true

4. Verify that the auto-reboot-safe property is set correctly.

   # svccfg -s svc:/system/boot-config:default listprop |grep config/auto-reboot-safe config/auto-reboot-safe boolean true

How to Clear Automatic Boot Archive Update Failures by Using the bootadm Command

During the process of booting the system, if a warning message that is similar to the following is displayed, take action accordingly:

WARNING: Automatic update of the boot archive failed.
Update the archives using 'bootadm update-archive'
command and then reboot the system from the same device that
was previously booted.

The following procedure describes how to manually update an out-of-date boot archive by using the bootadm command.

1. Become superuser or assume an equivalent role.

   Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services.

2. To update the boot archive, type:

   # bootadm update-archive

   bootadm

   Manages the boot archives on a system.

   update-archive

   Updates the current boot archive, if required. Applies to both SPARC and x86 based systems.

3. Reboot the system.

   # reboot

Using the bootadm Command to Manage the Boot Archives

The /sbin/bootadm command enables you to perform the following tasks:

• Manually update the current boot archives on a system.

• List the files and directories that are included in the boot archives on a system.

• x86 only: Maintain the GRUB menu.

• x86 only: Locate the active GRUB menu, as well as the current GRUB menu entries.

The syntax of the command is as follows:

/sbin/bootadm [subcommand] [-option] [-R altroot]

For more information about the bootadm command, see the bootadm(1M) man page.

How to Manually Update the Boot Archive by Using the bootadm Command

1. Become superuser or assume an equivalent role.

   Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services.

2. To update the boot archive, type:

   # bootadm update-archive

   bootadm

   Manages the boot archives on a system.

   update-archive

   Updates the current boot archive, if required. Applies to both SPARC and x86 based systems.

   • To update the boot archive on an alternate root, type:

     # bootadm update-archive -R /a

     -R altroot

     Specifies an alternate root path to apply to the update-archive subcommand.

     ---

     Note –

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

     ---

3. Reboot the system.

   # reboot

How to Manually Update the Boot Archive on a Solaris Volume Manager RAID-1 (Mirrored) Root Partition

The following procedure describes how to mount a mirrored metadevice during a failsafe boot. In this procedure, the root (/) file system that is used is /dev/dsk/c0t0d0s0.

1. Boot the failsafe archive.

   • SPARC platform: From the ok prompt, type the following command:

     ok boot -F failsafe

     If the system is already running, open a terminal window, become superuser, and type the following command:

     # reboot -- "-F failsafe"

     For more information, see How to Boot a SPARC Based System in Failsafe Mode.

   • x86 platform: Boot the system by selecting the failsafe boot entry in the GRUB menu.

     For more information, see How to Boot an x86 Based System in Failsafe Mode.

   Booting the system in failsafe mode produces the following output:

   Starting shell. #

2. During the failsafe boot, when prompted by the system to select a device to mount, type q to indicate none.

   Please select a device to be mounted (q for none)[?,??,q]: q

3. Temporarily mount a submirror of the root (/) file system as read-only on the /a directory.

   # mount -o ro /dev/dsk/c0t0d0s0 /a

4. Copy the md.conf file to the /kernel/drv directory.

   # cp /a/kernel/drv/md.conf /kernel/drv/

5. Unmount the /a directory.

   # unmount /a

6. Use the devfsadm command to load the md driver.

   # update_drv -f md

   Running this command causes the configuration to be read, and the necessary devices to be created.

   ---

   Note –

   Before proceeding to the next step, wait a few seconds to ensure that the md driver has had time to load.

   ---

7. Use the metasync command to ensure that the root (/) file system is in sync. For example:

   # metasync d0

8. Mount the root mirror metadevice on the /a directory.

   # mount /dev/md/dsk/d0 /a

9. Update the boot archive of the device that you mounted in the previous step.

   # bootadm update-archive -v -R /a

   If the boot archive fails to be updated, or an error message is displayed, do the following:

   1. Update the timestamp on the md.conf file on the /a directory, which forces an update of the boot archive.

      # touch /a/kernel/drv/md.conf

   2. Update the boot archive by running the bootadm command.

      # bootadm update-archive -v -R /a

      The update of the boot archive takes a few minutes to complete. If the boot archive was updated successfully, a message similar to the following is displayed:

      changed /a/etc/system cannot find: /a/etc/cluster/nodeid: No such file or directory cannot find: /a/etc/devices/mdi_ib_cache: No such file or directory Creating ram disk on /a updating /a/platform/i86pc/boot_archive

10. Unmount /a.

    # unmount /a

11. Reboot the system.

How to List Contents of the Boot Archive

1. Become superuser or assume an equivalent role.

   Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services.

2. To list the files and directories that are included in the boot archive, type:

   # bootadm list-archive

   list-archive

   Lists the files and directories that are included in the boot archive or archives. Applies to both SPARC and x86 based systems.

x86: How to Locate the Active GRUB Menu and List Current Menu Entries

Use this procedure to determine the location of the active GRUB menu and to list current GRUB menu entries.

1. Become superuser or assume an equivalent role.

   Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services.

2. To list the location of the active GRUB menu and current GRUB menu entries, type:

   # bootadm list-menu

   list-menu

   Lists the location of the active GRUB menu, as well as the current GRUB menu entries. Information about the autoboot-timeout, the default entry number, and the title of each entry is included in this listing. Applies to x86 based systems only.

Example 13–1 Listing the Location of the Active GRUB Menu and Current 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

x86: How to Set the Default Boot Entry for the Active GRUB Menu

1. Become superuser or assume an equivalent role.

   Roles contain authorizations and privileged commands. For more information about roles, see Configuring RBAC (Task Map) in System Administration Guide: Security Services.

2. To set the default boot entry in the active GRUB menu, type:

   # bootadm set-menu menu-entry

   set-menu

   Maintains the GRUB menu. The location of the active GRUB menu is boot/grub/menu.lst. Applies to x86 bases systems only.

   menu-entry

   Specifies the GRUB menu entry to set as the default.

3. To verify default menu entry has been changed, type:

   # bootadm list-menu

   The new default menu entry should be displayed.

Example 13–2 Switching the GRUB Default Menu Entry

This example shows how to switch the default GRUB menu to one of the menu entries that is displayed in the previous example. The menu entry that is selected is The Linux, menu entry 2.

# bootadm set-menu default=2

See Also

For a description of the menu.lst file in each GRUB implementation, see x86: Supported GRUB Versions.