1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause 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.Dd October 24, 2020 28.Dt JAIL 3lua 29.Os 30.Sh NAME 31.Nm attach , 32.Nm getid , 33.Nm getname , 34.Nm list , 35.Nm allparams , 36.Nm getparams , 37.Nm remove , 38.Nm setparams , 39.Nm CREATE , 40.Nm UPDATE , 41.Nm ATTACH , 42.Nm DYING 43.Nd Lua binding to 44.Xr jail 3 45.Sh SYNOPSIS 46.Bd -literal 47local jail = require('jail') 48.Ed 49.Pp 50.Bl -tag -width XXXX -compact 51.It Dv ok, err = jail.attach(jid|name) 52.It Dv jid, err = jail.getid(name) 53.It Dv name, err = jail.getname(jid) 54.It Dv params, err = jail.allparams() 55.It Dv iter, jail_obj = jail.list([params]) 56.It Dv jid, res = jail.getparams(jid|name, params [, flags ] ) 57.It Dv ok, err = jail.remove(jid|name) 58.It Dv jid, err = jail.setparams(jid|name, params, flags ) 59.It Dv jail.CREATE 60.It Dv jail.UPDATE 61.It Dv jail.ATTACH 62.It Dv jail.DYING 63.El 64.Sh DESCRIPTION 65The 66.Nm jail 67module is a binding to the 68.Xr jail 3 69library. 70It provides a string-oriented interface for the 71.Xr jail_get 2 72and 73.Xr jail_set 2 74system calls. 75.Bl -tag -width XXXX 76.It Dv ok, err = jail.attach(jid|name) 77Attach to the given jail, identified by an integer 78.Fa jid 79or the 80.Fa name . 81.It Dv jid, err = jail.getid(name) 82Get the jail identifier 83.Pq jid 84as an integer. 85.Fa name 86is the name of a jail or a jid in the form of a string. 87.It Dv name, err = jail.getname(jid) 88Get the name of a jail as a string for the given 89.Fa jid 90.Pq an integer . 91.It Dv iter, jail_obj = jail.list([params]) 92Returns an iterator over running jails on the system. 93.Dv params 94is a list of parameters to fetch for each jail as we iterate. 95.Dv jid 96and 97.Dv name 98will always be returned, and may be omitted from 99.Dv params . 100Additionally, 101.Dv params 102may be omitted or an empty table, but not nil. 103.Pp 104See 105.Sx EXAMPLES . 106.It Dv params, err = jail.allparams() 107Get a list of all supported parameter names 108.Pq as strings . 109See 110.Xr jail 8 111for descriptions of the core jail parameters. 112.It Dv jid, res = jail.getparams(jid|name, params [, flags ] ) 113Get a table of the requested parameters for the given jail. 114.Nm jid|name 115can either be the jid as an integer or the jid or name as a string. 116.Nm params 117is a list of parameter names. 118.Nm flags 119is an optional integer representing the flag bits to apply for the operation. 120See the list of flags below. 121Only the 122.Dv DYING 123flag is valid to set. 124.It Dv ok, err = jail.remove(jid|name) 125Remove the given jail, identified by an integer 126.Fa jid 127or the 128.Fa name . 129.It Dv jid, err = jail.setparams(jid|name, params [, flags ] ) 130Set parameters for a given jail. 131This is used to create, update, attach to, or destroy a jail. 132.Nm jid|name 133can either be the jid as an integer or the jid or name as a string. 134.Nm params 135is a table of parameters to apply to the jail, where each key in the table 136is a parameter name as a string and each value is a string that will be 137converted to the internal value type by 138.Xr jailparam_import 3 . 139.Nm flags 140is an optional integer representing the flag bits to apply for the operation. 141See the list of flags below. 142.El 143.Pp 144The 145.Nm flags 146arguments are an integer bitwise-or combination of one or more of the following 147flags: 148.Bl -tag -width XXXX 149.It Dv jail.CREATE 150Used with 151.Fn setparams 152to create a new jail. 153The jail must not already exist, unless combined with 154.Dv UPDATE . 155.It Dv jail.UPDATE 156Used with 157.Fn setparams 158to modify an existing jail. 159The jail must already exist, unless combined with 160.Dv CREATE . 161.It Dv jail.ATTACH 162Used with 163.Fn setparams 164in combination with 165.Dv CREATE 166or 167.Dv UPDATE 168to attach the current process to a jail. 169.It Dv jail.DYING 170Allow operating on a jail that is in the process of being removed. 171.El 172.Sh RETURN VALUES 173The 174.Fn getid 175and 176.Fn setparams 177functions return a jail identifier integer on success, or 178.Dv nil 179and an error message string if an error occurred. 180.Pp 181The 182.Fn getname 183function returns a jail name string on success, or 184.Dv nil 185and an error message string if an error occurred. 186.Pp 187The 188.Fn allparams 189function returns a list of parameter name strings on success, or 190.Dv nil 191and an error message string if an error occurred. 192.Pp 193The 194.Fn getparams 195function returns a jail identifier integer and a table of jail parameters 196with parameter name strings as keys and strings for values on success, or 197.Dv nil 198and an error message string if an error occurred. 199.Pp 200The 201.Fn list 202function returns an iterator over the list of running jails. 203.Pp 204The 205.Fn attach 206and 207.Fn remove 208functions return true on success, or 209.Dv nil 210and an error message string if an error occurred. 211.Sh EXAMPLES 212Set the hostname of jail 213.Dq foo 214to 215.Dq foo.bar : 216.Bd -literal -offset indent 217local jail = require('jail') 218 219jid, err = jail.setparams("foo", {["host.hostname"]="foo.bar"}, 220 jail.UPDATE) 221if not jid then 222 error(err) 223end 224.Ed 225.Pp 226Retrieve the hostname of jail 227.Dq foo : 228.Bd -literal -offset indent 229local jail = require('jail') 230 231jid, res = jail.getparams("foo", {"host.hostname"}) 232if not jid then 233 error(res) 234end 235print(res["host.hostname"]) 236.Ed 237.Pp 238Iterate over jails on the system: 239.Bd -literal -offset indent 240local jail = require('jail') 241 242-- Recommended: just loop over it 243for jparams in jail.list() do 244 print(jparams["jid"] .. " = " .. jparams["name"]) 245end 246 247-- Request path and hostname, too 248for jparams in jail.list({"path", "host.hostname"}) do 249 print(jparams["host.hostname"] .. " mounted at " .. jparams["path"]) 250end 251 252-- Raw iteration protocol 253local iter, jail_obj = jail.list() 254 255-- Request the first params 256local jparams = jail_obj:next() 257while jparams do 258 print(jparams["jid"] .. " = " .. jparams["name"]) 259 -- Subsequent calls may return nil 260 jparams = jail_obj:next() 261end 262.Ed 263.Sh SEE ALSO 264.Xr jail 2 , 265.Xr jail 3 , 266.Xr jail 8 267.Sh HISTORY 268The 269.Nm jail 270Lua module for flua first appeared in 271.Fx 13.0 . 272.Sh AUTHORS 273.An Ryan Moeller , 274with inspiration from 275.Nx 276gpio(3lua), by 277.An Mark Balmer . 278