1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 1999 Daniel C. Sobral 5.\" All rights reserved. 6.\" Copyright (c) 2021 Warner Losh <imp@FreeBSD.org> 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd June 4, 2026 30.Dt LOADER 8 31.Os 32.Sh NAME 33.Nm loader 34.Nd kernel bootstrapping final stage 35.Sh DESCRIPTION 36The program called 37.Nm 38is the final stage of 39.Fx Ns 's 40kernel bootstrapping process. 41It is responsible for bringing the kernel, kernel modules and other files into 42memory. 43It creates a set of 44.Xr sh 1 45like environment variables that are passed to the kernel. 46It executes boot scripts written in one of several interpreters. 47Together with the scripts, it controls the booting process and 48interaction with the user. 49.Pp 50It provides a scripting language that can be used to 51automate tasks, do pre-configuration or assist in recovery 52procedures. 53This scripting language is roughly divided in 54two main components. 55The smaller one is a set of commands 56designed for direct use by the casual user, called "builtin 57commands" for historical reasons. 58The main drive behind these commands is user-friendliness. 59The larger component is the scripting language built into 60the boot loader. 61.Fx 62provides three different interpreters: Forth, Lua and Simple. 63The Forth loader is based on an ANS Forth compatible 64Forth interpreter based on FICL, by 65.An John Sadler . 66The Lua loader is a full Lua interpreter from 67.Pa https://www.lua.org/ . 68The Simple loader only interprets a list of builtin commands 69without any control structure. 70.Pp 71During initialization, 72.Nm 73will probe for a console and set the 74.Va console 75variable, or set it to serial console 76.Pq Dq Li comconsole 77if the previous boot stage used that. 78If multiple consoles are selected, they will be listed separated by spaces. 79Then, devices are probed, 80.Va currdev 81and 82.Va loaddev 83are set, and 84.Va LINES 85is set to 24. 86Finally, an interpreter specific file will be executed. 87.Sh BUILTIN COMMANDS 88The commands common to all interpreters are described in the 89.Xr loader_simp 8 90.Dq BUILTIN COMMANDS 91section. 92.Pp 93The following commands are only available in 94.Xr loader_lua 8 95and 96.Xr loader_4th 8 : 97.Pp 98.Bl -tag -width indent -compact 99.\" sort the following entries according to the second field 100.It Ic be-list 101Lists the boot environments that are visible to 102.Nm . 103The listed names may be used directly with 104.Ic be-switch . 105.It Ic be-switch Ar beName 106Switch to the 107.Ar beName 108boot environment. 109The 110.Nm 111configuration will be reloaded from the new root, and any previously loaded 112kernel and modules will be immediately unloaded. 113.It Ic boot-conf 114Load the 115.Nm 116config and commence the autoboot sequence. 117.Pp 118.It Ic read-conf Ar file 119Load the specified configuration file. 120.Pp 121.It Ic reload-conf 122Revert any previously applied settings, and reload the configuration. 123Set comands that were executed at the command line to override variables 124previously 125.Cm set 126by 127.Xr loader.conf 5 128configuration will also be reverted, 129along with any module options that were toggled. 130.Pp 131.It Ic enable-module Ar kmod-name 132.It Ic disable-module Ar kmod-name 133.It Ic toggle-module Ar kmod-name 134Enable, disable, or toggle loading of the kernel module named 135.Dq Ar kmod-name . 136.Pp 137.It Ic show-module-options 138Describe all modules the 139.Nm 140is aware of, and show if they are enabled or not. 141.El 142.Pp 143The following command is only available in 144.Xr loader_lua 8 : 145.Pp 146.Bl -tag -width indent -compact 147.It Ic disable-device Ar device 148Set a newbus hint to disable the 149.Ar device . 150.El 151.Ss BUILTIN ENVIRONMENT VARIABLES 152The environment variables common to all interpreters are described in the 153.Xr loader_simp 8 154.Dq BUILTIN ENVIRONMENT VARIABLES 155section. 156.Sh SEE ALSO 157.Xr libsa 3 , 158.Xr loader.conf 5 , 159.Xr tuning 7 , 160.Xr boot 8 , 161.Xr btxld 8 , 162.Xr loader.efi 8 , 163.Xr loader_4th 8 , 164.Xr loader_lua 8 , 165.Xr loader_simp 8 166.Sh HISTORY 167The 168.Nm 169first appeared in 170.Fx 3.1 . 171The 172.Nm 173scripting language changed to Lua by default in 174.Fx 12.0 . 175.Sh AUTHORS 176.An -nosplit 177The 178.Nm 179was written by 180.An Michael Smith Aq Mt msmith@FreeBSD.org . 181.Pp 182FICL was written by 183.An John Sadler Aq Mt john_sadler@alum.mit.edu . 184.Pp 185.An Warner Losh Aq Mt imp@FreeBSD.org 186integrated Lua into the tree based on initial work done by Pedro Souza 187for the 2014 Google Summer of Code. 188