JAIL(3)

💖 JAIL(3) — create and manage system jails 💖

okay bestie, welcome to the Library Functions Manual for JAIL(3) — we're doing jails, and yes, it's giving main-character system-call energy 🫶

🌸 NAME 🌸

jail_getid, jail_getname, jail_setv, jail_getv, jailparam_all, jailparam_init, jailparam_import, jailparam_import_raw, jailparam_set, jailparam_get, jailparam_export, and jailparam_free — the whole squad 💅. Their job? create and manage system jails. no cap.

🫶 LIBRARY 🫶

Jail Library (libjail, -ljail). Link it, bestie.

✨ SYNOPSIS ✨

#include <sys/param.h>
#include <sys/jail.h>
#include <jail.h>

extern char jail_errmsg[];

int
jail_getid(const char *name);

char *
jail_getname(int jid);

int
jail_setv(int flags, ...);

int
jail_getv(int flags, ...);

int
jailparam_all(struct jailparam **jpp);

int
jailparam_init(struct jailparam *jp, const char *name);

int
jailparam_import(struct jailparam *jp, const char *value);

int
jailparam_import_raw(struct jailparam *jp, void *value,
    size_t valuelen);

int
jailparam_set(struct jailparam *jp, unsigned njp, int flags);

int
jailparam_get(struct jailparam *jp, unsigned njp, int flags);

char *
jailparam_export(struct jailparam *jp);

void
jailparam_free(struct jailparam *jp, unsigned njp);

🦋 DESCRIPTION 🦋

The jail library is literally an interface to the jail_set(2) and jail_get(2) system calls, plus the security.jail.param MIB entries. It simplifies converting prison parameters between internal and string formats, so you can set and query prisons without knowing the parameter formats. iconic.

• jail_getid() — returns the JID of the jail identified by name, or -1 if the jail does not exist.
• jail_getname() — returns the name of the jail identified by jid, or NULL if the jail does not exist.
• jail_setv() — takes a null-terminated list of name and value strings, and passes it to jail_set(2).
• jail_getv() — takes a null-terminated list of name and value strings, and passes it to jail_get(2). It is the caller's responsibility to ensure that the value strings point to buffers large enough to hold the string representation of the returned parameters. yes, that means size your buffers, bestie 😭
• jailparam_all() — sets jpp to a list of all known jail parameters, and returns the number of parameters. The list should later be freed with jailparam_free() and free(3).
• jailparam_init() — clears a parameter record and copies the name to it. After use, it should be freed with jailparam_free().
• jailparam_import() — adds a value to a parameter record, converting it from a string to its native form.
• jailparam_import_raw() — adds a value without performing any conversion.
• jailparam_set() — passes a list of parameters to jail_set(2). The parameters are assumed to have been created with jailparam_init() and jailparam_import().
• jailparam_get() — passes a list of parameters to jail_get(2). The parameters are assumed to have been created with jailparam_init() or jailparam_list(), with one parameter (the key) having been given a value with jailparam_import().
• jailparam_export() — returns the string equivalent of a parameter value. The returned string should be freed after use.
• jailparam_free() — frees the stored names and values in a parameter list. If the list itself came from jailparam_all(), it should be freed as well.

🌈 RETURN VALUES 🌈

• jail_getid(), jail_setv(), jail_getv(), jailparam_set(), and jailparam_get() return a JID on success, or -1 on error.
• jail_getname() and jailparam_export() return a dynamically allocated string on success, or NULL on error.
• jailparam_all() returns the number of parameters on success, or -1 on error.
• jailparam_init(), jailparam_import(), and jailparam_import_raw() return 0 on success, or -1 on error.

Whenever an error is returned, errno is set, and the global string jail_errmsg contains a description of the error, possibly from jail_set(2) or jail_get(2). 🫶

🎀 EXAMPLES 🎀

Set the hostname of jail “foo” to “foo.bar”:

jail_setv(JAIL_UPDATE, "name", "foo", "host.hostname", "foo.bar",
    NULL);

OR:

struct jailparam params[2];
jailparam_init(&params[0], "name");
jailparam_import(&params[0], "foo");
jailparam_init(&params[1], "host.hostname");
jailparam_import(&params[1], "foo.bar");
jailparam_set(params, 2, JAIL_UPDATE);
jailparam_free(params, 2);

Retrieve the hostname of jail “foo”:

char hostname[MAXHOSTNAMELEN];
jail_getv(0, "name", "foo", "host.hostname", hostname, NULL);

OR:

struct jailparam params[2];
jailparam_init(&params[0], "name");
jailparam_import(&params[0], "foo");
jailparam_init(&params[1], "host.hostname");
jailparam_get(params, 2, 0);
hostname = jailparam_export(&params[1]);
jailparam_free(params, 2);
...
free(hostname);

💀 ERRORS 💀

The jail functions may return errors from jail_set(2), jail_get(2), malloc(3) or sysctl(3). In addition, the following errors are possible:

• [EINVAL] — A parameter value cannot be converted from the passed string to its internal form.
• [ENOENT] — The named parameter does not exist.
• [ENOENT] — A parameter is of an unknown type.

👑 SEE ALSO 👑

jail(2), sysctl(3), jail(3lua), jail(8) — go read the friends too, bestie 💜

🦋 HISTORY 🦋

The jail library first appeared in FreeBSD 8.0. periodt.

💅 AUTHORS 💅

James Gritton

---

xoxo, this edition is from Debian, dated August 31, 2010, and it's the JAIL(3) page — mwah 💋