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

Benedict Reuschling bcr at
Thu May 22 16:25:58 UTC 2014

Author: bcr
Date: Thu May 22 16:25:57 2014
New Revision: 44908

  This PR and the patch was created during the BSDCan 2014 Doc lounge.
  From the PR:
  - Describe that it's possible to install prebuilt binaries as well as build
    from source.
  - Instructions on how to extract distfiles on 8.x & earlier / 9.0 & later
  - Remove reference to jail_www_devfs_ruleset rc.conf, as-is it prevents the
    jail from starting because a ruleset needs to be defined & as there is no
    documentation for that in the article, it's easier to remove it, by doing
    this, the default ruleset is applied.
  - Add instructions on how to keep jails up to date with freebsd-update.
  I cleaned up the patch a bit, but it is still good work for a first patch.
  PR:		docs/189901
  Submitted by:	Sevan Janiyan


Modified: head/en_US.ISO8859-1/books/handbook/jails/chapter.xml
--- head/en_US.ISO8859-1/books/handbook/jails/chapter.xml	Thu May 22 15:18:45 2014	(r44907)
+++ head/en_US.ISO8859-1/books/handbook/jails/chapter.xml	Thu May 22 16:25:57 2014	(r44908)
@@ -50,7 +50,8 @@
       host system.  Jails expand this model by virtualizing access to
       the file system, the set of users, and the networking subsystem.
       More fine-grained controls are available for tuning the access
-      of a jailed environment.</para>
+      of a jailed environment.  Jails can be considered as a type of
+      operating system-level virtualization.</para>
     <para>A jail is characterized by four elements:</para>
@@ -194,8 +195,72 @@
       system, and <quote>service</quote> jails, dedicated to one
       application or service, possibly running with privileges.  This
       is only a conceptual division and the process of building a jail
-      is not affected by it.  The &man.jail.8; manual page is quite
-      clear about the procedure for building a jail:</para>
+      is not affected by it.  When creating a <quote>complete</quote>
+      jail there are two options for the source of the userland: use
+      prebuilt binaries (such as those supplied on an install media)
+      or build from source.</para>
+    <para>To install the userland from installation media, first
+      create the root directory for the jail.  This can be done by
+      setting the <varname>DESTDIR</varname> variable to the proper
+      location.  The command to use depends on which shell is being
+      used.</para>
+    <para>When using &;:</para>
+    <screen>&prompt.root; <userinput>export DESTDIR=<replaceable>/here/is/the/jail</replaceable></userinput></screen>
+    <para>If <command>csh</command>/<command>tcsh</command> is used,
+      execute this instead:</para>
+    <screen>&prompt.root; <userinput>setenv DESTDIR <replaceable>/here/is/the/jail</replaceable></userinput></screen>
+    <para>Mount the install media as covered in &man.mdconfig.8;
+      when using the install ISO:</para>
+    <screen>&prompt.root; <userinput>mount -t cd9660 /dev/`mdconfig -f cdimage.iso` /mnt</userinput></screen>
+    <para>Extract the binaries from the tarballs on the install media
+      into the declared destination.  Minimally, only the base set
+      needs to be extracted, but a complete install can be performed
+      when preferred.</para>
+    <para>To install just the base system, run the next command when
+      using &os; 9.x or newer:</para>
+    <screen>&prompt.root; <userinput>tar -xf /mnt/freebsd_install/usr/freebsd_dist/base.txz -C $DESTDIR</userinput></screen>
+    <para>On &os; 8.x systems, use this command instead:</para>
+    <screen>&prompt.root; <userinput>/mnt/8.<replaceable>4</replaceable>-RELEASE/base/</userinput></screen>
+    <para>To install everything but the kernel, issue this
+      command:</para>
+    <para>When using &; on &os; 9.x and newer, issue this
+      command:</para>
+    <screen>&prompt.root; <userinput>for <replaceable>sets</replaceable> in BASE DOC GAMES PORTS; do (tar -xf /mnt/FREEBSD_INSTALL/USR/FREEBSD_DIST/$<replaceable>sets</replaceable>.TXZ -C $DESTDIR</userinput></screen>
+    <para>When using &os; 8.x, run this:</para>
+    <screen>&prompt.root; <userinput>cd /mnt/8.<replaceable>4</replaceable>-RELEASE; for <replaceable>dir</replaceable> in base catpages dict doc games info manpages ports; do (cd $<replaceable>dir</replaceable>; ./ ; done</userinput></screen>
+    <para>If <command>csh</command>/<command>tcsh</command> is used on
+      &os; 9.x and newer, execute this command:</para>
+    <screen>&prompt.root; <userinput>foreach <replaceable>sets</replaceable> ( BASE DOC GAMES PORTS )
+    <para>On &os; 8.x, run this command:</para>
+    <screen>&prompt.root; <userinput>foreach <replaceable>dir</replaceable> ( base catpages dict doc games info manpages ports )
+	cd /mnt/8.<replaceable>4</replaceable>-RELEASE/$dir; ./
+    <para>The &man.jail.8; manual page explains the procedure for
+      building a jail:</para>
     <screen>&prompt.root; <userinput>setenv D <replaceable>/here/is/the/jail</replaceable></userinput>
 &prompt.root; <userinput>mkdir -p $D</userinput>      <co xml:id="jailpath"/>
@@ -299,8 +364,7 @@ jail_list="<replaceable>www</replaceable
 	<programlisting>jail_<replaceable>www</replaceable>_rootdir="/usr/jail/www"     # jail's root directory
 jail_<replaceable>www</replaceable>_hostname="<replaceable>www</replaceable>"  # jail's hostname
 jail_<replaceable>www</replaceable>_ip=""           # jail's IP address
-jail_<replaceable>www</replaceable>_devfs_enable="YES"          # mount devfs in the jail
-jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</replaceable>" # devfs ruleset to apply to jail</programlisting>
+jail_<replaceable>www</replaceable>_devfs_enable="YES"          # mount devfs in the jail</programlisting>
 	<para>The default startup of jails configured in
 	  &man.rc.conf.5;, will run the <filename>/etc/rc</filename>
@@ -460,6 +524,22 @@ jail_<replaceable>www</replaceable>_devf
 	applications that contribute to &man.jail.8; management.
 	Please refer to its web page for more information.</para>
+    <sect2 xml:id="jails-updating">
+      <title>Keeping Jails Patched and up to Date</title>
+      <para>Jails should be kept up to date from the host operating
+	system as attempting to patch userland from within the jail
+	may likely fail as the default behaviour in FreeBSD is to
+	disallow the use of &man.chflags.1; in a jail which prevents
+	the replacement of some files.  It is possible to change this
+	behavior but it is recommended to use &man.freebsd-update.8;
+	to maintain jails instead.  Use <option>-b</option> to specify
+	the path of the jail to be updated.</para>
+      <screen>&prompt.root; <userinput>freebsd-update -b <replaceable>/here/is/the/jail</replaceable> fetch</userinput>
+&prompt.root; <userinput>freebsd-update -b <replaceable>/here/is/the/jail</replaceable> install</userinput></screen>
+    </sect2>
   <sect1 xml:id="jails-application">

More information about the svn-doc-all mailing list