os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Rename Service Jails to a more descriptive Updating Multiple Jails.

Browse source 
Editorial review of this section.
It still needs to address PR168939 and the comments in this section.

Sponsored by:	iXsystems
This commit is contained in:
Dru Lavigne 2014-04-10 15:07:29 +00:00
parent 6be13d71d5
commit d7387f291c
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=44517
1 changed files with 117 additions and 162 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

279
en_US.ISO8859-1/books/handbook/jails/chapter.xml
View file

@ -470,61 +470,55 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
</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@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>
it is upgraded. This can be
time consuming and tedious if a lot of jails are
created and manually updated.</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
<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
&mdash; 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>_devfs_ruleset="<replaceable>www_ruleset</rep
<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,19 +557,22 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
</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>
@ -583,9 +580,8 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
</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>_devfs_ruleset="<replaceable>www_ruleset</rep
<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>This section describes the steps needed to create
the master template.</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>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>_devfs_ruleset="<replaceable>www_ruleset</rep
<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>_devfs_ruleset="<replaceable>www_ruleset</rep
<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>_devfs_ruleset="<replaceable>www_ruleset</rep
<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>_devfs_ruleset="<replaceable>www_ruleset</rep
/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&nbsp;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"</programlisting>
</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"</programlisting>
<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"</programlisting>
</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"</programlisting>
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"</programlisting>
&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"</programlisting>
</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"</programlisting>
&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"</programlisting>
</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>