From owner-svn-doc-head@FreeBSD.ORG Fri Apr 25 14:48:47 2014 Return-Path: Delivered-To: svn-doc-head@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 4F78CF47; Fri, 25 Apr 2014 14:48:47 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 2F5BA1C74; Fri, 25 Apr 2014 14:48:47 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3PEmlEX078561; Fri, 25 Apr 2014 14:48:47 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3PEml81078560; Fri, 25 Apr 2014 14:48:47 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404251448.s3PEml81078560@svn.freebsd.org> From: Dru Lavigne Date: Fri, 25 Apr 2014 14:48:47 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44662 - head/en_US.ISO8859-1/books/handbook/geom X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 25 Apr 2014 14:48:47 -0000 Author: dru Date: Fri Apr 25 14:48:46 2014 New Revision: 44662 URL: http://svnweb.freebsd.org/changeset/doc/44662 Log: Editorial review of mirror chapter. Mostly fixes to acronyms, links, and "filesystems" and sentences beginning with commands. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/geom/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/geom/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/geom/chapter.xml Fri Apr 25 14:07:42 2014 (r44661) +++ head/en_US.ISO8859-1/books/handbook/geom/chapter.xml Fri Apr 25 14:48:46 2014 (r44662) @@ -295,8 +295,8 @@ Done. - &man.dump.8; is used in these procedures to copy file - systems. But &man.dump.8; does not work on file systems with + While dump is used in these procedures to copy file + systems, it does not work on file systems with soft updates journaling. See &man.tunefs.8; for information on detecting and disabling soft updates journaling. @@ -307,34 +307,34 @@ Done. Many disk systems store metadata at the end of each disk. Old metadata should be erased before reusing the disk for a mirror. Most problems are caused by two particular types of - leftover metadata: GPT partition tables, and old - &man.gmirror.8; metadata from a previous mirror. + leftover metadata: GPT partition tables and old + metadata from a previous mirror. - GPT metadata can be erased with &man.gpart.8;. This - example erases both primary and backup GPT partition tables + GPT metadata can be erased with gpart. This + example erases both primary and backup GPT partition tables from disk ada8: &prompt.root; gpart destroy -F ada8 - &man.gmirror.8; can remove a disk from an active mirror - and erase the metadata in one step. Here, the example disk + A disk can be removed from an active mirror and the + metadata erased in one step using gmirror. Here, the example disk ada8 is removed from the active mirror gm4: &prompt.root; gmirror remove gm4 ada8 - If the mirror is not running but old mirror metadata is + If the mirror is not running, but old mirror metadata is still on the disk, use gmirror clear to remove it: &prompt.root; gmirror clear ada8 - &man.gmirror.8; stores one block of metadata at the end of - the disk. Because GPT partition schemes also store metadata - at the end of the disk, mirroring entire GPT disks with - &man.gmirror.8; is not recommended. MBR partitioning is used + When gmirror is used, one block of metadata is stored at the end of + the disk. Because GPT partition schemes also store metadata + at the end of the disk, mirroring entire GPT disks with + gmirror is not recommended. MBR partitioning is used here because it only stores a partition table at the start of - the disk and does not conflict with &man.gmirror.8;. + the disk and does not conflict with gmirror. @@ -347,8 +347,8 @@ Done. system. A new mirror will be created on these two disks and used to replace the old single disk. - &man.gmirror.8; requires a kernel module, - geom_mirror.ko, either built into the + The + geom_mirror.ko kernel module must either be built into the kernel or loaded at boot- or run-time. Manually load the kernel module now: @@ -358,17 +358,17 @@ Done. &prompt.root; gmirror label -v gm0 /dev/ada1 /dev/ada2 - gm0 is a user-chosen device name + In this example, gm0 is a user-chosen device name assigned to the new mirror. After the mirror has been started, this device name will appear in /dev/mirror/. - MBR and bsdlabel partition tables can now be created on - the mirror with &man.gpart.8;. Here we show a traditional - split-filesystem layout, with partitions for + MBR and bsdlabel partition tables can now be created on + the mirror with gpart. This example uses a traditional + file system layout, with partitions for /, swap, /var, /tmp, and /usr. A - single / filesystem and a swap partition + single / file system and a swap partition will also work. Partitions on the mirror do not have to be the same size @@ -400,14 +400,14 @@ Done. 18874370 137426928 6 freebsd-ufs (65G) 156301298 1 - free - (512B) - Make the mirror bootable by installing bootcode in the MBR + Make the mirror bootable by installing bootcode in the MBR and bsdlabel and setting the active slice: &prompt.root; gpart bootcode -b /boot/mbr mirror/gm0 &prompt.root; gpart set -a active -i 1 mirror/gm0 &prompt.root; gpart bootcode -b /boot/boot mirror/gm0s1 - Format the filesystems on the new mirror, enabling + Format the file systems on the new mirror, enabling soft-updates. &prompt.root; newfs -U /dev/mirror/gm0s1a @@ -415,9 +415,9 @@ Done. &prompt.root; newfs -U /dev/mirror/gm0s1e &prompt.root; newfs -U /dev/mirror/gm0s1f - Filesystems from the original + File systems from the original ada0 disk can now be copied onto the - mirror with &man.dump.8; and &man.restore.8;. + mirror with dump and restore. &prompt.root; mount /dev/mirror/gm0s1a /mnt &prompt.root; dump -C16 -b64 -0aL -f - / | (cd /mnt && restore -rf -) @@ -428,8 +428,8 @@ Done. &prompt.root; dump -C16 -b64 -0aL -f - /tmp | (cd /mnt/tmp && restore -rf -) &prompt.root; dump -C16 -b64 -0aL -f - /usr | (cd /mnt/usr && restore -rf -) - /mnt/etc/fstab must be edited to - point to the new mirror filesystems: + Next, edit /mnt/etc/fstab to + point to the new mirror file systems: # Device Mountpoint FStype Options Dump Pass# /dev/mirror/gm0s1a / ufs rw 1 1 @@ -438,21 +438,21 @@ Done. /dev/mirror/gm0s1e /tmp ufs rw 2 2 /dev/mirror/gm0s1f /usr ufs rw 2 2 - If the &man.gmirror.8; kernel module has not been built + If the geom_mirror.ko kernel module has not been built into the kernel, /mnt/boot/loader.conf is edited to load the module at boot: geom_mirror_load="YES" Reboot the system to test the new mirror and verify that - all data has been copied. The BIOS will see the mirror as two + all data has been copied. The BIOS will see the mirror as two individual drives rather than a mirror. Because the drives are identical, it does not matter which is selected to boot. - See the Troubleshooting - section if there are problems booting. Powering down and + See + if there are problems booting. Powering down and disconnecting the original ada0 disk will allow it to be kept as an offline backup. @@ -469,17 +469,17 @@ Done. system. A one-disk mirror will be created on the new disk, the existing system copied onto it, and then the old disk will be inserted into the mirror. This slightly complex procedure - is required because &man.gmirror.8; needs to put a 512-byte + is required because gmirror needs to put a 512-byte block of metadata at the end of each disk, and the existing ada0 has usually had all of its space already allocated. - Load the &man.gmirror.8; kernel module: + Load the geom_mirror.ko kernel module: &prompt.root; gmirror load Check the media size of the original disk with - &man.diskinfo.8;: + diskinfo: &prompt.root; diskinfo -v ada0 | head -n3 /dev/ada0 @@ -488,39 +488,37 @@ Done. Create a mirror on the new disk. To make certain that the mirror capacity is not any larger than the original drive, - &man.gnop.8; is used to create a fake drive of the exact same + gnop is used to create a fake drive of the exact same size. This drive does not store any data, but is used only to - limit the size of the mirror. When &man.gmirror.8; creates + limit the size of the mirror. When gmirror creates the mirror, it will restrict the capacity to the size of gzero.nop, even if the new drive (ada1) has more space. Note that the 1000204821504 in the second line should be equal to ada0's media size - as shown by &man.diskinfo.8; above. + as shown by diskinfo above. &prompt.root; geom zero load &prompt.root; gnop create -s 1000204821504 gzero &prompt.root; gmirror label -v gm0 gzero.nop ada1 &prompt.root; gmirror forget gm0 - gzero.nop does not store any - data, so the mirror does not see it as connected. The mirror + Since gzero.nop does not store any + data, the mirror does not see it as connected. The mirror is told to forget unconnected components, removing references to gzero.nop. The result is a mirror device containing only a single disk, ada1. After creating gm0, view the - partition table on ada0. - - This output is from a 1 TB drive. If there is some + partition table on ada0. This output is from a 1 TB drive. If there is some unallocated space at the end of the drive, the contents may be copied directly from ada0 to the new mirror. However, if the output shows that all of the space on the - disk is allocated like the following listing, there is no - space available for the 512-byte &man.gmirror.8; metadata at + disk is allocated, like in the following listing, there is no + space available for the 512-byte mirror metadata at the end of the disk. &prompt.root; gpart show ada0 @@ -533,9 +531,8 @@ Done. be explained later. In either case, partition tables on the primary disk - should be copied first with the &man.gpart.8; - backup and restore - subcommands. + should be first copied using gpart backup + and gpart restore. &prompt.root; gpart backup ada0 > table.ada0 &prompt.root; gpart backup ada0s1 > table.ada0s1 @@ -615,7 +612,7 @@ BSD 8 Both the slice and the last partition should have some free space at the end of each disk. - Create filesystems on these new partitions. The + Create file systems on these new partitions. The number of partitions will vary, matching the partitions on the original disk, ada0. @@ -625,7 +622,7 @@ BSD 8 &prompt.root; newfs -U /dev/mirror/gm0s1f &prompt.root; newfs -U /dev/mirror/gm0s1g - Make the mirror bootable by installing bootcode in the MBR + Make the mirror bootable by installing bootcode in the MBR and bsdlabel and setting the active slice: &prompt.root; gpart bootcode -b /boot/mbr mirror/gm0 @@ -650,15 +647,15 @@ BSD 8 /dev/mirror/gm0s1f /data1 ufs rw 2 2 /dev/mirror/gm0s1g /data2 ufs rw 2 2 - If the &man.gmirror.8; kernel module has not been built + If the geom_mirror.ko kernel module has not been built into the kernel, edit /boot/loader.conf to load it: geom_mirror_load="YES" - Filesystems from the original disk can now be copied onto - the mirror with &man.dump.8; and &man.restore.8;. Note that - it may take some time to create a snapshot for each filesystem + File systems from the original disk can now be copied onto + the mirror with dump and restore. Note that + it may take some time to create a snapshot for each file system dumped with dump -L. &prompt.root; mount /dev/mirror/gm0s1a /mnt @@ -676,9 +673,9 @@ BSD 8 ada1. If everything is working, the system will boot from mirror/gm0, which now contains the same data as - ada0 had previously. See the - Troubleshooting - section if there are problems booting. + ada0 had previously. See + + if there are problems booting. At this point, the mirror still consists of only the single ada1 disk. @@ -694,9 +691,9 @@ BSD 8 mirror/gm0 has the same contents as ada0 before adding ada0 to the mirror. If there is - something wrong with the contents copied by &man.dump.8; and - &man.restore.8;, revert /etc/fstab to - mount the filesystems on ada0, + something wrong with the contents copied by dump and + restore, revert /etc/fstab to + mount the file systems on ada0, reboot, and try the whole procedure again. @@ -704,8 +701,8 @@ BSD 8 GEOM_MIRROR: Device gm0: rebuilding provider ada0 Synchronization between the two disks will start - immediately. &man.gmirror.8; status - shows the progress. + immediately. Use gmirror status + to view the progress. &prompt.root; gmirror status Name Status Components @@ -720,7 +717,7 @@ mirror/gm0 DEGRADED ada1 (ACTIVE) mirror/gm0 COMPLETE ada1 (ACTIVE) ada0 (ACTIVE) - mirror/gm0 now consists of + The mirror, mirror/gm0, now consists of the two disks ada0 and ada1, and the contents are automatically synchronized with each other. In use, @@ -731,21 +728,12 @@ mirror/gm0 COMPLETE ada1 (ACTIVE) Troubleshooting - - Problems with Booting - - - BIOS Settings - - BIOS settings may have to be changed to boot from one + If the system no longer boots, BIOS + settings may have to be changed to boot from one of the new mirrored drives. Either mirror drive can be used for booting, as they contain identical data. - - - Boot Problems - - If the boot stopped with this message, something is + If the boot stops with this message, something is wrong with the mirror device: Mounting from ufs:/dev/mirror/gm0s1a failed with error 19. @@ -771,7 +759,7 @@ Manual root filesystem specification: mountroot> Forgetting to load the - geom_mirror module in + geom_mirror.ko module in /boot/loader.conf can cause this problem. To fix it, boot from a &os; 9.0 or later installation media and choose Shell at @@ -788,15 +776,15 @@ mountroot> Save the file and reboot. - Other problems that cause error 19 - require more effort to fix. Enter - ufs:/dev/ada0s1a at the boot loader - prompt. Although the system should boot from + Other problems that cause error 19 + require more effort to fix. Although the system should boot from ada0, another prompt to select a - shell appears because /etc/fstab is - incorrect. Press the Enter key at the prompt. Undo the - modifications so far by reverting - /etc/fstab, mounting filesystems from + shell will appear if /etc/fstab is + incorrect. Enter + ufs:/dev/ada0s1a at the boot loader + prompt and press Enter. Undo the + edits in + /etc/fstab then mount the file systems from the original disk (ada0) instead of the mirror. Reboot the system and try the procedure again. @@ -804,8 +792,6 @@ mountroot> Enter full pathname of shell or RETURN for /bin/sh: &prompt.root; cp /etc/fstab.orig /etc/fstab &prompt.root; reboot - - @@ -833,9 +819,8 @@ mountroot> &prompt.root; gmirror forget gm0 - Any old metadata should be - cleared from the - replacement disk. Then the disk, + Any old metadata should be cleared from the replacement disk using the instructions in + . Then the disk, ada4 for this example, is inserted into the mirror: