| .\" |
| .\" 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 OpenZFS 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. |
| .\" |
| .\" 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. |
| .It Fl L |
| Display license information. |
| .It Fl V |
| Display version information. |
| .It Fl v |
| Be verbose. |
| .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. |
| .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. |
| .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. |
| .It Fl d Ar zedletdir |
| Read the enabled ZEDLETs from the specified directory. |
| .It Fl p Ar pidfile |
| Write the daemon's process ID to the specified file. |
| .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! |
| .It Fl s Ar statefile |
| Write the daemon's state to the specified file. |
| .It Fl j Ar jobs |
| Allow at most |
| .Ar jobs |
| ZEDLETs to run concurrently, |
| delaying execution of new ones until they finish. |
| 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 |
| The kernel maintains a list of recent zevents that can be viewed (along with |
| 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 |
| .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, |
| 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 |
| .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 |
| .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: |
| .Bl -enum -compact |
| .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: |
| .Bl -tag -compact -width "ZEVENT_TIME_STRING" |
| .It Sy ZEVENT_EID |
| The Event IDentifier. |
| .It Sy ZEVENT_CLASS |
| The zevent class string. |
| .It Sy ZEVENT_SUBCLASS |
| The zevent subclass string. |
| .It Sy ZEVENT_TIME |
| The time at which the zevent was posted as |
| .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: |
| .Bl -tag -compact -width "ZEVENT_TIME_STRING" |
| .It Sy ZED_PID |
| The daemon's process ID. |
| .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. |
| .It Pa @sysconfdir@/zfs/zed.d/zed.rc |
| The default rc file for common variables used by ZEDLETs. |
| .It Pa @zfsexecdir@/zed.d |
| The default directory for installed ZEDLETs. |
| .It Pa @runstatedir@/zed.pid |
| The default file containing the daemon's process ID. |
| .It Pa @runstatedir@/zed.state |
| The default file containing the daemon's state. |
| .El |
| . |
| .Sh SIGNALS |
| .Bl -tag -width "-c" |
| .It Sy SIGHUP |
| Reconfigure the daemon and rescan the directory for enabled ZEDLETs. |
| .It Sy SIGTERM , SIGINT |
| Terminate the daemon. |
| .El |
| . |
| .Sh SEE ALSO |
| .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 |
| Internationalization support via gettext has not been added. |