Update the bsdinstall handbook section to describe the automatic

'root-on-zfs' feature.  Also add documentation for the 'shell' mode
feature that was not documented before.

PR:		docs/187683
Submitted by:	Allan Jude <freebsd@allanjude.com>
Approved by:	bcr (mentor)

en_US.ISO8859-1/books/handbook/Makefile

@@ -56,6 +56,7 @@ IMAGES_EN+= bsdinstall/bsdinstall-distfile-verifying.png
 IMAGES_EN+= bsdinstall/bsdinstall-final-confirmation.png
 IMAGES_EN+= bsdinstall/bsdinstall-finalconfiguration.png
 IMAGES_EN+= bsdinstall/bsdinstall-final-modification-shell.png
+IMAGES_EN+= bsdinstall/bsdinstall-keymap-10.png
 IMAGES_EN+= bsdinstall/bsdinstall-keymap-select-default.png
 IMAGES_EN+= bsdinstall/bsdinstall-mainexit.png
 IMAGES_EN+= bsdinstall/bsdinstall-netinstall-files.png
@@ -73,6 +74,14 @@ IMAGES_EN+= bsdinstall/bsdinstall-timezone-confirm.png
 IMAGES_EN+= bsdinstall/bsdinstall-timezone-country.png
 IMAGES_EN+= bsdinstall/bsdinstall-timezone-region.png
 IMAGES_EN+= bsdinstall/bsdinstall-timezone-zone.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-disk_info.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-disk_select.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-geli_password.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-menu.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-partmenu.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-vdev_invalid.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-vdev_type.png
+IMAGES_EN+= bsdinstall/bsdinstall-zfs-warning.png
 IMAGES_EN+= geom/striping.pic
 IMAGES_EN+= install/adduser1.scr
 IMAGES_EN+= install/adduser2.scr

en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml

@@ -54,6 +54,17 @@
 	</personname>
       </author>
     </authorgroup>
+
+    <authorgroup>
+      <author>
+	<personname>
+	  <firstname>Allan</firstname>
+	  <surname>Jude</surname>
+	</personname>
+
+	<contrib>Updated for root-on-ZFS by </contrib>
+      </author>
+    </authorgroup>
   </info>
 
   <sect1 xml:id="bsdinstall-synopsis">
@@ -159,7 +170,8 @@
 	  &intel;&nbsp;EM64T architecture.  Examples of these
 	  processors include the &intel;&nbsp;&core;&nbsp;2 Duo, Quad,
 	  Extreme processor families, the &intel;&nbsp;&xeon; 3000,
-	  5000, and 7000 sequences of processors, and the
+	  5000, and 7000 sequences of processors, the
+	  &intel;&nbsp;&xeon; E3, E5 and E7 processors, and the
 	  &intel;&nbsp;&core; i3, i5 and i7 processors.</para>
 
 	<para>If you have a machine based on an nVidia nForce3
@@ -1056,6 +1068,23 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen>
 	    ISO-8859-1</guimenuitem> is also a safe option if the
 	  choice of keymap is not clear.</para>
       </note>
+
+      <para>In &os; 10.0-RELEASE and later, this menu has been
+	enhanced.  The full selection of keymaps is shown, with the
+	default preselected.  In addition, when selecting a different
+	keymap, a dialog is displayed that allows the user to try
+	the keymap and ensure it is correct before proceeding.</para>
+
+      <figure xml:id="bsdinstall-keymap-10">
+	<title>Enhanced Keymap Menu</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="bsdinstall/bsdinstall-keymap-10"/>
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
     </sect2>
 
     <sect2 xml:id="bsdinstall-hostname">
@@ -1213,16 +1242,19 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen>
   <sect1 xml:id="bsdinstall-partitioning">
     <title>Allocating Disk Space</title>
 
-    <para>There are three ways to allocate disk space for &os;.
+    <para>There are four ways to allocate disk space for &os;.
       <emphasis>Guided</emphasis> partitioning automatically sets up
       disk partitions, while <emphasis>Manual</emphasis> partitioning
