JAIL(3lua)

💖 JAIL(3lua) 💖

okay so bestie, welcome to jail(3lua) — the Lua binding to jail(3) and honestly? she's iconic. this is the page for the jail module, and by the end you're gonna be running FreeBSD jails from Lua like it's nothing. periodt.

---

✨ NAME ✨

attach, getid, getname, list, allparams, getparams, remove, setparams, CREATE, UPDATE, ATTACH, DYING — literally the whole squad, and they're all a Lua binding to jail(3). 🫶

---

🎀 SYNOPSIS 🎀

here's the vibe check, bestie — every single one of these, exactly as written:

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 🌸

so the jail module is a binding to the jail(3) library — it gives you a string-oriented interface for the jail_get(2) and jail_set(2) system calls. string-oriented means everything comes in and goes out as strings, which is lowkey the comfy way to live. 💅

• ok, err = jail.attach(jid|name) — attaches to the given jail. you identify it either by an integer jid or by the name. simple as that.
• jid, err = jail.getid(name) — grabs the jail identifier (jid) as an integer. name is the name of a jail or a jid in the form of a string, so she's flexible like that.
• name, err = jail.getname(jid) — gets the name of a jail as a string for the given jid (an integer). yes bestie, integer in, string out.
• iter, jail_obj = jail.list([params]) — returns an iterator over the 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. also, params may be omitted or an empty table, but not nil — do not come for her with a nil, she will not survive it. 😭

see "EXAMPLES" — there's a whole demo down there, go look.

• params, err = jail.allparams() — gets a list of all supported parameter names (as strings). for descriptions of the core jail parameters, see jail(8). ✨
• jid, res = jail.getparams(jid|name, params [, flags]) — gets 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 flags list below, bestie). only the DYING flag is valid to set here — just DYING, nobody else is invited.
• ok, err = jail.remove(jid|name) — removes the given jail, identified by an integer jid or the name. bye bestie 🦋
• jid, err = jail.setparams(jid|name, params [, flags]) — sets parameters for a given jail. this is the main character of the whole page, honestly: it's used to create, update, attach to, or destroy a jail. jid|name can either be the jid as an integer or the jid or name as a string. 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 jailparam_import(3). flags is an optional integer representing the flag bits to apply for the operation — again, see the flags list below.

🔥 the flags 🔥

the flags arguments are an integer bitwise-or combination of one or more of the following flags — pick your fighters and smash 'em together:

• 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. it's giving "ghost still in the group chat" energy 💀

---

⭐ RETURN VALUES ⭐

okay so here's what you actually get back, function by function:

• getid() and setparams() return a jail identifier integer on success, or nil and an error message string if an error occurred.
• getname() returns a jail name string on success, or nil and an error message string if an error occurred.
• allparams() returns a list of parameter name strings on success, or nil and an error message string if an error occurred.
• getparams() 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.
• list() returns an iterator over the list of running jails.
• attach() and remove() return true on success, or nil and an error message string if an error occurred.

so yeah — on success you get the good stuff, on failure you get nil plus a little error string telling you what went wrong. always check your returns, bestie, no cap. 🙈

---

🌈 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
    error(res)
end
print(res["host.hostname"])

iterate over jails on the system

local jail = require('jail')

-- 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) — go read those too, they're the extended universe. 📚

---

🧚 HISTORY 🧚

the jail Lua module for flua first appeared in FreeBSD 13.0. she's been serving looks since day one.

---

💜 AUTHORS 💜

Ryan Moeller, with inspiration from NetBSD gpio(3lua), by Mark Balmer. absolute legends, both of them. 🫶

---

and that's the whole page, bestie! this was the JAIL(3lua) manual, LOCAL section, from Debian, dated October 24, 2020 — reading it was giving study buddy energy and honestly? you ate. 💅✨🎀