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