-      allows advanced users to create customized partitions.  Finally,
+      allows advanced users to create customized partitions.  The
+      <acronym>ZFS</acronym> option, only available in &os; 10 and
+      later, will create an optionally encrypted root-on-ZFS system
+      with support for Boot Environments.  Finally,
       there's the option of starting a shell where command-line
       programs like &man.gpart.8;, &man.fdisk.8;, and &man.bsdlabel.8;
       can be used directly.</para>
 
     <figure xml:id="bsdinstall-part-guided-manual">
-      <title>Selecting Guided or Manual Partitioning</title>
+      <title>Selecting Guided, Manual or Shell Partitioning</title>
 
       <mediaobject>
 	<imageobject>
@@ -1232,6 +1264,17 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen>
       </mediaobject>
     </figure>
 
+    <figure xml:id="bsdinstall-zfs-partmenu">
+      <title>Selecting Guided, Manual, Shell or
+	<acronym>ZFS</acronym> Partitioning</title>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="bsdinstall/bsdinstall-zfs-partmenu"/>
+	</imageobject>
+      </mediaobject>
+    </figure>
+
     <para>This section describes what to consider when laying
       out the disk partitions.  It then demonstrates how to use both
       the Guided Partitioning and Manual Partitioning screens.</para>
@@ -1525,7 +1568,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen>
 
       <para>Another partition type worth noting is
 	<literal>freebsd-zfs</literal>, used for partitions that will
-	contain a &os; ZFS filesystem.  See
+	contain a &os; <acronym>ZFS</acronym> filesystem.  See
 	<xref linkend="filesystems-zfs"/>.  &man.gpart.8; shows more
 	of the available <acronym>GPT</acronym> partition
 	types.</para>
@@ -1662,6 +1705,174 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen>
 	<guibutton>[&nbsp;Finish&nbsp;]</guibutton> to continue with
 	the installation.</para>
     </sect2>
