zed.8: modernise
Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> Closes #12125
This commit is contained in:
наб
Brian Behlendorf
parent
475ee3bc2b
commit
e1ae0c4b99
|
|
@ -10,240 +10,247 @@
|
|||
.\" "OPENSOLARIS.LICENSE" or at <http://opensource.org/licenses/CDDL-1.0>.
|
||||
.\" You may not use this file except in compliance with the license.
|
||||
.\"
|
||||
.TH ZED 8 "Aug 24, 2020" OpenZFS
|
||||
|
||||
.SH NAME
|
||||
ZED \- ZFS Event Daemon
|
||||
|
||||
.SH SYNOPSIS
|
||||
.HP
|
||||
.B zed
|
||||
.\" [\fB\-c\fR \fIconfigfile\fR]
|
||||
[\fB\-d\fR \fIzedletdir\fR]
|
||||
[\fB\-f\fR]
|
||||
[\fB\-F\fR]
|
||||
[\fB\-h\fR]
|
||||
[\fB\-I\fR]
|
||||
[\fB\-L\fR]
|
||||
[\fB\-M\fR]
|
||||
[\fB\-p\fR \fIpidfile\fR]
|
||||
[\fB\-P\fR \fIpath\fR]
|
||||
[\fB\-s\fR \fIstatefile\fR]
|
||||
[\fB\-j\fR \fIjobs\fR]
|
||||
[\fB\-v\fR]
|
||||
[\fB\-V\fR]
|
||||
[\fB\-Z\fR]
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBZED\fR (ZFS Event Daemon) monitors events generated by the ZFS kernel
|
||||
module. When a zevent (ZFS Event) is posted, \fBZED\fR will run any ZEDLETs
|
||||
(ZFS Event Daemon Linkage for Executable Tasks) that have been enabled for the
|
||||
corresponding zevent class.
|
||||
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.BI \-h
|
||||
.\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049)
|
||||
.\"
|
||||
.Dd May 26, 2021
|
||||
.Dt ZED 8
|
||||
.Os
|
||||
.
|
||||
.Sh NAME
|
||||
.Nm ZED
|
||||
.Nd ZFS Event Daemon
|
||||
.Sh SYNOPSIS
|
||||
.Nm
|
||||
.Op Fl fFhILMvVZ
|
||||
.Op Fl d Ar zedletdir
|
||||
.Op Fl p Ar pidfile
|
||||
.Op Fl P Ar path
|
||||
.Op Fl s Ar statefile
|
||||
.Op Fl j Ar jobs
|
||||
.
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Nm
|
||||
(ZFS Event Daemon) monitors events generated by the ZFS kernel
|
||||
module.
|
||||
When a zevent (ZFS Event) is posted, the
|
||||
.Nm
|
||||
will run any ZEDLETs (ZFS Event Daemon Linkage for Executable Tasks)
|
||||
that have been enabled for the corresponding zevent class.
|
||||
.
|
||||
.Sh OPTIONS
|
||||
.Bl -tag -width "-h"
|
||||
.It Fl h
|
||||
Display a summary of the command-line options.
|
||||
.TP
|
||||
.BI \-L
|
||||
.It Fl L
|
||||
Display license information.
|
||||
.TP
|
||||
.BI \-V
|
||||
.It Fl V
|
||||
Display version information.
|
||||
.TP
|
||||
.BI \-v
|
||||
.It Fl v
|
||||
Be verbose.
|
||||
.TP
|
||||
.BI \-f
|
||||
.It Fl f
|
||||
Force the daemon to run if at all possible, disabling security checks and
|
||||
throwing caution to the wind. Not recommended for use in production.
|
||||
.TP
|
||||
.BI \-F
|
||||
Run the daemon in the foreground.
|
||||
.TP
|
||||
.BI \-M
|
||||
throwing caution to the wind.
|
||||
Not recommended for use in production.
|
||||
.It Fl F
|
||||
Don't daemonise: remain attached to the controlling terminal,
|
||||
log to the standard I/O streams.
|
||||
.It Fl M
|
||||
Lock all current and future pages in the virtual memory address space.
|
||||
This may help the daemon remain responsive when the system is under heavy
|
||||
memory pressure.
|
||||
.TP
|
||||
.BI \-I
|
||||
Request that the daemon idle rather than exit when the kernel modules are
|
||||
not loaded. Processing of events will start, or resume, when the kernel
|
||||
modules are (re)loaded. Under Linux the kernel modules cannot be unloaded
|
||||
while the daemon is running.
|
||||
.TP
|
||||
.BI \-Z
|
||||
.It Fl I
|
||||
Request that the daemon idle rather than exit when the kernel modules are not loaded.
|
||||
Processing of events will start, or resume, when the kernel modules are (re)loaded.
|
||||
Under Linux the kernel modules cannot be unloaded while the daemon is running.
|
||||
.It Fl Z
|
||||
Zero the daemon's state, thereby allowing zevents still within the kernel
|
||||
to be reprocessed.
|
||||
.TP
|
||||
.BI \-d\ zedletdir
|
||||
.It Fl d Ar zedletdir
|
||||
Read the enabled ZEDLETs from the specified directory.
|
||||
.TP
|
||||
.BI \-p\ pidfile
|
||||
.It Fl p Ar pidfile
|
||||
Write the daemon's process ID to the specified file.
|
||||
.TP
|
||||
.BI \-P\ path
|
||||
Custom $PATH for zedlets to use. Normally zedlets run in a locked-down
|
||||
environment, with hardcoded paths to the ZFS commands ($ZFS, $ZPOOL, $ZED, ...),
|
||||
and a hardcoded $PATH. This is done for security reasons. However, the
|
||||
ZFS test suite uses a custom PATH for its ZFS commands, and passes it to zed
|
||||
with -P. In short, -P is only to be used by the ZFS test suite; never use
|
||||
.It Fl P Ar path
|
||||
Custom
|
||||
.Ev $PATH
|
||||
for zedlets to use.
|
||||
Normally zedlets run in a locked-down environment, with hardcoded paths to the ZFS commands
|
||||
.Pq Ev $ZFS , $ZPOOL , $ZED , ... ,
|
||||
and a hard-coded
|
||||
.Ev $PATH .
|
||||
This is done for security reasons.
|
||||
However, the ZFS test suite uses a custom PATH for its ZFS commands, and passes it to
|
||||
.Nm
|
||||
with
|
||||
.Fl P .
|
||||
In short,
|
||||
.Fl P
|
||||
is only to be used by the ZFS test suite; never use
|
||||
it in production!
|
||||
.TP
|
||||
.BI \-s\ statefile
|
||||
.It Fl s Ar statefile
|
||||
Write the daemon's state to the specified file.
|
||||
.TP
|
||||
.BI \-j\ jobs
|
||||
Allow at most \fIjobs\fR ZEDLETs to run concurrently,
|
||||
.It Fl j Ar jobs
|
||||
Allow at most
|
||||
.Ar jobs
|
||||
ZEDLETs to run concurrently,
|
||||
delaying execution of new ones until they finish.
|
||||
Defaults to 16.
|
||||
.SH ZEVENTS
|
||||
.PP
|
||||
A zevent is comprised of a list of nvpairs (name/value pairs). Each zevent
|
||||
contains an EID (Event IDentifier) that uniquely identifies it throughout
|
||||
Defaults to
|
||||
.Sy 16 .
|
||||
.El
|
||||
.Sh ZEVENTS
|
||||
A zevent is comprised of a list of nvpairs (name/value pairs).
|
||||
Each zevent contains an EID (Event IDentifier) that uniquely identifies it throughout
|
||||
the lifetime of the loaded ZFS kernel module; this EID is a monotonically
|
||||
increasing integer that resets to 1 each time the kernel module is loaded.
|
||||
Each zevent also contains a class string that identifies the type of event.
|
||||
For brevity, a subclass string is defined that omits the leading components
|
||||
of the class string. Additional nvpairs exist to provide event details.
|
||||
.PP
|
||||
of the class string.
|
||||
Additional nvpairs exist to provide event details.
|
||||
.Pp
|
||||
The kernel maintains a list of recent zevents that can be viewed (along with
|
||||
their associated lists of nvpairs) using the "\fBzpool events \-v\fR" command.
|
||||
|
||||
.SH CONFIGURATION
|
||||
.PP
|
||||
their associated lists of nvpairs) using the
|
||||
.Nm zpool Cm events Fl v
|
||||
command.
|
||||
.
|
||||
.Sh CONFIGURATION
|
||||
ZEDLETs to be invoked in response to zevents are located in the
|
||||
\fIenabled-zedlets\fR directory. These can be symlinked or copied from the
|
||||
\fIinstalled-zedlets\fR directory; symlinks allow for automatic updates
|
||||
.Em enabled-zedlets
|
||||
directory
|
||||
.Pq Ar zedletdir .
|
||||
These can be symlinked or copied from the
|
||||
.Em installed-zedlets
|
||||
directory; symlinks allow for automatic updates
|
||||
from the installed ZEDLETs, whereas copies preserve local modifications.
|
||||
As a security measure, since ownership change is a privileged operation,
|
||||
ZEDLETs must be owned by root. They must have execute permissions for the user,
|
||||
ZEDLETs must be owned by root.
|
||||
They must have execute permissions for the user,
|
||||
but they must not have write permissions for group or other.
|
||||
Dotfiles are ignored.
|
||||
.PP
|
||||
.Pp
|
||||
ZEDLETs are named after the zevent class for which they should be invoked.
|
||||
In particular, a ZEDLET will be invoked for a given zevent if either its
|
||||
class or subclass string is a prefix of its filename (and is followed by
|
||||
a non-alphabetic character). As a special case, the prefix "all" matches
|
||||
all zevents. Multiple ZEDLETs may be invoked for a given zevent.
|
||||
|
||||
.SH ZEDLETS
|
||||
.PP
|
||||
a non-alphabetic character).
|
||||
As a special case, the prefix
|
||||
.Sy all
|
||||
matches all zevents.
|
||||
Multiple ZEDLETs may be invoked for a given zevent.
|
||||
.
|
||||
.Sh ZEDLETS
|
||||
ZEDLETs are executables invoked by the ZED in response to a given zevent.
|
||||
They should be written under the presumption they can be invoked concurrently,
|
||||
and they should use appropriate locking to access any shared resources.
|
||||
Common variables used by ZEDLETs can be stored in the default rc file which
|
||||
is sourced by scripts; these variables should be prefixed with "ZED_".
|
||||
.PP
|
||||
is sourced by scripts; these variables should be prefixed with
|
||||
.Sy ZED_ .
|
||||
.Pp
|
||||
The zevent nvpairs are passed to ZEDLETs as environment variables.
|
||||
Each nvpair name is converted to an environment variable in the following
|
||||
manner: 1) it is prefixed with "ZEVENT_", 2) it is converted to uppercase,
|
||||
and 3) each non-alphanumeric character is converted to an underscore.
|
||||
manner:
|
||||
.Bl -enum
|
||||
.It
|
||||
it is prefixed with
|
||||
.Sy ZEVENT_ ,
|
||||
.It
|
||||
it is converted to uppercase, and
|
||||
.It
|
||||
each non-alphanumeric character is converted to an underscore.
|
||||
.El
|
||||
.Pp
|
||||
Some additional environment variables have been defined to present certain
|
||||
nvpair values in a more convenient form. An incomplete list of zevent
|
||||
environment variables is as follows:
|
||||
.TP
|
||||
.B
|
||||
ZEVENT_EID
|
||||
nvpair values in a more convenient form.
|
||||
An incomplete list of zevent environment variables is as follows:
|
||||
.Bl -tag -width "ZEVENT_TIME_STRING"
|
||||
.It Sy ZEVENT_EID
|
||||
The Event IDentifier.
|
||||
.TP
|
||||
.B
|
||||
ZEVENT_CLASS
|
||||
.It Sy ZEVENT_CLASS
|
||||
The zevent class string.
|
||||
.TP
|
||||
.B
|
||||
ZEVENT_SUBCLASS
|
||||
.It Sy ZEVENT_SUBCLASS
|
||||
The zevent subclass string.
|
||||
.TP
|
||||
.B
|
||||
ZEVENT_TIME
|
||||
.It Sy ZEVENT_TIME
|
||||
The time at which the zevent was posted as
|
||||
"\fIseconds\fR\ \fInanoseconds\fR" since the Epoch.
|
||||
.TP
|
||||
.B
|
||||
ZEVENT_TIME_SECS
|
||||
The \fIseconds\fR component of ZEVENT_TIME.
|
||||
.TP
|
||||
.B
|
||||
ZEVENT_TIME_NSECS
|
||||
The \fInanoseconds\fR component of ZEVENT_TIME.
|
||||
.TP
|
||||
.B
|
||||
ZEVENT_TIME_STRING
|
||||
An almost-RFC3339-compliant string for ZEVENT_TIME.
|
||||
.PP
|
||||
.Dq Em seconds nanoseconds
|
||||
since the Epoch.
|
||||
.It Sy ZEVENT_TIME_SECS
|
||||
The
|
||||
.Em seconds
|
||||
component of
|
||||
.Sy ZEVENT_TIME .
|
||||
.It Sy ZEVENT_TIME_NSECS
|
||||
The
|
||||
.Em nanoseconds
|
||||
component of
|
||||
.Sy ZEVENT_TIME .
|
||||
.It Sy ZEVENT_TIME_STRING
|
||||
An almost-RFC3339-compliant string for
|
||||
.Sy ZEVENT_TIME .
|
||||
.El
|
||||
.Pp
|
||||
Additionally, the following ZED & ZFS variables are defined:
|
||||
.TP
|
||||
.B
|
||||
ZED_PID
|
||||
.Bl -tag -width "ZEVENT_TIME_STRING"
|
||||
.It Sy ZED_PID
|
||||
The daemon's process ID.
|
||||
.TP
|
||||
.B
|
||||
ZED_ZEDLET_DIR
|
||||
The daemon's current \fIenabled-zedlets\fR directory.
|
||||
.TP
|
||||
.B
|
||||
ZFS_ALIAS
|
||||
The ZFS alias (\fIname-version-release\fR) string used to build the daemon.
|
||||
.TP
|
||||
.B
|
||||
ZFS_VERSION
|
||||
The ZFS version used to build the daemon.
|
||||
.TP
|
||||
.B
|
||||
ZFS_RELEASE
|
||||
The ZFS release used to build the daemon.
|
||||
.PP
|
||||
ZEDLETs may need to call other ZFS commands. The installation paths of
|
||||
the following executables are defined: \fBZDB\fR, \fBZED\fR, \fBZFS\fR,
|
||||
\fBZINJECT\fR, and \fBZPOOL\fR. These variables can be overridden in the
|
||||
rc file if needed.
|
||||
|
||||
.SH FILES
|
||||
.TP
|
||||
.I @sysconfdir@/zfs/zed.d
|
||||
.It Sy ZED_ZEDLET_DIR
|
||||
The daemon's current
|
||||
.Em enabled-zedlets
|
||||
directory.
|
||||
.It Sy ZFS_ALIAS
|
||||
The alias
|
||||
.Pq Dq Em name Ns - Ns Em version Ns - Ns Em release
|
||||
string of the ZFS distribution the daemon is part of.
|
||||
.It Sy ZFS_VERSION
|
||||
The ZFS version the daemon is part of.
|
||||
.It Sy ZFS_RELEASE
|
||||
The ZFS release the daemon is part of.
|
||||
.El
|
||||
.Pp
|
||||
ZEDLETs may need to call other ZFS commands.
|
||||
The installation paths of the following executables are defined as environment variables:
|
||||
.Sy ZDB ,
|
||||
.Sy ZED ,
|
||||
.Sy ZFS ,
|
||||
.Sy ZINJECT ,
|
||||
and
|
||||
.Sy ZPOOL .
|
||||
These variables may be overridden in the rc file.
|
||||
.
|
||||
.Sh FILES
|
||||
.Bl -tag -width "-c"
|
||||
.It Pa @sysconfdir@/zfs/zed.d
|
||||
The default directory for enabled ZEDLETs.
|
||||
.TP
|
||||
.I @sysconfdir@/zfs/zed.d/zed.rc
|
||||
.It Pa @sysconfdir@/zfs/zed.d/zed.rc
|
||||
The default rc file for common variables used by ZEDLETs.
|
||||
.TP
|
||||
.I @zfsexecdir@/zed.d
|
||||
.It Pa @zfsexecdir@/zed.d
|
||||
The default directory for installed ZEDLETs.
|
||||
.TP
|
||||
.I @runstatedir@/zed.pid
|
||||
.It Pa @runstatedir@/zed.pid
|
||||
The default file containing the daemon's process ID.
|
||||
.TP
|
||||
.I @runstatedir@/zed.state
|
||||
.It Pa @runstatedir@/zed.state
|
||||
The default file containing the daemon's state.
|
||||
|
||||
.SH SIGNALS
|
||||
.TP
|
||||
.B HUP
|
||||
.El
|
||||
.
|
||||
.Sh SIGNALS
|
||||
.Bl -tag -width "-c"
|
||||
.It Sy SIGHUP
|
||||
Reconfigure the daemon and rescan the directory for enabled ZEDLETs.
|
||||
.TP
|
||||
.B TERM
|
||||
.It Sy SIGTERM , SIGINT
|
||||
Terminate the daemon.
|
||||
|
||||
.SH NOTES
|
||||
.PP
|
||||
\fBZED\fR requires root privileges.
|
||||
.\" Do not taunt zed.
|
||||
|
||||
.SH BUGS
|
||||
.PP
|
||||
.El
|
||||
.
|
||||
.Sh SEE ALSO
|
||||
.Xr zfs-events 5 ,
|
||||
.Xr zfs 8 ,
|
||||
.Xr zpool 8 ,
|
||||
.Xr zpool-events 8
|
||||
.
|
||||
.Sh NOTES
|
||||
The
|
||||
.Nm
|
||||
requires root privileges.
|
||||
.Pp
|
||||
Do not taunt the
|
||||
.Nm .
|
||||
.
|
||||
.Sh BUGS
|
||||
ZEDLETs are unable to return state/status information to the kernel.
|
||||
.PP
|
||||
.Pp
|
||||
Internationalization support via gettext has not been added.
|
||||
|
||||
.SH LICENSE
|
||||
.PP
|
||||
\fBZED\fR (ZFS Event Daemon) is distributed under the terms of the
|
||||
Common Development and Distribution License Version 1.0 (CDDL\-1.0).
|
||||
.PP
|
||||
Developed at Lawrence Livermore National Laboratory (LLNL\-CODE\-403049).
|
||||
|
||||
.SH SEE ALSO
|
||||
.BR zfs (8),
|
||||
.BR zpool (8)
|
||||
.BR zpool-events (8)
|
||||
|
|
|
|||
Loading…
Reference in New Issue