1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 3.\" 4.\" Copyright (c) 2020, Ryan Moeller <freqlabs@FreeBSD.org> 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd October 24, 2020 30.Dt JAIL 3lua 31.Os 32.Sh NAME 33.Nm getid , 34.Nm getname , 35.Nm allparams , 36.Nm getparams , 37.Nm setparams , 38.Nm CREATE , 39.Nm UPDATE , 40.Nm ATTACH , 41.Nm DYING 42.Nd Lua binding to 43.Xr jail 3 44.Sh SYNOPSIS 45.Bd -literal 46local jail = require('jail') 47.Ed 48.Pp 49.Bl -tag -width XXXX -compact 50.It Dv jid, err = jail.getid(name) 51.It Dv name, err = jail.getname(jid) 52.It Dv params, err = jail.allparams() 53.It Dv jid, res = jail.getparams(jid|name, params [, flags ] ) 54.It Dv jid, err = jail.setparams(jid|name, params, flags ) 55.It Dv jail.CREATE 56.It Dv jail.UPDATE 57.It Dv jail.ATTACH 58.It Dv jail.DYING 59.El 60.Sh DESCRIPTION 61The 62.Nm jail 63module is a binding to the 64.Xr jail 3 65library. 66It provides a string-oriented interface for the 67.Xr jail_get 2 68and 69.Xr jail_set 2 70system calls. 71.Bl -tag -width XXXX 72.It Dv jid, err = jail.getid(name) 73Get the jail identifier 74.Pq jid 75as an integer. 76.Fa name 77is the name of a jail or a jid in the form of a string. 78.It Dv name, err = jail.getname(jid) 79Get the name of a jail as a string for the given 80.Fa jid 81.Pq an integer . 82.It Dv params, err = jail.allparams() 83Get a list of all supported parameter names 84.Pq as strings . 85See 86.Xr jail 8 87for descriptions of the core jail parameters. 88.It Dv jid, res = jail.getparams(jid|name, params [, flags ] ) 89Get a table of the requested parameters for the given jail. 90.Nm jid|name 91can either be the jid as an integer or the jid or name as a string. 92.Nm params 93is a list of parameter names. 94.Nm flags 95is an optional integer representing the flag bits to apply for the operation. 96See the list of flags below. 97Only the 98.Dv DYING 99flag is valid to set. 100.It Dv jid, err = jail.setparams(jid|name, params [, flags ] ) 101Set parameters for a given jail. 102This is used to create, update, attach to, or destroy a jail. 103.Nm jid|name 104can either be the jid as an integer or the jid or name as a string. 105.Nm params 106is a table of parameters to apply to the jail, where each key in the table 107is a parameter name as a string and each value is a string that will be 108converted to the internal value type by 109.Xr jailparam_import 3 . 110.Nm flags 111is an optional integer representing the flag bits to apply for the operation. 112See the list of flags below. 113.El 114.Pp 115The 116.Nm flags 117arguments are an integer bitwise-or combination of one or more of the following 118flags: 119.Bl -tag -width XXXX 120.It Dv jail.CREATE 121Used with 122.Fn setparams 123to create a new jail. 124The jail must not already exist, unless combined with 125.Dv UPDATE . 126.It Dv jail.UPDATE 127Used with 128.Fn setparams 129to modify an existing jail. 130The jail must already exist, unless combined with 131.Dv CREATE . 132.It Dv jail.ATTACH 133Used with 134.Fn setparams 135in combination with 136.Dv CREATE 137or 138.Dv UPDATE 139to attach the current process to a jail. 140.It Dv jail.DYING 141Allow operating on a jail that is in the process of being removed. 142.El 143.Sh RETURN VALUES 144The 145.Fn getid 146and 147.Fn setparams 148functions return a jail identifier integer on success, or 149.Dv nil 150and an error message string if an error occurred. 151.Pp 152The 153.Fn getname 154function returns a jail name string on success, or 155.Dv nil 156and an error message string if an error occurred. 157.Pp 158The 159.Fn allparams 160function returns a list of parameter name strings on success, or 161.Dv nil 162and an error message string if an error occurred. 163.Pp 164The 165.Fn getparams 166function returns a jail identifier integer and a table of jail parameters 167with parameter name strings as keys and strings for values on success, or 168.Dv nil 169and an error message string if an error occurred. 170.Sh EXAMPLES 171Set the hostname of jail 172.Dq foo 173to 174.Dq foo.bar : 175.Bd -literal -offset indent 176local jail = require('jail') 177 178jid, err = jail.setparams("foo", {["host.hostname"]="foo.bar"}, 179 jail.UPDATE) 180if not jid then 181 error(err) 182end 183.Ed 184.Pp 185Retrieve the hostname of jail 186.Dq foo : 187.Bd -literal -offset indent 188local jail = require('jail') 189 190jid, res = jail.getparams("foo", {"host.hostname"}) 191if not jid then 192 error(res) 193end 194print(res["host.hostname"]) 195.Ed 196.Sh SEE ALSO 197.Xr jail 2 , 198.Xr jail 3 , 199.Xr jail 8 200.Sh HISTORY 201The 202.Nm jail 203Lua module for flua first appeared in 204.Fx 13.0 . 205.Sh AUTHORS 206.An Ryan Moeller , 207with inspiration from 208.Nx 209gpio(3lua), by 210.An Mark Balmer . 211