From owner-svn-doc-all@FreeBSD.ORG Thu Apr 10 15:07:30 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id DA3558CC; Thu, 10 Apr 2014 15:07:29 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id B984E1D15; Thu, 10 Apr 2014 15:07:29 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3AF7Tra087030; Thu, 10 Apr 2014 15:07:29 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3AF7TFm087029; Thu, 10 Apr 2014 15:07:29 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404101507.s3AF7TFm087029@svn.freebsd.org> From: Dru Lavigne Date: Thu, 10 Apr 2014 15:07:29 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 10 Apr 2014 15:07:30 -0000 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_www_devf - Application of Jails + + Updating Multiple Jails - - Service Jails DanielGerzoContributed by + + + + Simon + L. B. Nielsen + + Based upon an idea presented by + + + + + + Ken + Tom + + And an article written by + + - - - This section is based upon an idea originally presented by - &a.simon.email; at http://simon.nitro.dk/service-jails.html, and - an updated article written by Ken Tom - locals@gmail.com. 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. - - - Design - - One of the major problems with jails is the management - of their upgrade process. This tends to be a problem + 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. - - - 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. + + 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 HTTP, DNS, + and SMTP, into + individual jails. Additionally, + it provides a simple way to add, remove, and + upgrade jails. + + + Simpler solutions exist, + such as sysutils/ezjail, which provides an easier method of administering &os; jails and is not as sophisticated as this setup. - - - 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. - - - Examples of services in this context are: an - HTTP server, a DNS - server, a SMTP server, and so - forth. The goals of the setup described in this section @@ -533,8 +527,8 @@ jail_www_devf Create a simple and easy to understand jail - structure. This implies not having - to run a full installworld on each and every + structure that does not require + running a full installworld on each and every jail. @@ -563,29 +557,31 @@ jail_www_devf - As it has been already mentioned, this design relies - heavily on having a single master template which is - read-only (known as nullfs) + 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 nullfs + vnode backed memory device. This example + uses read-write nullfs mounts. - The file system layout is described in the following - list: + The file system layout is as follows: + The jails are based under the + /home partition. + + + Each jail will be mounted under the /home/j directory. - /home/j/mroot - is the template for each jail and the read-only - partition for all of the jails. + The template for each jail and the read-only + partition for all of the jails is /home/j/mroot. @@ -596,57 +592,43 @@ jail_www_devf Each jail will have a - /s directory, + /s directory that will be linked to the read-write portion of the system. - Each jail shall have its own read-write system that + Each jail will have its own read-write system that is based upon /home/j/skel. - Each jailspace (read-write portion of each jail) - shall be created in /home/js. + The read-write portion of each jail + will be created in /home/js. - - This assumes that the jails are based under the - /home partition. - This can, of course, be changed to anything else, but this - change will have to be reflected in each of the examples - below. - - - + Creating the Template - This section will describe the steps needed to create - the master template that will be the read-only portion for - the jails to use. - - It is always a good idea to update the &os; system to - the latest -RELEASE branch. Check the corresponding - Handbook Chapter - 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 - sysutils/cpdup package - will be required. We will use the &man.portsnap.8; utility - to download the &os; Ports Collection. The Handbook - Portsnap - Chapter is always good reading for - newcomers. + This section describes the steps needed to create + the master template. + + It is recommended to first update the host &os; system to + the latest -RELEASE branch using the instructions in + . + Additionally, this template uses the + sysutils/cpdup package or port + and portsnap + will be used to download the &os; Ports Collection. 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: @@ -680,7 +662,7 @@ jail_www_devf Use mergemaster to - install missing configuration files. Then get rid of + install missing configuration files. Then, remove the the extra directories that mergemaster creates: @@ -691,10 +673,10 @@ jail_www_devf 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 - s/ locations. - Real directories or the creation of directories in the + s/ locations as + the creation of directories in the wrong locations will cause the installation to fail. @@ -712,34 +694,34 @@ jail_www_devf As a last step, create a generic - /home/j/skel/etc/make.conf with its - contents as shown below: + /home/j/skel/etc/make.conf containing + this line: WRKDIRPREFIX?= /s/portbuild - Having WRKDIRPREFIX set up this - way will make it possible to compile &os; ports inside + 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 WRKDIRPREFIX allows builds to be done in the read-write portion of every jail. - + - + Creating Jails - Now that we have a complete &os; jail template, we can + The jail template can now be used to setup and configure the jails in /etc/rc.conf. This example - demonstrates the creation of 3 jails: NS, - MAIL and WWW. + demonstrates the creation of 3 jails: NS, + MAIL and WWW. - Put the following lines into the - /etc/fstab file, so that the + Add the following lines to + /etc/fstab, so that the read-only template for the jails and the read-write space will be available in the respective jails: @@ -750,19 +732,12 @@ jail_www_devf /home/js/mail /home/j/mail/s nullfs rw 0 0 /home/js/www /home/j/www/s nullfs rw 0 0 - - 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 - fsck to check - nullfs mounts or - dump to back up the - read-only nullfs mounts of the jails. This is why - they are marked with 0 0 in the - last two columns of each fstab - entry above. - + To prevent + fsck from checking + nullfs mounts during boot and + dump from backing up the + read-only nullfs mounts of the jails, the last two + columns are both set to 0. @@ -785,25 +760,20 @@ jail_www_ip="62.123.43.14" jail_www_rootdir="/usr/home/j/www" jail_www_devfs_enable="YES" - - The reason why the + The jail_name_rootdir variable is set to /usr/home instead of - /home is that - the physical path of the - /home directory + /home because + the physical path of + /home on a default &os; installation is /usr/home. The jail_name_rootdir variable must not 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. - + jails will refuse to start. @@ -814,11 +784,8 @@ jail_www_devfs_enable="YES" - Install the read-write template into each jail. - Note the use of - sysutils/cpdup, - which helps to ensure that a correct copy is done of - each directory: + Install the read-write template into each jail using + sysutils/cpdup: @@ -926,13 +890,6 @@ jail_www_devfs_enable="YES"umount /home/j/mail &prompt.root; umount /home/j/www/s &prompt.root; umount /home/j/www - - - The read-write systems are attached to the - read-only system - (/s) and must - be unmounted first. - @@ -961,11 +918,9 @@ jail_www_devfs_enable="YES" - 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. - + Use jls to check if the jails started correctly. + Run mergemaster in each jail to update the + configuration files.