[Bug 287148] Handbook chapter 22 on ZFS is so outdated it is actually plainly wrong today

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=287148

            Bug ID: 287148
           Summary: Handbook chapter 22 on ZFS is so outdated it is
                    actually plainly wrong today
           Product: Documentation
           Version: Latest
          Hardware: Any
                OS: Any
            Status: New
          Severity: Affects Many People
          Priority: ---
         Component: Books & Articles
          Assignee: doc@FreeBSD.org
          Reporter: mops@punkt.de

Hi all,

while assisting an OPNsense user with SSD replacement in their root zpool, he
did something like

zpool attach zroot ada1p4 ada0

after replacing a failed ada0. Of course I told them that this is absolutely
not the way to do it, that their system will be unbootable in case ada1 fails,
etc.

We went through the procedure in the forum discussion and the system is up and
healthy with a mirrored pool and EFI and legacy boot partitions on both
devices, now.

For reference:

https://forum.opnsense.org/index.php?topic=47333.0


I then asked what gave them the idea to use the whole disk and they claimed
about every piece of documentation they could find said to do exactly that.

Now I was certain that at least FreeBSD's own docs would of course show how to
create a proper GPT partition to use for ZFS etc. and wanted to drop them a
link to the handbook.

To my great surprise and dismay the handbook uses procedures like this:

zpool create example /dev/da0

And in the next code example it references devices like /dev/ad0s1a.

- we don't have adN since ATA CAM became the default (in FreeBSD 8?)
- nobody is supposed to use MBR partitioning on current hardware in 2025
- nobody is supposed to use BSD partition tables on current hardware on 2025 -
even with UFS

This entire chapter is misleading, downright dangerous, and in conflict with
the structures our installer actually produces.


So how can we fix that? Summer of Code? I do not have the capacity to rewrite
that chapter myself.

Kind regards, take care,
Patrick

-- 
You are receiving this mail because:
You are the assignee for the bug.