zed

ZED(8) System Manager's Manual ZED(8)

NAME

   ZED  ZFS Event Daemon

SYNOPSIS

   ZED [-fFhILMvVZ] [-d zedletdir] [-p pidfile] [-P path] [-s statefile] [-j jobs] [-b buflen]

DESCRIPTION

   The  ZED  (ZFS  Event Daemon) monitors events generated by the ZFS kernel module.  When a zevent (ZFS Event) is posted, the ZED will run any ZEDLETs (ZFS Event Daemon Linkage for Exe
   cutable 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  Don't daemonize: remain attached to the controlling terminal, log to the standard I/O streams.

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

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

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

   -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 hard-coded $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!

   -s statefile
       Write the daemon's state to the specified file.

   -j jobs
       Allow at most jobs ZEDLETs to run concurrently, delaying execution of new ones until they finish.  Defaults to 16.

   -b buflen
       Cap  kernel  event buffer growth to buflen entries.  This buffer is grown when the daemon misses an event, but results in unreclaimable memory use in the kernel.  A value of 0 re
       moves the cap.  Defaults to 1048576.

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 (zedletdir).  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, since ownership change is a privileged operation,  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 pre
   fix 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 appropri
   ate 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 alias (name-version-release) string of the ZFS distribution the daemon is part of.
   ZFS_VERSION         The ZFS version the daemon is part of.
   ZFS_RELEASE         The ZFS release the daemon is part of.

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

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/zfs-linux/zed.d
       The default directory for installed ZEDLETs.

   /run/zed.pid
       The default file containing the daemon's process ID.

   /run/zed.state
       The default file containing the daemon's state.

SIGNALS

   SIGHUP
       Reconfigure the daemon and rescan the directory for enabled ZEDLETs.

   SIGTERM, SIGINT
       Terminate the daemon.

SEE ALSO

   zfs(8), zpool(8), zpool-events(8)

NOTES

   The ZED requires root privileges.

   Do not taunt the ZED.

BUGS

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

   Internationalization support via gettext has not been added.

OpenZFS May 26, 2021 ZED(8)