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