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