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