usr.sbin/jail/jail.conf.5

.\"-
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2012 James Gritton
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd September 21, 2024
.Dt JAIL.CONF 5
.Os
.Sh NAME
.Nm jail.conf
.Nd configuration file for system jails
.Sh DESCRIPTION
The
.Nm
file consists of one or more jail definitions statements for use by the
.Xr jail 8
management program.
A jail definition statement consists of a single word, the name of the jail,
an opening curly brace, a list of at least two parameter assignments,
and a closing curly brace.
A parameter assignment consists of a single word, the parameter name,
an equals sign, a value enclosed in double quotes, and a terminating semicolon.
.Pp
The syntax of a jail definition is as follows:
.Bd -unfilled
. Ar jailname Cm \&{
.Bd -unfilled -offset indent -compact
.Ar parameter Cm = Qq Ar value ;
\&...
.Ed
.Cm \&}
.Ed
.Pp
This is used by
.Xr jail 8
to specify a jail on the command line and report the jail status,
and is also passed to the kernel when creating the jail.
.Ss Parameters
A jail is defined by a set of named parameters, specified inside the
jail definition.
.Em See
.Xr jail 8
.Em for a list of jail parameters
passed to the kernel, as well as internal parameters used when creating and
removing jails.
.Pp
A typical parameter has a name and a value.
Some parameters are boolean and may be specified with values of
.Dq true
or
.Dq false ,
or as valueless shortcuts, with a
.Dq no
prefix indicating a false value.
For example, these are equivalent:
.Bd -literal -offset indent
allow.mount = "false";
allow.nomount;
.Ed
.Pp
Other parameters may have more than one value.
A comma-separated list of values may be set in a single statement,
or an existing parameter list may be appended to using
.Dq += :
.Bd -literal -offset indent
ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3;

ip4.addr = 10.1.1.1;
ip4.addr += 10.1.1.2;
ip4.addr += 10.1.1.3;
.Ed
.Pp
Note the
.Va name
parameter is implicitly set to the name in the jail definition.
.Ss String format
Parameter values, including jail names, can be single tokens or quoted
strings.
A token is any sequence of characters that are not considered special in
the syntax of the configuration file (such as a semicolon or
whitespace).
If a value contains anything more than letters, numbers, dots, dashes
and underscores, it is advisable to put quote marks around that value.
Either single or double quotes may be used.
.Pp
Special characters may be quoted by preceding them with a backslash.
Common C-style backslash character codes are also supported, including
control characters and octal or hex ASCII codes.
A backslash at the end of a line will ignore the subsequent newline and
continue the string at the start of the next line.
.Ss Variables
A string may use shell-style variable substitution.
A parameter or variable name preceded by a dollar sign, and possibly
enclosed in braces, will be replaced with the value of that parameter or
variable.
For example, a jail's path may be defined in terms of its name or
hostname:
.Bd -literal -offset indent
path = "/var/jail/$name";

path = "/var/jail/${host.hostname}";
.Ed
.Pp
Variable substitution occurs in unquoted tokens or in double-quoted
strings, but not in single-quote strings.
.Pp
A variable is defined in the same way a parameter is, except that the
variable name is preceded with a dollar sign:
.Bd -literal -offset indent
$parentdir = "/var/jail";
path = "$parentdir/$name";
.Ed
.Pp
The difference between parameters and variables is that variables are
only used for substitution, while parameters are used both for
substitution and for passing to the kernel.
.Ss Wildcards
A jail definition with a name of
.Dq *
is used to define wildcard parameters.
Every defined jail will contain both the parameters from its own
definition statement, as well as any parameters in a wildcard
definition.
.Pp
Variable substitution is done on a per-jail basis, even when that
substitution is for a parameter defined in a wildcard section.
This is useful for wildcard parameters based on e.g., a jail's name.
.Pp
Later definitions in the configuration file supersede earlier ones, so a
wildcard section placed before (above) a jail definition defines
parameters that could be changed on a per-jail basis.
Or a wildcard section placed after (below) all jails would contain
parameters that always apply to every jail.
Multiple wildcard statements are allowed, and wildcard parameters may
also be specified outside of a jail definition statement.
.Pp
If hierarchical jails are defined, a partial-matching wildcard
definition may be specified.
For example, a definition with a name of
.Dq foo.*
would apply to jails with names like
.Dq foo.bar
and
.Dq foo.bar.baz .
.Ss Includes
A line of the form
.Bd -literal -offset ident
\&.include "filename";
.Ed
.Pp
will include another file (or files) in the configuration.
The filename should be either absolute, or relative to the
configuration file's directory.
It cannot contain variable expansions, but may contain
.Xr glob 3
patterns.
.Pp
The included file must exist, though a filename glob may match zero or
more files.
This allows inclusion of any/all files in a directory, such as
.Dq Pa /etc/jail.conf.d/*.conf ,
or conditional inclusion of a single file, such as
.Dq Pa jail.foo[.]conf .
.Ss Comments
The configuration file may contain comments in the common C, C++, and
shell formats:
.Bd -literal -offset indent
/* This is a C style comment.
 * It may span multiple lines.
 */

// This is a C++ style comment.

#  This is a shell style comment.
.Ed
.Pp
Comments are legal wherever whitespace is allowed, i.e., anywhere except
in the middle of a string or a token.
.Sh FILES
.Bl -tag -width "indent" -compact
.It Pa /etc/jail.conf
.It Pa /etc/jail.*.conf
.It Pa /etc/jail.conf.d/*.conf
.It Pa /usr/share/examples/jails/
.El
.Sh EXAMPLES
.Bd -literal
# Typical static defaults:
# Use the rc scripts to start and stop jails.  Mount jail's /dev.
exec.start = "/bin/sh /etc/rc";
exec.stop = "/bin/sh /etc/rc.shutdown jail";
exec.clean;
mount.devfs;

# Dynamic wildcard parameter:
# Base the path off the jail name.
path = "/var/jail/$name";

# A typical jail.
foo {
	host.hostname = "foo.com";
	ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3;
}

# This jail overrides the defaults defined above.
bar {
	exec.start = '';
	exec.stop = '';
	path = /;
	mount.nodevfs;
	persist;	// Required because there are no processes
}

# Include configurations from standard locations.
\[char46]include "/etc/jail.conf.d/*.conf";
\[char46]include "/etc/jail.*.conf";
\[char46]include "/usr/local/etc/jail[.]conf";
\[char46]include "/usr/local/etc/jail.conf.d/*.conf";
\[char46]include "/usr/local/etc/jail.*.conf";
.Ed
.Sh SEE ALSO
.Xr jail 2 ,
.Xr jail 3 ,
.Xr jail 3lua ,
.Xr rc.conf 5 ,
.Xr jail 8 ,
.Xr jexec 8 ,
.Xr jls 8 ,
.Xr zfs-jail 8
.Pp
The
.Dq Jails and Containers
chapter of the
.%B FreeBSD Handbook .
.Sh HISTORY
The
.Xr jail 8
utility appeared in
.Fx 4.0 .
The
.Nm
file was added in
.Fx 9.1 .
.Sh AUTHORS
.An -nosplit
The jail feature was written by
.An Poul-Henning Kamp
for R&D Associates
who contributed it to
.Fx .
.Pp
.An James Gritton
added the extensible jail parameters and configuration file.