1boot(1M)                System Administration Commands                boot(1M)
2
3
4

NAME

6       boot - start the system kernel or a standalone program
7

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

DESCRIPTION

20       Bootstrapping is the process of loading and executing a standalone pro‐
21       gram. For the purpose  of  this  discussion,  bootstrapping  means  the
22       process  of  loading and executing the bootable operating system. Typi‐
23       cally, the standalone program is the operating system kernel (see  ker‐
24       nel(1M)), but any standalone program can be booted instead. On a SPARC-
25       based system, the diagnostic monitor for a machine is a good example of
26       a  standalone  program  other  than  the  operating  system that can be
27       booted.
28
29
30       If the standalone is identified  as  a  dynamically-linked  executable,
31       boot will load the interpreter (linker/loader) as indicated by the exe‐
32       cutable format and then transfer control to  the  interpreter.  If  the
33       standalone  is  statically-linked,  it will jump directly to the stand‐
34       alone.
35
36
37       Once the kernel is loaded, it starts the UNIX system, mounts the neces‐
38       sary  file  systems  (see  vfstab(4)), and runs /sbin/init to bring the
39       system to the "initdefault" state specified in /etc/inittab. See  init‐
40       tab(4).
41
42   SPARC Bootstrap Procedure
43       On  SPARC  based systems, the bootstrap procedure on most machines con‐
44       sists 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
64       (when booting from a disk), or inetboot or wanboot (when booting across
65       the 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 ar‐
74       chive from the boot device.
75
76
77       An IP address can be obtained in one of three ways: RARP, DHCP, or man‐
78       ual configuration, depending on the functions available in and configu‐
79       ration of the PROM. Machines of the sun4u and  sun4v  kernel  architec‐
80       tures have DHCP-capable PROMs.
81
82
83       The boot command syntax for specifying the two methods of network boot‐
84       ing 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  net‐
100       work 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, inet‐
113       boot will also use reverse ARP to fetch its IP address, then  broadcast
114       bootparams RPC calls (see bootparams(4)) to locate configuration infor‐
115       mation and its root file system. inetboot then loads the  boot  archive
116       by means of NFS and transfers control to that archive.
117
118
119       When booting over the network using DHCP, the PROM broadcasts the hard‐
120       ware address and kernel architecture and requests an IP  address,  boot
121       parameters,  and network configuration information. After a DHCP server
122       responds and is selected (from  among  potentially  multiple  servers),
123       that server sends to the client an IP address and all other information
124       needed to boot the client.  After  receipt  of  this  information,  the
125       client PROM examines the name of the file to be loaded, and will behave
126       in one of two ways, depending on whether the file's name appears to  be
127       an  HTTP  URL.  If it does not, the PROM downloads inetboot, loads that
128       file into memory, and executes it. inetboot  loads  the  boot  archive,
129       which  takes  over  the  machine and releases inetboot. Startup scripts
130       then initiate the DHCP agent (see dhcpagent(1M)), which implements fur‐
131       ther 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 pro‐
137       ceeding to execute it. The file is expected to be the  wanboot  binary.
138       The  WAN  boot  process  can  be configured to use either DHCP or NVRAM
139       properties to discover the install server and router  and  the  proxies
140       needed  to  connect to it. When wanboot begins executing, it determines
141       whether sufficient information is available to it to allow it  to  pro‐
142       ceed. If any necessary information is missing, it will either exit with
143       an appropriate error or bring up a command interpreter and  prompt  for
144       further configuration information. Once wanboot has obtained the neces‐
145       sary information, it loads the boot loader  into  memory  by  means  of
146       HTTP.  If  an  encryption key has been installed on the client, wanboot
147       will verify the boot loader's  signature  and  its  accompanying  hash.
148       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  config‐
153       ured  with an HMAC SHA-1 key, the boot loader will perform an integrity
154       check of the root file system. Once  the  root  file  system  has  been
155       loaded into memory (and possibly had an integrity check performed), the
156       boot archive is  transferred  from  the  server.  If  provided  with  a
157       boot_logger  URL  by  means  of  the wanboot.conf(4) file, wanboot will
158       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
173       the form:
174
175         boot ... -o opt1[,opt2[,...]]
176
177
178
179
180       where each option may be an action:
181
182       dhcp
183
184           Require  wanboot  to  obtain  configuration  parameters by means of
185           DHCP.
186
187
188       prompt
189
190           Cause wanboot to enter its command interpreter.
191
192
193       <cmd>
194
195           One of the interpreter commands listed below.
196
197
198
199       ...or an assignment, using the  interpreter's  parameter  names  listed
200       below.
201
202
203       The wanboot Command Interpreter
204
205
206       The  wanboot  command interpreter is invoked by supplying a client-pro‐
207       gram-args of "-o prompt" when booting. Input consists  of  single  com‐
208       mands  or assignments, or a comma-separated list of commands or assign‐
209       ments. The configuration parameters are:
210
211       host-ip
212
213           IP address of the client (in dotted-decimal notation)
214
215
216       router-ip
217
218           IP address of the default router (in dotted-decimal notation)
219
220
221       subnet-mask
222
223           subnet mask (in dotted-decimal notation)
224
225
226       client-id
227
228           DHCP client identifier (a quoted ASCII string or hex ASCII)
229
230
231       hostname
232
233           hostname to request in DHCP transactions (ASCII)
234
235
236       http-proxy
237
238           HTTP proxy server specification (IPADDR[:PORT])
239
240
241
242       The key names are:
243
244       3des
245
246           the triple DES encryption key (48 hex ASCII characters)
247
248
249       aes
250
251           the AES encryption key (32 hex ASCII characters)
252
253
254       sha1
255
256           the HMAC SHA-1 signature key (40 hex ASCII characters)
257
258
259
260       Finally, the URL or the WAN boot CGI is referred to by means of:
261
262       bootserver
263
264           URL of WAN boot's CGI (the equivalent of OBP's file parameter)
265
266
267
268       The interpreter accepts the following commands:
269
270       help
271
272           Print a brief description of the available commands
273
274
275       var=val
276
277           Assign val to var, where var is one of the configuration  parameter
278           names, the key names, or bootserver.
279
280
281       var=
282
283           Unset parameter var.
284
285
286       list
287
288           List all parameters and their values (key values retrieved by means
289           of OBP are never shown).
290
291
292       prompt
293
294           Prompt for values for unset parameters. The name of each  parameter
295           and  its current value (if any) is printed, and the user can accept
296           this value (press Return) or enter a new value.
297
298
299       go
300
301           Once the user is satisfied that all values have been entered, leave
302           the interpreter and continue booting.
303
304
305       exit
306
307           Quit the boot interpreter and return to OBP's ok prompt.
308
309
310
311       Any  of these assignments or commands can be passed on the command line
312       as part of the -o options, subject to the OBP limit of  128  bytes  for
313       boot  arguments.  For  example,  -o  list,go  would simply list current
314       (default) values of the parameters and then continue booting.
315
316   iSCSI Boot
317       iSCSI boot is currently supported only on x86. The  host  being  booted
318       must  be  equipped with NIC(s) capable of iBFT (iSCSI Boot Firmware Ta‐
319       ble) or have the mainboard's BIOS be iBFT-capable. iBFT, defined in the
320       Advanced  Configuration  and Power Interface (ACPI) 3.0b specification,
321       specifies a block of information that contains various parameters  that
322       are useful to the iSCSI Boot process.
323
324
325       Firmware  implementing  iBFT  presents an iSCSI disk in the BIOS during
326       startup as a bootable device by  establishing  the  connection  to  the
327       iSCSI  target.  The rest of the process of iSCSI booting is the same as
328       booting from a local disk.
329
330
331       To configure the iBFT properly, users need to refer to  the  documenta‐
332       tion from their hardware vendors.
333
334   Booting from Disk
335       When  booting  from  disk,  the  OpenBoot  PROM firmware reads the boot
336       blocks from blocks 1 to 15 of  the  partition  specified  as  the  boot
337       device.  This standalone booter usually contains a file system-specific
338       reader capable of reading the boot archive.
339
340
341       If the pathname to the standalone is relative (does not  begin  with  a
342       slash),  the  second level boot will look for the standalone in a plat‐
343       form-dependent search path. This path is guaranteed to  contain  /plat‐
344       form/platform-name.  Many SPARC platforms next search the platform-spe‐
345       cific path entry /platform/hardware-class-name. See  filesystem(5).  If
346       the  pathname  is  absolute, boot will use the specified path. The boot
347       program then loads the standalone at the appropriate address, and  then
348       transfers control.
349
350
351       Once  the  boot  archive  has  been  transferred  from the boot device,
352       Solaris can initialize and take  over  control  of  the  machine.  This
353       process is further described in the "Boot Archive Phase," below, and is
354       identical on all platforms.
355
356
357       If the filename is not given on the command line  or  otherwise  speci‐
358       fied,  for  example,  by  the boot-file NVRAM variable, boot chooses an
359       appropriate default file to load based on what software is installed on
360       the system and the capabilities of the hardware and firmware.
361
362
363       The path to the kernel must not contain any whitespace.
364
365   Booting from ZFS
366       Booting  from  ZFS  differs  from booting from UFS in that, with ZFS, a
367       device specifier identifies a storage pool, not a single root file sys‐
368       tem.  A  storage  pool can contain multiple bootable datasets (that is,
369       root file systems). Therefore, when booting from ZFS, it is not  suffi‐
370       cient to specify a boot device. One must also identify a root file sys‐
371       tem within the pool that was identified by the boot device. By default,
372       the  dataset  selected  for booting is the one identified by the pool's
373       bootfs property. This default selection can be overridden by specifying
374       an alternate bootable dataset with the -Z option.
375
376   Boot Archive Phase
377       The  boot archive contains a file system image that is mounted using an
378       in-memory disk. The image is self-describing, specifically containing a
379       file  system  reader  in the boot block. This file system reader mounts
380       and opens the RAM disk image, then reads and executes the  kernel  con‐
381       tained within it. By default, this kernel is in:
382
383         /platform/`uname -i`/kernel/unix
384
385
386
387
388       If  booting  from ZFS, the pathnames of both the archive and the kernel
389       file are resolved in the root file system (that is,  dataset)  selected
390       for booting as described in the previous section.
391
392
393       The initialization of the kernel continues by loading necessary drivers
394       and modules from the in-memory filesystem until I/O can  be  turned  on
395       and  the  root filesystem mounted. Once the root filesystem is mounted,
396       the in-memory filesystem is no longer needed and is discarded.
397
398   OpenBoot PROM boot Command Behavior
399       The OpenBoot boot command takes arguments of the following form:
400
401         ok boot [device-specifier] [arguments]
402
403
404
405
406       The default boot command has no arguments:
407
408         ok boot
409
410
411
412
413       If no device-specifier is given on the boot command line, OpenBoot typ‐
414       ically  uses  the  boot-device  or  diag-device  NVRAM  variable. If no
415       optional arguments are given on the command  line,  OpenBoot  typically
416       uses  the  boot-file  or diag-file NVRAM variable as default boot argu‐
417       ments. (If the system is in diagnostics mode, diag-device and diag-file
418       are used instead of boot-device and boot-file).
419
420
421       arguments  may  include  more than one string. All argument strings are
422       passed to the secondary booter; they are not interpreted by OpenBoot.
423
424
425       If any arguments are specified on the boot command line,  then  neither
426       the boot-file nor the diag-file NVRAM variable is used. The contents of
427       the NVRAM variables are not merged with  command  line  arguments.  For
428       example, the command:
429
430         ok boot -s
431
432
433
434
435       ignores the settings in both boot-file and diag-file; it interprets the
436       string "-s" as arguments. boot will not use the contents  of  boot-file
437       or diag-file.
438
439
440       With older PROMs, the command:
441
442         ok boot net
443
444
445
446
447       took no arguments, using instead the settings in boot-file or diag-file
448       (if set) as the default file name and arguments to  pass  to  boot.  In
449       most cases, it is best to allow the boot command to choose an appropri‐
450       ate default based upon the system type, system hardware  and  firmware,
451       and  upon what is installed on the root file system. Changing boot-file
452       or diag-file can generate unexpected results in certain circumstances.
453
454
455       This behavior is found on most OpenBoot 2.x and 3.x based systems. Note
456       that differences may occur on some platforms.
457
458
459       The command:
460
461
462       ok boot cdrom
463
464
465       ...also  normally  takes no arguments. Accordingly, if boot-file is set
466       to the 64-bit kernel filename and you attempt to boot the  installation
467       CD  or  DVD  with  boot cdrom, boot will fail if the installation media
468       contains only a 32-bit kernel.
469
470
471       Because the contents of boot-file or diag-file can be ignored depending
472       on the form of the boot command used, reliance upon boot-file should be
473       discouraged for most production systems.
474
475
476       When executing a WAN boot from a local (CD or DVD) copy of wanboot, one
477       must use:
478
479
480       ok boot cdrom -F wanboot - install
481
482
483       Modern  PROMs have enhanced the network boot support package to support
484       the following syntax for arguments to be processed by the package:
485
486
487       [protocol,] [key=value,]*
488
489
490       All arguments are optional and can appear  in  any  order.  Commas  are
491       required  unless  the argument is at the end of the list. If specified,
492       an argument takes precedence over any default values,  or,  if  booting
493       using  DHCP,  over  configuration information provided by a DHCP server
494       for those parameters.
495
496
497       protocol, above, specifies the address discovery protocol to be used.
498
499
500       Configuration parameters, listed  below,  are  specified  as  key=value
501       attribute pairs.
502
503       tftp-server
504
505           IP address of the TFTP server
506
507
508       file
509
510           file to download using TFTP or URL for WAN boot
511
512
513       host-ip
514
515           IP address of the client (in dotted-decimal notation)
516
517
518       router-ip
519
520           IP address of the default router
521
522
523       subnet-mask
524
525           subnet mask (in dotted-decimal notation)
526
527
528       client-id
529
530           DHCP client identifier
531
532
533       hostname
534
535           hostname to use in DHCP transactions
536
537
538       http-proxy
539
540           HTTP proxy server specification (IPADDR[:PORT])
541
542
543       tftp-retries
544
545           maximum number of TFTP retries
546
547
548       dhcp-retries
549
550           maximum number of DHCP retries
551
552
553
554       The list of arguments to be processed by the network boot support pack‐
555       age is specified in one of two ways:
556
557           o      As arguments passed to the package's open method, or
558
559           o      arguments listed in the  NVRAM  variable  network-boot-argu‐
560                  ments.
561
562
563       Arguments specified in network-boot-arguments will be processed only if
564       there are no arguments passed to the package's open method.
565
566
567       Argument Values
568
569
570       protocol specifies the  address  discovery  protocol  to  be  used.  If
571       present, the possible values are rarp or dhcp.
572
573
574       If  other  configuration parameters are specified in the new syntax and
575       style specified by this document, absence  of  the  protocol  parameter
576       implies manual configuration.
577
578
579       If  no  other configuration parameters are specified, or if those argu‐
580       ments are specified in the positional parameter syntax  currently  sup‐
581       ported,  the  absence of the protocol parameter causes the network boot
582       support package to use the platform-specific default address  discovery
583       protocol.
584
585
586       Manual  configuration  requires  that  the  client  be  provided its IP
587       address, the name of the boot file, and the address of the server  pro‐
588       viding  the boot file image. Depending on the network configuration, it
589       might be required that subnet-mask and router-ip also be specified.
590
591
592       If the protocol argument is not specified,  the  network  boot  support
593       package uses the platform-specific default address discovery protocol.
594
595
596       tftp-server  is  the  IP address (in standard IPv4 dotted-decimal nota‐
597       tion) of the TFTP server that provides the file to  download  if  using
598       TFTP.
599
600
601       When  using  DHCP,  the value, if specified, overrides the value of the
602       TFTP server specified in the DHCP response.
603
604
605       The TFTP RRQ is unicast to the server if one is specified as  an  argu‐
606       ment or in the DHCP response. Otherwise, the TFTP RRQ is broadcast.
607
608
609       file  specifies  the file to be loaded by TFTP from the TFTP server, or
610       the URL if using HTTP. The use of HTTP is triggered if the file name is
611       a URL, that is, the file name starts with http: (case-insensitive).
612
613
614       When  using RARP and TFTP, the default file name is the ASCII hexadeci‐
615       mal representation of the IP address of the client, as documented in  a
616       preceding section of this document.
617
618
619       When using DHCP, this argument, if specified, overrides the name of the
620       boot file specified in the DHCP response.
621
622
623       When using DHCP and TFTP, the default file name is constructed from the
624       root node's name property, with commas (,) replaced by periods (.).
625
626
627       When  specified  on  the  command  line,  the filename must not contain
628       slashes (/).
629
630
631       The format of URLs is described in RFC 2396. The HTTP  server  must  be
632       specified  as an IP address (in standard IPv4 dotted-decimal notation).
633       The optional port number is specified in decimal.  If  a  port  is  not
634       specified, port 80 (decimal) is implied.
635
636
637       The URL presented must be "safe-encoded", that is, the package does not
638       apply escape encodings to the URL  presented.  URLs  containing  commas
639       must  be  presented as a quoted string. Quoting URLs is optional other‐
640       wise.
641
642
643       host-ip specifies the IP address (in standard IPv4 dotted-decimal nota‐
644       tion)  of  the  client,  the  system being booted. If using RARP as the
645       address discovery protocol, specifying this argument makes use of  RARP
646       unnecessary.
647
648
649       If  DHCP  is used, specifying the host-ip argument causes the client to
650       follow the steps required of a client with  an  "Externally  Configured
651       Network Address", as specified in RFC 2131.
652
653
654       router-ip  is the IP address (in standard IPv4 dotted-decimal notation)
655       of a router on a directly connected network. The router will be used as
656       the first hop for communications spanning networks. If this argument is
657       supplied, the router specified here takes precedence over the preferred
658       router specified in the DHCP response.
659
660
661       subnet-mask (specified in standard IPv4 dotted-decimal notation) is the
662       subnet mask on the client's network. If the subnet mask is not provided
663       (either by means of this argument or in the DHCP response), the default
664       mask appropriate to the network class (Class A, B, or C) of the address
665       assigned to the booting client will be assumed.
666
667
668       client-id  specifies  the  unique  identifier  for the client. The DHCP
669       client identifier is derived from this value. Client identifiers can be
670       specified as:
671
672           o      The ASCII hexadecimal representation of the identifier, or
673
674           o      a quoted string
675
676
677       Thus,  client-id="openboot"  and client-id=6f70656e626f6f74 both repre‐
678       sent a DHCP client identifier of 6F70656E626F6F74.
679
680
681       Identifiers specified on the command line must must not  include  slash
682       (/) or spaces.
683
684
685       The  maximum  length  of  the DHCP client identifier is 32 bytes, or 64
686       characters representing 32 bytes if using the ASCII  hexadecimal  form.
687       If  the latter form is used, the number of characters in the identifier
688       must be an even number. Valid characters are 0-9, a-f, and A-F.
689
690
691       For correct identification of clients, the client  identifier  must  be
692       unique  among  the  client  identifiers used on the subnet to which the
693       client is attached. System administrators are responsible for  choosing
694       identifiers that meet this requirement.
695
696
697       Specifying  a client identifier on a command line takes precedence over
698       any other DHCP mechanism of specifying identifiers.
699
700
701       hostname (specified as a string) specifies the hostname to be  used  in
702       DHCP  transactions.  The  name might or might not be qualified with the
703       local domain name. The maximum length of the hostname  is  255  charac‐
704       ters.
705
706       Note -
707
708         The  hostname  parameter  can  be  used  in service environments that
709         require that the client provide the  desired  hostname  to  the  DHCP
710         server.  Clients  provide  the  desired  hostname to the DHCP server,
711         which can then register the hostname and IP address assigned  to  the
712         client with DNS.
713
714
715       http-proxy is specified in the following standard notation for a host:
716
717         host [":"" port]
718
719
720
721
722       ...where  host  is  specified as an IP ddress (in standard IPv4 dotted-
723       decimal notation) and the optional port is specified in decimal.  If  a
724       port is not specified, port 8080 (decimal) is implied.
725
726
727       tftp-retries  is  the  maximum number of retries (specified in decimal)
728       attempted before  the  TFTP  process  is  determined  to  have  failed.
729       Defaults to using infinite retries.
730
731
732       dhcp-retries  is  the  maximum number of retries (specified in decimal)
733       attempted before  the  DHCP  process  is  determined  to  have  failed.
734       Defaults to of using infinite retries.
735
736   x86 Bootstrap Procedure
737       On x86 based systems, the bootstrapping process consists of two concep‐
738       tually distinct phases, kernel loading and kernel initialization.  Ker‐
739       nel loading is implemented in GRUB (GRand Unified Bootloader) using the
740       BIOS ROM on the system board, and BIOS extensions in ROMs on peripheral
741       boards.  The  BIOS  loads GRUB, starting with the first physical sector
742       from a hard disk, DVD, or CD. If supported by the ROM  on  the  network
743       adapter,  the  BIOS can also download the pxegrub binary from a network
744       boot server. Once GRUB is located, it executes a command in a  menu  to
745       load the unix kernel and a pre-constructed boot archive containing ker‐
746       nel modules and data.
747
748
749       If the device identified by GRUB as the  boot  device  contains  a  ZFS
750       storage  pool,  the  menu.lst file used to create the GRUB menu will be
751       found in the dataset at the root of the pool's dataset hierarchy.  This
752       is  the  dataset with the same name as the pool itself. There is always
753       exactly one such dataset in a pool, and so this dataset is  well-suited
754       for  pool-wide  data  such  as  the  menu.lst file. After the system is
755       booted, this dataset is mounted at /poolname in the root file system.
756
757
758       There can be multiple bootable datasets (that is,  root  file  systems)
759       within  a  pool. By default, the file system in which file name entries
760       in a menu.lst file are resolved is the one  identified  by  the  pool's
761       bootfs  property (see zpool(1M)). However, a menu.lst entry can contain
762       a bootfs command, which specifies an alternate dataset in the pool.  In
763       this  way, the menu.lst file can contain entries for multiple root file
764       systems within the pool.
765
766
767       Kernel initialization starts when GRUB finishes loading  the  boot  ar‐
768       chive  and  hands  control over to the unix binary. At this point, GRUB
769       becomes inactive and no more I/O occurs with the boot device. The  Unix
770       operating  system  initializes, links in the necessary modules from the
771       boot archive and mounts the root file system on the real  root  device.
772       At  this  point, the kernel regains storage I/O, mounts additional file
773       systems (see vfstab(4)), and starts various operating  system  services
774       (see smf(5)).
775
776   Failsafe Mode
777       A requirement of booting from a root filesystem image built into a boot
778       archive then remounting root onto the actual root device  is  that  the
779       contents  of  the  boot archive and the root filesystem must be consis‐
780       tent. Otherwise, the proper operation and integrity of the machine can‐
781       not be guaranteed.
782
783
784       The  term  "consistent"  means  that  all files and modules in the root
785       filesystem are also present in the boot archive and have identical con‐
786       tents.  Since the boot strategy requires first reading and mounting the
787       boot archive as the first-stage root image, all unloadable kernel  mod‐
788       ules  and  initialization derived from the contents of the boot archive
789       are required to match the real root filesystem.  Without  such  consis‐
790       tency,  it  is  possible that the system could be running with a kernel
791       module or parameter setting applied to the root device  before  reboot,
792       but  not  yet  updated  in  the  root archive. This inconsistency could
793       result in system instability or data loss.
794
795
796       Once the root filesystem is mounted, and before relinquishing  the  in-
797       memory  filesystem, Solaris performs a consistency verification against
798       the two file systems. If an inconsistency is detected, Solaris suspends
799       the  normal  boot  sequence and falls back to failsafe mode. Correcting
800       this state requires the administrator take one of two steps. The recom‐
801       mended  procedure  is to reboot to the failsafe archive and rebuild the
802       boot archive. This ensures that a known kernel is booted and  function‐
803       ing  for  the archive rebuild process. Alternatively, the administrator
804       can elect to clear the inconsistent boot archive service state and con‐
805       tinue  system bring-up if the inconsistency is such that correct system
806       operation will not be impaired. See svcadm(1M).
807
808
809       If the boot archive service is cleared and system bring-up is continued
810       (the  second alternative above), the system may be running with unload‐
811       able kernel drivers or other modules that are out-of-date with  respect
812       to  the  root filesystem. As such, correct system operation may be com‐
813       promised.
814
815
816       To ensure that the boot archive is consistent, the normal system  shut‐
817       down  process,  as initiated by reboot(1M) and shutdown(1M), checks for
818       and applies updates to the boot archive at the conclusion of the umoun‐
819       tall(1M) milestone.
820
821
822       An  update  to  any kernel file, driver, module or driver configuration
823       file that needs to be included in the boot archive after the  umountall
824       service  is  complete  will result in a failed boot archive consistency
825       check during the next boot. To avoid this, it is recommended to  always
826       shut down a machine cleanly.
827
828
829       If  an  update is required to the kernel after completion of the umoun‐
830       tall service, the administrator may elect to  rebuild  the  archive  by
831       invoking:
832
833         # bootadm update-archive
834
835
836
837   Failsafe Boot Archive
838       The  failsafe  archive  can be used to boot the machine at any time for
839       maintenance or troubleshooting. The failsafe boot archive is  installed
840       on the machine, sourced from the miniroot archive. Booting the failsafe
841       archive causes the machine to boot using the  in-memory  filesystem  as
842       the root device.
843
844   SPARC
845       The SPARC failsafe archive is:
846
847         /platform/`uname -i`/failsafe
848
849
850
851
852       ...and can be booted as follows:
853
854         ok boot [device-specifier] -F failsafe
855
856
857
858
859       If  a  user  wishes  to  boot  a failsafe archive from a particular ZFS
860       bootable dataset, this can be done as follows:
861
862         ok boot [device-specifier] -Z dataset -F failsafe
863
864
865
866   x86
867       The x86 failsafe archive is:
868
869         /boot/x86.miniroot-safe
870
871
872
873
874       ...and can be booted by selecting the Solaris failsafe  item  from  the
875       GRUB menu.
876

OPTIONS

878   SPARC
879       The following SPARC options are supported:
880
881       -a
882
883           The  boot  program  interprets  this flag to mean ask me, and so it
884           prompts for the name of the  standalone.  The  '-a'  flag  is  then
885           passed to the standalone program.
886
887
888       -D default-file
889
890           Explicitly  specify the default-file. On some systems, boot chooses
891           a dynamic default file, used when none is otherwise specified. This
892           option allows the default-file to be explicitly set and can be use‐
893           ful when booting kmdb(1) since, by default, kmdb loads the default-
894           file as exported by the boot program.
895
896
897       -F object
898
899           Boot  using the named object. The object must be either an ELF exe‐
900           cutable or bootable object containing a boot block. The primary use
901           is to boot the failsafe or wanboot boot archive.
902
903
904       -L
905
906           List the bootable datasets within a ZFS pool. You can select one of
907           the bootable datasets in the list, after  which  detailed  instruc‐
908           tions  for  booting  that  dataset are displayed. Boot the selected
909           dataset by following the instructions.  This  option  is  supported
910           only when the boot device contains a ZFS storage pool.
911
912
913       -V
914
915           Display verbose debugging information.
916
917
918       boot-flags
919
920           The boot program passes all boot-flags to file. They are not inter‐
921           preted by boot. See the kernel(1M) and  kmdb(1)  manual  pages  for
922           information about the options available with the default standalone
923           program.
924
925
926       client-program-args
927
928           The boot program passes all client-program-args to file.  They  are
929           not interpreted by boot.
930
931
932       file
933
934           Name  of a standalone program to boot. If a filename is not explic‐
935           itly specified, either on the boot command line or in the boot-file
936           NVRAM variable, boot chooses an appropriate default filename.
937
938
939       OBP names
940
941           Specify  the  open  boot prom designations. For example, on Desktop
942           SPARC based systems,  the  designation  /sbus/esp@0,800000/sd@3,0:a
943           indicates  a SCSI disk (sd) at target 3, lun0 on the SCSI bus, with
944           the esp host adapter plugged into slot 0.
945
946
947       -Z dataset
948
949           Boot from the root file system in the specified ZFS dataset.
950
951
952   x86
953       The following x86 options are supported:
954
955       -B prop=val...
956
957           One or more property-value pairs to be passed to the kernel. Multi‐
958           ple  property-value pairs must be separated by a comma. Use of this
959           option is the equivalent of the command: eeprom prop=val. See  eep‐
960           rom(1M) for available properties and valid values.
961
962           If  the  root file system corresponding to this menu entry is a ZFS
963           dataset, the menu entry needs the following option added:
964
965             -B $ZFS-BOOTFS
966
967
968
969
970       boot-args
971
972           The boot program passes all boot-args to file. They are not  inter‐
973           preted  by  boot.  See kernel(1M) and kmdb(1) for information about
974           the options available with the kernel.
975
976
977       /platform/i86pc/kernel/$ISADIR/unix
978
979           Name of the kernel to boot. When using the kernel$  token,  $ISADIR
980           expands  to  amd64  on  64-bit machines, and a null string on other
981           machines. As a result of this dereferencing, this path  expands  to
982           the proper kernel for the machine.
983
984

X86 BOOT SEQUENCE DETAILS

986       After  a PC-compatible machine is turned on, the system firmware in the
987       BIOS ROM executes a power-on self test (POST), runs BIOS extensions  in
988       peripheral  board  ROMs,  and invokes software interrupt INT 19h, Boot‐
989       strap. The INT 19h handler typically performs the standard  PC-compati‐
990       ble  boot,  which  consists of trying to read the first physical sector
991       from the first diskette drive, or, if that fails, from the  first  hard
992       disk. The processor then jumps to the first byte of the sector image in
993       memory.
994

X86 PRIMARY BOOT

996       The first sector on a floppy disk contains the master boot block  (GRUB
997       stage1).  The  stage 1 is responsible for loading GRUB stage2. Now GRUB
998       is  fully  functional.  It   reads   and   executes   the   menu   file
999       /boot/grub/menu.lst.  A similar sequence occurs for DVD or CD boot, but
1000       the master boot block location and contents  are  dictated  by  the  El
1001       Torito specification. The El Torito boot also leads to strap.com, which
1002       in turn loads boot.bin.
1003
1004
1005       The first sector on a hard disk contains the master boot  block,  which
1006       contains  the master boot program and the FDISK table, named for the PC
1007       program that maintains it. The master boot finds the  active  partition
1008       in  the FDISK table, loads its first sector (GRUB stage1), and jumps to
1009       its first byte in memory. This  completes  the  standard  PC-compatible
1010       hard disk boot sequence. If GRUB stage1 is installed on the master boot
1011       block (see the -m option of installgrub(1M)),  then  stage2  is  loaded
1012       directly from the Solaris FDISK partition regardless of the active par‐
1013       tition.
1014
1015
1016       An x86 FDISK partition for the Solaris  software  begins  with  a  one-
1017       cylinder  boot  slice,  which contains GRUB stage1 in the first sector,
1018       the standard Solaris disk label and volume table of contents (VTOC)  in
1019       the  second and third sectors, and GRUB stage2 in the fiftieth and sub‐
1020       sequent sectors. The area from sector 4 to 49 might contain boot blocks
1021       for  older  versions  of  Solaris.  This makes it possible for multiple
1022       Solaris releases on the same FDISK to coexist. When the FDISK partition
1023       for  the Solaris software is the active partition, the master boot pro‐
1024       gram (mboot) reads the partition boot program in the first sector  into
1025       memory  and jumps to it. It in turn reads GRUB stage2 program into mem‐
1026       ory and jumps to it. Once the GRUB menu  is  displayed,  the  user  can
1027       choose  to boot an operating system on a different partition, a differ‐
1028       ent disk, or possibly from the network.
1029
1030
1031       For network booting, the supported method is Intel's Preboot  eXecution
1032       Environment  (PXE)  standard.  When booting from the network using PXE,
1033       the system or network adapter BIOS uses DHCP to locate a network  boot‐
1034       strap  program  (pxegrub)  on  a boot server and reads it using Trivial
1035       File Transfer Protocol (TFTP). The BIOS executes the pxegrub by jumping
1036       to  its first byte in memory. The pxegrub program downloads a menu file
1037       and presents the entries to user.
1038

X86 KERNEL STARTUP

1040       The kernel  startup  process  is  independent  of  the  kernel  loading
1041       process.  During  kernel startup, console I/O goes to the device speci‐
1042       fied by the console property.
1043
1044
1045       When booting from UFS, the root device is  specified  by  the  bootpath
1046       property,  and  the  root  file  system type is specified by the fstype
1047       property.  These  properties   should   be   setup   by   the   Solaris
1048       Install/Upgrade process in /boot/solaris/bootenv.rc and can be overrid‐
1049       den with the -B option, described above (see the eeprom(1M) man page).
1050
1051
1052       When booting from ZFS, the root device is specified by a boot parameter
1053       specified  by the -B $ZFS-BOOTFS parameter on either the kernel or mod‐
1054       ule line in the GRUB menu entry. This value  (as  with  all  parameters
1055       specified by the -B option) is passed by GRUB to the kernel.
1056
1057
1058       If  the  console  properties  are  not present, console I/O defaults to
1059       screen and keyboard. The root device defaults to ramdisk and  the  file
1060       system defaults to ufs.
1061

EXAMPLES

1063   SPARC
1064       Example 1 To Boot the Default Kernel In Single-User Interactive Mode
1065
1066
1067       To  boot the default kernel in single-user interactive mode, respond to
1068       the ok prompt with one of the following:
1069
1070
1071         boot -as
1072
1073         boot disk3 -as
1074
1075
1076
1077       Example 2 Network Booting with WAN Boot-Capable PROMs
1078
1079
1080       To illustrate some of the subtle repercussions of various boot  command
1081       line  invocations,  assume  that the network-boot-arguments are set and
1082       that net is devaliased as shown in the commands below.
1083
1084
1085
1086       In the following command, device arguments in the device alias are pro‐
1087       cessed by the device driver. The network boot support package processes
1088       arguments in network-boot-arguments.
1089
1090
1091         boot net
1092
1093
1094
1095
1096       The command below results in no device arguments. The network boot sup‐
1097       port package processes arguments in network-boot-arguments.
1098
1099
1100         boot net:
1101
1102
1103
1104
1105       The command below results in no device arguments. rarp is the only net‐
1106       work boot support package argument. network-boot-arguments is ignored.
1107
1108
1109         boot net:rarp
1110
1111
1112
1113
1114       In the command below, the specified device arguments are  honored.  The
1115       network  boot support package processes arguments in network-boot-argu‐
1116       ments.
1117
1118
1119         boot net:speed=100,duplex=full
1120
1121
1122
1123       Example 3 Using wanboot with Older PROMs
1124
1125
1126       The command below results in the wanboot binary being loaded  from  DVD
1127       or  CD,  at which time wanboot will perform DHCP and then drop into its
1128       command interpreter to allow the user to enter keys and any other  nec‐
1129       essary configuration.
1130
1131
1132         boot cdrom -F wanboot -o dhcp,prompt
1133
1134
1135
1136   x86 (32-bit)
1137       Example  4 To Boot the Default Kernel In 32-bit Single-User Interactive
1138       Mode
1139
1140
1141       To boot the default kernel in single-user interactive  mode,  edit  the
1142       GRUB kernel command line to read:
1143
1144
1145         kernel /platform/i86pc/kernel/unix -as
1146
1147
1148
1149   x86 (64-bit Only)
1150       Example  5 To Boot the Default Kernel In 64-bit Single-User Interactive
1151       Mode
1152
1153
1154       To boot the default kernel in single-user interactive  mode,  edit  the
1155       GRUB kernel command line to read:
1156
1157
1158         kernel /platform/i86pc/kernel/amd64/unix -as
1159
1160
1161
1162       Example  6  Switching  Between  32-bit and 64-bit Kernels on 64-bit x86
1163       Platform
1164
1165
1166       To be able to boot both 32-bit and 64-bit kernels, add entries for both
1167       kernels  to  /boot/grub/menu.lst,  and  use  the set-menu subcommand of
1168       bootadm(1M) to switch. See bootadm(1M) for an example  of  the  bootadm
1169       set-menu.
1170
1171

FILES

1173       /platform/platform-name/ufsboot
1174
1175           Second-level program to boot from a disk, DVD, or CD
1176
1177
1178       /etc/inittab
1179
1180           Table in which the initdefault state is specified
1181
1182
1183       /sbin/init
1184
1185           Program that brings the system to the initdefault state
1186
1187
1188   64-bit SPARC Only
1189       /platform/platform-name/kernel/sparcv9/unix
1190
1191           Default program to boot system.
1192
1193
1194   x86 Only
1195       /boot
1196
1197           Directory containing boot-related files.
1198
1199
1200       /boot/grub/menu.lst
1201
1202           Menu of bootable operating systems displayed by GRUB.
1203
1204
1205       /platform/i86pc/kernel/unix
1206
1207           32-bit kernel.
1208
1209
1210   64-bit x86 Only
1211       /platform/i86pc/kernel/amd64/unix
1212
1213           64-bit kernel.
1214
1215

SEE ALSO

1217       kmdb(1),  uname(1), bootadm(1M), eeprom(1M), init(1M), installboot(1M),
1218       kernel(1M),  monitor(1M),  shutdown(1M),   svcadm(1M),   umountall(1M),
1219       zpool(1M),   uadmin(2),   bootparams(4),  inittab(4),  vfstab(4),  wan‐
1220       boot.conf(4), filesystem(5)
1221
1222
1223       RFC     903,     A     Reverse     Address     Resolution     Protocol,
1224       http://www.ietf.org/rfc/rfc903.txt
1225
1226
1227       RFC      2131,      Dynamic      Host      Configuration      Protocol,
1228       http://www.ietf.org/rfc/rfc2131.txt
1229
1230
1231       RFC   2132,    DHCP    Options    and    BOOTP    Vendor    Extensions,
1232       http://www.ietf.org/rfc/rfc2132.txt
1233
1234
1235       RFC   2396,   Uniform   Resource  Identifiers  (URI):  Generic  Syntax,
1236       http://www.ietf.org/rfc/rfc2396.txt
1237
1238
1239
1240
1241
1242       Sun Hardware Platform Guide
1243
1244
1245       OpenBoot Command Reference Manual
1246

WARNINGS

1248       The boot utility is unable to determine which  files  can  be  used  as
1249       bootable  programs.  If  the  booting of a file that is not bootable is
1250       requested, the boot utility loads it and branches to it.  What  happens
1251       after that is unpredictable.
1252

NOTES

1254       platform-name  can  be found using the -i option of uname(1). hardware-
1255       class-name can be found using the -m option of uname(1).
1256
1257
1258       The current release of the Solaris operating system  does  not  support
1259       machines running an UltraSPARC-I CPU.
1260
1261
1262
1263SunOS 5.11                        2 Mar 2009                          boot(1M)
Impressum