First pass at zfs(5). Flame suite on.
Diff Detail
Diff Detail
- Repository
- rS FreeBSD src repository - subversion
- Lint
Lint Skipped - Unit
Tests Skipped
Event Timeline
Comment Actions
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 | |
| 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 ("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") | |
| 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. | |
Comment Actions
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.