1 '\" te
   2 .\" Copyright 2018 OmniOS Community Edition (OmniOSce) Association.
   3 .\" Copyright 2015 Nexenta Systems Inc.
   4 .\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved
   5 .\" Copyright 1989 AT&T
   6 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   7 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
   8 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   9 .TH BOOT 1M "Jul 20, 2018"
  10 .SH NAME
  11 boot \- start the system kernel or a standalone program
  12 .SH SYNOPSIS
  13 .SS "SPARC"
  14 .LP
  15 .nf
  16 \fBboot\fR [\fIOBP\fR \fInames\fR] [\fIfile\fR] [\fB-aLV\fR] [\fB-F\fR \fIobject\fR] [\fB-D\fR \fIdefault-file\fR]
  17      [\fB-Z\fR \fIdataset\fR] [\fIboot-flags\fR] [\fB\(mi\(mi\fR] [\fIclient-program-args\fR]
  18 .fi
  19 
  20 .SS "x86"
  21 .LP
  22 .nf
  23 \fBboot\fR [\fIboot-flags\fR] [\fB-B\fR \fIprop\fR=\fIval\fR [,\fIval\fR...]]
  24 .fi
  25 
  26 .SH DESCRIPTION
  27 .LP
  28 Bootstrapping is the process of loading and executing a standalone program. For
  29 the purpose of this discussion, bootstrapping means the process of loading and
  30 executing the bootable operating system. Typically, the standalone program is
  31 the operating system kernel (see \fBkernel\fR(1M)), but any standalone program
  32 can be booted instead. On a SPARC-based system, the diagnostic monitor for a
  33 machine is a good example of a standalone program other than the operating
  34 system that can be booted.
  35 .sp
  36 .LP
  37 If the standalone is identified as a dynamically-linked executable, \fBboot\fR
  38 will load the interpreter (linker/loader) as indicated by the executable format
  39 and then transfer control to the interpreter. If the standalone is
  40 statically-linked, it will jump directly to the standalone.
  41 .sp
  42 .LP
  43 Once the kernel is loaded, it starts the UNIX system, mounts the necessary file
  44 systems (see \fBvfstab\fR(4)), and runs \fB/sbin/init\fR to bring the system to
  45 the "initdefault" state specified in \fB/etc/inittab\fR. See \fBinittab\fR(4).
  46 .SS "SPARC Bootstrap Procedure"
  47 .LP
  48 On SPARC based systems, the bootstrap procedure on most machines consists of
  49 the following basic phases.
  50 .sp
  51 .LP
  52 After the machine is turned on, the system firmware (in PROM) executes power-on
  53 self-test (POST). The form and scope of these tests depends on the version of
  54 the firmware in your system.
  55 .sp
  56 .LP
  57 After the tests have been completed successfully, the firmware attempts to
  58 autoboot if the appropriate flag has been set in the non-volatile storage area
  59 used by the firmware. The name of the file to load, and the device to load it
  60 from can also be manipulated.
  61 .sp
  62 .LP
  63 These flags and names can be set using the \fBeeprom\fR(1M) command from the
  64 shell, or by using \fBPROM\fR commands from the \fBok\fR prompt after the
  65 system has been halted.
  66 .sp
  67 .LP
  68 The second level program is either a filesystem-specific boot block (when
  69 booting from a disk), or \fBinetboot\fR (when booting across
  70 the network).
  71 .sp
  72 .LP
  73 Network Booting
  74 .sp
  75 .LP
  76 Network booting occurs in two steps: the client first obtains an IP address and
  77 any other parameters necessary to permit it to load the second-stage booter.
  78 The second-stage booter in turn loads the boot archive from the boot device.
  79 .sp
  80 .LP
  81 An IP address can be obtained in one of three ways: RARP, DHCP, or manual
  82 configuration, depending on the functions available in and configuration of the
  83 PROM. Machines of the \fBsun4u\fR and \fBsun4v\fR kernel architectures have
  84 DHCP-capable PROMs.
  85 .sp
  86 .LP
  87 The boot command syntax for specifying the two methods of network booting are:
  88 .sp
  89 .in +2
  90 .nf
  91 boot net:rarp
  92 boot net:dhcp
  93 .fi
  94 .in -2
  95 .sp
  96 
  97 .sp
  98 .LP
  99 The command:
 100 .sp
 101 .in +2
 102 .nf
 103 boot net
 104 .fi
 105 .in -2
 106 .sp
 107 
 108 .sp
 109 .LP
 110 without a \fBrarp\fR or \fBdhcp\fR specifier, invokes the default method for
 111 network booting over the network interface for which \fBnet\fR is an alias.
 112 .sp
 113 .LP
 114 The sequence of events for network booting using RARP/\fBbootparams\fR is
 115 described in the following paragraphs. The sequence for DHCP follows the
 116 RARP/\fBbootparams\fR description.
 117 .sp
 118 .LP
 119 When booting over the network using RARP/\fBbootparams\fR, the PROM begins by
 120 broadcasting a reverse ARP request until it receives a reply. When a reply is
 121 received, the PROM then broadcasts a TFTP request to fetch the first block of
 122 \fBinetboot\fR. Subsequent requests will be sent to the server that initially
 123 answered the first block request. After loading, \fBinetboot\fR will also use
 124 reverse ARP to fetch its IP address, then broadcast \fBbootparams\fR RPC calls
 125 (see \fBbootparams\fR(4)) to locate configuration information and its root file
 126 system. \fBinetboot\fR then loads the boot archive by means of NFS and
 127 transfers control to that archive.
 128 .sp
 129 .LP
 130 When booting over the network using DHCP, the PROM broadcasts the hardware
 131 address and kernel architecture and requests an IP address, boot parameters,
 132 and network configuration information. After a DHCP server responds and is
 133 selected (from among potentially multiple servers), that server sends to the
 134 client an IP address and all other information needed to boot the client. After
 135 receipt of this information, the client PROM examines the name of the file to
 136 be loaded, and will behave in one of two ways, depending on whether the file's
 137 name appears to be an HTTP URL. If it does not, the PROM downloads
 138 \fBinetboot\fR, loads that file into memory, and executes it. \fBinetboot\fR
 139 loads the boot archive, which takes over the machine and releases
 140 \fBinetboot\fR. Startup scripts then initiate the DHCP agent (see
 141 \fBdhcpagent\fR(1M)), which implements further DHCP activities.
 142 
 143 .SS "iSCSI Boot"
 144 .LP
 145 iSCSI boot is currently supported only on x86. The host being booted must be
 146 equipped with NIC(s) capable of iBFT (iSCSI Boot Firmware Table) or have the
 147 mainboard's BIOS be iBFT-capable. iBFT, defined in the Advanced Configuration
 148 and Power Interface (ACPI) 3.0b specification, specifies a block of information
 149 that contains various parameters that are useful to the iSCSI Boot process.
 150 .sp
 151 .LP
 152 Firmware implementing iBFT presents an iSCSI disk in the BIOS during startup as
 153 a bootable device by establishing the connection to the iSCSI target. The rest
 154 of the process of iSCSI booting is the same as booting from a local disk.
 155 .sp
 156 .LP
 157 To configure the iBFT properly, users need to refer to the documentation from
 158 their hardware vendors.
 159 .SS "Booting from Disk"
 160 .LP
 161 When booting from disk, the OpenBoot PROM firmware reads the boot blocks from
 162 blocks 1 to 15 of the partition specified as the boot device. This standalone
 163 booter usually contains a file system-specific reader capable of reading the
 164 boot archive.
 165 .sp
 166 .LP
 167 If the pathname to the standalone is relative (does not begin with a slash),
 168 the second level boot will look for the standalone in a platform-dependent
 169 search path. This path is guaranteed to contain
 170 \fB/platform/\fR\fIplatform-name\fR. Many SPARC platforms next search the
 171 platform-specific path entry \fB/platform/\fR\fIhardware-class-name\fR. See
 172 \fBfilesystem\fR(5). If the pathname is absolute, \fBboot\fR will use the
 173 specified path. The \fBboot\fR program then loads the standalone at the
 174 appropriate address, and then transfers control.
 175 .sp
 176 .LP
 177 Once the boot archive has been transferred from the boot device, Solaris can
 178 initialize and take over control of the machine. This process is further
 179 described in the "Boot Archive Phase," below, and is identical on all
 180 platforms.
 181 .sp
 182 .LP
 183 If the filename is not given on the command line or otherwise specified, for
 184 example, by the \fBboot-file\fR NVRAM variable, \fBboot\fR chooses an
 185 appropriate default file to load based on what software is installed on the
 186 system and the capabilities of the hardware and firmware.
 187 .sp
 188 .LP
 189 The path to the kernel must not contain any whitespace.
 190 .SS "Booting from ZFS"
 191 .LP
 192 Booting from ZFS differs from booting from UFS in that, with ZFS, a device
 193 specifier identifies a storage pool, not a single root file system. A storage
 194 pool can contain multiple bootable datasets (that is, root file systems).
 195 Therefore, when booting from ZFS, it is not sufficient to specify a boot
 196 device. One must also identify a root file system within the pool that was
 197 identified by the boot device. By default, the dataset selected for booting is
 198 the one identified by the pool's \fBbootfs\fR property. This default selection
 199 can be overridden by specifying an alternate bootable dataset with the \fB-Z\fR
 200 option.
 201 .SS "Boot Archive Phase"
 202 .LP
 203 The boot archive contains a file system image that is mounted using an
 204 in-memory disk. The image is self-describing, specifically containing a file
 205 system reader in the boot block. This file system reader mounts and opens the
 206 RAM disk image, then reads and executes the kernel contained within it. By
 207 default, this kernel is in:
 208 .sp
 209 .in +2
 210 .nf
 211 /platform/`uname -i`/kernel/unix
 212 .fi
 213 .in -2
 214 .sp
 215 
 216 .sp
 217 .LP
 218 If booting from ZFS, the pathnames of both the archive and the kernel file are
 219 resolved in the root file system (that is, dataset) selected for booting as
 220 described in the previous section.
 221 .sp
 222 .LP
 223 The initialization of the kernel continues by loading necessary drivers and
 224 modules from the in-memory filesystem until I/O can be turned on and the root
 225 filesystem mounted. Once the root filesystem is mounted, the in-memory
 226 filesystem is no longer needed and is discarded.
 227 .SS "OpenBoot PROM \fBboot\fR Command Behavior"
 228 .LP
 229 The OpenBoot \fBboot\fR command takes arguments of the following form:
 230 .sp
 231 .in +2
 232 .nf
 233 ok boot [\fIdevice-specifier\fR] [\fIarguments\fR]
 234 .fi
 235 .in -2
 236 .sp
 237 
 238 .sp
 239 .LP
 240 The default \fBboot\fR command has no arguments:
 241 .sp
 242 .in +2
 243 .nf
 244 ok boot
 245 .fi
 246 .in -2
 247 .sp
 248 
 249 .sp
 250 .LP
 251 If no \fIdevice-specifier\fR is given on the \fBboot\fR command line, OpenBoot
 252 typically uses the \fIboot-device\fR or \fIdiag-device\fR \fBNVRAM\fR variable.
 253 If no optional \fIarguments\fR are given on the command line, OpenBoot
 254 typically uses the \fIboot-file\fR or \fIdiag-file\fR \fBNVRAM\fR variable as
 255 default \fBboot\fR arguments. (If the system is in diagnostics mode,
 256 \fIdiag-device\fR and \fIdiag-file\fR are used instead of \fIboot-device\fR and
 257 \fIboot-file\fR).
 258 .sp
 259 .LP
 260 \fIarguments\fR may include more than one string. All \fIargument\fR strings
 261 are passed to the secondary booter; they are not interpreted by OpenBoot.
 262 .sp
 263 .LP
 264 If any \fIarguments\fR are specified on the \fBboot\fR command line, then
 265 neither the \fIboot-file\fR nor the \fIdiag-file\fR \fBNVRAM\fR variable is
 266 used. The contents of the \fBNVRAM\fR variables are not merged with command
 267 line arguments. For example, the command:
 268 .sp
 269 .in +2
 270 .nf
 271 ok \fBboot\fR \fB-s\fR
 272 .fi
 273 .in -2
 274 .sp
 275 
 276 .sp
 277 .LP
 278 ignores the settings in both \fIboot-file\fR and \fIdiag-file\fR; it interprets
 279 the string \fB"-s"\fR as \fIarguments\fR. \fBboot\fR will not use the contents
 280 of \fIboot-file\fR or \fIdiag-file\fR.
 281 .sp
 282 .LP
 283 With older PROMs, the command:
 284 .sp
 285 .in +2
 286 .nf
 287 ok \fBboot net\fR
 288 .fi
 289 .in -2
 290 .sp
 291 
 292 .sp
 293 .LP
 294 took no arguments, using instead the settings in \fIboot-file\fR or
 295 \fIdiag-file\fR (if set) as the default file name and arguments to pass to
 296 boot. In most cases, it is best to allow the \fBboot\fR command to choose an
 297 appropriate default based upon the system type, system hardware and firmware,
 298 and upon what is installed on the root file system. Changing \fIboot-file\fR or
 299 \fIdiag-file\fR can generate unexpected results in certain circumstances.
 300 .sp
 301 .LP
 302 This behavior is found on most OpenBoot 2.x and 3.x based systems. Note that
 303 differences may occur on some platforms.
 304 .sp
 305 .LP
 306 The command:
 307 .sp
 308 .LP
 309 ok \fBboot cdrom\fR
 310 .sp
 311 .LP
 312 \&...also normally takes no arguments. Accordingly, if \fIboot-file\fR is set
 313 to the 64-bit kernel filename and you attempt to boot the installation CD or
 314 DVD with \fBboot cdrom\fR, boot will fail if the installation media contains
 315 only a 32-bit kernel.
 316 .sp
 317 .LP
 318 Because the contents of \fIboot-file\fR or \fIdiag-file\fR can be ignored
 319 depending on the form of the \fBboot\fR command used, reliance upon
 320 \fIboot-file\fR should be discouraged for most production systems.
 321 .sp
 322 .LP
 323 Modern PROMs have enhanced the network boot support package to support the
 324 following syntax for arguments to be processed by the package:
 325 .sp
 326 .LP
 327 [\fIprotocol\fR,] [\fIkey\fR=\fIvalue\fR,]*
 328 .sp
 329 .LP
 330 All arguments are optional and can appear in any order. Commas are required
 331 unless the argument is at the end of the list. If specified, an argument takes
 332 precedence over any default values, or, if booting using DHCP, over
 333 configuration information provided by a DHCP server for those parameters.
 334 .sp
 335 .LP
 336 \fIprotocol\fR, above, specifies the address discovery protocol to be used.
 337 .sp
 338 .LP
 339 Configuration parameters, listed below, are specified as \fIkey\fR=\fIvalue\fR
 340 attribute pairs.
 341 .sp
 342 .ne 2
 343 .na
 344 \fB\fBtftp-server\fR\fR
 345 .ad
 346 .sp .6
 347 .RS 4n
 348 IP address of the TFTP server
 349 .RE
 350 
 351 .sp
 352 .ne 2
 353 .na
 354 \fB\fBfile\fR\fR
 355 .ad
 356 .sp .6
 357 .RS 4n
 358 file to download using TFTP
 359 .RE
 360 
 361 .sp
 362 .ne 2
 363 .na
 364 \fB\fBhost-ip\fR\fR
 365 .ad
 366 .sp .6
 367 .RS 4n
 368 IP address of the client (in dotted-decimal notation)
 369 .RE
 370 
 371 .sp
 372 .ne 2
 373 .na
 374 \fB\fBrouter-ip\fR\fR
 375 .ad
 376 .sp .6
 377 .RS 4n
 378 IP address of the default router
 379 .RE
 380 
 381 .sp
 382 .ne 2
 383 .na
 384 \fB\fBsubnet-mask\fR\fR
 385 .ad
 386 .sp .6
 387 .RS 4n
 388 subnet mask (in dotted-decimal notation)
 389 .RE
 390 
 391 .sp
 392 .ne 2
 393 .na
 394 \fB\fBclient-id\fR\fR
 395 .ad
 396 .sp .6
 397 .RS 4n
 398 DHCP client identifier
 399 .RE
 400 
 401 .sp
 402 .ne 2
 403 .na
 404 \fB\fBhostname\fR\fR
 405 .ad
 406 .sp .6
 407 .RS 4n
 408 hostname to use in DHCP transactions
 409 .RE
 410 
 411 .sp
 412 .ne 2
 413 .na
 414 \fB\fBhttp-proxy\fR\fR
 415 .ad
 416 .sp .6
 417 .RS 4n
 418 HTTP proxy server specification (IPADDR[:PORT])
 419 .RE
 420 
 421 .sp
 422 .ne 2
 423 .na
 424 \fB\fBtftp-retries\fR\fR
 425 .ad
 426 .sp .6
 427 .RS 4n
 428 maximum number of TFTP retries
 429 .RE
 430 
 431 .sp
 432 .ne 2
 433 .na
 434 \fB\fBdhcp-retries\fR\fR
 435 .ad
 436 .sp .6
 437 .RS 4n
 438 maximum number of DHCP retries
 439 .RE
 440 
 441 .sp
 442 .LP
 443 The list of arguments to be processed by the network boot support package is
 444 specified in one of two ways:
 445 .RS +4
 446 .TP
 447 .ie t \(bu
 448 .el o
 449 As arguments passed to the package's \fBopen\fR method, or
 450 .RE
 451 .RS +4
 452 .TP
 453 .ie t \(bu
 454 .el o
 455 arguments listed in the NVRAM variable \fBnetwork-boot-arguments\fR.
 456 .RE
 457 .sp
 458 .LP
 459 Arguments specified in \fBnetwork-boot-arguments\fR will be processed only if
 460 there are no arguments passed to the package's \fBopen\fR method.
 461 .sp
 462 .LP
 463 Argument Values
 464 .sp
 465 .LP
 466 \fIprotocol\fR specifies the address discovery protocol to be used. If present,
 467 the possible values are \fBrarp\fR or \fBdhcp\fR.
 468 .sp
 469 .LP
 470 If other configuration parameters are specified in the new syntax and style
 471 specified by this document, absence of the \fIprotocol\fR parameter implies
 472 manual configuration.
 473 .sp
 474 .LP
 475 If no other configuration parameters are specified, or if those arguments are
 476 specified in the positional parameter syntax currently supported, the absence
 477 of the \fIprotocol\fR parameter causes the network boot support package to use
 478 the platform-specific default address discovery protocol.
 479 .sp
 480 .LP
 481 Manual configuration requires that the client be provided its IP address, the
 482 name of the boot file, and the address of the server providing the boot file
 483 image. Depending on the network configuration, it might be required that
 484 \fBsubnet-mask\fR and \fBrouter-ip\fR also be specified.
 485 .sp
 486 .LP
 487 If the \fIprotocol\fR argument is not specified, the network boot support
 488 package uses the platform-specific default address discovery protocol.
 489 .sp
 490 .LP
 491 \fBtftp-server\fR is the IP address (in standard IPv4 dotted-decimal notation)
 492 of the TFTP server that provides the file to download if using TFTP.
 493 .sp
 494 .LP
 495 When using DHCP, the value, if specified, overrides the value of the TFTP
 496 server specified in the DHCP response.
 497 .sp
 498 .LP
 499 The TFTP RRQ is unicast to the server if one is specified as an argument or in
 500 the DHCP response. Otherwise, the TFTP RRQ is broadcast.
 501 .sp
 502 .LP
 503 \fIfile\fR specifies the file to be loaded by TFTP from the TFTP server.
 504 .sp
 505 .LP
 506 When using RARP and TFTP, the default file name is the ASCII hexadecimal
 507 representation of the IP address of the client, as documented in a preceding
 508 section of this document.
 509 .sp
 510 .LP
 511 When using DHCP, this argument, if specified, overrides the name of the boot
 512 file specified in the DHCP response.
 513 .sp
 514 .LP
 515 When using DHCP and TFTP, the default file name is constructed from the root
 516 node's \fBname\fR property, with commas (,) replaced by periods (.).
 517 .sp
 518 .LP
 519 When specified on the command line, the filename must not contain slashes
 520 (\fB/\fR).
 521 .sp
 522 .LP
 523 \fBhost-ip\fR specifies the IP address (in standard IPv4 dotted-decimal
 524 notation) of the client, the system being booted. If using RARP as the address
 525 discovery protocol, specifying this argument makes use of RARP unnecessary.
 526 .sp
 527 .LP
 528 If DHCP is used, specifying the \fBhost-ip\fR argument causes the client to
 529 follow the steps required of a client with an "Externally Configured Network
 530 Address", as specified in RFC 2131.
 531 .sp
 532 .LP
 533 \fBrouter-ip\fR is the IP address (in standard IPv4 dotted-decimal notation) of
 534 a router on a directly connected network. The router will be used as the first
 535 hop for communications spanning networks. If this argument is supplied, the
 536 router specified here takes precedence over the preferred router specified in
 537 the DHCP response.
 538 .sp
 539 .LP
 540 \fBsubnet-mask\fR (specified in standard IPv4 dotted-decimal notation) is the
 541 subnet mask on the client's network. If the subnet mask is not provided (either
 542 by means of this argument or in the DHCP response), the default mask
 543 appropriate to the network class (Class A, B, or C) of the address assigned to
 544 the booting client will be assumed.
 545 .sp
 546 .LP
 547 \fBclient-id\fR specifies the unique identifier for the client. The DHCP client
 548 identifier is derived from this value. Client identifiers can be specified as:
 549 .RS +4
 550 .TP
 551 .ie t \(bu
 552 .el o
 553 The ASCII hexadecimal representation of the identifier, or
 554 .RE
 555 .RS +4
 556 .TP
 557 .ie t \(bu
 558 .el o
 559 a quoted string
 560 .RE
 561 .sp
 562 .LP
 563 Thus, \fBclient-id="openboot"\fR and \fBclient-id=6f70656e626f6f74\fR both
 564 represent a DHCP client identifier of 6F70656E626F6F74.
 565 .sp
 566 .LP
 567 Identifiers specified on the command line must must not include slash (\fB/\fR)
 568 or spaces.
 569 .sp
 570 .LP
 571 The maximum length of the DHCP client identifier is 32 bytes, or 64 characters
 572 representing 32 bytes if using the ASCII hexadecimal form. If the latter form
 573 is used, the number of characters in the identifier must be an even number.
 574 Valid characters are 0-9, a-f, and A-F.
 575 .sp
 576 .LP
 577 For correct identification of clients, the client identifier must be unique
 578 among the client identifiers used on the subnet to which the client is
 579 attached. System administrators are responsible for choosing identifiers that
 580 meet this requirement.
 581 .sp
 582 .LP
 583 Specifying a client identifier on a command line takes precedence over any
 584 other DHCP mechanism of specifying identifiers.
 585 .sp
 586 .LP
 587 \fBhostname\fR (specified as a string) specifies the hostname to be used in
 588 DHCP transactions. The name might or might not be qualified with the local
 589 domain name. The maximum length of the hostname is 255 characters.
 590 .LP
 591 Note -
 592 .sp
 593 .RS 2
 594 The \fBhostname\fR parameter can be used in service environments that require
 595 that the client provide the desired hostname to the DHCP server. Clients
 596 provide the desired hostname to the DHCP server, which can then register the
 597 hostname and IP address assigned to the client with DNS.
 598 .RE
 599 .sp
 600 .LP
 601 \fBhttp-proxy\fR is specified in the following standard notation for a host:
 602 .sp
 603 .in +2
 604 .nf
 605 \fIhost\fR [":"" \fIport\fR]
 606 .fi
 607 .in -2
 608 .sp
 609 
 610 .sp
 611 .LP
 612 \&...where \fIhost\fR is specified as an IP ddress (in standard IPv4
 613 dotted-decimal notation) and the optional \fIport\fR is specified in decimal.
 614 If a port is not specified, port 8080 (decimal) is implied.
 615 .sp
 616 .LP
 617 \fBtftp-retries\fR is the maximum number of retries (specified in decimal)
 618 attempted before the TFTP process is determined to have failed. Defaults to
 619 using infinite retries.
 620 .sp
 621 .LP
 622 \fBdhcp-retries\fR is the maximum number of retries (specified in decimal)
 623 attempted before the DHCP process is determined to have failed. Defaults to of
 624 using infinite retries.
 625 .SS "x86 Bootstrap Procedure"
 626 .LP
 627 On x86 based systems, the bootstrapping process consists of two conceptually
 628 distinct phases, kernel loading and kernel initialization. Kernel loading is
 629 implemented in the boot loader using the BIOS ROM on the system
 630 board, and BIOS extensions in ROMs on peripheral boards. The BIOS loads boot
 631 loader, starting with the first physical sector from a hard disk, DVD, or CD. If
 632 supported by the ROM on the network adapter, the BIOS can also download the
 633 \fBpxeboot\fR binary from a network boot server. Once the boot loader is
 634 loaded, it in turn will load the \fBunix\fR kernel, a pre-constructed boot
 635 archive containing kernel modules and data, and any additional files specified
 636 in the boot loader configuration. Once specified files are loaded, the boot
 637 loader will start the kernel to complete boot.
 638 .sp
 639 .LP
 640 If the device identified by the boot loader as the boot device contains a ZFS
 641 storage pool, the \fBmenu.lst\fR file used to create the Boot Environment menu
 642 will be found in the dataset at the root of the pool's dataset hierarchy.
 643 This is the dataset with the same name as the pool itself. There is always
 644 exactly one such dataset in a pool, and so this dataset is well-suited for
 645 pool-wide data such as the \fBmenu.lst\fR file. After the system is booted,
 646 this dataset is mounted at /\fIpoolname\fR in the root file system.
 647 .sp
 648 .LP
 649 There can be multiple bootable datasets (that is, root file systems) within a
 650 pool. The default file system to load the kernel is identified by the boot
 651 pool \fBbootfs\fR property (see \fBzpool\fR(1M)). All bootable datasets are
 652 listed in the \fBmenu.lst\fR file, which is used by the boot loader to compose
 653 the Boot Environment menu, to implement support to load a kernel and boot from
 654 an alternate Boot Environment.
 655 .sp
 656 .LP
 657 Kernel initialization starts when the boot loader finishes loading the files
 658 specified in the boot loader configuration and hands control over to the
 659 \fBunix\fR binary. The Unix operating system initializes, links in the
 660 necessary modules from the boot archive and mounts the root file system on
 661 the real root device. At this point, the kernel regains
 662 storage I/O, mounts additional file systems (see \fBvfstab\fR(4)), and starts
 663 various operating system services (see \fBsmf\fR(5)).
 664 
 665 .SH OPTIONS
 666 .SS "SPARC"
 667 .LP
 668 The following SPARC options are supported:
 669 .sp
 670 .ne 2
 671 .na
 672 \fB\fB-a\fR\fR
 673 .ad
 674 .sp .6
 675 .RS 4n
 676 The boot program interprets this flag to mean \fBask me\fR, and so it prompts
 677 for the name of the standalone. The \fB\&'\fR\fB-a\fR\fB\&'\fR flag is then
 678 passed to the standalone program.
 679 .RE
 680 
 681 .sp
 682 .ne 2
 683 .na
 684 \fB\fB-D\fR \fIdefault-file\fR\fR
 685 .ad
 686 .sp .6
 687 .RS 4n
 688 Explicitly specify the \fIdefault-file\fR. On some systems, \fBboot\fR chooses
 689 a dynamic default file, used when none is otherwise specified. This option
 690 allows the \fIdefault-file\fR to be explicitly set and can be useful when
 691 booting \fBkmdb\fR(1) since, by default, \fBkmdb\fR loads the default-file as
 692 exported by the \fBboot\fR program.
 693 .RE
 694 
 695 .sp
 696 .ne 2
 697 .na
 698 \fB\fB-F\fR \fIobject\fR\fR
 699 .ad
 700 .sp .6
 701 .RS 4n
 702 Boot using the named object. The object must be either an ELF executable or
 703 bootable object containing a boot block. The primary use is to boot the
 704 failsafe boot archive.
 705 .RE
 706 
 707 .sp
 708 .ne 2
 709 .na
 710 \fB\fB-L\fR\fR
 711 .ad
 712 .sp .6
 713 .RS 4n
 714 List the bootable datasets within a ZFS pool. You can select one of the
 715 bootable datasets in the list, after which detailed instructions for booting
 716 that dataset are displayed. Boot the selected dataset by following the
 717 instructions. This option is supported only when the boot device contains a ZFS
 718 storage pool.
 719 .RE
 720 
 721 .sp
 722 .ne 2
 723 .na
 724 \fB\fB-V\fR\fR
 725 .ad
 726 .sp .6
 727 .RS 4n
 728 Display verbose debugging information.
 729 .RE
 730 
 731 .sp
 732 .ne 2
 733 .na
 734 \fB\fIboot-flags\fR\fR
 735 .ad
 736 .sp .6
 737 .RS 4n
 738 The boot program passes all \fIboot-flags\fR to \fBfile\fR. They are not
 739 interpreted by \fBboot\fR. See the \fBkernel\fR(1M) and \fBkmdb\fR(1) manual
 740 pages for information about the options available with the default standalone
 741 program.
 742 .RE
 743 
 744 .sp
 745 .ne 2
 746 .na
 747 \fB\fIclient-program-args\fR\fR
 748 .ad
 749 .sp .6
 750 .RS 4n
 751 The \fBboot\fR program passes all \fIclient-program-args\fR to \fIfile\fR. They
 752 are not interpreted by \fBboot\fR.
 753 .RE
 754 
 755 .sp
 756 .ne 2
 757 .na
 758 \fB\fIfile\fR\fR
 759 .ad
 760 .sp .6
 761 .RS 4n
 762 Name of a standalone program to \fBboot\fR. If a filename is not explicitly
 763 specified, either on the \fBboot\fR command line or in the \fIboot-file\fR
 764 NVRAM variable, \fBboot\fR chooses an appropriate default filename.
 765 .RE
 766 
 767 .sp
 768 .ne 2
 769 .na
 770 \fB\fIOBP\fR \fInames\fR\fR
 771 .ad
 772 .sp .6
 773 .RS 4n
 774 Specify the open boot prom designations. For example, on Desktop SPARC based
 775 systems, the designation \fB/sbus/esp@0,800000/sd@3,0:a\fR indicates a
 776 \fBSCSI\fR disk (sd) at target 3, lun0 on the \fBSCSI\fR bus, with the esp host
 777 adapter plugged into slot 0.
 778 .RE
 779 
 780 .sp
 781 .ne 2
 782 .na
 783 \fB\fB-Z\fR \fIdataset\fR\fR
 784 .ad
 785 .sp .6
 786 .RS 4n
 787 Boot from the root file system in the specified ZFS dataset.
 788 .RE
 789 
 790 .SS "x86"
 791 .LP
 792 The following x86 options are supported:
 793 .sp
 794 .ne 2
 795 .na
 796 \fB\fB-B\fR \fIprop\fR=\fIval\fR...\fR
 797 .ad
 798 .sp .6
 799 .RS 4n
 800 One or more property-value pairs to be passed to the kernel. Multiple
 801 property-value pairs must be separated by a comma. Use of this option is the
 802 equivalent of the command: \fBeeprom\fR \fIprop\fR=\fIval\fR. See
 803 \fBeeprom\fR(1M) for available properties and valid values.
 804 .RE
 805 
 806 .sp
 807 .ne 2
 808 .na
 809 \fB\fIboot-flags\fR\fR
 810 .ad
 811 .sp .6
 812 .RS 4n
 813 The boot program passes all \fIboot-flags\fR to \fBfile\fR. They are not
 814 interpreted by \fBboot\fR. See \fBkernel\fR(1M) and \fBkmdb\fR(1) for
 815 information about the options available with the kernel.
 816 .RE
 817 
 818 .SH X86 BOOT SEQUENCE DETAILS
 819 .LP
 820 After a PC-compatible machine is turned on, the system firmware in the \fBBIOS
 821 ROM\fR executes a power-on self test (POST), runs \fBBIOS\fR extensions in
 822 peripheral board \fBROMs,\fR and invokes software interrupt INT 19h, Bootstrap.
 823 The INT 19h handler typically performs the standard PC-compatible boot, which
 824 consists of trying to read the first physical sector from the first diskette
 825 drive, or, if that fails, from the first hard disk. The processor then jumps to
 826 the first byte of the sector image in memory.
 827 .SH X86 PRIMARY BOOT
 828 .LP
 829 The first sector on a hard disk contains the master boot block (first stage of
 830 the boot program), which contains the master boot program and the Master Boot
 831 Record (\fBMBR\fR) table. The master boot program has recorded the location of
 832 the secondary stage of the boot program and using this location, master boot
 833 will load and start the secondary stage of the boot program.
 834 
 835 To support booting multiple operating systems, the master boot program is also
 836 installed as the first sector of the partition with the illumos root file
 837 system. This will allow configuring third party boot programs to use the
 838 chainload technique to boot illumos system.
 839 
 840 If the first stage is installed on the master boot block (see the \fB-m\fR
 841 option of \fBinstallboot\fR(1M)), then \fBstage2\fR is loaded directly
 842 from the Solaris partition regardless of the active partition.
 843 .sp
 844 .LP
 845 A similar sequence occurs for DVD or CD boot, but the master boot block location
 846 and contents are dictated by the El Torito specification. The El Torito boot
 847 will then continue in the same way as with the hard disk.
 848 .sp
 849 .LP
 850 Floppy booting is not longer supported. Booting from USB devices follows the
 851 same procedure as with hard disks.
 852 .sp
 853 .LP
 854 An x86 \fBMBR\fR partition for the Solaris software begins with a
 855 one-cylinder boot slice, which contains the boot loader \fBstage1\fR in the
 856 first sector, the standard Solaris disk label and volume table of contents
 857 (VTOC) in the second and third sectors, and in case the UFS file system is
 858 used for the root file system, \fBstage2\fR in the fiftieth and subsequent
 859 sectors.
 860 
 861 If the zfs boot is used, \fBstage2\fR is always stored in the zfs pool
 862 boot program area.
 863 .sp
 864 .LP
 865 The behavior is slightly different when a disk is using \fBEFI\fR
 866 partitioning.
 867 
 868 To support a UFS root file system in the \fBEFI\fR partition, the \fBstage2\fR
 869 must be stored on separate dedicated partition, as there is no space in UFS
 870 file system boot program area to store the current \fBstage2\fR. This separate
 871 dedicated partition is used as raw disk space, and must have enough space
 872 for both \fBstage1\fR and \fBstage2\fR. The type (tag) of this partition
 873 must be \fBboot\fR, \fBEFI\fR UUID:
 874 .sp
 875 .in +2
 876 .nf
 877 \fB6a82cb45-1dd2-11b2-99a6-080020736631\fR
 878 .fi
 879 .in -2
 880 .sp
 881 For the UUID reference, please see \fB/usr/include/sys/efi_partition.h\fR.
 882 
 883 In case of a whole disk zfs pool configuration, the \fBstage1\fR is always
 884 installed in the first sector of the disk, and it always loads \fBstage2\fR
 885 from the partition specified at the boot loader installation time.
 886 .sp
 887 .LP
 888 Once \fBstage2\fR is running, it will load and start the third stage boot
 889 program from root file system. Boot loader supports loading from the ZFS,
 890 UFS and PCFS file systems. The stage3 boot program defaults to be
 891 \fB/boot/loader\fR, and implements a user interface to load and boot the
 892 unix kernel.
 893 .sp
 894 .LP
 895 For network booting, the supported method is Intel's Preboot eXecution
 896 Environment (PXE) standard. When booting from the network using PXE, the system
 897 or network adapter BIOS uses DHCP to locate a network bootstrap program
 898 (\fBpxeboot\fR) on a boot server and reads it using Trivial File Transfer
 899 Protocol (TFTP). The BIOS executes the \fBpxeboot\fR by jumping to its first
 900 byte in memory. The \fBpxeboot\fR program is combined stage2 and stage2 boot
 901 program and implements user interface to load and boot unix kernel.
 902 .SH X86 KERNEL STARTUP
 903 .LP
 904 The kernel startup process is independent of the kernel loading process. During
 905 kernel startup, console I/O goes to the device specified by the \fBconsole\fR
 906 property.
 907 .sp
 908 .LP
 909 When booting from UFS, the root device is specified by the \fBbootpath\fR
 910 property, and the root file system type is specified by the \fBfstype\fR
 911 property. These properties should be setup by the Solaris Install/Upgrade
 912 process in \fB/boot/solaris/bootenv.rc\fR and can be overridden with the
 913 \fB-B\fR option, described above (see the \fBeeprom\fR(1M) man page).
 914 .sp
 915 .LP
 916 When booting from ZFS, the root device is automatically passed by the boot
 917 loader to the kernel as a boot parameter \fB-B\fR \fBzfs-bootfs\fR. The actual
 918 value used by the boot loader can be observed with the \fBeeprom bootcmd\fR
 919 command.
 920 .sp
 921 .LP
 922 If the console properties are not present, console I/O defaults to \fBscreen\fR
 923 and \fBkeyboard\fR. The root device defaults to \fBramdisk\fR and the file
 924 system defaults to \fBufs\fR.
 925 .SH EXAMPLES
 926 .SS "SPARC"
 927 .LP
 928 \fBExample 1 \fRTo Boot the Default Kernel In Single-User Interactive Mode
 929 .sp
 930 .LP
 931 To boot the default kernel in single-user interactive mode, respond to the
 932 \fBok\fR prompt with one of the following:
 933 
 934 .sp
 935 .in +2
 936 .nf
 937 \fBboot\fR \fB\fR\fB-as\fR
 938 
 939 \fBboot\fR \fBdisk3\fR \fB-as\fR
 940 .fi
 941 .in -2
 942 .sp
 943 
 944 .LP
 945 \fBExample 2 \fRNetwork Booting
 946 .sp
 947 .LP
 948 To illustrate some of the subtle repercussions of various boot command line
 949 invocations, assume that the \fBnetwork-boot-arguments\fR are set and that
 950 \fBnet\fR is devaliased as shown in the commands below.
 951 
 952 .sp
 953 .LP
 954 In the following command, device arguments in the device alias are processed by
 955 the device driver. The network boot support package processes arguments in
 956 \fBnetwork-boot-arguments\fR.
 957 
 958 .sp
 959 .in +2
 960 .nf
 961 \fBboot net\fR
 962 .fi
 963 .in -2
 964 .sp
 965 
 966 .sp
 967 .LP
 968 The command below results in no device arguments. The network boot support
 969 package processes arguments in \fBnetwork-boot-arguments\fR.
 970 
 971 .sp
 972 .in +2
 973 .nf
 974 \fBboot net:\fR
 975 .fi
 976 .in -2
 977 .sp
 978 
 979 .sp
 980 .LP
 981 The command below results in no device arguments. \fBrarp\fR is the only
 982 network boot support package argument. \fBnetwork-boot-arguments\fR is ignored.
 983 
 984 .sp
 985 .in +2
 986 .nf
 987 \fBboot net:rarp\fR
 988 .fi
 989 .in -2
 990 .sp
 991 
 992 .sp
 993 .LP
 994 In the command below, the specified device arguments are honored. The network
 995 boot support package processes arguments in \fBnetwork-boot-arguments\fR.
 996 
 997 .sp
 998 .in +2
 999 .nf
1000 \fBboot net:speed=100,duplex=full\fR
1001 .fi
1002 .in -2
1003 .sp
1004 
1005 .SS "x86"
1006 .LP
1007 \fBExample 3 \fRTo Boot the Default Kernel In 64-bit Single-User Interactive
1008 Mode
1009 .sp
1010 .LP
1011 To boot the default kernel in single-user interactive mode, press the ESC key
1012 to get the boot loader \fBok\fR prompt and enter:
1013 
1014 .sp
1015 .in +2
1016 .nf
1017 boot -as
1018 .fi
1019 .in -2
1020 
1021 .SH FILES
1022 .ne 2
1023 .na
1024 \fB\fB/etc/inittab\fR\fR
1025 .ad
1026 .sp .6
1027 .RS 4n
1028 Table in which the \fBinitdefault\fR state is specified
1029 .RE
1030 
1031 .sp
1032 .ne 2
1033 .na
1034 \fB\fB/sbin/init\fR\fR
1035 .ad
1036 .sp .6
1037 .RS 4n
1038 Program that brings the system to the \fBinitdefault\fR state
1039 .RE
1040 
1041 .SS "64-bit SPARC Only"
1042 .ne 2
1043 .na
1044 \fB\fB/platform/\fR\fIplatform-name\fR\fB/kernel/sparcv9/unix\fR\fR
1045 .ad
1046 .sp .6
1047 .RS 4n
1048 Default program to boot system.
1049 .RE
1050 
1051 .SS "x86 Only"
1052 .ne 2
1053 .na
1054 \fB\fB/boot\fR\fR
1055 .ad
1056 .sp .6
1057 .RS 4n
1058 Directory containing boot-related files.
1059 .RE
1060 
1061 .sp
1062 .ne 2
1063 .na
1064 \fB\fB/rpool/boot/menu.lst\fR\fR
1065 .ad
1066 .sp .6
1067 .RS 4n
1068 Menu index file of bootable operating systems displayed by the boot loader.
1069 .sp
1070 \fBNote:\fR this file is located on the root ZFS pool. While many installs
1071 often name their root zpool 'rpool', this is not required and the
1072 /rpool in the path above should be substituted with the name of
1073 the root pool of your current system.
1074 .RE
1075 
1076 .sp
1077 .ne 2
1078 .na
1079 \fB\fB/platform/i86pc/kernel/unix\fR\fR
1080 .ad
1081 .sp .6
1082 .RS 4n
1083 32-bit kernel.
1084 .RE
1085 
1086 .SS "64-bit x86 Only"
1087 .ne 2
1088 .na
1089 \fB\fB/platform/i86pc/kernel/amd64/unix\fR\fR
1090 .ad
1091 .sp .6
1092 .RS 4n
1093 64-bit kernel.
1094 .RE
1095 
1096 .SH SEE ALSO
1097 .LP
1098 \fBkmdb\fR(1), \fBuname\fR(1), \fBbootadm\fR(1M), \fBeeprom\fR(1M),
1099 \fBinit\fR(1M), \fBinstallboot\fR(1M), \fBkernel\fR(1M), \fBmonitor\fR(1M),
1100 \fBshutdown\fR(1M), \fBsvcadm\fR(1M), \fBumountall\fR(1M), \fBzpool\fR(1M),
1101 \fBuadmin\fR(2), \fBbootparams\fR(4), \fBinittab\fR(4), \fBvfstab\fR(4),
1102 \fBfilesystem\fR(5)
1103 .sp
1104 .LP
1105 RFC 903, \fIA Reverse Address Resolution Protocol\fR,
1106 \fBhttp://www.ietf.org/rfc/rfc903.txt\fR
1107 .sp
1108 .LP
1109 RFC 2131, \fIDynamic Host Configuration Protocol\fR,
1110 \fBhttp://www.ietf.org/rfc/rfc2131.txt\fR
1111 .sp
1112 .LP
1113 RFC 2132, \fIDHCP Options and BOOTP Vendor Extensions\fR,
1114 \fBhttp://www.ietf.org/rfc/rfc2132.txt\fR
1115 .sp
1116 .LP
1117 RFC 2396, \fIUniform Resource Identifiers (URI): Generic Syntax\fR,
1118 \fBhttp://www.ietf.org/rfc/rfc2396.txt\fR
1119 .sp
1120 .LP
1121 \fI\fR
1122 .sp
1123 .LP
1124 \fISun Hardware Platform Guide\fR
1125 .sp
1126 .LP
1127 \fIOpenBoot Command Reference Manual\fR
1128 .SH WARNINGS
1129 .LP
1130 The \fBboot\fR utility is unable to determine which files can be used as
1131 bootable programs. If the booting of a file that is not bootable is requested,
1132 the \fBboot\fR utility loads it and branches to it. What happens after that is
1133 unpredictable.
1134 .SH NOTES
1135 .LP
1136 \fIplatform-name\fR can be found using the \fB-i\fR option of \fBuname\fR(1).
1137 \fIhardware-class-name\fR can be found using the \fB-m\fR option of
1138 \fBuname\fR(1).
1139 .sp
1140 .LP
1141 The current release of the Solaris operating system does not support machines
1142 running an UltraSPARC-I CPU.