Chapter 14 Managing the Solaris Boot Archives (Tasks)

This chapter describes boot archive management in the Solaris OS. Procedures for using the bootadm command are described in detail.

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

• Managing the Solaris Boot Archives (Task Map)

• Description of the Solaris Boot Archives

• Managing the boot-archive Service

• 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 a Solaris System (Tasks).

Managing the Solaris Boot Archives (Task Map)

Description of the Solaris Boot Archives

When you install the 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, in addition to a few 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.

If you are running a Solaris Express release on an x86 based system, two primary boot archives (one 32-bit archive and one 64-bit archive) are created at installation time. The 32-bit archive is located in /platform/i86pc/boot_archive. The 64-bit archive is located in /platform/i86pc/amd64/boot_archive.

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.

If you are running the Solaris Express release, the contents of this directory are divided into two groups of files:

• 32-bit boot archive files, which are located in /platform/i86pc/boot_archive

• 64-bit boot archive files, which are located in /platform/i86pc/amd64/boot_archive

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 the Failsafe Archive on a SPARC Based System and Booting the Failsafe Archive on an x86 Based System.

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

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 updating the boot archive by clearing the boot-archive service, see How to Update an Inconsistent Boot Archive by Clearing the boot-archive Service.

How to Update an Inconsistent Boot Archive by Clearing the boot-archive Service

The boot-archive service, svc:/system/boot-archive, is managed by SMF. This procedure shows how to update the boot archive when an inconsistent archive is detected during the boot process. Clearing the service works the same as running the boot -F failsafe command. Note that when you use this method to update the boot archives, there is no need to boot the failsafe archive or run the bootadm update-archive command. This command runs silently after the boot-archive service has been cleared.

The preferred method for correcting an inconsistent boot archive is to boot the system in failsafe mode. See the following references for instructions on booting the failsafe archive:

For SPARC based systems, see Booting a SPARC Based System From the Network.

For x86 based systems, see Booting the Failsafe Archive on an x86 Based System.

1. During the process of booting the system, if a warning similar to the following is displayed, ignore the warning.

   WARNING: The following files in / differ from the boot archive: changed file-name

   The system will enter system maintenance mode.

2. Clear the boot-archive service by typing the following command:

   # svcadm clear system/boot-archive

   After this command is run, the bootadm update-archive command runs silently. If the boot archive is updated successfully, the system is rebooted.

3. Verify the service is running.

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

Example 14–1 SPARC: Updating an inconsistent Boot Archive by Clearing the Boot-Archive Service

screen not found.
Can't open input device.
Keyboard not present.  Using ttya for input and output.

Sun Enterprise 220R (2 X UltraSPARC-II 450MHz), No Keyboard
OpenBoot 3.23, 1024 MB memory installed, Serial #13116682.
Ethernet address 8:0:20:c8:25:a, Host ID: 80c8250a.



Rebooting with command: boot                                          
Boot device: /pci@1f,4000/scsi@3/disk@1,0:a  File and args: 
SunOS Release 5.10 64-bit
Copyright 1983-2007 Sun Microsystems, Inc.  All rights reserved.
Use is subject to license terms.
DEBUG enabled
misc/forthdebug (507204 bytes) loaded
Hostname: marnie

WARNING: The following files in / differ from the boot archive:

    changed /kernel/drv/sd.conf

The recommended action is to reboot to the failsafe archive to correct
the above inconsistency. To accomplish this, on a GRUB-based platform,
reboot and select the "Solaris failsafe" option from the boot menu.
On an OBP-based platform, reboot then type "boot -F failsafe". Then
follow the prompts to update the boot archive. Alternately, to continue
booting at your own risk, you may clear the service by running:
"svcadm clear system/boot-archive"

Nov 21 15:47:20 svc.startd[100004]: svc:/system/boot-archive:default: Method 
"/lib/svc/method/boot-archive" failed with exit status 95.
Nov 21 15:47:20 svc.startd[100004]: system/boot-archive:default failed fatally: 
transitioned to maintenance (see 'svcs -xv' for details)
Requesting System Maintenance Mode
(See /lib/svc/share/README for more information.)
Console login service(s) cannot run

Root password for system maintenance (control-d to bypass): 
single-user privilege assigned to /dev/console.
Entering System Maintenance Mode

Nov 21 15:48:36 su: 'su root' succeeded for root on /dev/console
Sun Microsystems Inc.   SunOS 5.10, 
2007
.
.
.# 
# 
# svcadm clear system/boot-archive
# 
# NIS domain name is mpklab.sfbay.sun.com
/dev/rdsk/c0t1d0s5 is clean
Reading ZFS config: done.
#
# bootadm update-archive
# svcs boot-archive
STATE          STIME    FMRI
online          9:02:38 svc:/system/boot-archive:default

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

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

     ---

