7ed84fa14b
This effectively dumps everything lualoader knows about to the console using the libsa pager; that particular lua interface was added in r368591. A pager stub implementation has been added that just dumps the output as-is as a compat shim for older loader binaries that do not have lpager. This stub should be moved into a more appropriate .lua file if we add anything else that needs the pager.
237 lines
6.4 KiB
Groff
237 lines
6.4 KiB
Groff
.\"
|
|
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
|
|
.\"
|
|
.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd December 17, 2020
|
|
.Dt CONFIG.LUA 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm config.lua
|
|
.Nd FreeBSD config module
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
contains configuration and module loading functionality.
|
|
.Pp
|
|
Before hooking into or using the functionality provided by
|
|
.Nm ,
|
|
it must be included with a statement such as the following:
|
|
.Pp
|
|
.Dl local config = require("config")
|
|
.Ss Exported functions
|
|
The following functions are exported from
|
|
.Nm :
|
|
.Bl -tag -width "config.setCarouselIndex(id, idx)" -offset indent
|
|
.It Fn config.getCarouselIndex id
|
|
Returns the currently chosen index in the carousel menu entry described by
|
|
.Ev id .
|
|
See the definition of
|
|
.Xr menu.lua 8
|
|
for a more in-depth explanation of carousels.
|
|
.It Fn config.setCarouselIndex id idx
|
|
Set the chosen index for the carousel menu entry described by
|
|
.Ev id
|
|
to
|
|
.Ev idx .
|
|
A lookup will be done as needed to determine what value
|
|
.Ev idx
|
|
actually corresponds to.
|
|
.It Fn config.readConf file loaded_files
|
|
Process
|
|
.Pa file
|
|
as a configuration file
|
|
.Po e.g., as
|
|
.Pa loader.conf
|
|
.Pc
|
|
and then processing files listed in
|
|
.Ev loader_conf_files
|
|
variable
|
|
.Po see
|
|
.Xr loader.conf 5
|
|
.Pc .
|
|
The caller may optionally pass in a table as the
|
|
.Ev 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.
|
|
.It Fn config.processFile name silent
|
|
Process and parse
|
|
.Ev name
|
|
as a configuration file.
|
|
Returns true if
|
|
.Ev name
|
|
exists and parses without error, false otherwise.
|
|
If
|
|
.Ev silent
|
|
is true,
|
|
.Fn config.processFile
|
|
will not consider a failure to read the file as a failure.
|
|
.It Fn config.parse text
|
|
Parse
|
|
.Ev text
|
|
as a configuration file.
|
|
This is used internally by
|
|
.Fn 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.
|
|
.It Fn config.loadKernel other_kernel
|
|
Attempts to load
|
|
.Ev other_kernel
|
|
as a kernel.
|
|
If
|
|
.Ev other_kernel
|
|
is unset
|
|
.Fn config.loadKernel
|
|
will attempt to load
|
|
.Dq kernel .
|
|
Otherwise, it will try to load
|
|
.Dq kernel
|
|
first from
|
|
.Pa /boot/{other_kernel} ,
|
|
then from
|
|
.Pa {other_kernel} .
|
|
.Pp
|
|
The latter is tried in case an absolute path has been specified to the kernel
|
|
to use.
|
|
.Ev module_path
|
|
is amended to include the directory the kernel was found in if either of these
|
|
paths result in a loaded kernel.
|
|
.Pp
|
|
If no kernel was loaded from either of these paths,
|
|
.Fn config.loadKernel
|
|
will attempt to load a kernel named
|
|
.Dq {other_kernel}
|
|
from
|
|
.Ev module_path
|
|
instead of attempting to load a kernel named
|
|
.Dq kernel .
|
|
.Pp
|
|
Returns true if a kernel was loaded, false if no kernel was loaded.
|
|
.It Fn config.selectKernel kernel
|
|
Set
|
|
.Ev kernel
|
|
to the kernel that will be loaded when either
|
|
.Ic autoboot
|
|
or
|
|
.Ic boot
|
|
are invoked.
|
|
This is usually called by the menu system as the kernel selector carousel is
|
|
toggled through.
|
|
.It Fn config.load file reload
|
|
Loads
|
|
.Ev file
|
|
as a configuration file.
|
|
If
|
|
.Ev file
|
|
is not specified,
|
|
.Pa /boot/defaults/loader.conf
|
|
is used.
|
|
.Fn config.load
|
|
will then silently attempt to process any files specified in
|
|
.Ev loader_conf_files
|
|
after
|
|
.Ev file
|
|
has been processed.
|
|
.Xr nextboot 8
|
|
configuration will also be checked as part of
|
|
.Fn config.load .
|
|
Before returning, all
|
|
.Dq config.loaded
|
|
hooks will be run if
|
|
.Ev reload
|
|
is not set to true.
|
|
.It Fn config.reload file
|
|
Reloads
|
|
.Ev file
|
|
as a configuration file.
|
|
.Fn config.reload
|
|
will restore the environment to how it existed before the last config was
|
|
loaded, then it will invoke
|
|
.Fn config.load file .
|
|
Before returning, all
|
|
.Dq config.reloaded
|
|
hooks will be run.
|
|
.It Fn config.loadelf
|
|
Loads all ELF objects, the selected kernel as well as any modules configured to
|
|
be preloaded in
|
|
.Xr loader.conf 5 .
|
|
This will be called by the Lua intercepted
|
|
.Ic autoboot
|
|
and
|
|
.Ic boot
|
|
commands.
|
|
.It Fn config.enableModule modname
|
|
Marks a module named
|
|
.Fa modname
|
|
to be loaded during
|
|
.Fn config.loadelf .
|
|
If the module was previously blacklisted, then it will be forcefully allowed to
|
|
load.
|
|
.It Fn config.disableModule modname
|
|
Marks a module named
|
|
.Fa modname
|
|
to not be loaded during
|
|
.Fn config.loadelf .
|
|
.It Fn config.isModuleEnabled modname
|
|
Checks if the module named
|
|
.Fa modname
|
|
will be loaded during
|
|
.Fn config.loadelf .
|
|
It checks both that the module is marked for loading and that it is either
|
|
forced or not blacklisted.
|
|
.It Fn config.getModuleInfo
|
|
Returns a table with
|
|
.Dq modules
|
|
and
|
|
.Dq blacklist
|
|
tables describing the modules that the config module has been made aware of via
|
|
.Xr loader.conf 5
|
|
as well as a representation of
|
|
.Ar module_blacklist .
|
|
.El
|
|
.Ss Defined Hooks
|
|
The following hooks are defined in
|
|
.Nm :
|
|
.Bl -tag -width "config.reloaded" -offset indent
|
|
.It Fn config.loaded
|
|
.It Fn config.reloaded
|
|
.It Fn kernel.loaded
|
|
.It Fn modules.loaded
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr loader.conf 5 ,
|
|
.Xr loader 8 ,
|
|
.Xr menu.lua 8 ,
|
|
.Xr nextboot 8
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
file was originally written by
|
|
.An Pedro Souza Aq Mt pedrosouza@FreeBSD.org .
|
|
Later work and this manual page was done by
|
|
.An Kyle Evans Aq Mt kevans@FreeBSD.org .
|