FreeBSD manual

download PDF document: jail.3lua.pdf

JAIL(3lua) Lua Library Functions Manual JAIL(3lua) NAME attach, getid, getname, list, allparams, getparams, remove, setparams, CREATE, UPDATE, ATTACH, DYING - Lua binding to jail(3) SYNOPSIS local jail = require('jail') ok, err = jail.attach(jid|name) jid, err = jail.getid(name) name, err = jail.getname(jid) params, err = jail.allparams() iter, jail_obj = jail.list([params]) jid, res = jail.getparams(jid|name, params [, flags]) ok, err = jail.remove(jid|name) jid, err = jail.setparams(jid|name, params, flags) jail.CREATE jail.UPDATE jail.ATTACH jail.DYING DESCRIPTION The jail module is a binding to the jail(3) library. It provides a string-oriented interface for the jail_get(2) and jail_set(2) system calls. ok, err = jail.attach(jid|name) Attach to the given jail, identified by an integer jid or the name. jid, err = jail.getid(name) Get the jail identifier (jid) as an integer. name is the name of a jail or a jid in the form of a string. name, err = jail.getname(jid) Get the name of a jail as a string for the given jid (an integer). iter, jail_obj = jail.list([params]) Returns an iterator over running jails on the system. params is a list of parameters to fetch for each jail as we iterate. jid and name will always be returned, and may be omitted from params. Additionally, params may be omitted or an empty table, but not nil. See EXAMPLES. params, err = jail.allparams() Get a list of all supported parameter names (as strings). See jail(8) for descriptions of the core jail parameters. jid, res = jail.getparams(jid|name, params [, flags]) Get a table of the requested parameters for the given jail. jid|name can either be the jid as an integer or the jid or name as a string. params is a list of parameter names. flags is an optional integer representing the flag bits to apply for the operation. See the list of flags below. Only the DYING flag is valid to set. ok, err = jail.remove(jid|name) Remove the given jail, identified by an integer jid or the name. converted to the internal value type by jailparam_import(3). flags is an optional integer representing the flag bits to apply for the operation. See the list of flags below. The flags arguments are an integer bitwise-or combination of one or more of the following flags: jail.CREATE Used with setparams() to create a new jail. The jail must not already exist, unless combined with UPDATE. jail.UPDATE Used with setparams() to modify an existing jail. The jail must already exist, unless combined with CREATE. jail.ATTACH Used with setparams() in combination with CREATE or UPDATE to attach the current process to a jail. jail.DYING Allow operating on a jail that is in the process of being removed. RETURN VALUES The getid() and setparams() functions return a jail identifier integer on success, or nil and an error message string if an error occurred. The getname() function returns a jail name string on success, or nil and an error message string if an error occurred. The allparams() function returns a list of parameter name strings on success, or nil and an error message string if an error occurred. The 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 nil and an error message string if an error occurred. The list() function returns an iterator over the list of running jails. The attach() and remove() functions return true on success, or nil and an error message string if an error occurred. EXAMPLES Set the hostname of jail "foo" to "foo.bar": local jail = require('jail') jid, err = jail.setparams("foo", {["host.hostname"]="foo.bar"}, jail.UPDATE) if not jid then error(err) end Retrieve the hostname of jail "foo": local jail = require('jail') jid, res = jail.getparams("foo", {"host.hostname"}) if not jid then -- Recommended: just loop over it for jparams in jail.list() do print(jparams["jid"] .. " = " .. jparams["name"]) end -- Request path and hostname, too for jparams in jail.list({"path", "host.hostname"}) do print(jparams["host.hostname"] .. " mounted at " .. jparams["path"]) end -- Raw iteration protocol local iter, jail_obj = jail.list() -- Request the first params local jparams = jail_obj:next() while jparams do print(jparams["jid"] .. " = " .. jparams["name"]) -- Subsequent calls may return nil jparams = jail_obj:next() end SEE ALSO jail(2), jail(3), jail(8) HISTORY The jail Lua module for flua first appeared in FreeBSD 13.0. AUTHORS Ryan Moeller, with inspiration from NetBSD gpio(3lua), by Mark Balmer. FreeBSD 14.0-RELEASE-p11 October 24, 2020 FreeBSD 14.0-RELEASE-p11