stand/man/loader_lua.8

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