Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

boot(8)

Name

boot - start the system kernel or a standalone program

Synopsis

SPARC

boot [OBP names] [file] [-aLV] [-F object] [-D default-file]
     [-Z dataset] [-B prop [=val]]
     [boot-flags] [−−] [client-program-args]

x86

kernel$ root_path/platform/i86pc/amd64/kernel/unix
     /platform/i86pc/amd64/kernel/unix [boot-args]
     [-B prop=[val]] [,prop[=[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(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.

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(5)), and runs /usr/sbin/init to bring the system to the “initdefault” state specified in /etc/inittab. See inittab(5).

Verified Boot

Verified boot in Oracle Solaris secures a system's boot process. The feature protects the system from threats such as the following:

  • Corruption of kernel modules

  • Insertion or substitution of malicious programs that masquerade as legitimate kernel modules, such as Trojan viruses, spyware, and rootkits

  • Installation of unauthorized third-party kernel modules

Malicious programs can pass information to third parties as well as alter the behavior of Oracle Solaris. Although third-party modules are typically non-malicious, they might violate policies that control site changes. Therefore, the system also needs protection from unauthorized installation of these modules.

Starting in this release, a firmware upgrade for some SPARC platforms may be required to use verified boot. For more information, see the section Firmware Upgrade Needed for Verified Boot in Securing Systems and Attached Devices in Oracle Solaris 11.4.

In Oracle Solaris, verified boot is configurable not only on systems but also on Kernel Zones and LDOMS.


Note -  By default, any domain created by using a version of Oracle VM Server for SPARC earlier than version 3.4 sets boot-policy=warning. If the kernel module is unsigned or corrupted, this setting results in warning messages being issued while the domain boots after an Oracle VM Server for SPARC update.

For more information on verified boot, see the Using Verified Boot section in Securing Systems and Attached Devices in Oracle Solaris 11.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(8) 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 filesystem-specific boot block (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 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 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(5)) 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(8)), 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. The WAN boot process can be configured to use either DHCP or NVRAM properties to discover the install server and router and the proxies needed to connect to it. When wanboot begins executing, it determines whether sufficient 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 wanboot has obtained the necessary information, it loads the boot loader into memory by means of HTTP. If an encryption key has been installed on the client, wanboot will verify the boot loader's signature and its accompanying hash. Presence of an encryption key but no hashing key is an error.

The wanboot boot loader can communicate with the client using either HTTP or secure HTTP. If the former, and if the client has been configured with an HMAC SHA-1 key, the boot loader will perform an integrity check of the root file system. Once the root file system has been loaded into memory (and possibly had an integrity check performed), the boot archive is transferred from the server. If provided with a boot_logger URL by means of the wanboot.conf(5) file, wanboot will periodically log its progress.

Not all PROMs are capable of consuming URLs. You can determine whether a client is so capable using the list-security-keys OBP command (see monitor(8)).

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 consists 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 characters)

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

quiet

Does not print progress messages to the console during wanbootfs and miniroot download. This reduces the likelihood of TCP retransmissions in these early stage downloads, which can significantly increase the download time.

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.

iSCSI Boot

iSCSI boot is supported on both x86 and SPARC.

iSCSI Boot on x86

For iSCSI boot 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.

iSCSI Boot on SPARC

iSCSI boot on SPARC is supported with OpenBoot level 4.31 and above, and does not require a specific NIC.

The boot command in OpenBoot takes a series of keywords to identify the destination iSCSI target, following the keyword=value format. The complete form of the iSCSI boot command is:

boot net:iscsi-target-ip=t-ip,iscsi-target-name=name
     host-ip=h-ip[,router-ip=r-ip]
     [,subnet-mask=m-ip]
     [,iscsi-port=port]
     [,iscsi-lun=lun]
     [,iscsi-partition=partition]

The descriptions of the preceding keywords are as follows:

host-ip

IP address of booting host.

router-ip

IP address of routing gateway.

subnet-mask

Subnet mask of host-ip.

iscsi-target-ip

IP address of iSCSI target storing OS.

iscsi-target-name

Name of iSCSI target storing OS.

iscsi-partition

Partition containing the bootable root.

iscsi-port

IP port of the target.

iscsi-lun

LUN to be booted off on target.

The values of iscsi-target-ip, route-ip, and subnet-mask are in standard, IPv4 dotted-decimal format; for example, 255.255.255.0 for subnet-mask. IPv6 is not supported in the current OpenBoot implementation.

The value of iscsi-port, a decimal number, is in the range of 1 to 65535.

The value of iscsi-lun is in the format of a dashed hexadecimal LUN, ffff-ffff-ffff-ffff. Please refer to section 5 of RFC 4173 for details. Leading zeroes and trailing dashes can be excluded, thus, 3, for example, is equivalent to 0003-0000-0000-0000.

The value of iscsi-partition is one ASCII character, used to specify the root partition. Most commonly, it is a.

The value of iscsi-target-name is in the format of a string, as specified by RFC 3720 and RFC 3722.

Two security keys are added to provide CHAP authentication on the target side. These are:

chap-user

CHAP name

chap-password

CHAP secret

Currently these two keys can be set with the command set-ascii-security-key at the Open Boot PROM (ok) prompt. For example:

ok set-ascii-security-key chap-user chap name
ok set-ascii-security-key chap-password chap password

Bi-directional authentication is not yet supported. These two variables can be changed only under the Open Boot PROM prompt.

RFC 4173 is supported, to retrieve iSCSI boot information from a DHCP server. The DHCP server must specify the Root Path option for the booting client, after which the client can do an iSCSI boot by means of the simple command:

boot net:dhcp

Currently the key boot-device is used to retrieve the physical boot device path during iSCSI boot. This key is setup during Oracle Solaris installation. A manually modified key value might break iSCSI boot.

Booting from Disk

When booting from disk, the OpenBoot PROM firmware reads the boot blocks from the partition specified as the boot device. This standalone booter usually contains a file 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(7). 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, Oracle 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. Use the –L option to list the bootable datasets within a ZFS pool.

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.

When executing a WAN boot from a local (CD or DVD) 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 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 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:

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

  • 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, or the URL if using HTTP. The use of HTTP is triggered 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 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 (/).

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 specified in decimal. If a port is not specified, port 80 (decimal) is implied.

The URL presented must be “safe-encoded”, that is, the package 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 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:

  • The ASCII hexadecimal representation of the identifier, or

  • 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 address (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 GRUB (GRand Unified Bootloader) using the firmware on the system board and firmware extensions in ROMs on peripheral boards. The system firmware loads GRUB. The loading mechanism differs, depending on the type of system firmware that is shipped on the system board.

For systems with BIOS firmware, the first physical sector of a hard disk (known as the boot sector) is loaded into memory and its code executed. Traditionally, this code has inspected the DOS partition table, has found the partition marked as the active one, and has loaded the first sector from that partition into memory, and (finally) has executed that code. Disks that are partitioned with the GPT (GUID Partition Table) must have boot sector code that behaves differently, loading code from another location (because the GPT scheme does not reserve the first sector of each partition for boot sector code storage). In the case of GRUB running on BIOS firmware, that other location is a dedicated partition known as the BIOS Boot Partition. Once GRUB's boot sector code loads the rest of GRUB into memory, the boot process continues in earnest. Booting from a DVD, the firmware's reading special data structures (defined by the El Torito Bootable CD Specification) from the disc and loading sectors from the DVD into memory, as defined by those structures. These sectors comprise the first stage boot program. This boot program then loads the next stage, which, in the case of Oracle Solaris, is GRUB itself. Booting from the network is yet a different process on BIOS systems. Bootable network adapters include firmware that complies with the PXE (Preboot eXecution Environment) specification. When activated, the PXE firmware performs a DHCP exchange on the network, and downloads the BootFile that the DHCP server included in the DHCP response from the TFTP server that is also in the DHCP response. For Oracle Solaris, this BootFile (pxegrub2, or equivalent) is GRUB itself. GRUB then proceeds, ultimately, to download the UNIX kernel and the boot archive (see below), loads them into memory, and transfers control to UNIX.

For systems with UEFI-based firmware, the boot process is quite different. The UEFI firmware looks for the EFI System Partition (ESP) on disks that it has enumerated, and loads and executes UEFI boot programs according to a UEFI-specification-defined process. The net result is that a UEFI boot application is loaded into memory and executed. For Oracle Solaris, that UEFI boot application is GRUB, which has been specifically built to run as a UEFI boot application. The boot process then continues largely as it does on systems with BIOS firmware. Booting from a DVD also involves a search for a UEFI boot application, but the search method is quite different and uses data structures on the DVD defined by the El Torito Bootable CD Specification. The UEFI specification defines how the El Torito specification is used to locate UEFI boot applications. The boot process for network boot on a UEFI system is very similar to that of a BIOS system, except that UEFI systems make a slightly different DHCP request, which provides the DHCP server enough information to customize the BootFile that is returned for the UEFI system. Recall that UEFI systems require UEFI boot applications, not BIOS-targeted boot programs, which would otherwise be returned as the BootFile from the DHCP server. Once the UEFI boot application (which is GRUB itself) specified in the BootFile (grub2netx64.efi, or equivalent) is downloaded to the UEFI client, it (GRUB) is executed. As with the BIOS network boot process, GRUB downloads the UNIX kernel and boot archive from the DHCP-specified TFTP server, loads them into memory, then transfers control to UNIX.

Once GRUB is running, it executes script commands in its configuration file, grub.cfg, and, when directed to do so, loads the Oracle Solaris kernel (UNIX kernel) and a pre-constructed boot archive that contains kernel modules and essential data required for boot.

If the device identified by GRUB as the boot device contains a ZFS storage pool, the grub.cfg file used to create the GRUB menu will be found in the pool's top level dataset. (This is the dataset with the same name as the pool itself.) There is always exactly one such dataset in a pool, so this dataset is well-suited for pool-wide data such as the GRUB configuration files and data. 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 root file system in a pool is identified by the pool's bootfs property (see zpool(8)). If a specific bootfs (file system consistent with the naming scheme /root/name) is not specified (by means of the zfs-bootfs command in a GRUB menuentry block in the grub.cfg), the default bootfs root file system is used. Each GRUB menu entry may specify the bootfs to use, enabling the administrator to select from many bootable Oracle Solaris instances in a pool.

Kernel initialization starts when GRUB finishes loading the boot archive and hands control over to the unix binary. At this point, GRUB becomes inactive and no more I/O occurs with the boot device. 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(5)), and starts various operating system services (see smf(7)).

Enabling Automatic Rebooting (x86)

The Oracle Solaris operating system supports an smf(7) property that enables a system to automatically reboot from the current boot device, to recover from conditions such as an out-of-date boot archive.

The service svc:/system/boot-config:default contains the boolean property auto-reboot-safe, which is set to false by default. Setting it to true communicates that both the system's firmware and default GRUB menu entry are set to boot from the current boot device. The value of this property can be changed using svccfg(8) and svcadm(8). For example, to set auto-reboot-safe to enable automatic rebooting, enter a command such as:

example# svccfg -s svc:/system/boot-config:default \
      setprop config/auto-reboot-safe = true

Most systems are configured for automatic reboot from the current boot device. However, in some instances, automatic rebooting to an unknown operating system might produce undesirable results. For these instances, the auto-reboot-safe property allows you to specify the behavior you want.

Failsafe Mode

A requirement of booting from a root filesystem image built into a boot archive then remounting root onto the actual root device is that the contents of the boot archive and the root filesystem must be consistent. Otherwise, the proper operation and integrity of the machine cannot be guaranteed.

The term “consistent” means that all files and modules in the root filesystem are also present in the boot archive and have identical contents. Since the boot strategy requires first reading and mounting the boot archive as the first-stage root image, all unloadable kernel modules and initialization derived from the contents of the boot archive are required to match the real root filesystem. Without such consistency, it is possible that the system could be running with a kernel module or parameter setting applied to the root device before reboot, but not yet updated in the root archive. This inconsistency could result in system instability or data loss.

Once the root filesystem is mounted, and before relinquishing the in-memory filesystem, Oracle Solaris performs a consistency verification against the two file systems. If an inconsistency is detected, Oracle Solaris will automatically try to fix it and reboot into the same boot environment. If this fails (or if the system is an x86 machine that does not support fast reboot and has auto-reboot-safe not set to true), then the failsafe mode will be entered. Correcting the inconsistency requires the administrator take one of two steps. The recommended procedure is to reboot to a boot environment known to be consistent and rebuild the boot archive. This ensures that a known kernel is booted and functioning for the archive rebuild process. Alternatively, the administrator can elect to clear the inconsistent boot archive service state and continue system bring-up if the inconsistency is such that correct system operation will not be impaired. See svcadm(8).

If the boot archive service is cleared and system bring-up is continued (the second alternative above), the system may be running with unloadable kernel drivers or other modules that are out-of-date with respect to the root filesystem. As such, correct system operation may be compromised.

To ensure that the boot archive is consistent, the normal system shutdown process, as initiated by reboot(8) and shutdown(8), checks for and applies updates to the boot archive at the conclusion of the umountall milestone.

An update to any kernel file, driver, module or driver configuration file that needs to be included in the boot archive after the umountall service is complete will result in a failed boot archive consistency check during the next boot. To avoid this, it is recommended to always shut down a machine cleanly.

If an update is required to the kernel after completion of the umountall service, the administrator may elect to rebuild the archive by invoking:

# bootadm update-archive

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.

–B prop[=[val]]...

One or more properties, optionally with values to be passed to the kernel. Multiple properties may be supplied with separate –B options or separated by a comma. Properties without values are treated as boolean. Property names must meet the requirements of IEEE 1275-1994.

–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 or wanboot 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(8) 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 an Oracle T3-2 system, /pci@400/pci@1/pci@0/pci@4/scsi@0/disk@w5000cca0153966b9,0 refers to LUN 0 of a SAS disk attached to the onboard SAS controller.

–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 properties, optionally with values to be passed to the kernel. Multiple properties may be supplied with separate –B options or separated by a comma. Properties without values are set to "true". Use of this option is the equivalent of the command: eeprom prop=val. See eeprom(8) for available properties and valid values.

boot-args

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

Unless otherwise specified, an x86 system will boot /platform/i86pc/kernel/amd64/unix.

x86 BOOT SEQUENCE DETAILS

After a PC-compatible machine is turned on, the system firmware executes a power-on self test (POST), runs BIOS extensions in peripheral board ROMs, and locates and installs firmware extensions from peripheral board ROMs, and begins the boot process through a firmware-specific mechanism.

For BIOS systems, software interrupt INT 19h is executed. The INT 19h handler typically performs the standard PC-compatible boot, which consists of trying to read the first physical sector from the first hard disk. The processor then jumps to the first byte of the sector image in memory.

For UEFI firmware, the process is quite different, as previously explained in the “x86 Bootstrap Procedure” section, above.

x86 Primary BIOS Boot

The first sector on a disk medium contains the master boot record (which is either GRUB's first stage loader if GRUB is installed in the MBR, or another boot loader). This code is responsible for loading the next stage boot loader. For GRUB, that means loading the rest of GRUB into memory. Once that is done, GRUB is fully functional. It locates the GRUB prefix (the directory that contains the GRUB configuration file and GRUB loadable modules) and reads and executes the GRUB configuration file /boot/grub/grub.cfg. A similar sequence occurs for DVD or CD boot, but the master boot record location and contents are dictated by the El Torito specification (as previously described).

The first sector on a hard disk contains the master boot record (MBR), which contains the master boot program and the DOS partition table (also referred to as the FDISK table, named for the program that maintained it in DOS). If the disk is partitioned with the GPT scheme, the master boot program must be specialized to load the next stage boot loader into memory from a safe location on the disk. That safe location, in the case of GRUB, is a special GPT partition called the BIOS Boot Partition (BBP). This partition does not contain a file system, just empty space in which the second stage portion of GRUB can reside. It is from the BBP that the master boot program completes GRUB's loading.

If the disk is partitioned with the traditional DOS scheme, the master boot program finds the active partition in the DOS partition table, loads its first sector, and jumps to that which it loaded into memory. This completes the standard PC-compatible hard disk boot sequence. If GRUB's first stage is installed in the MBR (see the –m option of the bootadm(8) install-bootloader subcommand), then the remainder of GRUB is loaded directly from the Oracle Solaris DOS partition, regardless of the active partition.

The Oracle Solaris DOS partition begins with a one-cylinder boot slice, which contains GRUB's first stage loader in the first sector, the standard Oracle Solaris disk label and volume table of contents (VTOC) in the second and third sectors, and the GRUB second stage loader in the fiftieth and subsequent sectors. The area from sector 4 to 49 is unused (because it had been used to store boot blocks for older versions of Oracle Solaris). When the DOS partition for the Oracle Solaris software is the active partition, the master boot program (mboot, the generic master boot program) loads the partition boot program from the Oracle Solaris partition's first sector into memory and jumps to it. It, in turn, reads GRUB's second stage loader into memory and jumps to it. Once the GRUB menu is displayed, the user can choose to boot an operating system on a different partition, a different disk, or possibly from the network (provided the proper firmware support is present).

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 (pxegrub2) on a boot server and reads it using Trivial File Transfer Protocol (TFTP). The BIOS executes the pxegrub2 by jumping to its first byte in memory. The pxegrub program downloads a configuration file and presents the entries to user.

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 Oracle Solaris Install/Upgrade process in /boot/solaris/bootenv.rc and can be overridden with the –B option, described above (see the eeprom(8) man page).

When booting from ZFS, the root device is specified by a set of boot parameters specified on the multiboot command line in the GRUB menuentry. These boot parameters are synthesized by the GRUB zfs-bootfs command and are stored in the GRUB environment variable whose name is specified as the second argument to zfs-bootfs. This variable is then supplied, along with the –B kernel argument to pass vital ZFS parameters that identify the root filesystem to the kernel. (The previous version of Oracle Solaris GRUB used the substitution macro $ZFS-BOOTFS for this purpose. This is no longer supported, because $ZFS-BOOTFS is not a valid GRUB variable name.)

If the console is not specified as a kernel argument, the console is derived from the /boot/solaris/bootenv.rc on the root file system of the Oracle Solaris instance that is being booted. If no console variable is present in that file, the default console device is set to the graphical text console, and system keyboard (USB and PS/2 keyboards are supported).

It is important to note that the Oracle Solaris console can be configured differently from the GRUB console. For example, the GRUB console can be configured (see bootadm(8)'s set-menu subcommand) to use the screen and keyboard, while Oracle Solaris uses the serial port. The console transition will occur when GRUB transfers control to Oracle Solaris when the menu entry is booted.

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 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 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
Example 3 Using wanboot with Older PROMs

The command below results in the wanboot binary being loaded from DVD or CD, 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 4 To Boot the Default Kernel in Single-User Interactive Mode

To boot the default kernel in single-user interactive mode, edit the GRUB multiboot2 command line to read:

multiboot2 root_path/platform/i86pc/kernel/amd64/unix \
/platform/i86pc/kernel/amd64/unix -as

Files

/etc/inittab

Table in which the initdefault state is specified

/usr/sbin/init

Program that brings the system to the initdefault state

SPARC Only

/platform/platform-name/kernel/sparcv9/unix

Default program to boot system.

x86 Only

/boot

Directory containing boot-related files.

/rpool/boot/grub/grub.cfg

Menu of bootable operating systems displayed by GRUB. /rpool is a common convention. The pathname is configurable, depending on the capabilities of your installer. This file should never be edited directly, as it is auto-generated without notice. For an administrator-editable file, see custom.cfg, listed below.

/rpool/boot/grub/custom.cfg

Administrator-customizable supplemental GRUB configuration file. This file is “sourced” by grub.cfg after all other system-generated grub.cfg content is processed. This file will never be automatically overwritten, and can contain any valid GRUB configuration file syntax.

/rpool/boot/grub/menu.conf

Data file used by the Oracle Solaris boot administration infrastructure to store details of boot loader configuration that is ultimately used to build the GRUB configuration file (grub.cfg).

/platform/i86pc/kernel/amd64/unix

Default program to boot system.

See Also

kmdb(1), uname(1), uadmin(2), bootparams(5), inittab(5), vfstab(5), wanboot.conf(5), attributes(7), filesystem(7), smf(7), bootadm(8), eeprom(8), init(8), kernel(8), monitor(8), shutdown(8), svcadm(8), svccfg(8), zpool(8)

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

Booting and Shutting Down Oracle Solaris 11.4 Systems

Oracle OpenBoot 4.x Administration Guide

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