JAIL.CONF(5) BSD File Formats Manual JAIL.CONF(5)
NAME
jail.conf -- configuration file for jail(8)
DESCRIPTION
A jail(8) configuration file consists of one or more jail definitions statements, and parameter or variable statements within those jail def-
initions. A jail definition statement looks something like a C compound statement. A parameter statement looks like a C assignment, includ-
ing a terminating semicolon.
The general syntax of a jail definition is:
jailname {
parameter = "value";
parameter = "value";
...
}
Each jail is required to have a name at the front of its definition. This is used by jail(8) to specify a jail on the command line and
report the jail status, and is also passed to the kernel when creating the jail.
Parameters
A jail is defined by a set of named parameters, specified inside the jail definition. See jail(8) for a list of jail parameters passed to
the kernel, as well as internal parameters used when creating and removing jails.
A typical parameter has a name and a value. Some parameters are boolean and may be specified with values of ``true'' or ``false'', or as
valueless shortcuts, with a ``no'' prefix indicating a false value. For example, these are equivalent:
allow.mount = "false";
allow.nomount;
Other parameters may have more than one value. A comma-separated list of values may be set in a single statement, or an existing parameter
list may be appended to using ``+='':
ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3;
ip4.addr = 10.1.1.1;
ip4.addr += 10.1.1.2;
ip4.addr += 10.1.1.3;
Note the name parameter is implicitly set to the name in the jail definition.
String format
Parameter values, including jail names, can be single tokens or quoted strings. A token is any sequence of characters that aren't considered
special in the syntax of the configuration file (such as a semicolon or whitespace). If a value contains anything more than letters, num-
bers, dots, dashes and underscores, it is advisable to put quote marks around that value. Either single or double quotes may be used.
Special characters may be quoted by preceding them with a backslash. Common C-style backslash character codes are also supported, including
control characters and octal or hex ASCII codes. A backslash at the end of a line will ignore the subsequent newline and continue the string
at the start of the next line.
Variables
A string may use shell-style variable substitution. A parameter or variable name preceded by a dollar sign, and possibly enclosed in braces,
will be replaced with the value of that parameter or variable. For example, a jail's path may be defined in terms of its name or hostname:
path = "/var/jail/$name";
path = "/var/jail/${host.hostname}";
Variable substitution occurs in unquoted tokens or in double-quoted strings, but not in single-quote strings.
A variable is defined in the same way a parameter is, except that the variable name is preceded with a dollar sign:
$parentdir = "/var/jail";
path = "$parentdir/$name";
The difference between parameters and variables is that variables are only used for substitution, while parameters are used both for substi-
tution and for passing to the kernel.
Wildcards
A jail definition with a name of ``*'' is used to define wildcard parameters. Every defined jail will contain both the parameters from its
own definition statement, as well as any parameters in a wildcard definition.
Variable substitution is done on a per-jail basis, even when that substitution is for a parameter defined in a wildcard section. This is
useful for wildcard parameters based on e.g. a jail's name.
Later definitions in the configuration file supersede earlier ones, so a wildcard section placed before (above) a jail definition defines
parameters that could be changed on a per-jail basis. Or a wildcard section placed after (below) all jails would contain parameters that
always apply to every jail. Multiple wildcard statements are allowed, and wildcard parameters may also be specified outside of a jail defi-
nition statement.
If hierarchical jails are defined, a partial-matching wildcard definition may be specified. For example, a definition with a name of
``foo.*'' would apply to jails with names like ``foo.bar'' and ``foo.bar.baz''.
Comments
The configuration file may contain comments in the common C, C++, and shell formats:
/* This is a C style comment.
* It may span multiple lines.
*/
// This is a C++ style comment.
# This is a shell style comment.
Comments are legal wherever whitespace is allowed, i.e. anywhere except in the middle of a string or a token.
EXAMPLES
# Typical static defaults:
# Use the rc scripts to start and stop jails. Mount jail's /dev.
exec.start = "/bin/sh /etc/rc";
exec.stop = "/bin/sh /etc/rc.shutdown";
exec.clean;
mount.devfs;
# Dynamic wildcard parameter:
# Base the path off the jail name.
path = "/var/jail/$name";
# A typical jail.
foo {
host.hostname = "foo.com";
ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3;
}
# This jail overrides the defaults defined above.
bar {
exec.start = '';
exec.stop = '';
path = /;
mount.nodevfs;
persist; // Required because there are no processes
}
SEE ALSO
jail_set(2), rc.conf(5), jail(8), jls(8)
HISTORY
The jail(8) utility appeared in FreeBSD 4.0. The jail.conf file was added in FreeBSD 9.1.
AUTHORS
The jail feature was written by Poul-Henning Kamp for R&D Associates http://www.rndassociates.com/ who contributed it to FreeBSD.
James Gritton added the extensible jail parameters and configuration file.
BSD
February 13, 2014 BSD