---
name: "jail"
section: "3lua"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/jail/3lua"
---

# jail(3lua)

Lua binding to jail(3)

## NAME

**attach**, **getid**, **getname**, **list**, **allparams**, **getparams**, **remove**, **setparams**, **CREATE**, **UPDATE**, **ATTACH**, **DYING** – Lua binding to [jail(3)](/jail/3.md)

## 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)](/jail/3.md) library. It provides a string-oriented interface for the [jail\_get(2)](/jail_get/2.md) and [jail\_set(2)](/jail_set/2.md) 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)](/jail/8.md) 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*.

- jid, err = jail.setparams(jid\|name, params \[, flags\])

  Set parameters for a given jail. This is 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)](/jailparam_import/3.md). **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
    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/2.md), [jail(3)](/jail/3.md), [jail(8)](/jail/8.md)

## 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.