FreeBSD Manual Pages

JAIL.CONF(5) FreeBSD File Formats Manual JAIL.CONF(5)
NAMEjail.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 defi-
nitions. A jail definition statement looks something like a C compound
statement. A parameter statement looks like a C assignment, including 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 ker-
nel, 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 value-
less shortcuts, with a ``no'' prefix indicating a false value. For exam-
ple, 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 defini-
tion.
Stringformat
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, numbers,
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 vari-
able name preceded by a dollar sign, and possibly enclosed in braces,
will be replaced with the value of that parameter or variable. For exam-
ple, 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 substitu-
tion and for passing to the kernel.
Wildcards
A jail definition with a name of ``*'' is used to define wildcard parame-
ters. 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 substi-
tution 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 parame-
ters 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 definition 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 ALSOjail_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 who
contributed it to FreeBSD.
James Gritton added the extensible jail parameters and configuration
file.
FreeBSD Ports 11.2 February 13, 2014 FreeBSD Ports 11.2