diff options
Diffstat (limited to 'man/man8')
| -rw-r--r-- | man/man8/.gitignore | 1 | ||||
| -rw-r--r-- | man/man8/Makefile.am | 23 | ||||
| -rw-r--r-- | man/man8/zed.8.in | 265 |
3 files changed, 289 insertions, 0 deletions
diff --git a/man/man8/.gitignore b/man/man8/.gitignore new file mode 100644 index 000000000..be7e9040f --- /dev/null +++ b/man/man8/.gitignore @@ -0,0 +1 @@ +/zed.8 diff --git a/man/man8/Makefile.am b/man/man8/Makefile.am index f68082221..b89e34dfd 100644 --- a/man/man8/Makefile.am +++ b/man/man8/Makefile.am @@ -8,5 +8,28 @@ dist_man_MANS = \ zpool.8 \ zstreamdump.8 +nodist_man_MANS = \ + zed.8 + +EXTRA_DIST = \ + zed.8.in + +zed.8: $(srcdir)/zed.8.in + +do_subst = $(SED) \ + -e 's|@libexecdir[@]|$(libexecdir)|g' \ + -e 's|@runstatedir[@]|$(runstatedir)|g' \ + -e 's|@sysconfdir[@]|$(sysconfdir)|g' + +$(nodist_man_MANS): Makefile + $(RM) $@ [email protected] + srcdir=''; \ + test -f ./[email protected] || srcdir=$(srcdir)/; \ + $(do_subst) $${srcdir}[email protected] >[email protected] + mv [email protected] $@ + install-data-local: $(INSTALL) -d -m 0755 "$(DESTDIR)$(mandir)/man8" + +CLEANFILES = \ + $(nodist_man_MANS) 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) |