c/mirror_zfs
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_zfs.git synced 2024-11-17 10:01:01 +03:00
Code Issues Packages Projects Releases Wiki Activity

zed.8: modernise

Browse Source 
Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Closes #12125
This commit is contained in:
наб 2021-05-26 18:29:29 +02:00 committed by Brian Behlendorf
parent 3bcbb6af16
commit 1f3cbcfcc5
1 changed files with 194 additions and 187 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

381
man/man8/zed.8.in
View File

@ -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)