1 BOOT(1M) Maintenance Commands BOOT(1M) 2 3 4 5 NAME 6 boot - start the system kernel or a standalone program 7 8 SYNOPSIS 9 SPARC 10 boot [OBP names] [file] [-aLV] [-F object] [-D default-file] 11 [-Z dataset] [boot-flags]][[client-program-args] 12 13 14 x86 15 kernel$ /platform/i86pc/kernel/$ISADIR/unix [boot-args] 16 [-B prop=val [,val...]] 17 18 19 DESCRIPTION 20 Bootstrapping is the process of loading and executing a standalone 21 program. For the purpose of this discussion, bootstrapping means the 22 process of loading and executing the bootable operating system. 23 Typically, the standalone program is the operating system kernel (see 24 kernel(1M)), but any standalone program can be booted instead. On a 25 SPARC-based system, the diagnostic monitor for a machine is a good 26 example of a standalone program other than the operating system that 27 can be booted. 28 29 30 If the standalone is identified as a dynamically-linked executable, boot 31 will load the interpreter (linker/loader) as indicated by the 32 executable format and then transfer control to the interpreter. If the 33 standalone is statically-linked, it will jump directly to the 34 standalone. 35 36 37 Once the kernel is loaded, it starts the UNIX system, mounts the 38 necessary file systems (see vfstab(4)), and runs /sbin/init to bring 39 the system to the "initdefault" state specified in /etc/inittab. See 40 inittab(4). 41 42 SPARC Bootstrap Procedure 43 On SPARC based systems, the bootstrap procedure on most machines 44 consists of the following basic phases. 45 46 47 After the machine is turned on, the system firmware (in PROM) executes 48 power-on self-test (POST). The form and scope of these tests depends on 49 the version of the firmware in your system. 50 51 52 After the tests have been completed successfully, the firmware attempts 53 to autoboot if the appropriate flag has been set in the non-volatile 54 storage area used by the firmware. The name of the file to load, and 55 the device to load it from can also be manipulated. 56 57 58 These flags and names can be set using the eeprom(1M) command from the 59 shell, or by using PROM commands from the ok prompt after the system 60 has been halted. 61 62 63 The second level program is either a fileystem-specific boot block (when 64 booting from a disk), or inetboot or wanboot (when booting across the 65 network). 66 67 68 Network Booting 69 70 71 Network booting occurs in two steps: the client first obtains an IP 72 address and any other parameters necessary to permit it to load the 73 second-stage booter. The second-stage booter in turn loads the boot 74 archive from the boot device. 75 76 77 An IP address can be obtained in one of three ways: RARP, DHCP, or 78 manual configuration, depending on the functions available in and 79 configuration of the PROM. Machines of the sun4u and sun4v kernel 80 architectures have DHCP-capable PROMs. 81 82 83 The boot command syntax for specifying the two methods of network 84 booting are: 85 86 boot net:rarp 87 boot net:dhcp 88 89 90 91 92 The command: 93 94 boot net 95 96 97 98 99 without a rarp or dhcp specifier, invokes the default method for 100 network booting over the network interface for which net is an alias. 101 102 103 The sequence of events for network booting using RARP/bootparams is 104 described in the following paragraphs. The sequence for DHCP follows 105 the RARP/bootparams description. 106 107 108 When booting over the network using RARP/bootparams, the PROM begins by 109 broadcasting a reverse ARP request until it receives a reply. When a 110 reply is received, the PROM then broadcasts a TFTP request to fetch the 111 first block of inetboot. Subsequent requests will be sent to the server 112 that initially answered the first block request. After loading, 113 inetboot will also use reverse ARP to fetch its IP address, then 114 broadcast bootparams RPC calls (see bootparams(4)) to locate 115 configuration information and its root file system. inetboot then loads 116 the boot archive by means of NFS and transfers control to that archive. 117 118 119 When booting over the network using DHCP, the PROM broadcasts the 120 hardware address and kernel architecture and requests an IP address, 121 boot parameters, and network configuration information. After a DHCP 122 server responds and is selected (from among potentially multiple 123 servers), that server sends to the client an IP address and all other 124 information needed to boot the client. After receipt of this 125 information, the client PROM examines the name of the file to be 126 loaded, and will behave in one of two ways, depending on whether the 127 file's name appears to be an HTTP URL. If it does not, the PROM 128 downloads inetboot, loads that file into memory, and executes it. 129 inetboot loads the boot archive, which takes over the machine and 130 releases inetboot. Startup scripts then initiate the DHCP agent (see 131 dhcpagent(1M)), which implements further DHCP activities. 132 133 134 If the file to be loaded is an HTTP URL, the PROM will use HTTP to load 135 the referenced file. If the client has been configured with an HMAC 136 SHA-1 key, it will check the integrity of the loaded file before 137 proceeding to execute it. The file is expected to be the wanboot 138 binary. The WAN boot process can be configured to use either DHCP or 139 NVRAM properties to discover the install server and router and the 140 proxies needed to connect to it. When wanboot begins executing, it 141 determines whether sufficient information is available to it to allow 142 it to proceed. If any necessary information is missing, it will either 143 exit with an appropriate error or bring up a command interpreter and 144 prompt for further configuration information. Once wanboot has obtained 145 the necessary information, it loads the boot loader into memory by 146 means of HTTP. If an encryption key has been installed on the client, 147 wanboot will verify the boot loader's signature and its accompanying 148 hash. Presence of an encryption key but no hashing key is an error. 149 150 151 The wanboot boot loader can communicate with the client using either 152 HTTP or secure HTTP. If the former, and if the client has been 153 configured with an HMAC SHA-1 key, the boot loader will perform an 154 integrity check of the root file system. Once the root file system has 155 been loaded into memory (and possibly had an integrity check 156 performed), the boot archive is transferred from the server. If 157 provided with a boot_logger URL by means of the wanboot.conf(4) file, 158 wanboot will periodically log its progress. 159 160 161 Not all PROMs are capable of consuming URLs. You can determine whether 162 a client is so capable using the list-security-keys OBP command (see 163 monitor(1M)). 164 165 166 WAN booting is not currently available on the x86 platform. 167 168 169 The wanboot Command Line 170 171 172 When the client program is wanboot, it accepts client-program-args of the 173 form: 174 175 boot ... -o opt1[,opt2[,...]] 176 177 178 179 180 where each option may be an action: 181 182 dhcp 183 Require wanboot to obtain configuration parameters by means of 184 DHCP. 185 186 187 prompt 188 Cause wanboot to enter its command interpreter. 189 190 191 <cmd> 192 One of the interpreter commands listed below. 193 194 195 196 ...or an assignment, using the interpreter's parameter names listed 197 below. 198 199 200 The wanboot Command Interpreter 201 202 203 The wanboot command interpreter is invoked by supplying a client- 204 program-args of "-o prompt" when booting. Input consists of single 205 commands or assignments, or a comma-separated list of commands or 206 assignments. The configuration parameters are: 207 208 host-ip 209 IP address of the client (in dotted-decimal notation) 210 211 212 router-ip 213 IP address of the default router (in dotted-decimal notation) 214 215 216 subnet-mask 217 subnet mask (in dotted-decimal notation) 218 219 220 client-id 221 DHCP client identifier (a quoted ASCII string or hex ASCII) 222 223 224 hostname 225 hostname to request in DHCP transactions (ASCII) 226 227 228 http-proxy 229 HTTP proxy server specification (IPADDR[:PORT]) 230 231 232 233 The key names are: 234 235 3des 236 the triple DES encryption key (48 hex ASCII characters) 237 238 239 aes 240 the AES encryption key (32 hex ASCII characters) 241 242 243 sha1 244 the HMAC SHA-1 signature key (40 hex ASCII characters) 245 246 247 248 Finally, the URL or the WAN boot CGI is referred to by means of: 249 250 bootserver 251 URL of WAN boot's CGI (the equivalent of OBP's file parameter) 252 253 254 255 The interpreter accepts the following commands: 256 257 help 258 Print a brief description of the available commands 259 260 261 var=val 262 Assign val to var, where var is one of the configuration parameter 263 names, the key names, or bootserver. 264 265 266 var= 267 Unset parameter var. 268 269 270 list 271 List all parameters and their values (key values retrieved by means 272 of OBP are never shown). 273 274 275 prompt 276 Prompt for values for unset parameters. The name of each parameter 277 and its current value (if any) is printed, and the user can accept 278 this value (press Return) or enter a new value. 279 280 281 go 282 Once the user is satisfied that all values have been entered, leave 283 the interpreter and continue booting. 284 285 286 exit 287 Quit the boot interpreter and return to OBP's ok prompt. 288 289 290 291 Any of these assignments or commands can be passed on the command line 292 as part of the -o options, subject to the OBP limit of 128 bytes for 293 boot arguments. For example, -o list,go would simply list current 294 (default) values of the parameters and then continue booting. 295 296 iSCSI Boot 297 iSCSI boot is currently supported only on x86. The host being booted 298 must be equipped with NIC(s) capable of iBFT (iSCSI Boot Firmware 299 Table) or have the mainboard's BIOS be iBFT-capable. iBFT, defined in 300 the Advanced Configuration and Power Interface (ACPI) 3.0b 301 specification, specifies a block of information that contains various 302 parameters that are useful to the iSCSI Boot process. 303 304 305 Firmware implementing iBFT presents an iSCSI disk in the BIOS during 306 startup as a bootable device by establishing the connection to the 307 iSCSI target. The rest of the process of iSCSI booting is the same as 308 booting from a local disk. 309 310 311 To configure the iBFT properly, users need to refer to the 312 documentation from their hardware vendors. 313 314 Booting from Disk 315 When booting from disk, the OpenBoot PROM firmware reads the boot 316 blocks from blocks 1 to 15 of the partition specified as the boot 317 device. This standalone booter usually contains a file system-specific 318 reader capable of reading the boot archive. 319 320 321 If the pathname to the standalone is relative (does not begin with a 322 slash), the second level boot will look for the standalone in a 323 platform-dependent search path. This path is guaranteed to contain 324 /platform/platform-name. Many SPARC platforms next search the platform- 325 specific path entry /platform/hardware-class-name. See filesystem(5). If 326 the pathname is absolute, boot will use the specified path. The boot 327 program then loads the standalone at the appropriate address, and then 328 transfers control. 329 330 331 Once the boot archive has been transferred from the boot device, 332 Solaris can initialize and take over control of the machine. This 333 process is further described in the "Boot Archive Phase," below, and is 334 identical on all platforms. 335 336 337 If the filename is not given on the command line or otherwise 338 specified, for example, by the boot-file NVRAM variable, boot chooses an 339 appropriate default file to load based on what software is installed on 340 the system and the capabilities of the hardware and firmware. 341 342 343 The path to the kernel must not contain any whitespace. 344 345 Booting from ZFS 346 Booting from ZFS differs from booting from UFS in that, with ZFS, a 347 device specifier identifies a storage pool, not a single root file 348 system. A storage pool can contain multiple bootable datasets (that is, 349 root file systems). Therefore, when booting from ZFS, it is not 350 sufficient to specify a boot device. One must also identify a root file 351 system within the pool that was identified by the boot device. By 352 default, the dataset selected for booting is the one identified by the 353 pool's bootfs property. This default selection can be overridden by 354 specifying an alternate bootable dataset with the -Z option. 355 356 Boot Archive Phase 357 The boot archive contains a file system image that is mounted using an 358 in-memory disk. The image is self-describing, specifically containing a 359 file system reader in the boot block. This file system reader mounts 360 and opens the RAM disk image, then reads and executes the kernel 361 contained within it. By default, this kernel is in: 362 363 /platform/`uname -i`/kernel/unix 364 365 366 367 368 If booting from ZFS, the pathnames of both the archive and the kernel 369 file are resolved in the root file system (that is, dataset) selected 370 for booting as described in the previous section. 371 372 373 The initialization of the kernel continues by loading necessary drivers 374 and modules from the in-memory filesystem until I/O can be turned on and 375 the root filesystem mounted. Once the root filesystem is mounted, the 376 in-memory filesystem is no longer needed and is discarded. 377 378 OpenBoot PROM boot Command Behavior 379 The OpenBoot boot command takes arguments of the following form: 380 381 ok boot [device-specifier] [arguments] 382 383 384 385 386 The default boot command has no arguments: 387 388 ok boot 389 390 391 392 393 If no device-specifier is given on the boot command line, OpenBoot 394 typically uses the boot-device or diag-device NVRAM variable. If no 395 optional arguments are given on the command line, OpenBoot typically 396 uses the boot-file or diag-file NVRAM variable as default boot arguments. 397 (If the system is in diagnostics mode, diag-device and diag-file are used 398 instead of boot-device and boot-file). 399 400 401 arguments may include more than one string. All argument strings are 402 passed to the secondary booter; they are not interpreted by OpenBoot. 403 404 405 If any arguments are specified on the boot command line, then neither 406 the boot-file nor the diag-file NVRAM variable is used. The contents of 407 the NVRAM variables are not merged with command line arguments. For 408 example, the command: 409 410 ok boot -s 411 412 413 414 415 ignores the settings in both boot-file and diag-file; it interprets the 416 string "-s" as arguments. boot will not use the contents of boot-file or 417 diag-file. 418 419 420 With older PROMs, the command: 421 422 ok boot net 423 424 425 426 427 took no arguments, using instead the settings in boot-file or diag-file 428 (if set) as the default file name and arguments to pass to boot. In 429 most cases, it is best to allow the boot command to choose an 430 appropriate default based upon the system type, system hardware and 431 firmware, and upon what is installed on the root file system. Changing 432 boot-file or diag-file can generate unexpected results in certain 433 circumstances. 434 435 436 This behavior is found on most OpenBoot 2.x and 3.x based systems. Note 437 that differences may occur on some platforms. 438 439 440 The command: 441 442 443 ok boot cdrom 444 445 446 ...also normally takes no arguments. Accordingly, if boot-file is set to 447 the 64-bit kernel filename and you attempt to boot the installation CD 448 or DVD with boot cdrom, boot will fail if the installation media 449 contains only a 32-bit kernel. 450 451 452 Because the contents of boot-file or diag-file can be ignored depending 453 on the form of the boot command used, reliance upon boot-file should be 454 discouraged for most production systems. 455 456 457 When executing a WAN boot from a local (CD or DVD) copy of wanboot, one 458 must use: 459 460 461 ok boot cdrom -F wanboot - install 462 463 464 Modern PROMs have enhanced the network boot support package to support 465 the following syntax for arguments to be processed by the package: 466 467 468 [protocol,] [key=value,]* 469 470 471 All arguments are optional and can appear in any order. Commas are 472 required unless the argument is at the end of the list. If specified, 473 an argument takes precedence over any default values, or, if booting 474 using DHCP, over configuration information provided by a DHCP server 475 for those parameters. 476 477 478 protocol, above, specifies the address discovery protocol to be used. 479 480 481 Configuration parameters, listed below, are specified as key=value 482 attribute pairs. 483 484 tftp-server 485 IP address of the TFTP server 486 487 488 file 489 file to download using TFTP or URL for WAN boot 490 491 492 host-ip 493 IP address of the client (in dotted-decimal notation) 494 495 496 router-ip 497 IP address of the default router 498 499 500 subnet-mask 501 subnet mask (in dotted-decimal notation) 502 503 504 client-id 505 DHCP client identifier 506 507 508 hostname 509 hostname to use in DHCP transactions 510 511 512 http-proxy 513 HTTP proxy server specification (IPADDR[:PORT]) 514 515 516 tftp-retries 517 maximum number of TFTP retries 518 519 520 dhcp-retries 521 maximum number of DHCP retries 522 523 524 525 The list of arguments to be processed by the network boot support 526 package is specified in one of two ways: 527 528 o As arguments passed to the package's open method, or 529 530 o arguments listed in the NVRAM variable network-boot-arguments. 531 532 533 Arguments specified in network-boot-arguments will be processed only if 534 there are no arguments passed to the package's open method. 535 536 537 Argument Values 538 539 540 protocol specifies the address discovery protocol to be used. If 541 present, the possible values are rarp or dhcp. 542 543 544 If other configuration parameters are specified in the new syntax and 545 style specified by this document, absence of the protocol parameter 546 implies manual configuration. 547 548 549 If no other configuration parameters are specified, or if those 550 arguments are specified in the positional parameter syntax currently 551 supported, the absence of the protocol parameter causes the network 552 boot support package to use the platform-specific default address 553 discovery protocol. 554 555 556 Manual configuration requires that the client be provided its IP 557 address, the name of the boot file, and the address of the server 558 providing the boot file image. Depending on the network configuration, 559 it might be required that subnet-mask and router-ip also be specified. 560 561 562 If the protocol argument is not specified, the network boot support 563 package uses the platform-specific default address discovery protocol. 564 565 566 tftp-server is the IP address (in standard IPv4 dotted-decimal notation) 567 of the TFTP server that provides the file to download if using TFTP. 568 569 570 When using DHCP, the value, if specified, overrides the value of the 571 TFTP server specified in the DHCP response. 572 573 574 The TFTP RRQ is unicast to the server if one is specified as an 575 argument or in the DHCP response. Otherwise, the TFTP RRQ is broadcast. 576 577 578 file specifies the file to be loaded by TFTP from the TFTP server, or 579 the URL if using HTTP. The use of HTTP is triggered if the file name is 580 a URL, that is, the file name starts with http: (case-insensitive). 581 582 583 When using RARP and TFTP, the default file name is the ASCII 584 hexadecimal representation of the IP address of the client, as 585 documented in a preceding section of this document. 586 587 588 When using DHCP, this argument, if specified, overrides the name of the 589 boot file specified in the DHCP response. 590 591 592 When using DHCP and TFTP, the default file name is constructed from the 593 root node's name property, with commas (,) replaced by periods (.). 594 595 596 When specified on the command line, the filename must not contain 597 slashes (/). 598 599 600 The format of URLs is described in RFC 2396. The HTTP server must be 601 specified as an IP address (in standard IPv4 dotted-decimal notation). 602 The optional port number is specified in decimal. If a port is not 603 specified, port 80 (decimal) is implied. 604 605 606 The URL presented must be "safe-encoded", that is, the package does not 607 apply escape encodings to the URL presented. URLs containing commas 608 must be presented as a quoted string. Quoting URLs is optional 609 otherwise. 610 611 612 host-ip specifies the IP address (in standard IPv4 dotted-decimal 613 notation) of the client, the system being booted. If using RARP as the 614 address discovery protocol, specifying this argument makes use of RARP 615 unnecessary. 616 617 618 If DHCP is used, specifying the host-ip argument causes the client to 619 follow the steps required of a client with an "Externally Configured 620 Network Address", as specified in RFC 2131. 621 622 623 router-ip is the IP address (in standard IPv4 dotted-decimal notation) of 624 a router on a directly connected network. The router will be used as 625 the first hop for communications spanning networks. If this argument is 626 supplied, the router specified here takes precedence over the preferred 627 router specified in the DHCP response. 628 629 630 subnet-mask (specified in standard IPv4 dotted-decimal notation) is the 631 subnet mask on the client's network. If the subnet mask is not provided 632 (either by means of this argument or in the DHCP response), the default 633 mask appropriate to the network class (Class A, B, or C) of the address 634 assigned to the booting client will be assumed. 635 636 637 client-id specifies the unique identifier for the client. The DHCP 638 client identifier is derived from this value. Client identifiers can be 639 specified as: 640 641 o The ASCII hexadecimal representation of the identifier, or 642 643 o a quoted string 644 645 646 Thus, client-id="openboot" and client-id=6f70656e626f6f74 both represent 647 a DHCP client identifier of 6F70656E626F6F74. 648 649 650 Identifiers specified on the command line must must not include slash 651 (/) or spaces. 652 653 654 The maximum length of the DHCP client identifier is 32 bytes, or 64 655 characters representing 32 bytes if using the ASCII hexadecimal form. 656 If the latter form is used, the number of characters in the identifier 657 must be an even number. Valid characters are 0-9, a-f, and A-F. 658 659 660 For correct identification of clients, the client identifier must be 661 unique among the client identifiers used on the subnet to which the 662 client is attached. System administrators are responsible for choosing 663 identifiers that meet this requirement. 664 665 666 Specifying a client identifier on a command line takes precedence over 667 any other DHCP mechanism of specifying identifiers. 668 669 670 hostname (specified as a string) specifies the hostname to be used in 671 DHCP transactions. The name might or might not be qualified with the 672 local domain name. The maximum length of the hostname is 255 673 characters. 674 675 Note - 676 677 The hostname parameter can be used in service environments that 678 require that the client provide the desired hostname to the DHCP 679 server. Clients provide the desired hostname to the DHCP server, 680 which can then register the hostname and IP address assigned to the 681 client with DNS. 682 683 684 http-proxy is specified in the following standard notation for a host: 685 686 host [":"" port] 687 688 689 690 691 ...where host is specified as an IP ddress (in standard IPv4 dotted- 692 decimal notation) and the optional port is specified in decimal. If a 693 port is not specified, port 8080 (decimal) is implied. 694 695 696 tftp-retries is the maximum number of retries (specified in decimal) 697 attempted before the TFTP process is determined to have failed. 698 Defaults to using infinite retries. 699 700 701 dhcp-retries is the maximum number of retries (specified in decimal) 702 attempted before the DHCP process is determined to have failed. 703 Defaults to of using infinite retries. 704 705 x86 Bootstrap Procedure 706 On x86 based systems, the bootstrapping process consists of two 707 conceptually distinct phases, kernel loading and kernel initialization. 708 Kernel loading is implemented in GRUB (GRand Unified Bootloader) using 709 the BIOS ROM on the system board, and BIOS extensions in ROMs on 710 peripheral boards. The BIOS loads GRUB, starting with the first 711 physical sector from a hard disk, DVD, or CD. If supported by the ROM 712 on the network adapter, the BIOS can also download the pxegrub binary 713 from a network boot server. Once GRUB is located, it executes a command 714 in a menu to load the unix kernel and a pre-constructed boot archive 715 containing kernel modules and data. 716 717 718 If the device identified by GRUB as the boot device contains a ZFS 719 storage pool, the menu.lst file used to create the GRUB menu will be 720 found in the dataset at the root of the pool's dataset hierarchy. This 721 is the dataset with the same name as the pool itself. There is always 722 exactly one such dataset in a pool, and so this dataset is well-suited 723 for pool-wide data such as the menu.lst file. After the system is 724 booted, this dataset is mounted at /poolname in the root file system. 725 726 727 There can be multiple bootable datasets (that is, root file systems) 728 within a pool. By default, the file system in which file name entries 729 in a menu.lst file are resolved is the one identified by the pool's 730 bootfs property (see zpool(1M)). However, a menu.lst entry can contain 731 a bootfs command, which specifies an alternate dataset in the pool. In 732 this way, the menu.lst file can contain entries for multiple root file 733 systems within the pool. 734 735 736 Kernel initialization starts when GRUB finishes loading the boot 737 archive and hands control over to the unix binary. At this point, GRUB 738 becomes inactive and no more I/O occurs with the boot device. The Unix 739 operating system initializes, links in the necessary modules from the 740 boot archive and mounts the root file system on the real root device. 741 At this point, the kernel regains storage I/O, mounts additional file 742 systems (see vfstab(4)), and starts various operating system services 743 (see smf(5)). 744 745 Failsafe Mode 746 A requirement of booting from a root filesystem image built into a boot 747 archive then remounting root onto the actual root device is that the 748 contents of the boot archive and the root filesystem must be 749 consistent. Otherwise, the proper operation and integrity of the 750 machine cannot be guaranteed. 751 752 753 The term "consistent" means that all files and modules in the root 754 filesystem are also present in the boot archive and have identical 755 contents. Since the boot strategy requires first reading and mounting 756 the boot archive as the first-stage root image, all unloadable kernel 757 modules and initialization derived from the contents of the boot 758 archive are required to match the real root filesystem. Without such 759 consistency, it is possible that the system could be running with a 760 kernel module or parameter setting applied to the root device before 761 reboot, but not yet updated in the root archive. This inconsistency 762 could result in system instability or data loss. 763 764 765 Once the root filesystem is mounted, and before relinquishing the in- 766 memory filesystem, Solaris performs a consistency verification against 767 the two file systems. If an inconsistency is detected, Solaris suspends 768 the normal boot sequence and falls back to failsafe mode. Correcting 769 this state requires the administrator take one of two steps. The 770 recommended procedure is to reboot to the failsafe archive and rebuild 771 the boot archive. This ensures that a known kernel is booted and 772 functioning for the archive rebuild process. Alternatively, the 773 administrator can elect to clear the inconsistent boot archive service 774 state and continue system bring-up if the inconsistency is such that 775 correct system operation will not be impaired. See svcadm(1M). 776 777 778 If the boot archive service is cleared and system bring-up is continued 779 (the second alternative above), the system may be running with 780 unloadable kernel drivers or other modules that are out-of-date with 781 respect to the root filesystem. As such, correct system operation may 782 be compromised. 783 784 785 To ensure that the boot archive is consistent, the normal system 786 shutdown process, as initiated by reboot(1M) and shutdown(1M), checks 787 for and applies updates to the boot archive at the conclusion of the 788 umountall(1M) milestone. 789 790 791 An update to any kernel file, driver, module or driver configuration 792 file that needs to be included in the boot archive after the umountall 793 service is complete will result in a failed boot archive consistency 794 check during the next boot. To avoid this, it is recommended to always 795 shut down a machine cleanly. 796 797 798 If an update is required to the kernel after completion of the 799 umountall service, the administrator may elect to rebuild the archive 800 by invoking: 801 802 # bootadm update-archive 803 804 805 806 Failsafe Boot Archive 807 The failsafe archive can be used to boot the machine at any time for 808 maintenance or troubleshooting. The failsafe boot archive is installed 809 on the machine, sourced from the miniroot archive. Booting the failsafe 810 archive causes the machine to boot using the in-memory filesystem as the 811 root device. 812 813 SPARC 814 The SPARC failsafe archive is: 815 816 /platform/`uname -i`/failsafe 817 818 819 820 821 ...and can be booted as follows: 822 823 ok boot [device-specifier] -F failsafe 824 825 826 827 828 If a user wishes to boot a failsafe archive from a particular ZFS 829 bootable dataset, this can be done as follows: 830 831 ok boot [device-specifier] -Z dataset -F failsafe 832 833 834 835 x86 836 The x86 failsafe archive is: 837 838 /boot/x86.miniroot-safe 839 840 841 842 843 ...and can be booted by selecting the Solaris failsafe item from the 844 GRUB menu. 845 846 OPTIONS 847 SPARC 848 The following SPARC options are supported: 849 850 -a 851 The boot program interprets this flag to mean ask me, and so it 852 prompts for the name of the standalone. The '-a' flag is then passed 853 to the standalone program. 854 855 856 -D default-file 857 Explicitly specify the default-file. On some systems, boot chooses a 858 dynamic default file, used when none is otherwise specified. This 859 option allows the default-file to be explicitly set and can be 860 useful when booting kmdb(1) since, by default, kmdb loads the 861 default-file as exported by the boot program. 862 863 864 -F object 865 Boot using the named object. The object must be either an ELF 866 executable or bootable object containing a boot block. The primary 867 use is to boot the failsafe or wanboot boot archive. 868 869 870 -L 871 List the bootable datasets within a ZFS pool. You can select one of 872 the bootable datasets in the list, after which detailed 873 instructions for booting that dataset are displayed. Boot the 874 selected dataset by following the instructions. This option is 875 supported only when the boot device contains a ZFS storage pool. 876 877 878 -V 879 Display verbose debugging information. 880 881 882 boot-flags 883 The boot program passes all boot-flags to file. They are not 884 interpreted by boot. See the kernel(1M) and kmdb(1) manual pages 885 for information about the options available with the default 886 standalone program. 887 888 889 client-program-args 890 The boot program passes all client-program-args to file. They are not 891 interpreted by boot. 892 893 894 file 895 Name of a standalone program to boot. If a filename is not 896 explicitly specified, either on the boot command line or in the 897 boot-file NVRAM variable, boot chooses an appropriate default 898 filename. 899 900 901 OBP names 902 Specify the open boot prom designations. For example, on Desktop 903 SPARC based systems, the designation /sbus/esp@0,800000/sd@3,0:a 904 indicates a SCSI disk (sd) at target 3, lun0 on the SCSI bus, with 905 the esp host adapter plugged into slot 0. 906 907 908 -Z dataset 909 Boot from the root file system in the specified ZFS dataset. 910 911 912 x86 913 The following x86 options are supported: 914 915 -B prop=val... 916 One or more property-value pairs to be passed to the kernel. 917 Multiple property-value pairs must be separated by a comma. Use of 918 this option is the equivalent of the command: eeprom prop=val. See 919 eeprom(1M) for available properties and valid values. 920 921 If the root file system corresponding to this menu entry is a ZFS 922 dataset, the menu entry needs the following option added: 923 924 -B $ZFS-BOOTFS 925 926 927 928 929 boot-args 930 The boot program passes all boot-args to file. They are not 931 interpreted by boot. See kernel(1M) and kmdb(1) for information 932 about the options available with the kernel. 933 934 935 /platform/i86pc/kernel/$ISADIR/unix 936 Name of the kernel to boot. When using the kernel$ token, $ISADIR 937 expands to amd64 on 64-bit machines, and a null string on other 938 machines. As a result of this dereferencing, this path expands to 939 the proper kernel for the machine. 940 941 942 X86 BOOT SEQUENCE DETAILS 943 After a PC-compatible machine is turned on, the system firmware in the 944 BIOS ROM executes a power-on self test (POST), runs BIOS extensions in 945 peripheral board ROMs, and invokes software interrupt INT 19h, 946 Bootstrap. The INT 19h handler typically performs the standard PC- 947 compatible boot, which consists of trying to read the first physical 948 sector from the first diskette drive, or, if that fails, from the first 949 hard disk. The processor then jumps to the first byte of the sector 950 image in memory. 951 952 X86 PRIMARY BOOT 953 The first sector on a hard disk contains the master boot block, which 954 contains the master boot program and the FDISK table, named for the PC 955 program that maintains it. The master boot finds the active partition 956 in the FDISK table, loads its first sector (GRUB stage1), and jumps to 957 its first byte in memory. This completes the standard PC-compatible hard 958 disk boot sequence. If GRUB stage1 is installed on the master boot 959 block (see the -m option of installgrub(1M)), then stage2 is loaded 960 directly from the Solaris partition regardless of the active partition. 961 962 963 A similar sequence occurs for DVD or CD boot, but the master boot block 964 location and contents are dictated by the El Torito specification. The 965 El Torito boot will then continue in the same way as with the hard 966 disk. 967 968 969 Floppy booting is not longer supported. Booting from USB devices 970 follows the same procedure as with hard disks. 971 972 973 An x86 FDISK partition for the Solaris software begins with a one- 974 cylinder boot slice, which contains GRUB stage1 in the first sector, 975 the standard Solaris disk label and volume table of contents (VTOC) in 976 the second and third sectors, and GRUB stage2 in the fiftieth and 977 subsequent sectors. The area from sector 4 to 49 might contain boot 978 blocks for older versions of Solaris. This makes it possible for 979 multiple Solaris releases on the same FDISK to coexist. When the FDISK 980 partition for the Solaris software is the active partition, the master 981 boot program (mboot) reads the partition boot program in the first 982 sector into memory and jumps to it. It in turn reads GRUB stage2 983 program into memory and jumps to it. Once the GRUB menu is displayed, 984 the user can choose to boot an operating system on a different 985 partition, a different disk, or possibly from the network. 986 987 988 The behavior is slightly different when a disk is using EFI 989 partitioning. In that case the GRUB stage1 is always installed in the 990 first sector of the disk, and it always loads stage2 from the partition 991 specified at GRUB installation time. This only works on partitions 992 containing a ZFS root pool. 993 994 995 For network booting, the supported method is Intel's Preboot eXecution 996 Environment (PXE) standard. When booting from the network using PXE, 997 the system or network adapter BIOS uses DHCP to locate a network 998 bootstrap program (pxegrub) on a boot server and reads it using Trivial 999 File Transfer Protocol (TFTP). The BIOS executes the pxegrub by jumping 1000 to its first byte in memory. The pxegrub program downloads a menu file 1001 and presents the entries to user. 1002 1003 X86 KERNEL STARTUP 1004 The kernel startup process is independent of the kernel loading 1005 process. During kernel startup, console I/O goes to the device 1006 specified by the console property. 1007 1008 1009 When booting from UFS, the root device is specified by the bootpath 1010 property, and the root file system type is specified by the fstype 1011 property. These properties should be setup by the Solaris 1012 Install/Upgrade process in /boot/solaris/bootenv.rc and can be 1013 overridden with the -B option, described above (see the eeprom(1M) man 1014 page). 1015 1016 1017 When booting from ZFS, the root device is specified by a boot parameter 1018 specified by the -B $ZFS-BOOTFS parameter on either the kernel or module 1019 line in the GRUB menu entry. This value (as with all parameters 1020 specified by the -B option) is passed by GRUB to the kernel. 1021 1022 1023 If the console properties are not present, console I/O defaults to 1024 screen and keyboard. The root device defaults to ramdisk and the file 1025 system defaults to ufs. 1026 1027 EXAMPLES 1028 SPARC 1029 Example 1 To Boot the Default Kernel In Single-User Interactive Mode 1030 1031 1032 To boot the default kernel in single-user interactive mode, respond to 1033 the ok prompt with one of the following: 1034 1035 1036 boot -as 1037 1038 boot disk3 -as 1039 1040 1041 1042 Example 2 Network Booting with WAN Boot-Capable PROMs 1043 1044 1045 To illustrate some of the subtle repercussions of various boot command 1046 line invocations, assume that the network-boot-arguments are set and that 1047 net is devaliased as shown in the commands below. 1048 1049 1050 1051 In the following command, device arguments in the device alias are 1052 processed by the device driver. The network boot support package 1053 processes arguments in network-boot-arguments. 1054 1055 1056 boot net 1057 1058 1059 1060 1061 The command below results in no device arguments. The network boot 1062 support package processes arguments in network-boot-arguments. 1063 1064 1065 boot net: 1066 1067 1068 1069 1070 The command below results in no device arguments. rarp is the only 1071 network boot support package argument. network-boot-arguments is ignored. 1072 1073 1074 boot net:rarp 1075 1076 1077 1078 1079 In the command below, the specified device arguments are honored. The 1080 network boot support package processes arguments in network-boot- 1081 arguments. 1082 1083 1084 boot net:speed=100,duplex=full 1085 1086 1087 1088 Example 3 Using wanboot with Older PROMs 1089 1090 1091 The command below results in the wanboot binary being loaded from DVD 1092 or CD, at which time wanboot will perform DHCP and then drop into its 1093 command interpreter to allow the user to enter keys and any other 1094 necessary configuration. 1095 1096 1097 boot cdrom -F wanboot -o dhcp,prompt 1098 1099 1100 1101 x86 (32-bit) 1102 Example 4 To Boot the Default Kernel In 32-bit Single-User Interactive 1103 Mode 1104 1105 1106 To boot the default kernel in single-user interactive mode, edit the 1107 GRUB kernel command line to read: 1108 1109 1110 kernel /platform/i86pc/kernel/unix -as 1111 1112 1113 1114 x86 (64-bit Only) 1115 Example 5 To Boot the Default Kernel In 64-bit Single-User Interactive 1116 Mode 1117 1118 1119 To boot the default kernel in single-user interactive mode, edit the 1120 GRUB kernel command line to read: 1121 1122 1123 kernel /platform/i86pc/kernel/amd64/unix -as 1124 1125 1126 1127 Example 6 Switching Between 32-bit and 64-bit Kernels on 64-bit x86 1128 Platform 1129 1130 1131 To be able to boot both 32-bit and 64-bit kernels, add entries for both 1132 kernels to /boot/grub/menu.lst, and use the set-menu subcommand of 1133 bootadm(1M) to switch. See bootadm(1M) for an example of the bootadm 1134 set-menu. 1135 1136 1137 FILES 1138 /etc/inittab 1139 Table in which the initdefault state is specified 1140 1141 1142 /sbin/init 1143 Program that brings the system to the initdefault state 1144 1145 1146 64-bit SPARC Only 1147 /platform/platform-name/kernel/sparcv9/unix 1148 Default program to boot system. 1149 1150 1151 x86 Only 1152 /boot 1153 Directory containing boot-related files. 1154 1155 1156 /rpool/boot/grub/menu.lst 1157 Menu of bootable operating systems displayed by GRUB. 1158 1159 Note: this file is located on the root ZFS pool. While many 1160 installs often name their root zpool 'rpool', this is not required 1161 and the /rpool in the path above should be substituted with the 1162 name of the root pool of your current system. 1163 1164 1165 /platform/i86pc/kernel/unix 1166 32-bit kernel. 1167 1168 1169 64-bit x86 Only 1170 /platform/i86pc/kernel/amd64/unix 1171 64-bit kernel. 1172 1173 1174 SEE ALSO 1175 kmdb(1), uname(1), bootadm(1M), eeprom(1M), init(1M), installboot(1M), 1176 kernel(1M), monitor(1M), shutdown(1M), svcadm(1M), umountall(1M), 1177 zpool(1M), uadmin(2), bootparams(4), inittab(4), vfstab(4), 1178 wanboot.conf(4), filesystem(5) 1179 1180 1181 RFC 903, A Reverse Address Resolution Protocol, 1182 http://www.ietf.org/rfc/rfc903.txt 1183 1184 1185 RFC 2131, Dynamic Host Configuration Protocol, 1186 http://www.ietf.org/rfc/rfc2131.txt 1187 1188 1189 RFC 2132, DHCP Options and BOOTP Vendor Extensions, 1190 http://www.ietf.org/rfc/rfc2132.txt 1191 1192 1193 RFC 2396, Uniform Resource Identifiers (URI): Generic Syntax, 1194 http://www.ietf.org/rfc/rfc2396.txt 1195 1196 1197 1198 1199 Sun Hardware Platform Guide 1200 1201 1202 OpenBoot Command Reference Manual 1203 1204 WARNINGS 1205 The boot utility is unable to determine which files can be used as 1206 bootable programs. If the booting of a file that is not bootable is 1207 requested, the boot utility loads it and branches to it. What happens 1208 after that is unpredictable. 1209 1210 NOTES 1211 platform-name can be found using the -i option of uname(1). hardware- 1212 class-name can be found using the -m option of uname(1). 1213 1214 1215 The current release of the Solaris operating system does not support 1216 machines running an UltraSPARC-I CPU. 1217 1218 1219 1220 June 7, 2015 BOOT(1M)