| .\" |
| .\" This file is part of the ZFS Event Daemon (ZED) |
| .\" for ZFS on Linux (ZoL) <http://zfsonlinux.org/>. |
| .\" 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 "Octember 1, 2013" "ZFS on Linux" "System Administration Commands" |
| |
| .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\-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 \-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) |