BOOT(1M) Maintenance Commands BOOT(1M)


NAME


boot - start the system kernel or a standalone program

SYNOPSIS


SPARC


boot [OBP names] [file] [-aLV] [-F object] [-D default-file]
[-Z dataset] [boot-flags] [--] [client-program-args]


x86
boot [boot-flags] [-B prop=val [,val...]]


DESCRIPTION


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
kernel(1M)), 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.


If the standalone is identified as a dynamically-linked executable, boot
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.


Once the kernel is loaded, it starts the UNIX system, mounts the
necessary file systems (see vfstab(4)), and runs /sbin/init to bring the
system to the "initdefault" state specified in /etc/inittab. See
inittab(4).

SPARC Bootstrap Procedure


On SPARC based systems, the bootstrap procedure on most machines consists
of the following basic phases.


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.


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.


These flags and names can be set using the eeprom(1M) command from the
shell, or by using PROM commands from the ok prompt after the system has
been halted.


The second level program is either a fileystem-specific boot block (when
booting from a disk), or inetboot (when booting across the network).


Network Booting


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.


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 sun4u and sun4v kernel architectures have
DHCP-capable PROMs.


The boot command syntax for specifying the two methods of network booting
are:

boot net:rarp
boot net:dhcp


The command:

boot net


without a rarp or dhcp specifier, invokes the default method for network
booting over the network interface for which net is an alias.


The sequence of events for network booting using RARP/bootparams is
described in the following paragraphs. The sequence for DHCP follows the
RARP/bootparams description.


When booting over the network using RARP/bootparams, 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 inetboot. Subsequent requests will be sent to the server
that initially answered the first block request. After loading, inetboot
will also use reverse ARP to fetch its IP address, then broadcast
bootparams RPC calls (see bootparams(4)) to locate configuration
information and its root file system. inetboot then loads the boot
archive by means of NFS and transfers control to that archive.


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. After receipt of this information, the client PROM
examines the name of the file to be loaded, and will behave in one of two
ways, depending on whether the file's name appears to be an HTTP URL. If
it does not, the PROM downloads inetboot, loads that file into memory,
and executes it. inetboot loads the boot archive, which takes over the
machine and releases inetboot. Startup scripts then initiate the DHCP
agent (see dhcpagent(1M)), which implements further DHCP activities.


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


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.


To configure the iBFT properly, users need to refer to the documentation
from their hardware vendors.

Booting from Disk


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.


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
/platform/platform-name. Many SPARC platforms next search the platform-
specific path entry /platform/hardware-class-name. See filesystem(5). If
the pathname is absolute, boot will use the specified path. The boot
program then loads the standalone at the appropriate address, and then
transfers control.


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.


If the filename is not given on the command line or otherwise specified,
for example, by the boot-file NVRAM variable, boot chooses an appropriate
default file to load based on what software is installed on the system
and the capabilities of the hardware and firmware.


The path to the kernel must not contain any whitespace.

Booting from ZFS


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 bootfs property. This default selection can be overridden by
specifying an alternate bootable dataset with the -Z option.

Boot Archive Phase


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:

/platform/`uname -i`/kernel/unix


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.


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.

OpenBoot PROM boot Command Behavior
The OpenBoot boot command takes arguments of the following form:

ok boot [device-specifier] [arguments]


The default boot command has no arguments:

ok boot


If no device-specifier is given on the boot command line, OpenBoot
typically uses the boot-device or diag-device NVRAM variable. If no
optional arguments are given on the command line, OpenBoot typically uses
the boot-file or diag-file NVRAM variable as default boot arguments. (If
the system is in diagnostics mode, diag-device and diag-file are used
instead of boot-device and boot-file).


arguments may include more than one string. All argument strings are
passed to the secondary booter; they are not interpreted by OpenBoot.


If any arguments are specified on the boot command line, then neither the
boot-file nor the diag-file NVRAM variable is used. The contents of the
NVRAM variables are not merged with command line arguments. For example,
the command:

