flua: Add a libjail module

libjail is pretty small, so it makes for a good proof of concept demonstrating
how a system library can be wrapped to create a loadable Lua module for flua.

* Introduce 3lua section for man pages
* Add libjail module

Reviewed by:	kevans, manpages
Relnotes:	yes
Differential Revision:	https://reviews.freebsd.org/D26080

Makefile.inc1

@@ -2829,6 +2829,7 @@ _prebuild_libs=	${_kerberos5_lib_libasn1} \
 		lib/libelf lib/libexpat \
 		lib/libfigpar \
 		${_lib_libgssapi} \
+		lib/libjail \
 		lib/libkiconv lib/libkvm lib/liblzma lib/libmd lib/libnv \
 		lib/libzstd \
 		${_lib_casper} \

contrib/mandoc/msec.in

@@ -25,6 +25,7 @@
 LINE("1",		"FreeBSD General Commands Manual")
 LINE("2",		"FreeBSD System Calls Manual")
 LINE("3",		"FreeBSD Library Functions Manual")
+LINE("3lua",		"Lua Library Functions Manual")
 LINE("3p",		"Perl Library Functions Manual")
 LINE("4",		"FreeBSD Kernel Interfaces Manual")
 LINE("5",		"FreeBSD File Formats Manual")

etc/mtree/BSD.usr.dist

@@ -281,6 +281,8 @@
             ..
             find_interface
             ..
+            flua
+            ..
             hast
             ..
             hostapd
@@ -857,6 +859,8 @@
             ..
             man3
             ..
+            man3lua
+            ..
             man4
                 aarch64
                 ..

lib/Makefile

@@ -142,6 +142,11 @@ SUBDIR_DEPEND_liblzma= ${_libthr}
 SUBDIR_DEPEND_libpcap= ofed
 .endif
 
+.if !defined(COMPAT_32BIT)
+SUBDIR+=	flua
+SUBDIR_DEPEND_flua=	libjail
+.endif
+
 # NB: keep these sorted by MK_* knobs
 
 SUBDIR.${MK_ATM}+=	libngatm

lib/flua/Makefile

@@ -0,0 +1,5 @@
+# $FreeBSD$
+
+SUBDIR=	libjail
+
+.include <bsd.subdir.mk>

lib/flua/libjail/Makefile

@@ -0,0 +1,16 @@
+# $FreeBSD$
+
+SHLIB_NAME=	jail.so
+SHLIBDIR=	${LIBDIR}/flua
+
+SRCS+=		lua_jail.c
+
+CFLAGS+= \
+	-I${SRCTOP}/contrib/lua/src \
+	-I${SRCTOP}/lib/liblua \
+
+LIBADD+=	jail
+
+MAN=	jail.3lua
+
+.include <bsd.lib.mk>

lib/flua/libjail/jail.3lua

@@ -0,0 +1,210 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
+.\"
+.\" Copyright (c) 2020, Ryan Moeller <freqlabs@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 October 24, 2020
+.Dt JAIL 3lua
+.Os
+.Sh NAME
+.Nm getid ,
+.Nm getname ,
+.Nm allparams ,
+.Nm getparams ,
+.Nm setparams ,
+.Nm CREATE ,
+.Nm UPDATE ,
+.Nm ATTACH ,
+.Nm DYING
+.Nd Lua binding to
+.Xr jail 3
+.Sh SYNOPSIS
+.Bd -literal
+local jail = require('jail')
+.Ed
+.Pp
+.Bl -tag -width XXXX -compact
+.It Dv jid, err = jail.getid(name)
+.It Dv name, err = jail.getname(jid)
+.It Dv params, err = jail.allparams()
+.It Dv jid, res = jail.getparams(jid|name, params [, flags ] )
+.It Dv jid, err = jail.setparams(jid|name, params, flags )
+.It Dv jail.CREATE
+.It Dv jail.UPDATE
+.It Dv jail.ATTACH
+.It Dv jail.DYING
+.El
+.Sh DESCRIPTION
+The
+.Nm jail
+module is a binding to the
+.Xr jail 3
+library.
+It provides a string-oriented interface for the
+.Xr jail_get 2
+and
+.Xr jail_set 2
+system calls.
+.Bl -tag -width XXXX
+.It Dv jid, err = jail.getid(name)
+Get the jail identifier
+.Pq jid
+as an integer.
+.Fa name
+is the name of a jail or a jid in the form of a string.
+.It Dv name, err = jail.getname(jid)
+Get the name of a jail as a string for the given
+.Fa jid
+.Pq an integer .
+.It Dv params, err = jail.allparams()
+Get a list of all supported parameter names
+.Pq as strings .
+See
+.Xr jail 8
+for descriptions of the core jail parameters.
+.It Dv jid, res = jail.getparams(jid|name, params [, flags ] )
+Get a table of the requested parameters for the given jail.
+.Nm jid|name
+can either be the jid as an integer or the jid or name as a string.
+.Nm params
+is a list of parameter names.
+.Nm flags
+is an optional integer representing the flag bits to apply for the operation.
+See the list of flags below.
+Only the
+.Dv DYING
+flag is valid to set.
+.It Dv jid, err = jail.setparams(jid|name, params [, flags ] )
+Set parameters for a given jail.
+This is used to create, update, attach to, or destroy a jail.
+.Nm jid|name
+can either be the jid as an integer or the jid or name as a string.
+.Nm params
+is a table of parameters to apply to the jail, where each key in the table
+is a parameter name as a string and each value is a string that will be
+converted to the internal value type by
+.Xr jailparam_import 3 .
+.Nm flags
+is an optional integer representing the flag bits to apply for the operation.
+See the list of flags below.
+.El
+.Pp
+The
+.Nm flags
+arguments are an integer bitwise-or combination of one or more of the following
+flags:
+.Bl -tag -width XXXX
+.It Dv jail.CREATE
+Used with
+.Fn setparams
+to create a new jail.
+The jail must not already exist, unless combined with
+.Dv UPDATE .
+.It Dv jail.UPDATE
+Used with
+.Fn setparams
+to modify an existing jail.
+The jail must already exist, unless combined with
+.Dv CREATE .
+.It Dv jail.ATTACH
+Used with
+.Fn setparams
+in combination with
+.Dv CREATE
+or
+.Dv UPDATE
+to attach the current process to a jail.
+.It Dv jail.DYING
+Allow operating on a jail that is in the process of being removed.
+.El
+.Sh RETURN VALUES
+The
+.Fn getid
+and
+.Fn setparams
+functions return a jail identifier integer on success, or
+.Dv nil
+and an error message string if an error occurred.
+.Pp
+The
+.Fn getname
+function returns a jail name string on success, or
+.Dv nil
+and an error message string if an error occurred.
+.Pp
+The
+.Fn allparams
+function returns a list of parameter name strings on success, or
+.Dv nil
+and an error message string if an error occurred.
+.Pp
+The
+.Fn getparams
+function returns a jail identifier integer and a table of jail parameters
+with parameter name strings as keys and strings for values on success, or
+.Dv nil
+and an error message string if an error occurred.
+.Sh EXAMPLES
+Set the hostname of jail
+.Dq foo
+to
+.Dq foo.bar :
+.Bd -literal -offset indent
+local jail = require('jail')
+
+jid, err = jail.setparams("foo", {["host.hostname"]="foo.bar"},
+    jail.UPDATE)
+if not jid then
+    error(err)
+end
+.Ed
+.Pp
+Retrieve the hostname of jail
+.Dq foo :
+.Bd -literal -offset indent
+local jail = require('jail')
+
+jid, res = jail.getparams("foo", {"host.hostname"})
+if not jid then
+    error(res)
+end
+print(res["host.hostname"])
+.Ed
+.Sh SEE ALSO
+.Xr jail 2 ,
+.Xr jail 3 ,
+.Xr jail 8
+.Sh HISTORY
+The
+.Nm jail
+Lua module for flua first appeared in
+.Fx 13.0 .
+.Sh AUTHORS
+.An Ryan Moeller ,
+with inspiration from
+.Nx
+gpio(3lua), by
+.An Mark Balmer .

