1.\" Copyright (c) 1999 Daniel C. Sobral 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 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. 12.\" 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 23.\" SUCH DAMAGE. 24.\" 25.Dd September 29, 2021 26.Dt LOADER_SIMP 8 27.Os 28.Sh NAME 29.Nm loader_simp 30.Nd kernel bootstrapping final stage 31.Sh DESCRIPTION 32The program called 33.Nm 34is the final stage of 35.Fx Ns 's 36kernel bootstrapping process. 37On IA32 (i386) architectures, it is a 38.Pa BTX 39client. 40It is linked statically to 41.Xr libsa 3 42and usually located in the directory 43.Pa /boot . 44.Pp 45It provides a scripting language that can be used to 46automate tasks, do pre-configuration or assist in recovery 47procedures. 48This scripting language is roughly divided in 49two main components. 50The smaller one is a set of commands 51designed for direct use by the casual user, called "builtin 52commands" for historical reasons. 53The main drive behind these commands is user-friendliness. 54.Pp 55During initialization, 56.Nm 57will probe for a console and set the 58.Va console 59variable, or set it to serial console 60.Pq Dq Li comconsole 61if the previous boot stage used that. 62If multiple consoles are selected, they will be listed separated by spaces. 63Then, devices are probed, 64.Va currdev 65and 66.Va loaddev 67are set, and 68.Va LINES 69is set to 24. 70After that, 71.Pa /boot/loader.rc 72is processed if available. 73These files are processed through the 74.Ic include 75command, which reads all of them into memory before processing them, 76making disk changes possible. 77.Pp 78At this point, if an 79.Ic autoboot 80has not been tried, and if 81.Va autoboot_delay 82is not set to 83.Dq Li NO 84(not case sensitive), then an 85.Ic autoboot 86will be tried. 87If the system gets past this point, 88.Va prompt 89will be set and 90.Nm 91will engage interactive mode. 92Please note that historically even when 93.Va autoboot_delay 94is set to 95.Dq Li 0 96user will be able to interrupt autoboot process by pressing some key 97on the console while kernel and modules are being loaded. 98In some 99cases such behaviour may be undesirable, to prevent it set 100.Va autoboot_delay 101to 102.Dq Li -1 , 103in this case 104.Nm 105will engage interactive mode only if 106.Ic autoboot 107has failed. 108.Sh BUILTIN COMMANDS 109In 110.Nm , 111builtin commands take parameters from the command line. 112Presently, 113the only way to call them from a script is by using 114.Pa evaluate 115on a string. 116In the case of an error, an error message will be displayed and 117the interpreter's state will be reset, emptying the stack and restoring 118interpreting mode. 119.Pp 120The builtin commands available are: 121.Pp 122.Bl -tag -width Ds -compact 123.It Ic autoboot Op Ar seconds Op Ar prompt 124Proceeds to bootstrap the system after a number of seconds, if not 125interrupted by the user. 126Displays a countdown prompt 127warning the user the system is about to be booted, 128unless interrupted by a key press. 129The kernel will be loaded first if necessary. 130Defaults to 10 seconds. 131.Pp 132.It Ic bcachestat 133Displays statistics about disk cache usage. 134For debugging only. 135.Pp 136.It Ic boot 137.It Ic boot Ar kernelname Op Cm ... 138.It Ic boot Fl flag Cm ... 139Immediately proceeds to bootstrap the system, loading the kernel 140if necessary. 141Any flags or arguments are passed to the kernel, but they 142must precede the kernel name, if a kernel name is provided. 143.Pp 144.It Ic echo Xo 145.Op Fl n 146.Op Aq message 147.Xc 148Displays text on the screen. 149A new line will be printed unless 150.Fl n 151is specified. 152.Pp 153.It Ic heap 154Displays memory usage statistics. 155For debugging purposes only. 156.Pp 157.It Ic help Op topic Op subtopic 158Shows help messages read from 159.Pa /boot/loader.help . 160The special topic 161.Em index 162will list the topics available. 163.Pp 164.It Ic include Ar file Op Ar 165Process script files. 166Each file, in turn, is completely read into memory, 167and then each of its lines is passed to the command line interpreter. 168If any error is returned by the interpreter, the include 169command aborts immediately, without reading any other files, and 170returns an error itself (see 171.Sx ERRORS ) . 172.Pp 173.It Ic load Xo 174.Op Fl t Ar type 175.Ar file Cm ... 176.Xc 177Loads a kernel, kernel loadable module (kld), disk image, 178or file of opaque contents tagged as being of the type 179.Ar type . 180Kernel and modules can be either in a.out or ELF format. 181Any arguments passed after the name of the file to be loaded 182will be passed as arguments to that file. 183Use the 184.Li md_image 185type to make the kernel create a file-backed 186.Xr md 4 187disk. 188This is useful for booting from a temporary rootfs. 189Currently, argument passing does not work for the kernel. 190.Pp 191.It Ic load_geli Xo 192.Op Fl n Ar keyno 193.Ar prov Ar file 194.Xc 195Loads a 196.Xr geli 8 197encryption keyfile for the given provider name. 198The key index can be specified via 199.Ar keyno 200or will default to zero. 201.Pp 202.It Ic ls Xo 203.Op Fl l 204.Op Ar path 205.Xc 206Displays a listing of files in the directory 207.Ar path , 208or the root directory if 209.Ar path 210is not specified. 211If 212.Fl l 213is specified, file sizes will be shown too. 214.Pp 215.It Ic lsdev Op Fl v 216Lists all of the devices from which it may be possible to load modules, 217as well as ZFS pools. 218If 219.Fl v 220is specified, more details are printed, including ZFS pool information 221in a format that resembles 222.Nm zpool Cm status 223output. 224.Pp 225.It Ic lsmod Op Fl v 226Displays loaded modules. 227If 228.Fl v 229is specified, more details are shown. 230.Pp 231.It Ic lszfs Ar filesystem 232A ZFS extended command that can be used to explore the ZFS filesystem 233hierarchy in a pool. 234Lists the immediate children of the 235.Ar filesystem . 236The filesystem hierarchy is rooted at a filesystem with the same name 237as the pool. 238.Pp 239.It Ic more Ar file Op Ar 240Display the files specified, with a pause at each 241.Va LINES 242displayed. 243.Pp 244.It Ic pnpscan Op Fl v 245Scans for Plug-and-Play devices. 246This is not functional at present. 247.Pp 248.It Ic read Xo 249.Op Fl t Ar seconds 250.Op Fl p Ar prompt 251.Op Va variable 252.Xc 253Reads a line of input from the terminal, storing it in 254.Va variable 255if specified. 256A timeout can be specified with 257.Fl t , 258though it will be canceled at the first key pressed. 259A prompt may also be displayed through the 260.Fl p 261flag. 262.Pp 263.It Ic reboot 264Immediately reboots the system. 265.Pp 266.It Ic set Ar variable 267.It Ic set Ar variable Ns = Ns Ar value 268Set loader's environment variables. 269.Pp 270.It Ic show Op Va variable 271Displays the specified variable's value, or all variables and their 272values if 273.Va variable 274is not specified. 275.Pp 276.It Ic unload 277Remove all modules from memory. 278.Pp 279.It Ic unset Va variable 280Removes 281.Va variable 282from the environment. 283.Pp 284.It Ic \&? 285Lists available commands. 286.El 287.Ss BUILTIN ENVIRONMENT VARIABLES 288Environment variables can be set and unset through the 289.Ic set 290and 291.Ic unset 292builtins, and can have their values interactively examined through the 293use of the 294.Ic show 295builtin. 296Their values can also be accessed as described in 297.Sx BUILTIN PARSER . 298.Pp 299Notice that these environment variables are not inherited by any shell 300after the system has been booted. 301.Pp 302A few variables are set automatically by 303.Nm . 304Others can affect the behavior of either 305.Nm 306or the kernel at boot. 307Some options may require a value, 308while others define behavior just by being set. 309Both types of builtin variables are described below. 310.Bl -tag -width bootfile 311.It Va autoboot_delay 312Number of seconds 313.Ic autoboot 314will wait before booting. 315Configuration options are described in 316.Xr loader.conf 5 . 317.It Va boot_askname 318Instructs the kernel to prompt the user for the name of the root device 319when the kernel is booted. 320.It Va boot_cdrom 321Instructs the kernel to try to mount the root file system from CD-ROM. 322.It Va boot_ddb 323Instructs the kernel to start in the DDB debugger, rather than 324proceeding to initialize when booted. 325.It Va boot_dfltroot 326Instructs the kernel to mount the statically compiled-in root file system. 327.It Va boot_gdb 328Selects gdb-remote mode for the kernel debugger by default. 329.It Va boot_multicons 330Enables multiple console support in the kernel early on boot. 331In a running system, console configuration can be manipulated 332by the 333.Xr conscontrol 8 334utility. 335.It Va boot_mute 336All kernel console output is suppressed when console is muted. 337In a running system, the state of console muting can be manipulated by the 338.Xr conscontrol 8 339utility. 340.It Va boot_pause 341During the device probe, pause after each line is printed. 342.It Va boot_serial 343Force the use of a serial console even when an internal console 344is present. 345.It Va boot_single 346Prevents the kernel from initiating a multi-user startup; instead, 347a single-user mode will be entered when the kernel has finished 348device probing. 349.It Va boot_verbose 350Setting this variable causes extra debugging information to be printed 351by the kernel during the boot phase. 352.It Va bootfile 353List of semicolon-separated search path for bootable kernels. 354The default is 355.Dq Li kernel . 356.It Va comconsole_speed 357Defines the speed of the serial console (i386 and amd64 only). 358If the previous boot stage indicated that a serial console is in use 359then this variable is initialized to the current speed of the console 360serial port. 361Otherwise it is set to 115200 unless this was overridden using the 362.Va BOOT_COMCONSOLE_SPEED 363variable when 364.Nm 365was compiled. 366Changes to the 367.Va comconsole_speed 368variable take effect immediately. 369.It Va comconsole_port 370Defines the base i/o port used to access console UART 371(i386 and amd64 only). 372If the variable is not set, its assumed value is 0x3F8, which 373corresponds to PC port COM1, unless overridden by 374.Va BOOT_COMCONSOLE_PORT 375variable during the compilation of 376.Nm . 377Setting the 378.Va comconsole_port 379variable automatically set 380.Va hw.uart.console 381environment variable to provide a hint to kernel for location of the console. 382Loader console is changed immediately after variable 383.Va comconsole_port 384is set. 385.It Va comconsole_pcidev 386Defines the location of a PCI device of the 'simple communication' 387class to be used as the serial console UART (i386 and amd64 only). 388The syntax of the variable is 389.Li 'bus:device:function[:bar]' , 390where all members must be numeric, with possible 391.Li 0x 392prefix to indicate a hexadecimal value. 393The 394.Va bar 395member is optional and assumed to be 0x10 if omitted. 396The bar must decode i/o space. 397Setting the variable 398.Va comconsole_pcidev 399automatically sets the variable 400.Va comconsole_port 401to the base of the selected bar, and hint 402.Va hw.uart.console . 403Loader console is changed immediately after variable 404.Va comconsole_pcidev 405is set. 406.It Va console 407Defines the current console or consoles. 408Multiple consoles may be specified. 409In that case, the first listed console will become the default console for 410userland output (e.g.\& from 411.Xr init 8 ) . 412.It Va currdev 413Selects the default device to loader the kernel from. 414The syntax is: 415.Dl Ic loader_device: 416or 417.Dl Ic zfs:dataset: 418Examples: 419.Dl Ic disk0p2: 420.Dl Ic zfs:zroot/ROOT/default: 421.It Va dumpdev 422Sets the device for kernel dumps. 423This can be used to ensure that a device is configured before the corresponding 424.Va dumpdev 425directive from 426.Xr rc.conf 5 427has been processed, allowing kernel panics that happen during the early stages 428of boot to be captured. 429.It Va init_chroot 430See 431.Xr init 8 . 432.It Va init_exec 433See 434.Xr init 8 . 435.It Va init_path 436Sets the list of binaries which the kernel will try to run as the initial 437process. 438The first matching binary is used. 439The default list is 440.Dq Li /sbin/init:/sbin/oinit:/sbin/init.bak:\:/rescue/init . 441.It Va init_script 442See 443.Xr init 8 . 444.It Va init_shell 445See 446.Xr init 8 . 447.It Va interpret 448Has the value 449.Dq Li OK 450if the Forth's current state is interpreting. 451.It Va LINES 452Define the number of lines on the screen, to be used by the pager. 453.It Va module_path 454Sets the list of directories which will be searched for modules 455named in a load command or implicitly required by a dependency. 456The default value for this variable is 457.Dq Li /boot/kernel;/boot/modules . 458.It Va num_ide_disks 459Sets the number of IDE disks as a workaround for some problems in 460finding the root disk at boot. 461This has been deprecated in favor of 462.Va root_disk_unit . 463.It Va prompt 464Value of 465.Nm Ns 's 466prompt. 467Defaults to 468.Dq Li "${interpret}" . 469If variable 470.Va prompt 471is unset, the default prompt is 472.Ql > . 473.It Va root_disk_unit 474If the code which detects the disk unit number for the root disk is 475confused, e.g.\& by a mix of SCSI and IDE disks, or IDE disks with 476gaps in the sequence (e.g.\& no primary slave), the unit number can 477be forced by setting this variable. 478.It Va rootdev 479By default the value of 480.Va currdev 481is used to set the root file system 482when the kernel is booted. 483This can be overridden by setting 484.Va rootdev 485explicitly. 486.El 487.Pp 488Other variables are used to override kernel tunable parameters. 489The following tunables are available: 490.Bl -tag -width Va 491.It Va efi.rt.disabled 492Disable UEFI runtime services in the kernel, if applicable. 493Runtime services are only available and used if the kernel is booted in a UEFI 494environment. 495.It Va hw.physmem 496Limit the amount of physical memory the system will use. 497By default the size is in bytes, but the 498.Cm k , K , m , M , g 499and 500.Cm G 501suffixes 502are also accepted and indicate kilobytes, megabytes and gigabytes 503respectively. 504An invalid suffix will result in the variable being ignored by the 505kernel. 506.It Va hw.pci.host_start_mem , hw.acpi.host_start_mem 507When not otherwise constrained, this limits the memory start 508address. 509The default is 0x80000000 and should be set to at least size of the 510memory and not conflict with other resources. 511Typically, only systems without PCI bridges need to set this variable 512since PCI bridges typically constrain the memory starting address 513(and the variable is only used when bridges do not constrain this 514address). 515.It Va hw.pci.enable_io_modes 516Enable PCI resources which are left off by some BIOSes or are not 517enabled correctly by the device driver. 518Tunable value set to ON (1) by default, but this may cause problems 519with some peripherals. 520.It Va kern.maxusers 521Set the size of a number of statically allocated system tables; see 522.Xr tuning 7 523for a description of how to select an appropriate value for this 524tunable. 525When set, this tunable replaces the value declared in the kernel 526compile-time configuration file. 527.It Va kern.ipc.nmbclusters 528Set the number of mbuf clusters to be allocated. 529The value cannot be set below the default 530determined when the kernel was compiled. 531.It Va kern.ipc.nsfbufs 532Set the number of 533.Xr sendfile 2 534buffers to be allocated. 535Overrides 536.Dv NSFBUFS . 537Not all architectures use such buffers; see 538.Xr sendfile 2 539for details. 540.It Va kern.maxswzone 541Limits the amount of KVM to be used to hold swap 542metadata, which directly governs the 543maximum amount of swap the system can support, 544at the rate of approximately 200 MB of swap space 545per 1 MB of metadata. 546This value is specified in bytes of KVA space. 547If no value is provided, the system allocates 548enough memory to handle an amount of swap 549that corresponds to eight times the amount of 550physical memory present in the system. 551.Pp 552Note that swap metadata can be fragmented, 553which means that the system can run out of 554space before it reaches the theoretical limit. 555Therefore, care should be taken to not configure 556more swap than approximately half of the 557theoretical maximum. 558.Pp 559Running out of space for swap metadata can leave 560the system in an unrecoverable state. 561Therefore, you should only change 562this parameter if you need to greatly extend the 563KVM reservation for other resources such as the 564buffer cache or 565.Va kern.ipc.nmbclusters . 566Modifies kernel option 567.Dv VM_SWZONE_SIZE_MAX . 568.It Va kern.maxbcache 569Limits the amount of KVM reserved for use by the 570buffer cache, specified in bytes. 571The default maximum is 200MB on i386, 572and 400MB on amd64. 573This parameter is used to 574prevent the buffer cache from eating too much 575KVM in large-memory machine configurations. 576Only mess around with this parameter if you need to 577greatly extend the KVM reservation for other resources 578such as the swap zone or 579.Va kern.ipc.nmbclusters . 580Note that 581the NBUF parameter will override this limit. 582Modifies 583.Dv VM_BCACHE_SIZE_MAX . 584.It Va kern.msgbufsize 585Sets the size of the kernel message buffer. 586The default limit of 96KB is usually sufficient unless 587large amounts of trace data need to be collected 588between opportunities to examine the buffer or 589dump it to a file. 590Overrides kernel option 591.Dv MSGBUF_SIZE . 592.It Va machdep.disable_mtrrs 593Disable the use of i686 MTRRs (x86 only). 594.It Va net.inet.tcp.tcbhashsize 595Overrides the compile-time set value of 596.Dv TCBHASHSIZE 597or the preset default of 512. 598Must be a power of 2. 599.It Va twiddle_divisor 600Throttles the output of the 601.Sq twiddle 602I/O progress indicator displayed while loading the kernel and modules. 603This is useful on slow serial consoles where the time spent waiting for 604these characters to be written can add up to many seconds. 605The default is 16; a value of 32 spins half as fast, 606while a value of 8 spins twice as fast. 607.It Va vm.kmem_size 608Sets the size of kernel memory (bytes). 609This overrides the value determined when the kernel was compiled. 610Modifies 611.Dv VM_KMEM_SIZE . 612.It Va vm.kmem_size_min 613.It Va vm.kmem_size_max 614Sets the minimum and maximum (respectively) amount of kernel memory 615that will be automatically allocated by the kernel. 616These override the values determined when the kernel was compiled. 617Modifies 618.Dv VM_KMEM_SIZE_MIN 619and 620.Dv VM_KMEM_SIZE_MAX . 621.El 622.Ss ZFS FEATURES 623.Nm 624supports the following format for specifying ZFS filesystems which 625can be used wherever 626.Xr loader 8 627refers to a device specification: 628.Pp 629.Ar zfs:pool/filesystem: 630.Pp 631where 632.Pa pool/filesystem 633is a ZFS filesystem name as described in 634.Xr zfs 8 . 635.Pp 636If 637.Pa /etc/fstab 638does not have an entry for the root filesystem and 639.Va vfs.root.mountfrom 640is not set, but 641.Va currdev 642refers to a ZFS filesystem, then 643.Nm 644will instruct kernel to use that filesystem as the root filesystem. 645.Sh SECURITY 646Access to the 647.Nm 648command line provides several ways of compromising system security, 649including, but not limited to: 650.Pp 651.Bl -bullet 652.It 653Booting from removable storage. 654.Pp 655One can prevent unauthorized access 656to the 657.Nm 658command line by booting unconditionally in 659.Pa loader.rc . 660In order for this to be effective, one should also configure the firmware 661(BIOS or UEFI) to prevent booting from unauthorized devices. 662.Sh FILES 663.Bl -tag -width /boot/loader_simp -compact 664.It Pa /boot/loader_simp 665.Nm 666itself. 667.It Pa /boot/loader.rc 668The script run by 669.Nm 670on startup. 671.Sh EXAMPLES 672Boot in single user mode: 673.Pp 674.Dl boot -s 675.Pp 676Load the kernel, a splash screen, and then autoboot in five seconds. 677Notice that a kernel must be loaded before any other 678.Ic load 679command is attempted. 680.Bd -literal -offset indent 681load kernel 682load splash_bmp 683load -t splash_image_data /boot/chuckrulez.bmp 684autoboot 5 685.Ed 686.Pp 687Set the disk unit of the root device to 2, and then boot. 688This would be needed in a system with two IDE disks, 689with the second IDE disk hardwired to ada2 instead of ada1. 690.Bd -literal -offset indent 691set root_disk_unit=2 692boot /boot/kernel/kernel 693.Ed 694.Pp 695Set the default device used for loading a kernel from a ZFS filesystem: 696.Bd -literal -offset indent 697set currdev=zfs:tank/ROOT/knowngood: 698.Ed 699.Pp 700.Sh ERRORS 701The following values are thrown by 702.Nm : 703.Bl -tag -width XXXXX -offset indent 704.It 100 705Any type of error in the processing of a builtin. 706.It -1 707.Ic Abort 708executed. 709.It -2 710.Ic Abort" 711executed. 712.It -56 713.Ic Quit 714executed. 715.It -256 716Out of interpreting text. 717.It -257 718Need more text to succeed -- will finish on next run. 719.It -258 720.Ic Bye 721executed. 722.It -259 723Unspecified error. 724.El 725.Sh SEE ALSO 726.Xr libsa 3 , 727.Xr loader.conf 5 , 728.Xr tuning 7 , 729.Xr boot 8 , 730.Xr btxld 8 731.Sh HISTORY 732The 733.Nm 734first appeared in 735.Fx 3.1 . 736.Sh AUTHORS 737.An -nosplit 738The 739.Nm 740was written by 741.An Michael Smith Aq msmith@FreeBSD.org . 742