ok boot -s


ignores the settings in both boot-file and diag-file; it interprets the
string "-s" as arguments. boot will not use the contents of boot-file or
diag-file.


With older PROMs, the command:

ok boot net


took no arguments, using instead the settings in boot-file or diag-file
(if set) as the default file name and arguments to pass to boot. In most
cases, it is best to allow the boot 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 boot-file or
diag-file can generate unexpected results in certain circumstances.


This behavior is found on most OpenBoot 2.x and 3.x based systems. Note
that differences may occur on some platforms.


The command:


ok boot cdrom


...also normally takes no arguments. Accordingly, if boot-file is set to
the 64-bit kernel filename and you attempt to boot the installation CD or
DVD with boot cdrom, boot will fail if the installation media contains
only a 32-bit kernel.


Because the contents of boot-file or diag-file can be ignored depending
on the form of the boot command used, reliance upon boot-file should be
discouraged for most production systems.


Modern PROMs have enhanced the network boot support package to support
the following syntax for arguments to be processed by the package:


[protocol,] [key=value,]*


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.


protocol, above, specifies the address discovery protocol to be used.


Configuration parameters, listed below, are specified as key=value
attribute pairs.

tftp-server

IP address of the TFTP server


file

file to download using TFTP


host-ip

IP address of the client (in dotted-decimal notation)


router-ip

IP address of the default router


subnet-mask

subnet mask (in dotted-decimal notation)


client-id

DHCP client identifier


hostname

hostname to use in DHCP transactions


http-proxy

HTTP proxy server specification (IPADDR[:PORT])


tftp-retries

maximum number of TFTP retries


dhcp-retries

maximum number of DHCP retries


The list of arguments to be processed by the network boot support package
is specified in one of two ways:

o As arguments passed to the package's open method, or

o arguments listed in the NVRAM variable network-boot-arguments.


Arguments specified in network-boot-arguments will be processed only if
there are no arguments passed to the package's open method.


Argument Values


protocol specifies the address discovery protocol to be used. If present,
the possible values are rarp or dhcp.


If other configuration parameters are specified in the new syntax and
style specified by this document, absence of the protocol parameter
implies manual configuration.


If no other configuration parameters are specified, or if those arguments
are specified in the positional parameter syntax currently supported, the
absence of the protocol parameter causes the network boot support package
to use the platform-specific default address discovery protocol.


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 subnet-mask and router-ip also be specified.


If the protocol argument is not specified, the network boot support
package uses the platform-specific default address discovery protocol.


tftp-server is the IP address (in standard IPv4 dotted-decimal notation)
of the TFTP server that provides the file to download if using TFTP.


When using DHCP, the value, if specified, overrides the value of the TFTP
server specified in the DHCP response.


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.


file specifies the file to be loaded by TFTP from the TFTP server.


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.


When using DHCP, this argument, if specified, overrides the name of the
boot file specified in the DHCP response.


When using DHCP and TFTP, the default file name is constructed from the
root node's name property, with commas (,) replaced by periods (.).


When specified on the command line, the filename must not contain slashes
(/).


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


If DHCP is used, specifying the host-ip argument causes the client to
follow the steps required of a client with an "Externally Configured
Network Address", as specified in RFC 2131.


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


