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 .Dd September 5, 2023
  26 .Dt JAIL.CONF 5
  27 .Os
  28 .Sh NAME
  29 .Nm jail.conf
  30 .Nd configuration file for
  31 .Xr jail 8
  32 .Sh DESCRIPTION
  33 A
  34 .Xr jail 8
  35 configuration file consists of one or more jail definitions statements,
  36 and parameter or variable statements within those jail definitions.
  37 A jail definition statement looks something like a C compound statement.
  38 A parameter statement looks like a C assignment,
  39 including a terminating semicolon.
  40 .Pp
  41 The general syntax of a jail definition is:
  42 .Bd -literal -offset indent
  43 jailname {
  44         parameter = "value";
  45         parameter = "value";
  46         ...
  47 }
  48 .Ed
  49 .Pp
  50 Each jail is required to have a
  51 .Va name
  52 at the front of its definition.
  53 This is used by
  54 .Xr jail 8
  55 to specify a jail on the command line and report the jail status,
  56 and is also passed to the kernel when creating the jail.
  57 .Ss Parameters
  58 A jail is defined by a set of named parameters, specified inside the
  59 jail definition.
  60 .Em See
  61 .Xr jail 8
  62 .Em for a list of jail parameters
  63 passed to the kernel, as well as internal parameters used when creating and
  64 removing jails.
  65 .Pp
  66 A typical parameter has a name and a value.
  67 Some parameters are boolean and may be specified with values of
  68 .Dq true
  69 or
  70 .Dq false ,
  71 or as valueless shortcuts, with a
  72 .Dq no
  73 prefix indicating a false value.
  74 For example, these are equivalent:
  75 .Bd -literal -offset indent
  76 allow.mount = "false";
  77 allow.nomount;
  78 .Ed
  79 .Pp
  80 Other parameters may have more than one value.
  81 A comma-separated list of values may be set in a single statement,
  82 or an existing parameter list may be appended to using
  83 .Dq += :
  84 .Bd -literal -offset indent
  85 ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3;
  86
  87 ip4.addr = 10.1.1.1;
  88 ip4.addr += 10.1.1.2;
  89 ip4.addr += 10.1.1.3;
  90 .Ed
  91 .Pp
  92 Note the
  93 .Va name
  94 parameter is implicitly set to the name in the jail definition.
  95 .Ss String format
  96 Parameter values, including jail names, can be single tokens or quoted
  97 strings.
  98 A token is any sequence of characters that aren't considered special in
  99 the syntax of the configuration file (such as a semicolon or
 100 whitespace).
 101 If a value contains anything more than letters, numbers, dots, dashes
 102 and underscores, it is advisable to put quote marks around that value.
 103 Either single or double quotes may be used.
 104 .Pp
 105 Special characters may be quoted by preceding them with a backslash.
 106 Common C-style backslash character codes are also supported, including
 107 control characters and octal or hex ASCII codes.
 108 A backslash at the end of a line will ignore the subsequent newline and
 109 continue the string at the start of the next line.
 110 .Ss Variables
 111 A string may use shell-style variable substitution.
 112 A parameter or variable name preceded by a dollar sign, and possibly
 113 enclosed in braces, will be replaced with the value of that parameter or
 114 variable.
 115 For example, a jail's path may be defined in terms of its name or
 116 hostname:
 117 .Bd -literal -offset indent
 118 path = "/var/jail/$name";
 119
 120 path = "/var/jail/${host.hostname}";
 121 .Ed
 122 .Pp
 123 Variable substitution occurs in unquoted tokens or in double-quoted
 124 strings, but not in single-quote strings.
 125 .Pp
 126 A variable is defined in the same way a parameter is, except that the
 127 variable name is preceded with a dollar sign:
 128 .Bd -literal -offset indent
 129 $parentdir = "/var/jail";
 130 path = "$parentdir/$name";
 131 .Ed
 132 .Pp
 133 The difference between parameters and variables is that variables are
 134 only used for substitution, while parameters are used both for
 135 substitution and for passing to the kernel.
 136 .Ss Wildcards
 137 A jail definition with a name of
 138 .Dq *
 139 is used to define wildcard parameters.
 140 Every defined jail will contain both the parameters from its own
 141 definition statement, as well as any parameters in a wildcard
 142 definition.
 143 .Pp
 144 Variable substitution is done on a per-jail basis, even when that
 145 substitution is for a parameter defined in a wildcard section.
 146 This is useful for wildcard parameters based on e.g. a jail's name.
 147 .Pp
 148 Later definitions in the configuration file supersede earlier ones, so a
 149 wildcard section placed before (above) a jail definition defines
 150 parameters that could be changed on a per-jail basis.
 151 Or a wildcard section placed after (below) all jails would contain
 152 parameters that always apply to every jail.
 153 Multiple wildcard statements are allowed, and wildcard parameters may
 154 also be specified outside of a jail definition statement.
 155 .Pp
 156 If hierarchical jails are defined, a partial-matching wildcard
 157 definition may be specified.
 158 For example, a definition with a name of
 159 .Dq foo.*
 160 would apply to jails with names like
 161 .Dq foo.bar
 162 and
 163 .Dq foo.bar.baz .
 164 .Ss Includes
 165 A line of the form
 166 .Bd -literal -offset ident
 167 \&.include "filename";
 168 .Ed
 169 .Pp
 170 will include another file (or files) in the configuration.
 171 The filename should be either absolute, or relative to the
 172 configuration file's directory.  It cannot contain variable
 173 expansions, but may contain
 174 .Xr glob 3
 175 patterns.
 176 .Pp
 177 The included file must exist, though a filename glob may match zero or
 178 more files.  This allows inclusion of any/all files in a directory,
 179 such as
 180 .Dq /etc/jail.conf.d/*.conf ,
 181 or conditional inclusion of a single file, such as
 182 .Dq jail.foo[.]conf .
 183 .Ss Comments
 184 The configuration file may contain comments in the common C, C++, and
 185 shell formats:
 186 .Bd -literal -offset indent
 187 /* This is a C style comment.
 188  * It may span multiple lines.
 189  */
 190
 191 // This is a C++ style comment.
 192
 193 #  This is a shell style comment.
 194 .Ed
 195 .Pp
 196 Comments are legal wherever whitespace is allowed, i.e. anywhere except
 197 in the middle of a string or a token.
 198 .Sh FILES
 199 .Bl -tag -width "indent" -compact
 200 .It Pa /etc/jail.conf
 201 .It Pa /etc/jail.*.conf
 202 .It Pa /etc/jail.conf.d/*.conf
 203 .It Pa /usr/share/examples/jails/
 204 .El
 205 .Sh EXAMPLES
 206 .Bd -literal
 207 # Typical static defaults:
 208 # Use the rc scripts to start and stop jails.  Mount jail's /dev.
 209 exec.start = "/bin/sh /etc/rc";
 210 exec.stop = "/bin/sh /etc/rc.shutdown jail";
 211 exec.clean;
 212 mount.devfs;
 213
 214 # Dynamic wildcard parameter:
 215 # Base the path off the jail name.
 216 path = "/var/jail/$name";
 217
 218 # A typical jail.
 219 foo {
 220         host.hostname = "foo.com";
 221         ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3;
 222 }
 223
 224 # This jail overrides the defaults defined above.
 225 bar {
 226         exec.start = '';
 227         exec.stop = '';
 228         path = /;
 229         mount.nodevfs;
 230         persist;        // Required because there are no processes
 231 }
 232
 233 # Include configurations from standard locations.
 234 \[char46]include "/etc/jail.conf.d/*.conf";
 235 \[char46]include "/etc/jail.*.conf";
 236 \[char46]include "/usr/local/etc/jail[.]conf";
 237 \[char46]include "/usr/local/etc/jail.conf.d/*.conf";
 238 \[char46]include "/usr/local/etc/jail.*.conf";
 239 .Ed
 240 .Sh SEE ALSO
 241 .Xr jail_set 2 ,
 242 .Xr rc.conf 5 ,
 243 .Xr jail 8 ,
 244 .Xr jls 8
 245 .Sh HISTORY
 246 The
 247 .Xr jail 8
 248 utility appeared in
 249 .Fx 4.0 .
 250 The
 251 .Nm
 252 file was added in
 253 .Fx 9.1 .
 254 .Sh AUTHORS
 255 .An -nosplit
 256 The jail feature was written by
 257 .An Poul-Henning Kamp
 258 for R&D Associates
 259 who contributed it to
 260 .Fx .
 261 .Pp
 262 .An James Gritton
 263 added the extensible jail parameters and configuration file.