Page MenuHomeFreeBSD

add new zfs(5) manpage
Needs ReviewPublic

Authored by seanc on Jul 26 2015, 3:19 PM.
Referenced Files
Unknown Object (File)
May 14 2024, 11:19 AM
Unknown Object (File)
May 14 2024, 10:21 AM
Unknown Object (File)
May 10 2024, 2:11 PM
Unknown Object (File)
May 8 2024, 5:00 AM
Unknown Object (File)
Apr 22 2024, 5:08 AM
Unknown Object (File)
Apr 7 2024, 1:07 AM
Unknown Object (File)
Apr 7 2024, 12:39 AM
Unknown Object (File)
Feb 23 2024, 12:30 PM


Group Reviewers

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

Diff Detail

rS FreeBSD src repository - subversion
Lint Skipped
Tests Skipped

Event Timeline

seanc retitled this revision from to zfs(5).
seanc updated this object.
seanc edited the test plan for this revision. (Show Details)
seanc added reviewers: dru, allanjude.
seanc set the repository for this revision to rS FreeBSD src repository - subversion.
seanc added a project: Doc Committers.
brueffer added inline comments.

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


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


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


No trailing ,

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!


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

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


"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.


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


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:


Not needed.


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?


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)


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


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


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'


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


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).


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.


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

linimon retitled this revision from zfs(5) to add new zfs(5) manpage.Aug 5 2018, 6:22 AM

Given the transition to OpenZFS:

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

From for zfs in section 8:

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

– and so on.


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

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

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.