add new zfs(5) manpage

[seanc]

Summary

First pass at zfs(5). Flame suite on.

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

[brueffer]

cddl/contrib/opensolaris/cmd/zfs/zfs.5

13

I think there's a word missing here, "EXCLUDES"?

40

New sentence -> new line, also applies to a few places further down.

244

These should be sorted by section first, and by alphabet second.

249

No trailing ,

[wblock]

Please pardon the terseness in my comments, making them longer usually does not help clarity. They are suggestions and are mostly not meant literally but as ideas.
I only reviewed through the first third, will be back to look at the rest later. Thank you!

cddl/contrib/opensolaris/cmd/zfs/zfs.5

39

Kind of a long sentence, and "contained" is redundant. Maybe rearrange to get the point earlier:

Most
.Xr zfs 8
configuration information is contained within the pool and filesystem data and managed automatically.

40

"As detailed below" introduces an unnecessary pause and is not needed. This whole thing implies that the reader will be told about it, so this can be left out, leaving just:

Only a few external attributes are required.

43

The last half of this sentence about internal config was already stated above.

48

This sentence has already been stated twice. The term "bootstrapping" is vague, too. Does it mean "getting ZFS installed", or "making it able to boot", or something else? Let's just make the previous sentence do the work:

Only a few external attributes are required:

49

Not needed.

54

This assumes we want to enable ZFS, which is not unreasonable. But it would be better to explain what this particular setting enables. Same for the next entry: what is the difference between zfs_load (loading the module) and zfs_enable?

65

Try to avoid if/then sentences, which have a pause... like that one there. That can often be done by rearranging them. Also, I'm not sure we need to add an xref for each occurrence of ZFS.

This sentence is kind of hard to follow. I think it is saying this:

Additional configuration settings are available when using
.Xr gptzfsboot 8
to boot a ZFS filesystem:

("required" implies that the reader/user has to set them)

69

s/the following/these/ ("the following" almost always means "I am going to say some other stuff, and it will be after that")

[allanjude]

cddl/contrib/opensolaris/cmd/zfs/zfs.5

71

vsf.root.mountfrom is not required. The system defaults to booting from whichever dataset the zpool property 'bootfs' is set to

127

I think more of the configuration differences come from that fact that ZFS is the RAID controller, the Volume Manager, and the file system. And from the fact that storage is 'pooled'.

The CoW/log-structure adds some new features, like snapshots, clones etc, but likely has less to do with 'configuration'

157

You can still use fstab for some or all of your file systems. Set the zfs mountpoint property to 'legacy' and then use fstab

Also, this would be a good place to mention that this depends on the zfs_enable="YES" rc.conf flag, because the mounting is actually done by the /etc/rc.d/zfs script

191

in the ZFS book, we set a reservation of 10% of the space, rather than a quota on 90% of the space. This basically causes you to see '100% used' when you still have the 10% free, which is closer to the UFS behaviour (and sets off your low-space monitoring alarms sooner).

197

If you are not going to describe the heroic measures, it might be best not to mention them.

An explaination of why it is fatal might be more useful. "There must be space in the log to track the deletion of files..." etc.

Basically, there has to be room to store the 'dead list' of blocks that have been removed since the last snapshot, but this level of detail is likely too deep for this man page.

214

Describe more of what a snapshot is, to much the fact that it is 'free' into context.

[grahamperrin]

Given the transition to OpenZFS:

• please, does there remain a wish for a section 5 page for zfs?

From https://openzfs.github.io/openzfs-docs/man/8/zfs.8.html#DESCRIPTION for zfs in section 8:

> … tunables (zfs_*) are explained in zfs(4). …

– and so on.

[concussious.bugzilla_runbox.com]

Related:

In D3207#808568, @grahamperrin wrote:

• please, does there remain a wish for a section 5 page for zfs?

We are moving all the filesystem meta manuals to section four:

https://github.com/freebsd/freebsd-src/pull/1077

The only one we're leaving in section five is fs(5), which is about the format of the on-disk structures of UFS family filesystems.