Initial work on the new jail(8). There are more features to add, and some

cleaning up to do on existing features, but this is pretty much what the
final product will look like.

1 files changed, 465 insertions, 220 deletions

diff --git a/usr.sbin/jail/jail.8 b/usr.sbin/jail/jail.8
index 893efd84..ab66c6f 100644
--- a/usr.sbin/jail/jail.8
+++ b/usr.sbin/jail/jail.8
@@ -1,6 +1,5 @@
-.\"
 .\" Copyright (c) 2000, 2003 Robert N. M. Watson
-.\" Copyright (c) 2008 James Gritton
+.\" Copyright (c) 2008, 2010 James Gritton
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -24,186 +23,261 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"
-.\" ----------------------------------------------------------------------------
-.\" "THE BEER-WARE LICENSE" (Revision 42):
-.\" <phk@FreeBSD.org> wrote this file.  As long as you retain this notice you
-.\" can do whatever you want with this stuff. If we meet some day, and you think
-.\" this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
-.\" ----------------------------------------------------------------------------
-.\"
 .\" $FreeBSD$
 .\"
-.Dd January 17, 2010
+.Dd October 20, 2010
 .Dt JAIL 8
 .Os
 .Sh NAME
 .Nm jail
-.Nd "create or modify a system jail"
+.Nd "manage system jails"
 .Sh SYNOPSIS
 .Nm
-.Op Fl dhi
+.Op Fl dhilqv
 .Op Fl J Ar jid_file
-.Op Fl l u Ar username | Fl U Ar username
-.Op Fl c | m
-.Op Ar parameter=value ...
+.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 hi
-.Op Fl n Ar jailname
+.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 Fl l u Ar username | Fl U Ar username
-.Op Ar path hostname [ip[,..]] command ...
-.Nm
-.Op Fl r Ar jail
+.Op Ar path hostname [ Ar ip Ns [ Ns Ar ,... Ns ]] Ar command ...
 .Sh DESCRIPTION
 The
 .Nm
-utility creates a new jail or modifies an existing jail, optionally
-imprisoning the current process (and future descendants) inside it.
+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
-The options are as follows:
+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.
+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
-.Va ip
-addresses 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.
-See the
-.Va ip4.addr
-and
-.Va ip6.addr
-parameters further down for details.
-.It Fl i
-Output the jail identifier of the newly created jail.
-.It Fl n Ar jailname
-Set the jail's name.
-This is deprecated and is equivalent to setting the
-.Va name
+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 jail identifier, path, hostname, IP and
-command used to start the jail.
+file, containing parameters used to start the jail.
 .It Fl l
-Run program in the 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.
+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 setting the
+This is deprecated and is equivalent to the
 .Va securelevel
 parameter.
 .It Fl u Ar username
-The user name from host environment as whom the
-.Ar command
-should run.
-.It Fl U Ar username
-The user name from jailed environment as whom the
-.Ar command
-should run.
-.It Fl c
-Create a new jail.
-The
-.Va jid
+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 name
-parameters (if specified) 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.
-.It Fl cm
-Create a jail if it does not exist, or modify a jail if it does exist.
-.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.
+.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
-At least one of the
-.Fl c ,
-.Fl m
-or
+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
-options must be specified.
-.Pp
-.Ar Parameters
-are listed in
-.Dq name=value
-form, following the options.
-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 .
-Any parameters not set will be given default values, often based on the
-current environment.
+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.  To prevent errors,
+this is the only 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
-The pseudo-parameter
-.Va command
-specifies that the current process should enter the new (or modified) jail,
-and run the specified command.
-It must be the last parameter specified, because it includes not only
-the value following the
-.Sq =
-sign, but also passes the rest of the arguments to the command.
-.Pp
-Instead of supplying named
-.Ar parameters ,
-four fixed parameters may be supplied in order on the command line:
+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 .
-As the
-.Va jid
-and
-.Va name
-parameters aren't in this list, this mode will always create a new jail, and
-the
+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
-Jails have a set a core parameters, and modules can add their own jail
-parameters.
+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
@@ -231,14 +305,21 @@ If no
 .Va name
 is supplied, a default is assumed that is the same as the
 .Va jid .
-.It Va path
-Directory which is to be the root of the prison.
 The
-.Va command
-(if any) is run from this directory, as are commands from
-.Xr jexec 8 .
+.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 comma-separated list of IPv4 addresses assigned to the prison.
+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.
@@ -252,7 +333,7 @@ assigned to itself.
 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 a
+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
@@ -277,8 +358,20 @@ A set of IPv6 options for the prison, the counterparts to
 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
-Hostname of the prison.
+The hostname of the prison.
 Other similar parameters are
 .Va host.domainname ,
 .Va host.hostuuid
@@ -307,7 +400,7 @@ other jails under this jail).
 This limit is zero by default, indicating the jail is not allowed to
 create child jails.
 See the
-.Va "Hierarchical Jails"
+.Sx "Hierarchical Jails"
 section for more information.
 .It Va children.cur
 The number of descendents of this jail, including its own child jails
@@ -332,10 +425,13 @@ 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 jail is destroyed as its last process exits.
+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
@@ -404,6 +500,176 @@ 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 run
+.Xr devfs 8
+to restrict the devices visible inside the prison.
+.It Va mount.devfs.ruleset
+The ruleset from
+.Xr devfs.rules 5
+to use when mounting a devfs filesystem.
+The default ruleset is
+.Dq devfsrules_jail .
+.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
@@ -421,7 +687,6 @@ 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.
-.Sh EXAMPLES
 .Ss "Setting up a Jail Directory Tree"
 To set up a jail directory tree containing an entire
 .Fx
