Page MenuHomeFreeBSD

add new zfs(5) manpage
Needs ReviewPublic

Authored by seanc on Jul 26 2015, 3:19 PM.

Details

Reviewers
allanjude
dru
mahrens
Group Reviewers
manpages
Summary

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

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

Diff Detail

Repository
rS FreeBSD src repository
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

seanc updated this revision to Diff 7344.Jul 26 2015, 3:19 PM
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.
seanc added a project: Doc Committers.
dru added a reviewer: mahrens.Jul 26 2015, 3:22 PM
brueffer added inline comments.
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 added a subscriber: wblock.Jul 26 2015, 3:53 PM

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

bcr added a subscriber: bcr.Jul 28 2015, 12:31 PM
allanjude added inline comments.Jul 28 2015, 4:09 PM
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.

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