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