1227 lines
36 KiB
Groff
1227 lines
36 KiB
Groff
.\" Copyright (c) 2000, 2003 Robert N. M. Watson
|
|
.\" Copyright (c) 2008-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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd April 26, 2012
|
|
.Dt JAIL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm jail
|
|
.Nd "manage system jails"
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl dhilqv
|
|
.Op Fl J Ar jid_file
|
|
.Op Fl u Ar username
|
|
.Op Fl U Ar username
|
|
.Op Fl cmr
|
|
.Ar param Ns = Ns Ar value ...
|
|
.Op Cm command Ns = Ns Ar command ...
|
|
.Nm
|
|
.Op Fl dqv
|
|
.Op Fl f Ar conf_file
|
|
.Op Fl p Ar limit
|
|
.Op Fl cmr
|
|
.Op Ar jail
|
|
.Nm
|
|
.Op Fl qv
|
|
.Op Fl f Ar conf_file
|
|
.Op Fl rR
|
|
.Op Cm * | Ar jail ...
|
|
.Nm
|
|
.Op Fl dhilqv
|
|
.Op Fl J Ar jid_file
|
|
.Op Fl u Ar username
|
|
.Op Fl U Ar username
|
|
.Op Fl n Ar jailname
|
|
.Op Fl s Ar securelevel
|
|
.Op Ar path hostname [ Ar ip Ns [ Ns Ar ,... Ns ]] Ar command ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility creates new jails, or modifies or removes existing jails.
|
|
A jail is specified via parameters on the command line, or in the
|
|
.Xr jail.conf 5
|
|
file.
|
|
.Pp
|
|
At least one of the options
|
|
.Fl c ,
|
|
.Fl m
|
|
or
|
|
.Fl r
|
|
must be specified.
|
|
These options are used alone or in combination describe the operation to
|
|
perform:
|
|
.Bl -tag -width indent
|
|
.It Fl c
|
|
Create a new jail.
|
|
The jail
|
|
.Va jid
|
|
and
|
|
.Va name
|
|
parameters (if specified) on the command line,
|
|
or any jails
|
|
must not refer to an existing jail.
|
|
.It Fl m
|
|
Modify an existing jail.
|
|
One of the
|
|
.Va jid
|
|
or
|
|
.Va name
|
|
parameters must exist and refer to an existing jail.
|
|
Some parameters may not be changed on a running jail.
|
|
.It Fl r
|
|
Remove the
|
|
.Ar jail
|
|
specified by jid or name.
|
|
All jailed processes are killed, and all children of this jail are also
|
|
removed.
|
|
.It Fl rc
|
|
Restart an existing jail.
|
|
The jail is first removed and then re-created, as if
|
|
.Dq Nm Fl c
|
|
and
|
|
.Dq Nm Fl r
|
|
were run in succession.
|
|
.It Fl cm
|
|
Create a jail if it does not exist, or modify the jail if it does exist.
|
|
.It Fl mr
|
|
Modify an existing jail.
|
|
The jail may be restarted if necessary to modify parameters than could
|
|
not otherwise be changed.
|
|
.It Fl cmr
|
|
Create a jail if it doesn't exist, or modify (and possibly restart) the
|
|
jail if it does exist.
|
|
.El
|
|
.Pp
|
|
Other available options are:
|
|
.Bl -tag -width indent
|
|
.It Fl d
|
|
Allow making changes to a dying jail, equivalent to the
|
|
.Va allow.dying
|
|
parameter.
|
|
.It Fl f Ar conf_file
|
|
Use configuration file
|
|
.Ar conf_file
|
|
instead of the default
|
|
.Pa /etc/jail.conf .
|
|
.It Fl h
|
|
Resolve the
|
|
.Va host.hostname
|
|
parameter (or
|
|
.Va hostname )
|
|
and add all IP addresses returned by the resolver
|
|
to the list of addresses for this prison.
|
|
This is equivalent to the
|
|
.Va ip_hostname
|
|
parameter.
|
|
.It Fl i
|
|
Output (only) the jail identifier of the newly created jail(s).
|
|
This implies the
|
|
.Fl q
|
|
option.
|
|
.It Fl J Ar jid_file
|
|
Write a
|
|
.Ar jid_file
|
|
file, containing parameters used to start the jail.
|
|
.It Fl l
|
|
Run commands in a clean environment.
|
|
This is deprecated and is equivalent to the exec.clean parameter.
|
|
.It Fl n Ar jailname
|
|
Set the jail's name.
|
|
This is deprecated and is equivalent to the
|
|
.Va name
|
|
parameter.
|
|
.It Fl p Ar limit
|
|
Limit the number of commands from
|
|
.Va exec.*
|
|
that can run simultaneously.
|
|
.It Fl q
|
|
Suppress the message printed whenever a jail is created, modified or removed.
|
|
Only error messages will be printed.
|
|
.It Fl R
|
|
A variation of the
|
|
.Fl r
|
|
option that removes an existing jail without using the configuration file.
|
|
No removal-related parameters for this jail will be used - the jail will
|
|
simply be removed.
|
|
.It Fl s Ar securelevel
|
|
Set the
|
|
.Va kern.securelevel
|
|
MIB entry to the specified value inside the newly created jail.
|
|
This is deprecated and is equivalent to the
|
|
.Va securelevel
|
|
parameter.
|
|
.It Fl u Ar username
|
|
The user name from host environment as whom jailed commands should run.
|
|
This is deprecated and is equivalent to the
|
|
.Va exec.jail_user
|
|
and
|
|
.Va exec.system_jail_user
|
|
parameters.
|
|
.It Fl U Ar username
|
|
The user name from jailed environment as whom jailed commands should run.
|
|
This is deprecated and is equivalent to the
|
|
.Va exec.jail_user
|
|
parameter.
|
|
.It Fl v
|
|
Print a message on every operation, such as running commands and
|
|
mounting filesystems.
|
|
.El
|
|
.Pp
|
|
If no arguments are given after the options, the operation (except
|
|
remove) will be performed on all jails specified in the
|
|
.Xr jail.conf 5
|
|
file.
|
|
A single argument of a jail name will operate only on the specified jail.
|
|
The
|
|
.Fl r
|
|
and
|
|
.Fl R
|
|
options can also remove running jails that aren't in the
|
|
.Xr jail.conf 5
|
|
file, specified by name or jid.
|
|
.P
|
|
An argument of
|
|
.Dq *
|
|
is a wildcard that will operate on all jails, regardless of whether
|
|
they appear in
|
|
.Xr jail.conf 5 ;
|
|
this is the surest way for
|
|
.Fl r
|
|
to remove all jails.
|
|
If hierarchical jails exist, a partial-matching wildcard definition may
|
|
be specified.
|
|
For example, an argument of
|
|
.Dq foo.*
|
|
would apply to jails with names like
|
|
.Dq foo.bar
|
|
and
|
|
.Dq foo.bar.baz .
|
|
.Pp
|
|
A jail may be specified with parameters directly on the command line.
|
|
In this case, the
|
|
.Xr jail.conf 5
|
|
file will not be used.
|
|
For backward compatibility, the command line may also have four fixed
|
|
parameters, without names:
|
|
.Ar path ,
|
|
.Ar hostname ,
|
|
.Ar ip ,
|
|
and
|
|
.Ar command .
|
|
This mode will always create a new jail, and the
|
|
.Fl c
|
|
and
|
|
.Fl m
|
|
options don't apply (and must not exist).
|
|
.Ss Jail Parameters
|
|
Parameters in the
|
|
.Xr jail.conf 5
|
|
file, or on the command line, are generally in
|
|
.Dq name=value
|
|
form.
|
|
Some parameters are boolean, and do not have a value but are set by the
|
|
name alone with or without a
|
|
.Dq no
|
|
prefix, e.g.
|
|
.Va persist
|
|
or
|
|
.Va nopersist .
|
|
They can also be given the values
|
|
.Dq true
|
|
and
|
|
.Dq false .
|
|
Other partameters may have more than one value, specified as a
|
|
comma-separated list or with
|
|
.Dq +=
|
|
in the configuration file (see
|
|
.Xr jail.conf 5
|
|
for details).
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility recognizes two classes of parameters. There are the true jail
|
|
parameters that are passed to the kernel when the jail is created,
|
|
can be seen with
|
|
.Xr jls 8 ,
|
|
and can (usually) be changed with
|
|
.Dq Nm Fl m.
|
|
Then there are pseudo-parameters that are only used by
|
|
.Nm
|
|
itself.
|
|
.Pp
|
|
Jails have a set a core parameters, and kernel modules can add their own
|
|
jail parameters.
|
|
The current set of available parameters can be retrieved via
|
|
.Dq Nm sysctl Fl d Va security.jail.param .
|
|
Any parameters not set will be given default values, often based on the
|
|
current environment.
|
|
The core parameters are:
|
|
.Bl -tag -width indent
|
|
.It Va jid
|
|
The jail identifier.
|
|
This will be assigned automatically to a new jail (or can be explicitly
|
|
set), and can be used to identify the jail for later modification, or
|
|
for such commands as
|
|
.Xr jls 8
|
|
or
|
|
.Xr jexec 8 .
|
|
.It Va name
|
|
The jail name.
|
|
This is an arbitrary string that identifies a jail (except it may not
|
|
contain a
|
|
.Sq \&. ) .
|
|
Like the
|
|
.Va jid ,
|
|
it can be passed to later
|
|
.Nm
|
|
commands, or to
|
|
.Xr jls 8
|
|
or
|
|
.Xr jexec 8 .
|
|
If no
|
|
.Va name
|
|
is supplied, a default is assumed that is the same as the
|
|
.Va jid .
|
|
The
|
|
.Va name
|
|
parameter is implied by the
|
|
.Xr jail.conf 5
|
|
file format, and need not be explicitly set when using the configuration
|
|
file.
|
|
.It Va path
|
|
The directory which is to be the root of the prison.
|
|
Any commands run inside the prison, either by
|
|
.Nm
|
|
or from
|
|
.Xr jexec 8 ,
|
|
are run from this directory.
|
|
.It Va ip4.addr
|
|
A list of IPv4 addresses assigned to the prison.
|
|
If this is set, the jail is restricted to using only these addresses.
|
|
Any attempts to use other addresses fail, and attempts to use wildcard
|
|
addresses silently use the jailed address instead.
|
|
For IPv4 the first address given will be kept used as the source address
|
|
in case source address selection on unbound sockets cannot find a better
|
|
match.
|
|
It is only possible to start multiple jails with the same IP address,
|
|
if none of the jails has more than this single overlapping IP address
|
|
assigned to itself.
|
|
.It Va ip4.saddrsel
|
|
A boolean option to change the formerly mentioned behaviour and disable
|
|
IPv4 source address selection for the prison in favour of the primary
|
|
IPv4 address of the jail.
|
|
Source address selection is enabled by default for all jails and the
|
|
.Va ip4.nosaddrsel
|
|
setting of a parent jail is not inherited for any child jails.
|
|
.It Va ip4
|
|
Control the availability of IPv4 addresses.
|
|
Possible values are
|
|
.Dq inherit
|
|
to allow unrestricted access to all system addresses,
|
|
.Dq new
|
|
to restrict addresses via
|
|
.Va ip4.addr
|
|
above, and
|
|
.Dq disable
|
|
to stop the jail from using IPv4 entirely.
|
|
Setting the
|
|
.Va ip4.addr
|
|
parameter implies a value of
|
|
.Dq new .
|
|
.It Va ip6.addr , Va ip6.saddrsel , Va ip6
|
|
A set of IPv6 options for the prison, the counterparts to
|
|
.Va ip4.addr ,
|
|
.Va ip4.saddrsel
|
|
and
|
|
.Va ip4
|
|
above.
|
|
.It vnet
|
|
Create the prison with its own virtual network stack,
|
|
with its own network interfaces, addresses, routing table, etc.
|
|
The kernel must have been compiled with the
|
|
.Sy VIMAGE option
|
|
for this to be available.
|
|
Possible values are
|
|
.Dq inherit
|
|
to use the system network stack, possibly with restricted IP addresses,
|
|
and
|
|
.Dq new
|
|
to create a new network stack.
|
|
.It Va host.hostname
|
|
The hostname of the prison.
|
|
Other similar parameters are
|
|
.Va host.domainname ,
|
|
.Va host.hostuuid
|
|
and
|
|
.Va host.hostid .
|
|
.It Va host
|
|
Set the origin of hostname and related information.
|
|
Possible values are
|
|
.Dq inherit
|
|
to use the system information and
|
|
.Dq new
|
|
for the jail to use the information from the above fields.
|
|
Setting any of the above fields implies a value of
|
|
.Dq new .
|
|
.It Va securelevel
|
|
The value of the jail's
|
|
.Va kern.securelevel
|
|
sysctl.
|
|
A jail never has a lower securelevel than the default system, but by
|
|
setting this parameter it may have a higher one.
|
|
If the system securelevel is changed, any jail securelevels will be at
|
|
least as secure.
|
|
.It Va devfs_ruleset
|
|
The number of the devfs ruleset that is enforced for mounting devfs in
|
|
this jail.
|
|
A value of zero (default) means no ruleset is enforced.
|
|
Descendant jails inherit the parent jail's devfs ruleset enforcement.
|
|
Mounting devfs inside a jail is possible only if the
|
|
.Va allow.mount
|
|
and
|
|
.Va allow.mount.devfs
|
|
permissions are effective and
|
|
.Va enforce_statfs
|
|
is set to a value lower than 2.
|
|
Devfs rules and rulesets cannot be viewed or modified from inside a jail.
|
|
.Pp
|
|
NOTE: It is important that only appropriate device nodes in devfs be
|
|
exposed to a jail; access to disk devices in the jail may permit processes
|
|
in the jail to bypass the jail sandboxing by modifying files outside of
|
|
the jail.
|
|
See
|
|
.Xr devfs 8
|
|
for information on how to use devfs rules to limit access to entries
|
|
in the per-jail devfs.
|
|
A simple devfs ruleset for jails is available as ruleset #4 in
|
|
.Pa /etc/defaults/devfs.rules .
|
|
.It Va children.max
|
|
The number of child jails allowed to be created by this jail (or by
|
|
other jails under this jail).
|
|
This limit is zero by default, indicating the jail is not allowed to
|
|
create child jails.
|
|
See the
|
|
.Sx "Hierarchical Jails"
|
|
section for more information.
|
|
.It Va children.cur
|
|
The number of descendents of this jail, including its own child jails
|
|
and any jails created under them.
|
|
.It Va enforce_statfs
|
|
This determines which information processes in a jail are able to get
|
|
about mount points.
|
|
It affects the behaviour of the following syscalls:
|
|
.Xr statfs 2 ,
|
|
.Xr fstatfs 2 ,
|
|
.Xr getfsstat 2
|
|
and
|
|
.Xr fhstatfs 2
|
|
(as well as similar compatibility syscalls).
|
|
When set to 0, all mount points are available without any restrictions.
|
|
When set to 1, only mount points below the jail's chroot directory are
|
|
visible.
|
|
In addition to that, the path to the jail's chroot directory is removed
|
|
from the front of their pathnames.
|
|
When set to 2 (default), above syscalls can operate only on a mount-point
|
|
where the jail's chroot directory is located.
|
|
.It Va persist
|
|
Setting this boolean parameter allows a jail to exist without any
|
|
processes.
|
|
Normally, a command is run as part of jail creation, and then the jail
|
|
is destroyed as its last process exits.
|
|
A new jail must have either the
|
|
.Va persist
|
|
parameter or
|
|
.Va exec.start
|
|
or
|
|
.Va command
|
|
pseudo-parameter set.
|
|
.It Va cpuset.id
|
|
The ID of the cpuset associated with this jail (read-only).
|
|
.It Va dying
|
|
This is true if the jail is in the process of shutting down (read-only).
|
|
.It Va parent
|
|
The
|
|
.Va jid
|
|
of the parent of this jail, or zero if this is a top-level jail
|
|
(read-only).
|
|
.It Va allow.*
|
|
Some restrictions of the jail environment may be set on a per-jail
|
|
basis.
|
|
With the exception of
|
|
.Va allow.set_hostname ,
|
|
these boolean parameters are off by default.
|
|
.Bl -tag -width indent
|
|
.It Va allow.set_hostname
|
|
The jail's hostname may be changed via
|
|
.Xr hostname 1
|
|
or
|
|
.Xr sethostname 3 .
|
|
.It Va allow.sysvipc
|
|
A process within the jail has access to System V IPC primitives.
|
|
In the current jail implementation, System V primitives share a single
|
|
namespace across the host and jail environments, meaning that processes
|
|
within a jail would be able to communicate with (and potentially interfere
|
|
with) processes outside of the jail, and in other jails.
|
|
.It Va allow.raw_sockets
|
|
The prison root is allowed to create raw sockets.
|
|
Setting this parameter allows utilities like
|
|
.Xr ping 8
|
|
and
|
|
.Xr traceroute 8
|
|
to operate inside the prison.
|
|
If this is set, the source IP addresses are enforced to comply
|
|
with the IP address bound to the jail, regardless of whether or not
|
|
the
|
|
.Dv IP_HDRINCL
|
|
flag has been set on the socket.
|
|
Since raw sockets can be used to configure and interact with various
|
|
network subsystems, extra caution should be used where privileged access
|
|
to jails is given out to untrusted parties.
|
|
.It Va allow.chflags
|
|
Normally, privileged users inside a jail are treated as unprivileged by
|
|
.Xr chflags 2 .
|
|
When this parameter is set, such users are treated as privileged, and
|
|
may manipulate system file flags subject to the usual constraints on
|
|
.Va kern.securelevel .
|
|
.It Va allow.mount
|
|
privileged users inside the jail will be able to mount and unmount file
|
|
system types marked as jail-friendly.
|
|
The
|
|
.Xr lsvfs 1
|
|
command can be used to find file system types available for mount from
|
|
within a jail.
|
|
This permission is effective only if
|
|
.Va enforce_statfs
|
|
is set to a value lower than 2.
|
|
.It Va allow.mount.devfs
|
|
privileged users inside the jail will be able to mount and unmount the
|
|
devfs file system.
|
|
This permission is effective only together with
|
|
.Va allow.mount
|
|
and if
|
|
.Va enforce_statfs
|
|
is set to a value lower than 2.
|
|
Please consider restricting the devfs ruleset with the
|
|
.Va devfs_ruleset
|
|
option.
|
|
.It Va allow.mount.nullfs
|
|
privileged users inside the jail will be able to mount and unmount the
|
|
nullfs file system.
|
|
This permission is effective only together with
|
|
.Va allow.mount
|
|
and if
|
|
.Va enforce_statfs
|
|
is set to a value lower than 2.
|
|
.It Va allow.mount.procfs
|
|
privileged users inside the jail will be able to mount and unmount the
|
|
procfs file system.
|
|
This permission is effective only together with
|
|
.Va allow.mount
|
|
and if
|
|
.Va enforce_statfs
|
|
is set to a value lower than 2.
|
|
.It Va allow.mount.zfs
|
|
privileged users inside the jail will be able to mount and unmount the
|
|
ZFS file system.
|
|
This permission is effective only together with
|
|
.Va allow.mount
|
|
and if
|
|
.Va enforce_statfs
|
|
is set to a value lower than 2.
|
|
See
|
|
.Xr zfs 8
|
|
for information on how to configure the ZFS filesystem to operate from
|
|
within a jail.
|
|
.It Va allow.quotas
|
|
The prison root may administer quotas on the jail's filesystem(s).
|
|
This includes filesystems that the jail may share with other jails or
|
|
with non-jailed parts of the system.
|
|
.It Va allow.socket_af
|
|
Sockets within a jail are normally restricted to IPv4, IPv6, local
|
|
(UNIX), and route. This allows access to other protocol stacks that
|
|
have not had jail functionality added to them.
|
|
.El
|
|
.El
|
|
.Pp
|
|
There are pseudo-parameters that aren't passed to the kernel, but are
|
|
used by
|
|
.Nm
|
|
to set up the prison environment, often by running specified commands
|
|
when jails are created or removed.
|
|
The
|
|
.Va exec.*
|
|
command parameters are
|
|
.Xr sh 1
|
|
command lines that are run in either the system or prison environment.
|
|
They may be given multiple values, which run would the specified
|
|
commands in sequence.
|
|
All commands must succed (return a zero exit status), or the jail will
|
|
not be created or removed.
|
|
.Pp
|
|
The pseudo-parameters are:
|
|
.Bl -tag -width indent
|
|
.It Va exec.prestart
|
|
Command(s) to run in the system environment before a prison is created.
|
|
.It Va exec.start
|
|
Command(s) to run in the prison environment when a jail is created.
|
|
A typical command to run is
|
|
.Dq sh /etc/rc .
|
|
.It Va command
|
|
A synonym for
|
|
.Va exec.start
|
|
for use when specifying a prison directly on the command line.
|
|
Unlike other parameters whose value is a single string,
|
|
.Va command
|
|
uses the remainder of the
|
|
.Nm
|
|
command line as its own arguments.
|
|
.It Va exec.poststart
|
|
Command(s) to run in the system environment after a jail is created,
|
|
and after any
|
|
.Va exec.start
|
|
commands have completed.
|
|
.It Va exec.prestop
|
|
Command(s) to run in the system environment before a jail is removed.
|
|
.It Va exec.stop
|
|
Command(s) to run in the prison environment before a jail is removed,
|
|
and after any
|
|
.Va exec.prestop
|
|
commands have completed.
|
|
A typical command to run is
|
|
.Dq sh /etc/rc.shutdown .
|
|
.It Va exec.poststop
|
|
Command(s) to run in the system environment after a jail is removed.
|
|
.It Va exec.clean
|
|
Run commands in a clean environment.
|
|
The environment is discarded except for
|
|
.Ev HOME , SHELL , TERM
|
|
and
|
|
.Ev USER .
|
|
.Ev HOME
|
|
and
|
|
.Ev SHELL
|
|
are set to the target login's default values.
|
|
.Ev USER
|
|
is set to the target login.
|
|
.Ev TERM
|
|
is imported from the current environment.
|
|
The environment variables from the login class capability database for the
|
|
target login are also set.
|
|
.It Va exec.jail_user
|
|
The user to run commands as, when running in the prison environment.
|
|
The default is to run the commands as the current user.
|
|
.It Va exec.system_jail_user
|
|
This boolean option looks for the
|
|
.Va exec.jail_user
|
|
in the system
|
|
.Xr passwd 5
|
|
file, instead of in the prison's file.
|
|
.It Va exec.system_user
|
|
The user to run commands as, when running in the system environment.
|
|
The default is to run the commands as the current user.
|
|
.It Va exec.timeout
|
|
The maximum amount of time to wait for a command to complete.
|
|
If a command is still running after this many seconds have passed,
|
|
the jail not be created or removed.
|
|
.It Va exec.consolelog
|
|
A file to direct command output (stdout and stderr) to.
|
|
.It Va exec.fib
|
|
The FIB (routing table) to set when running commands inside the prison.
|
|
.It Va stop.timeout
|
|
The maximum amount of time to wait for a prison's processes to exit
|
|
after sending them a
|
|
.Dv SIGTERM
|
|
signal (which happens after the
|
|
.Va exec.stop commands have completed).
|
|
After this many seconds have passed, the prison will be removed, which
|
|
will kill any remaining processes.
|
|
If this is set to zero, no
|
|
.Dv SIGTERM
|
|
is sent and the prison is immediately removed.
|
|
The default is 10 seconds.
|
|
.It Va interface
|
|
A network interface to add the prison's IP addresses
|
|
.Va ( ip4.addr
|
|
and
|
|
.Va ip6.addr )
|
|
to.
|
|
An alias for each address will be added to the interface before the
|
|
prison is created, and will be removed from the interface after the
|
|
prison is removed.
|
|
.It Op Va ip4.addr
|
|
In addition to the IP addresses that are passed to the kernel, and
|
|
interface and/or a netmask may also be specified, in the form
|
|
.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar netmask .
|
|
If an interface is given before the IP address, an alias for the address
|
|
will be added to that interface, as it is with the
|
|
.Va interface
|
|
parameter. If a netmask in either dotted-quad or CIDR form is given
|
|
after IP address, it will be used when adding the IP alias.
|
|
.It Op Va ip6.addr
|
|
In addition to the IP addresses that are passed to the kernel,
|
|
and interface and/or a prefix may also be specified, in the form
|
|
.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar prefix .
|
|
.It Va vnet.interface
|
|
A network interface to give to a vnet-enabled jail after is it created.
|
|
The interface will automatically be returned when the jail is removed.
|
|
.It Va ip_hostname
|
|
Resolve the
|
|
.Va host.hostname
|
|
parameter and add all IP addresses returned by the resolver
|
|
to the list of addresses
|
|
.Va ( ip4.addr
|
|
or
|
|
.Va ip6.addr )
|
|
for this prison.
|
|
This may affect default address selection for outgoing IPv4 connections
|
|
of prisons.
|
|
The address first returned by the resolver for each address family
|
|
will be used as primary address.
|
|
.It Va mount
|
|
A filesystem to mount before creating the jail (and to unmount after
|
|
removing it), given as a single
|
|
.Xr fstab 5
|
|
line.
|
|
.It Va mount.fstab
|
|
An
|
|
.Xr fstab 5
|
|
format file containing filesystems to mount before creating a jail.
|
|
.It Va mount.devfs
|
|
Mount a
|
|
.Xr devfs
|
|
filesystem on the chrooted /dev directory, and apply the ruleset in the
|
|
.Va devfs_ruleset
|
|
parameter (or a default of ruleset 4: devfsrules_jail)
|
|
to restrict the devices visible inside the prison.
|
|
.It Va allow.dying
|
|
Allow making changes to a
|
|
.Va dying
|
|
jail.
|
|
.It Va depend
|
|
Specify a jail (or jails) that this jail depends on.
|
|
Any such jails must be fully created, up to the last
|
|
.Va exec.poststart
|
|
command, before any action will taken to create this jail.
|
|
When jails are removed the opposite is true:
|
|
this jail must be fully removed, up to the last
|
|
.Va exec.poststop
|
|
command, before the jail(s) it depends on are stopped.
|
|
.El
|
|
.Sh EXAMPLES
|
|
Jails are typically set up using one of two philosophies: either to
|
|
constrain a specific application (possibly running with privilege), or
|
|
to create a
|
|
.Dq "virtual system image"
|
|
running a variety of daemons and services.
|
|
In both cases, a fairly complete file system install of
|
|
.Fx
|
|
is
|
|
required, so as to provide the necessary command line tools, daemons,
|
|
libraries, application configuration files, etc.
|
|
However, for a virtual server configuration, a fair amount of
|
|
additional work is required so as to configure the
|
|
.Dq boot
|
|
process.
|
|
This manual page documents the configuration steps necessary to support
|
|
either of these steps, although the configuration steps may be
|
|
refined based on local requirements.
|
|
.Ss "Setting up a Jail Directory Tree"
|
|
To set up a jail directory tree containing an entire
|
|
.Fx
|
|
distribution, the following
|
|
.Xr sh 1
|
|
command script can be used:
|
|
.Bd -literal
|
|
D=/here/is/the/jail
|
|
cd /usr/src
|
|
mkdir -p $D
|
|
make world DESTDIR=$D
|
|
make distribution DESTDIR=$D
|
|
.Ed
|
|
.Pp
|
|
In many cases this example would put far more in the jail than needed.
|
|
In the other extreme case a jail might contain only one file:
|
|
the executable to be run in the jail.
|
|
.Pp
|
|
We recommend experimentation and caution that it is a lot easier to
|
|
start with a
|
|
.Dq fat
|
|
jail and remove things until it stops working,
|
|
than it is to start with a
|
|
.Dq thin
|
|
jail and add things until it works.
|
|
.Ss "Setting Up a Jail"
|
|
Do what was described in
|
|
.Sx "Setting Up a Jail Directory Tree"
|
|
to build the jail directory tree.
|
|
For the sake of this example, we will
|
|
assume you built it in
|
|
.Pa /data/jail/testjail ,
|
|
for a jail named
|
|
.Dq testjail .
|
|
Substitute below as needed with your
|
|
own directory, IP address, and hostname.
|
|
.Ss "Setting up the Host Environment"
|
|
First, you will want to set up your real system's environment to be
|
|
.Dq jail-friendly .
|
|
For consistency, we will refer to the parent box as the
|
|
.Dq "host environment" ,
|
|
and to the jailed virtual machine as the
|
|
.Dq "jail environment" .
|
|
Since jail is implemented using IP aliases, one of the first things to do
|
|
is to disable IP services on the host system that listen on all local
|
|
IP addresses for a service.
|
|
If a network service is present in the host environment that binds all
|
|
available IP addresses rather than specific IP addresses, it may service
|
|
requests sent to jail IP addresses if the jail did not bind the port.
|
|
This means changing
|
|
.Xr inetd 8
|
|
to only listen on the
|
|
appropriate IP address, and so forth.
|
|
Add the following to
|
|
.Pa /etc/rc.conf
|
|
in the host environment:
|
|
.Bd -literal -offset indent
|
|
sendmail_enable="NO"
|
|
inetd_flags="-wW -a 192.0.2.23"
|
|
rpcbind_enable="NO"
|
|
.Ed
|
|
.Pp
|
|
.Li 192.0.2.23
|
|
is the native IP address for the host system, in this example.
|
|
Daemons that run out of
|
|
.Xr inetd 8
|
|
can be easily set to use only the specified host IP address.
|
|
Other daemons
|
|
will need to be manually configured\(emfor some this is possible through
|
|
the
|
|
.Xr rc.conf 5
|
|
flags entries; for others it is necessary to modify per-application
|
|
configuration files, or to recompile the applications.
|
|
The following frequently deployed services must have their individual
|
|
configuration files modified to limit the application to listening
|
|
to a specific IP address:
|
|
.Pp
|
|
To configure
|
|
.Xr sshd 8 ,
|
|
it is necessary to modify
|
|
.Pa /etc/ssh/sshd_config .
|
|
.Pp
|
|
To configure
|
|
.Xr sendmail 8 ,
|
|
it is necessary to modify
|
|
.Pa /etc/mail/sendmail.cf .
|
|
.Pp
|
|
For
|
|
.Xr named 8 ,
|
|
it is necessary to modify
|
|
.Pa /etc/namedb/named.conf .
|
|
.Pp
|
|
In addition, a number of services must be recompiled in order to run
|
|
them in the host environment.
|
|
This includes most applications providing services using
|
|
.Xr rpc 3 ,
|
|
such as
|
|
.Xr rpcbind 8 ,
|
|
.Xr nfsd 8 ,
|
|
and
|
|
.Xr mountd 8 .
|
|
In general, applications for which it is not possible to specify which
|
|
IP address to bind should not be run in the host environment unless they
|
|
should also service requests sent to jail IP addresses.
|
|
Attempting to serve
|
|
NFS from the host environment may also cause confusion, and cannot be
|
|
easily reconfigured to use only specific IPs, as some NFS services are
|
|
hosted directly from the kernel.
|
|
Any third-party network software running
|
|
in the host environment should also be checked and configured so that it
|
|
does not bind all IP addresses, which would result in those services' also
|
|
appearing to be offered by the jail environments.
|
|
.Pp
|
|
Once
|
|
these daemons have been disabled or fixed in the host environment, it is
|
|
best to reboot so that all daemons are in a known state, to reduce the
|
|
potential for confusion later (such as finding that when you send mail
|
|
to a jail, and its sendmail is down, the mail is delivered to the host,
|
|
etc.).
|
|
.Ss "Configuring the Jail"
|
|
Start any jail for the first time without configuring the network
|
|
interface so that you can clean it up a little and set up accounts.
|
|
As
|
|
with any machine (virtual or not) you will need to set a root password, time
|
|
zone, etc.
|
|
Some of these steps apply only if you intend to run a full virtual server
|
|
inside the jail; others apply both for constraining a particular application
|
|
or for running a virtual server.
|
|
.Pp
|
|
Start a shell in the jail:
|
|
.Bd -literal -offset indent
|
|
jail -c path=/data/jail/testjail mount.devfs host.hostname=testhostname \\
|
|
ip4.addr=192.0.2.100 command=/bin/sh
|
|
.Ed
|
|
.Pp
|
|
Assuming no errors, you will end up with a shell prompt within the jail.
|
|
You can now run
|
|
.Pa /usr/sbin/sysinstall
|
|
and do the post-install configuration to set various configuration options,
|
|
or perform these actions manually by editing
|
|
.Pa /etc/rc.conf ,
|
|
etc.
|
|
.Pp
|
|
.Bl -bullet -offset indent -compact
|
|
.It
|
|
Configure
|
|
.Pa /etc/resolv.conf
|
|
so that name resolution within the jail will work correctly
|
|
.It
|
|
Run
|
|
.Xr newaliases 1
|
|
to quell
|
|
.Xr sendmail 8
|
|
warnings.
|
|
.It
|
|
Set a root password, probably different from the real host system
|
|
.It
|
|
Set the timezone
|
|
.It
|
|
Add accounts for users in the jail environment
|
|
.It
|
|
Install any packages the environment requires
|
|
.El
|
|
.Pp
|
|
You may also want to perform any package-specific configuration (web servers,
|
|
SSH servers, etc), patch up
|
|
.Pa /etc/syslog.conf
|
|
so it logs as you would like, etc.
|
|
If you are not using a virtual server, you may wish to modify
|
|
.Xr syslogd 8
|
|
in the host environment to listen on the syslog socket in the jail
|
|
environment; in this example, the syslog socket would be stored in
|
|
.Pa /data/jail/testjail/var/run/log .
|
|
.Pp
|
|
Exit from the shell, and the jail will be shut down.
|
|
.Ss "Starting the Jail"
|
|
You are now ready to restart the jail and bring up the environment with
|
|
all of its daemons and other programs.
|
|
Create an entry for the jail in
|
|
.Pa /etc/jail.conf :
|
|
.Bd -literal -offset indent
|
|
testjail {
|
|
path = /tmp/jail/testjail;
|
|
mount.devfs;
|
|
host.hostname = testhostname;
|
|
ip4.addr = 192.0.2.100;
|
|
interface = ed0;
|
|
exec.start = "/bin/sh /etc/rc";
|
|
exec.stop = "/bin/sh /etc/rc.shutdown";
|
|
}
|
|
.Ed
|
|
.Pp
|
|
To start a virtual server environment,
|
|
.Pa /etc/rc
|
|
is run to launch various daemons and services, and
|
|
.Pa /etc/rc.shutdown
|
|
is run to shut them down when the jail is removed.
|
|
If you are running a single application in the jail,
|
|
substitute the command used to start the application for
|
|
.Dq /bin/sh /etc/rc ;
|
|
there may be some script available to cleanly shut down the application,
|
|
or it may be sufficient to go without a stop command, and have
|
|
.Nm
|
|
send
|
|
.Dv SIGTERM
|
|
to the application.
|
|
.Pp
|
|
Start the jail by running:
|
|
.Bd -literal -offset indent
|
|
jail -c testjail
|
|
.Ed
|
|
.Pp
|
|
A few warnings may be produced; however, it should all work properly.
|
|
You should be able to see
|
|
.Xr inetd 8 ,
|
|
.Xr syslogd 8 ,
|
|
and other processes running within the jail using
|
|
.Xr ps 1 ,
|
|
with the
|
|
.Ql J
|
|
flag appearing beside jailed processes.
|
|
To see an active list of jails, use the
|
|
.Xr jls 8
|
|
utility.
|
|
You should also be able to
|
|
.Xr telnet 1
|
|
to the hostname or IP address of the jailed environment, and log
|
|
in using the accounts you created previously.
|
|
.Pp
|
|
It is possible to have jails started at boot time.
|
|
Please refer to the
|
|
.Dq jail_*
|
|
variables in
|
|
.Xr rc.conf 5
|
|
for more information.
|
|
.Ss "Managing the Jail"
|
|
Normal machine shutdown commands, such as
|
|
.Xr halt 8 ,
|
|
.Xr reboot 8 ,
|
|
and
|
|
.Xr shutdown 8 ,
|
|
cannot be used successfully within the jail.
|
|
To kill all processes from within a jail, you may use one of the
|
|
following commands, depending on what you want to accomplish:
|
|
.Bd -literal -offset indent
|
|
kill -TERM -1
|
|
kill -KILL -1
|
|
.Ed
|
|
.Pp
|
|
This will send the
|
|
.Dv SIGTERM
|
|
or
|
|
.Dv SIGKILL
|
|
signals to all processes in the jail - be careful not to run this from
|
|
the host environment!
|
|
Once all of the jail's processes have died, unless the jail was created
|
|
with the
|
|
.Va persist
|
|
parameter, the jail will be removed.
|
|
Depending on
|
|
the intended use of the jail, you may also want to run
|
|
.Pa /etc/rc.shutdown
|
|
from within the jail.
|
|
.Pp
|
|
To shut down the jail from the outside, simply remove it with
|
|
.Nm
|
|
.Ar -r ,
|
|
which will run any commands specified by
|
|
.Va exec.stop ,
|
|
and then send
|
|
.Dv SIGTERM
|
|
and eventually
|
|
.Dv SIGKILL
|
|
to any remaining jailed processes.
|
|
.Pp
|
|
The
|
|
.Pa /proc/ Ns Ar pid Ns Pa /status
|
|
file contains, as its last field, the name of the jail in which the
|
|
process runs, or
|
|
.Dq Li -
|
|
to indicate that the process is not running within a jail.
|
|
The
|
|
.Xr ps 1
|
|
command also shows a
|
|
.Ql J
|
|
flag for processes in a jail.
|
|
.Pp
|
|
You can also list/kill processes based on their jail ID.
|
|
To show processes and their jail ID, use the following command:
|
|
.Pp
|
|
.Dl "ps ax -o pid,jid,args"
|
|
.Pp
|
|
To show and then kill processes in jail number 3 use the following commands:
|
|
.Bd -literal -offset indent
|
|
pgrep -lfj 3
|
|
pkill -j 3
|
|
.Ed
|
|
or:
|
|
.Pp
|
|
.Dl "killall -j 3"
|
|
.Ss "Jails and File Systems"
|
|
It is not possible to
|
|
.Xr mount 8
|
|
or
|
|
.Xr umount 8
|
|
any file system inside a jail unless the file system is marked
|
|
jail-friendly, the jail's
|
|
.Va allow.mount
|
|
parameter is set and the jail's
|
|
.Va enforce_statfs
|
|
parameter is lower than 2.
|
|
.Pp
|
|
Multiple jails sharing the same file system can influence each other.
|
|
For example a user in one jail can fill the file system also
|
|
leaving no space for processes in the other jail.
|
|
Trying to use
|
|
.Xr quota 1
|
|
to prevent this will not work either as the file system quotas
|
|
are not aware of jails but only look at the user and group IDs.
|
|
This means the same user ID in two jails share the same file
|
|
system quota.
|
|
One would need to use one file system per jail to make this work.
|
|
.Ss "Sysctl MIB Entries"
|
|
The read-only entry
|
|
.Va security.jail.jailed
|
|
can be used to determine if a process is running inside a jail (value
|
|
is one) or not (value is zero).
|
|
.Pp
|
|
The variable
|
|
.Va security.jail.max_af_ips
|
|
determines how may address per address family a prison may have.
|
|
The default is 255.
|
|
.Pp
|
|
Some MIB variables have per-jail settings.
|
|
Changes to these variables by a jailed process do not effect the host
|
|
environment, only the jail environment.
|
|
These variables are
|
|
.Va kern.securelevel ,
|
|
.Va kern.hostname ,
|
|
.Va kern.domainname ,
|
|
.Va kern.hostid ,
|
|
and
|
|
.Va kern.hostuuid .
|
|
.Ss "Hierarchical Jails"
|
|
By setting a jail's
|
|
.Va children.max
|
|
parameter, processes within a jail may be able to create jails of their own.
|
|
These child jails are kept in a hierarchy, with jails only able to see and/or
|
|
modify the jails they created (or those jails' children).
|
|
Each jail has a read-only
|
|
.Va parent
|
|
parameter, containing the
|
|
.Va jid
|
|
of the jail that created it; a
|
|
.Va jid
|
|
of 0 indicates the jail is a child of the current jail (or is a top-level
|
|
jail if the current process isn't jailed).
|
|
.Pp
|
|
Jailed processes are not allowed to confer greater permissions than they
|
|
themselves are given, e.g. if a jail is created with
|
|
.Va allow.nomount ,
|
|
it is not able to create a jail with
|
|
.Va allow.mount
|
|
set.
|
|
Similarly, such restrictions as
|
|
.Va ip4.addr
|
|
and
|
|
.Va securelevel
|
|
may not be bypassed in child jails.
|
|
.Pp
|
|
A child jail may in turn create its own child jails if its own
|
|
.Va children.max
|
|
parameter is set (remember it is zero by default).
|
|
These jails are visible to and can be modified by their parent and all
|
|
ancestors.
|
|
.Pp
|
|
Jail names reflect this hierarchy, with a full name being an MIB-type string
|
|
separated by dots.
|
|
For example, if a base system process creates a jail
|
|
.Dq foo ,
|
|
and a process under that jail creates another jail
|
|
.Dq bar ,
|
|
then the second jail will be seen as
|
|
.Dq foo.bar
|
|
in the base system (though it is only seen as
|
|
.Dq bar
|
|
to any processes inside jail
|
|
.Dq foo ) .
|
|
Jids on the other hand exist in a single space, and each jail must have a
|
|
unique jid.
|
|
.Pp
|
|
Like the names, a child jail's
|
|
.Va path
|
|
appears relative to its creator's own
|
|
.Va path .
|
|
This is by virtue of the child jail being created in the chrooted
|
|
environment of the first jail.
|
|
.Sh SEE ALSO
|
|
.Xr killall 1 ,
|
|
.Xr lsvfs 1 ,
|
|
.Xr newaliases 1 ,
|
|
.Xr pgrep 1 ,
|
|
.Xr pkill 1 ,
|
|
.Xr ps 1 ,
|
|
.Xr quota 1 ,
|
|
.Xr jail_set 2 ,
|
|
.Xr jail.conf 5 ,
|
|
.Xr procfs 5 ,
|
|
.Xr rc.conf 5 ,
|
|
.Xr sysctl.conf 5 ,
|
|
.Xr chroot 8 ,
|
|
.Xr devfs 8 ,
|
|
.Xr halt 8 ,
|
|
.Xr inetd 8 ,
|
|
.Xr jexec 8 ,
|
|
.Xr jls 8 ,
|
|
.Xr mount 8 ,
|
|
.Xr named 8 ,
|
|
.Xr reboot 8 ,
|
|
.Xr rpcbind 8 ,
|
|
.Xr sendmail 8 ,
|
|
.Xr shutdown 8 ,
|
|
.Xr sysctl 8 ,
|
|
.Xr syslogd 8 ,
|
|
.Xr umount 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility appeared in
|
|
.Fx 4.0 .
|
|
Hierarchical/extensible jails were introduced in
|
|
.Fx 8.0 .
|
|
The configuration file was introduced in
|
|
.Fx 10.0 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The jail feature was written by
|
|
.An Poul-Henning Kamp
|
|
for R&D Associates
|
|
.Pa http://www.rndassociates.com/
|
|
who contributed it to
|
|
.Fx .
|
|
.Pp
|
|
.An Robert Watson
|
|
wrote the extended documentation, found a few bugs, added
|
|
a few new features, and cleaned up the userland jail environment.
|
|
.Pp
|
|
.An Bjoern A. Zeeb
|
|
added multi-IP jail support for IPv4 and IPv6 based on a patch
|
|
originally done by
|
|
.An Pawel Jakub Dawidek
|
|
for IPv4.
|
|
.Pp
|
|
.An James Gritton
|
|
added the extensible jail parameters, hierarchical jails,
|
|
and the configuration file.
|
|
.Sh BUGS
|
|
It might be a good idea to add an
|
|
address alias flag such that daemons listening on all IPs
|
|
.Pq Dv INADDR_ANY
|
|
will not bind on that address, which would facilitate building a safe
|
|
host environment such that host daemons do not impose on services offered
|
|
from within jails.
|
|
Currently, the simplest answer is to minimize services
|
|
offered on the host, possibly limiting it to services offered from
|
|
.Xr inetd 8
|
|
which is easily configurable.
|
|
.Sh NOTES
|
|
Great care should be taken when managing directories visible within the jail.
|
|
For example, if a jailed process has its current working directory set to a
|
|
directory that is moved out of the jail's chroot, then the process may gain
|
|
access to the file space outside of the jail.
|
|
It is recommended that directories always be copied, rather than moved, out
|
|
of a jail.
|