+
+    <sect2 xml:id="bsdinstall-part-zfs">
+      <title>Root-on-ZFS Automatic Partitioning</title>
+
+      <para>Support for automatic creation of root-on-ZFS
+	installations was added in &os; 10.0-RELEASE.  This
+	partitioning mode only works with whole disks and will erase
+	the contents of the entire disk.  The installer will
+	automatically create partitions aligned to 4k boundaries, as
+	well as force <acronym>ZFS</acronym> to use 4k sectors.  This
+	is safe even with 512 byte sector disks, and has the added
+	benefit of ensuring that pools created on 512 byte disks will
+	be able to have 4k sector disks added to them in the future,
+	for additional storage space, or as replacements for failed
+	disks.  The installer can also optionally employ <link
+	  linkend="disks-encrypting-geli">GELI</link> disk encryption.
+	If encryption is enabled, a 2&nbsp;GB unencrypted boot pool is
+	created that contains the <filename>/boot</filename>
+	directory, which holds the kernel and other files necessary
+	to boot the system.  A swap partition of a user selectable
+	size is also created, and all remaining space is used for the
+	<acronym>ZFS</acronym> pool.</para>
+
+      <para>The main <acronym>ZFS</acronym> menu in the installer
+	offers a number of options to control the creation of the
+	pool.</para>
+
+      <figure xml:id="bsdinstall-zfs-menu">
+	<title><acronym>ZFS</acronym> Partitioning Menu</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="bsdinstall/bsdinstall-zfs-menu"/>
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The most important option is selecting the vdev type
+	and one or more disks that will make up the vdev that will
+	constitute the pool.  The automatic <acronym>ZFS</acronym>
+	installer currently only supports the creation of a single
+	top level vdev, except in stripe mode.  To create more complex
+	pools, use <link
+	linkend="bsdinstall-part-shell">Shell Mode</link> to create
+	the pool.  The installer supports the creation of various
+	pool types, including stripe (not recommended, no redundancy),
+	mirror (best performance, least usable space), and RAID-Z 1,
+	2, and 3 (with the capability to withstand the concurrent
+	failure of 1, 2, and 3 disks, respectively).  A tooltip across
+	the bottom of the screen while selecting the pool type
+	provides advice about the number of required disks for each
+	type, and in the case of RAID-Z, the optimal number of disks
+	for each configuration.</para>
+
+      <figure xml:id="bsdinstall-zfs-vdev_type">
+	<title><acronym>ZFS</acronym> Pool Type</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="bsdinstall/bsdinstall-zfs-vdev_type"/>
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Once a pool type has been selected, a list of available
+	disks is displayed, and the user is prompted to select one or
+	more disks to make up the pool.  The configuration is then
+	validated, to ensure enough disks were selected.  If not,
+	select <guibutton>&lt;Change Selection&gt;</guibutton> to
+	return to the list of disks, or
+	<guibutton>&lt;Cancel&gt;</guibutton> to change the pool
+	type.</para>
+
+      <figure xml:id="bsdinstall-zfs-disk_select">
+	<title>Disk Selection</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="bsdinstall/bsdinstall-zfs-disk_select"/>
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <figure xml:id="bsdinstall-zfs-vdev_invalid">
+	<title>Invalid Selection</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="bsdinstall/bsdinstall-zfs-vdev_invalid"/>
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>If one or more disks are missing from the list, or if disks
+	were attached after the installer was started, select
+	<guibutton>- Rescan Devices</guibutton> to repopulate the list
+	of available disks.  To ensure that the correct disk is
+	selected, so as not to accidently destroy the wrong disks, the
+	<guibutton>- Disk Info</guibutton> menu allows you to inspect
+	each disk, including its partition table, and various other
+	information, including the device model number and serial
+	number, if available.</para>
+
+      <figure xml:id="bsdinstall-zfs-disk_info">
+	<title>Analysing a Disk</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="bsdinstall/bsdinstall-zfs-disk_info"/>
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The menu also allows the user to enter a name for the
+	pool, disable forcing 4k sectors, enable or disable
+	encryption, switch between GPT (recommended) and MBR partition
+	table types, and select the desired amount of swap
+	space.  Once all options have been set to the desired values,
+	select the <guibutton>&gt;&gt;&gt;&nbsp;Install</guibutton>
+	option at the top of the menu.</para>
+
+      <para>If &man.geli.8; disk encryption was enabled, the
+	installer will prompt twice for the passphrase to be
+	used to encrypt the disks.</para>
+
+      <figure xml:id="bsdinstall-zfs-geli_password">
+	<title>Disk Encryption Password</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="bsdinstall/bsdinstall-zfs-geli_password"/>
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The installer then offers a last chance to cancel before
+	the contents of the selected drives are destroyed to create
+	the <acronym>ZFS</acronym> pool.</para>
+
+      <figure xml:id="bsdinstall-zfs-warning">
+	<title>Last Chance</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="bsdinstall/bsdinstall-zfs-warning"/>
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The installation then proceeds normally.</para>
+
+    </sect2>
+
+    <sect2 xml:id="bsdinstall-part-shell">
+      <title>Shell Mode Partitioning</title>
+
+      <para>When creating advanced installations the basic interface
+	of bsdinstall may not provide the level of flexibility
+	required.  Selecting the <guibutton>Shell</guibutton> option
+	from the partitioning menu will drop the user to a shell.  The
+	user is expected to partition the drives and create the
+	desired file system(s), populate an &man.fstab.5; file in
+	<filename>/tmp/bsdinstall_etc/fstab</filename>, and mount the
+	file systems under <filename>/mnt</filename>.  Once this is
+	done, running <command>exit</command> will return to
+	bsdinstall and continue the installation, starting with the
+	extraction of the distribution sets.</para>
+    </sect2>
   </sect1>
 
   <sect1 xml:id="bsdinstall-final-warning">

en_US.ISO8859-1/books/handbook/disks/chapter.xml

@@ -2971,7 +2971,7 @@ gbde_lockdir="/etc/gbde"</programlisting>
       </sect3>
     </sect2>
 
-    <sect2>
+    <sect2 xml:id="disks-encrypting-geli">
       <info>
 	<title>Disk Encryption with <command>geli</command></title>