Project GRUDS: Handbook disk reorg

[Allan Jude]

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
> <part> 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 at freebsd.org mailing list
> http://lists.freebsd.org/mailman/listinfo/freebsd-doc
> To unsubscribe, send any mail to "freebsd-doc-unsubscribe at 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