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