path: root/usr/src/man/man1m/bootadm.1m

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.\" Copyright 2016 Toomas Soome <tsoome@me.com>
.\" Copyright 2018 OmniOS Community Edition (OmniOSce) Association.
.TH BOOTADM 1M "Jul 05, 2018"
.SH NAME
bootadm \- manage bootability of the operating system
.SH SYNOPSIS
.LP
.nf
\fB/sbin/bootadm\fR update-archive [\fB-vnf\fR] [\fB-R\fR \fIaltroot\fR [\fB-p\fR \fIplatform\fR]]
     [\fB-F \fIformat\fR]
.fi

.LP
.nf
\fB/sbin/bootadm\fR list-archive [\fB-vn\fR] [\fB-R\fR \fIaltroot\fR [\fB-p\fR \fIplatform\fR]]
.fi

.LP
.nf
\fB/sbin/bootadm\fR install-bootloader [\fB-Mfv\fR] [\fB-R\fR \fIaltroot\fR] [\fB-P\fR \fIpool\fR]
.fi

.LP
.nf
 x86 only
.fi

.LP
.nf
\fB/sbin/bootadm\fR set-menu [\fB-R\fR \fIaltroot\fR] \fIkey\fR=\fIvalue\fR
.fi

.LP
.nf
\fB/sbin/bootadm\fR list-menu [\fB-R\fR \fIaltroot\fR] [\fB-o\fR \fIkey\fR=\fIvalue\fR\fR]
.fi

.SH DESCRIPTION
.LP
The \fBbootadm\fR command manages the boot archive and, with x86 boot
environments, the boot loader menu. The
\fBupdate-archive\fR option provides a way for user to update the boot archive
as a preventative measure or as part of a recovery procedure. The
\fBset-menu\fR subcommand allows you to switch the \fBauto-boot\fR timeout and
default boot entry in the boot menu.
.sp
.LP
The \fBinstall-bootloader\fR subcommand installs the system boot loader on a
ZFS pool. If ZFS pool was not specified with the \fB-P\fR option, then the boot
loader is installed on the ZFS pool that the system booted from. If the
system did not boot from a ZFS pool (for example, it booted an installer via PXE
or CD-ROM) then the \fB-P\fR option is required.
.sp
This subcommand can be used to install, update, and repair the boot loader on a
ZFS pool intended for booting. When disks in the ZFS pool used for booting the
system have been replaced, one should run \fBbootadm install-bootloader\fR to
ensure that all disks in that pool have the system boot loader installed.
.sp
.LP
The \fBlist-menu\fR subcommand displays the location of the boot menu and the
current boot menu entries. The location of the boot menu list is
\fB/<boot pool root dataset mountpoint>/boot/menu.lst\fR.
Use the \fBlist-menu\fR subcommand to
locate the boot menu. See the EXAMPLES section for typical output from
the \fBlist-menu\fR option.
.sp
.LP
Note that OpenBoot PROM (OBP)-based machines, such as SPARC systems, use
PROM variables to set boot behavior and are managed by the \fBeeprom\fR(1M)
command.
.sp
.LP
The \fBbootadm\fR command determines dynamically the options supported by the
image to be managed, so that \fBbootadm\fR invoked on one platform can be used
to manage diskless clients of a different platform type.
.SH SUBCOMMANDS
.LP
The \fBbootadm\fR command has the following subcommands:
.sp
.ne 2
.na
\fB\fBupdate-archive\fR\fR
.ad
.sp .6
.RS 4n
Updates current boot archive if required. Applies to both SPARC and x86
platforms. The boot archive can be created in a number of different formats;
the default format is an IEEE/P1003 Data Interchange Standard cpio archive.
The format is configured through the following service management facility
(\fBsmf\fR(5)) property:
.sp
.in +2
.nf
svc:/system/boot-archive:default/config/format
.fi
.in -2

.sp
.LP
This property takes one of the following values:
.RS 8n

.sp
.ne 2
.na
\fBcpio\fR
.ad
.sp .6
.RS 4n
IEEE/P1003 Data Interchange Standard cpio archive (default).
.RE

.sp
.ne 2
.na
\fBhsfs\fR
.ad
.sp .6
.RS 4n
ISO 9660 filesystem image (only supported if \fI/usr/bin/mkisofs\fR is
available).
.RE

.sp
.ne 2
.na
\fBufs\fR
.ad
.sp .6
.RS 4n
UFS filesystem in which the files within are compressed using gzip if
\fI/usr/bin/gzip\fR is available.
.RE

