Changeset View
Standalone View
cddl/contrib/opensolaris/cmd/zfs/zfs.5
- This file was added.
.\" Copyright (c) 2015 | |||||
.\" Sean Chittenden | |||||
.\" | |||||
.\" Redistribution and use in source and binary forms, with or without | |||||
.\" modification, are permitted provided that the following conditions | |||||
.\" are met: | |||||
.\" 1. Redistributions of source code must retain the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer. | |||||
.\" 2. Redistributions in binary form must reproduce the above copyright | |||||
.\" notice, this list of conditions and the following disclaimer in the | |||||
.\" documentation and/or other materials provided with the distribution. | |||||
.\" | |||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND | |||||
brueffer: I think there's a word missing here, "EXCLUDES"? | |||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE | |||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |||||
.\" SUCH DAMAGE. | |||||
.\" | |||||
.\" $FreeBSD$ | |||||
.\" | |||||
.Dd July 25, 2015 | |||||
.Dt ZFS 5 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm zfs , | |||||
.Nm zpool | |||||
.Nd zfs external configuration information | |||||
.Sh DESCRIPTION | |||||
The | |||||
.Xr zfs 8 | |||||
filesystem is largely self-contained in that the vast majority of | |||||
.Xr zfs 8 | |||||
configuration is contained entirely within itself and is managed | |||||
wblockUnsubmitted Not Done Inline ActionsKind of a long sentence, and "contained" is redundant. Maybe rearrange to get the point earlier: Most wblock: Kind of a long sentence, and "contained" is redundant. Maybe rearrange to get the point… | |||||
automatically. As detailed below, there are a small number of necessary | |||||
bruefferUnsubmitted Not Done Inline ActionsNew sentence -> new line, also applies to a few places further down. brueffer: New sentence -> new line, also applies to a few places further down. | |||||
wblockUnsubmitted Not Done Inline Actions"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. wblock: "As detailed below" introduces an unnecessary pause and is not needed. This whole thing… | |||||
attributes required to bootstrap | |||||
.Xr zfs 8 , | |||||
but the majority of residual state from administrative actions and | |||||
wblockUnsubmitted Not Done Inline ActionsThe last half of this sentence about internal config was already stated above. wblock: The last half of this sentence about internal config was already stated above. | |||||
configuration is handled internally. | |||||
.Pp | |||||
Bootstrapping | |||||
.Xr zfs 8 | |||||
is limited to a small number of external configuration files and settings, | |||||
wblockUnsubmitted Not Done Inline ActionsThis 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: wblock: This sentence has already been stated twice. The term "bootstrapping" is vague, too. Does it… | |||||
specifically: | |||||
wblockUnsubmitted Not Done Inline ActionsNot needed. wblock: Not needed. | |||||
.Bl -tag -width indent-two | |||||
.It Va zfs_load | |||||
.Pq Vt bool | |||||
set to | |||||
.Dq Li YES | |||||
wblockUnsubmitted Not Done Inline ActionsThis 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? wblock: This assumes we want to enable ZFS, which is not unreasonable. But it would be better to… | |||||
in | |||||
.Xr loader.conf 5 | |||||
.It Va zfs_enable | |||||
.Pq Vt bool | |||||
set to | |||||
.Dq Li YES | |||||
in | |||||
.Xr rc.conf 5 | |||||
.El | |||||
.Pp | |||||
If a system is booting from a | |||||
wblockUnsubmitted Not Done Inline ActionsTry 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) wblock: Try to avoid if/then sentences, which have a pause... like that one there. That can often be… | |||||
.Xr zfs 8 | |||||
filesystem and the boot partition has had | |||||
.Xr gptzfsboot 8 | |||||
installed, the following configuration parameters are also required: | |||||
wblockUnsubmitted Not Done Inline Actionss/the following/these/ ("the following" almost always means "I am going to say some other stuff, and it will be after that") wblock: s/the following/these/ ("the following" almost always means "I am going to say some other… | |||||
.Bl -tag -width indent-two | |||||
.It Va vfs.root.mountfrom | |||||
allanjudeUnsubmitted Not Done Inline Actionsvsf.root.mountfrom is not required. The system defaults to booting from whichever dataset the zpool property 'bootfs' is set to allanjude: vsf.root.mountfrom is not required. The system defaults to booting from whichever dataset the… | |||||
.Pq Vt str | |||||
set in | |||||
.Xr loader.conf 5 . | |||||
The value for | |||||
.Va vfs.root.mountfrom | |||||
is a | |||||
.Vt rootdev , | |||||
which is structured like: | |||||
.Li Ao Ar vfstype Ac Ns : Ns Ao Ar zpool Ac Ns / Ns Ao Ar filesystem Ac | |||||
where | |||||
.Va Ao Ar vfstype Ac | |||||
is set to | |||||
.Va Ao Ar zfs Ac , | |||||
the | |||||
.Va Ao Ar zpool Ac | |||||
is the name of the root | |||||
.Xr zpool 8 | |||||
(customarily either | |||||
.Li Do zroot Dc Ns , | |||||
.Li Do tank Dc Ns , | |||||
or | |||||
.Li Do rpool Dc Ns ), | |||||
and | |||||
.Cm Ao Ar filesystem Ac | |||||
is a | |||||
.Xr zfs 8 | |||||
filesystem present on the above mentioned root | |||||
.Xr zpool 8 ; | |||||
for example | |||||
.Do zfs:zroot/ROOT/default Dc Ns . | |||||
.It Va bootfs | |||||
.Pq Vt str | |||||
is a | |||||
.Xr zpool 8 | |||||
attribute set on the root | |||||
.Xr zpool 8 | |||||
which points to the | |||||
.Va Ao Ar filesystem Ac | |||||
component of the | |||||
.Va vfs.root.mountfrom | |||||
attribute found in | |||||
.Xr loader.conf 8 Ns ; | |||||
for example: | |||||
.Va zroot/ROOT/default . | |||||
.El | |||||
.Pp | |||||
The remaining administrative items with regards to | |||||
.Xr zfs 8 | |||||
are contained within either the | |||||
.Xr zfs 8 | |||||
or | |||||
.Xr zpool 8 | |||||
man pages. | |||||
.Sh HISTORY | |||||
.Pp | |||||
The configuration differences in | |||||
allanjudeUnsubmitted Not Done Inline ActionsI 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' allanjude: I think more of the configuration differences come from that fact that ZFS is the RAID… | |||||
.Xr zfs 8 | |||||
originate from the fact that it is a copy-on-write, log-structured | |||||
filesystem. This is a fundamentally different approach compared to | |||||
traditional block-oriented file systems (e.g. UFS). The log-structured | |||||
filesystem approach enabled administrators with new filesystem management | |||||
possibilities that necessitated | |||||
.Xr zfs 8 | |||||
also revisit common administrative requirements, and thereby invalidating | |||||
many historical practices. It is reasonable to expect that administrators | |||||
used to block-oriented filesystems will not be accustomed to the way | |||||
.Xr zfs 8 | |||||
automagically handles many formerly manual and burdensome administrative | |||||
tasks. | |||||
.Pp | |||||
For example, | |||||
.Xr fstab 5 . | |||||
In the case of | |||||
.Xr zfs 8 , | |||||
because filesystems are decoupled from physical allocations on disk, it is | |||||
common practice to have hundreds or thousands of | |||||
.Xr zfs 8 | |||||
filesystems located within one or more | |||||
.Xr zpool 8 Ns 's. | |||||
With it being common to have thousands of filesystems spread across several | |||||
.Xr zpool 8 Ns 's, | |||||
it would have been unreasonable for | |||||
.Xr zfs 8 | |||||
to continue using | |||||
.Xr fstab 5 | |||||
as its way of managing filesystem mountpoints and filesystem options (see | |||||
allanjudeUnsubmitted Not Done Inline ActionsYou 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 allanjude: You can still use fstab for some or all of your file systems. Set the zfs mountpoint property… | |||||
.Xr zfs 8 | |||||
for a list of filesystem options). As such, | |||||
.Xr zfs 8 | |||||
grew its own native support to automatically manages mounting filesystems and | |||||
persisting filesystem options. In the case of multiple filesystems spread | |||||
across multiple | |||||
.Xr zpool 8 's, | |||||
.Xr zfs 8 | |||||
correctly handles mounting interleaved filesystems into the same filesystem | |||||
namespace (e.g. | |||||
.Pa zroot/ROOT/default | |||||
mounted on | |||||
.Pa / , | |||||
.Pa tank/var | |||||
mounted on | |||||
.Pa /var , | |||||
and | |||||
.Pa zroot/var/run | |||||
mounted on | |||||
.Pa /var/run Ns No ). | |||||
Such combinations are handled automatically and presents a very different | |||||
experience than many administrators are accustomed to. With | |||||
.Xr zfs 8 , | |||||
managing | |||||
.Xr fstab 5 | |||||
is now an irrelevant administrative activity. | |||||
.Sh CAVEATS | |||||
Unlike UFS where ~8% of space past 100% is reserved for administrators to | |||||
cope with disk out of space situations, | |||||
.Xr zfs 8 | |||||
does not provide any automatic padding. As such, it is incumbent of | |||||
administrators to set a | |||||
.Nm | |||||
.Cm quota | |||||
allanjudeUnsubmitted Not Done Inline Actionsin 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). allanjude: in the ZFS book, we set a reservation of 10% of the space, rather than a quota on 90% of the… | |||||
that reserves at least 10% of the space on each | |||||
.Xr zpool 8 | |||||
for low-disk situations, ideally approximately 20% for performance | |||||
reasons. Running a | |||||
.Xr zpool 8 | |||||
out of space can be fatal though heroic measures can sometimes be taken with | |||||
allanjudeUnsubmitted Not Done Inline ActionsIf 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. allanjude: If you are not going to describe the heroic measures, it might be best not to mention them.
An… | |||||
.Xr zdb 8 . | |||||
.Pp | |||||
There is no | |||||
.Xr fsck 8 | |||||
for | |||||
.Xr zfs 8 | |||||
because of the way | |||||
.Xr zfs 8 | |||||
checkpoints and writes out its transaction groups. This is a feature, not a | |||||
bug. In the event of a power outage, the filesystem is rolled back to its | |||||
last committed transaction (default is controlled by the | |||||
.Va vfs.zfs.txg.timeout | |||||
.Xr sysctl 8 Ns ). | |||||
.Pp | |||||
.Nm | |||||
.Cm snapshot | |||||
is effectively a | |||||
allanjudeUnsubmitted Not Done Inline ActionsDescribe more of what a snapshot is, to much the fact that it is 'free' into context. allanjude: Describe more of what a snapshot is, to much the fact that it is 'free' into context. | |||||
.Do free Dc | |||||
operation, this is life changing. Reverting to environments where snapshots | |||||
are taken on block-oriented filesystems will result in considerable sadness. | |||||
.Pp | |||||
.Xr df 1 | |||||
is largely made obsolete by | |||||
.Nm | |||||
.Cm list . | |||||
.Sh BUGS | |||||
.Xr zfs 8 | |||||
is magic and the first, best defense against bitrot, but the detection and | |||||
repair against bitrot is not enabled by default. It is necessary to either | |||||
manually run | |||||
.Nm | |||||
.Cm scrub | |||||
or set | |||||
.Va daily_scrub_zfs_enable | |||||
and | |||||
.Va daily_scrub_zfs_default_threshold | |||||
in | |||||
.Xr periodic.conf 5 . | |||||
.Pp | |||||
This man page does not exhaustive in the list of differences that result from | |||||
.Xr zfs 8 . | |||||
.Pp | |||||
A reasonable amount of advice should be provided in | |||||
.Xr tuning 7 | |||||
but is missing. | |||||
.Sh SEE ALSO | |||||
.Xr zfs 8 , | |||||
bruefferUnsubmitted Not Done Inline ActionsThese should be sorted by section first, and by alphabet second. brueffer: These should be sorted by section first, and by alphabet second. | |||||
.Xr zpool 8 , | |||||
.Xr gptzfsboot , | |||||
.Xr rc.conf 5 , | |||||
.Xr periodic.conf 5 , | |||||
.Xr loader.conf 5 , | |||||
bruefferUnsubmitted Not Done Inline ActionsNo trailing , brueffer: No trailing , | |||||
.Sh AUTHORS | |||||
.An Sean Chittenden |
I think there's a word missing here, "EXCLUDES"?