267 lines
8.2 KiB
Groff
267 lines
8.2 KiB
Groff
.\"
|
|
.\" This file is part of the ZFS Event Daemon (ZED).
|
|
.\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049).
|
|
.\" Copyright (C) 2013-2014 Lawrence Livermore National Security, LLC.
|
|
.\" Refer to the ZoL git commit log for authoritative copyright attribution.
|
|
.\"
|
|
.\" The contents of this file are subject to the terms of the
|
|
.\" Common Development and Distribution License Version 1.0 (CDDL-1.0).
|
|
.\" You can obtain a copy of the license from the top-level file
|
|
.\" "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\-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
|
|
Display a summary of the command-line options.
|
|
.TP
|
|
.BI \-L
|
|
Display license information.
|
|
.TP
|
|
.BI \-V
|
|
Display version information.
|
|
.TP
|
|
.BI \-v
|
|
Be verbose.
|
|
.TP
|
|
.BI \-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
|
|
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
|
|
Zero the daemon's state, thereby allowing zevents still within the kernel
|
|
to be reprocessed.
|
|
.\" .TP
|
|
.\" .BI \-c\ configfile
|
|
.\" Read the configuration from the specified file.
|
|
.TP
|
|
.BI \-d\ zedletdir
|
|
Read the enabled ZEDLETs from the specified directory.
|
|
.TP
|
|
.BI \-p\ 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 in production!
|
|
.TP
|
|
.BI \-s\ statefile
|
|
Write the daemon's state to the specified file.
|
|
.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
|
|
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
|
|
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
|
|
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
|
|
from the installed ZEDLETs, whereas copies preserve local modifications.
|
|
As a security measure, 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
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
The Event IDentifier.
|
|
.TP
|
|
.B
|
|
ZEVENT_CLASS
|
|
The zevent class string.
|
|
.TP
|
|
.B
|
|
ZEVENT_SUBCLASS
|
|
The zevent subclass string.
|
|
.TP
|
|
.B
|
|
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
|
|
Additionally, the following ZED & ZFS variables are defined:
|
|
.TP
|
|
.B
|
|
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
|
|
.\" @sysconfdir@/zfs/zed.conf
|
|
.\" The default configuration file for the daemon.
|
|
.TP
|
|
.I @sysconfdir@/zfs/zed.d
|
|
The default directory for enabled ZEDLETs.
|
|
.TP
|
|
.I @sysconfdir@/zfs/zed.d/zed.rc
|
|
The default rc file for common variables used by ZEDLETs.
|
|
.TP
|
|
.I @zfsexecdir@/zed.d
|
|
The default directory for installed ZEDLETs.
|
|
.TP
|
|
.I @runstatedir@/zed.pid
|
|
The default file containing the daemon's process ID.
|
|
.TP
|
|
.I @runstatedir@/zed.state
|
|
The default file containing the daemon's state.
|
|
|
|
.SH SIGNALS
|
|
.TP
|
|
.B HUP
|
|
Reconfigure the daemon and rescan the directory for enabled ZEDLETs.
|
|
.TP
|
|
.B TERM
|
|
Terminate the daemon.
|
|
|
|
.SH NOTES
|
|
.PP
|
|
\fBZED\fR requires root privileges.
|
|
.\" Do not taunt zed.
|
|
|
|
.SH BUGS
|
|
.PP
|
|
Events are processed synchronously by a single thread. This can delay the
|
|
processing of simultaneous zevents.
|
|
.PP
|
|
There is no maximum timeout for ZEDLET execution. Consequently, a misbehaving
|
|
ZEDLET can delay the processing of subsequent zevents.
|
|
.PP
|
|
The ownership and permissions of the \fIenabled-zedlets\fR directory (along
|
|
with all parent directories) are not checked. If any of these directories
|
|
are improperly owned or permissioned, an unprivileged user could insert a
|
|
ZEDLET to be executed as root. The requirement that ZEDLETs be owned by
|
|
root mitigates this to some extent.
|
|
.PP
|
|
ZEDLETs are unable to return state/status information to the kernel.
|
|
.PP
|
|
Some zevent nvpair types are not handled. These are denoted by zevent
|
|
environment variables having a "_NOT_IMPLEMENTED_" value.
|
|
.PP
|
|
Internationalization support via gettext has not been added.
|
|
.PP
|
|
The configuration file is not yet implemented.
|
|
.PP
|
|
The diagnosis engine is not yet implemented.
|
|
|
|
.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)
|