c/mirror_zfs
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_zfs.git synced 2026-05-22 10:37:35 +03:00
Code Issues Packages Projects Releases Wiki Activity

Modernise/fix/rewrite unlinted manpages

Browse Source 
zpool-destroy.8: flatten, fix description
zfs-wait.8: flatten, fix description, use list for events
zpool-reguid.8: flatten, fix description
zpool-history.8: flatten, fix description
zpool-export.8: flatten, fix description, remove -f "unmount" reference
  AFAICT no such command exists even in Illumos (as of today, anyway),
  and we definitely don't call it
zpool-labelclear.8: flatten, fix description
zpool-features.5: modernise
spl-module-parameters.5: modernise
zfs-mount-generator.8: rewrite
zfs-module-parameters.5: modernise

Reviewed-by: Richard Laager <rlaager@wiktel.com>
Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Closes #12169
This commit is contained in:
наб
2021-06-07 21:41:54 +02:00
committed by GitHub
parent afb96fa6ee
commit 2d815d955e
11 changed files with 3144 additions and 5530 deletions
Download Patch File Download Diff File Expand all files Collapse all files
man/man8/zfs-mount-generator.8.in
+165 -225
View File
@@ -21,232 +21,172 @@
.\" LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
.\" OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
.\" WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
.TH ZFS-MOUNT-GENERATOR 8 "Apr 19, 2021" OpenZFS
.SH "NAME"
zfs\-mount\-generator \- generates systemd mount units for ZFS
.SH SYNOPSIS
.B @systemdgeneratordir@/zfs\-mount\-generator
.sp
.SH DESCRIPTION
zfs\-mount\-generator implements the \fBGenerators Specification\fP
of
.BR systemd (1),
and is called during early boot to generate
.BR systemd.mount (5)
units for automatically mounted datasets. Mount ordering and dependencies
are created for all tracked pools (see below).
.SS ENCRYPTION KEYS
If the dataset is an encryption root, a service that loads the associated key (either from file or through a
.BR systemd\-ask\-password (1)
prompt) will be created. This service
. BR RequiresMountsFor
the path of the key (if file-based) and also copies the mount unit's
.BR After ,
.BR Before
.\"
.Dd May 31, 2021
.Dt ZFS-MOUNT-GENERATOR 8
.Os
.
.Sh NAME
.Nm zfs-mount-generator
.Nd generate systemd mount units for ZFS filesystems
.Sh SYNOPSIS
.Pa @systemdgeneratordir@/zfs-mount-generator
.
.Sh DESCRIPTION
.Nm
is a
.Xr systemd.generator 7
that generates native
.Xr systemd.mount 5
units for configured ZFS datasets.
.
.Ss Properties
.Bl -tag -compact -width "org.openzfs.systemd:required-by=unit[ unit]…"
.It Sy mountpoint Ns =
.No Skipped if Sy legacy No or Sy none .
.
.It Sy canmount Ns =
.No Skipped if Sy off .
.No Skipped if only Sy noauto
datasets exist for a given mountpoint and there's more than one.
.No Datasets with Sy yes No take precedence over ones with Sy noauto No for the same mountpoint.
.No Sets logical Em noauto No flag if Sy noauto .
Encryption roots always generate
.Sy zfs-load-key@ Ns Ar root Ns Sy .service ,
even if
.Sy off .
.
.It Sy atime Ns = , Sy relatime Ns = , Sy devices Ns = , Sy exec Ns = , Sy readonly Ns = , Sy setuid Ns = , Sy nbmand Ns =
Used to generate mount options equivalent to
.Nm zfs Cm mount .
.
.It Sy encroot Ns = , Sy keylocation Ns =
If the dataset is an encryption root, its mount unit will bind to
.Sy zfs-load-key@ Ns Ar root Ns Sy .service ,
with additional dependencies as follows:
.Bl -tag -compact -offset Ds -width "keylocation=https://URL (et al.)"
.It Sy keylocation Ns = Ns Sy prompt
None, uses
.Xr systemd-ask-password 1
.It Sy keylocation Ns = Ns Sy https:// Ns Ar URL Pq et al.\&
.Sy Wants Ns = , Sy After Ns = : Pa network-online.target
.It Sy keylocation Ns = Ns Sy file:// Ns < Ns Ar path Ns >
.Sy RequiresMountsFor Ns = Ns Ar path
.El
.
The service also uses the same
.Sy Wants Ns = ,
.Sy After Ns = ,
.Sy Requires Ns = , No and
.Sy RequiresMountsFor Ns = ,
as the mount unit.
.
.It Sy org.openzfs.systemd:requires Ns = Ns Pa path Ns Oo " " Ns Pa path Oc Ns …
.No Sets Sy Requires Ns = for the mount- and key-loading unit.
.
.It Sy org.openzfs.systemd:requires-mounts-for Ns = Ns Pa path Ns Oo " " Ns Pa path Oc Ns …
.No Sets Sy RequiresMountsFor Ns = for the mount- and key-loading unit.
.
.It Sy org.openzfs.systemd:before Ns = Ns Pa unit Ns Oo " " Ns Pa unit Oc Ns …
.No Sets Sy Before Ns = for the mount unit.
.
.It Sy org.openzfs.systemd:after Ns = Ns Pa unit Ns Oo " " Ns Pa unit Oc Ns …
.No Sets Sy After Ns = for the mount unit.
.
.It Sy org.openzfs.systemd:wanted-by Ns = Ns Pa unit Ns Oo " " Ns Pa unit Oc Ns …
.No Sets logical Em noauto No flag (see below).
.No If not Sy none , No sets Sy WantedBy Ns = for the mount unit.
.It Sy org.openzfs.systemd:required-by Ns = Ns Pa unit Ns Oo " " Ns Pa unit Oc Ns …
.No Sets logical Em noauto No flag (see below).
.No If not Sy none , No sets Sy RequiredBy Ns = for the mount unit.
.
.It Sy org.openzfs.systemd:nofail Ns = Ns (unset) Ns | Ns Sy on Ns | Ns Sy off
Waxes or wanes strength of default reverse dependencies of the mount unit, see below.
.
.It Sy org.openzfs.systemd:ignore Ns = Ns Sy on Ns | Ns Sy off
.No Skip if Sy on .
.No Defaults to Sy off .
.El
.
.Ss Unit Ordering And Dependencies
Additionally, unless the pool the dataset resides on
is imported at generation time, both units gain
.Sy Wants Ns = Ns Pa zfs-import.target
and
.BR Requires .
All mount units of encrypted datasets add the key\-load service for their encryption root to their
.BR Wants
and
.BR After .
The service will not be
.BR Want ed
or
.BR Require d
by
.BR local-fs.target
directly, and so will only be started manually or as a dependency of a started mount unit.
.SS UNIT ORDERING AND DEPENDENCIES
mount unit's
.BR Before
\->
key\-load service (if any)
\->
mount unit
\->
mount unit's
.BR After
It is worth nothing that when a mount unit is activated, it activates all available mount units for parent paths to its mountpoint, i.e. activating the mount unit for /tmp/foo/1/2/3 automatically activates all available mount units for /tmp, /tmp/foo, /tmp/foo/1, and /tmp/foo/1/2. This is true for any combination of mount units from any sources, not just ZFS.
.SS CACHE FILE
.Sy After Ns = Ns Pa zfs-import.target .
.Pp
Additionally, unless the logical
.Em noauto
flag is set, the mount unit gains a reverse-dependency for
.Pa local-fs.target
of strength
.Bl -tag -compact -offset Ds -width "(unset)"
.It (unset)
.Sy WantedBy Ns = No + Sy Before Ns =
.It Sy on
.Sy WantedBy Ns =
.It Sy off
.Sy RequiredBy Ns = No + Sy Before Ns =
.El
.
.Ss Cache File
Because ZFS pools may not be available very early in the boot process,
information on ZFS mountpoints must be stored separately. The output of the command
.PP
.RS 4
zfs list -H -o name,mountpoint,canmount,atime,relatime,devices,exec,readonly,setuid,nbmand,encroot,keylocation,org.openzfs.systemd:requires,org.openzfs.systemd:requires-mounts-for,org.openzfs.systemd:before,org.openzfs.systemd:after,org.openzfs.systemd:wanted-by,org.openzfs.systemd:required-by,org.openzfs.systemd:nofail,org.openzfs.systemd:ignore
.RE
.PP
for datasets that should be mounted by systemd, should be kept
separate from the pool at
.RI @sysconfdir@/zfs/zfs-list.cache/ POOLNAME .
.PP
The cache file, if writeable, will be kept synchronized with the pool
state by the
.I history_event-zfs-list-cacher.sh
ZEDLET.
.PP
.sp
.SS PROPERTIES
The behavior of the generator script can be influenced by the following dataset properties:
.sp
.TP 4
.BR canmount = on | off | noauto
If a dataset has
.BR mountpoint
set and
.BR canmount
is not
.BR off ,
a mount unit will be generated.
Additionally, if
.BR canmount
is
.BR on ,
.BR local-fs.target
will gain a dependency on the mount unit.
This behavior is equal to the
.BR auto
and
.BR noauto
legacy mount options, see
.BR systemd.mount (5).
Encryption roots always generate a key-load service, even for
.BR canmount=off .
.TP 4
.BR org.openzfs.systemd:requires\-mounts\-for = \fIpath\fR...
Space\-separated list of mountpoints to require to be mounted for this mount unit
.TP 4
.BR org.openzfs.systemd:before = \fIunit\fR...
The mount unit and associated key\-load service will be ordered before this space\-separated list of units.
.TP 4
.BR org.openzfs.systemd:after = \fIunit\fR...
The mount unit and associated key\-load service will be ordered after this space\-separated list of units.
.TP 4
.BR org.openzfs.systemd:wanted\-by = \fIunit\fR...
Space-separated list of units that will gain a
.BR Wants
dependency on this mount unit.
Setting this property implies
.BR noauto .
.TP 4
.BR org.openzfs.systemd:required\-by = \fIunit\fR...
Space-separated list of units that will gain a
.BR Requires
dependency on this mount unit.
Setting this property implies
.BR noauto .
.TP 4
.BR org.openzfs.systemd:nofail = unset | on | off
Toggles between a
.BR Wants
and
.BR Requires
type of dependency between the mount unit and
.BR local-fs.target ,
if
.BR noauto
isn't set or implied.
.BR on :
Mount will be
.BR WantedBy
local-fs.target
.BR off :
Mount will be
.BR Before
and
.BR RequiredBy
local-fs.target
.BR unset :
Mount will be
.BR Before
and
.BR WantedBy
local-fs.target
.TP 4
.BR org.openzfs.systemd:ignore = on | off
If set to
.BR on ,
do not generate a mount unit for this dataset.
See also
.BR systemd.mount (5)
.PP
.SH ENVIRONMENT
information on ZFS mountpoints must be stored separately.
The output of
.Dl Nm zfs Cm list Fl Ho Ar name , Ns Aq every property above in order
for datasets that should be mounted by systemd should be kept at
.Pa @sysconfdir@/zfs/zfs-list.cache/ Ns Ar poolname ,
and, if writeable, will be kept synchronized for the entire pool by the
.Pa history_event-zfs-list-cacher.sh
ZEDLET, if enabled
.Pq see Xr zed 8 .
.
.Sh ENVIRONMENT
The
.BR $ZFS_DEBUG
environment variable, which can either be 0 (default),
1 (print summary accounting information at the end),
or at least 2 (print accounting information for each subprocess as it finishes).
If not present, /proc/cmdline is additionally checked for
.BR debug ,
in which case the debug level is set to 2.
.SH EXAMPLE
.Sy ZFS_DEBUG
environment variable can either be
.Sy 0
(default),
.Sy 1
(print summary accounting information at the end), or at least
.Sy 2
(print accounting information for each subprocess as it finishes).
.
If not present,
.Pa /proc/cmdline
is additionally checked for
.Qq debug ,
in which case the debug level is set to
.Sy 2 .
.
.Sh EXAMPLES
To begin, enable tracking for the pool:
.PP
.RS 4
touch
.RI @sysconfdir@/zfs/zfs-list.cache/ POOLNAME
.RE
.PP
Then, enable the tracking ZEDLET:
.PP
.RS 4
ln -s "@zfsexecdir@/zed.d/history_event-zfs-list-cacher.sh" "@sysconfdir@/zfs/zed.d"
systemctl enable zfs-zed.service
systemctl restart zfs-zed.service
.RE
.PP
Force the running of the ZEDLET by setting a monitored property, e.g.
.BR canmount ,
for at least one dataset in the pool:
.PP
.RS 4
zfs set canmount=on
.I DATASET
.RE
.PP
This forces an update to the stale cache file.
To test the generator output, run
.PP
.RS 4
@systemdgeneratordir@/zfs-mount-generator /tmp/zfs-mount-generator
.RE
.PP
This will generate units and dependencies in
.I /tmp/zfs-mount-generator
for you to inspect them. The second and third argument are ignored.
If you're satisfied with the generated units, instruct systemd to re-run all generators:
.PP
.RS 4
systemctl daemon-reload
.RE
.PP
.sp
.SH SEE ALSO
.BR zfs (5)
.BR zfs-events (5)
.BR zed (8)
.BR zpool (5)
.BR systemd (1)
.BR systemd.target (5)
.BR systemd.special (7)
.BR systemd.mount (7)
.Dl # Nm touch Pa @sysconfdir@/zfs/zfs-list.cache/ Ns Ar poolname
Then enable the tracking ZEDLET:
.Dl # Nm ln Fl s Pa @zfsexecdir@/zed.d/history_event-zfs-list-cacher.sh @sysconfdir@/zfs/zed.d
.Dl # Nm systemctl Cm enable Pa zfs-zed.service
.Dl # Nm systemctl Cm restart Pa zfs-zed.service
.Pp
If no history event is in the queue,
inject one to ensure the ZEDLET runs to refresh the cache file
by setting a monitored property somewhere on the pool:
.Dl # Nm zfs Cm set Sy relatime Ns = Ns Sy off Ar poolname/dset
.Dl # Nm zfs Cm inherit Sy relatime Ar poolname/dset
.Pp
To test the generator output:
.Dl $ Nm mkdir Pa /tmp/zfs-mount-generator
.Dl $ Nm @systemdgeneratordir@/zfs-mount-generator Pa /tmp/zfs-mount-generator
.
If the generated units are satisfactory, instruct
.Nm systemd
to re-run all generators:
.Dl # Nm systemctl daemon-reload
.
.Sh SEE ALSO
.Xr systemd.mount 5 ,
.Xr systemd.target 5 ,
.Xr zfs 5 ,
.Xr zfs-events 5 ,
.Xr systemd.generator 7 ,
.Xr systemd.special 7 ,
.Xr zed 8
man/man8/zfs-wait.8
+11 -16
View File
@@ -18,7 +18,6 @@
.\"
.\" CDDL HEADER END
.\"
.\"
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
@@ -27,25 +26,20 @@
.\" Copyright 2017 Nexenta Systems, Inc.
.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
.\"
.Dd August 9, 2019
.Dd May 31, 2021
.Dt ZFS-WAIT 8
.Os
.
.Sh NAME
.Nm zfs-wait
.Nd Wait for background activity to stop in a ZFS filesystem
.Nd wait for activity in ZFS filesystem to stop
.Sh SYNOPSIS
.Nm zfs
.Cm wait
.Op Fl t Ar activity Ns Oo , Ns Ar activity Ns Oc Ns ...
.Ar fs
.Op Fl t Ar activity Ns Oo , Ns Ar activity Ns Oc Ns …
.Ar filesystem
.
.Sh DESCRIPTION
.Bl -tag -width Ds
.It Xo
.Nm zfs
.Cm wait
.Op Fl t Ar activity Ns Oo , Ns Ar activity Ns Oc Ns ...
.Ar fs
.Xc
Waits until all background activity of the given types has ceased in the given
filesystem.
The activity could cease because it has completed or because the filesystem has
@@ -58,13 +52,14 @@ immediately.
These are the possible values for
.Ar activity ,
along with what each one waits for:
.Bd -literal
deleteq The filesystem's internal delete queue to empty
.Ed
.Bl -tag -compact -offset Ds -width "deleteq"
.It Sy deleteq
The filesystem's internal delete queue to empty
.El
.Pp
Note that the internal delete queue does not finish draining until
all large files have had time to be fully destroyed and all open file
handles to unlinked files are closed.
.El
.
.Sh SEE ALSO
.Xr lsof 8
man/man8/zpool-destroy.8
+5 -12
View File
@@ -18,7 +18,6 @@
.\"
.\" CDDL HEADER END
.\"
.\"
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
@@ -27,29 +26,23 @@
.\" Copyright 2017 Nexenta Systems, Inc.
.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
.\"
.Dd August 9, 2019
.Dd May 31, 2021
.Dt ZPOOL-DESTROY 8
.Os
.
.Sh NAME
.Nm zpool-destroy
.Nd Destroys the given ZFS storage pool, freeing up any devices for other use
.Nd destroy ZFS storage pool
.Sh SYNOPSIS
.Nm zpool
.Cm destroy
.Op Fl f
.Ar pool
.
.Sh DESCRIPTION
.Bl -tag -width Ds
.It Xo
.Nm zpool
.Cm destroy
.Op Fl f
.Ar pool
.Xc
Destroys the given pool, freeing up any devices for other use.
This command tries to unmount any active datasets before destroying the pool.
.Bl -tag -width Ds
.It Fl f
Forces any active datasets contained within the pool to be unmounted.
.El
Forcefully unmount all active datasets.
.El
man/man8/zpool-export.8
+6 -17
View File
@@ -18,7 +18,6 @@
.\"
.\" CDDL HEADER END
.\"
.\"
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
@@ -30,24 +29,17 @@
.Dd February 16, 2020
.Dt ZPOOL-EXPORT 8
.Os
.
.Sh NAME
.Nm zpool-export
.Nd Exports the given ZFS storage pools from the system
.Nd export ZFS storage pools
.Sh SYNOPSIS
.Nm zpool
.Cm export
.Op Fl a
.Op Fl f
.Ar pool Ns ...
.Fl a Ns | Ns Ar pool Ns …
.
.Sh DESCRIPTION
.Bl -tag -width Ds
.It Xo
.Nm zpool
.Cm export
.Op Fl a
.Op Fl f
.Ar pool Ns ...
.Xc
Exports the given pools from the system.
All devices are marked as exported, but are still considered in use by other
subsystems.
@@ -69,15 +61,12 @@ the disks.
.It Fl a
Exports all pools imported on the system.
.It Fl f
Forcefully unmount all datasets, using the
.Nm unmount Fl f
command.
This option is not supported on Linux.
Forcefully unmount all datasets, and allow export of pools with active shared spares.
.Pp
This command will forcefully export the pool even if it has a shared spare that
is currently being used.
This may lead to potential data corruption.
.El
.El
.
.Sh SEE ALSO
.Xr zpool-import 8
man/man8/zpool-history.8
+5 -11
View File
@@ -18,7 +18,6 @@
.\"
.\" CDDL HEADER END
.\"
.\"
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
@@ -30,22 +29,17 @@
.Dd August 9, 2019
.Dt ZPOOL-HISTORY 8
.Os
.
.Sh NAME
.Nm zpool-history
.Nd Displays the command history of the specified ZFS storage pool(s)
.Nd inspect command history of ZFS storage pools
.Sh SYNOPSIS
.Nm zpool
.Cm history
.Op Fl il
.Oo Ar pool Oc Ns ...
.Oo Ar pool Oc Ns …
.
.Sh DESCRIPTION
.Bl -tag -width Ds
.It Xo
.Nm zpool
.Cm history
.Op Fl il
.Oo Ar pool Oc Ns ...
.Xc
Displays the command history of the specified pool(s) or all pools if no pool is
specified.
.Bl -tag -width Ds
@@ -56,7 +50,7 @@ Displays log records in long format, which in addition to standard format
includes, the user name, the hostname, and the zone in which the operation was
performed.
.El
.El
.
.Sh SEE ALSO
.Xr zpool-checkpoint 8 ,
.Xr zpool-events 8 ,
man/man8/zpool-labelclear.8
+5 -11
View File
@@ -18,7 +18,6 @@
.\"
.\" CDDL HEADER END
.\"
.\"
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
@@ -27,25 +26,20 @@
.\" Copyright 2017 Nexenta Systems, Inc.
.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
.\"
.Dd August 9, 2019
.Dd May 31, 2021
.Dt ZPOOL-LABELCLEAR 8
.Os
.
.Sh NAME
.Nm zpool-labelclear
.Nd Removes ZFS label information from the specified physical device
.Nd remove ZFS label information from device
.Sh SYNOPSIS
.Nm zpool
.Cm labelclear
.Op Fl f
.Ar device
.
.Sh DESCRIPTION
.Bl -tag -width Ds
.It Xo
.Nm zpool
.Cm labelclear
.Op Fl f
.Ar device
.Xc
Removes ZFS label information from the specified
.Ar device .
If the
@@ -58,7 +52,7 @@ must not be part of an active pool configuration.
.It Fl f
Treat exported or foreign devices as inactive.
.El
.El
.
.Sh SEE ALSO
.Xr zpool-destroy 8 ,
.Xr zpool-detach 8 ,
man/man8/zpool-reguid.8
+5 -10
View File
@@ -18,7 +18,6 @@
.\"
.\" CDDL HEADER END
.\"
.\"
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
@@ -27,27 +26,23 @@
.\" Copyright 2017 Nexenta Systems, Inc.
.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
.\"
.Dd August 9, 2019
.Dd May 31, 2021
.Dt ZPOOL-REGUID 8
.Os
.
.Sh NAME
.Nm zpool-reguid
.Nd Generate a new unique identifier for a ZFS storage pool
.Nd generate new unique identifier for ZFS storage pool
.Sh SYNOPSIS
.Nm zpool
.Cm reguid
.Ar pool
.
.Sh DESCRIPTION
.Bl -tag -width Ds
.It Xo
.Nm zpool
.Cm reguid
.Ar pool
.Xc
Generates a new unique identifier for the pool.
You must ensure that all devices in this pool are online and healthy before
performing this action.
.El
.
.Sh SEE ALSO
.Xr zpool-export 8 ,
.Xr zpool-import 8