From nobody@FreeBSD.org  Sat May 17 23:36:15 2014
Return-Path: <nobody@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 1A07EAB9
	for <freebsd-gnats-submit@FreeBSD.org>; Sat, 17 May 2014 23:36:15 +0000 (UTC)
Received: from cgiserv.freebsd.org (cgiserv.freebsd.org [IPv6:2001:1900:2254:206a::50:4])
	(using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
	(Client did not present a certificate)
	by mx1.freebsd.org (Postfix) with ESMTPS id 06DF9224F
	for <freebsd-gnats-submit@FreeBSD.org>; Sat, 17 May 2014 23:36:15 +0000 (UTC)
Received: from cgiserv.freebsd.org ([127.0.1.6])
	by cgiserv.freebsd.org (8.14.8/8.14.8) with ESMTP id s4HNaEBZ012106
	for <freebsd-gnats-submit@FreeBSD.org>; Sat, 17 May 2014 23:36:14 GMT
	(envelope-from nobody@cgiserv.freebsd.org)
Received: (from nobody@localhost)
	by cgiserv.freebsd.org (8.14.8/8.14.8/Submit) id s4HNaEXI012105;
	Sat, 17 May 2014 23:36:14 GMT
	(envelope-from nobody)
Message-Id: <201405172336.s4HNaEXI012105@cgiserv.freebsd.org>
Date: Sat, 17 May 2014 23:36:14 GMT
From: Sevan Janiyan <venture37@geeklan.co.uk>
To: freebsd-gnats-submit@FreeBSD.org
Subject: Update the jail section of the handbook
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         189901
>Category:       docs
>Synopsis:       Update the jail section of the handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    bcr
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Sat May 17 23:40:00 UTC 2014
>Closed-Date:    Thu May 22 16:32:07 UTC 2014
>Last-Modified:  Thu May 22 16:32:07 UTC 2014
>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:
Responsible-Changed-From-To: freebsd-doc->bcr  
Responsible-Changed-By: bcr 
Responsible-Changed-When: Sat May 17 23:40:49 UTC 2014 
Responsible-Changed-Why:  
Assign this to me as it was created as part of the Doc Lounge at BSDCan 2014. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=189901 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/189901: commit references a PR
Date: Thu, 22 May 2014 16:26:04 +0000 (UTC)

 Author: bcr
 Date: Thu May 22 16:25:57 2014
 New Revision: 44908
 URL: http://svnweb.freebsd.org/changeset/doc/44908
 
 Log:
   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
 
 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 &man.sh.1;:</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;&nbsp;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/install.sh</userinput></screen>
 +
 +    <para>To install everything but the kernel, issue this
 +      command:</para>
 +
 +    <para>When using &man.sh.1; on &os;&nbsp;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;&nbsp;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>; ./install.sh) ; 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 )
 +tar -xf /mnt/FREEBSD_INSTALL/USR/FREEBSD_DIST/$sets.TXZ -C $DESTDIR
 +done</userinput></screen>
 +
 +    <para>On &os;&nbsp;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; ./install.sh
 +done</userinput></screen>
 +
 +    <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>.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 +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>
 +
 +    <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>
  
    <sect1 xml:id="jails-application">
 _______________________________________________
 svn-doc-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-doc-all
 To unsubscribe, send any mail to "svn-doc-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: open->closed 
State-Changed-By: bcr 
State-Changed-When: Thu May 22 16:31:29 UTC 2014 
State-Changed-Why:  
A modified version of the patch was committed. Thanks for working on it! 
Keep it up. PR closed! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=189901 
>Unformatted:
