svn commit: r44517 - head/en_US.ISO8859-1/books/handbook/jails

Dru Lavigne dru at
Thu Apr 10 15:07:30 UTC 2014

Author: dru
Date: Thu Apr 10 15:07:29 2014
New Revision: 44517

  Rename Service Jails to a more descriptive Updating Multiple Jails.
  Editorial review of this section.
  It still needs to address PR168939 and the comments in this section.
  Sponsored by:	iXsystems


Modified: head/en_US.ISO8859-1/books/handbook/jails/chapter.xml
--- head/en_US.ISO8859-1/books/handbook/jails/chapter.xml	Thu Apr 10 07:19:02 2014	(r44516)
+++ head/en_US.ISO8859-1/books/handbook/jails/chapter.xml	Thu Apr 10 15:07:29 2014	(r44517)
@@ -470,61 +470,55 @@ jail_<replaceable>www</replaceable>_devf
   <sect1 xml:id="jails-application">
-    <title>Application of Jails</title>
+    <info>
+    <title>Updating Multiple Jails</title>
-    <sect2 xml:id="jails-service-jails">
-      <info><title>Service Jails</title>
 	  <author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname><contrib>Contributed by </contrib></author>
+	<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>
-      <para>This section is based upon an idea originally presented by
-	&; at <uri xlink:href=""></uri>, and
-	an updated article written by Ken Tom
-	<email>locals at</email>.  This section illustrates how
-	to set up a &os; system that adds an additional layer of
-	security, using the &man.jail.8; feature.  It is also assumed
-	that the given system is at least running RELENG_6_0 and the
-	information provided earlier in this chapter has been well
-	understood.</para>
-      <sect3 xml:id="jails-service-jails-design">
-	<title>Design</title>
-	<para>One of the major problems with jails is the management
-	  of their upgrade process.  This tends to be a problem
+	<para>The management of multiple jails can become
+	  problematic
 	  because every jail has to be rebuilt from scratch whenever
-	  it is updated.  This is usually not a problem for a single
-	  jail, since the update process is fairly simple, but can be
-	  quite time consuming and tedious if a lot of jails are
-	  created.</para>
-	<warning>
-	  <para>This setup requires advanced experience with &os; and
-	    usage of its features.  If the presented steps below look
-	    too complicated, it is advised to take a look at a simpler
-	    system such as
+	  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
 	    <package>sysutils/ezjail</package>, which
 	    provides an easier method of administering &os; jails and
 	    is not as sophisticated as this setup.</para>
-	</warning>
-	<para>This idea has been presented to resolve such issues by
-	  sharing as much as is possible between jails, in a safe way
-	  — using read-only &man.mount.nullfs.8; mounts, so that
-	  updating will be simpler, and putting single services into
-	  individual jails will become more attractive.  Additionally,
-	  it provides a simple way to add or remove jails as well as a
-	  way to upgrade them.</para>
-	<note>
-	  <para>Examples of services in this context are: an
-	    <acronym>HTTP</acronym> server, a <acronym>DNS</acronym>
-	    server, a <acronym>SMTP</acronym> server, and so
-	    forth.</para>
 	<para>The goals of the setup described in this section
@@ -533,8 +527,8 @@ jail_<replaceable>www</replaceable>_devf
 	    <para>Create a simple and easy to understand jail
-	      structure.  This implies <emphasis>not</emphasis> having
-	      to run a full installworld on each and every
+	      structure that does not require
+	      running a full installworld on each and every
@@ -563,29 +557,31 @@ jail_<replaceable>www</replaceable>_devf
-	<para>As it has been already mentioned, this design relies
-	  heavily on having a single master template which is
-	  read-only (known as <application>nullfs</application>)
+	<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 &; device.  In this example, we will
-	  use read-write <application>nullfs</application>
+	  vnode backed memory device.  This example
+	  uses read-write <application>nullfs</application>
-	<para>The file system layout is described in the following
-	  list:</para>
+	<para>The file system layout is as follows:</para>
+	    <para>The jails are based under the
+	    <filename>/home</filename> partition.</para>
+	  </listitem>
+	  <listitem>
 	    <para>Each jail will be mounted under the
-	    <para><filename>/home/j/mroot</filename>
-	      is the template for each jail and the read-only
-	      partition for all of the jails.</para>
+	    <para>The template for each jail and the read-only
+	      partition for all of the jails is <filename>/home/j/mroot</filename>.</para>
@@ -596,57 +592,43 @@ jail_<replaceable>www</replaceable>_devf
 	    <para>Each jail will have a
-	      <filename>/s</filename> directory,
+	      <filename>/s</filename> directory
 	      that will be linked to the read-write portion of the
-	    <para>Each jail shall have its own read-write system that
+	    <para>Each jail will have its own read-write system that
 	      is based upon <filename>/home/j/skel</filename>.</para>