.sp
.ne 2
.na
\fBufs-nocompress\fR
.ad
.sp .6
.RS 4n
UFS filesystem. The files within are not compressed but the resulting overall
boot archive will still be compressed if \fI/usr/bin/gzip\fR is available.
.RE
.RE

See \fBEXAMPLES\fR for how to change this value.

.RE

.sp
.ne 2
.na
\fB\fBlist-archive\fR\fR
.ad
.sp .6
.RS 4n
Lists the files and directories to be included in the boot archive. Applies to
both SPARC and x86 platforms.
.RE

.sp
.ne 2
.na
\fB\fBinstall-bootloader\fR\fR
.ad
.sp .6
.RS 4n
Applies platform specific method to install the system boot loader to the disks
that are part of the selected ZFS pool (either specified with \fB-P\fR or
the default).
.sp
On SPARC, the boot loader is installed in the boot area of the disk partition
used by the ZFS pool.
.sp
On x86, disks are formatted using either \fBMBR Partitioning\fR (Master Boot
Record) or using \fBGPT Partitioning\fR (GUID Partition Tables). The first
sector on the disk that is used by the \fBBIOS\fR to find a boot loader
is referred to as the \fBMBR\fR (Master Boot Record) and is always used
regardless of the partition scheme.
.sp
On x86, disks in a ZFS pool may be a combination of either type of partitioning
scheme.  If an entire disk was added to a ZFS pool (e.g. c0t0d0), then it was
formatted with \fBGPT\fR partitioning and the fact is recorded. The
\fBinstall-bootloader\fR subcommand will always update the system boot loader on
the disks. However, unless the entire disk was given a ZFS pool or the \fB-M\fR
option is specified, the \fBMBR\fR of the disk will not updated, as the system
cannot guarantee that the \fBMBR\fR belongs to it. If, for example, the system
was being dual booted, a different initial boot loader may be installed there.
.sp
To reinstall the boot loader on some or all of the disks, the \fB-f\fR option
must be passed to the \fBinstall-bootloader\fR subcommand to override boot
program version checks.
.RE

.sp
.ne 2
.na
\fB\fBset-menu\fR\fR
.ad
.sp .6
.RS 4n
Maintain the menu configuration. The index of menu entries is listed in the
\fBmenu.lst\fR file, and the actual configuration of the menu entry is located
in the boot environment \fB/boot\fR directory.
Applies to x86 platforms only.
.RE

.sp
.ne 2
.na
\fB\fBlist-menu\fR\fR
.ad
.sp .6
.RS 4n
Lists the location of the \fBmenu.lst\fR, as well as the current menu
entries. This listing includes the default entry, dataset name, and the
title of each entry. Applies to x86 platforms only.
.RE

.SH OPTIONS
.LP
The \fBbootadm\fR command has the following options:

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.sp .6
.RS 4n
In an \fBupdate-archive\fR operation, force re-generation of the boot-archive
even if no files have changed.

In an \fBinstall-bootloader\fR operation, override the boot loader versioning
constraints.
.RE

.sp
.ne 2
.na
\fB-F \fIformat\fR\fR
.ad
.sp .6
.RS 4n
In an \fBupdate-archive\fR operation, select the desired archive format. The
format can be any of the values shown above for the
svc:/system/boot-archive:default/config/format property.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.sp .6
.RS 4n
In an \fBupdate-archive\fR operation, archive content is checked but not
updated.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR\fR \fIkey\fR=\fIvalue\fR
.ad
.sp .6
.RS 4n
In a \fBlist-menu\fR operation, specify the menu entry for detailed inspection.
Possible keys are \fBentry\fR and \fBtitle\fR, taking either entry number or
title name as values.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIplatform\fR\fR
.ad
.sp .6
.RS 4n
The platform, or machine hardware class, of the client. The platform type can
only be specified together with \fB-R\fR, 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 \fBi86pc\fR, \fBsun4u\fR, or
\fBsun4v\fR.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
In an \fBupdate-archive\fR operation, stale files are displayed on stderr.
.sp
In an \fBinstall-bootloader\fR operation, display any output from tasks
performed.
.RE

.sp
.ne 2
.na
\fB\fB-M\fR\fR
.ad
.sp .6
.RS 4n
On x86 systems, in an \fBinstall-bootloader\fR operation, additionally installs
the system boot loader to the \fBMBR\fR (master boot record). For more
information, see the discussion of \fBinstall-bootloader\fR in the
\fBSUBCOMMANDS\fR section.
.sp
This option is not supported on non-x86 systems, and it is an error to specify
it.
.RE

