Attachment 167190 Details for Bug 207344 – Fixed errors in a paragraph of Jails

[patch] Fixed errors in a paragraph of Jails

fix2errors.diff (text/plain), 124.64 KB, created by harrij15 on 2016-02-19 18:12:34 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: harrij15

Created: 2016-02-19 18:12:34 UTC

Size: 124.64 KB

patch

obsolete

>Index: chapter.xml
>===================================================================
>--- chapter.xml	(revision 48199)
>+++ chapter.xml	(working copy)
>@@ -1,1611 +1,1611 @@
>-<?xml version="1.0" encoding="iso-8859-1"?>
>-
>-<chapter xmlns="http://docbook.org/ns/docbook"
>-  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
>-  xml:id="jails">
>-  <info>
>-    <title>Jails</title>
>-
>-    <authorgroup>
>-      <author><personname><firstname>Matteo</firstname><surname>Riondato</surname></personname><contrib>Contributed
>-	by </contrib></author>
>-    </authorgroup>
>-  </info>
>-
>-  <indexterm><primary>jails</primary></indexterm>
>-
>-  <sect1 xml:id="jails-synopsis">
>-    <title>Synopsis</title>
>-
>-    <para>Since system administration is a difficult task, many tools
>-      have been developed to make life easier for the administrator.
>-      These tools often enhance the way systems are installed,
>-      configured, and maintained.  One of the tools which can be used
>-      to enhance the security of a &os; system is
>-      <firstterm>jails</firstterm>.  Jails have been available since
>-      &os;&nbsp;4.X and continue to be enhanced in their usefulness,
>-      performance, reliability, and security.</para>
>-
>-    <para>Jails build upon the &man.chroot.2; concept, which is used
>-      to change the root directory of a set of processes, creating a
>-      safe environment, separate from the rest of the system.
>-      Processes created in the chrooted environment can not access
>-      files or resources outside of it.  For that reason, compromising
>-      a service running in a chrooted environment should not allow the
>-      attacker to compromise the entire system.  However, a chroot has
>-      several limitations.  It is suited to easy tasks which do not
>-      require much flexibility or complex, advanced features.  Over
>-      time many ways have been found to escape from a chrooted
>-      environment, making it a less than ideal solution for securing
>-      services.</para>
>-
>-    <para>Jails improve on the concept of the traditional chroot
>-      environment in several ways.  In a traditional chroot
>-      environment, processes are only limited in the part of the file
>-      system they can access.  The rest of the system resources,
>-      system users, running processes, and the networking subsystem
>-      are shared by the chrooted processes and the processes of the
>-      host system.  Jails expand this model by virtualizing access to
>-      the file system, the set of users, and the networking subsystem.
>-      More fine-grained controls are available for tuning the access
>-      of a jailed environment.  Jails can be considered as a type of
>-      operating system-level virtualization.</para>
>-
>-    <para>A jail is characterized by four elements:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>A directory subtree: the starting point from which a
>-	  jail is entered.  Once inside the jail, a process is not
>-	  permitted to escape outside of this subtree.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>A hostname: which will be used by the jail.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>An <acronym>IP</acronym> address: which is assigned to
>-	  the jail.  The <acronym>IP</acronym> address of a jail is
>-	  often an alias address for an existing network
>-	  interface.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>A command: the path name of an executable to run inside
>-	  the jail.  The path is relative to the root directory of the
>-	  jail environment.</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <para>Jails have their own set of users and their own <systemitem
>-	class="username">root</systemitem> account which are limited
>-      to the jail environment.  The <systemitem
>-	class="username">root</systemitem> account of a jail is not
>-      allowed to perform operations to the system outside of the
>-      associated jail environment.</para>
>-
>-    <para>This chapter provides an overview of the terminology and
>-      commands for managing &os; jails.  Jails are a powerful tool for
>-      both system administrators, and advanced users.</para>
>-
>-    <para>After reading this chapter, you will know:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>What a jail is and what purpose it may serve in &os;
>-	  installations.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to build, start, and stop a jail.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>The basics of jail administration, both from inside and
>-	  outside the jail.</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <important>
>-      <para>Jails are a powerful tool, but they are not a security
>-	panacea.  While it is not possible for a jailed process to
>-	break out on its own, there are several ways in which an
>-	unprivileged user outside the jail can cooperate with a
>-	privileged user inside the jail to obtain elevated privileges
>-	in the host environment.</para>
>-
>-      <para>Most of these attacks can be mitigated by ensuring that
>-	the jail root is not accessible to unprivileged users in the
>-	host environment.  As a general rule, untrusted users with
>-	privileged access to a jail should not be given access to the
>-	host environment.</para>
>-    </important>
>-  </sect1>
>-
>-  <sect1 xml:id="jails-terms">
>-    <title>Terms Related to Jails</title>
>-
>-    <para>To facilitate better understanding of parts of the &os;
>-      system related to jails, their internals and the way they
>-      interact with the rest of &os;, the following terms are used
>-      further in this chapter:</para>
>-
>-    <variablelist>
>-      <varlistentry>
>-	<term>&man.chroot.8; (command)</term>
>-	<listitem>
>-	  <para>Utility, which uses &man.chroot.2; &os; system call to
>-	    change the root directory of a process and all its
>-	    descendants.</para>
>-	</listitem>
>-      </varlistentry>
>-
>-      <varlistentry>
>-	<term>&man.chroot.2; (environment)</term>
>-	<listitem>
>-	  <para>The environment of processes running in a
>-	    <quote>chroot</quote>.  This includes resources such as
>-	    the part of the file system which is visible, user and
>-	    group IDs which are available, network interfaces and
>-	    other IPC mechanisms, etc.</para>
>-	</listitem>
>-      </varlistentry>
>-
>-      <varlistentry>
>-	<term>&man.jail.8; (command)</term>
>-	<listitem>
>-	  <para>The system administration utility which allows
>-	    launching of processes within a jail environment.</para>
>-	</listitem>
>-      </varlistentry>
>-
>-      <varlistentry>
>-	<term>host (system, process, user, etc.)</term>
>-	<listitem>
>-	  <para>The controlling system of a jail environment.  The
>-	    host system has access to all the hardware resources
>-	    available, and can control processes both outside of and
>-	    inside a jail environment.  One of the important
>-	    differences of the host system from a jail is that the
>-	    limitations which apply to superuser processes inside a
>-	    jail are not enforced for processes of the host
>-	    system.</para>
>-	</listitem>
>-      </varlistentry>
>-
>-      <varlistentry>
>-	<term>hosted (system, process, user, etc.)</term>
>-	<listitem>
>-	  <para>A process, user or other entity, whose access to
>-	    resources is restricted by a &os; jail.</para>
>-	</listitem>
>-      </varlistentry>
>-    </variablelist>
>-  </sect1>
>-
>-  <sect1 xml:id="jails-build">
>-    <title>Creating and Controlling Jails</title>
>-
>-    <para>Some administrators divide jails into the following two
>-      types: <quote>complete</quote> jails, which resemble a real &os;
>-      system, and <quote>service</quote> jails, dedicated to one
>-      application or service, possibly running with privileges.  This
>-      is only a conceptual division and the process of building a jail
>-      is not affected by it.  When creating a <quote>complete</quote>
>-      jail there are two options for the source of the userland: use
>-      prebuilt binaries (such as those supplied on an install media)
>-      or build from source.</para>
>-
>-    <para>To install the userland from installation media, first
>-      create the root directory for the jail.  This can be done by
>-      setting the <varname>DESTDIR</varname> variable to the proper
>-      location.</para>
>-
>-    <para>Start a shell and define <varname>DESTDIR</varname>:</para>
>-
>-    <screen>&prompt.root; <userinput>sh</userinput>
>-&prompt.root; <userinput>export DESTDIR=<replaceable>/here/is/the/jail</replaceable></userinput></screen>
>-
>-    <para>Mount the install media as covered in &man.mdconfig.8;
>-      when using the install ISO:</para>
>-
>-    <screen>&prompt.root; <userinput>mount -t cd9660 /dev/`mdconfig -f cdimage.iso` /mnt</userinput></screen>
>-
>-    <para>Extract the binaries from the tarballs on the install media
>-      into the declared destination.  Minimally, only the base set
>-      needs to be extracted, but a complete install can be performed
>-      when preferred.</para>
>-
>-    <para>To install just the base system:</para>
>-
>-    <screen>&prompt.root; <userinput>tar -xf /mnt/usr/freebsd-dist/base.txz -C $DESTDIR</userinput></screen>
>-
>-    <para>To install everything except the kernel:</para>
>-
>-    <screen>&prompt.root; <userinput>for <replaceable>sets</replaceable> in BASE PORTS; do tar -xf /mnt/FREEBSD_INSTALL/USR/FREEBSD_DIST/$<replaceable>sets</replaceable>.TXZ -C $DESTDIR ; done</userinput></screen>
>-
>-    <para>The &man.jail.8; manual page explains the procedure for
>-      building a jail:</para>
>-
>-    <screen>&prompt.root; <userinput>setenv D <replaceable>/here/is/the/jail</replaceable></userinput>
>-&prompt.root; <userinput>mkdir -p $D</userinput>      <co xml:id="jailpath"/>
>-&prompt.root; <userinput>cd /usr/src</userinput>
>-&prompt.root; <userinput>make buildworld</userinput>  <co xml:id="jailbuildworld"/>
>-&prompt.root; <userinput>make installworld DESTDIR=$D</userinput>  <co xml:id="jailinstallworld"/>
>-&prompt.root; <userinput>make distribution DESTDIR=$D</userinput>  <co xml:id="jaildistrib"/>
>-&prompt.root; <userinput>mount -t devfs devfs $D/dev</userinput>   <co xml:id="jaildevfs"/></screen>
>-
>-    <calloutlist>
>-      <callout arearefs="jailpath">
>-	<para>Selecting a location for a jail is the best starting
>-	  point.  This is where the jail will physically reside within
>-	  the file system of the jail's host.  A good choice can be
>-	  <filename
>-	    >/usr/jail/<replaceable>jailname</replaceable></filename>,
>-	  where <replaceable>jailname</replaceable> is the hostname
>-	  identifying the jail.  Usually, <filename>/usr/</filename>
>-	  has enough space for the jail file system, which for
>-	  <quote>complete</quote> jails is, essentially, a replication
>-	  of every file present in a default installation of the &os;
>-	  base system.</para>
>-      </callout>
>-
>-      <callout arearefs="jailbuildworld">
>-	<para>If you have already rebuilt your userland using
>-	  <command>make world</command> or
>-	  <command>make buildworld</command>, you can skip this step
>-	  and install your existing userland into the new jail.</para>
>-      </callout>
>-
>-      <callout arearefs="jailinstallworld">
>-	<para>This command will populate the directory subtree chosen
>-	  as jail's physical location on the file system with the
>-	  necessary binaries, libraries, manual pages and so
>-	  on.</para>
>-      </callout>
>-
>-      <callout arearefs="jaildistrib">
>-	<para>The <buildtarget>distribution</buildtarget> target for
>-	  <application>make</application> installs every needed
>-	  configuration file.  In simple words, it installs every
>-	  installable file of
>-	  <filename>/usr/src/etc/</filename> to the
>-	  <filename>/etc</filename> directory of the
>-	  jail environment:
>-	  <filename>$D/etc/</filename>.</para>
>-      </callout>
>-
>-      <callout arearefs="jaildevfs">
>-	<para>Mounting the &man.devfs.8; file system inside a jail is
>-	  not required.  On the other hand, any, or almost any
>-	  application requires access to at least one device,
>-	  depending on the purpose of the given application.  It is
>-	  very important to control access to devices from inside a
>-	  jail, as improper settings could permit an attacker to do
>-	  nasty things in the jail.  Control over &man.devfs.8; is
>-	  managed through rulesets which are described in the
>-	  &man.devfs.8; and &man.devfs.conf.5; manual pages.</para>
>-      </callout>
>-    </calloutlist>
>-
>-    <para>Once a jail is installed, it can be started by using the
>-      &man.jail.8; utility.  The &man.jail.8; utility takes four
>-      mandatory arguments which are described in the <xref
>-	linkend="jails-synopsis"/>.  Other arguments may be specified
>-      too, e.g., to run the jailed process with the credentials of a
>-      specific user.  The
>-      <option><replaceable>command</replaceable></option> argument
>-      depends on the type of the jail; for a
>-      <emphasis>virtual system</emphasis>,
>-      <filename>/etc/rc</filename> is a good choice, since it will
>-      replicate the startup sequence of a real &os; system.  For a
>-      <emphasis>service</emphasis> jail, it depends on the service or
>-      application that will run within the jail.</para>
>-
>-    <para>Jails are often started at boot time and the &os;
>-      <filename>rc</filename> mechanism provides an easy way to do
>-      this.</para>
>-
>-    <procedure>
>-      <step>
>-	<para>A list of the jails which are enabled to start at boot
>-	  time should be added to the &man.rc.conf.5; file:</para>
>-
>-	<programlisting>jail_enable="YES"   # Set to NO to disable starting of any jails
>-jail_list="<replaceable>www</replaceable>"     # Space separated list of names of jails</programlisting>
>-
>-	<note>
>-	  <para>Jail names in <varname>jail_list</varname> should
>-	    contain alphanumeric characters only.</para>
>-	</note>
>-      </step>
>-
>-      <step>
>-	<para>For each jail listed in <varname>jail_list</varname>, a
>-	  group of &man.rc.conf.5; settings, which describe the
>-	  particular jail, should be added:</para>
>-
>-	<programlisting>jail_<replaceable>www</replaceable>_rootdir="/usr/jail/www"     # jail's root directory
>-jail_<replaceable>www</replaceable>_hostname="<replaceable>www</replaceable>.example.org"  # jail's hostname
>-jail_<replaceable>www</replaceable>_ip="192.168.0.10"           # jail's IP address
>-jail_<replaceable>www</replaceable>_devfs_enable="YES"          # mount devfs in the jail</programlisting>
>-
>-	<para>The default startup of jails configured in
>-	  &man.rc.conf.5;, will run the <filename>/etc/rc</filename>
>-	  script of the jail, which assumes the jail is a complete
>-	  virtual system.  For service jails, the default startup
>-	  command of the jail should be changed, by setting the
>-	  <varname>jail_<replaceable>jailname</replaceable>_exec_start</varname>
>-	  option appropriately.</para>
>-
>-	<note>
>-	  <para>For a full list of available options, please see the
>-	    &man.rc.conf.5; manual page.</para>
>-	</note>
>-      </step>
>-    </procedure>
>-
>-    <para>&man.service.8; can be used to start or stop a jail by hand,
>-      if an entry for it exists in
>-      <filename>rc.conf</filename>:</para>
>-
>-    <screen>&prompt.root; <userinput>service jail start <replaceable>www</replaceable></userinput>
>-&prompt.root; <userinput>service jail stop <replaceable>www</replaceable></userinput></screen>
>-
>-    <para>Jails can be shut down with &man.jexec.8;.  Use &man.jls.8;
>-      to identify the jail's <varname>JID</varname>, then use
>-      &man.jexec.8; to run the shutdown script in that jail.</para>
>-
>-    <screen>&prompt.root; <userinput>jls</userinput>
>-   JID  IP Address      Hostname                      Path
>-     3  192.168.0.10    www                           /usr/jail/www
>-&prompt.root; <userinput>jexec <replaceable>3</replaceable> /etc/rc.shutdown</userinput></screen>
>-
>-    <para>More information about this can be found in the &man.jail.8;
>-      manual page.</para>
>-  </sect1>
>-
>-  <sect1 xml:id="jails-tuning">
>-    <title>Fine Tuning and Administration</title>
>-
>-    <para>There are several options which can be set for any jail, and
>-      various ways of combining a host &os; system with jails, to
>-      produce higher level applications.  This section
>-      presents:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>Some of the options available for tuning the behavior
>-	  and security restrictions implemented by a jail
>-	  installation.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Some of the high-level applications for jail management,
>-	  which are available through the &os; Ports Collection, and
>-	  can be used to implement overall jail-based
>-	  solutions.</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <sect2 xml:id="jails-tuning-utilities">
>-      <title>System Tools for Jail Tuning in &os;</title>
>-
>-      <para>Fine tuning of a jail's configuration is mostly done by
>-	setting &man.sysctl.8; variables.  A special subtree of sysctl
>-	exists as a basis for organizing all the relevant options: the
>-	<varname>security.jail.*</varname> hierarchy of &os; kernel
>-	options.  Here is a list of the main jail-related sysctls,
>-	complete with their default value.  Names should be
>-	self-explanatory, but for more information about them, please
>-	refer to the &man.jail.8; and &man.sysctl.8; manual
>-	pages.</para>
>-
>-      <itemizedlist>
>-	<listitem>
>-	  <para><varname>security.jail.set_hostname_allowed:
>-	      1</varname></para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para><varname>security.jail.socket_unixiproute_only:
>-	      1</varname></para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para><varname>security.jail.sysvipc_allowed:
>-	      0</varname></para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para><varname>security.jail.enforce_statfs:
>-	      2</varname></para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para><varname>security.jail.allow_raw_sockets:
>-	      0</varname></para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para><varname>security.jail.chflags_allowed:
>-	      0</varname></para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para><varname>security.jail.jailed: 0</varname></para>
>-	</listitem>
>-      </itemizedlist>
>-
>-      <para>These variables can be used by the system administrator of
>-	the <emphasis>host system</emphasis> to add or remove some of
>-	the limitations imposed by default on the <systemitem
>-	  class="username">root</systemitem> user.  Note that there
>-	are some limitations which cannot be removed.  The
>-	<systemitem class="username">root</systemitem> user is not
>-	allowed to mount or unmount file systems from within a
>-	&man.jail.8;.  The <systemitem
>-	  class="username">root</systemitem> inside a jail may not
>-	load or unload &man.devfs.8; rulesets, set firewall rules, or
>-	do many other administrative tasks which require modifications
>-	of in-kernel data, such as setting the
>-	<varname>securelevel</varname> of the kernel.</para>
>-
>-      <para>The base system of &os; contains a basic set of tools for
>-	viewing information about the active jails, and attaching to a
>-	jail to run administrative commands.  The &man.jls.8; and
>-	&man.jexec.8; commands are part of the base &os; system, and
>-	can be used to perform the following simple tasks:</para>
>-
>-      <itemizedlist>
>-	<listitem>
>-	  <para>Print a list of active jails and their corresponding
>-	    jail identifier (<acronym>JID</acronym>),
>-	    <acronym>IP</acronym> address, hostname and path.</para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>Attach to a running jail, from its host system, and
>-	    run a command inside the jail or perform administrative
>-	    tasks inside the jail itself.  This is especially useful
>-	    when the <systemitem class="username">root</systemitem>
>-	    user wants to cleanly shut down a jail.  The &man.jexec.8;
>-	    utility can also be used to start a shell in a jail to do
>-	    administration in it; for example:</para>
>-
>-	  <screen>&prompt.root; <userinput>jexec <replaceable>1</replaceable> tcsh</userinput></screen>
>-	</listitem>
>-      </itemizedlist>
>-    </sect2>
>-
>-    <sect2 xml:id="jails-tuning-admintools">
>-      <title>High-Level Administrative Tools in the &os; Ports
>-	Collection</title>
>-
>-      <para>Among the many third-party utilities for jail
>-	administration, one of the most complete and useful is
>-	<package>sysutils/ezjail</package>.  It is a set of scripts
>-	that contribute to &man.jail.8; management.  Please refer to
>-	<link xlink:href="&url.books.handbook;/jails-ezjail.html">the
>-	  handbook section on <application>ezjail</application></link>
>-	for more information.</para>
>-    </sect2>
>-
>-    <sect2 xml:id="jails-updating">
>-      <title>Keeping Jails Patched and up to Date</title>
>-
>-      <para>Jails should be kept up to date from the host operating
>-	system as attempting to patch userland from within the jail
>-	may likely fail as the default behaviour in FreeBSD is to
>-	disallow the use of &man.chflags.1; in a jail which prevents
>-	the replacement of some files.  It is possible to change this
>-	behavior but it is recommended to use &man.freebsd-update.8;
>-	to maintain jails instead.  Use <option>-b</option> to specify
>-	the path of the jail to be updated.</para>
>-
>-      <screen>&prompt.root; <userinput>freebsd-update -b <replaceable>/here/is/the/jail</replaceable> fetch</userinput>
>-&prompt.root; <userinput>freebsd-update -b <replaceable>/here/is/the/jail</replaceable> install</userinput></screen>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 xml:id="jails-application">
>-    <info>
>-      <title>Updating Multiple Jails</title>
>-
>-      <authorgroup>
>-	<author>
>-	  <personname>
>-	    <firstname>Daniel</firstname>
>-	    <surname>Gerzo</surname>
>-	  </personname>
>-	  <contrib>Contributed by </contrib>
>-	</author>
>-      </authorgroup>
>-      <authorgroup>
>-	<author>
>-	  <personname>
>-	    <firstname>Simon</firstname>
>-	    <surname>L. B. Nielsen</surname>
>-	  </personname>
>-	  <contrib>Based upon an idea presented by </contrib>
>-	</author>
>-      </authorgroup>
>-      <authorgroup>
>-	<author>
>-	  <personname>
>-	    <firstname>Ken</firstname>
>-	    <surname>Tom</surname>
>-	  </personname>
>-	  <contrib>And an article written by </contrib>
>-	</author>
>-      </authorgroup>
>-    </info>
>-
>-    <para>The management of multiple jails can become problematic
>-      because every jail has to be rebuilt from scratch whenever it is
>-      upgraded.  This can be time consuming and tedious if a lot of
>-      jails are created and manually updated.</para>
>-
>-    <para>This section demonstrates one method to resolve this issue
>-      by safely sharing as much as is possible between jails using
>-      read-only &man.mount.nullfs.8; mounts, so that updating is
>-      simpler.  This makes it more attractive to put single services,
>-      such as <acronym>HTTP</acronym>, <acronym>DNS</acronym>, and
>-      <acronym>SMTP</acronym>, into individual jails.  Additionally,
>-      it provides a simple way to add, remove, and upgrade
>-      jails.</para>
>-
>-    <note>
>-      <para>Simpler solutions exist, such as
>-	<application>ezjail</application>, which provides an easier
>-	method of administering &os; jails but is less versatile than
>-	this setup.  <application>ezjail</application> is covered in
>-	more detail in <xref linkend="jails-ezjail"/>.</para>
>-    </note>
>-
>-    <para>The goals of the setup described in this section are:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>Create a simple and easy to understand jail structure
>-	  that does not require running a full installworld on each
>-	  and every jail.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Make it easy to add new jails or remove existing
>-	  ones.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Make it easy to update or upgrade existing jails.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Make it possible to run a customized &os; branch.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Be paranoid about security, reducing as much as
>-	  possible the possibility of compromise.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Save space and inodes, as much as possible.</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <para>This design relies on a single, read-only master template
>-      which is mounted into each jail and one read-write device per
>-      jail.  A device can be a separate physical disc, a partition, or
>-      a vnode backed memory device.  This example uses read-write
>-      <application>nullfs</application> mounts.</para>
>-
>-    <para>The file system layout is as follows:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>The jails are based under the
>-	  <filename>/home</filename> partition.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Each jail will be mounted under the
>-	  <filename>/home/j</filename> directory.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>The template for each jail and the read-only partition
>-	  for  all of the jails is
>-	  <filename>/home/j/mroot</filename>.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>A blank directory will be created for each jail under
>-	  the <filename>/home/j</filename> directory.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Each jail will have a <filename>/s</filename> directory
>-	  that will be linked to the read-write portion of the
>-	  system.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Each jail will have its own read-write system that is
>-	  based upon <filename>/home/j/skel</filename>.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>The read-write portion of each jail will be created in
>-	  <filename>/home/js</filename>.</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-	
>-
>-    <sect2 xml:id="jails-service-jails-template">
>-      <title>Creating the Template</title>
>-
>-      <para>This section describes the steps needed to create the
>-	master template.</para>
>-
>-      <para>It is recommended to first update the host &os; system to
>-	the latest -RELEASE branch using the instructions in <xref
>-	  linkend="makeworld"/>.  Additionally, this template uses the
>-	<package>sysutils/cpdup</package> package or port and
>-	<application>portsnap</application> will be used to download
>-	the &os; Ports Collection.</para>
>-
>-      <procedure>
>-	<step>
>-	  <para>First, create a directory structure for the read-only
>-	    file system which will contain the &os; binaries for the
>-	    jails.  Then, change directory to the &os; source tree and
>-	    install the read-only file system to the jail
>-	    template:</para>
>-
>-	  <screen>&prompt.root; <userinput>mkdir /home/j /home/j/mroot</userinput>
>-&prompt.root; <userinput>cd /usr/src</userinput>
>-&prompt.root; <userinput>make installworld DESTDIR=/home/j/mroot</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>Next, prepare a &os; Ports Collection for the jails as
>-	    well as a &os; source tree, which is required for
>-	    <application>mergemaster</application>:</para>
>-
>-	  <screen>&prompt.root; <userinput>cd /home/j/mroot</userinput>
>-&prompt.root; <userinput>mkdir usr/ports</userinput>
>-&prompt.root; <userinput>portsnap -p /home/j/mroot/usr/ports fetch extract</userinput>
>-&prompt.root; <userinput>cpdup /usr/src /home/j/mroot/usr/src</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>Create a skeleton for the read-write portion of the
>-	    system:</para>
>-
>-	  <screen>&prompt.root; <userinput>mkdir /home/j/skel /home/j/skel/home /home/j/skel/usr-X11R6 /home/j/skel/distfiles</userinput>
>-&prompt.root; <userinput>mv etc /home/j/skel</userinput>
>-&prompt.root; <userinput>mv usr/local /home/j/skel/usr-local</userinput>
>-&prompt.root; <userinput>mv tmp /home/j/skel</userinput>
>-&prompt.root; <userinput>mv var /home/j/skel</userinput>
>-&prompt.root; <userinput>mv root /home/j/skel</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>Use <application>mergemaster</application> to install
>-	    missing configuration files.  Then, remove the extra
>-	    directories that <application>mergemaster</application>
>-	    creates:</para>
>-
>-	  <screen>&prompt.root; <userinput>mergemaster -t /home/j/skel/var/tmp/temproot -D /home/j/skel -i</userinput>
>-&prompt.root; <userinput>cd /home/j/skel</userinput>
>-&prompt.root; <userinput>rm -R bin boot lib libexec mnt proc rescue sbin sys usr dev</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>Now, symlink the read-write file system to the
>-	    read-only file system.  Ensure that the symlinks are
>-	    created in the correct <filename>s/</filename> locations
>-	    as the creation of directories in the wrong locations will
>-	    cause the installation to fail.</para>
>-
>-	  <screen>&prompt.root; <userinput>cd /home/j/mroot</userinput>
>-&prompt.root; <userinput>mkdir s</userinput>
>-&prompt.root; <userinput>ln -s s/etc etc</userinput>
>-&prompt.root; <userinput>ln -s s/home home</userinput>
>-&prompt.root; <userinput>ln -s s/root root</userinput>
>-&prompt.root; <userinput>ln -s s/usr-local usr/local</userinput>
>-&prompt.root; <userinput>ln -s s/usr-X11R6 usr/X11R6</userinput>
>-&prompt.root; <userinput>ln -s s/distfiles usr/ports/distfiles</userinput>
>-&prompt.root; <userinput>ln -s s/tmp tmp</userinput>
>-&prompt.root; <userinput>ln -s s/var var</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>As a last step, create a generic
>-	    <filename>/home/j/skel/etc/make.conf</filename> containing
>-	    this line:</para>
>-
>-	  <programlisting>WRKDIRPREFIX?=  /s/portbuild</programlisting>
>-
>-	  <para>This makes it possible to compile &os; ports inside
>-	    each jail.  Remember that the ports directory is part of
>-	    the read-only system.  The custom path for
>-	    <literal>WRKDIRPREFIX</literal> allows builds to be done
>-	    in the read-write portion of every jail.</para>
>-	</step>
>-      </procedure>
>-    </sect2>
>-
>-    <sect2 xml:id="jails-service-jails-creating">
>-      <title>Creating Jails</title>
>-
>-      <para>The jail template can now be used to setup and configure
>-	the jails in <filename>/etc/rc.conf</filename>.  This example
>-	demonstrates the creation of 3 jails: <literal>NS</literal>,
>-	<literal>MAIL</literal> and <literal>WWW</literal>.</para>
>-
>-      <procedure>
>-	<step>
>-	  <para>Add the following lines to
>-	    <filename>/etc/fstab</filename>, so that the read-only
>-	    template for the jails and the read-write space will be
>-	    available in the respective jails:</para>
>-
>-	  <programlisting>/home/j/mroot   /home/j/ns     nullfs  ro  0   0
>-/home/j/mroot   /home/j/mail   nullfs  ro  0   0
>-/home/j/mroot   /home/j/www    nullfs  ro  0   0
>-/home/js/ns     /home/j/ns/s   nullfs  rw  0   0
>-/home/js/mail   /home/j/mail/s nullfs  rw  0   0
>-/home/js/www    /home/j/www/s  nullfs  rw  0   0</programlisting>
>-
>-	  <para>To prevent
>-	    <application>fsck</application> from checking
>-	    <application>nullfs</application> mounts during boot and
>-	    <application>dump</application> from backing up the
>-	    read-only nullfs mounts of the jails, the last two
>-	    columns are both set to <literal>0</literal>.</para>
>-	</step>
>-
>-	<step>
>-	  <para>Configure the jails in
>-	    <filename>/etc/rc.conf</filename>:</para>
>-
>-	  <programlisting>jail_enable="YES"
>-jail_set_hostname_allow="NO"
>-jail_list="ns mail www"
>-jail_ns_hostname="ns.example.org"
>-jail_ns_ip="192.168.3.17"
>-jail_ns_rootdir="/usr/home/j/ns"
>-jail_ns_devfs_enable="YES"
>-jail_mail_hostname="mail.example.org"
>-jail_mail_ip="192.168.3.18"
>-jail_mail_rootdir="/usr/home/j/mail"
>-jail_mail_devfs_enable="YES"
>-jail_www_hostname="www.example.org"
>-jail_www_ip="62.123.43.14"
>-jail_www_rootdir="/usr/home/j/www"
>-jail_www_devfs_enable="YES"</programlisting>
>-
>-	  <para>The
>-	    <varname>jail_<replaceable>name</replaceable>_rootdir</varname>
>-	    variable is set to
>-	    <filename>/usr/home</filename> instead
>-	    of <filename>/home</filename> because
>-	    the physical path of <filename
>-	      >/home</filename> on a default &os;
>-	    installation is <filename
>-	      >/usr/home</filename>.  The
>-	    <varname>jail_<replaceable>name</replaceable>_rootdir</varname>
>-	    variable must <emphasis>not</emphasis> be set to a path
>-	    which includes a symbolic link, otherwise the jails will
>-	    refuse to start.</para>
>-	</step>
>-
>-	<step>
>-	  <para>Create the required mount points for the read-only
>-	    file system of each jail:</para>
>-
>-	  <screen>&prompt.root; <userinput>mkdir /home/j/ns /home/j/mail /home/j/www</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>Install the read-write template into each jail using
>-	    <package>sysutils/cpdup</package>:</para>
>-	    
>-
>-	  <screen>&prompt.root; <userinput>mkdir /home/js</userinput>
>-&prompt.root; <userinput>cpdup /home/j/skel /home/js/ns</userinput>
>-&prompt.root; <userinput>cpdup /home/j/skel /home/js/mail</userinput>
>-&prompt.root; <userinput>cpdup /home/j/skel /home/js/www</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>In this phase, the jails are built and prepared to
>-	    run.  First, mount the required file systems for each
>-	    jail, and then start them:</para>
>-
>-	  <screen>&prompt.root; <userinput>mount -a</userinput>
>-&prompt.root; <userinput>service jail start</userinput></screen>
>-	</step>
>-      </procedure>
>-
>-      <para>The jails should be running now.  To check if they have
>-	started correctly, use <command>jls</command>.  Its output
>-	should be similar to the following:</para>
>-
>-      <screen>&prompt.root; <userinput>jls</userinput>
>-   JID  IP Address      Hostname                      Path
>-     3  192.168.3.17    ns.example.org                /home/j/ns
>-     2  192.168.3.18    mail.example.org              /home/j/mail
>-     1  62.123.43.14    www.example.org               /home/j/www</screen>
>-
>-      <para>At this point, it should be possible to log onto each
>-	jail, add new users, or configure daemons.  The
>-	<literal>JID</literal> column indicates the jail
>-	identification number of each running jail.  Use the following
>-	command to perform administrative tasks in the jail whose
>-	<acronym>JID</acronym> is <literal>3</literal>:</para>
>-
>-      <screen>&prompt.root; <userinput>jexec 3 tcsh</userinput></screen>
>-    </sect2>
>-
>-    <sect2 xml:id="jails-service-jails-upgrading">
>-      <title>Upgrading</title>
>-
>-      <para>The design of this setup provides an easy way to upgrade
>-	existing jails while minimizing their downtime.  Also, it
>-	provides a way to roll back to the older version should a
>-	problem occur.</para>
>-
>-      <procedure>
>-	<step>
>-	  <para>The first step is to upgrade the host system.  Then,
>-	    create a new temporary read-only template in
>-	    <filename>/home/j/mroot2</filename>.</para>
>-
>-	  <screen>&prompt.root; <userinput>mkdir /home/j/mroot2</userinput>
>-&prompt.root; <userinput>cd /usr/src</userinput>
>-&prompt.root; <userinput>make installworld DESTDIR=/home/j/mroot2</userinput>
>-&prompt.root; <userinput>cd /home/j/mroot2</userinput>
>-&prompt.root; <userinput>cpdup /usr/src usr/src</userinput>
>-&prompt.root; <userinput>mkdir s</userinput></screen>
>-
>-	  <para>The <buildtarget>installworld</buildtarget> creates a
>-	    few unnecessary directories, which should be
>-	    removed:</para>
>-
>-	  <screen>&prompt.root; <userinput>chflags -R 0 var</userinput>
>-&prompt.root; <userinput>rm -R etc var root usr/local tmp</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>Recreate the read-write symlinks for the master file
>-	    system:</para>
>-
>-	  <screen>&prompt.root; <userinput>ln -s s/etc etc</userinput>
>-&prompt.root; <userinput>ln -s s/root root</userinput>
>-&prompt.root; <userinput>ln -s s/home home</userinput>
>-&prompt.root; <userinput>ln -s ../s/usr-local usr/local</userinput>
>-&prompt.root; <userinput>ln -s ../s/usr-X11R6 usr/X11R6</userinput>
>-&prompt.root; <userinput>ln -s s/tmp tmp</userinput>
>-&prompt.root; <userinput>ln -s s/var var</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>Next, stop the jails:</para>
>-
>-	  <screen>&prompt.root; <userinput>service jail stop</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>Unmount the original file systems as the read-write
>-	    systems are attached to the read-only system
>-	    (<filename>/s</filename>):</para>
>-	    
>-
>-	  <screen>&prompt.root; <userinput>umount /home/j/ns/s</userinput>
>-&prompt.root; <userinput>umount /home/j/ns</userinput>
>-&prompt.root; <userinput>umount /home/j/mail/s</userinput>
>-&prompt.root; <userinput>umount /home/j/mail</userinput>
>-&prompt.root; <userinput>umount /home/j/www/s</userinput>
>-&prompt.root; <userinput>umount /home/j/www</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>Move the old read-only file system and replace it with
>-	    the new one.  This will serve as a backup and archive of
>-	    the old read-only file system should something go wrong.
>-	    The naming convention used here corresponds to when a new
>-	    read-only file system has been created.  Move the original
>-	    &os; Ports Collection over to the new file system to save
>-	    some space and inodes:</para>
>-
>-	  <screen>&prompt.root; <userinput>cd /home/j</userinput>
>-&prompt.root; <userinput>mv mroot mroot.20060601</userinput>
>-&prompt.root; <userinput>mv mroot2 mroot</userinput>
>-&prompt.root; <userinput>mv mroot.20060601/usr/ports mroot/usr</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>At this point the new read-only template is ready, so
>-	    the only remaining task is to remount the file systems and
>-	    start the jails:</para>
>-
>-	  <screen>&prompt.root; <userinput>mount -a</userinput>
>-&prompt.root; <userinput>service jail start</userinput></screen>
>-	</step>
>-      </procedure>
>-
>-      <para>Use <command>jls</command> to check if the jails started
>-	correctly.  Run <command>mergemaster</command> in each jail to
>-	update the configuration files.</para>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 xml:id="jails-ezjail">
>-    <info>
>-      <title>Managing Jails with
>-	<application>ezjail</application></title>
>-
>-      <authorgroup>
>-	<author>
>-	  <personname>
>-	    <firstname>Warren</firstname>
>-	    <surname>Block</surname>
>-	  </personname><contrib>Originally contributed by </contrib>
>-	</author>
>-      </authorgroup>
>-    </info>
>-
>-    <para>Creating and managing multiple jails can quickly become
>-      tedious and error-prone.  Dirk Engling's
>-      <application>ezjail</application> automates and greatly
>-      simplifies many jail tasks.  A <emphasis>basejail</emphasis> is
>-      created as a template.  Additional jails use
>-      &man.mount.nullfs.8; to share many of the basejail directories
>-      without using additional disk space.  Each additional jail takes
>-      only a few megabytes of disk space before applications are
>-      installed.  Upgrading the copy of the userland in the basejail
>-      automatically upgrades all of the other jails.</para>
>-
>-    <para>Additional benefits and features are described in detail on
>-      the <application>ezjail</application> web site, <link
>-	xlink:href="https://erdgeist.org/arts/software/ezjail/"></link>.</para>
>-
>-    <sect2 xml:id="jails-ezjail-install">
>-      <title>Installing <application>ezjail</application></title>
>-
>-      <para>Installing <application>ezjail</application> consists of
>-	adding a loopback interface for use in jails, installing the
>-	port or package, and enabling the service.</para>
>-
>-      <procedure xml:id="jails-ezjail-install-procedure">
>-	<step>
>-	  <para>To keep jail loopback traffic off the host's loopback
>-	    network interface <literal>lo0</literal>, a second
>-	    loopback interface is created by adding an entry to
>-	    <filename>/etc/rc.conf</filename>:</para>
>-
>-	  <programlisting>cloned_interfaces="lo1"</programlisting>
>-
>-	  <para>The second loopback interface <literal>lo1</literal>
>-	    will be created when the system starts.  It can also be
>-	    created manually without a restart:</para>
>-
>-	  <screen>&prompt.root; <userinput>service netif cloneup</userinput>
>-Created clone interfaces: lo1.</screen>
>-
>-	  <para>Jails can be allowed to use aliases of this secondary
>-	    loopback interface without interfering with the
>-	    host.</para>
>-
>-	  <para>Inside a jail, access to the loopback address
>-	    <systemitem class="ipaddress">127.0.0.1</systemitem> is
>-	    redirected to the first <acronym>IP</acronym> address
>-	    assigned to the jail.  To make the jail loopback
>-	    correspond with the new <literal>lo1</literal> interface,
>-	    that interface must be specified first in the list of
>-	    interfaces and <acronym>IP</acronym> addresses given when
>-	    creating a new jail.</para>
>-
>-	  <para>Give each jail a unique loopback address in the
>-	    <systemitem
>-	      class="ipaddress">127.0.0.0</systemitem><systemitem
>-	      class="netmask">/8</systemitem> netblock.</para>
>-	</step>
>-
>-	<step>
>-	  <para>Install
>-	    <package role="port">sysutils/ezjail</package>:</para>
>-
>-	  <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/ezjail</userinput>
>-&prompt.root; <userinput>make install clean</userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>Enable <application>ezjail</application> by adding
>-	    this line to <filename>/etc/rc.conf</filename>:</para>
>-
>-	  <programlisting>ezjail_enable="YES"</programlisting>
>-	</step>
>-
>-	<step>
>-	  <para>The service will automatically start on system boot.
>-	    It can be started immediately for the current
>-	    session:</para>
>-
>-	  <screen>&prompt.root; <userinput>service ezjail start</userinput></screen>
>-	</step>
>-      </procedure>
>-    </sect2>
>-
>-    <sect2 xml:id="jails-ezjail-initialsetup">
>-      <title>Initial Setup</title>
>-
>-      <para>With <application>ezjail</application> installed, the
>-	basejail directory structure can be created and populated.
>-	This step is only needed once on the jail host
>-	computer.</para>
>-
>-      <para>In both of these examples, <option>-p</option> causes the
>-	ports tree to be retrieved with &man.portsnap.8; into the
>-	basejail.  That single copy of the ports directory will be
>-	shared by all the jails.  Using a separate copy of the ports
>-	directory for jails isolates them from the host.  The
>-	<application>ezjail</application> <acronym>FAQ</acronym>
>-	explains in more detail: <link
>-	  xlink:href="http://erdgeist.org/arts/software/ezjail/#FAQ"></link>.</para>
>-
>-      <procedure xml:id="jails-ezjail-initialsetup-procedure">
>-	<step>
>-	  <stepalternatives>
>-	    <step>
>-	      <title>To Populate the Jail with &os;-RELEASE</title>
>-
>-	      <para>For a basejail based on the &os; RELEASE matching
>-		that of the host computer, use
>-		<command>install</command>.  For example, on a host
>-		computer running &os;&nbsp;10-STABLE, the latest
>-		RELEASE version of &os;&nbsp;-10 will be installed in
>-		the jail):</para>
>-
>-	      <screen>&prompt.root; <userinput>ezjail-admin install -p</userinput></screen>
>-	    </step>
>-
>-	    <step>
>-	      <title>To Populate the Jail with
>-		<command>installworld</command></title>
>-
>-	      <para>The basejail can be installed from binaries
>-		created by <buildtarget>buildworld</buildtarget> on
>-		the host with
>-		<command>ezjail-admin update</command>.</para>
>-
>-	      <para>In this example, &os;&nbsp;10-STABLE has been
>-		built from source.  The jail directories are created.
>-		Then <buildtarget>installworld</buildtarget> is
>-		executed, installing the host's
>-		<filename>/usr/obj</filename> into the
>-		basejail.</para>
>-
>-	      <screen>&prompt.root; <userinput>ezjail-admin update -i -p</userinput></screen>
>-
>-	      <para>The host's <filename>/usr/src</filename> is used
>-		by default.  A different source directory on the host
>-		can be specified with <option>-s</option> and a path,
>-		or set with <varname>ezjail_sourcetree</varname> in
>-		<filename>/usr/local/etc/ezjail.conf</filename>.</para>
>-	    </step>
>-	  </stepalternatives>
>-	</step>
>-      </procedure>
>-
>-      <tip>
>-	<para>The basejail's ports tree is shared by other jails.
>-	  However, downloaded distfiles are stored in the jail that
>-	  downloaded them.  By default, these files are stored in
>-	  <filename>/var/ports/distfiles</filename> within each
>-	  jail.  <filename>/var/ports</filename> inside each jail is
>-	  also used as a work directory when building ports.</para>
>-      </tip>
>-    </sect2>
>-
>-    <sect2 xml:id="jails-ezjail-create">
>-      <title>Creating and Starting a New Jail</title>
>-
>-      <para>New jails are created with
>-	<command>ezjail-admin create</command>.  In these examples,
>-	the <literal>lo1</literal> loopback interface is used as
>-	described above.</para>
>-
>-      <procedure xml:id="jails-ezjail-create-steps">
>-	<title>Create and Start a New Jail</title>
>-
>-	<step>
>-	  <para>Create the jail, specifying a name and the loopback
>-	    and network interfaces to use, along with their
>-	    <acronym>IP</acronym> addresses.  In this example, the
>-	    jail is named <literal>dnsjail</literal>.</para>
>-
>-	  <screen>&prompt.root; <userinput>ezjail-admin create <replaceable>dnsjail</replaceable> '<replaceable>lo1|127.0.1.1</replaceable>,<replaceable>em0</replaceable>|<replaceable>192.168.1.50</replaceable>'</userinput></screen>
>-
>-	  <tip xml:id="jails-ezjail-raw-network-sockets">
>-	    <para>Most network services run in jails without
>-	      problems.  A few network services, most notably
>-	      &man.ping.8;, use
>-	      <emphasis>raw network sockets</emphasis>.  In jails, raw
>-	      network sockets are disabled by default for security.
>-	      Services that require them will not work.</para>
>-
>-	    <para>Occasionally, a jail genuinely needs raw sockets.
>-	      For example, network monitoring applications often use
>-	      &man.ping.8; to check the availability of other
>-	      computers.  When raw network sockets are actually needed
>-	      in a jail, they can be enabled by editing the
>-	      <application>ezjail</application>
>-	      configuration file for the individual jail,
>-	      <filename>/usr/local/etc/ezjail/<replaceable>jailname</replaceable></filename>.
>-	      Modify the <literal>parameters</literal>
>-	      entry:</para>
>-
>-	    <programlisting>export jail_<replaceable>jailname</replaceable>_parameters="allow.raw_sockets=1"</programlisting>
>-
>-	    <para>Do not enable raw network sockets unless services in
>-	      the jail actually require them.</para>
>-	  </tip>
>-	</step>
>-
>-	<step>
>-	  <para>Start the jail:</para>
>-
>-	  <screen>&prompt.root; <userinput>ezjail-admin start <replaceable>dnsjail</replaceable></userinput></screen>
>-	</step>
>-
>-	<step>
>-	  <para>Use a console on the jail:</para>
>-
>-	  <screen>&prompt.root; <userinput>ezjail-admin console <replaceable>dnsjail</replaceable></userinput></screen>
>-	</step>
>-      </procedure>
>-
>-      <para>The jail is operating and additional configuration can be
>-	completed.  Typical settings added at this point
>-	include:</para>
>-
>-      <procedure>
>-	<step>
>-	  <title>Set the
>-	    <systemitem class="username">root</systemitem>
>-	    Password</title>
>-
>-	  <para>Connect to the jail and set the
>-	    <systemitem class="username">root</systemitem> user's
>-	    password:</para>
>-
>-	  <screen>&prompt.root; <userinput>ezjail-admin console <replaceable>dnsjail</replaceable></userinput>
>-&prompt.root; <userinput>passwd</userinput>
>-Changing local password for root
>-New Password:
>-Retype New Password:</screen>
>-	</step>
>-
>-	<step>
>-	  <title>Time Zone Configuration</title>
>-
>-	  <para>The jail's time zone can be set with &man.tzsetup.8;.
>-	    To avoid spurious error messages, the &man.adjkerntz.8;
>-	    entry in <filename>/etc/crontab</filename> can be
>-	    commented or removed.  This job attempts to update the
>-	    computer's hardware clock with time zone changes, but
>-	    jails are not allowed to access that hardware.</para>
>-	</step>
>-
>-	<step>
>-	  <title><acronym>DNS</acronym> Servers</title>
>-
>-	  <para>Enter domain name server lines in
>-	    <filename>/etc/resolv.conf</filename> so
>-	    <acronym>DNS</acronym> works in the jail.</para>
>-	</step>
>-
>-	<step>
>-	  <title>Edit <filename>/etc/hosts</filename></title>
>-
>-	  <para>Change the address and add the jail name to the
>-	    <literal>localhost</literal> entries in
>-	    <filename>/etc/hosts</filename>.</para>
>-	</step>
>-
>-	<step>
>-	  <title>Configure <filename>/etc/rc.conf</filename></title>
>-
>-	  <para>Enter configuration settings in
>-	    <filename>/etc/rc.conf</filename>.  This is much like
>-	    configuring a full computer.  The host name and
>-	    <acronym>IP</acronym> address are not set here.  Those
>-	    values are already provided by the jail
>-	    configuration.</para>
>-	</step>
>-      </procedure>
>-
>-      <para>With the jail configured, the applications for which the
>-	jail was created can be installed.</para>
>-
>-      <tip>
>-	<para>Some ports must be built with special options to be used
>-	  in a jail.  For example, both of the network monitoring
>-	  plugin packages
>-	  <package role="port">net-mgmt/nagios-plugins</package> and
>-	  <package role="port">net-mgmt/monitoring-plugins</package>
>-	  have a <literal>JAIL</literal> option which must be enabled
>-	  for them to work correctly inside a jail.</para>
>-      </tip>
>-    </sect2>
>-
>-    <sect2 xml:id="jails-ezjail-update">
>-      <title>Updating Jails</title>
>-
>-      <sect3 xml:id="jails-ezjail-update-os">
>-	<title>Updating the Operating System</title>
>-
>-	<para>Because the basejail's copy of the userland is shared by
>-	  the other jails, updating the basejail automatically updates
>-	  all of the other jails.  Either source or binary updates can
>-	  be used.</para>
>-
>-	<para>To build the world from source on the host, then
>-	  install it in the basejail, use:</para>
>-
>-	<screen>&prompt.root; <userinput>ezjail-admin update -b</userinput></screen>
>-
>-	<para>If the world has already been compiled on the host,
>-	  install it in the basejail with:</para>
>-
>-	<screen>&prompt.root; <userinput>ezjail-admin update -i</userinput></screen>
>-
>-	<para>Binary updates use &man.freebsd-update.8;.  These
>-	  updates have the same limitations as if
>-	  &man.freebsd-update.8; were being run directly.  The most
>-	  important one is that only -RELEASE versions of &os; are
>-	  available with this method.</para>
>-
>-	<para>Update the basejail to the latest patched release of
>-	  the version of &os; on the host.  For example, updating from
>-	  RELEASE-p1 to RELEASE-p2.</para>
>-
>-	<screen>&prompt.root; <userinput>ezjail-admin update -u</userinput></screen>
>-
>-	<para>To upgrade the basejail to a new version, first
>-	  upgrade the host system as described in <xref
>-	    linkend="freebsdupdate-upgrade" />.  Once the host has
>-	  been upgraded and rebooted, the basejail can then be
>-	  upgraded.  &man.freebsd-update.8; has no way of determining
>-	  which version is currently installed in the basejail, so the
>-	  original version must be specified.  Use &man.file.1; to
>-	  determine the original version in the basejail:</para>
>-
>-	<screen>&prompt.root; <userinput>file /usr/jails/basejail/bin/sh</userinput>
>-/usr/jails/basejail/bin/sh: ELF 64-bit LSB executable, x86-64, version 1 (FreeBSD), dynamically linked (uses shared libs), for FreeBSD 9.3, stripped</screen>
>-
>-	<para>Now use this information to perform the upgrade from
>-	  <literal>9.3-RELEASE</literal> to the current version of
>-	  the host system:</para>
>-
>-	<screen>&prompt.root; <userinput>ezjail-admin update -U -s <replaceable>9.3-RELEASE</replaceable></userinput></screen>
>-
>-	<para>After updating the basejail, &man.mergemaster.8; must
>-	  be run to update each jail's configuration files.</para>
>-
>-	<para>How to use &man.mergemaster.8; depends on the purpose
>-	  and trustworthiness of a jail.  If a jail's services or
>-	  users are not trusted, then &man.mergemaster.8; should only
>-	  be run from within that jail:</para>
>-
>-	<example xml:id="jails-ezjail-update-mergemaster-untrusted">
>-	  <title>&man.mergemaster.8; on Untrusted Jail</title>
>-
>-	  <para>Delete the link from the jail's
>-	    <filename>/usr/src</filename> into the basejail and
>-	    create a new <filename>/usr/src</filename> in the jail
>-	    as a mountpoint.  Mount the host computer's
>-	    <filename>/usr/src</filename> read-only on the jail's
>-	    new <filename>/usr/src</filename> mountpoint:</para>
>-
>-	  <screen>&prompt.root; <userinput>rm /usr/jails/<replaceable>jailname</replaceable>/usr/src</userinput>
>-&prompt.root; <userinput>mkdir /usr/jails/<replaceable>jailname</replaceable>/usr/src</userinput>
>-&prompt.root; <userinput>mount -t nullfs -o ro /usr/src /usr/jails/<replaceable>jailname</replaceable>/usr/src</userinput></screen>
>-
>-	  <para>Get a console in the jail:</para>
>-
>-	  <screen>&prompt.root; <userinput>ezjail-admin console <replaceable>jailname</replaceable></userinput></screen>
>-
>-	  <para>Inside the jail, run <command>mergemaster</command>.
>-	    Then exit the jail console:</para>
>-
>-	  <screen>&prompt.root; <userinput>cd /usr/src</userinput>
>-&prompt.root; <userinput>mergemaster -U</userinput>
>-&prompt.root; <userinput>exit</userinput></screen>
>-
>-	  <para>Finally, unmount the jail's
>-	    <filename>/usr/src</filename>:</para>
>-
>-	  <screen>&prompt.root; <userinput>umount /usr/jails/<replaceable>jailname</replaceable>/usr/src</userinput></screen>
>-	</example>
>-
>-	<example xml:id="jails-ezjail-update-mergemaster-trusted">
>-
>-	  <title>&man.mergemaster.8; on Trusted Jail</title>
>-
>-	  <para>If the users and services in a jail are trusted,
>-	    &man.mergemaster.8; can be run from the host:</para>
>-
>-	  <screen>&prompt.root; <userinput>mergemaster -U -D /usr/jails/<replaceable>jailname</replaceable></userinput></screen>
>-	</example>
>-      </sect3>
>-
>-      <sect3 xml:id="jails-ezjail-update-ports">
>-	<title>Updating Ports</title>
>-
>-	<para>The ports tree in the basejail is shared by the other
>-	  jails.  Updating that copy of the ports tree gives the other
>-	  jails the updated version also.</para>
>-
>-	<para>The basejail ports tree is updated with
>-	  &man.portsnap.8;:</para>
>-
>-	<screen>&prompt.root; <userinput>ezjail-admin update -P</userinput></screen>
>-      </sect3>
>-    </sect2>
>-
>-    <sect2 xml:id="jails-ezjail-control">
>-      <title>Controlling Jails</title>
>-
>-      <sect3 xml:id="jails-ezjail-control-stop-start">
>-	<title>Stopping and Starting Jails</title>
>-
>-	<para><application>ezjail</application> automatically starts
>-	  jails when the computer is started.  Jails can be manually
>-	  stopped and restarted with <command>stop</command> and
>-	  <command>start</command>:</para>
>-
>-	<screen>&prompt.root; <userinput>ezjail-admin stop <replaceable>sambajail</replaceable></userinput>
>-Stopping jails: sambajail.</screen>
>-
>-	<para>By default, jails are started automatically when the
>-	  host computer starts.  Autostarting can be disabled
>-	  with <command>config</command>:</para>
>-
>-	<screen>&prompt.root; <userinput>ezjail-admin config -r norun <replaceable>seldomjail</replaceable></userinput></screen>
>-
>-	<para>This takes effect the next time the host computer is
>-	  started.  A jail that is already running will not be
>-	  stopped.</para>
>-
>-	<para>Enabling autostart is very similar:</para>
>-
>-	<screen>&prompt.root; <userinput>ezjail-admin config -r run <replaceable>oftenjail</replaceable></userinput></screen>
>-      </sect3>
>-
>-      <sect3 xml:id="jails-ezjail-control-backup">
>-	<title>Archiving and Restoring Jails</title>
>-
>-	<para>Use <command>archive</command> to create a
>-	  <filename>.tar.gz</filename> archive of a jail.  The file
>-	  name is composed from the name of the jail and the current
>-	  date.  Archive files are written to the archive directory,
>-	  <filename>/usr/jails/ezjail_archives</filename>.  A
>-	  different archive directory can be chosen by setting
>-	  <varname>ezjail_archivedir</varname> in the configuration
>-	  file.</para>
>-
>-	<para>The archive file can be copied elsewhere as a backup, or
>-	  an existing jail can be restored from it with
>-	  <command>restore</command>.  A new jail can be created from
>-	  the archive, providing a convenient way to clone existing
>-	  jails.</para>
>-
>-	<para>Stop and archive a jail named
>-	  <literal>wwwserver</literal>:</para>
>-
>-	<screen>&prompt.root; <userinput>ezjail-admin stop <replaceable>wwwserver</replaceable></userinput>
>-Stopping jails: wwwserver.
>-&prompt.root; <userinput>ezjail-admin archive <replaceable>wwwserver</replaceable></userinput>
>-&prompt.root; <userinput>ls /usr/jails/ezjail-archives/</userinput>
>-wwwserver-201407271153.13.tar.gz</screen>
>-
>-	<para>Create a new jail named
>-	  <literal>wwwserver-clone</literal> from the archive created
>-	  in the previous step.  Use the <filename>em1</filename>
>-	  interface and assign a new <acronym>IP</acronym> address to
>-	  avoid conflict with the original:</para>
>-
>-	<screen>&prompt.root; <userinput>ezjail-admin create -a /usr/jails/ezjail_archives/wwwserver-201407271153.13.tar.gz <replaceable>wwwserver-clone</replaceable> 'lo1|127.0.3.1,em1|192.168.1.51'</userinput></screen>
>-      </sect3>
>-    </sect2>
>-
>-    <sect2 xml:id="jails-ezjail-example-bind">
>-      <title>Full Example: <application>BIND</application> in a
>-	Jail</title>
>-
>-      <para>Putting the <application>BIND</application>
>-	<acronym>DNS</acronym> server in a jail improves security by
>-	isolating it.  This example creates a simple caching-only name
>-	server.</para>
>-
>-      <itemizedlist xml:id="jails-ezjail-example-bind-assumptions">
>-	<listitem>
>-	  <para>The jail will be called
>-	    <literal>dns1</literal>.</para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>The jail will use <acronym>IP</acronym> address
>-	    <literal>192.168.1.240</literal> on the host's
>-	    <literal>re0</literal> interface.</para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>The upstream <acronym>ISP</acronym>'s DNS servers are
>-	    at <literal>10.0.0.62</literal> and
>-	    <literal>10.0.0.61</literal>.</para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>The basejail has already been created and a ports tree
>-	    installed.</para>
>-	</listitem>
>-      </itemizedlist>
>-
>-      <example xml:id="jails-ezjail-example-bind-steps">
>-	<title>Running BIND in a Jail</title>
>-
>-	<para>Create a cloned loopback interface by adding a line to
>-	  <filename>/etc/rc.conf</filename>:</para>
>-
>-	<programlisting>cloned_interfaces="lo1"</programlisting>
>-
>-	<para>Immediately create the new loopback interface:</para>
>-
>-	<screen>&prompt.root; <userinput>service netif cloneup</userinput>
>-Created clone interfaces: lo1.</screen>
>-
>-	<para>Create the jail:</para>
>-
>-	<screen>&prompt.root; <userinput>ezjail-admin create dns1 'lo1|127.0.2.1,re0|192.168.1.240'</userinput></screen>
>-
>-	<para>Start the jail, connect to a console running on it, and
>-	  perform some basic configuration:</para>
>-
>-	<screen>&prompt.root; <userinput>ezjail-admin start dns1</userinput>
>-&prompt.root; <userinput>ezjail-admin console dns1</userinput>
>-&prompt.root; <userinput>passwd</userinput>
>-Changing local password for root
>-New Password:
>-Retype New Password:
>-&prompt.root; <userinput>tzsetup</userinput>
>-&prompt.root; <userinput>sed -i .bak -e '/adjkerntz/ s/^/#/' /etc/crontab</userinput>
>-&prompt.root; <userinput>sed -i .bak -e 's/127.0.0.1/127.0.2.1/g; s/localhost.my.domain/dns1.my.domain dns1/' /etc/hosts</userinput></screen>
>-
>-	<para>Temporarily set the upstream <acronym>DNS</acronym>
>-	  servers in <filename>/etc/resolv.conf</filename> so ports
>-	  can be downloaded:</para>
>-
>-	<programlisting>nameserver 10.0.0.62
>-nameserver 10.0.0.61</programlisting>
>-
>-	<para>Still using the jail console, install
>-	  <package role="port">dns/bind99</package>.</para>
>-
>-	<screen>&prompt.root; <userinput>make -C /usr/ports/dns/bind99 install clean</userinput></screen>
>-
>-	<para>Configure the name server by editing
>-	  <filename>/usr/local/etc/namedb/named.conf</filename>.</para>
>-
>-	<para>Create an Access Control List (<acronym>ACL</acronym>)
>-	  of addresses and networks that are permitted to send
>-	  <acronym>DNS</acronym> queries to this name server.  This
>-	  section is added just before the <literal>options</literal>
>-	  section already in the file:</para>
>-
>-	<programlisting>...
>-// or cause huge amounts of useless Internet traffic.
>-
>-acl "trusted" {
>-	192.168.1.0/24;
>-	localhost;
>-	localnets;
>-};
>-
>-options {
>-...</programlisting>
>-
>-	<para>Use the jail <acronym>IP</acronym> address in the
>-	  <literal>listen-on</literal> setting to accept
>-	  <acronym>DNS</acronym> queries from other computers on the
>-	  network:</para>
>-
>-	<programlisting>	listen-on	{ 192.168.1.240; };</programlisting>
>-
>-	<para>A simple caching-only <acronym>DNS</acronym> name server
>-	  is created by changing the <literal>forwarders</literal>
>-	  section.  The original file contains:</para>
>-
>-	<programlisting>/*
>-	forwarders {
>-		127.0.0.1;
>-	};
>-*/</programlisting>
>-
>-	<para>Uncomment the section by removing the
>-	  <literal>/*</literal> and <literal>*/</literal> lines.
>-	  Enter the <acronym>IP</acronym> addresses of the upstream
>-	  <acronym>DNS</acronym> servers.  Immediately after the
>-	  <literal>forwarders</literal> section, add references to the
>-	  <literal>trusted</literal> <acronym>ACL</acronym> defined
>-	  earlier:</para>
>-
>-	<programlisting>	forwarders {
>-		10.0.0.62;
>-		10.0.0.61;
>-	};
>-
>-	allow-query       { any; };
>-	allow-recursion   { trusted; };
>-	allow-query-cache { trusted; };</programlisting>
>-
>-	<para>Enable the service in
>-	  <filename>/etc/rc.conf</filename>:</para>
>-
>-	<programlisting>named_enable="YES"</programlisting>
>-
>-	<para>Start and test the name server:</para>
>-
>-	<screen>&prompt.root; <userinput>service named start</userinput>
>-wrote key file "/usr/local/etc/namedb/rndc.key"
>-Starting named.
>-&prompt.root; <userinput>/usr/local/bin/dig @192.168.1.240 freebsd.org</userinput></screen>
>-
>-	<para>A response that includes</para>
>-
>-	<screen>;; Got answer;</screen>
>-
>-	<para>shows that the new <acronym>DNS</acronym> server is
>-	  working.  A long delay followed by a response
>-	  including</para>
>-
>-	<screen>;; connection timed out; no servers could be reached</screen>
>-
>-	<para>shows a problem.  Check the configuration settings and
>-	  make sure any local firewalls allow the new
>-	  <acronym>DNS</acronym> access to the upstream
>-	  <acronym>DNS</acronym> servers.</para>
>-
>-	<para>The new <acronym>DNS</acronym> server can use itself for
>-	  local name resolution, just like other local computers.  Set
>-	  the address of the <acronym>DNS</acronym> server in the
>-	  client computer's
>-	  <filename>/etc/resolv.conf</filename>:</para>
>-
>-	<programlisting>nameserver 192.168.1.240</programlisting>
>-
>-	<para>A local <acronym>DHCP</acronym> server can be configured
>-	  to provide this address for a local <acronym>DNS</acronym>
>-	  server, providing automatic configuration on
>-	  <acronym>DHCP</acronym> clients.</para>
>-      </example>
>-    </sect2>
>-  </sect1>
>-</chapter>
>+<?xml version="1.0" encoding="iso-8859-1"?>
>+
>+<chapter xmlns="http://docbook.org/ns/docbook"
>+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
>+  xml:id="jails">
>+  <info>
>+    <title>Jails</title>
>+
>+    <authorgroup>
>+      <author><personname><firstname>Matteo</firstname><surname>Riondato</surname></personname><contrib>Contributed
>+	by </contrib></author>
>+    </authorgroup>
>+  </info>
>+
>+  <indexterm><primary>jails</primary></indexterm>
>+
>+  <sect1 xml:id="jails-synopsis">
>+    <title>Synopsis</title>
>+
>+    <para>Since system administration is a difficult task, many tools
>+      have been developed to make life easier for the administrator.
>+      These tools often enhance the way systems are installed,
>+      configured, and maintained.  One of the tools which can be used
>+      to enhance the security of a &os; system is
>+      <firstterm>jails</firstterm>.  Jails have been available since
>+      &os;&nbsp;4.X and continue to be enhanced in their usefulness,
>+      performance, reliability, and security.</para>
>+
>+    <para>Jails build upon the &man.chroot.2; concept (which is used
>+      to change the root directory of a set of processes) to create a
>+      safe environment, separate from the rest of the system.
>+      Processes created in the chrooted environment can not access
>+      files or resources outside of it.  For that reason, compromising
>+      a service running in a "chroot-ed" environment should not allow the
>+      attacker to compromise the entire system.  However, a chroot has
>+      several limitations.  It is suited to easy tasks which do not
>+      require much flexibility or complex, advanced features.  Over
>+      time many ways have been found to escape from a chrooted
>+      environment, making it a less than ideal solution for securing
>+      services.</para>
>+
>+    <para>Jails improve on the concept of the traditional chroot
>+      environment in several ways.  In a traditional chroot
>+      environment, processes are only limited in the part of the file
>+      system they can access.  The rest of the system resources,
>+      system users, running processes, and the networking subsystem
>+      are shared by the chrooted processes and the processes of the
>+      host system.  Jails expand this model by virtualizing access to
>+      the file system, the set of users, and the networking subsystem.
>+      More fine-grained controls are available for tuning the access
>+      of a jailed environment.  Jails can be considered as a type of
>+      operating system-level virtualization.</para>
>+
>+    <para>A jail is characterized by four elements:</para>
>+
>+    <itemizedlist>
>+      <listitem>
>+	<para>A directory subtree: the starting point from which a
>+	  jail is entered.  Once inside the jail, a process is not
>+	  permitted to escape outside of this subtree.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>A hostname: which will be used by the jail.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>An <acronym>IP</acronym> address: which is assigned to
>+	  the jail.  The <acronym>IP</acronym> address of a jail is
>+	  often an alias address for an existing network
>+	  interface.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>A command: the path name of an executable to run inside
>+	  the jail.  The path is relative to the root directory of the
>+	  jail environment.</para>
>+      </listitem>
>+    </itemizedlist>
>+
>+    <para>Jails have their own set of users and their own <systemitem
>+	class="username">root</systemitem> account which are limited
>+      to the jail environment.  The <systemitem
>+	class="username">root</systemitem> account of a jail is not
>+      allowed to perform operations to the system outside of the
>+      associated jail environment.</para>
>+
>+    <para>This chapter provides an overview of the terminology and
>+      commands for managing &os; jails.  Jails are a powerful tool for
>+      both system administrators, and advanced users.</para>
>+
>+    <para>After reading this chapter, you will know:</para>
>+
>+    <itemizedlist>
>+      <listitem>
>+	<para>What a jail is and what purpose it may serve in &os;
>+	  installations.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>How to build, start, and stop a jail.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>The basics of jail administration, both from inside and
>+	  outside the jail.</para>
>+      </listitem>
>+    </itemizedlist>
>+
>+    <important>
>+      <para>Jails are a powerful tool, but they are not a security
>+	panacea.  While it is not possible for a jailed process to
>+	break out on its own, there are several ways in which an
>+	unprivileged user outside the jail can cooperate with a
>+	privileged user inside the jail to obtain elevated privileges
>+	in the host environment.</para>
>+
>+      <para>Most of these attacks can be mitigated by ensuring that
>+	the jail root is not accessible to unprivileged users in the
>+	host environment.  As a general rule, untrusted users with
>+	privileged access to a jail should not be given access to the
>+	host environment.</para>
>+    </important>
>+  </sect1>
>+
>+  <sect1 xml:id="jails-terms">
>+    <title>Terms Related to Jails</title>
>+
>+    <para>To facilitate better understanding of parts of the &os;
>+      system related to jails, their internals and the way they
>+      interact with the rest of &os;, the following terms are used
>+      further in this chapter:</para>
>+
>+    <variablelist>
>+      <varlistentry>
>+	<term>&man.chroot.8; (command)</term>
>+	<listitem>
>+	  <para>Utility, which uses &man.chroot.2; &os; system call to
>+	    change the root directory of a process and all its
>+	    descendants.</para>
>+	</listitem>
>+      </varlistentry>
>+
>+      <varlistentry>
>+	<term>&man.chroot.2; (environment)</term>
>+	<listitem>
>+	  <para>The environment of processes running in a
>+	    <quote>chroot</quote>.  This includes resources such as
>+	    the part of the file system which is visible, user and
>+	    group IDs which are available, network interfaces and
>+	    other IPC mechanisms, etc.</para>
>+	</listitem>
>+      </varlistentry>
>+
>+      <varlistentry>
>+	<term>&man.jail.8; (command)</term>
>+	<listitem>
>+	  <para>The system administration utility which allows
>+	    launching of processes within a jail environment.</para>
>+	</listitem>
>+      </varlistentry>
>+
>+      <varlistentry>
>+	<term>host (system, process, user, etc.)</term>
>+	<listitem>
>+	  <para>The controlling system of a jail environment.  The
>+	    host system has access to all the hardware resources
>+	    available, and can control processes both outside of and
>+	    inside a jail environment.  One of the important
>+	    differences of the host system from a jail is that the
>+	    limitations which apply to superuser processes inside a
>+	    jail are not enforced for processes of the host
>+	    system.</para>
>+	</listitem>
>+      </varlistentry>
>+
>+      <varlistentry>
>+	<term>hosted (system, process, user, etc.)</term>
>+	<listitem>
>+	  <para>A process, user or other entity, whose access to
>+	    resources is restricted by a &os; jail.</para>
>+	</listitem>
>+      </varlistentry>
>+    </variablelist>
>+  </sect1>
>+
>+  <sect1 xml:id="jails-build">
>+    <title>Creating and Controlling Jails</title>
>+
>+    <para>Some administrators divide jails into the following two
>+      types: <quote>complete</quote> jails, which resemble a real &os;
>+      system, and <quote>service</quote> jails, dedicated to one
>+      application or service, possibly running with privileges.  This
>+      is only a conceptual division and the process of building a jail
>+      is not affected by it.  When creating a <quote>complete</quote>
>+      jail there are two options for the source of the userland: use
>+      prebuilt binaries (such as those supplied on an install media)
>+      or build from source.</para>
>+
>+    <para>To install the userland from installation media, first
>+      create the root directory for the jail.  This can be done by
>+      setting the <varname>DESTDIR</varname> variable to the proper
>+      location.</para>
>+
>+    <para>Start a shell and define <varname>DESTDIR</varname>:</para>
>+
>+    <screen>&prompt.root; <userinput>sh</userinput>
>+&prompt.root; <userinput>export DESTDIR=<replaceable>/here/is/the/jail</replaceable></userinput></screen>
>+
>+    <para>Mount the install media as covered in &man.mdconfig.8;
>+      when using the install ISO:</para>
>+
>+    <screen>&prompt.root; <userinput>mount -t cd9660 /dev/`mdconfig -f cdimage.iso` /mnt</userinput></screen>
>+
>+    <para>Extract the binaries from the tarballs on the install media
>+      into the declared destination.  Minimally, only the base set
>+      needs to be extracted, but a complete install can be performed
>+      when preferred.</para>
>+
>+    <para>To install just the base system:</para>
>+
>+    <screen>&prompt.root; <userinput>tar -xf /mnt/usr/freebsd-dist/base.txz -C $DESTDIR</userinput></screen>
>+
>+    <para>To install everything except the kernel:</para>
>+
>+    <screen>&prompt.root; <userinput>for <replaceable>sets</replaceable> in BASE PORTS; do tar -xf /mnt/FREEBSD_INSTALL/USR/FREEBSD_DIST/$<replaceable>sets</replaceable>.TXZ -C $DESTDIR ; done</userinput></screen>
>+
>+    <para>The &man.jail.8; manual page explains the procedure for
>+      building a jail:</para>
>+
>+    <screen>&prompt.root; <userinput>setenv D <replaceable>/here/is/the/jail</replaceable></userinput>
>+&prompt.root; <userinput>mkdir -p $D</userinput>      <co xml:id="jailpath"/>
>+&prompt.root; <userinput>cd /usr/src</userinput>
>+&prompt.root; <userinput>make buildworld</userinput>  <co xml:id="jailbuildworld"/>
>+&prompt.root; <userinput>make installworld DESTDIR=$D</userinput>  <co xml:id="jailinstallworld"/>
>+&prompt.root; <userinput>make distribution DESTDIR=$D</userinput>  <co xml:id="jaildistrib"/>
>+&prompt.root; <userinput>mount -t devfs devfs $D/dev</userinput>   <co xml:id="jaildevfs"/></screen>
>+
>+    <calloutlist>
>+      <callout arearefs="jailpath">
>+	<para>Selecting a location for a jail is the best starting
>+	  point.  This is where the jail will physically reside within
>+	  the file system of the jail's host.  A good choice can be
>+	  <filename
>+	    >/usr/jail/<replaceable>jailname</replaceable></filename>,
>+	  where <replaceable>jailname</replaceable> is the hostname
>+	  identifying the jail.  Usually, <filename>/usr/</filename>
>+	  has enough space for the jail file system, which for
>+	  <quote>complete</quote> jails is, essentially, a replication
>+	  of every file present in a default installation of the &os;
>+	  base system.</para>
>+      </callout>
>+
>+      <callout arearefs="jailbuildworld">
>+	<para>If you have already rebuilt your userland using
>+	  <command>make world</command> or
>+	  <command>make buildworld</command>, you can skip this step
>+	  and install your existing userland into the new jail.</para>
>+      </callout>
>+
>+      <callout arearefs="jailinstallworld">
>+	<para>This command will populate the directory subtree chosen
>+	  as jail's physical location on the file system with the
>+	  necessary binaries, libraries, manual pages and so
>+	  on.</para>
>+      </callout>
>+
>+      <callout arearefs="jaildistrib">
>+	<para>The <buildtarget>distribution</buildtarget> target for
>+	  <application>make</application> installs every needed
>+	  configuration file.  In simple words, it installs every
>+	  installable file of
>+	  <filename>/usr/src/etc/</filename> to the
>+	  <filename>/etc</filename> directory of the
>+	  jail environment:
>+	  <filename>$D/etc/</filename>.</para>
>+      </callout>
>+
>+      <callout arearefs="jaildevfs">
>+	<para>Mounting the &man.devfs.8; file system inside a jail is
>+	  not required.  On the other hand, any, or almost any
>+	  application requires access to at least one device,
>+	  depending on the purpose of the given application.  It is
>+	  very important to control access to devices from inside a
>+	  jail, as improper settings could permit an attacker to do
>+	  nasty things in the jail.  Control over &man.devfs.8; is
>+	  managed through rulesets which are described in the
>+	  &man.devfs.8; and &man.devfs.conf.5; manual pages.</para>
>+      </callout>
>+    </calloutlist>
>+
>+    <para>Once a jail is installed, it can be started by using the
>+      &man.jail.8; utility.  The &man.jail.8; utility takes four
>+      mandatory arguments which are described in the <xref
>+	linkend="jails-synopsis"/>.  Other arguments may be specified
>+      too, e.g., to run the jailed process with the credentials of a
>+      specific user.  The
>+      <option><replaceable>command</replaceable></option> argument
>+      depends on the type of the jail; for a
>+      <emphasis>virtual system</emphasis>,
>+      <filename>/etc/rc</filename> is a good choice, since it will
>+      replicate the startup sequence of a real &os; system.  For a
>+      <emphasis>service</emphasis> jail, it depends on the service or
>+      application that will run within the jail.</para>
>+
>+    <para>Jails are often started at boot time and the &os;
>+      <filename>rc</filename> mechanism provides an easy way to do
>+      this.</para>
>+
>+    <procedure>
>+      <step>
>+	<para>A list of the jails which are enabled to start at boot
>+	  time should be added to the &man.rc.conf.5; file:</para>
>+
>+	<programlisting>jail_enable="YES"   # Set to NO to disable starting of any jails
>+jail_list="<replaceable>www</replaceable>"     # Space separated list of names of jails</programlisting>
>+
>+	<note>
>+	  <para>Jail names in <varname>jail_list</varname> should
>+	    contain alphanumeric characters only.</para>
>+	</note>
>+      </step>
>+
>+      <step>
>+	<para>For each jail listed in <varname>jail_list</varname>, a
>+	  group of &man.rc.conf.5; settings, which describe the
>+	  particular jail, should be added:</para>
>+
>+	<programlisting>jail_<replaceable>www</replaceable>_rootdir="/usr/jail/www"     # jail's root directory
>+jail_<replaceable>www</replaceable>_hostname="<replaceable>www</replaceable>.example.org"  # jail's hostname
>+jail_<replaceable>www</replaceable>_ip="192.168.0.10"           # jail's IP address
>+jail_<replaceable>www</replaceable>_devfs_enable="YES"          # mount devfs in the jail</programlisting>
>+
>+	<para>The default startup of jails configured in
>+	  &man.rc.conf.5;, will run the <filename>/etc/rc</filename>
>+	  script of the jail, which assumes the jail is a complete
>+	  virtual system.  For service jails, the default startup
>+	  command of the jail should be changed, by setting the
>+	  <varname>jail_<replaceable>jailname</replaceable>_exec_start</varname>
>+	  option appropriately.</para>
>+
>+	<note>
>+	  <para>For a full list of available options, please see the
>+	    &man.rc.conf.5; manual page.</para>
>+	</note>
>+      </step>
>+    </procedure>
>+
>+    <para>&man.service.8; can be used to start or stop a jail by hand,
>+      if an entry for it exists in
>+      <filename>rc.conf</filename>:</para>
>+
>+    <screen>&prompt.root; <userinput>service jail start <replaceable>www</replaceable></userinput>
>+&prompt.root; <userinput>service jail stop <replaceable>www</replaceable></userinput></screen>
>+
>+    <para>Jails can be shut down with &man.jexec.8;.  Use &man.jls.8;
>+      to identify the jail's <varname>JID</varname>, then use
>+      &man.jexec.8; to run the shutdown script in that jail.</para>
>+
>+    <screen>&prompt.root; <userinput>jls</userinput>
>+   JID  IP Address      Hostname                      Path
>+     3  192.168.0.10    www                           /usr/jail/www
>+&prompt.root; <userinput>jexec <replaceable>3</replaceable> /etc/rc.shutdown</userinput></screen>
>+
>+    <para>More information about this can be found in the &man.jail.8;
>+      manual page.</para>
>+  </sect1>
>+
>+  <sect1 xml:id="jails-tuning">
>+    <title>Fine Tuning and Administration</title>
>+
>+    <para>There are several options which can be set for any jail, and
>+      various ways of combining a host &os; system with jails, to
>+      produce higher level applications.  This section
>+      presents:</para>
>+
>+    <itemizedlist>
>+      <listitem>
>+	<para>Some of the options available for tuning the behavior
>+	  and security restrictions implemented by a jail
>+	  installation.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>Some of the high-level applications for jail management,
>+	  which are available through the &os; Ports Collection, and
>+	  can be used to implement overall jail-based
>+	  solutions.</para>
>+      </listitem>
>+    </itemizedlist>
>+
>+    <sect2 xml:id="jails-tuning-utilities">
>+      <title>System Tools for Jail Tuning in &os;</title>
>+
>+      <para>Fine tuning of a jail's configuration is mostly done by
>+	setting &man.sysctl.8; variables.  A special subtree of sysctl
>+	exists as a basis for organizing all the relevant options: the
>+	<varname>security.jail.*</varname> hierarchy of &os; kernel
>+	options.  Here is a list of the main jail-related sysctls,
>+	complete with their default value.  Names should be
>+	self-explanatory, but for more information about them, please
>+	refer to the &man.jail.8; and &man.sysctl.8; manual
>+	pages.</para>
>+
>+      <itemizedlist>
>+	<listitem>
>+	  <para><varname>security.jail.set_hostname_allowed:
>+	      1</varname></para>
>+	</listitem>
>+
>+	<listitem>
>+	  <para><varname>security.jail.socket_unixiproute_only:
>+	      1</varname></para>
>+	</listitem>
>+
>+	<listitem>
>+	  <para><varname>security.jail.sysvipc_allowed:
>+	      0</varname></para>
>+	</listitem>
>+
>+	<listitem>
>+	  <para><varname>security.jail.enforce_statfs:
>+	      2</varname></para>
>+	</listitem>
>+
>+	<listitem>
>+	  <para><varname>security.jail.allow_raw_sockets:
>+	      0</varname></para>
>+	</listitem>
>+
>+	<listitem>
>+	  <para><varname>security.jail.chflags_allowed:
>+	      0</varname></para>
>+	</listitem>
>+
>+	<listitem>
>+	  <para><varname>security.jail.jailed: 0</varname></para>
>+	</listitem>
>+      </itemizedlist>
>+
>+      <para>These variables can be used by the system administrator of
>+	the <emphasis>host system</emphasis> to add or remove some of
>+	the limitations imposed by default on the <systemitem
>+	  class="username">root</systemitem> user.  Note that there
>+	are some limitations which cannot be removed.  The
>+	<systemitem class="username">root</systemitem> user is not
>+	allowed to mount or unmount file systems from within a
>+	&man.jail.8;.  The <systemitem
>+	  class="username">root</systemitem> inside a jail may not
>+	load or unload &man.devfs.8; rulesets, set firewall rules, or
>+	do many other administrative tasks which require modifications
>+	of in-kernel data, such as setting the
>+	<varname>securelevel</varname> of the kernel.</para>
>+
>+      <para>The base system of &os; contains a basic set of tools for
>+	viewing information about the active jails, and attaching to a
>+	jail to run administrative commands.  The &man.jls.8; and
>+	&man.jexec.8; commands are part of the base &os; system, and
>+	can be used to perform the following simple tasks:</para>
>+
>+      <itemizedlist>
>+	<listitem>
>+	  <para>Print a list of active jails and their corresponding
>+	    jail identifier (<acronym>JID</acronym>),
>+	    <acronym>IP</acronym> address, hostname and path.</para>
>+	</listitem>
>+
>+	<listitem>
>+	  <para>Attach to a running jail, from its host system, and
>+	    run a command inside the jail or perform administrative
>+	    tasks inside the jail itself.  This is especially useful
>+	    when the <systemitem class="username">root</systemitem>
>+	    user wants to cleanly shut down a jail.  The &man.jexec.8;
>+	    utility can also be used to start a shell in a jail to do
>+	    administration in it; for example:</para>
>+
>+	  <screen>&prompt.root; <userinput>jexec <replaceable>1</replaceable> tcsh</userinput></screen>
>+	</listitem>
>+      </itemizedlist>
>+    </sect2>
>+
>+    <sect2 xml:id="jails-tuning-admintools">
>+      <title>High-Level Administrative Tools in the &os; Ports
>+	Collection</title>
>+
>+      <para>Among the many third-party utilities for jail
>+	administration, one of the most complete and useful is
>+	<package>sysutils/ezjail</package>.  It is a set of scripts
>+	that contribute to &man.jail.8; management.  Please refer to
>+	<link xlink:href="&url.books.handbook;/jails-ezjail.html">the
>+	  handbook section on <application>ezjail</application></link>
>+	for more information.</para>
>+    </sect2>
>+
>+    <sect2 xml:id="jails-updating">
>+      <title>Keeping Jails Patched and up to Date</title>
>+
>+      <para>Jails should be kept up to date from the host operating
>+	system as attempting to patch userland from within the jail
>+	may likely fail as the default behaviour in FreeBSD is to
>+	disallow the use of &man.chflags.1; in a jail which prevents
>+	the replacement of some files.  It is possible to change this
>+	behavior but it is recommended to use &man.freebsd-update.8;
>+	to maintain jails instead.  Use <option>-b</option> to specify
>+	the path of the jail to be updated.</para>
>+
>+      <screen>&prompt.root; <userinput>freebsd-update -b <replaceable>/here/is/the/jail</replaceable> fetch</userinput>
>+&prompt.root; <userinput>freebsd-update -b <replaceable>/here/is/the/jail</replaceable> install</userinput></screen>
>+    </sect2>
>+  </sect1>
>+
>+  <sect1 xml:id="jails-application">
>+    <info>
>+      <title>Updating Multiple Jails</title>
>+
>+      <authorgroup>
>+	<author>
>+	  <personname>
>+	    <firstname>Daniel</firstname>
>+	    <surname>Gerzo</surname>
>+	  </personname>
>+	  <contrib>Contributed by </contrib>
>+	</author>
>+      </authorgroup>
>+      <authorgroup>
>+	<author>
>+	  <personname>
>+	    <firstname>Simon</firstname>
>+	    <surname>L. B. Nielsen</surname>
>+	  </personname>
>+	  <contrib>Based upon an idea presented by </contrib>
>+	</author>
>+      </authorgroup>
>+      <authorgroup>
>+	<author>
>+	  <personname>
>+	    <firstname>Ken</firstname>
>+	    <surname>Tom</surname>
>+	  </personname>
>+	  <contrib>And an article written by </contrib>
>+	</author>
>+      </authorgroup>
>+    </info>
>+
>+    <para>The management of multiple jails can become problematic
>+      because every jail has to be rebuilt from scratch whenever it is
>+      upgraded.  This can be time consuming and tedious if a lot of
>+      jails are created and manually updated.</para>
>+
>+    <para>This section demonstrates one method to resolve this issue
>+      by safely sharing as much as is possible between jails using
>+      read-only &man.mount.nullfs.8; mounts, so that updating is
>+      simpler.  This makes it more attractive to put single services,
>+      such as <acronym>HTTP</acronym>, <acronym>DNS</acronym>, and
>+      <acronym>SMTP</acronym>, into individual jails.  Additionally,
>+      it provides a simple way to add, remove, and upgrade
>+      jails.</para>
>+
>+    <note>
>+      <para>Simpler solutions exist, such as
>+	<application>ezjail</application>, which provides an easier
>+	method of administering &os; jails but is less versatile than
>+	this setup.  <application>ezjail</application> is covered in
>+	more detail in <xref linkend="jails-ezjail"/>.</para>
>+    </note>
>+
>+    <para>The goals of the setup described in this section are:</para>
>+
>+    <itemizedlist>
>+      <listitem>
>+	<para>Create a simple and easy to understand jail structure
>+	  that does not require running a full installworld on each
>+	  and every jail.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>Make it easy to add new jails or remove existing
>+	  ones.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>Make it easy to update or upgrade existing jails.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>Make it possible to run a customized &os; branch.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>Be paranoid about security, reducing as much as
>+	  possible the possibility of compromise.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>Save space and inodes, as much as possible.</para>
>+      </listitem>
>+    </itemizedlist>
>+
>+    <para>This design relies on a single, read-only master template
>+      which is mounted into each jail and one read-write device per
>+      jail.  A device can be a separate physical disc, a partition, or
>+      a vnode backed memory device.  This example uses read-write
>+      <application>nullfs</application> mounts.</para>
>+
>+    <para>The file system layout is as follows:</para>
>+
>+    <itemizedlist>
>+      <listitem>
>+	<para>The jails are based under the
>+	  <filename>/home</filename> partition.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>Each jail will be mounted under the
>+	  <filename>/home/j</filename> directory.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>The template for each jail and the read-only partition
>+	  for  all of the jails is
>+	  <filename>/home/j/mroot</filename>.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>A blank directory will be created for each jail under
>+	  the <filename>/home/j</filename> directory.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>Each jail will have a <filename>/s</filename> directory
>+	  that will be linked to the read-write portion of the
>+	  system.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>Each jail will have its own read-write system that is
>+	  based upon <filename>/home/j/skel</filename>.</para>
>+      </listitem>
>+
>+      <listitem>
>+	<para>The read-write portion of each jail will be created in
>+	  <filename>/home/js</filename>.</para>
>+      </listitem>
>+    </itemizedlist>
>+
>+	
>+
>+    <sect2 xml:id="jails-service-jails-template">
>+      <title>Creating the Template</title>
>+
>+      <para>This section describes the steps needed to create the
>+	master template.</para>
>+
>+      <para>It is recommended to first update the host &os; system to
>+	the latest -RELEASE branch using the instructions in <xref
>+	  linkend="makeworld"/>.  Additionally, this template uses the
>+	<package>sysutils/cpdup</package> package or port and
>+	<application>portsnap</application> will be used to download
>+	the &os; Ports Collection.</para>
>+
>+      <procedure>
>+	<step>
>+	  <para>First, create a directory structure for the read-only
>+	    file system which will contain the &os; binaries for the
>+	    jails.  Then, change directory to the &os; source tree and
>+	    install the read-only file system to the jail
>+	    template:</para>
>+
>+	  <screen>&prompt.root; <userinput>mkdir /home/j /home/j/mroot</userinput>
>+&prompt.root; <userinput>cd /usr/src</userinput>
>+&prompt.root; <userinput>make installworld DESTDIR=/home/j/mroot</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>Next, prepare a &os; Ports Collection for the jails as
>+	    well as a &os; source tree, which is required for
>+	    <application>mergemaster</application>:</para>
>+
>+	  <screen>&prompt.root; <userinput>cd /home/j/mroot</userinput>
>+&prompt.root; <userinput>mkdir usr/ports</userinput>
>+&prompt.root; <userinput>portsnap -p /home/j/mroot/usr/ports fetch extract</userinput>
>+&prompt.root; <userinput>cpdup /usr/src /home/j/mroot/usr/src</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>Create a skeleton for the read-write portion of the
>+	    system:</para>
>+
>+	  <screen>&prompt.root; <userinput>mkdir /home/j/skel /home/j/skel/home /home/j/skel/usr-X11R6 /home/j/skel/distfiles</userinput>
>+&prompt.root; <userinput>mv etc /home/j/skel</userinput>
>+&prompt.root; <userinput>mv usr/local /home/j/skel/usr-local</userinput>
>+&prompt.root; <userinput>mv tmp /home/j/skel</userinput>
>+&prompt.root; <userinput>mv var /home/j/skel</userinput>
>+&prompt.root; <userinput>mv root /home/j/skel</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>Use <application>mergemaster</application> to install
>+	    missing configuration files.  Then, remove the extra
>+	    directories that <application>mergemaster</application>
>+	    creates:</para>
>+
>+	  <screen>&prompt.root; <userinput>mergemaster -t /home/j/skel/var/tmp/temproot -D /home/j/skel -i</userinput>
>+&prompt.root; <userinput>cd /home/j/skel</userinput>
>+&prompt.root; <userinput>rm -R bin boot lib libexec mnt proc rescue sbin sys usr dev</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>Now, symlink the read-write file system to the
>+	    read-only file system.  Ensure that the symlinks are
>+	    created in the correct <filename>s/</filename> locations
>+	    as the creation of directories in the wrong locations will
>+	    cause the installation to fail.</para>
>+
>+	  <screen>&prompt.root; <userinput>cd /home/j/mroot</userinput>
>+&prompt.root; <userinput>mkdir s</userinput>
>+&prompt.root; <userinput>ln -s s/etc etc</userinput>
>+&prompt.root; <userinput>ln -s s/home home</userinput>
>+&prompt.root; <userinput>ln -s s/root root</userinput>
>+&prompt.root; <userinput>ln -s s/usr-local usr/local</userinput>
>+&prompt.root; <userinput>ln -s s/usr-X11R6 usr/X11R6</userinput>
>+&prompt.root; <userinput>ln -s s/distfiles usr/ports/distfiles</userinput>
>+&prompt.root; <userinput>ln -s s/tmp tmp</userinput>
>+&prompt.root; <userinput>ln -s s/var var</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>As a last step, create a generic
>+	    <filename>/home/j/skel/etc/make.conf</filename> containing
>+	    this line:</para>
>+
>+	  <programlisting>WRKDIRPREFIX?=  /s/portbuild</programlisting>
>+
>+	  <para>This makes it possible to compile &os; ports inside
>+	    each jail.  Remember that the ports directory is part of
>+	    the read-only system.  The custom path for
>+	    <literal>WRKDIRPREFIX</literal> allows builds to be done
>+	    in the read-write portion of every jail.</para>
>+	</step>
>+      </procedure>
>+    </sect2>
>+
>+    <sect2 xml:id="jails-service-jails-creating">
>+      <title>Creating Jails</title>
>+
>+      <para>The jail template can now be used to setup and configure
>+	the jails in <filename>/etc/rc.conf</filename>.  This example
>+	demonstrates the creation of 3 jails: <literal>NS</literal>,
>+	<literal>MAIL</literal> and <literal>WWW</literal>.</para>
>+
>+      <procedure>
>+	<step>
>+	  <para>Add the following lines to
>+	    <filename>/etc/fstab</filename>, so that the read-only
>+	    template for the jails and the read-write space will be
>+	    available in the respective jails:</para>
>+
>+	  <programlisting>/home/j/mroot   /home/j/ns     nullfs  ro  0   0
>+/home/j/mroot   /home/j/mail   nullfs  ro  0   0
>+/home/j/mroot   /home/j/www    nullfs  ro  0   0
>+/home/js/ns     /home/j/ns/s   nullfs  rw  0   0
>+/home/js/mail   /home/j/mail/s nullfs  rw  0   0
>+/home/js/www    /home/j/www/s  nullfs  rw  0   0</programlisting>
>+
>+	  <para>To prevent
>+	    <application>fsck</application> from checking
>+	    <application>nullfs</application> mounts during boot and
>+	    <application>dump</application> from backing up the
>+	    read-only nullfs mounts of the jails, the last two
>+	    columns are both set to <literal>0</literal>.</para>
>+	</step>
>+
>+	<step>
>+	  <para>Configure the jails in
>+	    <filename>/etc/rc.conf</filename>:</para>
>+
>+	  <programlisting>jail_enable="YES"
>+jail_set_hostname_allow="NO"
>+jail_list="ns mail www"
>+jail_ns_hostname="ns.example.org"
>+jail_ns_ip="192.168.3.17"
>+jail_ns_rootdir="/usr/home/j/ns"
>+jail_ns_devfs_enable="YES"
>+jail_mail_hostname="mail.example.org"
>+jail_mail_ip="192.168.3.18"
>+jail_mail_rootdir="/usr/home/j/mail"
>+jail_mail_devfs_enable="YES"
>+jail_www_hostname="www.example.org"
>+jail_www_ip="62.123.43.14"
>+jail_www_rootdir="/usr/home/j/www"
>+jail_www_devfs_enable="YES"</programlisting>
>+
>+	  <para>The
>+	    <varname>jail_<replaceable>name</replaceable>_rootdir</varname>
>+	    variable is set to
>+	    <filename>/usr/home</filename> instead
>+	    of <filename>/home</filename> because
>+	    the physical path of <filename
>+	      >/home</filename> on a default &os;
>+	    installation is <filename
>+	      >/usr/home</filename>.  The
>+	    <varname>jail_<replaceable>name</replaceable>_rootdir</varname>
>+	    variable must <emphasis>not</emphasis> be set to a path
>+	    which includes a symbolic link, otherwise the jails will
>+	    refuse to start.</para>
>+	</step>
>+
>+	<step>
>+	  <para>Create the required mount points for the read-only
>+	    file system of each jail:</para>
>+
>+	  <screen>&prompt.root; <userinput>mkdir /home/j/ns /home/j/mail /home/j/www</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>Install the read-write template into each jail using
>+	    <package>sysutils/cpdup</package>:</para>
>+	    
>+
>+	  <screen>&prompt.root; <userinput>mkdir /home/js</userinput>
>+&prompt.root; <userinput>cpdup /home/j/skel /home/js/ns</userinput>
>+&prompt.root; <userinput>cpdup /home/j/skel /home/js/mail</userinput>
>+&prompt.root; <userinput>cpdup /home/j/skel /home/js/www</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>In this phase, the jails are built and prepared to
>+	    run.  First, mount the required file systems for each
>+	    jail, and then start them:</para>
>+
>+	  <screen>&prompt.root; <userinput>mount -a</userinput>
>+&prompt.root; <userinput>service jail start</userinput></screen>
>+	</step>
>+      </procedure>
>+
>+      <para>The jails should be running now.  To check if they have
>+	started correctly, use <command>jls</command>.  Its output
>+	should be similar to the following:</para>
>+
>+      <screen>&prompt.root; <userinput>jls</userinput>
>+   JID  IP Address      Hostname                      Path
>+     3  192.168.3.17    ns.example.org                /home/j/ns
>+     2  192.168.3.18    mail.example.org              /home/j/mail
>+     1  62.123.43.14    www.example.org               /home/j/www</screen>
>+
>+      <para>At this point, it should be possible to log onto each
>+	jail, add new users, or configure daemons.  The
>+	<literal>JID</literal> column indicates the jail
>+	identification number of each running jail.  Use the following
>+	command to perform administrative tasks in the jail whose
>+	<acronym>JID</acronym> is <literal>3</literal>:</para>
>+
>+      <screen>&prompt.root; <userinput>jexec 3 tcsh</userinput></screen>
>+    </sect2>
>+
>+    <sect2 xml:id="jails-service-jails-upgrading">
>+      <title>Upgrading</title>
>+
>+      <para>The design of this setup provides an easy way to upgrade
>+	existing jails while minimizing their downtime.  Also, it
>+	provides a way to roll back to the older version should a
>+	problem occur.</para>
>+
>+      <procedure>
>+	<step>
>+	  <para>The first step is to upgrade the host system.  Then,
>+	    create a new temporary read-only template in
>+	    <filename>/home/j/mroot2</filename>.</para>
>+
>+	  <screen>&prompt.root; <userinput>mkdir /home/j/mroot2</userinput>
>+&prompt.root; <userinput>cd /usr/src</userinput>
>+&prompt.root; <userinput>make installworld DESTDIR=/home/j/mroot2</userinput>
>+&prompt.root; <userinput>cd /home/j/mroot2</userinput>
>+&prompt.root; <userinput>cpdup /usr/src usr/src</userinput>
>+&prompt.root; <userinput>mkdir s</userinput></screen>
>+
>+	  <para>The <buildtarget>installworld</buildtarget> creates a
>+	    few unnecessary directories, which should be
>+	    removed:</para>
>+
>+	  <screen>&prompt.root; <userinput>chflags -R 0 var</userinput>
>+&prompt.root; <userinput>rm -R etc var root usr/local tmp</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>Recreate the read-write symlinks for the master file
>+	    system:</para>
>+
>+	  <screen>&prompt.root; <userinput>ln -s s/etc etc</userinput>
>+&prompt.root; <userinput>ln -s s/root root</userinput>
>+&prompt.root; <userinput>ln -s s/home home</userinput>
>+&prompt.root; <userinput>ln -s ../s/usr-local usr/local</userinput>
>+&prompt.root; <userinput>ln -s ../s/usr-X11R6 usr/X11R6</userinput>
>+&prompt.root; <userinput>ln -s s/tmp tmp</userinput>
>+&prompt.root; <userinput>ln -s s/var var</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>Next, stop the jails:</para>
>+
>+	  <screen>&prompt.root; <userinput>service jail stop</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>Unmount the original file systems as the read-write
>+	    systems are attached to the read-only system
>+	    (<filename>/s</filename>):</para>
>+	    
>+
>+	  <screen>&prompt.root; <userinput>umount /home/j/ns/s</userinput>
>+&prompt.root; <userinput>umount /home/j/ns</userinput>
>+&prompt.root; <userinput>umount /home/j/mail/s</userinput>
>+&prompt.root; <userinput>umount /home/j/mail</userinput>
>+&prompt.root; <userinput>umount /home/j/www/s</userinput>
>+&prompt.root; <userinput>umount /home/j/www</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>Move the old read-only file system and replace it with
>+	    the new one.  This will serve as a backup and archive of
>+	    the old read-only file system should something go wrong.
>+	    The naming convention used here corresponds to when a new
>+	    read-only file system has been created.  Move the original
>+	    &os; Ports Collection over to the new file system to save
>+	    some space and inodes:</para>
>+
>+	  <screen>&prompt.root; <userinput>cd /home/j</userinput>
>+&prompt.root; <userinput>mv mroot mroot.20060601</userinput>
>+&prompt.root; <userinput>mv mroot2 mroot</userinput>
>+&prompt.root; <userinput>mv mroot.20060601/usr/ports mroot/usr</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>At this point the new read-only template is ready, so
>+	    the only remaining task is to remount the file systems and
>+	    start the jails:</para>
>+
>+	  <screen>&prompt.root; <userinput>mount -a</userinput>
>+&prompt.root; <userinput>service jail start</userinput></screen>
>+	</step>
>+      </procedure>
>+
>+      <para>Use <command>jls</command> to check if the jails started
>+	correctly.  Run <command>mergemaster</command> in each jail to
>+	update the configuration files.</para>
>+    </sect2>
>+  </sect1>
>+
>+  <sect1 xml:id="jails-ezjail">
>+    <info>
>+      <title>Managing Jails with
>+	<application>ezjail</application></title>
>+
>+      <authorgroup>
>+	<author>
>+	  <personname>
>+	    <firstname>Warren</firstname>
>+	    <surname>Block</surname>
>+	  </personname><contrib>Originally contributed by </contrib>
>+	</author>
>+      </authorgroup>
>+    </info>
>+
>+    <para>Creating and managing multiple jails can quickly become
>+      tedious and error-prone.  Dirk Engling's
>+      <application>ezjail</application> automates and greatly
>+      simplifies many jail tasks.  A <emphasis>basejail</emphasis> is
>+      created as a template.  Additional jails use
>+      &man.mount.nullfs.8; to share many of the basejail directories
>+      without using additional disk space.  Each additional jail takes
>+      only a few megabytes of disk space before applications are
>+      installed.  Upgrading the copy of the userland in the basejail
>+      automatically upgrades all of the other jails.</para>
>+
>+    <para>Additional benefits and features are described in detail on
>+      the <application>ezjail</application> web site, <link
>+	xlink:href="https://erdgeist.org/arts/software/ezjail/"></link>.</para>
>+
>+    <sect2 xml:id="jails-ezjail-install">
>+      <title>Installing <application>ezjail</application></title>
>+
>+      <para>Installing <application>ezjail</application> consists of
>+	adding a loopback interface for use in jails, installing the
>+	port or package, and enabling the service.</para>
>+
>+      <procedure xml:id="jails-ezjail-install-procedure">
>+	<step>
>+	  <para>To keep jail loopback traffic off the host's loopback
>+	    network interface <literal>lo0</literal>, a second
>+	    loopback interface is created by adding an entry to
>+	    <filename>/etc/rc.conf</filename>:</para>
>+
>+	  <programlisting>cloned_interfaces="lo1"</programlisting>
>+
>+	  <para>The second loopback interface <literal>lo1</literal>
>+	    will be created when the system starts.  It can also be
>+	    created manually without a restart:</para>
>+
>+	  <screen>&prompt.root; <userinput>service netif cloneup</userinput>
>+Created clone interfaces: lo1.</screen>
>+
>+	  <para>Jails can be allowed to use aliases of this secondary
>+	    loopback interface without interfering with the
>+	    host.</para>
>+
>+	  <para>Inside a jail, access to the loopback address
>+	    <systemitem class="ipaddress">127.0.0.1</systemitem> is
>+	    redirected to the first <acronym>IP</acronym> address
>+	    assigned to the jail.  To make the jail loopback
>+	    correspond with the new <literal>lo1</literal> interface,
>+	    that interface must be specified first in the list of
>+	    interfaces and <acronym>IP</acronym> addresses given when
>+	    creating a new jail.</para>
>+
>+	  <para>Give each jail a unique loopback address in the
>+	    <systemitem
>+	      class="ipaddress">127.0.0.0</systemitem><systemitem
>+	      class="netmask">/8</systemitem> netblock.</para>
>+	</step>
>+
>+	<step>
>+	  <para>Install
>+	    <package role="port">sysutils/ezjail</package>:</para>
>+
>+	  <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/ezjail</userinput>
>+&prompt.root; <userinput>make install clean</userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>Enable <application>ezjail</application> by adding
>+	    this line to <filename>/etc/rc.conf</filename>:</para>
>+
>+	  <programlisting>ezjail_enable="YES"</programlisting>
>+	</step>
>+
>+	<step>
>+	  <para>The service will automatically start on system boot.
>+	    It can be started immediately for the current
>+	    session:</para>
>+
>+	  <screen>&prompt.root; <userinput>service ezjail start</userinput></screen>
>+	</step>
>+      </procedure>
>+    </sect2>
>+
>+    <sect2 xml:id="jails-ezjail-initialsetup">
>+      <title>Initial Setup</title>
>+
>+      <para>With <application>ezjail</application> installed, the
>+	basejail directory structure can be created and populated.
>+	This step is only needed once on the jail host
>+	computer.</para>
>+
>+      <para>In both of these examples, <option>-p</option> causes the
>+	ports tree to be retrieved with &man.portsnap.8; into the
>+	basejail.  That single copy of the ports directory will be
>+	shared by all the jails.  Using a separate copy of the ports
>+	directory for jails isolates them from the host.  The
>+	<application>ezjail</application> <acronym>FAQ</acronym>
>+	explains in more detail: <link
>+	  xlink:href="http://erdgeist.org/arts/software/ezjail/#FAQ"></link>.</para>
>+
>+      <procedure xml:id="jails-ezjail-initialsetup-procedure">
>+	<step>
>+	  <stepalternatives>
>+	    <step>
>+	      <title>To Populate the Jail with &os;-RELEASE</title>
>+
>+	      <para>For a basejail based on the &os; RELEASE matching
>+		that of the host computer, use
>+		<command>install</command>.  For example, on a host
>+		computer running &os;&nbsp;10-STABLE, the latest
>+		RELEASE version of &os;&nbsp;-10 will be installed in
>+		the jail):</para>
>+
>+	      <screen>&prompt.root; <userinput>ezjail-admin install -p</userinput></screen>
>+	    </step>
>+
>+	    <step>
>+	      <title>To Populate the Jail with
>+		<command>installworld</command></title>
>+
>+	      <para>The basejail can be installed from binaries
>+		created by <buildtarget>buildworld</buildtarget> on
>+		the host with
>+		<command>ezjail-admin update</command>.</para>
>+
>+	      <para>In this example, &os;&nbsp;10-STABLE has been
>+		built from source.  The jail directories are created.
>+		Then <buildtarget>installworld</buildtarget> is
>+		executed, installing the host's
>+		<filename>/usr/obj</filename> into the
>+		basejail.</para>
>+
>+	      <screen>&prompt.root; <userinput>ezjail-admin update -i -p</userinput></screen>
>+
>+	      <para>The host's <filename>/usr/src</filename> is used
>+		by default.  A different source directory on the host
>+		can be specified with <option>-s</option> and a path,
>+		or set with <varname>ezjail_sourcetree</varname> in
>+		<filename>/usr/local/etc/ezjail.conf</filename>.</para>
>+	    </step>
>+	  </stepalternatives>
>+	</step>
>+      </procedure>
>+
>+      <tip>
>+	<para>The basejail's ports tree is shared by other jails.
>+	  However, downloaded distfiles are stored in the jail that
>+	  downloaded them.  By default, these files are stored in
>+	  <filename>/var/ports/distfiles</filename> within each
>+	  jail.  <filename>/var/ports</filename> inside each jail is
>+	  also used as a work directory when building ports.</para>
>+      </tip>
>+    </sect2>
>+
>+    <sect2 xml:id="jails-ezjail-create">
>+      <title>Creating and Starting a New Jail</title>
>+
>+      <para>New jails are created with
>+	<command>ezjail-admin create</command>.  In these examples,
>+	the <literal>lo1</literal> loopback interface is used as
>+	described above.</para>
>+
>+      <procedure xml:id="jails-ezjail-create-steps">
>+	<title>Create and Start a New Jail</title>
>+
>+	<step>
>+	  <para>Create the jail, specifying a name and the loopback
>+	    and network interfaces to use, along with their
>+	    <acronym>IP</acronym> addresses.  In this example, the
>+	    jail is named <literal>dnsjail</literal>.</para>
>+
>+	  <screen>&prompt.root; <userinput>ezjail-admin create <replaceable>dnsjail</replaceable> '<replaceable>lo1|127.0.1.1</replaceable>,<replaceable>em0</replaceable>|<replaceable>192.168.1.50</replaceable>'</userinput></screen>
>+
>+	  <tip xml:id="jails-ezjail-raw-network-sockets">
>+	    <para>Most network services run in jails without
>+	      problems.  A few network services, most notably
>+	      &man.ping.8;, use
>+	      <emphasis>raw network sockets</emphasis>.  In jails, raw
>+	      network sockets are disabled by default for security.
>+	      Services that require them will not work.</para>
>+
>+	    <para>Occasionally, a jail genuinely needs raw sockets.
>+	      For example, network monitoring applications often use
>+	      &man.ping.8; to check the availability of other
>+	      computers.  When raw network sockets are actually needed
>+	      in a jail, they can be enabled by editing the
>+	      <application>ezjail</application>
>+	      configuration file for the individual jail,
>+	      <filename>/usr/local/etc/ezjail/<replaceable>jailname</replaceable></filename>.
>+	      Modify the <literal>parameters</literal>
>+	      entry:</para>
>+
>+	    <programlisting>export jail_<replaceable>jailname</replaceable>_parameters="allow.raw_sockets=1"</programlisting>
>+
>+	    <para>Do not enable raw network sockets unless services in
>+	      the jail actually require them.</para>
>+	  </tip>
>+	</step>
>+
>+	<step>
>+	  <para>Start the jail:</para>
>+
>+	  <screen>&prompt.root; <userinput>ezjail-admin start <replaceable>dnsjail</replaceable></userinput></screen>
>+	</step>
>+
>+	<step>
>+	  <para>Use a console on the jail:</para>
>+
>+	  <screen>&prompt.root; <userinput>ezjail-admin console <replaceable>dnsjail</replaceable></userinput></screen>
>+	</step>
>+      </procedure>
>+
>+      <para>The jail is operating and additional configuration can be
>+	completed.  Typical settings added at this point
>+	include:</para>
>+
>+      <procedure>
>+	<step>
>+	  <title>Set the
>+	    <systemitem class="username">root</systemitem>
>+	    Password</title>
>+
>+	  <para>Connect to the jail and set the
>+	    <systemitem class="username">root</systemitem> user's
>+	    password:</para>
>+
>+	  <screen>&prompt.root; <userinput>ezjail-admin console <replaceable>dnsjail</replaceable></userinput>
>+&prompt.root; <userinput>passwd</userinput>
>+Changing local password for root
>+New Password:
>+Retype New Password:</screen>
>+	</step>
>+
>+	<step>
>+	  <title>Time Zone Configuration</title>
>+
>+	  <para>The jail's time zone can be set with &man.tzsetup.8;.
>+	    To avoid spurious error messages, the &man.adjkerntz.8;
>+	    entry in <filename>/etc/crontab</filename> can be
>+	    commented or removed.  This job attempts to update the
>+	    computer's hardware clock with time zone changes, but
>+	    jails are not allowed to access that hardware.</para>
>+	</step>
>+
>+	<step>
>+	  <title><acronym>DNS</acronym> Servers</title>
>+
>+	  <para>Enter domain name server lines in
>+	    <filename>/etc/resolv.conf</filename> so
>+	    <acronym>DNS</acronym> works in the jail.</para>
>+	</step>
>+
>+	<step>
>+	  <title>Edit <filename>/etc/hosts</filename></title>
>+
>+	  <para>Change the address and add the jail name to the
>+	    <literal>localhost</literal> entries in
>+	    <filename>/etc/hosts</filename>.</para>
>+	</step>
>+
>+	<step>
>+	  <title>Configure <filename>/etc/rc.conf</filename></title>
>+
>+	  <para>Enter configuration settings in
>+	    <filename>/etc/rc.conf</filename>.  This is much like
>+	    configuring a full computer.  The host name and
>+	    <acronym>IP</acronym> address are not set here.  Those
>+	    values are already provided by the jail
>+	    configuration.</para>
>+	</step>
>+      </procedure>
>+
>+      <para>With the jail configured, the applications for which the
>+	jail was created can be installed.</para>
>+
>+      <tip>
>+	<para>Some ports must be built with special options to be used
>+	  in a jail.  For example, both of the network monitoring
>+	  plugin packages
>+	  <package role="port">net-mgmt/nagios-plugins</package> and
>+	  <package role="port">net-mgmt/monitoring-plugins</package>
>+	  have a <literal>JAIL</literal> option which must be enabled
>+	  for them to work correctly inside a jail.</para>
>+      </tip>
>+    </sect2>
>+
>+    <sect2 xml:id="jails-ezjail-update">
>+      <title>Updating Jails</title>
>+
>+      <sect3 xml:id="jails-ezjail-update-os">
>+	<title>Updating the Operating System</title>
>+
>+	<para>Because the basejail's copy of the userland is shared by
>+	  the other jails, updating the basejail automatically updates
>+	  all of the other jails.  Either source or binary updates can
>+	  be used.</para>
>+
>+	<para>To build the world from source on the host, then
>+	  install it in the basejail, use:</para>
>+
>+	<screen>&prompt.root; <userinput>ezjail-admin update -b</userinput></screen>
>+
>+	<para>If the world has already been compiled on the host,
>+	  install it in the basejail with:</para>
>+
>+	<screen>&prompt.root; <userinput>ezjail-admin update -i</userinput></screen>
>+
>+	<para>Binary updates use &man.freebsd-update.8;.  These
>+	  updates have the same limitations as if
>+	  &man.freebsd-update.8; were being run directly.  The most
>+	  important one is that only -RELEASE versions of &os; are
>+	  available with this method.</para>
>+
>+	<para>Update the basejail to the latest patched release of
>+	  the version of &os; on the host.  For example, updating from
>+	  RELEASE-p1 to RELEASE-p2.</para>
>+
>+	<screen>&prompt.root; <userinput>ezjail-admin update -u</userinput></screen>
>+
>+	<para>To upgrade the basejail to a new version, first
>+	  upgrade the host system as described in <xref
>+	    linkend="freebsdupdate-upgrade" />.  Once the host has
>+	  been upgraded and rebooted, the basejail can then be
>+	  upgraded.  &man.freebsd-update.8; has no way of determining
>+	  which version is currently installed in the basejail, so the
>+	  original version must be specified.  Use &man.file.1; to
>+	  determine the original version in the basejail:</para>
>+
>+	<screen>&prompt.root; <userinput>file /usr/jails/basejail/bin/sh</userinput>
>+/usr/jails/basejail/bin/sh: ELF 64-bit LSB executable, x86-64, version 1 (FreeBSD), dynamically linked (uses shared libs), for FreeBSD 9.3, stripped</screen>
>+
>+	<para>Now use this information to perform the upgrade from
>+	  <literal>9.3-RELEASE</literal> to the current version of
>+	  the host system:</para>
>+
>+	<screen>&prompt.root; <userinput>ezjail-admin update -U -s <replaceable>9.3-RELEASE</replaceable></userinput></screen>
>+
>+	<para>After updating the basejail, &man.mergemaster.8; must
>+	  be run to update each jail's configuration files.</para>
>+
>+	<para>How to use &man.mergemaster.8; depends on the purpose
>+	  and trustworthiness of a jail.  If a jail's services or
>+	  users are not trusted, then &man.mergemaster.8; should only
>+	  be run from within that jail:</para>
>+
>+	<example xml:id="jails-ezjail-update-mergemaster-untrusted">
>+	  <title>&man.mergemaster.8; on Untrusted Jail</title>
>+
>+	  <para>Delete the link from the jail's
>+	    <filename>/usr/src</filename> into the basejail and
>+	    create a new <filename>/usr/src</filename> in the jail
>+	    as a mountpoint.  Mount the host computer's
>+	    <filename>/usr/src</filename> read-only on the jail's
>+	    new <filename>/usr/src</filename> mountpoint:</para>
>+
>+	  <screen>&prompt.root; <userinput>rm /usr/jails/<replaceable>jailname</replaceable>/usr/src</userinput>
>+&prompt.root; <userinput>mkdir /usr/jails/<replaceable>jailname</replaceable>/usr/src</userinput>
>+&prompt.root; <userinput>mount -t nullfs -o ro /usr/src /usr/jails/<replaceable>jailname</replaceable>/usr/src</userinput></screen>
>+
>+	  <para>Get a console in the jail:</para>
>+
>+	  <screen>&prompt.root; <userinput>ezjail-admin console <replaceable>jailname</replaceable></userinput></screen>
>+
>+	  <para>Inside the jail, run <command>mergemaster</command>.
>+	    Then exit the jail console:</para>
>+
>+	  <screen>&prompt.root; <userinput>cd /usr/src</userinput>
>+&prompt.root; <userinput>mergemaster -U</userinput>
>+&prompt.root; <userinput>exit</userinput></screen>
>+
>+	  <para>Finally, unmount the jail's
>+	    <filename>/usr/src</filename>:</para>
>+
>+	  <screen>&prompt.root; <userinput>umount /usr/jails/<replaceable>jailname</replaceable>/usr/src</userinput></screen>
>+	</example>
>+
>+	<example xml:id="jails-ezjail-update-mergemaster-trusted">
>+
>+	  <title>&man.mergemaster.8; on Trusted Jail</title>
>+
>+	  <para>If the users and services in a jail are trusted,
>+	    &man.mergemaster.8; can be run from the host:</para>
>+
>+	  <screen>&prompt.root; <userinput>mergemaster -U -D /usr/jails/<replaceable>jailname</replaceable></userinput></screen>
>+	</example>
>+      </sect3>
>+
>+      <sect3 xml:id="jails-ezjail-update-ports">
>+	<title>Updating Ports</title>
>+
>+	<para>The ports tree in the basejail is shared by the other
>+	  jails.  Updating that copy of the ports tree gives the other
>+	  jails the updated version also.</para>
>+
>+	<para>The basejail ports tree is updated with
>+	  &man.portsnap.8;:</para>
>+
>+	<screen>&prompt.root; <userinput>ezjail-admin update -P</userinput></screen>
>+      </sect3>
>+    </sect2>
>+
>+    <sect2 xml:id="jails-ezjail-control">
>+      <title>Controlling Jails</title>
>+
>+      <sect3 xml:id="jails-ezjail-control-stop-start">
>+	<title>Stopping and Starting Jails</title>
>+
>+	<para><application>ezjail</application> automatically starts
>+	  jails when the computer is started.  Jails can be manually
>+	  stopped and restarted with <command>stop</command> and
>+	  <command>start</command>:</para>
>+
>+	<screen>&prompt.root; <userinput>ezjail-admin stop <replaceable>sambajail</replaceable></userinput>
>+Stopping jails: sambajail.</screen>
>+
>+	<para>By default, jails are started automatically when the
>+	  host computer starts.  Autostarting can be disabled
>+	  with <command>config</command>:</para>
>+
>+	<screen>&prompt.root; <userinput>ezjail-admin config -r norun <replaceable>seldomjail</replaceable></userinput></screen>
>+
>+	<para>This takes effect the next time the host computer is
>+	  started.  A jail that is already running will not be
>+	  stopped.</para>
>+
>+	<para>Enabling autostart is very similar:</para>
>+
>+	<screen>&prompt.root; <userinput>ezjail-admin config -r run <replaceable>oftenjail</replaceable></userinput></screen>
>+      </sect3>
>+
>+      <sect3 xml:id="jails-ezjail-control-backup">
>+	<title>Archiving and Restoring Jails</title>
>+
>+	<para>Use <command>archive</command> to create a
>+	  <filename>.tar.gz</filename> archive of a jail.  The file
>+	  name is composed from the name of the jail and the current
>+	  date.  Archive files are written to the archive directory,
>+	  <filename>/usr/jails/ezjail_archives</filename>.  A
>+	  different archive directory can be chosen by setting
>+	  <varname>ezjail_archivedir</varname> in the configuration
>+	  file.</para>
>+
>+	<para>The archive file can be copied elsewhere as a backup, or
>+	  an existing jail can be restored from it with
>+	  <command>restore</command>.  A new jail can be created from
>+	  the archive, providing a convenient way to clone existing
>+	  jails.</para>
>+
>+	<para>Stop and archive a jail named
>+	  <literal>wwwserver</literal>:</para>
>+
>+	<screen>&prompt.root; <userinput>ezjail-admin stop <replaceable>wwwserver</replaceable></userinput>
>+Stopping jails: wwwserver.
>+&prompt.root; <userinput>ezjail-admin archive <replaceable>wwwserver</replaceable></userinput>
>+&prompt.root; <userinput>ls /usr/jails/ezjail-archives/</userinput>
>+wwwserver-201407271153.13.tar.gz</screen>
>+
>+	<para>Create a new jail named
>+	  <literal>wwwserver-clone</literal> from the archive created
>+	  in the previous step.  Use the <filename>em1</filename>
>+	  interface and assign a new <acronym>IP</acronym> address to
>+	  avoid conflict with the original:</para>
>+
>+	<screen>&prompt.root; <userinput>ezjail-admin create -a /usr/jails/ezjail_archives/wwwserver-201407271153.13.tar.gz <replaceable>wwwserver-clone</replaceable> 'lo1|127.0.3.1,em1|192.168.1.51'</userinput></screen>
>+      </sect3>
>+    </sect2>
>+
>+    <sect2 xml:id="jails-ezjail-example-bind">
>+      <title>Full Example: <application>BIND</application> in a
>+	Jail</title>
>+
>+      <para>Putting the <application>BIND</application>
>+	<acronym>DNS</acronym> server in a jail improves security by
>+	isolating it.  This example creates a simple caching-only name
>+	server.</para>
>+
>+      <itemizedlist xml:id="jails-ezjail-example-bind-assumptions">
>+	<listitem>
>+	  <para>The jail will be called
>+	    <literal>dns1</literal>.</para>
>+	</listitem>
>+
>+	<listitem>
>+	  <para>The jail will use <acronym>IP</acronym> address
>+	    <literal>192.168.1.240</literal> on the host's
>+	    <literal>re0</literal> interface.</para>
>+	</listitem>
>+
>+	<listitem>
>+	  <para>The upstream <acronym>ISP</acronym>'s DNS servers are
>+	    at <literal>10.0.0.62</literal> and
>+	    <literal>10.0.0.61</literal>.</para>
>+	</listitem>
>+
>+	<listitem>
>+	  <para>The basejail has already been created and a ports tree
>+	    installed.</para>
>+	</listitem>
>+      </itemizedlist>
>+
>+      <example xml:id="jails-ezjail-example-bind-steps">
>+	<title>Running BIND in a Jail</title>
>+
>+	<para>Create a cloned loopback interface by adding a line to
>+	  <filename>/etc/rc.conf</filename>:</para>
>+
>+	<programlisting>cloned_interfaces="lo1"</programlisting>
>+
>+	<para>Immediately create the new loopback interface:</para>
>+
>+	<screen>&prompt.root; <userinput>service netif cloneup</userinput>
>+Created clone interfaces: lo1.</screen>
>+
>+	<para>Create the jail:</para>
>+
>+	<screen>&prompt.root; <userinput>ezjail-admin create dns1 'lo1|127.0.2.1,re0|192.168.1.240'</userinput></screen>
>+
>+	<para>Start the jail, connect to a console running on it, and
>+	  perform some basic configuration:</para>
>+
>+	<screen>&prompt.root; <userinput>ezjail-admin start dns1</userinput>
>+&prompt.root; <userinput>ezjail-admin console dns1</userinput>
>+&prompt.root; <userinput>passwd</userinput>
>+Changing local password for root
>+New Password:
>+Retype New Password:
>+&prompt.root; <userinput>tzsetup</userinput>
>+&prompt.root; <userinput>sed -i .bak -e '/adjkerntz/ s/^/#/' /etc/crontab</userinput>
>+&prompt.root; <userinput>sed -i .bak -e 's/127.0.0.1/127.0.2.1/g; s/localhost.my.domain/dns1.my.domain dns1/' /etc/hosts</userinput></screen>
>+
>+	<para>Temporarily set the upstream <acronym>DNS</acronym>
>+	  servers in <filename>/etc/resolv.conf</filename> so ports
>+	  can be downloaded:</para>
>+
>+	<programlisting>nameserver 10.0.0.62
>+nameserver 10.0.0.61</programlisting>
>+
>+	<para>Still using the jail console, install
>+	  <package role="port">dns/bind99</package>.</para>
>+
>+	<screen>&prompt.root; <userinput>make -C /usr/ports/dns/bind99 install clean</userinput></screen>
>+
>+	<para>Configure the name server by editing
>+	  <filename>/usr/local/etc/namedb/named.conf</filename>.</para>
>+
>+	<para>Create an Access Control List (<acronym>ACL</acronym>)
>+	  of addresses and networks that are permitted to send
>+	  <acronym>DNS</acronym> queries to this name server.  This
>+	  section is added just before the <literal>options</literal>
>+	  section already in the file:</para>
>+
>+	<programlisting>...
>+// or cause huge amounts of useless Internet traffic.
>+
>+acl "trusted" {
>+	192.168.1.0/24;
>+	localhost;
>+	localnets;
>+};
>+
>+options {
>+...</programlisting>
>+
>+	<para>Use the jail <acronym>IP</acronym> address in the
>+	  <literal>listen-on</literal> setting to accept
>+	  <acronym>DNS</acronym> queries from other computers on the
>+	  network:</para>
>+
>+	<programlisting>	listen-on	{ 192.168.1.240; };</programlisting>
>+
>+	<para>A simple caching-only <acronym>DNS</acronym> name server
>+	  is created by changing the <literal>forwarders</literal>
>+	  section.  The original file contains:</para>
>+
>+	<programlisting>/*
>+	forwarders {
>+		127.0.0.1;
>+	};
>+*/</programlisting>
>+
>+	<para>Uncomment the section by removing the
>+	  <literal>/*</literal> and <literal>*/</literal> lines.
>+	  Enter the <acronym>IP</acronym> addresses of the upstream
>+	  <acronym>DNS</acronym> servers.  Immediately after the
>+	  <literal>forwarders</literal> section, add references to the
>+	  <literal>trusted</literal> <acronym>ACL</acronym> defined
>+	  earlier:</para>
>+
>+	<programlisting>	forwarders {
>+		10.0.0.62;
>+		10.0.0.61;
>+	};
>+
>+	allow-query       { any; };
>+	allow-recursion   { trusted; };
>+	allow-query-cache { trusted; };</programlisting>
>+
>+	<para>Enable the service in
>+	  <filename>/etc/rc.conf</filename>:</para>
>+
>+	<programlisting>named_enable="YES"</programlisting>
>+
>+	<para>Start and test the name server:</para>
>+
>+	<screen>&prompt.root; <userinput>service named start</userinput>
>+wrote key file "/usr/local/etc/namedb/rndc.key"
>+Starting named.
>+&prompt.root; <userinput>/usr/local/bin/dig @192.168.1.240 freebsd.org</userinput></screen>
>+
>+	<para>A response that includes</para>
>+
>+	<screen>;; Got answer;</screen>
>+
>+	<para>shows that the new <acronym>DNS</acronym> server is
>+	  working.  A long delay followed by a response
>+	  including</para>
>+
>+	<screen>;; connection timed out; no servers could be reached</screen>
>+
>+	<para>shows a problem.  Check the configuration settings and
>+	  make sure any local firewalls allow the new
>+	  <acronym>DNS</acronym> access to the upstream
>+	  <acronym>DNS</acronym> servers.</para>
>+
>+	<para>The new <acronym>DNS</acronym> server can use itself for
>+	  local name resolution, just like other local computers.  Set
>+	  the address of the <acronym>DNS</acronym> server in the
>+	  client computer's
>+	  <filename>/etc/resolv.conf</filename>:</para>
>+
>+	<programlisting>nameserver 192.168.1.240</programlisting>
>+
>+	<para>A local <acronym>DHCP</acronym> server can be configured
>+	  to provide this address for a local <acronym>DNS</acronym>
>+	  server, providing automatic configuration on
>+	  <acronym>DHCP</acronym> clients.</para>
>+      </example>
>+    </sect2>
>+  </sect1>
>+</chapter>

Actions: View | Diff

Attachments on bug 207344: 167190