1 .\" Copyright (c) 1999 Daniel C. Sobral
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .Dd September 29, 2021
32 .Nd kernel bootstrapping final stage
38 kernel bootstrapping process.
39 On IA32 (i386) architectures, it is a
42 It is linked statically to
44 and usually located in the directory
47 It provides a scripting language that can be used to
48 automate tasks, do pre-configuration or assist in recovery
50 This scripting language is roughly divided in
52 The smaller one is a set of commands
53 designed for direct use by the casual user, called "builtin
54 commands" for historical reasons.
55 The main drive behind these commands is user-friendliness.
57 During initialization,
59 will probe for a console and set the
61 variable, or set it to serial console
63 if the previous boot stage used that.
64 If multiple consoles are selected, they will be listed separated by spaces.
65 Then, devices are probed,
74 is processed if available.
75 These files are processed through the
77 command, which reads all of them into memory before processing them,
78 making disk changes possible.
82 has not been tried, and if
86 (not case sensitive), then an
89 If the system gets past this point,
93 will engage interactive mode.
94 Please note that historically even when
98 user will be able to interrupt autoboot process by pressing some key
99 on the console while kernel and modules are being loaded.
101 cases such behaviour may be undesirable, to prevent it set
107 will engage interactive mode only if
113 builtin commands take parameters from the command line.
115 the only way to call them from a script is by using
118 In the case of an error, an error message will be displayed and
119 the interpreter's state will be reset, emptying the stack and restoring
122 The builtin commands available are:
124 .Bl -tag -width Ds -compact
125 .It Ic autoboot Op Ar seconds Op Ar prompt
126 Proceeds to bootstrap the system after a number of seconds, if not
127 interrupted by the user.
128 Displays a countdown prompt
129 warning the user the system is about to be booted,
130 unless interrupted by a key press.
131 The kernel will be loaded first if necessary.
132 Defaults to 10 seconds.
135 Displays statistics about disk cache usage.
139 .It Ic boot Ar kernelname Op Cm ...
140 .It Ic boot Fl flag Cm ...
141 Immediately proceeds to bootstrap the system, loading the kernel
143 Any flags or arguments are passed to the kernel, but they
144 must precede the kernel name, if a kernel name is provided.
150 Displays text on the screen.
151 A new line will be printed unless
156 Displays memory usage statistics.
157 For debugging purposes only.
159 .It Ic help Op topic Op subtopic
160 Shows help messages read from
161 .Pa /boot/loader.help .
164 will list the topics available.
166 .It Ic include Ar file Op Ar
167 Process script files.
168 Each file, in turn, is completely read into memory,
169 and then each of its lines is passed to the command line interpreter.
170 If any error is returned by the interpreter, the include
171 command aborts immediately, without reading any other files, and
172 returns an error itself (see
179 Loads a kernel, kernel loadable module (kld), disk image,
180 or file of opaque contents tagged as being of the type
182 Kernel and modules can be either in a.out or ELF format.
183 Any arguments passed after the name of the file to be loaded
184 will be passed as arguments to that file.
187 type to make the kernel create a file-backed
190 This is useful for booting from a temporary rootfs.
191 Currently, argument passing does not work for the kernel.
199 encryption keyfile for the given provider name.
200 The key index can be specified via
202 or will default to zero.
208 Displays a listing of files in the directory
210 or the root directory if
215 is specified, file sizes will be shown too.
218 Lists all of the devices from which it may be possible to load modules,
219 as well as ZFS pools.
222 is specified, more details are printed, including ZFS pool information
223 in a format that resembles
228 Displays loaded modules.
231 is specified, more details are shown.
233 .It Ic lszfs Ar filesystem
234 A ZFS extended command that can be used to explore the ZFS filesystem
236 Lists the immediate children of the
238 The filesystem hierarchy is rooted at a filesystem with the same name
241 .It Ic more Ar file Op Ar
242 Display the files specified, with a pause at each
246 .It Ic pnpscan Op Fl v
247 Scans for Plug-and-Play devices.
248 This is not functional at present.
255 Reads a line of input from the terminal, storing it in
258 A timeout can be specified with
260 though it will be canceled at the first key pressed.
261 A prompt may also be displayed through the
266 Immediately reboots the system.
268 .It Ic set Ar variable
269 .It Ic set Ar variable Ns = Ns Ar value
270 Set loader's environment variables.
272 .It Ic show Op Va variable
273 Displays the specified variable's value, or all variables and their
279 Remove all modules from memory.
281 .It Ic unset Va variable
284 from the environment.
287 Lists available commands.
289 .Ss BUILTIN ENVIRONMENT VARIABLES
290 Environment variables can be set and unset through the
294 builtins, and can have their values interactively examined through the
298 Their values can also be accessed as described in
301 Notice that these environment variables are not inherited by any shell
302 after the system has been booted.
304 A few variables are set automatically by
306 Others can affect the behavior of either
308 or the kernel at boot.
309 Some options may require a value,
310 while others define behavior just by being set.
311 Both types of builtin variables are described below.
312 .Bl -tag -width bootfile
313 .It Va autoboot_delay
316 will wait before booting.
317 Configuration options are described in
320 Instructs the kernel to prompt the user for the name of the root device
321 when the kernel is booted.
323 Instructs the kernel to try to mount the root file system from CD-ROM.
325 Instructs the kernel to start in the DDB debugger, rather than
326 proceeding to initialize when booted.
328 Instructs the kernel to mount the statically compiled-in root file system.
330 Selects gdb-remote mode for the kernel debugger by default.
331 .It Va boot_multicons
332 Enables multiple console support in the kernel early on boot.
333 In a running system, console configuration can be manipulated
338 All kernel console output is suppressed when console is muted.
339 In a running system, the state of console muting can be manipulated by the
343 During the device probe, pause after each line is printed.
345 Force the use of a serial console even when an internal console
348 Prevents the kernel from initiating a multi-user startup; instead,
349 a single-user mode will be entered when the kernel has finished
352 Setting this variable causes extra debugging information to be printed
353 by the kernel during the boot phase.
355 List of semicolon-separated search path for bootable kernels.
358 .It Va comconsole_speed
359 Defines the speed of the serial console (i386 and amd64 only).
360 If the previous boot stage indicated that a serial console is in use
361 then this variable is initialized to the current speed of the console
363 Otherwise it is set to 9600 unless this was overridden using the
364 .Va BOOT_COMCONSOLE_SPEED
370 variable take effect immediately.
371 .It Va comconsole_port
372 Defines the base i/o port used to access console UART
373 (i386 and amd64 only).
374 If the variable is not set, its assumed value is 0x3F8, which
375 corresponds to PC port COM1, unless overridden by
376 .Va BOOT_COMCONSOLE_PORT
377 variable during the compilation of
381 variable automatically set
383 environment variable to provide a hint to kernel for location of the console.
384 Loader console is changed immediately after variable
387 .It Va comconsole_pcidev
388 Defines the location of a PCI device of the 'simple communication'
389 class to be used as the serial console UART (i386 and amd64 only).
390 The syntax of the variable is
391 .Li 'bus:device:function[:bar]' ,
392 where all members must be numeric, with possible
394 prefix to indicate a hexadecimal value.
397 member is optional and assumed to be 0x10 if omitted.
398 The bar must decode i/o space.
400 .Va comconsole_pcidev
401 automatically sets the variable
403 to the base of the selected bar, and hint
404 .Va hw.uart.console .
405 Loader console is changed immediately after variable
406 .Va comconsole_pcidev
409 Defines the current console or consoles.
410 Multiple consoles may be specified.
411 In that case, the first listed console will become the default console for
412 userland output (e.g.\& from
415 Selects the default device to loader the kernel from.
417 .Dl Ic loader_device:
422 .Dl Ic zfs:zroot/ROOT/default:
424 Sets the device for kernel dumps.
425 This can be used to ensure that a device is configured before the corresponding
429 has been processed, allowing kernel panics that happen during the early stages
430 of boot to be captured.
438 Sets the list of binaries which the kernel will try to run as the initial
440 The first matching binary is used.
442 .Dq Li /sbin/init:/sbin/oinit:/sbin/init.bak:\:/rescue/init .
452 if the Forth's current state is interpreting.
454 Define the number of lines on the screen, to be used by the pager.
456 Sets the list of directories which will be searched for modules
457 named in a load command or implicitly required by a dependency.
458 The default value for this variable is
459 .Dq Li /boot/kernel;/boot/modules .
461 Sets the number of IDE disks as a workaround for some problems in
462 finding the root disk at boot.
463 This has been deprecated in favor of
470 .Dq Li "${interpret}" .
473 is unset, the default prompt is
475 .It Va root_disk_unit
476 If the code which detects the disk unit number for the root disk is
477 confused, e.g.\& by a mix of SCSI and IDE disks, or IDE disks with
478 gaps in the sequence (e.g.\& no primary slave), the unit number can
479 be forced by setting this variable.
481 By default the value of
483 is used to set the root file system
484 when the kernel is booted.
485 This can be overridden by setting
490 Other variables are used to override kernel tunable parameters.
491 The following tunables are available:
493 .It Va efi.rt.disabled
494 Disable UEFI runtime services in the kernel, if applicable.
495 Runtime services are only available and used if the kernel is booted in a UEFI
498 Limit the amount of physical memory the system will use.
499 By default the size is in bytes, but the
500 .Cm k , K , m , M , g
504 are also accepted and indicate kilobytes, megabytes and gigabytes
506 An invalid suffix will result in the variable being ignored by the
508 .It Va hw.pci.host_start_mem , hw.acpi.host_start_mem
509 When not otherwise constrained, this limits the memory start
511 The default is 0x80000000 and should be set to at least size of the
512 memory and not conflict with other resources.
513 Typically, only systems without PCI bridges need to set this variable
514 since PCI bridges typically constrain the memory starting address
515 (and the variable is only used when bridges do not constrain this
517 .It Va hw.pci.enable_io_modes
518 Enable PCI resources which are left off by some BIOSes or are not
519 enabled correctly by the device driver.
520 Tunable value set to ON (1) by default, but this may cause problems
521 with some peripherals.
523 Set the size of a number of statically allocated system tables; see
525 for a description of how to select an appropriate value for this
527 When set, this tunable replaces the value declared in the kernel
528 compile-time configuration file.
529 .It Va kern.ipc.nmbclusters
530 Set the number of mbuf clusters to be allocated.
531 The value cannot be set below the default
532 determined when the kernel was compiled.
533 .It Va kern.ipc.nsfbufs
536 buffers to be allocated.
539 Not all architectures use such buffers; see
542 .It Va kern.maxswzone
543 Limits the amount of KVM to be used to hold swap
544 metadata, which directly governs the
545 maximum amount of swap the system can support,
546 at the rate of approximately 200 MB of swap space
547 per 1 MB of metadata.
548 This value is specified in bytes of KVA space.
549 If no value is provided, the system allocates
550 enough memory to handle an amount of swap
551 that corresponds to eight times the amount of
552 physical memory present in the system.
554 Note that swap metadata can be fragmented,
555 which means that the system can run out of
556 space before it reaches the theoretical limit.
557 Therefore, care should be taken to not configure
558 more swap than approximately half of the
561 Running out of space for swap metadata can leave
562 the system in an unrecoverable state.
563 Therefore, you should only change
564 this parameter if you need to greatly extend the
565 KVM reservation for other resources such as the
567 .Va kern.ipc.nmbclusters .
568 Modifies kernel option
569 .Dv VM_SWZONE_SIZE_MAX .
570 .It Va kern.maxbcache
571 Limits the amount of KVM reserved for use by the
572 buffer cache, specified in bytes.
573 The default maximum is 200MB on i386,
575 This parameter is used to
576 prevent the buffer cache from eating too much
577 KVM in large-memory machine configurations.
578 Only mess around with this parameter if you need to
579 greatly extend the KVM reservation for other resources
580 such as the swap zone or
581 .Va kern.ipc.nmbclusters .
583 the NBUF parameter will override this limit.
585 .Dv VM_BCACHE_SIZE_MAX .
586 .It Va kern.msgbufsize
587 Sets the size of the kernel message buffer.
588 The default limit of 96KB is usually sufficient unless
589 large amounts of trace data need to be collected
590 between opportunities to examine the buffer or
592 Overrides kernel option
594 .It Va machdep.disable_mtrrs
595 Disable the use of i686 MTRRs (x86 only).
596 .It Va net.inet.tcp.tcbhashsize
597 Overrides the compile-time set value of
599 or the preset default of 512.
600 Must be a power of 2.
601 .It Va twiddle_divisor
602 Throttles the output of the
604 I/O progress indicator displayed while loading the kernel and modules.
605 This is useful on slow serial consoles where the time spent waiting for
606 these characters to be written can add up to many seconds.
607 The default is 16; a value of 32 spins half as fast,
608 while a value of 8 spins twice as fast.
610 Sets the size of kernel memory (bytes).
611 This overrides the value determined when the kernel was compiled.
614 .It Va vm.kmem_size_min
615 .It Va vm.kmem_size_max
616 Sets the minimum and maximum (respectively) amount of kernel memory
617 that will be automatically allocated by the kernel.
618 These override the values determined when the kernel was compiled.
622 .Dv VM_KMEM_SIZE_MAX .
626 supports the following format for specifying ZFS filesystems which
629 refers to a device specification:
631 .Ar zfs:pool/filesystem:
635 is a ZFS filesystem name as described in
640 does not have an entry for the root filesystem and
641 .Va vfs.root.mountfrom
644 refers to a ZFS filesystem, then
646 will instruct kernel to use that filesystem as the root filesystem.
650 command line provides several ways of compromising system security,
651 including, but not limited to:
655 Booting from removable storage.
657 One can prevent unauthorized access
660 command line by booting unconditionally in
662 In order for this to be effective, one should also configure the firmware
663 (BIOS or UEFI) to prevent booting from unauthorized devices.
665 .Bl -tag -width /boot/loader_simp -compact
666 .It Pa /boot/loader_simp
669 .It Pa /boot/loader.rc
674 Boot in single user mode:
678 Load the kernel, a splash screen, and then autoboot in five seconds.
679 Notice that a kernel must be loaded before any other
681 command is attempted.
682 .Bd -literal -offset indent
685 load -t splash_image_data /boot/chuckrulez.bmp
689 Set the disk unit of the root device to 2, and then boot.
690 This would be needed in a system with two IDE disks,
691 with the second IDE disk hardwired to ada2 instead of ada1.
692 .Bd -literal -offset indent
694 boot /boot/kernel/kernel
697 Set the default device used for loading a kernel from a ZFS filesystem:
698 .Bd -literal -offset indent
699 set currdev=zfs:tank/ROOT/knowngood:
703 The following values are thrown by
705 .Bl -tag -width XXXXX -offset indent
707 Any type of error in the processing of a builtin.
718 Out of interpreting text.
720 Need more text to succeed -- will finish on next run.
743 .An Michael Smith Aq msmith@FreeBSD.org .
projects / FreeBSD / FreeBSD.git / blob