Merge remote-tracking branch 'origin/master'

[unleashed/lotheac.git] / share / man / man8 / boot.8

'\" te
.\" Copyright 2018 OmniOS Community Edition (OmniOSce) Association.
.\" Copyright 2015 Nexenta Systems Inc.
.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 1989 AT&T
.\" 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]
.TH BOOT 8 "Jul 20, 2018"
.SH NAME
boot \- start the system kernel or a standalone program
.SH SYNOPSIS
.SS "SPARC"
.LP
.nf
\fBboot\fR [\fIOBP\fR \fInames\fR] [\fIfile\fR] [\fB-aLV\fR] [\fB-F\fR \fIobject\fR] [\fB-D\fR \fIdefault-file\fR]
     [\fB-Z\fR \fIdataset\fR] [\fIboot-flags\fR] [\fB\(mi\(mi\fR] [\fIclient-program-args\fR]
.fi

.SS "x86"
.LP
.nf
\fBboot\fR [\fIboot-flags\fR] [\fB-B\fR \fIprop\fR=\fIval\fR [,\fIval\fR...]]
.fi

.SH DESCRIPTION
.LP
Bootstrapping is the process of loading and executing a standalone program. For
the purpose of this discussion, bootstrapping means the process of loading and
executing the bootable operating system. Typically, the standalone program is
the operating system kernel (see \fBkernel\fR(8)), but any standalone program
can be booted instead. On a SPARC-based system, the diagnostic monitor for a
machine is a good example of a standalone program other than the operating
system that can be booted.
.sp
.LP
If the standalone is identified as a dynamically-linked executable, \fBboot\fR
will load the interpreter (linker/loader) as indicated by the executable format
and then transfer control to the interpreter. If the standalone is
statically-linked, it will jump directly to the standalone.
.sp
.LP
Once the kernel is loaded, it starts the UNIX system, mounts the necessary file
systems (see \fBvfstab\fR(4)), and runs \fB/sbin/init\fR to bring the system to
the "initdefault" state specified in \fB/etc/inittab\fR. See \fBinittab\fR(4).
.SS "SPARC Bootstrap Procedure"
.LP
On SPARC based systems, the bootstrap procedure on most machines consists of
the following basic phases.
.sp
.LP
After the machine is turned on, the system firmware (in PROM) executes power-on
self-test (POST). The form and scope of these tests depends on the version of
the firmware in your system.
.sp
.LP
After the tests have been completed successfully, the firmware attempts to
autoboot if the appropriate flag has been set in the non-volatile storage area
used by the firmware. The name of the file to load, and the device to load it
from can also be manipulated.
.sp
.LP
These flags and names can be set using the \fBeeprom\fR(8) command from the
shell, or by using \fBPROM\fR commands from the \fBok\fR prompt after the
system has been halted.
.sp
.LP
The second level program is either a filesystem-specific boot block (when
booting from a disk), or \fBinetboot\fR (when booting across
the network).
.sp
.LP
Network Booting
.sp
.LP
Network booting occurs in two steps: the client first obtains an IP address and
any other parameters necessary to permit it to load the second-stage booter.
The second-stage booter in turn loads the boot archive from the boot device.
.sp
.LP
An IP address can be obtained in one of three ways: RARP, DHCP, or manual
configuration, depending on the functions available in and configuration of the
PROM. Machines of the \fBsun4u\fR and \fBsun4v\fR kernel architectures have
DHCP-capable PROMs.
.sp
.LP
The boot command syntax for specifying the two methods of network booting are:
.sp
.in +2
.nf
boot net:rarp
boot net:dhcp
.fi
.in -2
.sp

.sp
.LP
The command:
.sp
.in +2
.nf
boot net
.fi
.in -2
.sp

.sp
.LP
without a \fBrarp\fR or \fBdhcp\fR specifier, invokes the default method for
network booting over the network interface for which \fBnet\fR is an alias.
.sp
.LP
The sequence of events for network booting using RARP/\fBbootparams\fR is
described in the following paragraphs. The sequence for DHCP follows the
RARP/\fBbootparams\fR description.
.sp
.LP
When booting over the network using RARP/\fBbootparams\fR, the PROM begins by
broadcasting a reverse ARP request until it receives a reply. When a reply is
received, the PROM then broadcasts a TFTP request to fetch the first block of
\fBinetboot\fR. Subsequent requests will be sent to the server that initially
answered the first block request. After loading, \fBinetboot\fR will also use
reverse ARP to fetch its IP address, then broadcast \fBbootparams\fR RPC calls
(see \fBbootparams\fR(4)) to locate configuration information and its root file
system. \fBinetboot\fR then loads the boot archive by means of NFS and
transfers control to that archive.
.sp
.LP
When booting over the network using DHCP, the PROM broadcasts the hardware
address and kernel architecture and requests an IP address, boot parameters,
and network configuration information. After a DHCP server responds and is
selected (from among potentially multiple servers), that server sends to the
client an IP address and all other information needed to boot the client.
Next, the PROM downloads
\fBinetboot\fR, loads that file into memory, and executes it. \fBinetboot\fR
loads the boot archive, which takes over the machine and releases
\fBinetboot\fR. Startup scripts then initiate the DHCP agent (see
\fBdhcpagent\fR(8)), which implements further DHCP activities.

.SS "iSCSI Boot"
.LP
iSCSI boot is currently supported only on x86. The host being booted must be
equipped with NIC(s) capable of iBFT (iSCSI Boot Firmware Table) or have the
mainboard's BIOS be iBFT-capable. iBFT, defined in the Advanced Configuration
and Power Interface (ACPI) 3.0b specification, specifies a block of information
that contains various parameters that are useful to the iSCSI Boot process.
.sp
.LP
Firmware implementing iBFT presents an iSCSI disk in the BIOS during startup as
a bootable device by establishing the connection to the iSCSI target. The rest
of the process of iSCSI booting is the same as booting from a local disk.
.sp
.LP
To configure the iBFT properly, users need to refer to the documentation from
their hardware vendors.
.SS "Booting from Disk"
.LP
When booting from disk, the OpenBoot PROM firmware reads the boot blocks from
blocks 1 to 15 of the partition specified as the boot device. This standalone
booter usually contains a file system-specific reader capable of reading the
boot archive.
.sp
.LP
If the pathname to the standalone is relative (does not begin with a slash),
the second level boot will look for the standalone in a platform-dependent
search path. This path is guaranteed to contain
\fB/platform/\fR\fIplatform-name\fR. Many SPARC platforms next search the
platform-specific path entry \fB/platform/\fR\fIhardware-class-name\fR. See
\fBfilesystem\fR(5). If the pathname is absolute, \fBboot\fR will use the
specified path. The \fBboot\fR program then loads the standalone at the
appropriate address, and then transfers control.
.sp
.LP
Once the boot archive has been transferred from the boot device, Solaris can
initialize and take over control of the machine. This process is further
described in the "Boot Archive Phase," below, and is identical on all
platforms.
.sp
.LP
If the filename is not given on the command line or otherwise specified, for
example, by the \fBboot-file\fR NVRAM variable, \fBboot\fR chooses an
appropriate default file to load based on what software is installed on the
system and the capabilities of the hardware and firmware.
.sp
.LP
The path to the kernel must not contain any whitespace.
.SS "Booting from ZFS"
.LP
Booting from ZFS differs from booting from UFS in that, with ZFS, a device
specifier identifies a storage pool, not a single root file system. A storage
pool can contain multiple bootable datasets (that is, root file systems).
Therefore, when booting from ZFS, it is not sufficient to specify a boot
device. One must also identify a root file system within the pool that was
identified by the boot device. By default, the dataset selected for booting is
the one identified by the pool's \fBbootfs\fR property. This default selection
can be overridden by specifying an alternate bootable dataset with the \fB-Z\fR
option.
.SS "Boot Archive Phase"
.LP
The boot archive contains a file system image that is mounted using an
in-memory disk. The image is self-describing, specifically containing a file
system reader in the boot block. This file system reader mounts and opens the
RAM disk image, then reads and executes the kernel contained within it. By
default, this kernel is in:
.sp
.in +2
.nf
/platform/`uname -i`/kernel/unix
.fi
.in -2
.sp

.sp
.LP
If booting from ZFS, the pathnames of both the archive and the kernel file are
resolved in the root file system (that is, dataset) selected for booting as
described in the previous section.
.sp
.LP
The initialization of the kernel continues by loading necessary drivers and
modules from the in-memory filesystem until I/O can be turned on and the root
filesystem mounted. Once the root filesystem is mounted, the in-memory
filesystem is no longer needed and is discarded.
.SS "OpenBoot PROM \fBboot\fR Command Behavior"
.LP
The OpenBoot \fBboot\fR command takes arguments of the following form:
.sp
.in +2
.nf
ok boot [\fIdevice-specifier\fR] [\fIarguments\fR]
.fi
.in -2
.sp

.sp
.LP
The default \fBboot\fR command has no arguments:
.sp
.in +2
.nf
ok boot
.fi
.in -2
.sp

.sp
.LP
If no \fIdevice-specifier\fR is given on the \fBboot\fR command line, OpenBoot
typically uses the \fIboot-device\fR or \fIdiag-device\fR \fBNVRAM\fR variable.
If no optional \fIarguments\fR are given on the command line, OpenBoot
typically uses the \fIboot-file\fR or \fIdiag-file\fR \fBNVRAM\fR variable as
default \fBboot\fR arguments. (If the system is in diagnostics mode,
\fIdiag-device\fR and \fIdiag-file\fR are used instead of \fIboot-device\fR and
\fIboot-file\fR).
.sp
.LP
\fIarguments\fR may include more than one string. All \fIargument\fR strings
are passed to the secondary booter; they are not interpreted by OpenBoot.
.sp
.LP
If any \fIarguments\fR are specified on the \fBboot\fR command line, then
neither the \fIboot-file\fR nor the \fIdiag-file\fR \fBNVRAM\fR variable is
used. The contents of the \fBNVRAM\fR variables are not merged with command
line arguments. For example, the command:
.sp
.in +2
.nf
ok \fBboot\fR \fB-s\fR
.fi
.in -2
.sp

.sp
.LP
ignores the settings in both \fIboot-file\fR and \fIdiag-file\fR; it interprets
the string \fB"-s"\fR as \fIarguments\fR. \fBboot\fR will not use the contents
of \fIboot-file\fR or \fIdiag-file\fR.
.sp
.LP
With older PROMs, the command:
.sp
.in +2
.nf
ok \fBboot net\fR
.fi
.in -2
.sp

.sp
.LP
took no arguments, using instead the settings in \fIboot-file\fR or
\fIdiag-file\fR (if set) as the default file name and arguments to pass to
boot. In most cases, it is best to allow the \fBboot\fR command to choose an
appropriate default based upon the system type, system hardware and firmware,
and upon what is installed on the root file system. Changing \fIboot-file\fR or
\fIdiag-file\fR can generate unexpected results in certain circumstances.
.sp
.LP
This behavior is found on most OpenBoot 2.x and 3.x based systems. Note that
differences may occur on some platforms.
.sp
.LP
The command:
.sp
.LP
ok \fBboot cdrom\fR
.sp
.LP
\&...also normally takes no arguments. Accordingly, if \fIboot-file\fR is set
to the 64-bit kernel filename and you attempt to boot the installation CD or
DVD with \fBboot cdrom\fR, boot will fail if the installation media contains
only a 32-bit kernel.
.sp
.LP
Because the contents of \fIboot-file\fR or \fIdiag-file\fR can be ignored
depending on the form of the \fBboot\fR command used, reliance upon
\fIboot-file\fR should be discouraged for most production systems.
.sp
.LP
Modern PROMs have enhanced the network boot support package to support the
following syntax for arguments to be processed by the package:
.sp
.LP
[\fIprotocol\fR,] [\fIkey\fR=\fIvalue\fR,]*
.sp
.LP
All arguments are optional and can appear in any order. Commas are required
unless the argument is at the end of the list. If specified, an argument takes
precedence over any default values, or, if booting using DHCP, over
configuration information provided by a DHCP server for those parameters.
.sp
.LP
\fIprotocol\fR, above, specifies the address discovery protocol to be used.
.sp
.LP
Configuration parameters, listed below, are specified as \fIkey\fR=\fIvalue\fR
attribute pairs.
.sp
.ne 2
.na
\fB\fBtftp-server\fR\fR
.ad
.sp .6
.RS 4n
IP address of the TFTP server
.RE

.sp
.ne 2
.na
\fB\fBfile\fR\fR
.ad
.sp .6
.RS 4n
file to download using TFTP
.RE

.sp
.ne 2
.na
\fB\fBhost-ip\fR\fR
.ad
.sp .6
.RS 4n
IP address of the client (in dotted-decimal notation)
.RE

.sp
.ne 2
.na
\fB\fBrouter-ip\fR\fR
.ad
.sp .6
.RS 4n
IP address of the default router
.RE

.sp
.ne 2
.na
\fB\fBsubnet-mask\fR\fR
.ad
.sp .6
.RS 4n
subnet mask (in dotted-decimal notation)
.RE

.sp
.ne 2
.na
\fB\fBclient-id\fR\fR
.ad
.sp .6
.RS 4n
DHCP client identifier
.RE

.sp
.ne 2
.na
\fB\fBhostname\fR\fR
.ad
.sp .6
.RS 4n
hostname to use in DHCP transactions
.RE

.sp
.ne 2
.na
\fB\fBtftp-retries\fR\fR
.ad
.sp .6
.RS 4n
maximum number of TFTP retries
.RE

.sp
.ne 2
.na
\fB\fBdhcp-retries\fR\fR
.ad
.sp .6
.RS 4n
maximum number of DHCP retries
.RE

.sp
.LP
The list of arguments to be processed by the network boot support package is
specified in one of two ways:
.RS +4
.TP
.ie t \(bu
.el o
As arguments passed to the package's \fBopen\fR method, or
.RE
.RS +4
.TP
.ie t \(bu
.el o
arguments listed in the NVRAM variable \fBnetwork-boot-arguments\fR.
.RE
.sp
.LP
Arguments specified in \fBnetwork-boot-arguments\fR will be processed only if
there are no arguments passed to the package's \fBopen\fR method.
.sp
.LP
Argument Values
.sp
.LP
\fIprotocol\fR specifies the address discovery protocol to be used. If present,
the possible values are \fBrarp\fR or \fBdhcp\fR.
.sp
.LP
If other configuration parameters are specified in the new syntax and style
specified by this document, absence of the \fIprotocol\fR parameter implies
manual configuration.
.sp
.LP
If no other configuration parameters are specified, or if those arguments are
specified in the positional parameter syntax currently supported, the absence
of the \fIprotocol\fR parameter causes the network boot support package to use
the platform-specific default address discovery protocol.
.sp
.LP
Manual configuration requires that the client be provided its IP address, the
name of the boot file, and the address of the server providing the boot file
image. Depending on the network configuration, it might be required that
\fBsubnet-mask\fR and \fBrouter-ip\fR also be specified.
.sp
.LP
If the \fIprotocol\fR argument is not specified, the network boot support
package uses the platform-specific default address discovery protocol.
.sp
.LP
\fBtftp-server\fR is the IP address (in standard IPv4 dotted-decimal notation)
of the TFTP server that provides the file to download if using TFTP.
.sp
.LP
When using DHCP, the value, if specified, overrides the value of the TFTP
server specified in the DHCP response.
.sp
.LP
The TFTP RRQ is unicast to the server if one is specified as an argument or in
the DHCP response. Otherwise, the TFTP RRQ is broadcast.
.sp
.LP
\fIfile\fR specifies the file to be loaded by TFTP from the TFTP server.
.sp
.LP
When using RARP and TFTP, the default file name is the ASCII hexadecimal
representation of the IP address of the client, as documented in a preceding
section of this document.
.sp
.LP
When using DHCP, this argument, if specified, overrides the name of the boot
file specified in the DHCP response.
.sp
.LP
When using DHCP and TFTP, the default file name is constructed from the root
node's \fBname\fR property, with commas (,) replaced by periods (.).
.sp
.LP
When specified on the command line, the filename must not contain slashes
(\fB/\fR).
.sp
.LP
\fBhost-ip\fR specifies the IP address (in standard IPv4 dotted-decimal
notation) of the client, the system being booted. If using RARP as the address
discovery protocol, specifying this argument makes use of RARP unnecessary.
.sp
.LP
If DHCP is used, specifying the \fBhost-ip\fR argument causes the client to
follow the steps required of a client with an "Externally Configured Network
Address", as specified in RFC 2131.
.sp
.LP
\fBrouter-ip\fR is the IP address (in standard IPv4 dotted-decimal notation) of
a router on a directly connected network. The router will be used as the first
hop for communications spanning networks. If this argument is supplied, the
router specified here takes precedence over the preferred router specified in
the DHCP response.
.sp
.LP
\fBsubnet-mask\fR (specified in standard IPv4 dotted-decimal notation) is the
subnet mask on the client's network. If the subnet mask is not provided (either
by means of this argument or in the DHCP response), the default mask
appropriate to the network class (Class A, B, or C) of the address assigned to
the booting client will be assumed.
.sp
.LP
\fBclient-id\fR specifies the unique identifier for the client. The DHCP client
identifier is derived from this value. Client identifiers can be specified as:
.RS +4
.TP
.ie t \(bu
.el o
The ASCII hexadecimal representation of the identifier, or
.RE
.RS +4
.TP
.ie t \(bu
.el o
a quoted string
.RE
.sp
.LP
Thus, \fBclient-id="openboot"\fR and \fBclient-id=6f70656e626f6f74\fR both
represent a DHCP client identifier of 6F70656E626F6F74.
.sp
.LP
Identifiers specified on the command line must must not include slash (\fB/\fR)
or spaces.
.sp
.LP
The maximum length of the DHCP client identifier is 32 bytes, or 64 characters
representing 32 bytes if using the ASCII hexadecimal form. If the latter form
is used, the number of characters in the identifier must be an even number.
Valid characters are 0-9, a-f, and A-F.
.sp
.LP
For correct identification of clients, the client identifier must be unique
among the client identifiers used on the subnet to which the client is
attached. System administrators are responsible for choosing identifiers that
meet this requirement.
.sp
.LP
Specifying a client identifier on a command line takes precedence over any
other DHCP mechanism of specifying identifiers.
.sp
.LP
\fBhostname\fR (specified as a string) specifies the hostname to be used in
DHCP transactions. The name might or might not be qualified with the local
domain name. The maximum length of the hostname is 255 characters.
.LP
Note -
.sp
.RS 2
The \fBhostname\fR parameter can be used in service environments that require
that the client provide the desired hostname to the DHCP server. Clients
provide the desired hostname to the DHCP server, which can then register the
hostname and IP address assigned to the client with DNS.
.RE
.sp
.LP

\fBtftp-retries\fR is the maximum number of retries (specified in decimal)
attempted before the TFTP process is determined to have failed. Defaults to
using infinite retries.
.sp
.LP
\fBdhcp-retries\fR is the maximum number of retries (specified in decimal)
attempted before the DHCP process is determined to have failed. Defaults to of
using infinite retries.
.SS "x86 Bootstrap Procedure"
.LP
On x86 based systems, the bootstrapping process consists of two conceptually
distinct phases, kernel loading and kernel initialization. Kernel loading is
implemented in the boot loader using the BIOS ROM on the system
board, and BIOS extensions in ROMs on peripheral boards. The BIOS loads boot
loader, starting with the first physical sector from a hard disk, DVD, or CD. If
supported by the ROM on the network adapter, the BIOS can also download the
\fBpxeboot\fR binary from a network boot server. Once the boot loader is
loaded, it in turn will load the \fBunix\fR kernel, a pre-constructed boot
archive containing kernel modules and data, and any additional files specified
in the boot loader configuration. Once specified files are loaded, the boot
loader will start the kernel to complete boot.
.sp
.LP
If the device identified by the boot loader as the boot device contains a ZFS
storage pool, the \fBmenu.lst\fR file used to create the Boot Environment menu
will be found in the dataset at the root of the pool's dataset hierarchy.
This is the dataset with the same name as the pool itself. There is always
exactly one such dataset in a pool, and so this dataset is well-suited for
pool-wide data such as the \fBmenu.lst\fR file. After the system is booted,
this dataset is mounted at /\fIpoolname\fR in the root file system.
.sp
.LP
There can be multiple bootable datasets (that is, root file systems) within a
pool. The default file system to load the kernel is identified by the boot
pool \fBbootfs\fR property (see \fBzpool\fR(8)). All bootable datasets are
listed in the \fBmenu.lst\fR file, which is used by the boot loader to compose
the Boot Environment menu, to implement support to load a kernel and boot from
an alternate Boot Environment.
.sp
.LP
Kernel initialization starts when the boot loader finishes loading the files
specified in the boot loader configuration and hands control over to the
\fBunix\fR binary. The Unix operating system initializes, links in the
necessary modules from the boot archive and mounts the root file system on
the real root device. At this point, the kernel regains
storage I/O, mounts additional file systems (see \fBvfstab\fR(4)), and starts
various operating system services (see \fBsmf\fR(5)).

.SH OPTIONS
.SS "SPARC"
.LP
The following SPARC options are supported:
.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.sp .6
.RS 4n
The boot program interprets this flag to mean \fBask me\fR, and so it prompts
for the name of the standalone. The \fB\&'\fR\fB-a\fR\fB\&'\fR flag is then
passed to the standalone program.
.RE

.sp
.ne 2
.na
\fB\fB-D\fR \fIdefault-file\fR\fR
.ad
.sp .6
.RS 4n
Explicitly specify the \fIdefault-file\fR. On some systems, \fBboot\fR chooses
a dynamic default file, used when none is otherwise specified. This option
allows the \fIdefault-file\fR to be explicitly set and can be useful when
booting \fBkmdb\fR(1) since, by default, \fBkmdb\fR loads the default-file as
exported by the \fBboot\fR program.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR \fIobject\fR\fR
.ad
.sp .6
.RS 4n
Boot using the named object. The object must be either an ELF executable or
bootable object containing a boot block. The primary use is to boot the
failsafe boot archive.
.RE

.sp
.ne 2
.na
\fB\fB-L\fR\fR
.ad
.sp .6
.RS 4n
List the bootable datasets within a ZFS pool. You can select one of the
bootable datasets in the list, after which detailed instructions for booting
that dataset are displayed. Boot the selected dataset by following the
instructions. This option is supported only when the boot device contains a ZFS
storage pool.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.sp .6
.RS 4n
Display verbose debugging information.
.RE

.sp
.ne 2
.na
\fB\fIboot-flags\fR\fR
.ad
.sp .6
.RS 4n
The boot program passes all \fIboot-flags\fR to \fBfile\fR. They are not
interpreted by \fBboot\fR. See the \fBkernel\fR(8) and \fBkmdb\fR(1) manual
pages for information about the options available with the default standalone
program.
.RE

.sp
.ne 2
.na
\fB\fIclient-program-args\fR\fR
.ad
.sp .6
.RS 4n
The \fBboot\fR program passes all \fIclient-program-args\fR to \fIfile\fR. They
are not interpreted by \fBboot\fR.
.RE

.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.sp .6
.RS 4n
Name of a standalone program to \fBboot\fR. If a filename is not explicitly
specified, either on the \fBboot\fR command line or in the \fIboot-file\fR
NVRAM variable, \fBboot\fR chooses an appropriate default filename.
.RE

.sp
.ne 2
.na
\fB\fIOBP\fR \fInames\fR\fR
.ad
.sp .6
.RS 4n
Specify the open boot prom designations. For example, on Desktop SPARC based
systems, the designation \fB/sbus/esp@0,800000/sd@3,0:a\fR indicates a
\fBSCSI\fR disk (sd) at target 3, lun0 on the \fBSCSI\fR bus, with the esp host
adapter plugged into slot 0.
.RE

.sp
.ne 2
.na
\fB\fB-Z\fR \fIdataset\fR\fR
.ad
.sp .6
.RS 4n
Boot from the root file system in the specified ZFS dataset.
.RE

.SS "x86"
.LP
The following x86 options are supported:
.sp
.ne 2
.na
\fB\fB-B\fR \fIprop\fR=\fIval\fR...\fR
.ad
.sp .6
.RS 4n
One or more property-value pairs to be passed to the kernel. Multiple
property-value pairs must be separated by a comma. Use of this option is the
equivalent of the command: \fBeeprom\fR \fIprop\fR=\fIval\fR. See
\fBeeprom\fR(8) for available properties and valid values.
.RE

.sp
.ne 2
.na
\fB\fIboot-flags\fR\fR
.ad
.sp .6
.RS 4n
The boot program passes all \fIboot-flags\fR to \fBfile\fR. They are not
interpreted by \fBboot\fR. See \fBkernel\fR(8) and \fBkmdb\fR(1) for
information about the options available with the kernel.
.RE

.SH X86 BOOT SEQUENCE DETAILS
.LP
After a PC-compatible machine is turned on, the system firmware in the \fBBIOS
ROM\fR executes a power-on self test (POST), runs \fBBIOS\fR extensions in
peripheral board \fBROMs,\fR and invokes software interrupt INT 19h, Bootstrap.
The INT 19h handler typically performs the standard PC-compatible boot, which
consists of trying to read the first physical sector from the first diskette
drive, or, if that fails, from the first hard disk. The processor then jumps to
the first byte of the sector image in memory.
.SH X86 PRIMARY BOOT
.LP
The first sector on a hard disk contains the master boot block (first stage of
the boot program), which contains the master boot program and the Master Boot
Record (\fBMBR\fR) table. The master boot program has recorded the location of
the secondary stage of the boot program and using this location, master boot
will load and start the secondary stage of the boot program.

To support booting multiple operating systems, the master boot program is also
installed as the first sector of the partition with the illumos root file
system. This will allow configuring third party boot programs to use the
chainload technique to boot illumos system.

If the first stage is installed on the master boot block (see the \fB-m\fR
option of \fBinstallboot\fR(8)), then \fBstage2\fR is loaded directly
from the Solaris partition regardless of the active partition.
.sp
.LP
A similar sequence occurs for DVD or CD boot, but the master boot block location
and contents are dictated by the El Torito specification. The El Torito boot
will then continue in the same way as with the hard disk.
.sp
.LP
Floppy booting is not longer supported. Booting from USB devices follows the
same procedure as with hard disks.
.sp
.LP
An x86 \fBMBR\fR partition for the Solaris software begins with a
one-cylinder boot slice, which contains the boot loader \fBstage1\fR in the
first sector, the standard Solaris disk label and volume table of contents
(VTOC) in the second and third sectors, and in case the UFS file system is
used for the root file system, \fBstage2\fR in the fiftieth and subsequent
sectors.

If the zfs boot is used, \fBstage2\fR is always stored in the zfs pool
boot program area.
.sp
.LP
The behavior is slightly different when a disk is using \fBEFI\fR
partitioning.

To support a UFS root file system in the \fBEFI\fR partition, the \fBstage2\fR
must be stored on separate dedicated partition, as there is no space in UFS
file system boot program area to store the current \fBstage2\fR. This separate
dedicated partition is used as raw disk space, and must have enough space
for both \fBstage1\fR and \fBstage2\fR. The type (tag) of this partition
must be \fBboot\fR, \fBEFI\fR UUID:
.sp
.in +2
.nf
\fB6a82cb45-1dd2-11b2-99a6-080020736631\fR
.fi
.in -2
.sp
For the UUID reference, please see \fB/usr/include/sys/efi_partition.h\fR.

In case of a whole disk zfs pool configuration, the \fBstage1\fR is always
installed in the first sector of the disk, and it always loads \fBstage2\fR
from the partition specified at the boot loader installation time.
.sp
.LP
Once \fBstage2\fR is running, it will load and start the third stage boot
program from root file system. Boot loader supports loading from the ZFS,
UFS and PCFS file systems. The stage3 boot program defaults to be
\fB/boot/loader\fR, and implements a user interface to load and boot the
unix kernel.
.sp
.LP
For network booting, the supported method is Intel's Preboot eXecution
Environment (PXE) standard. When booting from the network using PXE, the system
or network adapter BIOS uses DHCP to locate a network bootstrap program
(\fBpxeboot\fR) on a boot server and reads it using Trivial File Transfer
Protocol (TFTP). The BIOS executes the \fBpxeboot\fR by jumping to its first
byte in memory. The \fBpxeboot\fR program is combined stage2 and stage2 boot
program and implements user interface to load and boot unix kernel.
.SH X86 KERNEL STARTUP
.LP
The kernel startup process is independent of the kernel loading process. During
kernel startup, console I/O goes to the device specified by the \fBconsole\fR
property.
.sp
.LP
When booting from UFS, the root device is specified by the \fBbootpath\fR
property, and the root file system type is specified by the \fBfstype\fR
property. These properties should be setup by the Solaris Install/Upgrade
process in \fB/boot/solaris/bootenv.rc\fR and can be overridden with the
\fB-B\fR option, described above (see the \fBeeprom\fR(8) man page).
.sp
.LP
When booting from ZFS, the root device is automatically passed by the boot
loader to the kernel as a boot parameter \fB-B\fR \fBzfs-bootfs\fR. The actual
value used by the boot loader can be observed with the \fBeeprom bootcmd\fR
command.
.sp
.LP
If the console properties are not present, console I/O defaults to \fBscreen\fR
and \fBkeyboard\fR. The root device defaults to \fBramdisk\fR and the file
system defaults to \fBufs\fR.
.SH EXAMPLES
.SS "SPARC"
.LP
\fBExample 1 \fRTo Boot the Default Kernel In Single-User Interactive Mode
.sp
.LP
To boot the default kernel in single-user interactive mode, respond to the
\fBok\fR prompt with one of the following:

.sp
.in +2
.nf
\fBboot\fR \fB\fR\fB-as\fR

\fBboot\fR \fBdisk3\fR \fB-as\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRNetwork Booting
.sp
.LP
To illustrate some of the subtle repercussions of various boot command line
invocations, assume that the \fBnetwork-boot-arguments\fR are set and that
\fBnet\fR is devaliased as shown in the commands below.

.sp
.LP
In the following command, device arguments in the device alias are processed by
the device driver. The network boot support package processes arguments in
\fBnetwork-boot-arguments\fR.

.sp
.in +2
.nf
\fBboot net\fR
.fi
.in -2
.sp

.sp
.LP
The command below results in no device arguments. The network boot support
package processes arguments in \fBnetwork-boot-arguments\fR.

.sp
.in +2
.nf
\fBboot net:\fR
.fi
.in -2
.sp

.sp
.LP
The command below results in no device arguments. \fBrarp\fR is the only
network boot support package argument. \fBnetwork-boot-arguments\fR is ignored.

.sp
.in +2
.nf
\fBboot net:rarp\fR
.fi
.in -2
.sp

.sp
.LP
In the command below, the specified device arguments are honored. The network
boot support package processes arguments in \fBnetwork-boot-arguments\fR.

.sp
.in +2
.nf
\fBboot net:speed=100,duplex=full\fR
.fi
.in -2
.sp

.SS "x86"
.LP
\fBExample 3 \fRTo Boot the Default Kernel In 64-bit Single-User Interactive
Mode
.sp
.LP
To boot the default kernel in single-user interactive mode, press the ESC key
to get the boot loader \fBok\fR prompt and enter:

.sp
.in +2
.nf
boot -as
.fi
.in -2

.SH FILES
.ne 2
.na
\fB\fB/etc/inittab\fR\fR
.ad
.sp .6
.RS 4n
Table in which the \fBinitdefault\fR state is specified
.RE

.sp
.ne 2
.na
\fB\fB/sbin/init\fR\fR
.ad
.sp .6
.RS 4n
Program that brings the system to the \fBinitdefault\fR state
.RE

.SS "64-bit SPARC Only"
.ne 2
.na
\fB\fB/platform/\fR\fIplatform-name\fR\fB/kernel/sparcv9/unix\fR\fR
.ad
.sp .6
.RS 4n
Default program to boot system.
.RE

.SS "x86 Only"
.ne 2
.na
\fB\fB/boot\fR\fR
.ad
.sp .6
.RS 4n
Directory containing boot-related files.
.RE

.sp
.ne 2
.na
\fB\fB/rpool/boot/menu.lst\fR\fR
.ad
.sp .6
.RS 4n
Menu index file of bootable operating systems displayed by the boot loader.
.sp
\fBNote:\fR this file is located on the root ZFS pool. While many installs
often name their root zpool 'rpool', this is not required and the
/rpool in the path above should be substituted with the name of
the root pool of your current system.
.RE

.sp
.ne 2
.na
\fB\fB/platform/kernel/unix\fR\fR
.ad
.sp .6
.RS 4n
32-bit kernel.
.RE

.SS "64-bit x86 Only"
.ne 2
.na
\fB\fB/platform/kernel/amd64/unix\fR\fR
.ad
.sp .6
.RS 4n
64-bit kernel.
.RE

.SH SEE ALSO
.LP
\fBkmdb\fR(1), \fBuname\fR(1), \fBbootadm\fR(8), \fBeeprom\fR(8),
\fBinit\fR(8), \fBinstallboot\fR(8), \fBkernel\fR(8), \fBmonitor\fR(8),
\fBshutdown\fR(8), \fBsvcadm\fR(8), \fBumountall\fR(8), \fBzpool\fR(8),
\fBuadmin\fR(2), \fBbootparams\fR(4), \fBinittab\fR(4), \fBvfstab\fR(4),
\fBfilesystem\fR(5)
.sp
.LP
RFC 903, \fIA Reverse Address Resolution Protocol\fR,
\fBhttp://www.ietf.org/rfc/rfc903.txt\fR
.sp
.LP
RFC 2131, \fIDynamic Host Configuration Protocol\fR,
\fBhttp://www.ietf.org/rfc/rfc2131.txt\fR
.sp
.LP
RFC 2132, \fIDHCP Options and BOOTP Vendor Extensions\fR,
\fBhttp://www.ietf.org/rfc/rfc2132.txt\fR
.sp
.LP
\fI\fR
.sp
.LP
\fISun Hardware Platform Guide\fR
.sp
.LP
\fIOpenBoot Command Reference Manual\fR
.SH WARNINGS
.LP
The \fBboot\fR utility is unable to determine which files can be used as
bootable programs. If the booting of a file that is not bootable is requested,
the \fBboot\fR utility loads it and branches to it. What happens after that is
unpredictable.
.SH NOTES
.LP
\fIplatform-name\fR can be found using the \fB-i\fR option of \fBuname\fR(1).
\fIhardware-class-name\fR can be found using the \fB-m\fR option of
\fBuname\fR(1).
.sp
.LP
The current release of the Solaris operating system does not support machines
running an UltraSPARC-I CPU.