From da0f1f5085871f914a0a139f6e82345c9ce0e694 Mon Sep 17 00:00:00 2001
From: Ed Maste <emaste@FreeBSD.org>
Date: Tue, 6 Mar 2018 12:55:31 +0000
Subject: [PATCH] Document jail.conf Jail configuration

jail.conf is the preferred method of configuring jails in all supported
FreeBSD versions.  Older rc.conf(5) configuration produces a warning.
Update the handbook example to match based on the submission in the PR,
with a few modifications.

PR:		187142
Submitted by:	Jack-Benny Persson
Reviewed by:	bcr, eadler
Approved by:	bcr, eadler
Sponsored by:	The FreeBSD Foundation
Differential Revision:	https://reviews.freebsd.org/D14524
---
 .../books/handbook/jails/chapter.xml          | 41 ++++++++-----------
 1 file changed, 18 insertions(+), 23 deletions(-)

diff --git a/en_US.ISO8859-1/books/handbook/jails/chapter.xml b/en_US.ISO8859-1/books/handbook/jails/chapter.xml
index e18e2eca0d..2118264e9f 100644
--- a/en_US.ISO8859-1/books/handbook/jails/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/jails/chapter.xml
@@ -313,46 +313,41 @@
 
     <procedure>
       <step>
-	<para>A list of the jails which are enabled to start at boot
-	  time should be added to the &man.rc.conf.5; file:</para>
+	<para>Configure jail parameters in
+	  <filename>jail.conf</filename>:</para>
+	<programlisting><replaceable>www</replaceable> {
+    host.hostname = <replaceable>www.example.org</replaceable>;           # Hostname
+    ip4.addr = <replaceable>192.168.0.10</replaceable>;                   # IP address of the jail
+    path ="<replaceable>/usr/jail/www</replaceable>";                     # Path to the jail
+    devfs_ruleset = "<replaceable>www_ruleset</replaceable>";             # devfs ruleset
+    mount.devfs;                               # Mount devfs inside the jail
+    exec.start = "/bin/sh /etc/rc";            # Start command
+    exec.stop = "/bin/sh /etc/rc.shutdown";    # Stop command
+}</programlisting>
 
-	<programlisting>jail_enable="YES"   # Set to NO to disable starting of any jails
-jail_list="<replaceable>www</replaceable>"     # Space separated list of names of jails</programlisting>
+	<para>Configure jails to start at boot time in
+	  <filename>rc.conf</filename>:</para>
 
-	<note>
-	  <para>Jail names in <varname>jail_list</varname> should
-	    contain alphanumeric characters only.</para>
-	</note>
-      </step>
-
-      <step>
-	<para>For each jail listed in <varname>jail_list</varname>, a
-	  group of &man.rc.conf.5; settings, which describe the
-	  particular jail, should be added:</para>
-
-	<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</programlisting>
+	<programlisting>jail_enable="YES"   # Set to NO to disable starting of any jails</programlisting>
 
 	<para>The default startup of jails configured in
-	  &man.rc.conf.5;, will run the <filename>/etc/rc</filename>
+	  &man.jail.conf.5;, will run the <filename>/etc/rc</filename>
 	  script of the jail, which assumes the jail is a complete
 	  virtual system.  For service jails, the default startup
 	  command of the jail should be changed, by setting the
-	  <varname>jail_<replaceable>jailname</replaceable>_exec_start</varname>
+	  <varname>exec.start</varname>
 	  option appropriately.</para>
 
 	<note>
 	  <para>For a full list of available options, please see the
-	    &man.rc.conf.5; manual page.</para>
+	    &man.jail.conf.5; manual page.</para>
 	</note>
       </step>
     </procedure>
 
     <para>&man.service.8; can be used to start or stop a jail by hand,
       if an entry for it exists in
-      <filename>rc.conf</filename>:</para>
+      <filename>jail.conf</filename>:</para>
 
     <screen>&prompt.root; <userinput>service jail start <replaceable>www</replaceable></userinput>
 &prompt.root; <userinput>service jail stop <replaceable>www</replaceable></userinput></screen>