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

5 files changed, 137 insertions, 1 deletions

diff --git a/share/examples/Makefile b/share/examples/Makefile
index 50ca81fb2f3bf..f4273d2266f09 100644
--- a/share/examples/Makefile
+++ b/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
 
diff --git a/share/examples/flua/libjail.lua b/share/examples/flua/libjail.lua
new file mode 100644
index 0000000000000..3ff878460d2f6
--- /dev/null
+++ b/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
diff --git a/share/man/Makefile b/share/man/Makefile
index e1dc9cf06c80c..59a1ab9dbc367 100644
--- a/share/man/Makefile
+++ b/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
diff --git a/share/man/man3lua/Makefile b/share/man/man3lua/Makefile
new file mode 100644
index 0000000000000..751d559adfb5e
--- /dev/null
+++ b/share/man/man3lua/Makefile
@@ -0,0 +1,7 @@
+# $FreeBSD$
+
+.include <src.opts.mk>
+
+MAN=	intro.3lua
+
+.include <bsd.prog.mk>
diff --git a/share/man/man3lua/intro.3lua b/share/man/man3lua/intro.3lua
new file mode 100644
index 0000000000000..854865a5ca42e
--- /dev/null
+++ b/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 .