From nobody@FreeBSD.org  Wed Jun 18 14:05:06 2008
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 0D374106566B
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 18 Jun 2008 14:05:06 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (www.freebsd.org [IPv6:2001:4f8:fff6::21])
	by mx1.freebsd.org (Postfix) with ESMTP id EB0FF8FC0C
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 18 Jun 2008 14:05:05 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.14.2/8.14.2) with ESMTP id m5IE55Ov082783
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 18 Jun 2008 14:05:05 GMT
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.14.2/8.14.1/Submit) id m5IE55m4082782;
	Wed, 18 Jun 2008 14:05:05 GMT
	(envelope-from nobody)
Message-Id: <200806181405.m5IE55m4082782@www.freebsd.org>
Date: Wed, 18 Jun 2008 14:05:05 GMT
From: Hywel Mallett <Hywel@hmallett.co.uk>
To: freebsd-gnats-submit@FreeBSD.org
Subject: Geom RAID1 handbook example only covers boot partition
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         124716
>Category:       docs
>Synopsis:       [patch] GEOM RAID1 handbook example only covers boot partition
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    dru
>State:          closed
>Quarter:        
>Keywords:       handbook
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jun 18 14:10:02 UTC 2008
>Closed-Date:    Fri Apr 11 16:29:12 UTC 2014
>Last-Modified:  Fri Apr 11 16:29:12 UTC 2014
>Originator:     Hywel Mallett
>Release:        
>Organization:
>Environment:
>Description:
In the handbook the section on RAID0 is very clear, and gives a good example of how to configure a new RAID0 array and newfs it. This section assumes that the new array is an additional array to be added to /etc/fstab.
By contrast the section on RAID1 assumes that you want a mirrored root partition on a newly-installed system. The extra complexities mean that the section is confusing to a beginner.
>How-To-Repeat:

>Fix:
Move the existing RAID1 section to a new section - "How to mirror your boot partition" (or similar).
Create a new RAID1 section covering how to add a RAID1 array as an additional filesystem, in the same vein as the current RAID0 section.

>Release-Note:
>Audit-Trail:

From: hywel@hmallett.co.uk
To: FreeBSD-gnats-submit@FreeBSD.org, freebsd-doc@FreeBSD.org
Cc:  
Subject: Re: docs/124716: Geom RAID1 handbook example only covers boot
	partition
