Initial implementation of zed (ZFS Event Daemon)

zed monitors ZFS events.  When a zevent is posted, zed will run any
scripts that have been enabled for the corresponding zevent class.
Multiple scripts may be invoked for a given zevent.  The zevent
nvpairs are passed to the scripts as environment variables.

Events are processed synchronously by the single thread, and there is
no maximum timeout for script execution.  Consequently, a misbehaving
script can delay (or forever block) the processing of subsequent
zevents.  Plans are to address this in future commits.

Initial scripts have been developed to log events to syslog
and send email in response to checksum/data/io errors and
resilver.finish/scrub.finish events.  By default, email will only
be sent if the ZED_EMAIL variable is configured in zed.rc (which is
serving as a config file of sorts until a proper configuration file
is implemented).

Signed-off-by: Chris Dunlap <[email protected]>
Signed-off-by: Brian Behlendorf <[email protected]>
Issue #2

1 files changed, 265 insertions, 0 deletions

diff --git a/man/man8/zed.8.in b/man/man8/zed.8.in
new file mode 100644
index 000000000..b853d86e5
--- /dev/null
+++ b/man/man8/zed.8.in
@@ -0,0 +1,265 @@
+.\"
+.\" CDDL HEADER START
+.\"
+.\" The contents of this file are subject to the terms of the
+.\" Common Development and Distribution License (the "License").
+.\" You may not use this file except in compliance with the License.
+.\"
+.\" You can obtain a copy of the license from the top-level
+.\" OPENSOLARIS.LICENSE or <http://opensource.org/licenses/CDDL-1.0>.
+.\" See the License for the specific language governing permissions
+.\" and limitations under the License.
+.\"
+.\" When distributing Covered Code, include this CDDL HEADER in each file
+.\" and include the License file from the top-level OPENSOLARIS.LICENSE.
+.\" If applicable, add the following below this CDDL HEADER, with the
+.\" fields enclosed by brackets "[]" replaced with your own identifying
+.\" information: Portions Copyright [yyyy] [name of copyright owner]
+.\"
+.\" CDDL HEADER END
+.\"
+.\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049).
+.\" Copyright (C) 2013-2014 Lawrence Livermore National Security, LLC.
+.\"
+.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 \fIscriptdir\fR]
+[\fB\-f\fR]
+[\fB\-F\fR]
+[\fB\-h\fR]
+[\fB\-L\fR]
+[\fB\-M\fR]
+[\fB\-p\fR \fIpidfile\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 ZFS event (zevent) is posted, \fBzed\fR will run any scripts
+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\  scriptdir
+Read the enabled scripts from the specified directory.
+.TP
+.BI \-p\  pidfile
+Write the daemon's process ID to the specified file.
+.TP
+.BI \-s\  statefile
+Write the daemon's state to the specified file.
+
+.SH ZEVENTS
+.PP
+A zevent is comprised of a list of name/value pairs (nvpairs).  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
+The scripts to be invoked in response to zevents are located in the
+enabled-scripts directory.  These can be symlinked or copied from the
+installed-scripts directory; symlinks allow for automatic updates from the
+installed scripts, whereas copies preserve local modifications.  As a security
+measure, scripts 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
+Scripts are named after the zevent class for which they should be invoked.
+In particular, a script 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 scripts may be invoked for a given zevent.
+
+.SH SCRIPTS
+.PP
+Scripts 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 the scripts can be stored in the default
+rc file which is sourced by the scripts; these variables should be prefixed
+with "ZED_".
+.PP
+The zevent nvpairs are passed to the scripts 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_SCRIPT_DIR
+The daemon's current enabled-scripts directory.
+.TP
+.B
+ZFS_ALIAS
+The ZFS alias (name-ver-rel) 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
+Scripts 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
+zed.rc 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 scripts.
+.TP
+.I @sysconfdir@/zfs/zed.d/zed.rc
+The default rc file for common variables used by the scripts.
+.TP
+.I @libexecdir@/zfs/zed.d
+The default directory for installed scripts.
+.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 scripts.
+.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 script execution.  Consequently, a misbehaving
+script can delay the processing of subsequent zevents.
+.PP
+The ownership and permissions of the enabled-scripts 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
+script to be executed as root.  The requirement that scripts be owned by
+root mitigates this to some extent.
+.PP
+Scripts 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 COPYRIGHT
+.PP
+Developed at Lawrence Livermore National Laboratory (LLNL\-CODE\-403049).
+.br
+Copyright (C) 2013\-2014 Lawrence Livermore National Security, LLC.
+
+.SH LICENSE
+.PP
+\fBzed\fR (ZFS Event Daemon) is distributed under the terms of the
+Common Development and Distribution License (CDDL\-1.0).
+
+.SH SEE ALSO
+.BR zfs (8),
+.BR zpool (8)