man -- native and user-defined properties of ZFS datasets

[RamonAbudAlcala]

Hi! I was just reading the documentation on zfs properties and cannot quite understand something in the first few paragraphs. I hope someone here can help me.

The following is an exerpt with some highlights I want to point out:

Native Properties

Every dataset has a set of properties that export statistics about the dataset as well as control various behaviors. Properties are inherited from the parent unless overridden by the child. Some properties apply only to certain types of datasets (file systems, volumes, or snapshots).

The values of numeric properties can be specified using human-readable suffixes (for example, k, KB, M, Gb, and so forth, up to Z for zettabyte). The following are all valid (and equal) specifications: 1536M, 1.5g, 1.50GB.

The values of non-numeric properties are case sensitive and must be lowercase, except for mountpoint, sharenfs, and sharesmb.

The following native properties consist of read-only statistics about the dataset. These properties can be neither set, nor inherited. Native properties apply to all dataset types unless otherwise noted.

The subtitle is called "Native Properties". At the beginning it says that Properties are inherited unless otherwise stated, but at the end it says that (the following) Properties cannot be inherited. What is going on?

As I understand all "properties" within this subtitle are Native Properties (= "the following properties"). Are there some that can be inherited and others that can't. If so, which ones? I feel that this part of the documentation can be clarified.

Thanks in advance!

[rincebrain]

"Native properties" is meant to contrast with custom "User Properties" later, where you can set things like com.foo:myname=myvalue on a dataset, and ZFS itself doesn't care, it just stores the k/v pair and moves on.

First, it lists the things that are just read-only, because they're either computed things about the data on the dataset like usedbydataset, or compressratio, or because they're immutable things about the dataset itself (like origin for a cloned dataset, or creation for when it was made). Inherited isn't really the word I'd use to describe any relationship between them in say "mypool" and "mypool/thing".

That initial list is for those read-only properties, but if you go further down, it says:

The following native properties can be used to change the behavior of a ZFS dataset.

With other properties like checksum, compression, etc which change the behavior of the dataset after.

If you'd like to take a crack at making it seem more clear to you, by all means, go for it - since those are all autogenerated from the manpage, you could go for tweaking that appropriately, and the documentation would update to suit.