lib/flua/libjail/lua_jail.c

@@ -0,0 +1,391 @@
+/*-
+ * SPDX-License-Identifier: BSD-2-Clause
+ *
+ * Copyright (c) 2020, Ryan Moeller <freqlabs@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 REGENTS 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 REGENTS 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$
+ */
+
+#include <sys/cdefs.h>
+__FBSDID("$FreeBSD$");
+
+#include <sys/param.h>
+#include <sys/jail.h>
+#include <errno.h>
+#include <jail.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <lua.h>
+#include <lauxlib.h>
+#include <lualib.h>
+
+int luaopen_jail(lua_State *);
+
+static int
+l_getid(lua_State *L)
+{
+	const char *name;
+	int jid;
+
+	name = luaL_checkstring(L, 1);
+	jid = jail_getid(name);
+	if (jid == -1) {
+		lua_pushnil(L);
+		lua_pushstring(L, jail_errmsg);
+		return (2);
+	}
+	lua_pushinteger(L, jid);
+	return (1);
+}
+
+static int
+l_getname(lua_State *L)
+{
+	char *name;
+	int jid;
+
+	jid = luaL_checkinteger(L, 1);
+	name = jail_getname(jid);
+	if (name == NULL) {
+		lua_pushnil(L);
+		lua_pushstring(L, jail_errmsg);
+		return (2);
+	}
+	lua_pushstring(L, name);
+	free(name);
+	return (1);
+}
+
+static int
+l_allparams(lua_State *L)
+{
+	struct jailparam *params;
+	int params_count;
+
+	params_count = jailparam_all(&params);
+	if (params_count == -1) {
+		lua_pushnil(L);
+		lua_pushstring(L, jail_errmsg);
+		return (2);
+	}
+	lua_newtable(L);
+	for (int i = 0; i < params_count; ++i) {
+		lua_pushstring(L, params[i].jp_name);
+		lua_rawseti(L, -2, i + 1);
+	}
+	jailparam_free(params, params_count);
+	free(params);
+	return (1);
+}
+
+static int
+l_getparams(lua_State *L)
+{
+	const char *name;
+	struct jailparam *params;
+	size_t params_count, skipped;
+	int flags, jid, type;
+
+	type = lua_type(L, 1);
+	luaL_argcheck(L, type == LUA_TSTRING || type == LUA_TNUMBER, 1,
+	    "expected a jail name (string) or id (integer)");
+	luaL_checktype(L, 2, LUA_TTABLE);
+	params_count = 1 + lua_rawlen(L, 2);
+	luaL_argcheck(L, params_count > 1, 2, "expected #params > 0");
+	flags = luaL_optinteger(L, 3, 0);
+
+	params = malloc(params_count * sizeof(struct jailparam));
+	if (params == NULL)
+		return (luaL_error(L, "malloc: %s", strerror(errno)));
+
+	/*
+	 * Set the jail name or id param as determined by the first arg.
+	 */
+
+	if (type == LUA_TSTRING) {
+		if (jailparam_init(&params[0], "name") == -1) {
+			free(params);
+			return (luaL_error(L, "jailparam_init: %s",
+			    jail_errmsg));
+		}
+		name = lua_tostring(L, 1);
+		if (jailparam_import(&params[0], name) == -1) {
+			jailparam_free(params, 1);
+			free(params);
+			return (luaL_error(L, "jailparam_import: %s",
+			    jail_errmsg));
+		}
+	} else /* type == LUA_TNUMBER */ {
+		if (jailparam_init(&params[0], "jid") == -1) {
+			free(params);
+			return (luaL_error(L, "jailparam_init: %s",
+			    jail_errmsg));
+		}
+		jid = lua_tointeger(L, 1);
+		if (jailparam_import_raw(&params[0], &jid, sizeof(jid)) == -1) {
+			jailparam_free(params, 1);
+			free(params);
+			return (luaL_error(L, "jailparam_import_raw: %s",
+			    jail_errmsg));
+		}
+	}
+
+	/*
+	 * Set the remaining param names being requested.
+	 */
+
+	skipped = 0;
+	for (size_t i = 1; i < params_count; ++i) {
+		const char *param_name;
+
+		lua_rawgeti(L, -1, i);
+		param_name = lua_tostring(L, -1);
+		if (param_name == NULL) {
+			jailparam_free(params, i - skipped);
+			free(params);
+			return (luaL_argerror(L, 2,
+			    "param names must be strings"));
+		}
+		lua_pop(L, 1);
+		/* Skip name or jid, whichever was given. */
+		if (type == LUA_TSTRING) {
+			if (strcmp(param_name, "name") == 0) {
+				++skipped;
+				continue;
+			}
+		} else /* type == LUA_TNUMBER */ {
+			if (strcmp(param_name, "jid") == 0) {
+				++skipped;
+				continue;
+			}
+		}
+		if (jailparam_init(&params[i - skipped], param_name) == -1) {
+			jailparam_free(params, i - skipped);
+			free(params);
+			return (luaL_error(L, "jailparam_init: %s",
+			    jail_errmsg));
+		}
+	}
+	params_count -= skipped;
+
+	/*
+	 * Get the values and convert to a table.
+	 */
+
+	jid = jailparam_get(params, params_count, flags);
+	if (jid == -1) {
+		jailparam_free(params, params_count);
+		free(params);
+		lua_pushnil(L);
+		lua_pushstring(L, jail_errmsg);
+		return (2);
+	}
+	lua_pushinteger(L, jid);
+
+	lua_newtable(L);
+	for (size_t i = 0; i < params_count; ++i) {
+		char *value;
+
+		value = jailparam_export(&params[i]);
+		lua_pushstring(L, value);
+		free(value);
+		lua_setfield(L, -2, params[i].jp_name);
+	}
+
+	jailparam_free(params, params_count);
+	free(params);
+
+	return (2);
+}
+
+static int
+l_setparams(lua_State *L)
+{
+	const char *name;
+	struct jailparam *params;
+	size_t params_count;
+	int flags, jid, type;
+
+	type = lua_type(L, 1);
+	luaL_argcheck(L, type == LUA_TSTRING || type == LUA_TNUMBER, 1,
+	    "expected a jail name (string) or id (integer)");
+	luaL_checktype(L, 2, LUA_TTABLE);
+
+	lua_pushnil(L);
+	for (params_count = 1; lua_next(L, 2) != 0; ++params_count)
+		lua_pop(L, 1);
+	luaL_argcheck(L, params_count > 1, 2, "expected #params > 0");
+
+	flags = luaL_optinteger(L, 3, 0);
+
+	params = malloc(params_count * sizeof(struct jailparam));
+	if (params == NULL)
+		return (luaL_error(L, "malloc: %s", strerror(errno)));
+
+	/*
+	 * Set the jail name or id param as determined by the first arg.
+	 */
+
+	if (type == LUA_TSTRING) {
+		if (jailparam_init(&params[0], "name") == -1) {
+			free(params);
+			return (luaL_error(L, "jailparam_init: %s",
+			    jail_errmsg));
+		}
+		name = lua_tostring(L, 1);
+		if (jailparam_import(&params[0], name) == -1) {
+			jailparam_free(params, 1);
+			free(params);
+			return (luaL_error(L, "jailparam_import: %s",
+			    jail_errmsg));
+		}
+	} else /* type == LUA_TNUMBER */ {
+		if (jailparam_init(&params[0], "jid") == -1) {
+			free(params);
+			return (luaL_error(L, "jailparam_init: %s",
+			    jail_errmsg));
+		}
+		jid = lua_tointeger(L, 1);
+		if (jailparam_import_raw(&params[0], &jid, sizeof(jid)) == -1) {
+			jailparam_free(params, 1);
+			free(params);
+			return (luaL_error(L, "jailparam_import_raw: %s",
+			    jail_errmsg));
+		}
+	}
+
+	/*
+	 * Set the rest of the provided params.
+	 */
+
+	lua_pushnil(L);
+	for (size_t i = 1; i < params_count && lua_next(L, 2) != 0; ++i) {
+		const char *value;
+
+		name = lua_tostring(L, -2);
+		if (name == NULL) {
+			jailparam_free(params, i);
+			free(params);
+			return (luaL_argerror(L, 2,
+			    "param names must be strings"));
+		}
+		if (jailparam_init(&params[i], name) == -1) {
+			jailparam_free(params, i);
+			free(params);
+			return (luaL_error(L, "jailparam_init: %s",
+			    jail_errmsg));
+		}
+
+		value = lua_tostring(L, -1);
+		if (value == NULL) {
+			jailparam_free(params, i + 1);
+			free(params);
+			return (luaL_argerror(L, 2,
+			    "param values must be strings"));
+		}
+		if (jailparam_import(&params[i], value) == -1) {
+			jailparam_free(params, i + 1);
+			free(params);
+			return (luaL_error(L, "jailparam_import: %s",
+			    jail_errmsg));
+		}
+
+		lua_pop(L, 1);
+	}
+
+	/*
+	 * Attempt to set the params.
+	 */
+
+	jid = jailparam_set(params, params_count, flags);
+	if (jid == -1) {
+		jailparam_free(params, params_count);
+		free(params);
+		lua_pushnil(L);
+		lua_pushstring(L, jail_errmsg);
+		return (2);
+	}
+	lua_pushinteger(L, jid);
+
+	jailparam_free(params, params_count);
+	free(params);
+	return (1);
+}
+
+static const struct luaL_Reg l_jail[] = {
+	/** Get id of a jail by name.
+	 * @param name	jail name (string)
+	 * @return	jail id (integer)
+	 *		or nil, error (string) on error
+	 */
+	{"getid", l_getid},
+	/** Get name of a jail by id.
+	 * @param jid	jail id (integer)
+	 * @return	jail name (string)
+	 *		or nil, error (string) on error
+	 */
+	{"getname", l_getname},
+	/** Get a list of all known jail parameters.
+	 * @return	list of jail parameter names (table of strings)
+	 *		or nil, error (string) on error
+	 */
+	{"allparams", l_allparams},
+	/** Get the listed params for a given jail.
+	 * @param jail	jail name (string) or id (integer)
+	 * @param params	list of parameter names (table of strings)
+	 * @param flags	optional flags (integer)
+	 * @return	jid (integer), params (table of [string] = string)
+	 *		or nil, error (string) on error
+	 */
+	{"getparams", l_getparams},
+	/** Set params for a given jail.
+	 * @param jail	jail name (string) or id (integer)
+	 * @param params	params and values (table of [string] = string)
+	 * @param flags	optional flags (integer)
+	 * @return	jid (integer)
+	 *		or nil, error (string) on error
+	 */
+	{"setparams", l_setparams},
+	{NULL, NULL}
+};
+
+int
+luaopen_jail(lua_State *L)
+{
+	lua_newtable(L);
+
+	luaL_setfuncs(L, l_jail, 0);
+
+	lua_pushinteger(L, JAIL_CREATE);
+	lua_setfield(L, -2, "CREATE");
+	lua_pushinteger(L, JAIL_UPDATE);
+	lua_setfield(L, -2, "UPDATE");
+	lua_pushinteger(L, JAIL_ATTACH);
+	lua_setfield(L, -2, "ATTACH");
+	lua_pushinteger(L, JAIL_DYING);
+	lua_setfield(L, -2, "DYING");
+
+	return (1);
+}

