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 interpter. 57.Pp 58During initialization, 59.Nm 60will probe for a console and set the 61.Va console 62variable, or set it to serial console 63.Pq Dq Li comconsole 64if the previous boot stage used that. 65If multiple consoles are selected, they will be 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 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. 118If an error condition occurs, an exception will be generated, 119which can be intercepted using Lua exception handling. 120If not intercepted, an error message will be displayed and 121the interpreter's state will be 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 135by it as 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 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 will be probed and be 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.Sh EXAMPLES 204Boot in single user mode: 205.Pp 206.Dl boot -s 207.Pp 208Load the kernel, a splash screen, and then autoboot in five seconds. 209Notice that a kernel must be loaded before any other 210.Ic load 211command is attempted. 212.Bd -literal -offset indent 213load kernel 214load splash_bmp 215load -t splash_image_data /boot/chuckrulez.bmp 216autoboot 5 217.Ed 218.Pp 219Set the disk unit of the root device to 2, and then boot. 220This would be needed in a system with two IDE disks, 221with the second IDE disk hardwired to ada2 instead of ada1. 222.Bd -literal -offset indent 223set root_disk_unit=2 224boot /boot/kernel/kernel 225.Ed 226.Pp 227Set the default device used for loading a kernel from a ZFS filesystem: 228.Bd -literal -offset indent 229set currdev=zfs:tank/ROOT/knowngood: 230.Ed 231.Pp 232.Sh ERRORS 233The following values are thrown by 234.Nm : 235.Bl -tag -width XXXXX -offset indent 236.It 100 237Any type of error in the processing of a builtin. 238.It -1 239.Ic Abort 240executed. 241.It -2 242.Ic Abort" 243executed. 244.It -56 245.Ic Quit 246executed. 247.It -256 248Out of interpreting text. 249.It -257 250Need more text to succeed -- will finish on next run. 251.It -258 252.Ic Bye 253executed. 254.It -259 255Unspecified error. 256.El 257.Sh SEE ALSO 258.Xr libstand 3 , 259.Xr loader.conf 5 , 260.Xr tuning 7 , 261.Xr boot 8 , 262.Xr btxld 8 263.Sh HISTORY 264The 265.Nm 266first appeared in 267.Fx 12.0 . 268
