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