diff options
Diffstat (limited to 'sys/contrib/openzfs/man/man8/zed.8.in')
| -rw-r--r-- | sys/contrib/openzfs/man/man8/zed.8.in | 268 |
1 files changed, 268 insertions, 0 deletions
diff --git a/sys/contrib/openzfs/man/man8/zed.8.in b/sys/contrib/openzfs/man/man8/zed.8.in new file mode 100644 index 000000000000..2ca3935724d7 --- /dev/null +++ b/sys/contrib/openzfs/man/man8/zed.8.in @@ -0,0 +1,268 @@ +.\" +.\" This file is part of the ZFS Event Daemon (ZED) +.\" for ZFS on Linux (ZoL) <https://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\-I\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 \-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. +.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) +.BR zpool-events (8) |