.sp
.ne 2
.na
\fB-P\fR\ \fIpool\fR
.ad
.sp .6
.RS 4n
In an \fBinstall-bootloader\fR operation, the boot loader is installed on
the disks in the ZFS pool \fIpool\fR. If the \fB-P\fR option is not specified,
then the boot loader is installed on the ZFS pool that the system booted from.
If the system did not boot from a ZFS pool then the \fB-P\fR option is required.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR\ \fIaltroot\fR\fR
.ad
.sp .6
.RS 4n
Operation is applied to an alternate root path. In an \fBinstall-bootloader\fR
operation, the boot loader is still installed on the specified pool; however,
the boot loader itself will come from the alternate root.
.LP
Note -
.sp
.RS 2
The root file system of any non-global zones must not be referenced with the
\fB-R\fR 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 \fBzones\fR(5).
.RE
.RE

.sp
.ne 2
.na
\fB\fIkey\fR=\fIvalue\fR\fR
.ad
.sp .6
.RS 4n
Possible values are:
.sp
.ne 2
.na
\fB\fBdefault=\fR\fIentrynum\fR\fR
.ad
.sp .6
.RS 4n
The item number (for example, 0, 1, or 2) in the boot menu designating the
operating system to boot when the timer expires.
.RE

.sp
.ne 2
.na
\fB\fBtimeout=\fR\fIseconds\fR\fR
.ad
.sp .6
.RS 4n
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.
.RE

.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUpdating the Current Boot Archive
.sp
.LP
The following command updates the current boot archive:

.sp
.in +2
.nf
# bootadm update-archive
.fi
.in -2

.LP
\fBExample 2 \fRUpdating the Boot Archive on an Alternate Root
.sp
.LP
The following command updates the boot archive on an alternate root:

.sp
.in +2
.nf
# bootadm update-archive -R /a
.fi
.in -2

.LP
\fBExample 3 \fRListing Boot Menu Entries and Location of Boot Menu
.sp
.LP
The following command lists the boot environments and the location of the
\fBmenu.lst\fR:

.sp
.in +2
.nf
# bootadm list-menu
the location for the active menu is: /raid/boot/menu.lst
Index  Default  Dataset             Menu
0      -        raid/ROOT/test-182  test-182
1      -        raid/ROOT/test-183  test-183
2      *        raid/ROOT/test-184  test-184
.fi
.in -2

.LP
\fBExample 4 \fRSwitching Default Boot Entry
.sp
.LP
The following command refers to the menu displayed in the previous example. The
user selects test-183 (item 1).

.sp
.in +2
.nf
# bootadm set-menu default=1
.fi
.in -2

.LP
\fBExample 5 \fRChanging archive format
.sp
.LP
The following command changes the boot archive format to \fIufs\fR

.sp
.in +2
.nf
# svccfg -s system/boot-archive:default setprop config/format = ufs
# svcadm refresh system/boot-archive:default
# bootadm update-archive -f
.fi
.in -2

.LP
\fBExample 6 \fRDetailed information about menu entry.
.sp
.LP
The following command lists more detailed information about a boot menu entry:

.sp
.in +2
.nf
# bootadm list-menu -o entry=2
the location for the active menu is: /raid/boot/menu.lst

Title:       test-184
Timeout:     10
Console:     text
Bootfs:      raid/ROOT/test-184
Kernel:      /platform/i86pc/kernel/amd64/unix
Boot-args:   "-v"

Modules:
Name:        boot_archive
Path:        /platform/i86pc/${ISADIR}/boot_archive
Type:        rootfs
Status:      Load

Name:        boot_archive.hash
Path:        /platform/i86pc/${ISADIR}/boot_archive.hash
Type:        hash
Status:      Load

Name:        system
Path:        /boot/modules/etc/system
Type:        file
Hash:        4f4fe2d2dfae393a2a87ce29e3c71b803938c5fb
Flags:       name=etc/system
Status:      Load

.fi
.in -2

.SH EXIT STATUS
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.sp .6
.RS 4n
The command completed successfully.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.sp .6
.RS 4n
The command exited due to an error.
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.LP
\fBboot\fR(1M), \fBbeadm\fR(1M), \fBinstallboot\fR(1M), \fBattributes\fR(5)