From 73577bf01de5c4677dc54d97f93310286c254780 Mon Sep 17 00:00:00 2001 From: Ryan Moeller Date: Sat, 24 Oct 2020 17:08:59 +0000 Subject: [PATCH] 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 | 1 + contrib/mandoc/msec.in | 1 + etc/mtree/BSD.usr.dist | 4 + lib/Makefile | 5 + lib/flua/Makefile | 5 + lib/flua/libjail/Makefile | 16 ++ lib/flua/libjail/jail.3lua | 210 +++++++++++++++++ lib/flua/libjail/lua_jail.c | 391 ++++++++++++++++++++++++++++++++ share/examples/Makefile | 4 + share/examples/flua/libjail.lua | 60 +++++ share/man/Makefile | 2 +- share/man/man3lua/Makefile | 7 + share/man/man3lua/intro.3lua | 65 ++++++ usr.bin/man/man.1 | 1 + usr.bin/man/man.sh | 2 +- 15 files changed, 772 insertions(+), 2 deletions(-) create mode 100644 lib/flua/Makefile create mode 100644 lib/flua/libjail/Makefile create mode 100644 lib/flua/libjail/jail.3lua create mode 100644 lib/flua/libjail/lua_jail.c create mode 100644 share/examples/flua/libjail.lua create mode 100644 share/man/man3lua/Makefile create mode 100644 share/man/man3lua/intro.3lua diff --git a/Makefile.inc1 b/Makefile.inc1 index 1f5a9641a8db..c52895259e3a 100644 --- a/Makefile.inc1 +++ b/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} \ diff --git a/contrib/mandoc/msec.in b/contrib/mandoc/msec.in index d5b319f16a9f..fc198202fbf1 100644 --- a/contrib/mandoc/msec.in +++ b/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") diff --git a/etc/mtree/BSD.usr.dist b/etc/mtree/BSD.usr.dist index 73a5fe6eca9c..b9329600c231 100644 --- a/etc/mtree/BSD.usr.dist +++ b/etc/mtree/BSD.usr.dist @@ -281,6 +281,8 @@ .. find_interface .. + flua + .. hast .. hostapd @@ -857,6 +859,8 @@ .. man3 .. + man3lua + .. man4 aarch64 .. diff --git a/lib/Makefile b/lib/Makefile index f5006d4eb5f4..5d7caa6b9423 100644 --- a/lib/Makefile +++ b/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 diff --git a/lib/flua/Makefile b/lib/flua/Makefile new file mode 100644 index 000000000000..2ea9f69b98d4 --- /dev/null +++ b/lib/flua/Makefile @@ -0,0 +1,5 @@ +# $FreeBSD$ + +SUBDIR= libjail + +.include diff --git a/lib/flua/libjail/Makefile b/lib/flua/libjail/Makefile new file mode 100644 index 000000000000..22f9bdb33fef --- /dev/null +++ b/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 diff --git a/lib/flua/libjail/jail.3lua b/lib/flua/libjail/jail.3lua new file mode 100644 index 000000000000..fb54b94844f5 --- /dev/null +++ b/lib/flua/libjail/jail.3lua @@ -0,0 +1,210 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD +.\" +.\" Copyright (c) 2020, Ryan Moeller +.\" +.\" 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 . diff --git a/lib/flua/libjail/lua_jail.c b/lib/flua/libjail/lua_jail.c new file mode 100644 index 000000000000..9981fd5421c6 --- /dev/null +++ b/lib/flua/libjail/lua_jail.c @@ -0,0 +1,391 @@ +/*- + * SPDX-License-Identifier: BSD-2-Clause + * + * Copyright (c) 2020, Ryan Moeller + * + * 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 +__FBSDID("$FreeBSD$"); + +#include +#include +#include +#include +#include +#include + +#include +#include +#include + +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(¶ms); + 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(¶ms[0], "name") == -1) { + free(params); + return (luaL_error(L, "jailparam_init: %s", + jail_errmsg)); + } + name = lua_tostring(L, 1); + if (jailparam_import(¶ms[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(¶ms[0], "jid") == -1) { + free(params); + return (luaL_error(L, "jailparam_init: %s", + jail_errmsg)); + } + jid = lua_tointeger(L, 1); + if (jailparam_import_raw(¶ms[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(¶ms[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(¶ms[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(¶ms[0], "name") == -1) { + free(params); + return (luaL_error(L, "jailparam_init: %s", + jail_errmsg)); + } + name = lua_tostring(L, 1); + if (jailparam_import(¶ms[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(¶ms[0], "jid") == -1) { + free(params); + return (luaL_error(L, "jailparam_init: %s", + jail_errmsg)); + } + jid = lua_tointeger(L, 1); + if (jailparam_import_raw(¶ms[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(¶ms[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(¶ms[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); +} diff --git a/share/examples/Makefile b/share/examples/Makefile index 50ca81fb2f3b..f4273d2266f0 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 000000000000..3ff878460d2f --- /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 + * + * 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 e1dc9cf06c80..59a1ab9dbc36 100644 --- a/share/man/Makefile +++ b/share/man/Makefile @@ -4,7 +4,7 @@ .include # 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 000000000000..751d559adfb5 --- /dev/null +++ b/share/man/man3lua/Makefile @@ -0,0 +1,7 @@ +# $FreeBSD$ + +.include + +MAN= intro.3lua + +.include diff --git a/share/man/man3lua/intro.3lua b/share/man/man3lua/intro.3lua new file mode 100644 index 000000000000..854865a5ca42 --- /dev/null +++ b/share/man/man3lua/intro.3lua @@ -0,0 +1,65 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD +.\" +.\" Copyright (c) 2020, Ryan Moeller +.\" +.\" 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 . diff --git a/usr.bin/man/man.1 b/usr.bin/man/man.1 index 2e3629864cfc..4305e81c1115 100644 --- a/usr.bin/man/man.1 +++ b/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 , diff --git a/usr.bin/man/man.sh b/usr.bin/man/man.sh index 12a370cd8efb..f31c464fcc8f 100755 --- a/usr.bin/man/man.sh +++ b/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'