1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org> 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd December 17, 2020 28.Dt CONFIG.LUA 8 29.Os 30.Sh NAME 31.Nm config.lua 32.Nd FreeBSD config module 33.Sh DESCRIPTION 34.Nm 35contains configuration and module loading functionality. 36.Pp 37Before hooking into or using the functionality provided by 38.Nm , 39it must be included with a statement such as the following: 40.Pp 41.Dl local config = require("config") 42.Ss Exported functions 43The following functions are exported from 44.Nm : 45.Bl -tag -width "config.setCarouselIndex(id, idx)" -offset indent 46.It Fn config.getCarouselIndex id 47Returns the currently chosen index in the carousel menu entry described by 48.Ev id . 49See the definition of 50.Xr menu.lua 8 51for a more in-depth explanation of carousels. 52.It Fn config.setCarouselIndex id idx 53Set the chosen index for the carousel menu entry described by 54.Ev id 55to 56.Ev idx . 57A lookup will be done as needed to determine what value 58.Ev idx 59actually corresponds to. 60.It Fn config.readConf file loaded_files 61Process 62.Pa file 63as a configuration file 64.Po e.g., as 65.Pa loader.conf 66.Pc 67and then processing files listed in 68.Ev loader_conf_files 69variable 70.Po see 71.Xr loader.conf 5 72.Pc . 73The caller may optionally pass in a table as the 74.Ev loaded_files 75argument, which uses filenames as keys and any non-nil value to 76indicate that the file named by the key has already been loaded and 77should not be loaded again. 78.It Fn config.processFile name silent 79Process and parse 80.Ev name 81as a configuration file. 82Returns true if 83.Ev name 84exists and parses without error, false otherwise. 85If 86.Ev silent 87is true, 88.Fn config.processFile 89will not consider a failure to read the file as a failure. 90.It Fn config.parse text 91Parse 92.Ev text 93as a configuration file. 94This is used internally by 95.Fn config.processFile 96to parse the contents of a configuration file. 97Returns true if parsing succeeds without error, false if an error occurred. 98A message is also printed to the console if an error is encountered. 99.It Fn config.loadKernel other_kernel 100Attempts to load 101.Ev other_kernel 102as a kernel. 103If 104.Ev other_kernel 105is unset 106.Fn config.loadKernel 107will attempt to load 108.Dq kernel . 109Otherwise, it will try to load 110.Dq kernel 111first from 112.Pa /boot/{other_kernel} , 113then from 114.Pa {other_kernel} . 115.Pp 116The latter is tried in case an absolute path has been specified to the kernel 117to use. 118.Ev module_path 119is amended to include the directory the kernel was found in if either of these 120paths result in a loaded kernel. 121.Pp 122If no kernel was loaded from either of these paths, 123.Fn config.loadKernel 124will attempt to load a kernel named 125.Dq {other_kernel} 126from 127.Ev module_path 128instead of attempting to load a kernel named 129.Dq kernel . 130.Pp 131Returns true if a kernel was loaded, false if no kernel was loaded. 132.It Fn config.selectKernel kernel 133Set 134.Ev kernel 135to the kernel that will be loaded when either 136.Ic autoboot 137or 138.Ic boot 139are invoked. 140This is usually called by the menu system as the kernel selector carousel is 141toggled through. 142.It Fn config.load file reload 143Loads 144.Ev file 145as a configuration file. 146If 147.Ev file 148is not specified, 149.Pa /boot/defaults/loader.conf 150is used. 151.Fn config.load 152will then silently attempt to process any files specified in 153.Ev loader_conf_files 154after 155.Ev file 156has been processed. 157.Xr nextboot 8 158configuration will also be checked as part of 159.Fn config.load . 160Before returning, all 161.Dq config.loaded 162hooks will be run if 163.Ev reload 164is not set to true. 165.It Fn config.reload file 166Reloads 167.Ev file 168as a configuration file. 169.Fn config.reload 170will restore the environment to how it existed before the last config was 171loaded, then it will invoke 172.Fn config.load file . 173Before returning, all 174.Dq config.reloaded 175hooks will be run. 176.It Fn config.loadelf 177Loads all ELF objects, the selected kernel as well as any modules configured to 178be preloaded in 179.Xr loader.conf 5 . 180This will be called by the Lua intercepted 181.Ic autoboot 182and 183.Ic boot 184commands. 185.It Fn config.enableModule modname 186Marks a module named 187.Fa modname 188to be loaded during 189.Fn config.loadelf . 190If the module was previously blacklisted, then it will be forcefully allowed to 191load. 192.It Fn config.disableModule modname 193Marks a module named 194.Fa modname 195to not be loaded during 196.Fn config.loadelf . 197.It Fn config.isModuleEnabled modname 198Checks if the module named 199.Fa modname 200will be loaded during 201.Fn config.loadelf . 202It checks both that the module is marked for loading and that it is either 203forced or not blacklisted. 204.It Fn config.getModuleInfo 205Returns a table with 206.Dq modules 207and 208.Dq blacklist 209tables describing the modules that the config module has been made aware of via 210.Xr loader.conf 5 211as well as a representation of 212.Ar module_blacklist . 213.El 214.Ss Defined Hooks 215The following hooks are defined in 216.Nm : 217.Bl -tag -width "config.reloaded" -offset indent 218.It Fn config.buildenv env 219.It Fn config.loaded 220.It Fn config.reloaded 221.It Fn kernel.loaded 222.It Fn modules.loaded 223.El 224.Pp 225Note that the 226.Fn config.buildenv 227hook is only invoked when an environment needs to be built to execute a lua 228configuration file that has been specified in 229.Ev loader_conf_files . 230It will be invoked for each configuration file encountered. 231.Sh SEE ALSO 232.Xr loader.conf 5 , 233.Xr loader 8 , 234.Xr menu.lua 8 , 235.Xr nextboot 8 236.Sh AUTHORS 237The 238.Nm 239file was originally written by 240.An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . 241Later work and this manual page was done by 242.An Kyle Evans Aq Mt kevans@FreeBSD.org . 243