usr.sbin/jail/jail.conf.5

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