How to Manually Update the Boot Archive on a RAID-1 (Mirror) Volume

This procedure applies to updating the boot archive on RAID-1 (mirror) volumes that are created and maintained by using Solaris Volume Manager (SVM).

If the boot archive and the root (/) file system become inconsistent, an error message is displayed when you boot the system. Typically, the recommended action is to boot the system in failsafe mode, then run the bootadm update-archive command to update the boot archives. However, if the root (/) file system is a mirrored metadevice (RAID-1 volume), this method fails to successfully update the boot archive.

When you boot the system in failsafe mode, a message similar to the following is displayed:

Searching for installed OS instances...
/dev/dsk/c0t0d0s0 is under md control, skipping.
/dev/dsk/c1t3d0s0 is under md control, skipping.
No installed OS instance found.

This message indicates the metadevice was skipped. To manually update the boot archives, follow the steps that are described in the following procedure.

1. On the system that has an inconsistent boot archive, become superuser or assume an equivalent role.

2. Boot the failsafe archive.

   • On a SPARC based system, type:

     # reboot -- "-F failsafe"

     To boot the failsafe archive from the ok prompt, type:

     ok boot -F failsafe

     For more information, see How to Boot the Failsafe Archive on a SPARC Based System.

   • On an x86 based system, boot the system, then select the failsafe boot entry in the GRUB menu.

     For more information, see How to Boot the Failsafe Archive on an x86 Based System by Using GRUB.

   The system boots in failsafe mode, searches for installed OS instances, then returns the message previously described, “No installed OS instance found”. After the boot sequence completes, the command prompt is displayed.

3. Use the metastat command to determine the primary submirror.

   # metastat -p

   -p

   Displays a list of active metadevices and hot spare pools.

   The -p output is designed for taking a snapshot of the configuration for later recovery or setup.

   For example:

   # metastat -p d10 -m d0 d1 1 d0 1 1 c0t0d0s0 d1 1 1 c1t3d0s0

   In the previous output, d0 and d1 are submirrors of d10. The primary submirror, which is typically listed first, is d0.

4. Mount the primary submirror.

   For example:

   # mount /dev/dsk/c0t0d0s0 /a

5. Temporarily update the /etc/vfstab file to use a single root (/) partition.

   1. Make a copy of the original vfstab file.

      # cp /a/etc/vfstab /a/etc/vfstab.orig

   2. Using a text editor, edit the vfstab file as follows:

      1. Comment out the line for the root (/) mirror metadevice.

         #device device mount FS fsck mount mount #to mount to fsck point type pass at boot options # . . . #/dev/md/dsk/d10 /dev/md/rdsk/d10 / ufs 1 no -

         In the previous example, the line, /dev/md/dsk/d10, was commented out.

      2. Add a new line for the disk device of the primary submirror.

         #device device mount FS fsck mount mount #to mount to fsck point type pass at boot options # . . . #/dev/md/dsk/d10 /dev/md/rdsk/d10 / ufs 1 no - /dev/dsk/c0t0d0s0 /dev/rdsk/c0t0d0s0 / ufs 1 no - . . .

         In the previous example, a new line for the disk device of the primary submirror, /dev/dsk/c0t0d0s0, was added.

   3. Save the changes.

6. To prevent the system from attempting to boot from the metadevice, temporarily update the /etc/system file as follows:

   1. Make a copy of the original /etc/system file.

      # cp /a/etc/system /a/etc/system.orig

   2. Using a text editor, edit the /etc/system file, commenting out the rootdev line. This line is located between the Begin MDD root and the End MDD root lines.

      * Begin MDD root info (do not edit) # rootdev:/pseudo/md@0:0,0,blk * End MDD root info (do not edit)

   3. Save the changes.

7. Run the command to update the boot archive.

   # bootadm update-archive -R /a

8. Unmount the primary submirror, then reboot the system.

   # umount /a # shutdown -i 6

   • If the system still does not boot normally, reboot the failsafe archive and check the /etc/vfstab and the /etc/system files to make sure the information is correct.

9. After the system has successfully rebooted, rebuild the metadevice:

   1. Identify the name of the root (/) mirror metadevice from the vfstab file.

      The name of the metadevice is the line that was commented out in Step 5.

   2. Display the components of the mirror by using the metastat command.

      For example:

      # metastat -p d10 -m d0 d1 1 d0 1 1 c0t0d0s0 d1 1 1 c1t3d0s0

   3. Detach the faulty submirror.

      # metadetach mirror submirror

      For example:

      # metadetach d10 d1

   4. Replace the existing copy of the /etc/vfstab file with the original file.

      # cp /a/etc/vfstab.orig /a/etc/vfstab

   5. Replace the existing copy of the /etc/system file with the original file.

      # cp /a/etc/system.orig /a/etc/system

   6. Reboot the system.

      # shutdown -i 6

   After the system reboots, the mirrored root (/) partition is restored on the metadevice.

