svn commit: r44517 - head/en_US.ISO8859-1/books/handbook/jails
Dru Lavigne
dru at FreeBSD.org
Thu Apr 10 15:07:30 UTC 2014
Author: dru
Date: Thu Apr 10 15:07:29 2014
New Revision: 44517
URL: http://svnweb.freebsd.org/changeset/doc/44517
Log:
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
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>
<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>
<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>This section is based upon an idea originally presented by
- &a.simon.email; at <uri xlink:href="http://simon.nitro.dk/service-jails.html">http://simon.nitro.dk/service-jails.html</uri>, and
- an updated article written by Ken Tom
- <email>locals at gmail.com</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>
</note>
<para>The goals of the setup described in this section
@@ -533,8 +527,8 @@ jail_<replaceable>www</replaceable>_devf
<itemizedlist>
<listitem>
<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
jail.</para>
</listitem>
@@ -563,29 +557,31 @@ jail_<replaceable>www</replaceable>_devf
</listitem>
</itemizedlist>
- <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 &man.md.4; device. In this example, we will
- use read-write <application>nullfs</application>
+ vnode backed memory device. This example
+ uses read-write <application>nullfs</application>
mounts.</para>
- <para>The file system layout is described in the following
- list:</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><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>
</listitem>
<listitem>
@@ -596,57 +592,43 @@ jail_<replaceable>www</replaceable>_devf
<listitem>
<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
system.</para>
</listitem>
<listitem>
- <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>
</listitem>
<listitem>
- <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>
</listitem>
</itemizedlist>
- <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>
<procedure>
<step>
<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
<step>
<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
<step>
<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
fail.</para>
@@ -712,34 +694,34 @@ jail_<replaceable>www</replaceable>_devf
<step>
<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>
</step>
</procedure>
- </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>
<procedure>
<step>
- <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>
</step>
<step>
@@ -785,25 +760,20 @@ jail_www_ip="62.123.43.14"
jail_www_rootdir="/usr/home/j/www"
jail_www_devfs_enable="YES"</programlisting>
- <warning>
- <para>The reason why the
+ <para>The
<varname>jail_<replaceable>name</replaceable>_rootdir</varname>
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
<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. 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>
</step>
<step>
@@ -814,11 +784,8 @@ jail_www_devfs_enable="YES"</programlist
</step>
<step>
- <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
<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 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
</procedure>
<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 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
+ 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">
<title>Upgrading</title>
- <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>
<procedure>
<step>
- <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
removed:</para>
@@ -909,13 +871,15 @@ jail_www_devfs_enable="YES"</programlist
</step>
<step>
- <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>
</step>
<step>
- <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>
</step>
<step>
@@ -961,11 +918,9 @@ jail_www_devfs_enable="YES"</programlist
</step>
</procedure>
- <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>
</sect2>
</sect1>
</chapter>
More information about the svn-doc-all
mailing list