stand/lua/config.lua.8

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