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