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