Index: cddl/contrib/opensolaris/cmd/zfs/zfs.5
===================================================================
--- /dev/null
+++ cddl/contrib/opensolaris/cmd/zfs/zfs.5
@@ -0,0 +1,251 @@
+.\" 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
+.\" 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
+automatically.  As detailed below, there are a small number of necessary
+attributes required to bootstrap
+.Xr zfs 8 ,
+but the majority of residual state from administrative actions and
+configuration is handled internally.
+.Pp
+Bootstrapping
+.Xr zfs 8
+is limited to a small number of external configuration files and settings,
+specifically:
+.Bl -tag -width indent-two
+.It Va zfs_load
+.Pq Vt bool
+set to
+.Dq Li YES
+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
+.Xr zfs 8
+filesystem and the boot partition has had
+.Xr gptzfsboot 8
+installed, the following configuration parameters are also required:
+.Bl -tag -width indent-two
+.It Va vfs.root.mountfrom
+.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
+.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
+.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
+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
+.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
+.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 ,
+.Xr zpool 8 ,
+.Xr gptzfsboot ,
+.Xr rc.conf 5 ,
+.Xr periodic.conf 5 ,
+.Xr loader.conf 5 ,
+.Sh AUTHORS
+.An Sean Chittenden