Inconsistent and ambiguous naming - should this be reported as a bug ?

[gitcnd]

TLDR;- naming/ambiguity problem:-

• zpool
• pool
• poolname
• vdev
• filesystem
• device
• deviceid
• root file system
• dataset
• mountpoint
• directory
• volume
• label
• hostid
• snapshot
• filename
• device
• ... many more

I'm relatively new to ZFS, but a reasonably proficient Linux admin and developer, and the naming and guesswork (by the software itself, not just my brain) is very frustrating:

For example - in "man zfs-rename" it says this:-
zfs rename [-f] filesystem|volume|snapshot filesystem|volume|snapshot
which appears like it's guessing whether I'm talking about a filesystem or a volume or a snapshot based on whatever I enter.

I can also do this:-

NAME   USED  AVAIL     REFER  MOUNTPOINT
zcdc   673G  17.4T      673G  /home

which introduces two new things - a "NAME" of unknown meaning, and a mountpoint.

I can do this as well:-

# zpool status
  pool: zcdc
 state: ONLINE
status: Mismatch between pool hostid and system hostid on imported pool.
        This pool was previously imported into a system with a different hostid,
        and then was verbatim imported into this system.
action: Export this pool on all systems on which it is imported.
        Then import it to correct the mismatch.
   see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-EY
config:

        NAME                                                     STATE     READ WRITE CKSUM
        zcdc                                                     ONLINE       0     0     0
          raidz1-0                                               ONLINE       0     0     0
            ata-ST10000DM0004-1ZC101_ZKG00H7Z                    ONLINE       0     0     0
            ata-ST10000VN0004-1ZD101_ZA21EAXE                    ONLINE       0     0     0
            ata-WDC_WD100EZAZ-11TDBA0_JEHZ8D9N                   ONLINE       0     0     0
        logs
          ata-Samsung_SSD_860_EVO_M.2_1TB_S415NS0R401524N-part6  ONLINE       0     0     0
        cache
          sde1                                                   ONLINE       0     0     0

which introduces something called a "pool" (probably short for "poolname", but the programmer wanted the text to line up pretty at the expense of confusion, so omitted the word "name" from after the word pool?
We also see another THREE different NAMEs of unknown types one which also says "zcdc", another which seems to mean the kind of pool it is (raidz) and more which are my disk ids, and as another example of guesswork - it's omitted the /dev/by-id/ prefix from my disk volumes, and mangled my cache into "sde1" (I specificed it with zpool add -f zcdc cache ata-Samsung_SSD_860_EVO_M.2_1TB_S415NS0R401524N-part1 but that naming doesn't seem to persist properly).

As you can see - I need to change the "hostid" (which is not called a "hostid", but instead called "label") so I tried this:

# zpool labelclear zcdc
failed to open zcdc: Is a directory

and now we have another new concept arriving called "directory".

I tried this (I explain why next):-

# zfs rename -u zcdc cdc
cannot create 'cdc': missing dataset name

which now introduced yet-another thing called a "dataset name"... and goes on to say that it cannot create the name "cdc" because I didn't give it the name "cdc", which I did... so the error itself also makes no sense now.

I'm guessing now that my pool named "zcdc" contains a datasetname of "zcdc" (the same name - so if that's true, someplace in the setup, zfs itself has decided to use the name I gave it for two different things at once). hence my above attempt to rename it.

In terms of GRUB, a new concept of a "ZFS dataset that contains the root file system" is introduced - it's not clear what "root" means (probably not folder "/root" - I'm guessing they mean the "/" filesystem, upon which /etc is located) and the option to use that is as follows:-

root=ZFS=rpool/ROOT/void.

and

zfs set bootfs=rpool/ROOT/void rpool

so once again we see a bunch of new concepts with inexplicable names - what's the "ROOT" in all-caps mean? Is that supposed to mean the "/" mountpoint, except we can't use that because it's a separator character? Does "void" mean it's blank, but blanks can't be entered? What's the last "rpool" for?

I've read a pile of forum postings from other people having major issues when things have the same names...

I'm confident this needs to be fixed. I'm not stupid (I hope) and after 3 days of learning all this (which includes building it to run on custom kernels and booting it) I still can't make head or tails of the naming.

So my questions:

1. Should this be fixed? Should we ask for the naming of everything to be totally unambiguous at all times, and ask for them never to call anything by any more than one of those things (e.g. never call a "hostid" a "label" when it's the same thing).
2. Should we ask for some sanity checking to be added, so it's never possible for us to name anything when any name we pick is going to clash with any other name that exists already (e.g. never allow a single name like "zcdc" to be used on any more than one thing at once (if it's a pool - ban it as a name for a dataset or mountpoint or volume or label or hostid or snapshor or filename or device or anything else that's possible to have a name).
3. Alternatively, should we ask for some way to disambiguate things? e.g. let us put pool:zcdc so it can never get mixed up with dataset:zcdc
4. Is it even possible for any of this to be fixed? zfs is an antique product from "sun" I gather, and I'm guessing that there's going to be crushing resistance from "upstream" for anything to be changed to make it easier to understand - would that be an accurate assessment of the status of new-feature-liklihood ?

[rincebrain]

You might find zpoolconcepts.7 and zfsconcepts.7 useful to start, and this useful for more detailed information.

[gitcnd]

Thanks - grateful for the suggestion, however, why/how does any of that apply to my topic? All of those resources suffer from the same problems I've mentioned above, and with the exception of trying to update my hostid, I think I've eventually managed to understand everything? (I'm not asking for help here - just trying to contribute suggestions, as a newcomer, to help all other newcomers in future).

You obviously cannot have any kind of working documentation you can point anyone to, when the software itself uses different terminology, and when all of the terminology in use is ambiguous or nonspecific or differs (e.g. the "labelclear" command is used to clear the hostid, and the word "pool" refers to a zpool, not any other kind of pool (like those unrelated to zfs), and that word itself never actually means "pool" in the firstplace - it almost always means zpoolname, except in basically all commandline output, it has the heading of "NAME" instead of zpoolname - except for all other output where the heading NAME means some other kind of name - like it does when they use that heading for datasetnames, device identifiers, and device labels to name just a few) - see the problem?

[rincebrain]

I interpreted this as a request for clarification on the terminology involved.

As I was clearly far off the mark, I'll leave this for someone else to address.

[gitcnd]

"clarification on the terminology involved" - You were almost spot-on, except I meant for everyone, all the time, not just me, now. (and that arstechnica article looks useful, but for for now I'm going to solve my hostid issue with a wipefs and rebuild of the entire array - a whole day is more than enough down that bad-naming rabbithole!)