stand/lua/config.lua.8

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