266 lines
7.8 KiB
Groff
266 lines
7.8 KiB
Groff
.\"
|
|
.\" 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)
|