@@ -434,20 +699,8 @@ cd /usr/src
 mkdir -p $D
 make world DESTDIR=$D
 make distribution DESTDIR=$D
-mount -t devfs devfs $D/dev
 .Ed
 .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 .
-.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.
@@ -465,8 +718,9 @@ Do what was described in
 to build the jail directory tree.
 For the sake of this example, we will
 assume you built it in
-.Pa /data/jail/192.0.2.100 ,
-named for the jailed IP address.
+.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"
@@ -563,8 +817,9 @@ inside the jail; others apply both for constraining a particular application
 or for running a virtual server.
 .Pp
 Start a shell in the jail:
+.Pp
 .Bd -literal -offset indent
-jail -c path=/data/jail/192.0.2.100 host.hostname=testhostname \\
+jail -c path=/data/jail/testjail mount.devfs host.hostname=testhostname \\
 	ip4.addr=192.0.2.100 command=/bin/sh
 .Ed
 .Pp
@@ -578,15 +833,6 @@ etc.
 .Pp
 .Bl -bullet -offset indent -compact
 .It
-Create an empty
-.Pa /etc/fstab
-to quell startup warnings about missing fstab (virtual server only)
-.It
-Disable the port mapper
-.Pa ( /etc/rc.conf :
-.Li rpcbind_enable="NO" )
-(virtual server only)
-.It
 Configure
 .Pa /etc/resolv.conf
 so that name resolution within the jail will work correctly
@@ -597,11 +843,6 @@ to quell
 .Xr sendmail 8
 warnings.
 .It
-Disable interface configuration to quell startup warnings about
-.Xr ifconfig 8
-.Pq Li network_interfaces=""
-(virtual server only)
-.It
 Set a root password, probably different from the real host system
 .It
 Set the timezone
@@ -619,36 +860,47 @@ 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/192.0.2.100/var/run/log .
+.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.
-If you are running a single application in the jail, substitute the
-command used to start the application for
-.Pa /etc/rc
-in the examples below.
+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.
-To do this, first bring up the
-virtual host interface, and then start the jail's
-.Pa /etc/rc
-script from within the jail.
+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
-ifconfig ed0 inet alias 192.0.2.100/32
-mount -t procfs proc /data/jail/192.0.2.100/proc
-jail -c path=/data/jail/192.0.2.100 host.hostname=testhostname \\
-	ip4.addr=192.0.2.100 command=/bin/sh /etc/rc
+jail -c testjail
 .Ed
 .Pp
-A few warnings will be produced, because most
-.Xr sysctl 8
-configuration variables cannot be set from within the jail, as they are
-global across all jails and the host environment.
-However, it should all
-work properly.
+A few warnings may be produced; however, it should all work properly.
 You should be able to see
 .Xr inetd 8 ,
 .Xr syslogd 8 ,
@@ -671,15 +923,6 @@ Please refer to the
 variables in
 .Xr rc.conf 5
 for more information.
-The
-.Xr rc 8
-jail script provides a flexible system to start/stop jails:
-.Bd -literal
-/etc/rc.d/jail start
-/etc/rc.d/jail stop
-/etc/rc.d/jail start myjail
-/etc/rc.d/jail stop myjail
-.Ed
 .Ss "Managing the Jail"
 Normal machine shutdown commands, such as
 .Xr halt 8 ,
@@ -687,9 +930,9 @@ Normal machine shutdown commands, such as
 and
 .Xr shutdown 8 ,
 cannot be used successfully within the jail.
-To kill all processes in a
-jail, you may log into the jail and, as root, use one of the following
-commands, depending on what you want to accomplish:
+To kill all processes from within a jail, you may use one of the
+following commands, depending on what you want to accomplish:
+.Pp
 .Bd -literal -offset indent
 kill -TERM -1
 kill -KILL -1
@@ -699,21 +942,27 @@ This will send the
 .Dv SIGTERM
 or
 .Dv SIGKILL
-signals to all processes in the jail from within the jail.
+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.
-To kill processes from outside the jail, use the
-.Xr jexec 8
-utility in conjunction with the one of the
-.Xr kill 1
-commands above.
-You may also remove the jail with
+.Pp
+To shut down the jail from the outside, simply remove it with
 .Nm
 .Ar -r ,
-which will killall the jail's processes with
-.Dv SIGKILL .
+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
@@ -831,7 +1080,7 @@ unique jid.
 .Pp
 Like the names, a child jail's
 .Va path
-is relative to its creator's own
+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.
@@ -843,12 +1092,12 @@ environment of the first jail.
 .Xr pkill 1 ,
 .Xr ps 1 ,
 .Xr quota 1 ,
-.Xr chroot 2 ,
 .Xr jail_set 2 ,
-.Xr jail_attach 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 ,
@@ -890,14 +1139,10 @@ originally done by
 for IPv4.
 .Pp
 .An James Gritton
-added the extensible jail parameters and hierarchical jails.
+added the extensible jail parameters, hierarchical jails,
+and the configuration file.
 .Sh BUGS
-Jail currently lacks the ability to allow access to
-specific jail information via
-.Xr ps 1
-as opposed to
-.Xr procfs 5 .
-Similarly, it might be a good idea to add an
+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