-	    <para>Each jailspace (read-write portion of each jail)
-	      shall be created in <filename>/home/js</filename>.</para>
+	    <para>The read-write portion of each jail
+	      will be created in <filename>/home/js</filename>.</para>
-	<note>
-	  <para>This assumes that the jails are based under the
-	    <filename>/home</filename> partition.
-	    This can, of course, be changed to anything else, but this
-	    change will have to be reflected in each of the examples
-	    below.</para>
-	</note>
 	<!-- Insert an image or drawing here to illustrate the example. -->
-      </sect3>
-      <sect3 xml:id="jails-service-jails-template">
+      <sect2 xml:id="jails-service-jails-template">
 	<title>Creating the Template</title>
-	<para>This section will describe the steps needed to create
-	  the master template that will be the read-only portion for
-	  the jails to use.</para>
-	<para>It is always a good idea to update the &os; system to
-	  the latest -RELEASE branch.  Check the corresponding
-	  Handbook <link xlink:href="&url.books.handbook;/makeworld.html">Chapter</link>
-	  to accomplish this task.  In the case the update is not
-	  feasible, the buildworld will be required in order to be
-	  able to proceed.  Additionally, the
-	  <package>sysutils/cpdup</package> package
-	  will be required.  We will use the &man.portsnap.8; utility
-	  to download the &os; Ports Collection.  The Handbook
-	  <link xlink:href="&url.books.handbook;/ports-using.html">Portsnap
-	    Chapter</link> is always good reading for
-	  newcomers.</para>
+	<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>
 	    <para>First, create a directory structure for the
 	      read-only file system which will contain the &os;
-	      binaries for our jails, then change directory to the
+	      binaries for the jails.  Then, change directory to the
 	      &os; source tree and install the read-only file system
 	      to the jail template:</para>
@@ -680,7 +662,7 @@ jail_<replaceable>www</replaceable>_devf
 	    <para>Use <application>mergemaster</application> to
-	      install missing configuration files.  Then get rid of
+	      install missing configuration files.  Then, remove the
 	      the extra directories that
 	      <application>mergemaster</application> creates:</para>
@@ -691,10 +673,10 @@ jail_<replaceable>www</replaceable>_devf
 	    <para>Now, symlink the read-write file system to the
-	      read-only file system.  Please make sure that the
+	      read-only file system.  Ensure that the
 	      symlinks are created in the correct
-	      <filename>s/</filename> locations.
-	      Real directories or the creation of directories in the
+	      <filename>s/</filename> locations as
+	      the creation of directories in the
 	      wrong locations will cause the installation to
@@ -712,34 +694,34 @@ jail_<replaceable>www</replaceable>_devf
 	    <para>As a last step, create a generic
-	      <filename>/home/j/skel/etc/make.conf</filename> with its
-	      contents as shown below:</para>
+	      <filename>/home/j/skel/etc/make.conf</filename> containing
+	      this line:</para>
 	    <programlisting>WRKDIRPREFIX?=  /s/portbuild</programlisting>
-	    <para>Having <literal>WRKDIRPREFIX</literal> set up this
-	      way will make it possible to compile &os; ports inside
+	    <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>
-      </sect3>
+      </sect2>
-      <sect3 xml:id="jails-service-jails-creating">
+      <sect2 xml:id="jails-service-jails-creating">
 	<title>Creating Jails</title>
-	<para>Now that we have a complete &os; jail template, we can
+	<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: <quote>NS</quote>,
-	  <quote>MAIL</quote> and <quote>WWW</quote>.</para>
+	  demonstrates the creation of 3 jails: <literal>NS</literal>,
+	  <literal>MAIL</literal> and <literal>WWW</literal>.</para>
-	    <para>Put the following lines into the
-	      <filename>/etc/fstab</filename> file, so that the
+	    <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>
@@ -750,19 +732,12 @@ jail_<replaceable>www</replaceable>_devf
 /home/js/mail   /home/j/mail/s nullfs  rw  0   0
 /home/js/www    /home/j/www/s  nullfs  rw  0   0</programlisting>
-	    <note>
-	      <para>Partitions marked with a 0 pass number are not
-		checked by &man.fsck.8; during boot, and partitions
-		marked with a 0 dump number are not backed up by
-		&man.dump.8;.  We do not want
-		<application>fsck</application> to check
-		<application>nullfs</application> mounts or
-		<application>dump</application> to back up the
-		read-only nullfs mounts of the jails.  This is why
-		they are marked with <quote>0 0</quote> in the
-		last two columns of each <filename>fstab</filename>
-		entry above.</para>
-	    </note>
+	      <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>
@@ -785,25 +760,20 @@ jail_www_ip=""
-	    <warning>
-	      <para>The reason why the
+	      <para>The
 		variable is set to
 		<filename class="directory">/usr/home</filename>
 		instead of