share/examples/Makefile

@@ -16,6 +16,7 @@ LDIRS=	BSD_daemon \
 	drivers \
 	etc \
 	find_interface \
+	flua \
 	indent \
 	ipfw \
 	jails \
@@ -98,6 +99,9 @@ SE_FIND_INTERFACE= \
 	README \
 	find_interface.c
 
+SE_DIRS+=	flua
+SE_FLUA=	libjail.lua
+
 SE_DIRS+=	indent
 SE_INDENT=	indent.pro
 

share/examples/flua/libjail.lua

@@ -0,0 +1,60 @@
+#!/usr/libexec/flua
+--[[
+/*-
+ * SPDX-License-Identifier: BSD-2-Clause
+ *
+ * Copyright (c) 2020, Ryan Moeller <freqlabs@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 REGENTS 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 REGENTS 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$
+ */
+]]--
+
+jail = require("jail")
+ucl = require("ucl")
+
+name = "demo"
+
+-- Create a persistent jail named "demo" with all other parameters default.
+jid, err = jail.setparams(name, {persist = "true"}, jail.CREATE)
+if not jid then
+    error(err)
+end
+
+-- Get a list of all known jail parameter names.
+allparams = jail.allparams()
+
+-- Get all the parameters of the jail we created.
+jid, res = jail.getparams(name, allparams)
+if not jid then
+    error(res)
+end
+
+-- Display the jail's parameters as a pretty-printed JSON object.
+print(ucl.to_json(res))
+
+-- Update the "persist" parameter to "false" to remove the jail.
+jid, err = jail.setparams(name, {persist = "false"}, jail.UPDATE)
+if not jid then
+    error(err)
+end

