openSolaris 2008 - Using the bootadm Command to Manage the Boot Archives - System Administration Guide: Basic Administration

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

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

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

On the system that has an inconsistent boot archive, become superuser or assume an equivalent role.
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.
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.
Mount the primary submirror.
For example:
```
# mount /dev/dsk/c0t0d0s0 /a
```

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

Make a copy of the original vfstab file.
```
# cp /a/etc/vfstab /a/etc/vfstab.orig
```

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

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.

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.

Save the changes.

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.
Run the command to update the boot archive.
```
# bootadm update-archive -R /a
```
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.
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.
Reattach the submirror that was detached in the previous step.
```
# metattach mirror submirror
```
For example:
```
# metattach d10 d1
```
The mirror resynchronization begins.
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

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

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

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

Using the bootadm Command to Manage the Boot Archives