Date: Mon, 17 Mar 2014 23:43:50 GMT From: Allan Jude <freebsd@allanjude.com> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/187683: [patch] Handbook section on bsdinstall is missing details of ZFS feature added in 10.0 Message-ID: <201403172343.s2HNhor2054372@cgiserv.freebsd.org> Resent-Message-ID: <201403172350.s2HNo0fa049662@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 187683
>Category: docs
>Synopsis: [patch] Handbook section on bsdinstall is missing details of ZFS feature added in 10.0
>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: Mon Mar 17 23:50:00 UTC 2014
>Closed-Date:
>Last-Modified:
>Originator: Allan Jude
>Release: 10.0-RELEASE
>Organization:
ScaleEngine Inc.
>Environment:
>Description:
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.
Includes many screenshots
>How-To-Repeat:
>Fix:
Apply this patch
Patch attached with submission follows:
Index: head/en_US.ISO8859-1/books/handbook/Makefile
===================================================================
--- head/en_US.ISO8859-1/books/handbook/Makefile (revision 44203)
+++ head/en_US.ISO8859-1/books/handbook/Makefile (working copy)
@@ -56,6 +56,7 @@
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-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
Index: head/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml (revision 44203)
+++ head/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml (working copy)
@@ -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; EM64T architecture. Examples of these
processors include the &intel; &core; 2 Duo, Quad,
Extreme processor families, the &intel; &xeon; 3000,
- 5000, and 7000 sequences of processors, and the
+ 5000, and 7000 sequences of processors, the
+ &intel; &xeon; E3, E5 and E7 processors, and the
&intel; &core; i3, i5 and i7 processors.</para>
<para>If you have a machine based on an nVidia nForce3
@@ -1056,6 +1068,23 @@
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 @@
<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,18 @@
</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>
+
+
<sect2 xml:id="bsdinstall-part-guided">
<title>Guided Partitioning</title>
@@ -1427,7 +1471,7 @@
<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>
@@ -1564,6 +1608,174 @@
<guibutton>[ Finish ]</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 boundries, 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 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 redundnacy),
+ 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><Change Selection></guibutton> to
+ return to the list of disks, or
+ <guibutton><Cancel></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 is 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>>>> Install</guibutton> option at the top of
+ the menu.</para>
+
+ <para>If &man.geli.8; disk encryption was enabled, the installer
+ will prompt for the passphrase to be used to encrypt the disks
+ twice.</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 provides 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">
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-keymap-10.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-keymap-10.png
===================================================================
--- head/share/images/books/handbook/bsdinstall/bsdinstall-keymap-10.png (revision 0)
+++ head/share/images/books/handbook/bsdinstall/bsdinstall-keymap-10.png (working copy)
Property changes on: head/share/images/books/handbook/bsdinstall/bsdinstall-keymap-10.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-disk_info.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-disk_info.png
===================================================================
--- head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-disk_info.png (revision 0)
+++ head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-disk_info.png (working copy)
Property changes on: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-disk_info.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-disk_select.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-disk_select.png
===================================================================
--- head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-disk_select.png (revision 0)
+++ head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-disk_select.png (working copy)
Property changes on: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-disk_select.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-geli_password.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-geli_password.png
===================================================================
--- head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-geli_password.png (revision 0)
+++ head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-geli_password.png (working copy)
Property changes on: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-geli_password.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-menu.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-menu.png
===================================================================
--- head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-menu.png (revision 0)
+++ head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-menu.png (working copy)
Property changes on: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-menu.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-partmenu.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-partmenu.png
===================================================================
--- head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-partmenu.png (revision 0)
+++ head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-partmenu.png (working copy)
Property changes on: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-partmenu.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-vdev_invalid.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-vdev_invalid.png
===================================================================
--- head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-vdev_invalid.png (revision 0)
+++ head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-vdev_invalid.png (working copy)
Property changes on: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-vdev_invalid.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-vdev_type.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-vdev_type.png
===================================================================
--- head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-vdev_type.png (revision 0)
+++ head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-vdev_type.png (working copy)
Property changes on: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-vdev_type.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-warning.png
===================================================================
Cannot display: file marked as a binary type.
svn:mime-type = image/png
Index: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-warning.png
===================================================================
--- head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-warning.png (revision 0)
+++ head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-warning.png (working copy)
Property changes on: head/share/images/books/handbook/bsdinstall/bsdinstall-zfs-warning.png
___________________________________________________________________
Added: svn:mime-type
## -0,0 +1 ##
+image/png
\ No newline at end of property
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403172343.s2HNhor2054372>