---
name: "config.lua"
section: "8"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/config.lua"
---

# config.lua(8)

bootloader configuration module

## NAME

**config.lua** – bootloader configuration module

## DESCRIPTION

**config.lua** contains configuration and module loading functionality.

Before hooking into or using the functionality provided by **config.lua**, 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**:

- **config.getCarouselIndex**(*id*)

  Returns the currently chosen index in the carousel menu entry described by id. See the definition of [menu.lua(8)](/menu.lua/8.md) for a more in-depth explanation of carousels.

- **config.setCarouselIndex**(*id*, *idx*)

  Set 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*)

  Process *file* as a configuration file (e.g., as *loader.conf*) and then process 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)](/loader.conf/5.md)). The caller may optionally pass in a table as the loaded\_files argument, which uses filenames as keys and any non-nil value to indicate that the file named by the key has already been loaded and should not be loaded again.

- **config.processFile**(*name*, *silent*)

  Process and parse 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*)

  Parse 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*)

  Set 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)](/nextboot/8.md) 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)](/loader.conf/5.md). 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)](/loader.conf/5.md) 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

[loader.conf(5)](/loader.conf/5.md), [loader(8)](/loader/8.md), [menu.lua(8)](/menu.lua/8.md), [nextboot(8)](/nextboot/8.md)

## 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*⟩.