Bug 135983
| Summary: | "The Z File System" - title is misleading and causes search issue | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | Dan Naumov <dan.naumov> |
| Component: | Books & Articles | Assignee: | freebsd-doc (Nobody) <doc> |
| Status: | Closed FIXED | ||
| Severity: | Affects Only Me | ||
| Priority: | Normal | ||
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
|
Description
Dan Naumov
2009-06-23 23:00:13 UTC
On Tue, 23 Jun 2009 21:53:27 GMT Dan Naumov <dan.naumov@gmail.com> wrote: > > >Number: 135983 > >Category: docs > >Synopsis: "The Z File System" - title is misleading and causes search issue > >Confidential: no > >Severity: non-critical > >Priority: medium > >Responsible: freebsd-doc > >State: open > >Quarter: > >Keywords: > >Date-Required: > >Class: doc-bug > >Submitter-Id: current-users > >Arrival-Date: Tue Jun 23 22:00:13 UTC 2009 > >Closed-Date: > >Last-Modified: > >Originator: Dan Naumov > >Release: 7.2-RELEASE > >Organization: > >Environment: > FreeBSD atom.localdomain 7.2-RELEASE-p1 FreeBSD 7.2-RELEASE-p1 #0: Tue Jun 9 18:02:21 UTC 2009 root@amd64-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC amd64 > >Description: > People looking for information regarding ZFS support in FreeBSD are very likely to start by opening the handbook table of contents in their web browser, initiate their browser search function and search for "ZFS". This will result in 0 matches and the user will be left confused, thinking the handbook has no articles on the subject. > > Proposal: edit the following files: > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/filesystems-zfs.html > > and change any instances of "The Z File System" (a name which has no basis on reality) to "ZFS - Zettabyte File System". This will make the term searchable using web browser (or any other viewer) search functions allowing easier access for the user. Additionally this would decipher the ZFS acronym in a proper way with actual basis on the origin of the name. Actually, the term "Zettabyte" is out dated too. As for the "Z file system" - I read that somewhere. I just can't remember, perhaps it was the source code or a link on Sun's site or a developer blog; trust me, I wouldn't have used it otherwise. Searching around it appears that it's an orphan acronym (according to: http://opensolaris.org/os/community/zfs/faq/#whatstandfor) I have no issue with the changes, and may even make them myself if I find the time; however, I just wanted to explain where the "basis of reality" part. Thanks, --- Tom Rhodes Tom Rhodes wrote: > The following reply was made to PR docs/135983; it has been noted by GNATS. > > From: Tom Rhodes <trhodes@FreeBSD.org> > To: Dan Naumov <dan.naumov@gmail.com> > Cc: bug-followup@FreeBSD.org > Subject: Re: docs/135983: "The Z File System" - title is misleading and > causes search issue > Date: Wed, 24 Jun 2009 02:58:47 -0400 > > On Tue, 23 Jun 2009 21:53:27 GMT > Dan Naumov <dan.naumov@gmail.com> wrote: > > > > > >Number: 135983 > > >Category: docs > > >Synopsis: "The Z File System" - title is misleading and causes search issue > > >Confidential: no > > >Severity: non-critical > > >Priority: medium > > >Responsible: freebsd-doc > > >State: open > > >Quarter: > > >Keywords: > > >Date-Required: > > >Class: doc-bug > > >Submitter-Id: current-users > > >Arrival-Date: Tue Jun 23 22:00:13 UTC 2009 > > >Closed-Date: > > >Last-Modified: > > >Originator: Dan Naumov > > >Release: 7.2-RELEASE > > >Organization: > > >Environment: > > FreeBSD atom.localdomain 7.2-RELEASE-p1 FreeBSD 7.2-RELEASE-p1 #0: Tue Jun 9 18:02:21 UTC 2009 root@amd64-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC amd64 > > >Description: > > People looking for information regarding ZFS support in FreeBSD are very likely to start by opening the handbook table of contents in their web browser, initiate their browser search function and search for "ZFS". This will result in 0 matches and the user will be left confused, thinking the handbook has no articles on the subject. > > > > Proposal: edit the following files: > > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/ > > http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/filesystems-zfs.html > > > > and change any instances of "The Z File System" (a name which has no basis on reality) to "ZFS - Zettabyte File System". This will make the term searchable using web browser (or any other viewer) search functions allowing easier access for the user. Additionally this would decipher the ZFS acronym in a proper way with actual basis on the origin of the name. > > Actually, the term "Zettabyte" is out dated too. As for the "Z > file system" - I read that somewhere. I just can't remember, > perhaps it was the source code or a link on Sun's site or a > developer blog; trust me, I wouldn't have used it otherwise. > Searching around it appears that it's an orphan acronym > (according to: > http://opensolaris.org/os/community/zfs/faq/#whatstandfor) > > I have no issue with the changes, and may even make them > myself if I find the time; however, I just wanted to > explain where the "basis of reality" part. Thanks, > > --- > Tom Rhodes > The chapter still appears when using the "search the Handbook" link, so I feel this is not much of an issue. As a compromise though, we could probably change the title to: "The Z File System (ZFS)" Hopefully you didn't take an offense to my initial PR, the Handbook guide was what actually had me started on getting into ZFS with FreeBSD :) Either way, I had some other changes in mind as well, for example the RAID-Z example uses a pool made of 2 disks. While it will obviously work, all SUN documentation indicates that the suggested amount of vdevs for a RAIDZ or RAIDZ2 pool is between 3 and 9 devices and that bigger pools should be broken up to be made of smaller groups of vdevs (for example 2 x 7disk RAIDZ for a single pool 14 disk setup).. Using RAIDZ with just 2 disks will result in slower performance than simply using a ZFS mirror and using more than 9 disks is likely to cause problems with parity computations (I have already heard stories of people running into Bad Things (tm) while using a 24-disk RAIDZ-2 and a 14-disk RAIDZ configurations during resilvering and scrubs). Things like this definitely deserve a mention. If you don't have much time, I could see if I could find a few moments over the next week or 2 to make a few changes. What's the proposed format of change submissions? Are edited files ok or does one need to submit patches and if it's the latter, whats the syntax for making properly suited diffs? - Sincerely, Dan Naumov Patch below, please comment if you disagree or commit if you don't :)
==============================================================
diff -ru /DATA/bsdwork/docs/doc/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml
/DATA/bsdwork/docs/doc-mine/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml
--- /DATA/bsdwork/docs/doc/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml 2008-11-26
06:54:41.000000000 +0200
+++ /DATA/bsdwork/docs/doc-mine/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml 2009-06-30
02:33:10.786630005 +0300
@@ -108,7 +108,7 @@
</sect1>
<sect1 id="filesystems-zfs">
- <title>The Z File System</title>
+ <title>The Z File System (ZFS)</title>
<para>The Z file system, developed by &sun;, is a new
technology designed to use a pooled storage method. This means
@@ -198,19 +198,20 @@
<screen>&prompt.root; <userinput>echo 'zfs_enable="YES"' >>
/etc/rc.conf</userinput>
&prompt.root; <userinput>/etc/rc.d/zfs start</userinput></screen>
- <para>The remainder of this document assumes two
+ <para>The remainder of this document assumes 3
<acronym>SCSI</acronym> disks are available, and their device names
- are <devicename><replaceable>da0</replaceable></devicename>
- and <devicename><replaceable>da1</replaceable></devicename>
- respectively. Users of <acronym>IDE</acronym> hardware may
- use the <devicename><replaceable>ad</replaceable></devicename>
+ are <devicename><replaceable>da0</replaceable></devicename>,
+ <devicename><replaceable>da1</replaceable></devicename>
+ and <devicename><replaceable>da2</replaceable></devicename>.
+ Users of <acronym>IDE</acronym> hardware may use the
+ <devicename><replaceable>ad</replaceable></devicename>
devices in place of <acronym>SCSI</acronym> hardware.</para>
<sect3>
<title>Single Disk Pool</title>
- <para>To create a <acronym>ZFS</acronym> over a single disk
- device, use the <command>zpool</command> command:</para>
+ <para>To create a simple, non-redundant <acronym>ZFS</acronym> pool using a
+ single disk device, use the <command>zpool</command> command:</para>
<screen>&prompt.root; <userinput>zpool create example
/dev/da0</userinput></screen>
@@ -340,13 +341,19 @@
<title><acronym>ZFS</acronym> RAID-Z</title>
<para>As previously noted, this section will assume that
- two <acronym>SCSI</acronym> exists as devices
- <devicename>da0</devicename> and
- <devicename>da1</devicename>. To create a
+ 3 <acronym>SCSI</acronym> discs exist as devices
+ <devicename>da0</devicename>, <devicename>da1</devicename>
+ and <devicename>da2</devicename>. To create a
<acronym>RAID</acronym>-Z pool, issue the following
command:</para>
- <screen>&prompt.root; <userinput>zpool create storage raidz da0
da1</userinput></screen>
+ <screen>&prompt.root; <userinput>zpool create storage raidz da0 da1
da2</userinput></screen>
+
+ <warning><para>The recommended amount of devices to be used in a
<acronym>RAID</acronym>-Z
+ configuration is 3-9. If your needs call for a single pool to
consist of 10 disks or more,
+ consider breaking it up into groups of smaller
<acronym>RAID</acronym>-Z. If you only
+ have 2 disks and require redundancy, consider using a
<acronym>ZFS</acronym> mirror
+ configuration. See the &man.zpool.8; manual page for more
details.</para></warning>
<para>The <literal>storage</literal> zpool should have been
created. This may be verified by using the &man.mount.8; and
@@ -432,8 +439,8 @@
/dev/ad0s1a 2026030 235240 1628708 13% /
devfs 1 1 0 100% /dev
/dev/ad0s1d 54098308 1032826 48737618 2% /usr
-storage 17547008 0 17547008 0% /storage
-storage/home 17547008 0 17547008 0% /home</screen>
+storage 26320512 0 26320512 0% /storage
+storage/home 26320512 0 26320512 0% /home</screen>
<para>This completes the <acronym>RAID</acronym>-Z
configuration. To get status updates about the file systems
@@ -477,6 +484,7 @@
raidz1 DEGRADED 0 0 0
da0 ONLINE 0 0 0
da1 OFFLINE 0 0 0
+ da2 ONLINE 0 0 0
errors: No known data errors</screen>
@@ -509,6 +517,7 @@
raidz1 ONLINE 0 0 0
da0 ONLINE 0 0 0
da1 ONLINE 0 0 0
+ da2 ONLINE 0 0 0
errors: No known data errors</screen>
@@ -556,6 +565,7 @@
raidz1 ONLINE 0 0 0
da0 ONLINE 0 0 0
da1 ONLINE 0 0 0
+ da2 ONLINE 0 0 0
errors: No known data errors</screen>
==============================================================
- Sincerely,
Dan Naumov
In case I managed to screw up formatting using gmail, here is a direct link to the patch file: http://jago.pp.fi/temp/filesystems.chapter.sgml.patch.txt For future reference, when submitting patches, am I supposed to include them into the email body of replying to the PR or am I supposed to include the patch file(s) as an attachment? - Sincerely, Dan Naumov Hello Considering the amount of time during which nothing has happened, am I to assume that my patch submission has been deemed unnecessary and the PR itself unimportant? Would be nice to get some kind of closure, either a commit of the patch I have submitted or a decline of the patch and closure of the PR with a brief explanation for the decline. Sincerely, Dan Naumov remko 2009-08-11 07:10:14 UTC
FreeBSD doc repository
Modified files:
en_US.ISO8859-1/books/handbook/filesystems chapter.sgml
Log:
Tidy up the ZFS section a bit, adjust the RAID-Z example from two to three
drives and add a warning that the suggested configuration is between three
to nine disks.
PR: 135983
Revision Changes Path
1.6 +27 -14 doc/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml
_______________________________________________
cvs-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/cvs-all
To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
State Changed From-To: open->closed Committed, thanks for the reminder! |
