From owner-freebsd-doc@FreeBSD.ORG Tue Jul 16 00:27:49 2013 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 8F7C47C9 for ; Tue, 16 Jul 2013 00:27:49 +0000 (UTC) (envelope-from freebsd@allanjude.com) Received: from mx1.scaleengine.net (beauharnois2.bhs1.scaleengine.net [142.4.218.15]) by mx1.freebsd.org (Postfix) with ESMTP id 6F78F312 for ; Tue, 16 Jul 2013 00:27:48 +0000 (UTC) Received: from [10.1.1.1] (S01060001abad1dea.hm.shawcable.net [50.70.108.129]) (Authenticated sender: allan.jude@scaleengine.com) by mx1.scaleengine.net (Postfix) with ESMTPSA id 8406F34A97 for ; Tue, 16 Jul 2013 00:18:39 +0000 (UTC) Message-ID: <51E4915F.9010303@allanjude.com> Date: Mon, 15 Jul 2013 20:18:39 -0400 From: Allan Jude User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:20.0) Gecko/20100101 Thunderbird/20.0 MIME-Version: 1.0 To: freebsd-doc@freebsd.org Subject: Re: Project GRUDS: Handbook disk reorg References: In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 16 Jul 2013 00:27:49 -0000 On 2013-07-15 19:23, Warren Block wrote: > Project GRUDS (Grand Unified Disk Storage) > > Goal: Edit and rewrite the scattered, repetitive, and conflicting > Handbook > sections on disk storage into a unified group. This would be a separate > in the Handbook, starting where chapter 19, Storage, currently > begins. > > The problem: Right now there are at least three different places in the > Handbook show disk partitioning methods and guidelines. All are > different, and none really complete. An in-depth chapter on > partitioning would allow sections to link to it and dispense with long > explanations that distract from the current topic. Besides reducing > redundancy, this would make many sections shorter and let users familiar > with the concepts skip ahead easily. > > It's a big project, but even as a plan would help future Handbook > contributions go in the right place. > > Tentative outline: > > > Part 4:Disk Storage > Introduction > Quick start > links to current methods for > mirror (gmirror and ZFS) > BIOS RAID (graid) > RAID-5/RAID-Z (ZFS) > > Disk Hardware Chapter > Introduction > Blocks > 512-byte > Advanced Format > Hardware RAID versus software RAID > Comparison, advantages and disadvantages > HAST? > Device names > SATA, IDE, SCSI, USB, most common hardware RAID device names > Conclusion > > > Disk Partitions Chapter > Introduction > Partitioning Schemes > Metadata (types, locations, conflicts) > MBR > GPT > Others > Conclusion > > > Labels Chapter (expanded from existing GEOM "Labeling Disk Devices") > Introduction > easy device relocatability > provided by geom_label (others?) > GPT labels > Generic labels (glabel(8)) > Filesystem labels > "Unique ID" labels > GPT UUID > ufsid > others? > Conclusion > > > GEOM Chapter ("Disk Device Transformations with GEOM"?) > Introduction > what is GEOM? > from existing GEOM chapter > additional section on graid(8) > sorted in order of most common usage (gmirror, graid, ...) > Conclusion > > > Filesystems Chapter > Introduction > what are filesystems? > UFS > traditional split-filesystem layout > newer, unified everything in root layout > Other filesystems > ext2, NTFS, etc > mention NFS, with pointer to NFS section in "Network Servers" > mention ZFS, and how it is more than a filesystem, and will be > covered in the next chapter > Conclusion > > > ZFS Chapter > neither fish nor fowl, it's a dessert topping *and* a floor wax > both device and filesystem > Introduction > what is it? > brief mention of best capabilities > in-depth > Conclusion > > > Backup Chapter > Introduction > UFS Backup (main part from existing Storage chapter) > ZFS Backup > Conclusion > _______________________________________________ > freebsd-doc@freebsd.org mailing list > http://lists.freebsd.org/mailman/listinfo/freebsd-doc > To unsubscribe, send any mail to "freebsd-doc-unsubscribe@freebsd.org" I definitely think this is a good idea, as I work on the ZFS chapter, I am often left wondering about where things that are not specific to ZFS should be covered. I imagine chapters 19 through 21 should be reorganized into a single coherent chapter, probably with a bit of stuff from the installation chapters moved here as well. Notes: Quick-start section should probably cover installation with 'root on zfs' Hardware chapter might mention SAS and things like SAS expanders and other enterprise hardware considerations The metadata storage location conflicts chapter is a really good idea. whole-disk GEOM + GPT is basically not possible, so you get in to per-partition GEOMs The labels bit should probably talk a bit about ZFS gUIDs and how ZFS does labels (this is both metadata and a label...) too The GEOM chapter should have at least a small stub for each GEOM type, like cache, journal, multipath, etc Moving ZFS to its own chapter is probably a good idea too. ZFS straddles the definition of raid transform, volume manager and file system (and maybe also block device for zvols), so doesn't fit neatly into the existing structure. For the ZFS chapter, this is the structure that bcr@ and myself proposed at the last docsprint (this is probably a lot more detail than you need, but if anyone has suggestions or ideas for additional things to do, please let me know): ZFS - ZFS introduction (what is ZFS) - ZFS Features and Terminology (giant table of definitions) - ZFS differences to other file systems (not sure about this one yet, or whether it should be part of the ZFS introduction section, could also just highlight differences to UFS, stuff we do not support out of the box like shareiscsi, zones) - quick start (get people started) - Admin Guide - zpool creation and destriction - Adding/Removing devices - Adding ZIL, L2ARC, hot spares - Dealing with failed devices - Upgrading a pool - Importing and exporting a pool - Checking the status of a pool - Performance monitoring (Built-in tools like iostat) - zpool split - ZFS administration - creating and destroying filesystems (explained in the terminology section) - creating and destroying volumes - renaming datasets - dataset properties (setting and querying as a general concept) - snapshots - clones - replication (you replicate a dataset, not an entire pool) - quota/reservation - compression - deduplication (copies property could go well in here, describe tradeoffs) - ZFS volumes - delegated administration - ZFS advanced topics and troubleshooting - root-on-ZFS installation? (or does this go in the bsdinstall chapter) - trouble booting off ZFS - BEADM? - zdb (?) - Fixing common problems one might encounter (devices offline, could be part of the zpool section) - Tuning recommendations? - ZFS on i386 - Links to ZFS evil tuning guide and other docs covering ZFS in even greater detail