Fix up a few documentation nits in jail(8), as well as improve the

instructions so as to reduce warnings during jail startup, etc.
Add a somewhat bolder warning recommending the use of
kern.jail.set_hostname to limit jail renamining.

1 files changed, 72 insertions, 24 deletions

diff --git a/usr.sbin/jail/jail.8 b/usr.sbin/jail/jail.8
index 6826c45..f6238e7 100644
--- a/usr.sbin/jail/jail.8
+++ b/usr.sbin/jail/jail.8
@@ -71,20 +71,49 @@ in the host environment:
 sendmail_enable="NO"
 inetd_flags="-wW -a 192.168.11.23"
 portmap_enable="NO"
+syslogd_flags="-ss"
 .Ed
 .Pp
 .Li 192.169.11.23
-is the native IP address for the host system, in this case.  It is possible
-to set up jails without using an exposed host IP, but in most virtual hosting
-environments, you won't want to do this.  Sendmail can be configured to
-listen to a specific IP, but this involves modifying
-.Pa /etc/sendmail.cf ,
-so it's easier to just disable it, and only have mail service within
-jails.  This is also more secure.  You will probably also want to disable
-the portmapper.  You can reboot to let this take effect, or manually
-kill/restart the daemons.
-.Pp
-Start your jail for the first time without configuring the network
+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--for some this is possible through
+the
+.Xr rc.conf 5
+flags entries, for others it is not possible without munging
+the per-application configuration files, or even recompiling.  For those
+applications that cannot specify the IP they run on, it is better to disable
+them, if possible.
+.Pp
+A number of daemons ship with the base system that may have problems when
+run from outside of a jail in a jail-centric environment.  This includes
+.Xr syslogd 8 ,
+.Xr sendmail 8 ,
+.Xr named 8 ,
+and
+.Xr portmap 8 .
+While sendmail and named can be configured to listen only on a specific
+IP using their configuration files, in most cases it is easier to simply
+run the daemons in jails only, and not in the host environment.  Syslogd
+cannot be configured to bind only a single IP, but can be configured to
+not bind a network port, using the ``-ss'' argument.  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.)
+.Pp
+Start any jails 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.  Before beginning, you may want to copy
@@ -104,11 +133,19 @@ You will end up with a shell prompt, assuming no errors, within the jail.  You
 can now run
 .Pa /stand/sysinstall
 and do the post-install configuration to set various configuration options,
-including:
+or perform these actions manually by editing rc.conf, etc.
 .Pp
 .Bl -bullet -offset indent -compact
 .It
-Disable the port mapper
+Create an empty /etc/fstab to quell startup warnings about missing fstab
+.It
+Disable the port mapper (rc.conf: portmap_enable="NO")
+.It
+Disable interface configuration to quell startup warnings about ifconfig
+(network_interfaces="")
+.It
+Configure /etc/resolv.conf
+so that name resolution within the jail will work correctly
 .It
 Set a root password, probably different from the real host system
 .It
@@ -119,17 +156,8 @@ Add accounts for users in the jail environment
 Install any packages that you think the environment requires
 .El
 .Pp
-Outside of
-.Xr sysinstall 8 ,
-you will probably also want to configure
-.Xr resolv.conf 5
-appropriately, as well as any package-specific configuration, such as
-Web servers, ssh, etc.  You'll probably want to replace the
-.Dq /dev/console
-line of
-.Pa /etc/syslog.conf
-with something more useful, such as UDP-based logging to a log host, or
-even the host environment's syslog.
+You may also want to perform any package-specific configuration (web servers,
+SSH servers, etc), patch up /etc/syslog.conf so it logs as you'd like, etc.
 .Pp
 Exit from the shell, and the jail will be shut down.
 .Ss Starting the Jail
@@ -138,6 +166,12 @@ all of its daemons and other programs.  To do this, first bring up the
 virtual host interface, and then start the jail's
 .Pa /etc/rc
 script from within the jail.
+.Pp
+NOTE: If you plan to allow untrusted users to have root access inside the
+jail, you may wish to consider setting the kern.jail.set_hostname_allowed to
+0.  Please see the management reasons why this is a good idea.  If you
+do decide to set this variable, it must be set before starting any jails,
+and once each boot.
 .Bd -literal -offset indent
 # ifconfig ed0 inet alias 192.168.11.100 netmask 255.255.255.255
 # mount -t procfs proc /data/jail/192.168.11.100/proc
@@ -222,3 +256,17 @@ who contributed it to FreeBSD.
 
 Robert Watson wrote the extended documentation, found a few bugs, added
 a few new features, and cleaned up the userland jail environment.
+.Sh BUGS
+Jail currently lacks strong management functionality, such as the ability
+to deliver signals to all processes in a jail, and 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
+address alias flag such that daemons listening on all IPs (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 simplist answer is to minimize services
+offered on the host, possibly limiting it to services offered from inetd
+which is easily configurable.