Date: Thu, 10 Apr 2014 15:07:29 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44517 - head/en_US.ISO8859-1/books/handbook/jails Message-ID: <201404101507.s3AF7TFm087029@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404101507.s3AF7TFm087029>