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.Dd July 8, 2022 26.Dt JAIL.CONF 5 27.Os 28.Sh NAME 29.Nm jail.conf 30.Nd configuration file for 31.Xr jail 8 32.Sh DESCRIPTION 33A 34.Xr jail 8 35configuration file consists of one or more jail definitions statements, 36and parameter or variable statements within those jail definitions. 37A jail definition statement looks something like a C compound statement. 38A parameter statement looks like a C assignment, 39including a terminating semicolon. 40.Pp 41The general syntax of a jail definition is: 42.Bd -literal -offset indent 43jailname { 44 parameter = "value"; 45 parameter = "value"; 46 ... 47} 48.Ed 49.Pp 50Each jail is required to have a 51.Va name 52at the front of its definition. 53This is used by 54.Xr jail 8 55to specify a jail on the command line and report the jail status, 56and is also passed to the kernel when creating the jail. 57.Ss Parameters 58A jail is defined by a set of named parameters, specified inside the 59jail definition. 60See 61.Xr jail 8 62for a list of jail parameters passed to the kernel, 63as well as internal parameters used when creating and removing jails. 64.Pp 65A typical parameter has a name and a value. 66Some parameters are boolean and may be specified with values of 67.Dq true 68or 69.Dq false , 70or as valueless shortcuts, with a 71.Dq no 72prefix indicating a false value. 73For example, these are equivalent: 74.Bd -literal -offset indent 75allow.mount = "false"; 76allow.nomount; 77.Ed 78.Pp 79Other parameters may have more than one value. 80A comma-separated list of values may be set in a single statement, 81or an existing parameter list may be appended to using 82.Dq += : 83.Bd -literal -offset indent 84ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3; 85 86ip4.addr = 10.1.1.1; 87ip4.addr += 10.1.1.2; 88ip4.addr += 10.1.1.3; 89.Ed 90.Pp 91Note the 92.Va name 93parameter is implicitly set to the name in the jail definition. 94.Ss String format 95Parameter values, including jail names, can be single tokens or quoted 96strings. 97A token is any sequence of characters that aren't considered special in 98the syntax of the configuration file (such as a semicolon or 99whitespace). 100If a value contains anything more than letters, numbers, dots, dashes 101and underscores, it is advisable to put quote marks around that value. 102Either single or double quotes may be used. 103.Pp 104Special characters may be quoted by preceding them with a backslash. 105Common C-style backslash character codes are also supported, including 106control characters and octal or hex ASCII codes. 107A backslash at the end of a line will ignore the subsequent newline and 108continue the string at the start of the next line. 109.Ss Variables 110A string may use shell-style variable substitution. 111A parameter or variable name preceded by a dollar sign, and possibly 112enclosed in braces, will be replaced with the value of that parameter or 113variable. 114For example, a jail's path may be defined in terms of its name or 115hostname: 116.Bd -literal -offset indent 117path = "/var/jail/$name"; 118 119path = "/var/jail/${host.hostname}"; 120.Ed 121.Pp 122Variable substitution occurs in unquoted tokens or in double-quoted 123strings, but not in single-quote strings. 124.Pp 125A variable is defined in the same way a parameter is, except that the 126variable name is preceded with a dollar sign: 127.Bd -literal -offset indent 128$parentdir = "/var/jail"; 129path = "$parentdir/$name"; 130.Ed 131.Pp 132The difference between parameters and variables is that variables are 133only used for substitution, while parameters are used both for 134substitution and for passing to the kernel. 135.Ss Wildcards 136A jail definition with a name of 137.Dq * 138is used to define wildcard parameters. 139Every defined jail will contain both the parameters from its own 140definition statement, as well as any parameters in a wildcard 141definition. 142.Pp 143Variable substitution is done on a per-jail basis, even when that 144substitution is for a parameter defined in a wildcard section. 145This is useful for wildcard parameters based on e.g. a jail's name. 146.Pp 147Later definitions in the configuration file supersede earlier ones, so a 148wildcard section placed before (above) a jail definition defines 149parameters that could be changed on a per-jail basis. 150Or a wildcard section placed after (below) all jails would contain 151parameters that always apply to every jail. 152Multiple wildcard statements are allowed, and wildcard parameters may 153also be specified outside of a jail definition statement. 154.Pp 155If hierarchical jails are defined, a partial-matching wildcard 156definition may be specified. 157For example, a definition with a name of 158.Dq foo.* 159would apply to jails with names like 160.Dq foo.bar 161and 162.Dq foo.bar.baz . 163.Ss Comments 164The configuration file may contain comments in the common C, C++, and 165shell formats: 166.Bd -literal -offset indent 167/* This is a C style comment. 168 * It may span multiple lines. 169 */ 170 171// This is a C++ style comment. 172 173# This is a shell style comment. 174.Ed 175.Pp 176Comments are legal wherever whitespace is allowed, i.e. anywhere except 177in the middle of a string or a token. 178.Sh FILES 179.Bl -tag -width "indent" -compact 180.It Pa /etc/jail.conf 181.It Pa /etc/jail.*.conf 182.It Pa /etc/jail.conf.d/*.conf 183.It Pa /usr/share/examples/jails/ 184.El 185.Sh EXAMPLES 186.Bd -literal 187# Typical static defaults: 188# Use the rc scripts to start and stop jails. Mount jail's /dev. 189exec.start = "/bin/sh /etc/rc"; 190exec.stop = "/bin/sh /etc/rc.shutdown jail"; 191exec.clean; 192mount.devfs; 193 194# Dynamic wildcard parameter: 195# Base the path off the jail name. 196path = "/var/jail/$name"; 197 198# A typical jail. 199foo { 200 host.hostname = "foo.com"; 201 ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3; 202} 203 204# This jail overrides the defaults defined above. 205bar { 206 exec.start = ''; 207 exec.stop = ''; 208 path = /; 209 mount.nodevfs; 210 persist; // Required because there are no processes 211} 212.Ed 213.Sh SEE ALSO 214.Xr jail_set 2 , 215.Xr rc.conf 5 , 216.Xr jail 8 , 217.Xr jls 8 218.Sh HISTORY 219The 220.Xr jail 8 221utility appeared in 222.Fx 4.0 . 223The 224.Nm 225file was added in 226.Fx 9.1 . 227.Sh AUTHORS 228.An -nosplit 229The jail feature was written by 230.An Poul-Henning Kamp 231for R&D Associates 232who contributed it to 233.Fx . 234.Pp 235.An James Gritton 236added the extensible jail parameters and configuration file. 237