man ZED (8): ZFS Event Daemon

SYNOPSIS

zed [-d zedletdir] [-f] [-F] [-h] [-L] [-M] [-p pidfile] [-s statefile] [-v] [-V] [-Z]

DESCRIPTION

ZED (ZFS Event Daemon) monitors events generated by the ZFS kernel

module. When a zevent (ZFS Event) is posted, ZED will run any ZEDLETs (ZFS Event Daemon Linkage for Executable Tasks) that have been enabled for the corresponding zevent class.

OPTIONS

-h: Display a summary of the command-line options.
-L: Display license information.
-V: Display version information.
-v: Be verbose.
-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.
-F: Run the daemon in the foreground.
-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.
-Z: Zero the daemon's state, thereby allowing zevents still within the kernel to be reprocessed.
-d zedletdir: Read the enabled ZEDLETs from the specified directory.
-p pidfile: Write the daemon's process ID to the specified file.
-s statefile: Write the daemon's state to the specified file.

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.

The kernel maintains a list of recent zevents that can be viewed (along with their associated lists of nvpairs) using the "zpool events -v" command.

CONFIGURATION

ZEDLETs to be invoked in response to zevents are located in the enabled-zedlets directory. These can be symlinked or copied from the installed-zedlets 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.

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.

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_".

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:

ZEVENT_EID: The Event IDentifier.
ZEVENT_CLASS: The zevent class string.
ZEVENT_SUBCLASS: The zevent subclass string.
ZEVENT_TIME: The time at which the zevent was posted as "seconds nanoseconds" since the Epoch.
ZEVENT_TIME_SECS: The seconds component of ZEVENT_TIME.
ZEVENT_TIME_NSECS: The nanoseconds component of ZEVENT_TIME.
ZEVENT_TIME_STRING: An almost-RFC3339-compliant string for ZEVENT_TIME.

Additionally, the following ZED & ZFS variables are defined:

ZED_PID: The daemon's process ID.
ZED_ZEDLET_DIR: The daemon's current enabled-zedlets directory.
ZFS_ALIAS: The ZFS alias (name-version-release) string used to build the daemon.
ZFS_VERSION: The ZFS version used to build the daemon.
ZFS_RELEASE: The ZFS release used to build the daemon.

ZEDLETs may need to call other ZFS commands. The installation paths of the following executables are defined: ZDB, ZED, ZFS, ZINJECT, and ZPOOL. These variables can be overridden in the rc file if needed.

FILES

/etc/zfs/zed.d: The default directory for enabled ZEDLETs.
/etc/zfs/zed.d/zed.rc: The default rc file for common variables used by ZEDLETs.
/usr/lib/x86_64-linux-gnu/zfs/zed.d: The default directory for installed ZEDLETs.
/var/run/zed.pid: The default file containing the daemon's process ID.
/var/run/zed.state: The default file containing the daemon's state.

SIGNALS

HUP: Reconfigure the daemon and rescan the directory for enabled ZEDLETs.
TERM: Terminate the daemon.

NOTES

ZED requires root privileges.

BUGS

Events are processed synchronously by a single thread. This can delay the processing of simultaneous zevents.

There is no maximum timeout for ZEDLET execution. Consequently, a misbehaving ZEDLET can delay the processing of subsequent zevents.

The ownership and permissions of the enabled-zedlets 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.

ZEDLETs are unable to return state/status information to the kernel.

Some zevent nvpair types are not handled. These are denoted by zevent environment variables having a "_NOT_IMPLEMENTED_" value.

Internationalization support via gettext has not been added.

The configuration file is not yet implemented.

The diagnosis engine is not yet implemented.

LICENSE

ZED (ZFS Event Daemon) is distributed under the terms of the Common Development and Distribution License Version 1.0 (CDDL-1.0).

Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049).