1.\" Copyright (c) 2012 James Gritton 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd February 13, 2014 28.Dt JAIL.CONF 5 29.Os 30.Sh NAME 31.Nm jail.conf 32.Nd configuration file for 33.Xr jail 8 34.Sh DESCRIPTION 35A 36.Xr jail 8 37configuration file consists of one or more jail definitions statements, 38and parameter or variable statements within those jail definitions. 39A jail definition statement looks something like a C compound statement. 40A parameter statement looks like a C assignment, 41including a terminating semicolon. 42.Pp 43The general syntax of a jail definition is: 44.Bd -literal -offset indent 45jailname { 46 parameter = "value"; 47 parameter = "value"; 48 ... 49} 50.Ed 51.Pp 52Each jail is required to have a 53.Va name 54at the front of its definition. 55This is used by 56.Xr jail 8 57to specify a jail on the command line and report the jail status, 58and is also passed to the kernel when creating the jail. 59.Ss Parameters 60A jail is defined by a set of named parameters, specified inside the 61jail definition. 62See 63.Xr jail 8 64for a list of jail parameters passed to the kernel, 65as well as internal parameters used when creating and removing jails. 66.Pp 67A typical parameter has a name and a value. 68Some parameters are boolean and may be specified with values of 69.Dq true 70or 71.Dq false , 72or as valueless shortcuts, with a 73.Dq no 74prefix indicating a false value. 75For example, these are equivalent: 76.Bd -literal -offset indent 77allow.mount = "false"; 78allow.nomount; 79.Ed 80.Pp 81Other parameters may have more than one value. 82A comma-separated list of values may be set in a single statement, 83or an existing parameter list may be appended to using 84.Dq += : 85.Bd -literal -offset indent 86ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3; 87 88ip4.addr = 10.1.1.1; 89ip4.addr += 10.1.1.2; 90ip4.addr += 10.1.1.3; 91.Ed 92.Pp 93Note the 94.Va name 95parameter is implicitly set to the name in the jail definition. 96.Ss String format 97Parameter values, including jail names, can be single tokens or quoted 98strings. 99A token is any sequence of characters that aren't considered special in 100the syntax of the configuration file (such as a semicolon or 101whitespace). 102If a value contains anything more than letters, numbers, dots, dashes 103and underscores, it is advisable to put quote marks around that value. 104Either single or double quotes may be used. 105.Pp 106Special characters may be quoted by preceding them with a backslash. 107Common C-style backslash character codes are also supported, including 108control characters and octal or hex ASCII codes. 109A backslash at the end of a line will ignore the subsequent newline and 110continue the string at the start of the next line. 111.Ss Variables 112A string may use shell-style variable substitution. 113A parameter or variable name preceded by a dollar sign, and possibly 114enclosed in braces, will be replaced with the value of that parameter or 115variable. 116For example, a jail's path may be defined in terms of its name or 117hostname: 118.Bd -literal -offset indent 119path = "/var/jail/$name"; 120 121path = "/var/jail/${host.hostname}"; 122.Ed 123.Pp 124Variable substitution occurs in unquoted tokens or in double-quoted 125strings, but not in single-quote strings. 126.Pp 127A variable is defined in the same way a parameter is, except that the 128variable name is preceded with a dollar sign: 129.Bd -literal -offset indent 130$parentdir = "/var/jail"; 131path = "$parentdir/$name"; 132.Ed 133.Pp 134The difference between parameters and variables is that variables are 135only used for substitution, while parameters are used both for 136substitution and for passing to the kernel. 137.Ss Wildcards 138A jail definition with a name of 139.Dq * 140is used to define wildcard parameters. 141Every defined jail will contain both the parameters from its own 142definition statement, as well as any parameters in a wildcard 143definition. 144.Pp 145Variable substitution is done on a per-jail basis, even when that 146substitution is for a parameter defined in a wildcard section. 147This is useful for wildcard parameters based on e.g. a jail's name. 148.Pp 149Later definitions in the configuration file supersede earlier ones, so a 150wildcard section placed before (above) a jail definition defines 151parameters that could be changed on a per-jail basis. 152Or a wildcard section placed after (below) all jails would contain 153parameters that always apply to every jail. 154Multiple wildcard statements are allowed, and wildcard parameters may 155also be specified outside of a jail definition statement. 156.Pp 157If hierarchical jails are defined, a partial-matching wildcard 158definition may be specified. 159For example, a definition with a name of 160.Dq foo.* 161would apply to jails with names like 162.Dq foo.bar 163and 164.Dq foo.bar.baz . 165.Ss Comments 166The configuration file may contain comments in the common C, C++, and 167shell formats: 168.Bd -literal -offset indent 169/* This is a C style comment. 170 * It may span multiple lines. 171 */ 172 173// This is a C++ style comment. 174 175# This is a shell style comment. 176.Ed 177.Pp 178Comments are legal wherever whitespace is allowed, i.e. anywhere except 179in the middle of a string or a token. 180.Sh EXAMPLES 181.Bd -literal 182# Typical static defaults: 183# Use the rc scripts to start and stop jails. Mount jail's /dev. 184exec.start = "/bin/sh /etc/rc"; 185exec.stop = "/bin/sh /etc/rc.shutdown"; 186exec.clean; 187mount.devfs; 188 189# Dynamic wildcard parameter: 190# Base the path off the jail name. 191path = "/var/jail/$name"; 192 193# A typical jail. 194foo { 195 host.hostname = "foo.com"; 196 ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3; 197} 198 199# This jail overrides the defaults defined above. 200bar { 201 exec.start = ''; 202 exec.stop = ''; 203 path = /; 204 mount.nodevfs; 205 persist; // Required because there are no processes 206} 207.Ed 208.Sh SEE ALSO 209.Xr jail_set 2 , 210.Xr rc.conf 5 , 211.Xr jail 8 , 212.Xr jls 8 213.Sh HISTORY 214The 215.Xr jail 8 216utility appeared in 217.Fx 4.0 . 218The 219.Nm 220file was added in 221.Fx 9.1 . 222.Sh AUTHORS 223.An -nosplit 224The jail feature was written by 225.An Poul-Henning Kamp 226for R&D Associates 227.Pa http://www.rndassociates.com/ 228who contributed it to 229.Fx . 230.Pp 231.An James Gritton 232added the extensible jail parameters and configuration file. 233