From owner-freebsd-doc@FreeBSD.ORG Mon Mar 17 23:50:01 2014 Return-Path: Delivered-To: freebsd-doc@smarthost.ysv.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 34A276D9 for ; Mon, 17 Mar 2014 23:50:01 +0000 (UTC) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:1900:2254:206c::16:87]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 10881AE4 for ; Mon, 17 Mar 2014 23:50:01 +0000 (UTC) Received: from freefall.freebsd.org (localhost [127.0.0.1]) by freefall.freebsd.org (8.14.8/8.14.8) with ESMTP id s2HNo0Gm049671 for ; Mon, 17 Mar 2014 23:50:00 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.8/8.14.8/Submit) id s2HNo0fa049662; Mon, 17 Mar 2014 23:50:00 GMT (envelope-from gnats) Resent-Date: Mon, 17 Mar 2014 23:50:00 GMT Resent-Message-Id: <201403172350.s2HNo0fa049662@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Allan Jude Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 9A6F3659 for ; Mon, 17 Mar 2014 23:43:53 +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)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 85885AA9 for ; Mon, 17 Mar 2014 23:43:53 +0000 (UTC) Received: from cgiserv.freebsd.org ([127.0.1.6]) by cgiserv.freebsd.org (8.14.8/8.14.8) with ESMTP id s2HNhokJ054375 for ; Mon, 17 Mar 2014 23:43:50 GMT (envelope-from nobody@cgiserv.freebsd.org) Received: (from nobody@localhost) by cgiserv.freebsd.org (8.14.8/8.14.8/Submit) id s2HNhor2054372; Mon, 17 Mar 2014 23:43:50 GMT (envelope-from nobody) Message-Id: <201403172343.s2HNhor2054372@cgiserv.freebsd.org> Date: Mon, 17 Mar 2014 23:43:50 GMT From: Allan Jude To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-3.1 Subject: docs/187683: [patch] Handbook section on bsdinstall is missing details of ZFS feature added in 10.0 X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 17 Mar 2014 23:50:01 -0000 >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 @@ + + + + + Allan + Jude + + + Updated for root-on-ZFS by + + @@ -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. If you have a machine based on an nVidia nForce3 @@ -1056,6 +1068,23 @@ ISO-8859-1 is also a safe option if the choice of keymap is not clear. + + 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. + +
+ Enhanced Keymap Menu + + + + + + +
+ @@ -1213,16 +1242,19 @@ Allocating Disk Space - There are three ways to allocate disk space for &os;. + There are four ways to allocate disk space for &os;. Guided partitioning automatically sets up disk partitions, while Manual partitioning - allows advanced users to create customized partitions. Finally, + allows advanced users to create customized partitions. The + ZFS 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.
- Selecting Guided or Manual Partitioning + Selecting Guided, Manual or Shell Partitioning @@ -1232,6 +1264,18 @@
+
+ Selecting Guided, Manual, Shell or + <acronym>ZFS</acronym> Partitioning + + + + + + +
+ + Guided Partitioning @@ -1427,7 +1471,7 @@ Another partition type worth noting is freebsd-zfs, used for partitions that will - contain a &os; ZFS filesystem. See + contain a &os; ZFS filesystem. See . &man.gpart.8; shows more of the available GPT partition types. @@ -1564,6 +1608,174 @@ [ Finish ] to continue with the installation. + + + Root-on-ZFS Automatic Partitioning + + 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 ZFS 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 GELI disk encryption. + If encryption is enabled, a 2 GB unencrypted boot pool is + created that contains the /boot + 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 + ZFS pool. + + The main ZFS menu in the installer + offers a number of options to control the creation of the + pool. + +
+ <acronym>ZFS</acronym> Partitioning Menu + + + + + + +
+ + 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 ZFS + installer currently only supports the creation of a single + top level vdev, except in stripe mode. To create more complex + pools, use Shell Mode 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. + +
+ <acronym>ZFS</acronym> Pool Type + + + + + + +
+ + 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 <Change Selection> to + return to the list of disks, or + <Cancel> to change the pool + type. + +
+ Disk Selection + + + + + + +
+ +
+ Invalid Selection + + + + + + +
+ + If one or more disks is missing from the list, or if disks + were attached after the installer was started, select + - Rescan Devices 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 + - Disk Info 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. + +
+ Analysing a Disk + + + + + + +
+ + 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 >>> Install option at the top of + the menu. + + If &man.geli.8; disk encryption was enabled, the installer + will prompt for the passphrase to be used to encrypt the disks + twice. + +
+ Disk Encryption Password + + + + + + +
+ + The installer then offers a last chance to cancel before + the contents of the selected drives are destroyed to create + the ZFS pool. + +
+ Last Chance + + + + + + +
+ + The installation then provides normally + + + + + Shell Mode Partitioning + + When creating advanced installations the basic interface + of bsdinstall may not provide the level of flexibility + required. Selecting the Shell 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 + /tmp/bsdinstall_etc/fstab, and mount the + file systems under /mnt. Once this is + done, running exit will return to + bsdinstall and continue the installation, starting with the + extraction of the distribution sets. + 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: