1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 1999 Daniel C. Sobral 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd September 29, 2021 29.Dt LOADER_LUA 8 30.Os 31.Sh NAME 32.Nm loader_lua 33.Nd kernel bootstrapping final stage 34.Sh DESCRIPTION 35The program called 36.Nm 37is the final stage of 38.Fx Ns 's 39kernel bootstrapping process. 40On IA32 (i386) architectures, it is a 41.Pa BTX 42client. 43It is linked statically to 44.Xr libsa 3 45and usually located in the directory 46.Pa /boot . 47.Pp 48It provides a scripting language that can be used to 49automate tasks, do pre-configuration or assist in recovery 50procedures. 51This scripting language is roughly divided in 52two main components. 53The smaller one is a set of commands 54designed for direct use by the casual user, called "builtin 55commands" for historical reasons. 56The main drive behind these commands is user-friendliness. 57The bigger component is the Lua interpreter. 58.Pp 59During initialization, 60.Nm 61probes for a console and sets the 62.Va console 63variable, or sets it to serial console 64.Pq Dq Li comconsole 65if the previous boot stage used that. 66If multiple consoles are selected, they are listed separated by spaces. 67Then, devices are probed, 68.Va currdev 69and 70.Va loaddev 71are set, and 72.Va LINES 73is set to 24. 74Next, Lua is initialized, and 75.Pa /boot/lua/loader.lua 76is processed if it exists. 77After that, 78.Pa /boot/loader.conf 79is processed if available. 80.Pp 81At this point, if an 82.Ic autoboot 83has not been attempted, and if 84.Va autoboot_delay 85is not set to 86.Dq Li NO 87(case insensitive), then an 88.Ic autoboot 89is attempted. 90If the system gets past this point, 91.Va prompt 92is set and 93.Nm 94enters interactive mode. 95Please note that, historically, even when 96.Va autoboot_delay 97is set to 98.Dq Li 0 , 99the user can interrupt the autoboot process by pressing a key 100on the console while the kernel and modules are being loaded. 101To prevent this set 102.Va autoboot_delay 103to 104.Dq Li -1 . 105In this case 106.Nm 107enters 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. 118If an error condition occurs, an exception is generated, 119which can be intercepted using Lua exception handling. 120If not intercepted, an error message is displayed and 121the interpreter's state is reset, emptying the stack and restoring 122interpreting mode. 123.Pp 124The commands are described in the 125.Xr loader_simp 8 126.Dq BUILTIN COMMANDS 127section. 128.Ss BUILTIN ENVIRONMENT VARIABLES 129The environment variables common to all interpreters are described in the 130.Xr loader_simp 8 131.Dq BUILTIN ENVIRONMENT VARIABLES 132section. 133.Ss BUILTIN PARSER 134When a builtin command is executed, the rest of the line is taken 135as arguments, and it is processed by a special parser which 136is not used for regular Lua commands. 137.Sh SECURITY 138Access to the 139.Nm 140command line provides several ways of compromising system security, 141including, but not limited to: 142.Pp 143.Bl -bullet 144.It 145Booting from removable storage, by setting the 146.Va currdev 147or 148.Va loaddev 149variables 150.It 151Executing a binary of choice, by setting the 152.Va init_path 153or 154.Va init_script 155variables 156.It 157Overriding ACPI DSDT to inject arbitrary code into the ACPI subsystem 158.El 159.Pp 160One can prevent unauthorized access 161to the 162.Nm 163command line by setting the 164.Va password , 165or setting 166.Va autoboot_delay 167to -1. 168See 169.Xr loader.conf 5 170for details. 171In order for this to be effective, one should also configure the firmware 172(BIOS or UEFI) to prevent booting from unauthorized devices. 173.Sh MD 174Memory disk (MD) can be used when the 175.Nm 176was compiled with 177.Va MD_IMAGE_SIZE . 178The size of the memory disk is determined by 179.Va MD_IMAGE_SIZE . 180If MD available, a file system can be embedded into the 181.Nm 182with 183.Pa /sys/tools/embed_mfs.sh . 184Then, MD is probed and set to 185.Va currdev 186during initialization. 187.Pp 188Currently, MD is only supported in 189.Xr loader.efi 8 . 190.Sh FILES 191.Bl -tag -width /usr/share/examples/bootforth/ -compact 192.It Pa /boot/loader 193.Nm 194itself. 195.It Pa /boot/defaults/loader.conf 196.It Pa /boot/lua/loader.lua 197Loader init 198.It Pa /boot/loader.conf 199.It Pa /boot/loader.conf.local 200.Nm 201configuration files, as described in 202.Xr loader.conf 5 . 203.El 204.Sh EXAMPLES 205Boot in single user mode: 206.Pp 207.Dl boot -s 208.Pp 209Load the kernel, a splash screen, and then autoboot in five seconds. 210Notice that a kernel must be loaded before any other 211.Ic load 212command is attempted. 213.Bd -literal -offset indent 214load kernel 215load splash_bmp 216load -t splash_image_data /boot/chuckrulez.bmp 217autoboot 5 218.Ed 219.Pp 220Set the disk unit of the root device to 2, and then boot. 221This would be needed in a system with two IDE disks, 222with the second IDE disk hardwired to ada2 instead of ada1. 223.Bd -literal -offset indent 224set root_disk_unit=2 225boot /boot/kernel/kernel 226.Ed 227.Pp 228Set the default device used for loading a kernel from a ZFS filesystem: 229.Bd -literal -offset indent 230set currdev=zfs:tank/ROOT/knowngood: 231.Ed 232.Pp 233.Sh ERRORS 234The following values are thrown by 235.Nm : 236.Bl -tag -width XXXXX -offset indent 237.It 100 238Any type of error in the processing of a builtin. 239.It -1 240.Ic Abort 241executed. 242.It -2 243.Ic Abort" 244executed. 245.It -56 246.Ic Quit 247executed. 248.It -256 249Out of interpreting text. 250.It -257 251Need more text to succeed -- will finish on next run. 252.It -258 253.Ic Bye 254executed. 255.It -259 256Unspecified error. 257.El 258.Sh SEE ALSO 259.Xr libsa 3 , 260.Xr loader.conf 5 , 261.Xr tuning 7 , 262.Xr boot 8 , 263.Xr btxld 8 264.Sh HISTORY 265The 266.Nm 267first appeared in 268.Fx 12.0 . 269
