1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 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 April 27, 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.readConfFiles files loaded_files 63Process 64.Ev files 65as if it were 66.Ev loader_conf_files . 67The caller should pass in a table as the 68.Ev loaded_files 69argument, which uses filenames as keys and any non-nil value to indicate that 70the file named by the key has been loaded. 71.It Fn config.processFile name silent 72Process and parse 73.Ev name 74as a configuration file. 75Returns true if 76.Ev name 77exists and parses without error, false otherwise. 78If 79.Ev silent 80is true, 81.Fn config.processFile 82will not consider a failure to read the file as a failure. 83.It Fn config.parse text 84Parse 85.Ev text 86as a configuration file. 87This is used internally by 88.Fn config.processFile 89to parse the contents of a configuration file. 90Returns true if parsing succeeds without error, false if an error occurred. 91A message is also printed to the console if an error is encountered. 92.It Fn config.loadKernel other_kernel 93Attempts to load 94.Ev other_kernel 95as a kernel. 96If 97.Ev other_kernel 98is unset 99.Fn config.loadKernel 100will attempt to load 101.Dq kernel . 102Otherwise, it will try to load 103.Dq kernel 104first from 105.Pa /boot/{other_kernel} , 106then from 107.Pa {other_kernel} . 108.Pp 109The latter is tried in case an absolute path has been specified to the kernel 110to use. 111.Ev module_path 112is amended to include the directory the kernel was found in if either of these 113paths result in a loaded kernel. 114.Pp 115If no kernel was loaded from either of these paths, 116.Fn config.loadKernel 117will attempt to load a kernel named 118.Dq {other_kernel} 119from 120.Ev module_path 121instead of attempting to load a kernel named 122.Dq kernel . 123.Pp 124Returns true if a kernel was loaded, false if no kernel was loaded. 125.It Fn config.selectKernel kernel 126Set 127.Ev kernel 128to the kernel that will be loaded when either 129.Ic autoboot 130or 131.Ic boot 132are invoked. 133This is usually called by the menu system as the kernel selector carousel is 134toggled through. 135.It Fn config.load file reload 136Loads 137.Ev file 138as a configuration file. 139If 140.Ev file 141is not specified, 142.Pa /boot/defaults/loader.conf 143is used. 144.Fn config.load 145will then silently attempt to process any files specified in 146.Ev loader_conf_files 147after 148.Ev file 149has been processed. 150.Xr nextboot 8 151configuration will also be checked as part of 152.Fn config.load . 153Before returning, all 154.Dq config.loaded 155hooks will be run if 156.Ev reload 157is not set to true. 158.It Fn config.reload file 159Reloads 160.Ev file 161as a configuration file. 162.Fn config.reload 163will restore the environment to how it existed before the last config was 164loaded, then it will invoke 165.Fn config.load file . 166Before returning, all 167.Dq config.reloaded 168hooks will be run. 169.It Fn config.loadelf 170Loads all ELF objects, the selected kernel as well as any modules configured to 171be preloaded in 172.Xr loader.conf 5 . 173This will be called by the Lua intercepted 174.Ic autoboot 175and 176.Ic boot 177commands. 178.El 179.Ss Defined Hooks 180The following hooks are defined in 181.Nm : 182.Bl -tag -width "config.reloaded" -offset indent 183.It Fn config.loaded 184.It Fn config.reloaded 185.It Fn kernel.loaded 186.It Fn modules.loaded 187.El 188.Sh SEE ALSO 189.Xr loader.conf 5 , 190.Xr loader 8 , 191.Xr menu.lua 8 , 192.Xr nextboot 8 193.Sh AUTHORS 194The 195.Nm 196file was originally written by 197.An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . 198Later work and this manual page was done by 199.An Kyle Evans Aq Mt kevans@FreeBSD.org . 200