CONFIG.LUA(8)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

okay bestie, welcome to config.lua(8) — the System Manager's Manual page for the bootloader configuration module. 🎀 This one is lowkey iconic: it's all about configuration and module loading, and the functions are the main characters. iykyk. 💅

🌸 NAME

config.lua — bootloader configuration module. Periodt. ✨

💖 DESCRIPTION

config.lua contains configuration and module loading functionality. No cap. ✨

Before you hook into it or use anything it provides, it must be included with a statement such as the following:

local config = require("config")

✨ Exported functions

The following functions are exported from config.lua, and they are fr fr the ones you need to know about:

  • config.getCarouselIndex(id) — Returns the currently chosen index in the carousel menu entry described by id. See the definition of menu.lua(8) for a more in-depth explanation of carousels. (Carousel lore, bestie. Obsessed. 🎠)
  • config.setCarouselIndex(id, idx) — Sets the chosen index for the carousel menu entry described by id to idx. A lookup will be done as needed to determine what value idx actually corresponds to.
  • config.readConf(file, loaded_files) — Processes file as a configuration file (e.g., as loader.conf) and then processes files listed in the loader_conf_files variable. Additionally, the top-level call to readConf will process files listed in the loader_conf_dirs and local_loader_conf_files variables (see loader.conf(5)). The caller may optionally pass in a table as the loaded_files argument; that table uses filenames as keys, and any non-nil value indicates that the file named by the key has already been loaded and should not be loaded again. No double-loading, slay. 🫶
  • config.processFile(name, silent) — Processes and parses name as a configuration file. Returns true if name exists and parses without error, false otherwise. If silent is true, config.processFile() will not consider a failure to read the file as a failure. 🙈
  • config.parse(text) — Parses text as a configuration file. This is used internally by config.processFile() to parse the contents of a configuration file. Returns true if parsing succeeds without error, false if an error occurred. A message is also printed to the console if an error is encountered. 💀
  • config.loadKernel(other_kernel) — Attempts to load other_kernel as a kernel. If other_kernel is unset, config.loadKernel() will attempt to load kernel. Otherwise, it will try to load kernel first from /boot/{other_kernel}, then from {other_kernel}. The latter is tried in case an absolute path has been specified to the kernel to use. module_path is amended to include the directory the kernel was found in if either of these paths result in a loaded kernel. If no kernel was loaded from either of these paths, config.loadKernel() will attempt to load a kernel named {other_kernel} from module_path instead of attempting to load a kernel named kernel. Returns true if a kernel was loaded, false if no kernel was loaded. 🔥
  • config.selectKernel(kernel) — Sets kernel to the kernel that will be loaded when either autoboot or boot are invoked. This is usually called by the menu system as the kernel selector carousel is toggled through. 🎠
  • config.load(file, reload) — Loads file as a configuration file. If file is not specified, /boot/defaults/loader.conf is used. config.load() will then silently attempt to process any files specified in loader_conf_files after file has been processed. nextboot(8) configuration will also be checked as part of config.load(). Before returning, all config.loaded hooks will be run if reload is not set to true. ✨
  • config.reload(file) — Reloads file as a configuration file. config.reload() will restore the environment to how it existed before the last config was loaded, then it will invoke config.load(file). Before returning, all config.reloaded hooks will be run. 🌀
  • config.loadelf() — Loads all ELF objects, the selected kernel as well as any modules configured to be preloaded in loader.conf(5). This will be called by the Lua intercepted autoboot and boot commands. 👑
  • config.enableModule(modname) — Marks a module named modname to be loaded during config.loadelf(). If the module was previously blacklisted, then it will be forcefully allowed to load. 💪
  • config.disableModule(modname) — Marks a module named modname to not be loaded during config.loadelf(). 🚫
  • config.isModuleEnabled(modname) — Checks if the module named modname will be loaded during config.loadelf(). It checks both that the module is marked for loading and that it is either forced or not blacklisted. ✅
  • config.getModuleInfo() — Returns a table with modules and blacklist tables describing the modules that the config module has been made aware of via loader.conf(5) as well as a representation of module_blacklist. 📦

🪝 Defined Hooks

The following hooks are defined in config.lua:

  • config.buildenv(env)
  • config.loaded()
  • config.reloaded()
  • kernel.loaded()
  • modules.loaded()

Note that the config.buildenv() hook is only invoked when an environment needs to be built to execute a lua configuration file that has been specified in loader_conf_files. It will be invoked for each configuration file encountered. 🌈

👀 SEE ALSO

💌 AUTHORS

The config.lua file was originally written by Pedro Souza (pedrosouza@FreeBSD.org). Later work and this manual page was done by Kyle Evans (kevans@FreeBSD.org). 🫶

Debian, March 29, 2025 — that’s the source/version and date for this manual page. config.lua(8) Byeee bestie! 💖

📦 where this page comes from