-		<filename class="directory">/home</filename> is that
-		the physical path of the
-		<filename class="directory">/home</filename> directory
+		<filename class="directory">/home</filename> because
+		the physical path of
+		<filename class="directory">/home</filename>
 		on a default &os; installation is
 		<filename class="directory">/usr/home</filename>.  The
 		variable must <emphasis>not</emphasis> be set to a
 		path which includes a symbolic link, otherwise the
-		jails will refuse to start.  Use the &man.realpath.1;
-		utility to determine a value which should be set to
-		this variable.  Please see the &os;-SA-07:01.jail
-		Security Advisory for more information.</para>
-	    </warning>
+		jails will refuse to start.</para>
@@ -814,11 +784,8 @@ jail_www_devfs_enable="YES"</programlist
-	    <para>Install the read-write template into each jail.
-	      Note the use of
-	      <package>sysutils/cpdup</package>,
-	      which helps to ensure that a correct copy is done of
-	      each directory:</para>
+	    <para>Install the read-write template into each jail using
+	      <package>sysutils/cpdup</package>:</para>
 	    <!-- keramida: Why is cpdup required here?  Doesn't cpio(1)
 	     already include adequate functionality for performing this
 	     job *and* have the advantage of being part of the base
@@ -833,8 +800,7 @@ jail_www_devfs_enable="YES"</programlist
 	    <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 using the jail rc
-	      script.</para>
+	      jail, and then start them:</para>
 	    <screen>&prompt.root; <userinput>mount -a</userinput>
 &prompt.root; <userinput>service jail start</userinput></screen>
@@ -842,7 +808,7 @@ jail_www_devfs_enable="YES"</programlist
 	<para>The jails should be running now.  To check if they have
-	  started correctly, use the &man.jls.8; command.  Its output
+	  started correctly, use <command>jls</command>.  Its output
 	  should be similar to the following:</para>
 	<screen>&prompt.root; <userinput>jls</userinput>
@@ -852,32 +818,28 @@ jail_www_devfs_enable="YES"</programlist
      1               /home/j/www</screen>
 	<para>At this point, it should be possible to log onto each
-	  jail, add new users or configure daemons.  The
+	  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 in order to perform administrative tasks
-	  in the jail whose <literal>JID</literal> is 3:</para>
+	  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>
-      </sect3>
+      </sect2>
-      <sect3 xml:id="jails-service-jails-upgrading">
+      <sect2 xml:id="jails-service-jails-upgrading">
-	<para>In time, there will be a need to upgrade the system to a
-	  newer version of &os;, either because of a security issue,
-	  or because new features have been implemented which are
-	  useful for the existing jails.  The design of this setup
-	  provides an easy way to upgrade existing jails.
-	  Additionally, it minimizes their downtime, as the jails will
-	  be brought down only in the very last minute.  Also, it
-	  provides a way to roll back to the older versions should any
-	  problems occur.</para>
+	<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>
-	    <para>The first step is to upgrade the host system in the
-	      usual manner.  Then create a new temporary read-only
+	    <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>
@@ -887,7 +849,7 @@ jail_www_devfs_enable="YES"</programlist
 &prompt.root; <userinput>cpdup /usr/src usr/src</userinput>
 &prompt.root; <userinput>mkdir s</userinput></screen>
-	    <para>The <buildtarget>installworld</buildtarget> run
+	    <para>The <buildtarget>installworld</buildtarget>
 	      creates a few unnecessary directories, which should be
@@ -909,13 +871,15 @@ jail_www_devfs_enable="YES"</programlist
-	    <para>The right time to stop the jails is now:</para>
+	    <para>Next, stop the jails:</para>
 	    <screen>&prompt.root; <userinput>service jail stop</userinput></screen>
-	    <para>Unmount the original file systems:</para>
+	    <para>Unmount the original file systems as the read-write
+	      systems are attached to the read-only system
+	      (<filename>/s</filename>):</para>
 	    <!-- keramida: Shouldn't we suggest a short script-based
 	     loop here, instead of tediously copying the same commands
 	     multiple times? -->
@@ -926,13 +890,6 @@ jail_www_devfs_enable="YES"</programlist
 &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>
-	    <note>
-	      <para>The read-write systems are attached to the
-		read-only system
-		(<filename>/s</filename>) and must
-		be unmounted first.</para>
-	    </note>
@@ -961,11 +918,9 @@ jail_www_devfs_enable="YES"</programlist
-	<para>Use &man.jls.8; to check if the jails started correctly.
-	  Do not forget to run mergemaster in each jail.  The
-	  configuration files will need to be updated as well as the
-	  rc.d scripts.</para>
-      </sect3>
+	<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>

More information about the svn-doc-all mailing list