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.
|