share/man/Makefile

@@ -4,7 +4,7 @@
 .include <src.opts.mk>
 
 # XXX MISSING:	man3f
-SUBDIR=	man1 man3 man4 man5 man6 man7 man8 man9
+SUBDIR=	man1 man3 man3lua man4 man5 man6 man7 man8 man9
 SUBDIR_PARALLEL=
 
 MAKEWHATIS?=	makewhatis

share/man/man3lua/Makefile

@@ -0,0 +1,7 @@
+# $FreeBSD$
+
+.include <src.opts.mk>
+
+MAN=	intro.3lua
+
+.include <bsd.prog.mk>

share/man/man3lua/intro.3lua

@@ -0,0 +1,65 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
+.\"
+.\" Copyright (c) 2020, Ryan Moeller <freqlabs@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 October 24, 2020
+.Dt INTRO 3lua
+.Os
+.Sh NAME
+.Nm intro
+.Nd introduction to the Lua modules for flua
+.Po
+.Fx
+Lua
+.Pc
+.Sh DESCRIPTION
+This section describes
+.Em flua
+.Po
+.Fx
+Lua
+.Pc
+and the Lua modules provided in the
+.Fx
+base system.
+.Pp
+The Lua modules provided by
+.Fx
+are:
+.Bl -tag -width jail
+.It Xr jail 3lua
+Wrapper for
+.Xr jail 3 .
+.El
+.Sh SEE ALSO
+.Xr jail 3lua
+.Sh AUTHORS
+.An Ryan Moeller ,
+with inspiration from
+.Nx
+intro(3lua), by
+.An Marc Balmer .

usr.bin/man/man.1

@@ -365,6 +365,7 @@ Local configuration files.
 .Xr whatis 1 ,
 .Xr intro 2 ,
 .Xr intro 3 ,
+.Xr intro 3lua ,
 .Xr intro 4 ,
 .Xr intro 5 ,
 .Xr man.conf 5 ,

usr.bin/man/man.sh

@@ -1012,7 +1012,7 @@ STTY=/bin/stty
 SYSCTL=/sbin/sysctl
 
 debug=0
-man_default_sections='1:8:2:3:n:4:5:6:7:9:l'
+man_default_sections='1:8:2:3:3lua:n:4:5:6:7:9:l'
 man_default_path='/usr/share/man:/usr/share/openssl/man:/usr/local/share/man:/usr/local/man'
 cattool='/usr/bin/zcat -f'