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 November 14, 2025 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 boot-conf 101Load the 102.Nm 103config and commence the autoboot sequence. 104.Pp 105.It Ic read-conf Ar file 106Load the specified configuration file. 107.Pp 108.It Ic reload-conf 109Revert any previously applied settings, and reload the configuration. 110Set comands that were executed at the command line to override variables 111previously 112.Cm set 113by 114.Xr loader.conf 5 115configuration will also be reverted, 116along with any module options that were toggled. 117.Pp 118.It Ic enable-module Ar kmod-name 119.It Ic disable-module Ar kmod-name 120.It Ic toggle-module Ar kmod-name 121Enable, disable, or toggle loading of the kernel module named 122.Dq Ar kmod-name . 123.Pp 124.It Ic show-module-options 125Describe all modules the 126.Nm 127is aware of, and show if they are enabled or not. 128.El 129.Pp 130The following command is only available in 131.Xr loader_lua 8 : 132.Pp 133.Bl -tag -width indent -compact 134.It Ic disable-device Ar device 135Set a newbus hint to disable the 136.Ar device . 137.El 138.Ss BUILTIN ENVIRONMENT VARIABLES 139The environment variables common to all interpreters are described in the 140.Xr loader_simp 8 141.Dq BUILTIN ENVIRONMENT VARIABLES 142section. 143.Sh SEE ALSO 144.Xr libsa 3 , 145.Xr loader.conf 5 , 146.Xr tuning 7 , 147.Xr boot 8 , 148.Xr btxld 8 , 149.Xr loader.efi 8 , 150.Xr loader_4th 8 , 151.Xr loader_lua 8 , 152.Xr loader_simp 8 153.Sh HISTORY 154The 155.Nm 156first appeared in 157.Fx 3.1 . 158The 159.Nm 160scripting language changed to Lua by default in 161.Fx 12.0 . 162.Sh AUTHORS 163.An -nosplit 164The 165.Nm 166was written by 167.An Michael Smith Aq Mt msmith@FreeBSD.org . 168.Pp 169FICL was written by 170.An John Sadler Aq Mt john_sadler@alum.mit.edu . 171.Pp 172.An Warner Losh Aq Mt imp@FreeBSD.org 173integrated Lua into the tree based on initial work done by Pedro Souza 174for the 2014 Google Summer of Code. 175