diff options
Diffstat (limited to 'lib/flua/libjail/jail.3lua')
| -rw-r--r-- | lib/flua/libjail/jail.3lua | 210 |
1 files changed, 210 insertions, 0 deletions
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 <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 . |