home | help 
JAIL.CONF(5)		       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  defini-
     tions.   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  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 defini-
     tion.

   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 spe-
     cial in the syntax of the configuration file (such as a semicolon or white-
     space).   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.  Com-
     mon 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  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 vari-
     able name is preceeded 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 substitution 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 substitu-
     tion 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 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 ALSO
     jail_set(2) 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.

FreeBSD 9.1			  May 23, 2012			    JAIL.CONF(5)
home | help