subnet-mask (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.


client-id specifies the unique identifier for the client. The DHCP client
identifier is derived from this value. Client identifiers can be
specified as:

o The ASCII hexadecimal representation of the identifier, or

o a quoted string


Thus, client-id="openboot" and client-id=6f70656e626f6f74 both represent
a DHCP client identifier of 6F70656E626F6F74.


Identifiers specified on the command line must must not include slash (/)
or spaces.


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.


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.


Specifying a client identifier on a command line takes precedence over
any other DHCP mechanism of specifying identifiers.


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

Note -

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


http-proxy is specified in the following standard notation for a host:

host [":"" port]


...where host is specified as an IP ddress (in standard IPv4 dotted-
decimal notation) and the optional port is specified in decimal. If a
port is not specified, port 8080 (decimal) is implied.


tftp-retries is the maximum number of retries (specified in decimal)
attempted before the TFTP process is determined to have failed. Defaults
to using infinite retries.


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

x86 Bootstrap Procedure
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 pxeboot binary from a network boot server.
Once the boot loader is loaded, it in turn will load the unix 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.


If the device identified by the boot loader as the boot device contains a
ZFS storage pool, the menu.lst 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 menu.lst file. After the
system is booted, this dataset is mounted at /poolname in the root file
system.


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 bootfs property (see zpool(1M)). All bootable datasets
are listed in the menu.lst 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.


Kernel initialization starts when the boot loader finishes loading the
files specified in the boot loader configuration and hands control over
to the unix 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 vfstab(4)), and starts various
operating system services (see smf(5)).


OPTIONS


SPARC


The following SPARC options are supported:

-a

The boot program interprets this flag to mean ask me, and so it
prompts for the name of the standalone. The '-a' flag is then passed
to the standalone program.


-D default-file

Explicitly specify the default-file. On some systems, boot chooses a
dynamic default file, used when none is otherwise specified. This
option allows the default-file to be explicitly set and can be useful
when booting kmdb(1) since, by default, kmdb loads the default-file
as exported by the boot program.


-F object

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.


-L

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.


-V

Display verbose debugging information.


boot-flags

The boot program passes all boot-flags to file. They are not
interpreted by boot. See the kernel(1M) and kmdb(1) manual pages for
information about the options available with the default standalone
program.


client-program-args

The boot program passes all client-program-args to file. They are not
interpreted by boot.


file

Name of a standalone program to boot. If a filename is not explicitly
specified, either on the boot command line or in the boot-file NVRAM
variable, boot chooses an appropriate default filename.


OBP names

Specify the open boot prom designations. For example, on Desktop
SPARC based systems, the designation /sbus/esp@0,800000/sd@3,0:a
indicates a SCSI disk (sd) at target 3, lun0 on the SCSI bus, with
the esp host adapter plugged into slot 0.


-Z dataset

Boot from the root file system in the specified ZFS dataset.


x86
The following x86 options are supported:

-B prop=val...

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: eeprom prop=val. See eeprom(1M) for
available properties and valid values.


boot-flags

The boot program passes all boot-flags to file. They are not
interpreted by boot. See kernel(1M) and kmdb(1) for information about
the options available with the kernel.


X86 BOOT SEQUENCE DETAILS
After a PC-compatible machine is turned on, the system firmware in the
BIOS ROM executes a power-on self test (POST), runs BIOS extensions in
peripheral board ROMs, 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.

X86 PRIMARY BOOT
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 (MBR) 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 -m
option of installboot(1M)), then stage2 is loaded directly from the
Solaris partition regardless of the active partition.


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.


Floppy booting is not longer supported. Booting from USB devices follows
the same procedure as with hard disks.


An x86 MBR partition for the Solaris software begins with a one-cylinder
boot slice, which contains the boot loader stage1 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, stage2 in the fiftieth and subsequent sectors.

If the zfs boot is used, stage2 is always stored in the zfs pool boot
program area.


The behavior is slightly different when a disk is using EFI partitioning.

To support a UFS root file system in the EFI partition, the stage2 must
be stored on separate dedicated partition, as there is no space in UFS
file system boot program area to store the current stage2. This separate
dedicated partition is used as raw disk space, and must have enough space
for both stage1 and stage2. The type (tag) of this partition must be
boot, EFI UUID:

6a82cb45-1dd2-11b2-99a6-080020736631

For the UUID reference, please see /usr/include/sys/efi_partition.h.

In case of a whole disk zfs pool configuration, the stage1 is always
installed in the first sector of the disk, and it always loads stage2
from the partition specified at the boot loader installation time.


