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