3fe0ac6aa5
The previous interface was pretty bad, and required the caller to get some implementation details correct that it really shouldn't need to (e.g. loader_conf_files handling) and pass in an empty table for it to use. The new and much improved interface, readConf, is much less of a hack; hiding these implementation details and just doing the right thing. config.lua will now use it to process /boot/defaults/loader.conf and the subsequent loader_conf_files from there, and read-conf will also use it. This improvement submitted by Olivier (cited below), loader_conf_files handling from the original patch was changed to just clobber it before processing and not bother restoring it after the fact following r360505 where it's now guaranteed to evade the loader environment. PR: 244640 Submitted by: Olivier Certner (olivier freebsd free fr>
209 lines
5.6 KiB
Groff
209 lines
5.6 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 April 30, 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.
|
|
.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 .
|