10. Reattach the submirror that was detached in the previous step.

    # metattach mirror submirror

    For example:

    # metattach d10 d1

    The mirror resynchronization begins.

11. To check the status of the resynchronization process, use the metastat command:

    # metastat | grep `Resync in progress'

    When no output is returned, the process is finished.

Example 14–2 SPARC: Manually Updating the Boot Archive on a RAID-1 (Mirror) Volume

This example shows the steps for manually updating the boot archive on a system with an SVM root (/) mirrored metadevice. The system that was used for this example is a SPARC based system running the Solaris 10 10/08 FCS release.

SunOS Release 5.10 Version Generic_137137-09 64-bit
Copyright 1983-2008 Sun Microsystems, Inc.  All rights reserved.
Use is subject to license terms.
WARNING: Unexpected EOF on line 14 of /kernel/drv/md.conf
Hostname: pilgrim1

WARNING: The following files in / differ from the boot archive:

    changed /kernel/drv/md.conf

The recommended action is to reboot to the failsafe archive to correct
the above inconsistency. To accomplish this, on a GRUB-based platform,
reboot and select the "Solaris failsafe" option from the boot menu.
On an OBP-based platform, reboot then type "boot -F failsafe". Then
follow the prompts to update the boot archive. Alternately, to continue
booting at your own risk, you may clear the service by running:
"svcadm clear system/boot-archive"

Sep 18 15:22:06 svc.startd[7]: svc:/system/boot-archive:default: 
Method "/lib/svc/method/boot-archive" failed with exit status 95.
Sep 18 15:22:06 svc.startd[7]: system/boot-archive:default
failed fatally: transitioned to maintenance (see 'svcs -xv' for details)
Requesting System Maintenance Mode
(See /lib/svc/share/README for more information.)
Console login service(s) cannot run

Root password for system maintenance (control-d to bypass):
single-user privilege assigned to /dev/console.
Entering System Maintenance Mode

Sep 18 15:22:18 su: 'su root' succeeded for root on /dev/console
Sun Microsystems Inc.    SunOS 5.10  Generic  January 2005
# reboot -- "-F failsafe"
syncing file systems... done
rebooting...
Resetting ...
Rebooting with command: boot -F failsafe
Boot device: /pci@1f,4000/scsi@3/disk@0,0:a  File and args: -F failsafe
SunOS Release 5.10 Version Generic_137137-08	 64-bit
Copyright 1983-2008 Sun Microsystems, Inc.  All rights reserved.
Use is subject to license terms.
Configuring devices.
Searching for installed OS instances...
/dev/dsk/c0t0d0s0 is under md control, skipping.
/dev/dsk/c1t3d0s0 is under md control, skipping.
No installed OS instance found.

Starting shell.

pilgrim1# metastat -p
d10 -m d0 d1 1
d0 1 1 c0t0d0s0
d1 1 1 c1t3d0s0

# mount /dev/dsk/c0t0d0s0 /a
# cp /a/etc/vfstab /a/etc/vfstab.orig
# vi /a/etc/vfstab

<< input changes to vfstab file, then save changes >>

# cp /a/etc/system /a/etc/system.orig
# vi /a/etc/system

<< input changes to /etc/system file, then save changes >>

# bootadm update-archive -R /a
Creating boot_archive for /a
updating /a/platform/sun4u/boot_archive
15+0 records in
15+0 records out
# umount /a
# shutdown -i 6

<< reboot the system >>

Rebooting with command: boot
Boot device: /pci@1f,4000/scsi@3/disk@0,0:a  File and args:
SunOS Release 5.10 Version Generic_137137-08  64-bit
Copyright 1983-2008 Sun Microsystems, Inc.  All rights reserved.
Use is subject to license terms.
[...]
# metastat -p d10
# metadetach d10 d1
# cp /a/etc/vfstab.orig /a/etc/vfstab
# cp /a/etc/system.orig /a/etc/system
# shutdown -i 6

<< reboot the system >>

Rebooting with command: boot
Boot device: /pci@1f,4000/scsi@3/disk@0,0:a  File and args:
SunOS Release 5.10 Version Generic_137137-08 64-bit
Copyright 1983-2008 Sun Microsystems, Inc.  All rights reserved.
Use is subject to license terms.
[...]
# metattach d10 d1
# metastat | grep 'Resync in progress'
    Resync in progress: 4 % done
# metastat | grep 'Resync in progress'

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 14–3 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 14–4 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 Implementations.