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_LUA 8 29.Os 30.Sh NAME 31.Nm loader_lua 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. 56The bigger component is the Lua interpreter. 57.Pp 58During initialization, 59.Nm 60probes for a console and sets the 61.Va console 62variable, or sets it to serial console 63.Pq Dq Li comconsole 64if the previous boot stage used that. 65If multiple consoles are selected, they are listed separated by spaces. 66Then, devices are probed, 67.Va currdev 68and 69.Va loaddev 70are set, and 71.Va LINES 72is set to 24. 73Next, Lua is initialized, and 74.Pa /boot/lua/loader.lua 75is processed if it exists. 76After that, 77.Pa /boot/loader.conf 78is processed if available. 79.Pp 80At this point, if an 81.Ic autoboot 82has not been attempted, and if 83.Va autoboot_delay 84is not set to 85.Dq Li NO 86(case insensitive), then an 87.Ic autoboot 88is attempted. 89If the system gets past this point, 90.Va prompt 91is set and 92.Nm 93enters interactive mode. 94Please note that, historically, even when 95.Va autoboot_delay 96is set to 97.Dq Li 0 , 98the user can interrupt the autoboot process by pressing a key 99on the console while the kernel and modules are being loaded. 100To prevent this set 101.Va autoboot_delay 102to 103.Dq Li -1 . 104In this case 105.Nm 106enters interactive mode only if 107.Ic autoboot 108has failed. 109.Sh BUILTIN COMMANDS 110In 111.Nm , 112builtin commands take parameters from the command line. 113Presently, 114the only way to call them from a script is by using 115.Pa evaluate 116on a string. 117If an error condition occurs, an exception is generated, 118which can be intercepted using Lua exception handling. 119If not intercepted, an error message is displayed and 120the interpreter's state is reset, emptying the stack and restoring 121interpreting mode. 122.Pp 123The commands are described in the 124.Xr loader_simp 8 125.Dq BUILTIN COMMANDS 126section. 127.Ss BUILTIN ENVIRONMENT VARIABLES 128The environment variables common to all interpreters are described in the 129.Xr loader_simp 8 130.Dq BUILTIN ENVIRONMENT VARIABLES 131section. 132.Ss BUILTIN PARSER 133When a builtin command is executed, the rest of the line is taken 134as arguments, and it is processed by a special parser which 135is not used for regular Lua commands. 136.Sh SECURITY 137Access to the 138.Nm 139command line provides several ways of compromising system security, 140including, but not limited to: 141.Pp 142.Bl -bullet 143.It 144Booting from removable storage, by setting the 145.Va currdev 146or 147.Va loaddev 148variables 149.It 150Executing a binary of choice, by setting the 151.Va init_path 152or 153.Va init_script 154variables 155.It 156Overriding ACPI DSDT to inject arbitrary code into the ACPI subsystem 157.El 158.Pp 159One can prevent unauthorized access 160to the 161.Nm 162command line by setting the 163.Va password , 164or setting 165.Va autoboot_delay 166to -1. 167See 168.Xr loader.conf 5 169for details. 170In order for this to be effective, one should also configure the firmware 171(BIOS or UEFI) to prevent booting from unauthorized devices. 172.Sh MD 173Memory disk (MD) can be used when the 174.Nm 175was compiled with 176.Va MD_IMAGE_SIZE . 177The size of the memory disk is determined by 178.Va MD_IMAGE_SIZE . 179If MD available, a file system can be embedded into the 180.Nm 181with 182.Pa /sys/tools/embed_mfs.sh . 183Then, MD is probed and set to 184.Va currdev 185during initialization. 186.Pp 187Currently, MD is only supported in 188.Xr loader.efi 8 . 189.Sh FILES 190.Bl -tag -width /usr/share/examples/bootforth/ -compact 191.It Pa /boot/loader 192.Nm 193itself. 194.It Pa /boot/defaults/loader.conf 195.It Pa /boot/lua/loader.lua 196Loader init 197.It Pa /boot/loader.conf 198.It Pa /boot/loader.conf.local 199.Nm 200configuration files, as described in 201.Xr loader.conf 5 . 202.Sh EXAMPLES 203Boot in single user mode: 204.Pp 205.Dl boot -s 206.Pp 207Load the kernel, a splash screen, and then autoboot in five seconds. 208Notice that a kernel must be loaded before any other 209.Ic load 210command is attempted. 211.Bd -literal -offset indent 212load kernel 213load splash_bmp 214load -t splash_image_data /boot/chuckrulez.bmp 215autoboot 5 216.Ed 217.Pp 218Set the disk unit of the root device to 2, and then boot. 219This would be needed in a system with two IDE disks, 220with the second IDE disk hardwired to ada2 instead of ada1. 221.Bd -literal -offset indent 222set root_disk_unit=2 223boot /boot/kernel/kernel 224.Ed 225.Pp 226Set the default device used for loading a kernel from a ZFS filesystem: 227.Bd -literal -offset indent 228set currdev=zfs:tank/ROOT/knowngood: 229.Ed 230.Pp 231.Sh ERRORS 232The following values are thrown by 233.Nm : 234.Bl -tag -width XXXXX -offset indent 235.It 100 236Any type of error in the processing of a builtin. 237.It -1 238.Ic Abort 239executed. 240.It -2 241.Ic Abort" 242executed. 243.It -56 244.Ic Quit 245executed. 246.It -256 247Out of interpreting text. 248.It -257 249Need more text to succeed -- will finish on next run. 250.It -258 251.Ic Bye 252executed. 253.It -259 254Unspecified error. 255.El 256.Sh SEE ALSO 257.Xr libstand 3 , 258.Xr loader.conf 5 , 259.Xr tuning 7 , 260.Xr boot 8 , 261.Xr btxld 8 262.Sh HISTORY 263The 264.Nm 265first appeared in 266.Fx 12.0 . 267
