docs/189901: Update the jail section of the handbook

Sevan Janiyan venture37 at geeklan.co.uk
Sat May 17 23:40:00 UTC 2014 

>Number:         189901
>Category:       docs
>Synopsis:       Update the jail section of the handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Sat May 17 23:40:00 UTC 2014
>Closed-Date:
>Last-Modified:
>Originator:     Sevan Janiyan
>Release:        11.0-CURRENT
>Organization:
>Environment:
FreeBSD 11.0-CURRENT FreeBSD 11.0-CURRENT #0 r266021M
>Description:
The following changes where made
Mention that jails is operating system level virtualisation
Describe that it's possible to install perbuilt 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.

>How-To-Repeat:

>Fix:


Patch attached with submission follows:

Index: jails/chapter.xml
===================================================================
--- jails/chapter.xml	(revision 44837)
+++ jails/chapter.xml	(working copy)
@@ -50,7 +50,9 @@
       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,9 +196,75 @@
       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 a install media ) or build from
+      source.</para>
 
+    <para>To install the userland from installation media, first
+      create the root directory for the jail.</para>
+
+    <para>Set the <varname>DESTDIR</varname> variable to this
+      location.</para>
+
+    <para>If using <command>sh</command></para>
+
+    <screen>&prompt.root; <userinput>export DESTDIR=<replaceable>/here/is/the/jail</replaceable></userinput></screen>
+
+    <para>If using <command>csh</command>/<command>tcsh</command></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;
+      if 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 tar balls on the install media
+      into the declared destination, realistically, only the base set
+      needs to be extracted but a complete install can be performed if
+      preferred.</para>
+
+  <para>To install just base:</para>
+
+  <para>On &os; 9.x and 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</para>
+
+  <screen>&prompt.root; <userinput>/mnt/8.4-RELEASE/base/install.sh</userinput></screen>
+
+  <para>To install everything but kernel:</para>
+
+  <para>If using <command>sh</command></para>
+
+  <para>On &os; 9.x and newer</para>
+
+  <screen>&prompt.root; <userinput>for sets in BASE DOC GAMES PORTS; do (tar -xf /mnt/FREEBSD_INSTALL/USR/FREEBSD_DIST/$sets.TXZ -C $DESTDIR</userinput></screen>
+
+  <para>On &os; 8.x</para>
+
+  <screen>&prompt.root; <userinput>cd /mnt/8.4-RELEASE; for dir in base catpages dict doc games info manpages ports; do (cd $dir ; ./install.s    h) ; done</userinput></screen>
+
+  <para>If using <command>csh</command>/<command>tcsh</command></para>
+
+  <para>On &os; 9.x and newer</para>
+
+  <screen>&prompt.root; <userinput>foreach sets ( BASE DOC GAMES PORTS )
+      tar -xf /mnt/FREEBSD_INSTALL/USR/FREEBSD_DIST/$sets.TXZ -C $DESTDIR
+      done</userinput></screen>
+
+  <para>On &os; 8.x</para>
+
+  <screen>&prompt.root; <userinput>foreach dir ( base catpages dict doc games info manpages ports )
+      cd /mnt/8.4-RELEASE/$dir; ./install.sh
+      done</userinput></screen>
+
+  <para>The &man.jail.8; manual page is quite clear about the
+      procedure for building a jail from source:</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"/>
 &prompt.root; <userinput>cd /usr/src</userinput>
@@ -299,8 +367,7 @@
 	<programlisting>jail_<replaceable>www</replaceable>_rootdir="/usr/jail/www"     # jail's root directory
 jail_<replaceable>www</replaceable>_hostname="<replaceable>www</replaceable>.example.org"  # jail's hostname
 jail_<replaceable>www</replaceable>_ip="192.168.0.10"           # 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 +527,24 @@
 	applications that contribute to &man.jail.8; management.
 	Please refer to its web page for more information.</para>
     </sect2>
+
+    <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's possible to change this behaviour but it is recommended
+	to use &man.freebsd-update.8; to maintain jails instead.
+	Using the <option>-b</option> option the path of the jail to
+	be updated can be specified.</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>
 
   <sect1 xml:id="jails-application">

>Release-Note:
>Audit-Trail:
>Unformatted:

More information about the freebsd-doc mailing list