Differences between the datasets properties in zfs

[musjj]

I'm new to zfs and I'm kind of confused with the properties listed in the example: https://github.com/nix-community/disko/blob/master/example/zfs.nix

For example, there are apparently 3 ways of setting mountpoint:

• datasets.*.mountpoint
• datasets.*.options.mountpoint
• datasets.*.content.mountpoint

Can anyone explain the differences and the CLI equivalent so I can look it up in the docs?

[TheRealGramdalf]

• datasets.*.mountpoint

• This sets a "legacy" mountpoint, aka the fstab. Typical ZFS installations instead use the mountpoint property (see the next point)

• datasets.*.options.mountpoint

• This sets the respective zfsprop - the native feature used by ZFS to automatically mount datasets independently of fstab (typically via a systemd service that grabs information from the datasets and mounts it). datasets.*.options.* can actually be used to set any zfsprop - compression, encryption, or even custom user-specified ones like com.sun:auto-snapshot (which is used in second party tooling outside of ZFS, in this case some sort of sun microsystems thing).

• datasets.*.content.mountpoint

• This isn't actually valid - I believe you're referring to disko.devices.<devicename>.content.partitions.<partname>.content.mountpoint, not disko.devices.zpool.<zpoolname>.datasets.<datasetname>.content.mountpoint. In actuality it doesn't really matter - since neither are valid in the context - the former is only valid if disko.devices.<devicename>.content.partitions.<partname>.type is NOT zfs.
  • It essentially boils down to ambiguous wording - disko.devices.zpool is used to define the contents inside a zfs pool - datasets, zfs volumes, and their respective properties - whereas disko.devices.<devicename>... defines the physical layout of the zfs pool as a whole (what disks to use, whether to use an entire disk or a single partition etc). Disko further abstracts upon this by adding in custom glue in the form of mountpoint.
  • In my mind the best solution would be to rename mountpoint to something like fstabEntry to disambiguate the two - mountpoint is generic and has it's own special meaning in various contexts. One alternative (or additional?) solution would be to rename ...<datasetname>.options to ...<datasetname>.properties/zfsprops, since that aligns closer to the upstream implementation.

Edit:
Further confusion comes because in order to use an fstab entry to mount a zfs dataset, you need to set the zfsprop mountpoint=legacy for it to work properly.

p.s. I realize that changing an option name isn't ideal, but it's not unheard of, and is in my opinion better to do sooner rather than later, in case disko sees more widespread adoption and it becomes even more cemented. Part of the problem is also the lack of easily readable docs, so some of this concern may be invalid once those are available (though I personally prefer explicit configuration rather than ambiguous configuration).