Date: Wed, 18 Jun 2008 15:27:35 +0100

 This message is in MIME format.
 
 --=_2pc7evbkmg6c
 Content-Type: text/plain;
 	charset=ISO-8859-1;
 	DelSp="Yes";
 	format="flowed"
 Content-Disposition: inline
 Content-Transfer-Encoding: 7bit
 
 Patch attached for perusal. It is to be applied to chapter.sgml in the  
 geom directory.
 I've merely copied the sgml from the existing article - it may not be  
 standards-compliant.
 
 
 
 --=_2pc7evbkmg6c
 Content-Type: text/plain;
 	charset=UTF-8;
 	name="geom.txt.diff.txt"
 Content-Disposition: attachment;
 	filename="geom.txt.diff.txt"
 Content-Transfer-Encoding: quoted-printable
 
 --- chapter.sgml        2008-06-18 15:23:31.000000000 +0100
 +++ chapter.sgml.new    2008-06-18 15:23:52.000000000 +0100
 @@ -239,11 +239,77 @@
        interruption, and even be physically stored in a data
        safe.</para>
 
 +    <procedure>
 +      <title>Creating a mirror of unformatted ATA disks</title>
 +
 +      <step><para>Load the <filename>geom_mirror</filename>
 +        module:</para>
 +
 +    <screen>&prompt.root; <userinput>kldload geom_mirror</userinput></scree=
 n>
 +       </step>
 +
 +      <step><para>Ensure that a suitable mount point exists, such as <filen=
 ame
 +        role=3D"directory">/mnt</filename>:</para>
 +
 +        <screen>&prompt.root; <userinput>mkdir /mnt</userinput></screen>
 +      </step>
 +
 +      <step><para>Determine the device names for the disks which will
 +        be mirrored, and create the new mirror device.  For example,
 +       to mirror two unused and unpartitioned <acronym>ATA</acronym> disks,
 +       for example <filename>/dev/ad2</filename> and
 +       <filename>/dev/ad3</filename>:</para>
 +
 +        <screen>&prompt.root; <userinput>gmirror label -vb round-robin gm0 =
 /dev/ad2 /dev/ad3</userinput></screen>
 +
 +<!--
 +    <para>A message should be returned explaining that meta data has
 +      been stored on the devices.
 +XXX: What message?  Put it inside the screen output above.
 +-->
 +      </step>
 +
 +      <step><para>Write a standard label, also known as a partition
 +        table, on the new volume:</para>
 +
 +        <screen>&prompt.root; <userinput>bsdlabel -w /dev/mirror/gm0</useri=
 nput></screen>
 +
 +      </step>
 +
 +      <step><para>This process should have created two other devices
 +        in the <filename role=3D"directory">/dev/mirror</filename>
 +        directory in addition to the <devicename>gm0</devicename> device.
 +        Those include <devicename>gm0a</devicename> and
 +        <devicename>gm0c</devicename>.  At this point a file system may be =
 created
 +        on the <devicename>gm0a</devicename> device with the
 +        <command>newfs</command> utility:</para>
 +
 +      <screen>&prompt.root; <userinput>newfs -U /dev/mirror/gm0a</userinput=
 ></screen>
 +
 +      <para>Many numbers will glide across the screen, and after a few
 +        seconds, the process will be complete.  The volume has been
 +        created and is ready to be mounted.</para>
 +    </step>
 +  </procedure>
 +
 +  <para>To manually mount the created disk stripe:</para>
 +
 +  <screen>&prompt.root; <userinput>mount /dev/mirror/gm0a /mnt</userinput><=
 /screen>
 +
 +  <para>To mount this striped file system automatically during the boot
 +    process, place the volume information in
 +    <filename>/etc/fstab</filename> file:</para>
 +
 +  <screen>&prompt.root; <userinput>echo "/dev/mirror/gm0a /mnt ufs rw 2 2" =
 \</userinput>
 +    <userinput>&gt;&gt; /etc/fstab</userinput></screen>
 +
 +    <para>To use gmirror on a root partition, more steps are required for s=
 etup</para>
 +
      <para>To begin, ensure the system has two disk drives of equal size,
        this exercise assumes they are direct access (&man.da.4;)
        <acronym>SCSI</acronym> disks.</para>
 -
 -    <para>Begin by installing &os; on the first disk with only two
 +
 +   <para>Begin by installing &os; on the first disk with only two
        partitions.  One should be a swap partition, double the
        <acronym>RAM</acronym> size and all remaining space devoted to
        the root (<filename role=3D"directory">/</filename>) file system.
 
 --=_2pc7evbkmg6c--
 
State-Changed-From-To: open->analyzed 
State-Changed-By: trhodes 
State-Changed-When: Wed Sep 10 05:41:07 UTC 2008 
State-Changed-Why:  
Working on a new gmirror section, would like to further 
investigate this idea.  Take the PR. 


Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Wed Sep 10 05:41:07 UTC 2008 
Responsible-Changed-Why:  
Working on a new gmirror section, would like to further 
investigate this idea.  Take the PR. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=124716 
Responsible-Changed-From-To: trhodes->dru 
Responsible-Changed-By: dru 
Responsible-Changed-When: Fri Apr 11 16:27:13 UTC 2014 
Responsible-Changed-Why:  
I'll take this one. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=124716 
State-Changed-From-To: analyzed->closed 
State-Changed-By: dru 
State-Changed-When: Fri Apr 11 16:27:46 UTC 2014 
State-Changed-Why:  
Looking through the source of this doc, it looks like it only 
contained one example when the bug was reported. It has had 
two examples for some time now, which should address the 
submitter's request. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=124716 
>Unformatted:
