FreeBSD Manual Pages
JAIL.CONF(5) File Formats Manual JAIL.CONF(5) NAME jail.conf -- configuration file for system jails DESCRIPTION The jail.conf file consists of one or more jail definitions statements for use by the jail(8) management program. A jail definition statement consists of a single word, the name of the jail, an opening curly brace, a list of at least two parameter assignments, and a closing curly brace. A parameter assignment consists of a single word, the pa- rameter name, an equals sign, a value enclosed in double quotes, and a terminating semicolon. The syntax of a jail definition is as follows: jailname { parameter = "value"; ... } This is used by jail(8) to specify a jail on the command line and re- port 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 re- moving 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 defi- nition. String format Parameter values, including jail names, can be single tokens or quoted strings. A token is any sequence of characters that are not 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 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 host- name: 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 parame- ters. Every defined jail will contain both the parameters from its own definition statement, as well as any parameters in a wildcard defini- tion. Variable substitution is done on a per-jail basis, even when that sub- stitution 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 pa- rameters that could be changed on a per-jail basis. Or a wildcard sec- tion placed after (below) all jails would contain parameters that al- ways apply to every jail. Multiple wildcard statements are allowed, and wildcard parameters may also be specified outside of a jail defini- tion statement. If hierarchical jails are defined, a partial-matching wildcard defini- tion 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". Includes A line of the form .include "filename"; will include another file (or files) in the configuration. The file- name should be either absolute, or relative to the configuration file's directory. It cannot contain variable expansions, but may contain glob(3) patterns. The included file must exist, though a filename glob may match zero or more files. This allows inclusion of any/all files in a directory, such as "/etc/jail.conf.d/*.conf", or conditional inclusion of a single file, such as "jail.foo[.]conf". 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 ex- cept in the middle of a string or a token. FILES /etc/jail.conf /etc/jail.*.conf /etc/jail.conf.d/*.conf /usr/share/examples/jails/ 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 jail"; 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 } # Include configurations from standard locations. .include "/etc/jail.conf.d/*.conf"; .include "/etc/jail.*.conf"; .include "/usr/local/etc/jail[.]conf"; .include "/usr/local/etc/jail.conf.d/*.conf"; .include "/usr/local/etc/jail.*.conf"; SEE ALSO jail(2), jail(3), jail(3lua), rc.conf(5), jail(8), jexec(8), jls(8), zfs-jail(8) The "Jails and Containers" chapter of the FreeBSD Handbook. 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 15.0 September 21, 2024 JAIL.CONF(5)
NAME | DESCRIPTION | FILES | EXAMPLES | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=jail.conf&manpath=FreeBSD+15.0-RELEASE+and+Ports>