xref: /freebsd/stand/man/loader_simp.8 (revision 48b05b8fc2485ba5cc7ba7b52c62965feea101a8)
19873c807SWarner Losh.\" Copyright (c) 1999 Daniel C. Sobral
29873c807SWarner Losh.\" All rights reserved.
39873c807SWarner Losh.\"
49873c807SWarner Losh.\" Redistribution and use in source and binary forms, with or without
59873c807SWarner Losh.\" modification, are permitted provided that the following conditions
69873c807SWarner Losh.\" are met:
79873c807SWarner Losh.\" 1. Redistributions of source code must retain the above copyright
89873c807SWarner Losh.\"    notice, this list of conditions and the following disclaimer.
99873c807SWarner Losh.\" 2. Redistributions in binary form must reproduce the above copyright
109873c807SWarner Losh.\"    notice, this list of conditions and the following disclaimer in the
119873c807SWarner Losh.\"    documentation and/or other materials provided with the distribution.
129873c807SWarner Losh.\"
139873c807SWarner Losh.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
149873c807SWarner Losh.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
159873c807SWarner Losh.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
169873c807SWarner Losh.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
179873c807SWarner Losh.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
189873c807SWarner Losh.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
199873c807SWarner Losh.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
209873c807SWarner Losh.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
219873c807SWarner Losh.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
229873c807SWarner Losh.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
239873c807SWarner Losh.\" SUCH DAMAGE.
249873c807SWarner Losh.\"
25*48b05b8fSKyle Evans.Dd September 30, 2021
269e1dc7beSWarner Losh.Dt LOADER_SIMP 8
279873c807SWarner Losh.Os
289873c807SWarner Losh.Sh NAME
299e1dc7beSWarner Losh.Nm loader_simp
309873c807SWarner Losh.Nd kernel bootstrapping final stage
319873c807SWarner Losh.Sh DESCRIPTION
329873c807SWarner LoshThe program called
339873c807SWarner Losh.Nm
349873c807SWarner Loshis the final stage of
359873c807SWarner Losh.Fx Ns 's
369873c807SWarner Loshkernel bootstrapping process.
379873c807SWarner LoshOn IA32 (i386) architectures, it is a
389873c807SWarner Losh.Pa BTX
399873c807SWarner Loshclient.
409873c807SWarner LoshIt is linked statically to
4111f49259SWarner Losh.Xr libsa 3
429873c807SWarner Loshand usually located in the directory
439873c807SWarner Losh.Pa /boot .
449873c807SWarner Losh.Pp
459873c807SWarner LoshIt provides a scripting language that can be used to
469873c807SWarner Loshautomate tasks, do pre-configuration or assist in recovery
479873c807SWarner Loshprocedures.
489873c807SWarner LoshThis scripting language is roughly divided in
499873c807SWarner Loshtwo main components.
509873c807SWarner LoshThe smaller one is a set of commands
519873c807SWarner Loshdesigned for direct use by the casual user, called "builtin
529873c807SWarner Loshcommands" for historical reasons.
539873c807SWarner LoshThe main drive behind these commands is user-friendliness.
549873c807SWarner Losh.Pp
559873c807SWarner LoshDuring initialization,
569873c807SWarner Losh.Nm
579873c807SWarner Loshwill probe for a console and set the
589873c807SWarner Losh.Va console
599873c807SWarner Loshvariable, or set it to serial console
609873c807SWarner Losh.Pq Dq Li comconsole
619873c807SWarner Loshif the previous boot stage used that.
629873c807SWarner LoshIf multiple consoles are selected, they will be listed separated by spaces.
639873c807SWarner LoshThen, devices are probed,
649873c807SWarner Losh.Va currdev
659873c807SWarner Loshand
669873c807SWarner Losh.Va loaddev
679873c807SWarner Loshare set, and
689873c807SWarner Losh.Va LINES
699873c807SWarner Loshis set to 24.
709873c807SWarner LoshAfter that,
719873c807SWarner Losh.Pa /boot/loader.rc
729873c807SWarner Loshis processed if available.
739873c807SWarner LoshThese files are processed through the
749873c807SWarner Losh.Ic include
759873c807SWarner Loshcommand, which reads all of them into memory before processing them,
769873c807SWarner Loshmaking disk changes possible.
779873c807SWarner Losh.Pp
789873c807SWarner LoshAt this point, if an
799873c807SWarner Losh.Ic autoboot
809873c807SWarner Loshhas not been tried, and if
819873c807SWarner Losh.Va autoboot_delay
829873c807SWarner Loshis not set to
839873c807SWarner Losh.Dq Li NO
849873c807SWarner Losh(not case sensitive), then an
859873c807SWarner Losh.Ic autoboot
869873c807SWarner Loshwill be tried.
879873c807SWarner LoshIf the system gets past this point,
889873c807SWarner Losh.Va prompt
899873c807SWarner Loshwill be set and
909873c807SWarner Losh.Nm
919873c807SWarner Loshwill engage interactive mode.
929873c807SWarner LoshPlease note that historically even when
939873c807SWarner Losh.Va autoboot_delay
949873c807SWarner Loshis set to
959873c807SWarner Losh.Dq Li 0
969873c807SWarner Loshuser will be able to interrupt autoboot process by pressing some key
979873c807SWarner Loshon the console while kernel and modules are being loaded.
989873c807SWarner LoshIn some
999873c807SWarner Loshcases such behaviour may be undesirable, to prevent it set
1009873c807SWarner Losh.Va autoboot_delay
1019873c807SWarner Loshto
1029873c807SWarner Losh.Dq Li -1 ,
1039873c807SWarner Loshin this case
1049873c807SWarner Losh.Nm
1059873c807SWarner Loshwill engage interactive mode only if
1069873c807SWarner Losh.Ic autoboot
1079873c807SWarner Loshhas failed.
1089873c807SWarner Losh.Sh BUILTIN COMMANDS
1099873c807SWarner LoshIn
1109873c807SWarner Losh.Nm ,
1119873c807SWarner Loshbuiltin commands take parameters from the command line.
1129873c807SWarner LoshPresently,
1139873c807SWarner Loshthe only way to call them from a script is by using
1149873c807SWarner Losh.Pa evaluate
1159873c807SWarner Loshon a string.
1169e1dc7beSWarner LoshIn the case of an error, an error message will be displayed and
1179873c807SWarner Loshthe interpreter's state will be reset, emptying the stack and restoring
1189873c807SWarner Loshinterpreting mode.
1199873c807SWarner Losh.Pp
1209873c807SWarner LoshThe builtin commands available are:
1219873c807SWarner Losh.Pp
1229873c807SWarner Losh.Bl -tag -width Ds -compact
1239873c807SWarner Losh.It Ic autoboot Op Ar seconds Op Ar prompt
1249873c807SWarner LoshProceeds to bootstrap the system after a number of seconds, if not
1259873c807SWarner Loshinterrupted by the user.
1269873c807SWarner LoshDisplays a countdown prompt
1279873c807SWarner Loshwarning the user the system is about to be booted,
1289873c807SWarner Loshunless interrupted by a key press.
1299873c807SWarner LoshThe kernel will be loaded first if necessary.
1309873c807SWarner LoshDefaults to 10 seconds.
1319873c807SWarner Losh.Pp
1329873c807SWarner Losh.It Ic bcachestat
1339873c807SWarner LoshDisplays statistics about disk cache usage.
1349873c807SWarner LoshFor debugging only.
1359873c807SWarner Losh.Pp
1369873c807SWarner Losh.It Ic boot
1379873c807SWarner Losh.It Ic boot Ar kernelname Op Cm ...
1389873c807SWarner Losh.It Ic boot Fl flag Cm ...
1399873c807SWarner LoshImmediately proceeds to bootstrap the system, loading the kernel
1409873c807SWarner Loshif necessary.
1419873c807SWarner LoshAny flags or arguments are passed to the kernel, but they
1429873c807SWarner Loshmust precede the kernel name, if a kernel name is provided.
1439873c807SWarner Losh.Pp
1449873c807SWarner Losh.It Ic echo Xo
1459873c807SWarner Losh.Op Fl n
1469873c807SWarner Losh.Op Aq message
1479873c807SWarner Losh.Xc
1489873c807SWarner LoshDisplays text on the screen.
1499873c807SWarner LoshA new line will be printed unless
1509873c807SWarner Losh.Fl n
1519873c807SWarner Loshis specified.
1529873c807SWarner Losh.Pp
1539873c807SWarner Losh.It Ic heap
1549873c807SWarner LoshDisplays memory usage statistics.
1559873c807SWarner LoshFor debugging purposes only.
1569873c807SWarner Losh.Pp
1579873c807SWarner Losh.It Ic help Op topic Op subtopic
1589873c807SWarner LoshShows help messages read from
1599873c807SWarner Losh.Pa /boot/loader.help .
1609873c807SWarner LoshThe special topic
1619873c807SWarner Losh.Em index
1629873c807SWarner Loshwill list the topics available.
1639873c807SWarner Losh.Pp
1649873c807SWarner Losh.It Ic include Ar file Op Ar
1659873c807SWarner LoshProcess script files.
1669873c807SWarner LoshEach file, in turn, is completely read into memory,
1679873c807SWarner Loshand then each of its lines is passed to the command line interpreter.
1689873c807SWarner LoshIf any error is returned by the interpreter, the include
1699873c807SWarner Loshcommand aborts immediately, without reading any other files, and
1709873c807SWarner Loshreturns an error itself (see
1719873c807SWarner Losh.Sx ERRORS ) .
1729873c807SWarner Losh.Pp
1739873c807SWarner Losh.It Ic load Xo
1749873c807SWarner Losh.Op Fl t Ar type
1759873c807SWarner Losh.Ar file Cm ...
1769873c807SWarner Losh.Xc
1779873c807SWarner LoshLoads a kernel, kernel loadable module (kld), disk image,
1789873c807SWarner Loshor file of opaque contents tagged as being of the type
1799873c807SWarner Losh.Ar type .
1809873c807SWarner LoshKernel and modules can be either in a.out or ELF format.
1819873c807SWarner LoshAny arguments passed after the name of the file to be loaded
1829873c807SWarner Loshwill be passed as arguments to that file.
1839873c807SWarner LoshUse the
1849873c807SWarner Losh.Li md_image
1859873c807SWarner Loshtype to make the kernel create a file-backed
1869873c807SWarner Losh.Xr md 4
1879873c807SWarner Loshdisk.
1889873c807SWarner LoshThis is useful for booting from a temporary rootfs.
1899873c807SWarner LoshCurrently, argument passing does not work for the kernel.
1909873c807SWarner Losh.Pp
1919873c807SWarner Losh.It Ic load_geli Xo
1929873c807SWarner Losh.Op Fl n Ar keyno
1939873c807SWarner Losh.Ar prov Ar file
1949873c807SWarner Losh.Xc
1959873c807SWarner LoshLoads a
1969873c807SWarner Losh.Xr geli 8
1979873c807SWarner Loshencryption keyfile for the given provider name.
1989873c807SWarner LoshThe key index can be specified via
1999873c807SWarner Losh.Ar keyno
2009873c807SWarner Loshor will default to zero.
2019873c807SWarner Losh.Pp
2029873c807SWarner Losh.It Ic ls Xo
2039873c807SWarner Losh.Op Fl l
2049873c807SWarner Losh.Op Ar path
2059873c807SWarner Losh.Xc
2069873c807SWarner LoshDisplays a listing of files in the directory
2079873c807SWarner Losh.Ar path ,
2089873c807SWarner Loshor the root directory if
2099873c807SWarner Losh.Ar path
2109873c807SWarner Loshis not specified.
2119873c807SWarner LoshIf
2129873c807SWarner Losh.Fl l
2139873c807SWarner Loshis specified, file sizes will be shown too.
2149873c807SWarner Losh.Pp
2159873c807SWarner Losh.It Ic lsdev Op Fl v
2169873c807SWarner LoshLists all of the devices from which it may be possible to load modules,
2179873c807SWarner Loshas well as ZFS pools.
2189873c807SWarner LoshIf
2199873c807SWarner Losh.Fl v
2209873c807SWarner Loshis specified, more details are printed, including ZFS pool information
2219873c807SWarner Loshin a format that resembles
2229873c807SWarner Losh.Nm zpool Cm status
2239873c807SWarner Loshoutput.
2249873c807SWarner Losh.Pp
2259873c807SWarner Losh.It Ic lsmod Op Fl v
2269873c807SWarner LoshDisplays loaded modules.
2279873c807SWarner LoshIf
2289873c807SWarner Losh.Fl v
2299873c807SWarner Loshis specified, more details are shown.
2309873c807SWarner Losh.Pp
2319873c807SWarner Losh.It Ic lszfs Ar filesystem
2329873c807SWarner LoshA ZFS extended command that can be used to explore the ZFS filesystem
2339873c807SWarner Loshhierarchy in a pool.
2349873c807SWarner LoshLists the immediate children of the
2359873c807SWarner Losh.Ar filesystem .
2369873c807SWarner LoshThe filesystem hierarchy is rooted at a filesystem with the same name
2379873c807SWarner Loshas the pool.
2389873c807SWarner Losh.Pp
2399873c807SWarner Losh.It Ic more Ar file Op Ar
2409873c807SWarner LoshDisplay the files specified, with a pause at each
2419873c807SWarner Losh.Va LINES
2429873c807SWarner Loshdisplayed.
2439873c807SWarner Losh.Pp
2449873c807SWarner Losh.It Ic pnpscan Op Fl v
2459873c807SWarner LoshScans for Plug-and-Play devices.
2469873c807SWarner LoshThis is not functional at present.
2479873c807SWarner Losh.Pp
2489873c807SWarner Losh.It Ic read Xo
2499873c807SWarner Losh.Op Fl t Ar seconds
2509873c807SWarner Losh.Op Fl p Ar prompt
2519873c807SWarner Losh.Op Va variable
2529873c807SWarner Losh.Xc
2539873c807SWarner LoshReads a line of input from the terminal, storing it in
2549873c807SWarner Losh.Va variable
2559873c807SWarner Loshif specified.
2569873c807SWarner LoshA timeout can be specified with
2579873c807SWarner Losh.Fl t ,
2589873c807SWarner Loshthough it will be canceled at the first key pressed.
2599873c807SWarner LoshA prompt may also be displayed through the
2609873c807SWarner Losh.Fl p
2619873c807SWarner Loshflag.
2629873c807SWarner Losh.Pp
2639873c807SWarner Losh.It Ic reboot
2649873c807SWarner LoshImmediately reboots the system.
2659873c807SWarner Losh.Pp
2669873c807SWarner Losh.It Ic set Ar variable
2679873c807SWarner Losh.It Ic set Ar variable Ns = Ns Ar value
2689873c807SWarner LoshSet loader's environment variables.
2699873c807SWarner Losh.Pp
2709873c807SWarner Losh.It Ic show Op Va variable
2719873c807SWarner LoshDisplays the specified variable's value, or all variables and their
2729873c807SWarner Loshvalues if
2739873c807SWarner Losh.Va variable
2749873c807SWarner Loshis not specified.
2759873c807SWarner Losh.Pp
2769873c807SWarner Losh.It Ic unload
2779873c807SWarner LoshRemove all modules from memory.
2789873c807SWarner Losh.Pp
2799873c807SWarner Losh.It Ic unset Va variable
2809873c807SWarner LoshRemoves
2819873c807SWarner Losh.Va variable
2829873c807SWarner Loshfrom the environment.
2839873c807SWarner Losh.Pp
2849873c807SWarner Losh.It Ic \&?
2859873c807SWarner LoshLists available commands.
2869873c807SWarner Losh.El
2879873c807SWarner Losh.Ss BUILTIN ENVIRONMENT VARIABLES
2889873c807SWarner LoshEnvironment variables can be set and unset through the
2899873c807SWarner Losh.Ic set
2909873c807SWarner Loshand
2919873c807SWarner Losh.Ic unset
2929873c807SWarner Loshbuiltins, and can have their values interactively examined through the
2939873c807SWarner Loshuse of the
2949873c807SWarner Losh.Ic show
2959873c807SWarner Loshbuiltin.
2969873c807SWarner LoshTheir values can also be accessed as described in
2979873c807SWarner Losh.Sx BUILTIN PARSER .
2989873c807SWarner Losh.Pp
2999873c807SWarner LoshNotice that these environment variables are not inherited by any shell
3009873c807SWarner Loshafter the system has been booted.
3019873c807SWarner Losh.Pp
3029873c807SWarner LoshA few variables are set automatically by
3039873c807SWarner Losh.Nm .
3049873c807SWarner LoshOthers can affect the behavior of either
3059873c807SWarner Losh.Nm
3069873c807SWarner Loshor the kernel at boot.
3079873c807SWarner LoshSome options may require a value,
3089873c807SWarner Loshwhile others define behavior just by being set.
3099873c807SWarner LoshBoth types of builtin variables are described below.
3109873c807SWarner Losh.Bl -tag -width bootfile
3119873c807SWarner Losh.It Va autoboot_delay
3129873c807SWarner LoshNumber of seconds
3139873c807SWarner Losh.Ic autoboot
3149873c807SWarner Loshwill wait before booting.
3159873c807SWarner LoshConfiguration options are described in
3169873c807SWarner Losh.Xr loader.conf 5 .
3179873c807SWarner Losh.It Va boot_askname
3189873c807SWarner LoshInstructs the kernel to prompt the user for the name of the root device
3199873c807SWarner Loshwhen the kernel is booted.
3209873c807SWarner Losh.It Va boot_cdrom
3219873c807SWarner LoshInstructs the kernel to try to mount the root file system from CD-ROM.
3229873c807SWarner Losh.It Va boot_ddb
3239873c807SWarner LoshInstructs the kernel to start in the DDB debugger, rather than
3249873c807SWarner Loshproceeding to initialize when booted.
3259873c807SWarner Losh.It Va boot_dfltroot
3269873c807SWarner LoshInstructs the kernel to mount the statically compiled-in root file system.
3279873c807SWarner Losh.It Va boot_gdb
3289873c807SWarner LoshSelects gdb-remote mode for the kernel debugger by default.
3299873c807SWarner Losh.It Va boot_multicons
3309873c807SWarner LoshEnables multiple console support in the kernel early on boot.
3319873c807SWarner LoshIn a running system, console configuration can be manipulated
3329873c807SWarner Loshby the
3339873c807SWarner Losh.Xr conscontrol 8
3349873c807SWarner Loshutility.
3359873c807SWarner Losh.It Va boot_mute
3369873c807SWarner LoshAll kernel console output is suppressed when console is muted.
3379873c807SWarner LoshIn a running system, the state of console muting can be manipulated by the
3389873c807SWarner Losh.Xr conscontrol 8
3399873c807SWarner Loshutility.
3409873c807SWarner Losh.It Va boot_pause
3419873c807SWarner LoshDuring the device probe, pause after each line is printed.
342*48b05b8fSKyle Evans.It Va boot_safe
343*48b05b8fSKyle EvansForce userland to boot in
344*48b05b8fSKyle Evans.Dq safe mode ,
345*48b05b8fSKyle Evanswhich may disable or limit the functionality of some services that may not be
346*48b05b8fSKyle Evansdesired in safe mode.
347*48b05b8fSKyle EvansThis is typically set by selecting
348*48b05b8fSKyle Evans.Dq safe mode
349*48b05b8fSKyle Evansin the loader menu, which also sets some other hints for the kernel.
350*48b05b8fSKyle EvansApplications wishing to respect safe mode should
351*48b05b8fSKyle Evans.Sy only
352*48b05b8fSKyle Evanstest for the presence of
353*48b05b8fSKyle Evans.Va boot_safe
354*48b05b8fSKyle Evansin
355*48b05b8fSKyle Evans.Xr kenv 1 ,
356*48b05b8fSKyle Evansnot for any particular value.
3579873c807SWarner Losh.It Va boot_serial
3589873c807SWarner LoshForce the use of a serial console even when an internal console
3599873c807SWarner Loshis present.
3609873c807SWarner Losh.It Va boot_single
3619873c807SWarner LoshPrevents the kernel from initiating a multi-user startup; instead,
3629873c807SWarner Losha single-user mode will be entered when the kernel has finished
3639873c807SWarner Loshdevice probing.
3649873c807SWarner Losh.It Va boot_verbose
3659873c807SWarner LoshSetting this variable causes extra debugging information to be printed
3669873c807SWarner Loshby the kernel during the boot phase.
3679873c807SWarner Losh.It Va bootfile
3689873c807SWarner LoshList of semicolon-separated search path for bootable kernels.
3699873c807SWarner LoshThe default is
3709873c807SWarner Losh.Dq Li kernel .
3719873c807SWarner Losh.It Va comconsole_speed
3729873c807SWarner LoshDefines the speed of the serial console (i386 and amd64 only).
3739873c807SWarner LoshIf the previous boot stage indicated that a serial console is in use
3749873c807SWarner Loshthen this variable is initialized to the current speed of the console
3759873c807SWarner Loshserial port.
3764722ceb7SEd MasteOtherwise it is set to 115200 unless this was overridden using the
3779873c807SWarner Losh.Va BOOT_COMCONSOLE_SPEED
3789873c807SWarner Loshvariable when
3799873c807SWarner Losh.Nm
3809873c807SWarner Loshwas compiled.
3819873c807SWarner LoshChanges to the
3829873c807SWarner Losh.Va comconsole_speed
3839873c807SWarner Loshvariable take effect immediately.
3849873c807SWarner Losh.It Va comconsole_port
3859873c807SWarner LoshDefines the base i/o port used to access console UART
3869873c807SWarner Losh(i386 and amd64 only).
3879873c807SWarner LoshIf the variable is not set, its assumed value is 0x3F8, which
3889873c807SWarner Loshcorresponds to PC port COM1, unless overridden by
3899873c807SWarner Losh.Va BOOT_COMCONSOLE_PORT
3909873c807SWarner Loshvariable during the compilation of
3919873c807SWarner Losh.Nm .
3929873c807SWarner LoshSetting the
3939873c807SWarner Losh.Va comconsole_port
3949873c807SWarner Loshvariable automatically set
3959873c807SWarner Losh.Va hw.uart.console
3969873c807SWarner Loshenvironment variable to provide a hint to kernel for location of the console.
3979873c807SWarner LoshLoader console is changed immediately after variable
3989873c807SWarner Losh.Va comconsole_port
3999873c807SWarner Loshis set.
4009873c807SWarner Losh.It Va comconsole_pcidev
4019873c807SWarner LoshDefines the location of a PCI device of the 'simple communication'
4029873c807SWarner Loshclass to be used as the serial console UART (i386 and amd64 only).
4039873c807SWarner LoshThe syntax of the variable is
4049873c807SWarner Losh.Li 'bus:device:function[:bar]' ,
4059873c807SWarner Loshwhere all members must be numeric, with possible
4069873c807SWarner Losh.Li 0x
4079873c807SWarner Loshprefix to indicate a hexadecimal value.
4089873c807SWarner LoshThe
4099873c807SWarner Losh.Va bar
4109873c807SWarner Loshmember is optional and assumed to be 0x10 if omitted.
4119873c807SWarner LoshThe bar must decode i/o space.
4129873c807SWarner LoshSetting the variable
4139873c807SWarner Losh.Va comconsole_pcidev
4149873c807SWarner Loshautomatically sets the variable
4159873c807SWarner Losh.Va comconsole_port
4169873c807SWarner Loshto the base of the selected bar, and hint
4179873c807SWarner Losh.Va hw.uart.console .
4189873c807SWarner LoshLoader console is changed immediately after variable
4199873c807SWarner Losh.Va comconsole_pcidev
4209873c807SWarner Loshis set.
4219873c807SWarner Losh.It Va console
4229873c807SWarner LoshDefines the current console or consoles.
4239873c807SWarner LoshMultiple consoles may be specified.
4249873c807SWarner LoshIn that case, the first listed console will become the default console for
4259873c807SWarner Loshuserland output (e.g.\& from
4269873c807SWarner Losh.Xr init 8 ) .
4279873c807SWarner Losh.It Va currdev
4289873c807SWarner LoshSelects the default device to loader the kernel from.
4299873c807SWarner LoshThe syntax is:
4309873c807SWarner Losh.Dl Ic loader_device:
4319873c807SWarner Loshor
4329873c807SWarner Losh.Dl Ic zfs:dataset:
4339873c807SWarner LoshExamples:
4349873c807SWarner Losh.Dl Ic disk0p2:
4359873c807SWarner Losh.Dl Ic zfs:zroot/ROOT/default:
4369873c807SWarner Losh.It Va dumpdev
4379873c807SWarner LoshSets the device for kernel dumps.
4389873c807SWarner LoshThis can be used to ensure that a device is configured before the corresponding
4399873c807SWarner Losh.Va dumpdev
4409873c807SWarner Loshdirective from
4419873c807SWarner Losh.Xr rc.conf 5
4429873c807SWarner Loshhas been processed, allowing kernel panics that happen during the early stages
4439873c807SWarner Loshof boot to be captured.
4449873c807SWarner Losh.It Va init_chroot
4459873c807SWarner LoshSee
4469873c807SWarner Losh.Xr init 8 .
4479873c807SWarner Losh.It Va init_exec
4489873c807SWarner LoshSee
4499873c807SWarner Losh.Xr init 8 .
4509873c807SWarner Losh.It Va init_path
4519873c807SWarner LoshSets the list of binaries which the kernel will try to run as the initial
4529873c807SWarner Loshprocess.
4539873c807SWarner LoshThe first matching binary is used.
4549873c807SWarner LoshThe default list is
4559873c807SWarner Losh.Dq Li /sbin/init:/sbin/oinit:/sbin/init.bak:\:/rescue/init .
4569873c807SWarner Losh.It Va init_script
4579873c807SWarner LoshSee
4589873c807SWarner Losh.Xr init 8 .
4599873c807SWarner Losh.It Va init_shell
4609873c807SWarner LoshSee
4619873c807SWarner Losh.Xr init 8 .
4629873c807SWarner Losh.It Va interpret
4639873c807SWarner LoshHas the value
4649873c807SWarner Losh.Dq Li OK
4659873c807SWarner Loshif the Forth's current state is interpreting.
4669873c807SWarner Losh.It Va LINES
4679873c807SWarner LoshDefine the number of lines on the screen, to be used by the pager.
4689873c807SWarner Losh.It Va module_path
4699873c807SWarner LoshSets the list of directories which will be searched for modules
4709873c807SWarner Loshnamed in a load command or implicitly required by a dependency.
4719873c807SWarner LoshThe default value for this variable is
4729873c807SWarner Losh.Dq Li /boot/kernel;/boot/modules .
4739873c807SWarner Losh.It Va num_ide_disks
4749873c807SWarner LoshSets the number of IDE disks as a workaround for some problems in
4759873c807SWarner Loshfinding the root disk at boot.
4769873c807SWarner LoshThis has been deprecated in favor of
4779873c807SWarner Losh.Va root_disk_unit .
4789873c807SWarner Losh.It Va prompt
4799873c807SWarner LoshValue of
4809873c807SWarner Losh.Nm Ns 's
4819873c807SWarner Loshprompt.
4829873c807SWarner LoshDefaults to
4839873c807SWarner Losh.Dq Li "${interpret}" .
4849873c807SWarner LoshIf variable
4859873c807SWarner Losh.Va prompt
4869873c807SWarner Loshis unset, the default prompt is
4879873c807SWarner Losh.Ql > .
4889873c807SWarner Losh.It Va root_disk_unit
4899873c807SWarner LoshIf the code which detects the disk unit number for the root disk is
4909873c807SWarner Loshconfused, e.g.\& by a mix of SCSI and IDE disks, or IDE disks with
4919873c807SWarner Loshgaps in the sequence (e.g.\& no primary slave), the unit number can
4929873c807SWarner Loshbe forced by setting this variable.
4939873c807SWarner Losh.It Va rootdev
4949873c807SWarner LoshBy default the value of
4959873c807SWarner Losh.Va currdev
4969873c807SWarner Loshis used to set the root file system
4979873c807SWarner Loshwhen the kernel is booted.
4989873c807SWarner LoshThis can be overridden by setting
4999873c807SWarner Losh.Va rootdev
5009873c807SWarner Loshexplicitly.
5019873c807SWarner Losh.El
5029873c807SWarner Losh.Pp
5039873c807SWarner LoshOther variables are used to override kernel tunable parameters.
5049873c807SWarner LoshThe following tunables are available:
5059873c807SWarner Losh.Bl -tag -width Va
5069873c807SWarner Losh.It Va efi.rt.disabled
5079873c807SWarner LoshDisable UEFI runtime services in the kernel, if applicable.
5089873c807SWarner LoshRuntime services are only available and used if the kernel is booted in a UEFI
5099873c807SWarner Loshenvironment.
5109873c807SWarner Losh.It Va hw.physmem
5119873c807SWarner LoshLimit the amount of physical memory the system will use.
5129873c807SWarner LoshBy default the size is in bytes, but the
5139873c807SWarner Losh.Cm k , K , m , M , g
5149873c807SWarner Loshand
5159873c807SWarner Losh.Cm G
5169873c807SWarner Loshsuffixes
5179873c807SWarner Loshare also accepted and indicate kilobytes, megabytes and gigabytes
5189873c807SWarner Loshrespectively.
5199873c807SWarner LoshAn invalid suffix will result in the variable being ignored by the
5209873c807SWarner Loshkernel.
5219873c807SWarner Losh.It Va hw.pci.host_start_mem , hw.acpi.host_start_mem
5229873c807SWarner LoshWhen not otherwise constrained, this limits the memory start
5239873c807SWarner Loshaddress.
5249873c807SWarner LoshThe default is 0x80000000 and should be set to at least size of the
5259873c807SWarner Loshmemory and not conflict with other resources.
5269873c807SWarner LoshTypically, only systems without PCI bridges need to set this variable
5279873c807SWarner Loshsince PCI bridges typically constrain the memory starting address
5289873c807SWarner Losh(and the variable is only used when bridges do not constrain this
5299873c807SWarner Loshaddress).
5309873c807SWarner Losh.It Va hw.pci.enable_io_modes
5319873c807SWarner LoshEnable PCI resources which are left off by some BIOSes or are not
5329873c807SWarner Loshenabled correctly by the device driver.
5339873c807SWarner LoshTunable value set to ON (1) by default, but this may cause problems
5349873c807SWarner Loshwith some peripherals.
5359873c807SWarner Losh.It Va kern.maxusers
5369873c807SWarner LoshSet the size of a number of statically allocated system tables; see
5379873c807SWarner Losh.Xr tuning 7
5389873c807SWarner Loshfor a description of how to select an appropriate value for this
5399873c807SWarner Loshtunable.
5409873c807SWarner LoshWhen set, this tunable replaces the value declared in the kernel
5419873c807SWarner Loshcompile-time configuration file.
5429873c807SWarner Losh.It Va kern.ipc.nmbclusters
5439873c807SWarner LoshSet the number of mbuf clusters to be allocated.
5449873c807SWarner LoshThe value cannot be set below the default
5459873c807SWarner Loshdetermined when the kernel was compiled.
5469873c807SWarner Losh.It Va kern.ipc.nsfbufs
5479873c807SWarner LoshSet the number of
5489873c807SWarner Losh.Xr sendfile 2
5499873c807SWarner Loshbuffers to be allocated.
5509873c807SWarner LoshOverrides
5519873c807SWarner Losh.Dv NSFBUFS .
5529873c807SWarner LoshNot all architectures use such buffers; see
5539873c807SWarner Losh.Xr sendfile 2
5549873c807SWarner Loshfor details.
5559873c807SWarner Losh.It Va kern.maxswzone
5569873c807SWarner LoshLimits the amount of KVM to be used to hold swap
5579873c807SWarner Loshmetadata, which directly governs the
5589873c807SWarner Loshmaximum amount of swap the system can support,
5599873c807SWarner Loshat the rate of approximately 200 MB of swap space
5609873c807SWarner Loshper 1 MB of metadata.
5619873c807SWarner LoshThis value is specified in bytes of KVA space.
5629873c807SWarner LoshIf no value is provided, the system allocates
5639873c807SWarner Loshenough memory to handle an amount of swap
5649873c807SWarner Loshthat corresponds to eight times the amount of
5659873c807SWarner Loshphysical memory present in the system.
5669873c807SWarner Losh.Pp
5679873c807SWarner LoshNote that swap metadata can be fragmented,
5689873c807SWarner Loshwhich means that the system can run out of
5699873c807SWarner Loshspace before it reaches the theoretical limit.
5709873c807SWarner LoshTherefore, care should be taken to not configure
5719873c807SWarner Loshmore swap than approximately half of the
5729873c807SWarner Loshtheoretical maximum.
5739873c807SWarner Losh.Pp
5749873c807SWarner LoshRunning out of space for swap metadata can leave
5759873c807SWarner Loshthe system in an unrecoverable state.
5769873c807SWarner LoshTherefore, you should only change
5779873c807SWarner Loshthis parameter if you need to greatly extend the
5789873c807SWarner LoshKVM reservation for other resources such as the
5799873c807SWarner Loshbuffer cache or
5809873c807SWarner Losh.Va kern.ipc.nmbclusters .
5819873c807SWarner LoshModifies kernel option
5829873c807SWarner Losh.Dv VM_SWZONE_SIZE_MAX .
5839873c807SWarner Losh.It Va kern.maxbcache
5849873c807SWarner LoshLimits the amount of KVM reserved for use by the
5859873c807SWarner Loshbuffer cache, specified in bytes.
5869873c807SWarner LoshThe default maximum is 200MB on i386,
5879873c807SWarner Loshand 400MB on amd64.
5889873c807SWarner LoshThis parameter is used to
5899873c807SWarner Loshprevent the buffer cache from eating too much
5909873c807SWarner LoshKVM in large-memory machine configurations.
5919873c807SWarner LoshOnly mess around with this parameter if you need to
5929873c807SWarner Loshgreatly extend the KVM reservation for other resources
5939873c807SWarner Loshsuch as the swap zone or
5949873c807SWarner Losh.Va kern.ipc.nmbclusters .
5959873c807SWarner LoshNote that
5969873c807SWarner Loshthe NBUF parameter will override this limit.
5979873c807SWarner LoshModifies
5989873c807SWarner Losh.Dv VM_BCACHE_SIZE_MAX .
5999873c807SWarner Losh.It Va kern.msgbufsize
6009873c807SWarner LoshSets the size of the kernel message buffer.
6019873c807SWarner LoshThe default limit of 96KB is usually sufficient unless
6029873c807SWarner Loshlarge amounts of trace data need to be collected
6039873c807SWarner Loshbetween opportunities to examine the buffer or
6049873c807SWarner Loshdump it to a file.
6059873c807SWarner LoshOverrides kernel option
6069873c807SWarner Losh.Dv MSGBUF_SIZE .
6079873c807SWarner Losh.It Va machdep.disable_mtrrs
6089873c807SWarner LoshDisable the use of i686 MTRRs (x86 only).
6099873c807SWarner Losh.It Va net.inet.tcp.tcbhashsize
6109873c807SWarner LoshOverrides the compile-time set value of
6119873c807SWarner Losh.Dv TCBHASHSIZE
6129873c807SWarner Loshor the preset default of 512.
6139873c807SWarner LoshMust be a power of 2.
6149873c807SWarner Losh.It Va twiddle_divisor
6159873c807SWarner LoshThrottles the output of the
6169873c807SWarner Losh.Sq twiddle
6179873c807SWarner LoshI/O progress indicator displayed while loading the kernel and modules.
6189873c807SWarner LoshThis is useful on slow serial consoles where the time spent waiting for
6199873c807SWarner Loshthese characters to be written can add up to many seconds.
62074578402SColin PercivalThe default is 16; a value of 32 spins half as fast,
62174578402SColin Percivalwhile a value of 8 spins twice as fast.
6229873c807SWarner Losh.It Va vm.kmem_size
6239873c807SWarner LoshSets the size of kernel memory (bytes).
6249873c807SWarner LoshThis overrides the value determined when the kernel was compiled.
6259873c807SWarner LoshModifies
6269873c807SWarner Losh.Dv VM_KMEM_SIZE .
6279873c807SWarner Losh.It Va vm.kmem_size_min
6289873c807SWarner Losh.It Va vm.kmem_size_max
6299873c807SWarner LoshSets the minimum and maximum (respectively) amount of kernel memory
6309873c807SWarner Loshthat will be automatically allocated by the kernel.
6319873c807SWarner LoshThese override the values determined when the kernel was compiled.
6329873c807SWarner LoshModifies
6339873c807SWarner Losh.Dv VM_KMEM_SIZE_MIN
6349873c807SWarner Loshand
6359873c807SWarner Losh.Dv VM_KMEM_SIZE_MAX .
6369873c807SWarner Losh.El
6379873c807SWarner Losh.Ss ZFS FEATURES
6389873c807SWarner Losh.Nm
6399873c807SWarner Loshsupports the following format for specifying ZFS filesystems which
6409873c807SWarner Loshcan be used wherever
6419873c807SWarner Losh.Xr loader 8
6429873c807SWarner Loshrefers to a device specification:
6439873c807SWarner Losh.Pp
6449873c807SWarner Losh.Ar zfs:pool/filesystem:
6459873c807SWarner Losh.Pp
6469873c807SWarner Loshwhere
6479873c807SWarner Losh.Pa pool/filesystem
6489873c807SWarner Loshis a ZFS filesystem name as described in
6499873c807SWarner Losh.Xr zfs 8 .
6509873c807SWarner Losh.Pp
6519873c807SWarner LoshIf
6529873c807SWarner Losh.Pa /etc/fstab
6539873c807SWarner Loshdoes not have an entry for the root filesystem and
6549873c807SWarner Losh.Va vfs.root.mountfrom
6559873c807SWarner Loshis not set, but
6569873c807SWarner Losh.Va currdev
6579873c807SWarner Loshrefers to a ZFS filesystem, then
6589873c807SWarner Losh.Nm
6599873c807SWarner Loshwill instruct kernel to use that filesystem as the root filesystem.
6609873c807SWarner Losh.Sh SECURITY
6619873c807SWarner LoshAccess to the
6629873c807SWarner Losh.Nm
6639873c807SWarner Loshcommand line provides several ways of compromising system security,
6649873c807SWarner Loshincluding, but not limited to:
6659873c807SWarner Losh.Pp
6669873c807SWarner Losh.Bl -bullet
6679873c807SWarner Losh.It
6689873c807SWarner LoshBooting from removable storage.
6699873c807SWarner Losh.Pp
6709873c807SWarner LoshOne can prevent unauthorized access
6719873c807SWarner Loshto the
6729873c807SWarner Losh.Nm
6739873c807SWarner Loshcommand line by booting unconditionally in
6749873c807SWarner Losh.Pa loader.rc .
6759873c807SWarner LoshIn order for this to be effective, one should also configure the firmware
6769873c807SWarner Losh(BIOS or UEFI) to prevent booting from unauthorized devices.
677643fc698SGraham Percival.El
6789873c807SWarner Losh.Sh FILES
6799873c807SWarner Losh.Bl -tag -width /boot/loader_simp -compact
6809873c807SWarner Losh.It Pa /boot/loader_simp
6819873c807SWarner Losh.Nm
6829873c807SWarner Loshitself.
6839873c807SWarner Losh.It Pa /boot/loader.rc
6849873c807SWarner LoshThe script run by
6859873c807SWarner Losh.Nm
6869873c807SWarner Loshon startup.
687643fc698SGraham Percival.El
6889873c807SWarner Losh.Sh EXAMPLES
6899873c807SWarner LoshBoot in single user mode:
6909873c807SWarner Losh.Pp
6919873c807SWarner Losh.Dl boot -s
6929873c807SWarner Losh.Pp
6939873c807SWarner LoshLoad the kernel, a splash screen, and then autoboot in five seconds.
6949873c807SWarner LoshNotice that a kernel must be loaded before any other
6959873c807SWarner Losh.Ic load
6969873c807SWarner Loshcommand is attempted.
6979873c807SWarner Losh.Bd -literal -offset indent
6989873c807SWarner Loshload kernel
6999873c807SWarner Loshload splash_bmp
7009873c807SWarner Loshload -t splash_image_data /boot/chuckrulez.bmp
7019873c807SWarner Loshautoboot 5
7029873c807SWarner Losh.Ed
7039873c807SWarner Losh.Pp
7049873c807SWarner LoshSet the disk unit of the root device to 2, and then boot.
7059873c807SWarner LoshThis would be needed in a system with two IDE disks,
7069873c807SWarner Loshwith the second IDE disk hardwired to ada2 instead of ada1.
7079873c807SWarner Losh.Bd -literal -offset indent
7089873c807SWarner Loshset root_disk_unit=2
7099873c807SWarner Loshboot /boot/kernel/kernel
7109873c807SWarner Losh.Ed
7119873c807SWarner Losh.Pp
7129873c807SWarner LoshSet the default device used for loading a kernel from a ZFS filesystem:
7139873c807SWarner Losh.Bd -literal -offset indent
7149873c807SWarner Loshset currdev=zfs:tank/ROOT/knowngood:
7159873c807SWarner Losh.Ed
7169873c807SWarner Losh.Pp
7179873c807SWarner Losh.Sh ERRORS
7189873c807SWarner LoshThe following values are thrown by
7199873c807SWarner Losh.Nm :
7209873c807SWarner Losh.Bl -tag -width XXXXX -offset indent
7219873c807SWarner Losh.It 100
7229873c807SWarner LoshAny type of error in the processing of a builtin.
7239873c807SWarner Losh.It -1
7249873c807SWarner Losh.Ic Abort
7259873c807SWarner Loshexecuted.
7269873c807SWarner Losh.It -2
7279873c807SWarner Losh.Ic Abort"
7289873c807SWarner Loshexecuted.
7299873c807SWarner Losh.It -56
7309873c807SWarner Losh.Ic Quit
7319873c807SWarner Loshexecuted.
7329873c807SWarner Losh.It -256
7339873c807SWarner LoshOut of interpreting text.
7349873c807SWarner Losh.It -257
7359873c807SWarner LoshNeed more text to succeed -- will finish on next run.
7369873c807SWarner Losh.It -258
7379873c807SWarner Losh.Ic Bye
7389873c807SWarner Loshexecuted.
7399873c807SWarner Losh.It -259
7409873c807SWarner LoshUnspecified error.
7419873c807SWarner Losh.El
7429873c807SWarner Losh.Sh SEE ALSO
74311f49259SWarner Losh.Xr libsa 3 ,
7449873c807SWarner Losh.Xr loader.conf 5 ,
7459873c807SWarner Losh.Xr tuning 7 ,
7469873c807SWarner Losh.Xr boot 8 ,
7479873c807SWarner Losh.Xr btxld 8
7489873c807SWarner Losh.Sh HISTORY
7499873c807SWarner LoshThe
7509873c807SWarner Losh.Nm
7519873c807SWarner Loshfirst appeared in
7529873c807SWarner Losh.Fx 3.1 .
7539873c807SWarner Losh.Sh AUTHORS
7549873c807SWarner Losh.An -nosplit
7559873c807SWarner LoshThe
7569873c807SWarner Losh.Nm
7579873c807SWarner Loshwas written by
7589873c807SWarner Losh.An Michael Smith Aq msmith@FreeBSD.org .
759