boot(1M)
NAME
boot - start the system kernel or a standalone program
SYNOPSIS
SPARC
boot [ OBP names] [file] [-afV] [-D default-file] [boot-
flags] [--] [client-program-args]
x86
b [file] [-f] [-D default-file] [boot-args]
i
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 exam-
ple of a standalone program other than the operating system
that can be booted.
If the standalone is identified as a dynamically-linked exe-
cutable, 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) com-
mand from the shell, or by using PROM commands from the ok
prompt after the system has been halted.
The second level program is either ufsboot (when booting
from a disk), or inetboot or wanboot (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 UNIX kernel.
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 kernel architecture 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 descrip-
tion.
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 inet-
boot. 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 kernel via NFS and transfers control
to it.
When booting over the network using DHCP, the PROM broad-
casts 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 invokes the kernel, which
loads the files it needs and releases inetboot. Startup
scripts then initiate the DHCP agent (see dhcpagent(1M)),
which implements further DHCP activities.
If the file to be loaded is an HTTP URL, the PROM will use
HTTP to load the referenced file. If the client has been
configured with an HMAC SHA-1 key, it will check the
integrity of the loaded file before proceeding to execute
it. The file is expected to be the wanboot binary. When
wanboot begins executing, it will determine whether suffi-
cient information is available to it to allow it to proceed.
If any necessary information is missing, it will either exit
with an appropriate error or bring up a command interpreter
and prompt for further configuration information. Once wan-
boot has obtained the necessary information, it will load
its boot file system into memory by means of HTTP. If an
encryption key has been installed on the client, wanboot
will decrypt the file system image and its accompanying hash
(presence of an encryption key but no hashing key is an
error), then verify the hash. The boot file system contains
various configuration data needed to allow wanboot to set
the correct time and proceed to obtain a root file system.
The boot file system is examined to determine whether wan-
boot should use HTTP or secure HTTP. If the former, and if
the client has been configured with an HMAC SHA-1 key, wan-
boot will perform an integrity check of the root file sys-
tem. Once the root file system has been loaded into memory
(and possibly had an integrity check performed), wanboot
loads and executes UNIX from it. If provided with a
boot_logger URL by means of the wanboot.conf(4) file, wan-
boot will periodically log its progress.
Not all PROMs are capable of consuming URLs. You can deter-
mine whether a client is so capable using the list-
security-keys OBP command (see monitor(1M)).
WAN booting is not currently available on the x86 platform.
The wanboot Command Line
When the client program is wanboot, it accepts client-
program-args of the form:
boot ... -o opt1[,opt2[,...]]
where each option may be an action:
dhcp Require wanboot to obtain configuration parameters by
means of DHCP.
prompt
Cause wanboot to enter its command interpreter.
<cmd> One of the interpreter commands listed below.
...or an assignment, using the interpreter's parameter names
listed below.
The wanboot Command Interpreter
The wanboot command interpreter is invoked by supplying a
client-program-args of "-o prompt" when booting. Input con-
sists of single commands or assignments, or a comma-
separated list of commands or assignments. The configuration
parameters are:
host-ip
IP address of the client (in dotted-decimal notation)
router-ip
IP address of the default router (in dotted-decimal
notation)
subnet-mask
subnet mask (in dotted-decimal notation)
client-id
DHCP client identifier (a quoted ASCII string or hex
ASCII)
hostname
hostname to request in DHCP transactions (ASCII)
http-proxy
HTTP proxy server specification (IPADDR[:PORT])
The key names are:
3des the triple DES encryption key (48 hex ASCII charac-
ters)
aes the AES encryption key (32 hex ASCII characters)
sha1 the HMAC SHA-1 signature key (40 hex ASCII characters)
Finally, the URL or the WAN boot CGI is referred to by means
of:
bootserver
URL of WAN boot's CGI (the equivalent of OBP's file
parameter)
The interpreter accepts the following commands:
help Print a brief description of the available commands
var=val
Assign val to var, where var is one of the configura-
tion parameter names, the key names, or bootserver.
var= Unset parameter var.
list List all parameters and their values (key values
retrieved by means of OBP are never shown).
prompt
Prompt for values for unset parameters. The name of
each parameter and its current value (if any) is
printed, and the user can accept this value (press
Return) or enter a new value.
go Once the user is satisfied that all values have been
entered, leave the interpreter and continue booting.
exit Quit the boot interpreter and return to OBP's ok
prompt.
Any of these assignments or commands can be passed on the
command line as part of the -o options, subject to the OBP
limit of 128 bytes for boot arguments. For example, -o
list,go would simply list current (default) values of the
parameters and then continue booting.
Booting from Disk
When booting from disk (or disk-like device), the bootstrap-
ping process consists of two conceptually distinct phases,
primary boot and secondary boot. In the primary boot phase,
the PROM loads the primary boot block from blocks 1 to 15 of
the disk partition selected as the boot device.
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.
If the filename is not given on the command line or other-
wise specified, for example, by the boot-file NVRAM vari-
able, boot chooses an appropriate default file to load based
on what software is installed on the system, the capabili-
ties of the hardware and firmware, and on a user configur-
able policy file (see FILES, below).
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 sys-
tem type, system hardware and firmware, and upon what is
installed on the root file system. It is accepted practice
to augment the boot command's policy by modifying the policy
file; however, changing boot-file or diag-file may 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 with boot cdrom, boot will fail if
the installation CD 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 pro-
duction systems. To change the OS policy, change the policy
file. A significant exception is when a production system
has both 32-bit and 64-bit packages installed, but the pro-
duction system requires use of the 32-bit OS.
When executing a WAN boot from a local (CD) copy of wanboot,
one must use:
ok boot cdrom -F wanboot - install
Modern PROMs have enhanced the network boot support package
to support the following syntax for arguments to be pro-
cessed by the package:
[protocol,] [key=value,]*
All arguments are optional and can appear in any order. Com-
mas 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 configura-
tion information provided by a DHCP server for those parame-
ters.
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 or URL for WAN boot
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 pro-
cessed 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, or the URL if using HTTP. The use of HTTP is trig-
gered if the file name is a URL, that is, the file name
starts with http: (case-insensitive).
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 con-
structed from the root node's name property, with commas (,)
replaced by periods (.).
When specified on the command line, the filename must not
contain slashes (/).
The format of URLs is described in RFC 2396. The HTTP server
must be specified as an IP address (in standard IPv4
dotted-decimal notation). The optional port number is speci-
fied in decimal. If a port is not specified, port 80
(decimal) is implied.
The URL presented must be "safe-encoded", that is, the pack-
age does not apply escape encodings to the URL presented.
URLs containing commas must be presented as a quoted string.
Quoting URLs is optional otherwise.
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 nota-
tion) is the subnet mask on the client's network. If the
subnet mask is not provided (either by means of this argu-
ment 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 identif-
ier, or
o a quoted string
Thus, client-id="openboot" and client-id=6f70656e626f6f74
both represent a DHCP client identifier of
006F70656E626F6F74.
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 sub-
net 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 pre-
cedence over any other DHCP mechanism of specifying identif-
iers.
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 environ-
ments 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, primary boot and secondary
boot. The primary boot is implemented in the BIOS ROM on the
system board, and BIOS extensions in ROMs on peripheral
boards. It is distinguished by its ability to control the
installed peripheral devices and to provide I/O services
through software interrupts. It begins the booting process
by loading the first physical sector from a floppy disk,
hard disk, or CD-ROM, or, if supported by the system or net-
work adapter BIOS, by reading a bootstrap program from a
network boot server. The primary boot is implemented in x86
real-mode code.
The secondary boot is loaded by the primary boot. It is
implemented in 32-bit, paged, protected mode code. It also
loads and uses peripheral-specific BIOS extensions written
in x86 real-mode code. The secondary boot is called boot.bin
and is capable of reading and booting from a UFS file system
on a hard disk or a CD or by way of a LAN using the NFS pro-
tocol.
The secondary boot is responsible for running the Configura-
tion Assistant program which determines the installed dev-
ices in the system (possibly with help from the user). The
secondary boot then reads the script in /etc/bootrc, which
controls the booting process. This file contains boot
interpreter commands, which are defined below, and can be
modified to change defaults or to adapt to a specific
machine.
The standard /etc/bootrc script prompts the user to enter a
b character to boot with specified options, or an i charac-
ter to invoke the interpreter interactively. Pressing
<ENTER> without entering a character boots the default ker-
nel. All other responses are considered errors and cause the
script to restart.
Once the kernel is loaded, it starts the operating system,
loads the necessary modules, mounts the necessary file sys-
tems (see vfstab(4)), and runs /sbin/init to bring the sys-
tem to the ``initdefault'' state specified in /etc/inittab.
See inittab(4).
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 boot-
ing kadb(1M) since, by default, kadb loads the
default-file as exported by the boot program.
-f When booting an Autoclient system, this flag forces
the boot program to bypass the client's local cache
and read all files over the network from the client's
file server. This flag is ignored for all non-
Autoclient systems. The -f flag is then passed to the
standalone program.
-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
kadb(1M) 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. On most systems, the
default filename is the 32-bit kernel. On systems
capable of supporting both the 32-bit and 64-bit ker-
nels, the 64-bit kernel will be chosen in preference
to the 32-bit kernel. boot chooses an appropriate
default file to boot based on what software is
installed on the system, the capabilities of the
hardware and firmware, and on a user configurable pol-
icy file.
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.
x86
The following x86 options are supported:
-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 boot-
ing kadb(1M) since, by default, kadb loads the
default-file as exported by the boot program.
-f When booting an Autoclient system, this flag forces
the boot program to bypass the client's local cache
and read all files over the network from the client's
file server. This flag is ignored for all non-
Autoclient systems. The -f flag is then passed to the
standalone program.
boot-args
The boot program passes all boot-args to file. They
are not interpreted by boot. See kernel(1M) and
kadb(1M) for information about the options available
with the kernel.
file Name of a standalone program to boot. The default is
to boot /platform/platform-name/kernel/unix from the
root partition, but you can specify another program on
the command line.
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 floppy disk contains the master boot
block. The boot block is responsible for loading the image
of the boot loader strap.com, which then loads the secondary
boot, boot.bin. A similar sequence occurs for CD-ROM boot,
but the master boot block location and contents are dictated
by the El Torito specification. The El Torito boot also
leads to strap.com, which in turn loads boot.bin.
The first sector on a hard disk contains the master boot
block, which contains the master boot program and the FDISK
table, named for the PC program that maintains it. The mas-
ter boot finds the active partition in the FDISK table,
loads its first sector, and jumps to its first byte in
memory. This completes the standard PC-compatible hard disk
boot sequence.
An x86 FDISK partition for the Solaris software begins with
a one-cylinder boot slice, which contains the partition boot
program (pboot) in the first sector, the standard Solaris
disk label and volume table of contents (VTOC) in the second
and third sectors, and the bootblk program in the fourth and
subsequent sectors. When the FDISK partition for the Solaris
software is the active partition, the master boot program
(mboot) reads the partition boot program in the first sector
into memory and jumps to it. It in turn reads the bootblk
program into memory and jumps to it. Regardless of the type
of the active partition, if the drive contains multiple
FDISK partitions, the user is given the opportunity to
reboot another partition.
bootblk or strap.com (depending upon the active partition
type) reads boot.bin from the file system in the Solaris
root slice and jumps to its first byte in memory.
For network booting, you have the choice of the boot floppy
or Intel's Preboot eXecution Environment (PXE) standard.
When booting from the network using the boot floppy, you can
select which network configuration strategy you want by
editing the boot properties, changing the setting for net-
config-strategy. By default, net-config-strategy is set to
rarp. It can have two settings, rarp or dhcp. When booting
from the network using PXE, the system or network adapter
BIOS uses DHCP to locate a network bootstrap program (NBP)
on a boot server and reads it using Trivial File Transfer
Protocol (TFTP). The BIOS executes the NBP by jumping to its
first byte in memory. The NBP uses DHCP to locate the secon-
dary bootstrap on a boot server, reads it using TFTP, and
executes it.
x86 Secondary Boot
The secondary boot, boot.bin, switches the processor to 32-
bit, paged, protected mode, and performs some limited
machine initialization. It runs the Configuration Assistant
program which either auto-boots the system, or presents a
list of possible boot devices, depending on the state of the
auto-boot? variable (see eeprom(1M)).
Disk target devices (including CDROM drives) are expected to
contain UFS file systems. Network devices can be configured
to use either DHCP or Reverse Address Resolution Protocol
(RARP) and bootparams RPC to discover the machine's IP
address and which server will provide the root file system.
The root file system is then mounted using NFS. After a suc-
cessful root mount, boot.bin invokes a command interpreter,
which interprets /etc/bootrc.
Secondary Boot Programming Language for x86
The wide range of hardware that must be supported on x86
based systems demands great flexibility in the booting pro-
cess. This flexibility is achieved in part by making the
secondary boot programmable. The secondary boot contains an
interpreter that accepts a simple command language similar
to those of sh and csh. The primary differences are that
pipelines, loops, standard output, and output redirection
are not supported.
x86 Lexical Structure
The boot interpreter splits input lines into words separated
by blanks and tabs. The metacharacters are dollar sign ($),
single-quote ('), double-quote ("), number sign (#), new-
line, and backslash (\). The special meaning of metacharac-
ters can be avoided by preceding them with a backslash. A
new-line preceded by a backslash is treated as a blank. A
number sign introduces a comment, which continues to the
next new-line.
A string enclosed in a pair of single-quote or double-quote
characters forms all or part of a single word. White space
and new-line characters within a quoted string become part
of the word. Characters within a quoted string can be quoted
by preceding them with a backslash character; thus a
single-quote character can appear in a single-quoted string
by preceding it with a backslash. Two backslashes produce a
single backslash, and a new-line preceded by a backslash
produces a new-line in the string.
x86 Variables
The boot maintains a set of variables, each of which has a
string value. The first character of a variable name must be
a letter, and subsequent characters can be letters, digits,
or underscores. The set command creates a variable and/or
assigns a value to it, or displays the values of variables.
The unset command deletes a variable.
Variable substitution is performed when the interpreter
encounters a dollar-sign that is not preceded by a
backslash. The variable name following the dollar sign is
replaced by the value of the variable, and parsing continues
at the beginning of the value. Variable substitution is per-
formed in double-quoted strings, but not in single-quoted
strings. A variable name can be enclosed in braces to
separate it from following characters.
x86 Commands
A command is a sequence of words terminated by a new-line
character. The first word is the name of the command and
subsequent words are arguments to the command. All commands
are built-in commands. Standalone programs are executed with
the run command.
x86 Conditional Execution of Commands
Commands can be conditionally executed by surrounding them
with the if, elseif, else, and endif commands:
if expr1
...
elseif expr2
...
elseif expr3
...
else
...
endif
An if block may be embedded in other if blocks.
x86 Expressions
The set, if, and elseif commands evaluate arithmetic expres-
sions with the syntax and semantics of the C programming
language. The ||, &&, |, ^, &, ==, !=, <, >, <=, >=, >>, <<,
+, -, *, /, %, ~, and ! operators are accepted, as are (, ),
and comma. Signed 32-bit integer arithmetic is performed.
Expressions are parsed after the full command line has been
formed. Each token in an expression must be a separate argu-
ment word, so blanks must separate all tokens on the command
line.
Before an arithmetic operation is performed on an operand
word, it is converted from a string to a signed 32-bit
integer value. After an optional leading sign, a leading 0
produces octal conversion and a leading 0x or 0X produces
hexadecimal conversion. Otherwise, decimal conversion is
performed. A string that is not a legal integer is con-
verted to zero.
Several built-in functions for string manipulation are pro-
vided. Built-in function names begin with a dot. String
arguments to these functions are not converted to integers.
To cause an operator, for example, -, to be treated as a
string, it must be preceded by a backslash, and that
backslash must be quoted with another backslash. Also be
aware that a null string can produce a blank argument, and
thus an expression syntax error. For example:
if .strneq ( ${usrarg}X , \- , 1 )
is the safe way to test whether the variable usrarg starts
with a -, even if it could be null.
x86 I/O
The boot interpreter takes its input from the system console
or from one or more files. The source command causes the
interpreter to read a file into memory and begin parsing it.
The console command causes the interpreter to take its input
from the system console. Reaching EOF causes the interpreter
to resume parsing the previous input source. CTRL-D entered
at the beginning of console line is treated as EOF.
The echo command writes its arguments to the display. The
read command reads the system console and assigns word
values to its argument variables.
x86 Debugging
The verbose command turns verbose mode on and off. In ver-
bose mode, the interpreter displays lines from the current
source file and displays the command as actually executed
after variable substitution.
The singlestep command turns singlestep mode on and off. In
singlestep mode, the interpreter displays step ? before pro-
cessing the next command, and waits for keyboard input,
which is discarded. Processing proceeds when ENTER is
pressed. This allows slow execution in verbose mode.
x86 Initialization
When the interpreter is first invoked by the boot, it begins
execution of a compiled-in initialization string. This
string typically consists of "source /etc/bootrc\n" to run
the boot script in the root file system.
x86 Communication With Standalone Programs
The boot passes information to standalone programs through
arguments to the run command. A standalone program can pass
information back to the boot by setting a boot interpreter
variable using the var_ops() boot service function. It can
also pass information to the kernel using the setprop() boot
service function. The whoami property is set to the name of
the standalone program.
x86 Built-in Commands
console
Interpret input from the console until CTRL-D.
echo arg1 ...
Display the arguments separated by blanks and ter-
minate with a new-line.
echo -n arg1 ...
Display the arguments separated by blanks, but do not
terminate with a new-line.
getprop propname varname
Assign the value of property propname to the variable
varname. A property value of length zero produces a
null string. If the property does not exist, the vari-
able is not set.
getproplen propname varname
Assign the length in hexadecimal of the value of pro-
perty propname to the variable varname. Property value
lengths include the terminating null. If the property
does not exist, the variable is set to 0xFFFFFFFF (-
1).
if expr
If the expression expr is true, execute instructions
to the next elseif, else, or endif. If expr is false,
do not execute the instructions.
elseif expr
If the preceding if and elseif commands all failed,
and expr is true, execute instructions to the next
elseif, else, or endif. Otherwise, do not execute the
instructions.
else If the preceding if and elseif commands all failed,
execute instructions to the next elseif, else, or
endif. Otherwise, do not execute the instructions.
endif Revert to the execution mode of the surrounding block.
help Display a help screen that contains summaries of all
available boot shell commands.
read name1 ...
Read a line from the console, break it into words, and
assign them as values to the variables name1, and so
forth.
readt time ...
Same as read, but timeout after time seconds.
run name arg1 ...
Load and transfer control to the standalone program
name, passing it arg1 and further arguments.
set Display all the current variables and their values.
set name
Set the value of the variable name to the null string.
set name word
Set the value of the variable name to word.
set name expr
Set the value of the variable name to the value of
expr. expr must consist of more than one word. The
value is encoded in unsigned hexadecimal, so that -1
is represented by 0xFFFFFFFF.
setcolor
Set the text mode display attributes. Allowable colors
are black, blue, green, cyan, red, magenta, brown,
white, gray, lt_blue, lt_green, lt_cyan, lt_red,
lt_magenta, yellow, and hi_white.
setprop propname word
Set the value of the property propname to word.
singlestep or singlestep on
Turn on singlestep mode, in which the interpreter
displays step ? before each command is processed, and
waits for keyboard input. Press ENTER to execute the
next command.
singlestep off
Turn off singlestep mode.
source name
Read the file name into memory and begin to interpret
it. At EOF, return to the previous source of input.
unset name
Delete the variable name.
verbose or verbose on
Turn on verbose mode, which displays lines from source
files and commands to be executed.
verbose off
Turn off verbose mode.
x86 Built-in Functions
The following built-in functions are accepted within expres-
sions:
.strcmp(string1, string2)
Returns an integer value that is less than, equal to,
or greater than zero, as string1 is lexicographically
less than, equal to, or greater than string2.
.strncmp(string1, string2, n)
Returns an integer value that is less than, equal to,
or greater than zero, as string1 is lexicographically
less than, equal to, or greater than string2. At most,
n characters are compared.
.streq (string1, string2)
Returns true if string1 is equal to string2, and false
otherwise.
.strneq (string1, string2, n)
Returns true if string1 is equal to string2, and false
otherwise. At most, n characters are compared.
.strfind (string, addr, n)
Scans n locations in memory starting at addr, looking
for the beginning of string. The string in memory need
not be null-terminated. Returns true if string is
found, and false otherwise. .strfind can be used to
search for strings in the ROM BIOS and BIOS extensions
that identify different machines and peripheral
boards.
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
32-bit SPARC
Example 2: To Boot kadb Specifying The 32-Bit Kernel As The
Default File
To boot kadb specifying the 32-bit kernel as the default
file:
boot kadb -D kernel/unix
Example 3: To Boot the 32-Bit Kernel Explicitly
To boot the 32-bit kernel explicitly, the kernel file name
should be specified. So, to boot the 32-bit kernel in
single-user interactive mode, respond to the ok prompt with
one of the following:
boot kernel/unix -as
boot disk3 kernel/unix -as
64-bit SPARC
Example 4: To Boot the 64-Bit Kernel Explicitly
To boot the 64-bit kernel explicitly, the kernel file name
should be specified. So, to boot the 64-bit kernel in
single-user interactive mode, respond to the ok prompt with
one of the following:
boot kernel/sparcv9/unix -as
boot disk3 kernel/sparcv9/unix -as
Refer to the NOTES section "Booting UltraSPARC Systems"
before booting the 64-bit kernel using an explicit filename.
Example 5: Network Booting with WAN Boot-Capable PROMs
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 net-
work 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 argu-
ments in network-boot-arguments.
boot net:speed=100,duplex=full
Example 6: Using wanboot with Older PROMs
The command below results in the wanboot binary being loaded
from CD-ROM, at which time wanboot will perform DHCP and
then drop into its command interpreter to allow the user to
enter keys and any other necessary configuration.
boot cdrom -F wanboot -o dhcp,prompt
x86
Example 7: To Boot the Default Kernel In Single-User
Interactive Mode
To boot the default kernel in single-user interactive mode,
respond to the > prompt with one of the following:
b -as
b kernel/unix -as
FILES
/platform/platform-name/ufsboot
second level program to boot from a disk or CD.
/etc/inittab
table in which the "initdefault" state is speci-
fied.
/sbin/init
program that brings the system to the "initde-
fault" state.
/platform/platform-name/boot.conf
/platform/hardware-class-name/boot.conf
Primary and alternate pathnames for the boot pol-
icy file. Note that the policy file is not imple-
mented on all platforms.
32-bit SPARC and x86
/platform/platform-name/kernel/unix
default program to boot system.
64-bit SPARC only
/platform/platform-name/kernel/sparcv9/unix
default program to boot system.
See NOTES section "Booting UltraSPARC Systems."
x86 Only
/etc/bootrc
script that controls the booting process.
/platform/platform-name/boot/solaris/boot.bin
second level boot program used on x86 systems in place
of ufsboot.
/platform/platform-name/boot
directory containing boot-related files.
SEE ALSO
uname(1), eeprom(1M), init(1M), installboot(1M), kadb(1M),
kernel(1M), monitor(1M), shutdown(1M), uadmin(2), boot-
params(4), inittab(4), vfstab(4), wanboot.conf(4), filesys-
tem(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 Syn-
tax, http://www.ietf.org/rfc/rfc2396.txt
System Administration Guide: Basic Administration
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).
64-bit SPARC
Booting UltraSPARC Systems
Certain platforms may need a firmware upgrade to run the
64-bit kernel. See the Sun Hardware Platform Guide for
details. If the 64-bit kernel packages are installed and
boot detects that the platform needs a firmware upgrade to
run 64-bit, boot displays a message on the console and
chooses the 32-bit kernel as the default file instead.
On systems containing 200MHz or lower UltraSPARC-1 proces-
sors, it is possible for a user to run a 64-bit program
designed to exploit a problem that could cause a processor
to stall. Because 64-bit progams cannot run on the 32-bit
kernel, the 32-bit kernel is chosen as the default file on
these systems.
The code sequence that exploits the problem is very unusual
and is not likely to be generated by a compiler. Assembler
code had to be specifically written to demonstrate the prob-
lem. It is highly unlikely that a legitimate handwritten
assembler routine would use this code sequence.
Users willing to assume the risk that a user might acciden-
tally or deliberately run a program that was designed to
cause a processor to stall may choose to run the 64-bit ker-
nel by modifying the boot policy file. Edit
/platform/platform-name/boot.conf so that it contains an
uncommented line with the variable named
ALLOW_64BIT_KERNEL_ON_UltraSPARC_1_CPU set to the value true
as shown in the example that follows:
ALLOW_64BIT_KERNEL_ON_UltraSPARC_1_CPU=true
For more information, see the Sun Hardware Platform Guide.
x86 Only
Because the ``-'' key on national language keyboards has
been moved, an alternate key must be used to supply argu-
ments to the boot command on an x86 based system using these
keyboards. Use the ``-'' on the numeric keypad. The specific
language keyboard and the alternate key to be used in place
of the ``-'' during bootup is shown below.
Keyboard
Substitute Key
Italy '
Spain '
Sweden
+
France
?
Germany
?
For example, b -r would be typed as b +r on Swedish key-
boards, although the screen display will show as b -r.
Man(1) output converted with
man2html