NAME

       ZED — ZFS Event Daemon

SYNOPSIS

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

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 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  Don't daemonise: 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.

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