Re: ZFS upgrade loader actions -- is it possible to check before reboot if your system will reboot cleanly?

On Fri, Nov 24, 2023, at 18:40, Dan Mahoney (Ports) wrote:
> I was reading a couple recent threads (one about upgrading from 13.2 to 14) and another more virtiolic
> thread about how terrible, awful, no-good our documentation is.  I don’t agree with this.  
> 
> I shied away from Linux for years because of nonfunctional man pages, or man pages that someone
> bothered to write, but then to only point to a postscript file on disk, or to point at an “info” file.
> I mused regularly that it’s sad that “The Linux Documentation Project” website is in fact a whole
> different website from “The Linux Project”…or any hundred of Linux Projects.  
> 
> Anyway, both threads talked about zpool upgrades and needing to update your bootloader. I was recently
> bitten by this, requiring my datacenter to put a physical disc in a drive for me to recover from.  (And
> I even had to ship them a USB cdrom drive — don’t get me started on supermicro’s virtual media
> implementation.  it’s bad).
> 
> I understand that printing the raw commands to upgrade your boot loader (and/or your pmbr) as part of
> the output of a successful “zpool upgrade” is probably a bad idea, as the commands are not
> one-size-fits-all, but having a special manpage for this process, specifically (and having zpool
> upgrade point at that page) might be useful. 
> 
> If the handbook doesn’t say something about this process, then it should as well.
> 
> But also, it would be really nice to be able to poll the version of the various components that are
> actually installed on the system (the boot loader, and even the pmbr if you have one) and see if
> they’re current and can support the current version of your boot pool.
> 
> I don’t know if this is possible.  Gpart bootcode, for example, only has a command to *install* the
> bootcode, not read it back.  Since the loader and the mbr are tiny, highly optimized pieces of code, I
> don’t know if there are any strings that can be examined to see if they match the running system.  But
> if the tools don’t exist, they should — even absent any version strings, if nothing else, gpart
> bootcode should be able to non-intrusively compare a file with the already existing one.
> 
> Does anyone know for sure?
> 
> -Dan

There are at least 4 different types of documentation.
* Developer API documentation
* User interface documentation
* How to/Example documentation
* FAQs

From my point of view Linux is better bottom up and FreeBSD is better top down. Though that is an issue for your request because the current boot loader documentation definitely has a more developer bent to it.