Once stage2 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
/boot/loader, and implements a user interface to load and boot the unix
kernel.


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 (pxeboot) on a boot server and reads it using Trivial File
Transfer Protocol (TFTP). The BIOS executes the pxeboot by jumping to its
first byte in memory. The pxeboot program is combined stage2 and stage2
boot program and implements user interface to load and boot unix kernel.

X86 KERNEL STARTUP
The kernel startup process is independent of the kernel loading process.
During kernel startup, console I/O goes to the device specified by the
console property.


When booting from UFS, the root device is specified by the bootpath
property, and the root file system type is specified by the fstype
property. These properties should be setup by the Solaris Install/Upgrade
process in /boot/solaris/bootenv.rc and can be overridden with the -B
option, described above (see the eeprom(1M) man page).


When booting from ZFS, the root device is automatically passed by the
boot loader to the kernel as a boot parameter -B zfs-bootfs. The actual
value used by the boot loader can be observed with the eeprom bootcmd
command.


If the console properties are not present, console I/O defaults to screen
and keyboard. The root device defaults to ramdisk and the file system
defaults to ufs.

EXAMPLES


SPARC


Example 1: To Boot the Default Kernel In Single-User Interactive Mode




To boot the default kernel in single-user interactive mode, respond to
the ok prompt with one of the following:


boot -as

boot disk3 -as


Example 2: Network Booting




To illustrate some of the subtle repercussions of various boot command
line invocations, assume that the network-boot-arguments are set and that
net is devaliased as shown in the commands below.


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


boot net


The command below results in no device arguments. The network boot
support package processes arguments in network-boot-arguments.


boot net:


The command below results in no device arguments. rarp is the only
network boot support package argument. network-boot-arguments is ignored.


boot net:rarp


In the command below, the specified device arguments are honored. The
network boot support package processes arguments in network-boot-
arguments.


boot net:speed=100,duplex=full


x86

Example 3: To Boot the Default Kernel In 64-bit Single-User Interactive


Mode


To boot the default kernel in single-user interactive mode, press the ESC
key to get the boot loader ok prompt and enter:


boot -as


FILES


/etc/inittab

Table in which the initdefault state is specified


/sbin/init

Program that brings the system to the initdefault state


64-bit SPARC Only
/platform/platform-name/kernel/sparcv9/unix

Default program to boot system.


x86 Only
/boot

Directory containing boot-related files.


/rpool/boot/menu.lst

Menu index file of bootable operating systems displayed by the boot
loader.

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


/platform/i86pc/kernel/unix

32-bit kernel.


64-bit x86 Only
/platform/i86pc/kernel/amd64/unix

64-bit kernel.


SEE ALSO


kmdb(1), uname(1), bootadm(1M), eeprom(1M), init(1M), installboot(1M),
kernel(1M), monitor(1M), shutdown(1M), svcadm(1M), umountall(1M),
zpool(1M), uadmin(2), bootparams(4), inittab(4), vfstab(4), filesystem(5)


RFC 903, A Reverse Address Resolution Protocol,
http://www.ietf.org/rfc/rfc903.txt


RFC 2131, Dynamic Host Configuration Protocol,
http://www.ietf.org/rfc/rfc2131.txt


RFC 2132, DHCP Options and BOOTP Vendor Extensions,
http://www.ietf.org/rfc/rfc2132.txt


RFC 2396, Uniform Resource Identifiers (URI): Generic Syntax,
http://www.ietf.org/rfc/rfc2396.txt


Sun Hardware Platform Guide


OpenBoot Command Reference Manual

WARNINGS


The boot 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 boot utility loads it and branches to it. What happens
after that is unpredictable.

NOTES


platform-name can be found using the -i option of uname(1). hardware-
class-name can be found using the -m option of uname(1).


The current release of the Solaris operating system does not support
machines running an UltraSPARC-I CPU.


July 20, 2018 BOOT(1M)