granicus.if.org Git - zfs/blob - man/man8/zed.8.in

   1 .\"
   2 .\" CDDL HEADER START
   3 .\"
   4 .\" The contents of this file are subject to the terms of the
   5 .\" Common Development and Distribution License (the "License").
   6 .\" You may not use this file except in compliance with the License.
   7 .\"
   8 .\" You can obtain a copy of the license from the top-level
   9 .\" OPENSOLARIS.LICENSE or <http://opensource.org/licenses/CDDL-1.0>.
  10 .\" See the License for the specific language governing permissions
  11 .\" and limitations under the License.
  12 .\"
  13 .\" When distributing Covered Code, include this CDDL HEADER in each file
  14 .\" and include the License file from the top-level OPENSOLARIS.LICENSE.
  15 .\" If applicable, add the following below this CDDL HEADER, with the
  16 .\" fields enclosed by brackets "[]" replaced with your own identifying
  17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  18 .\"
  19 .\" CDDL HEADER END
  20 .\"
  21 .\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049).
  22 .\" Copyright (C) 2013-2014 Lawrence Livermore National Security, LLC.
  23 .\"
  24 .TH ZED 8 "Octember 1, 2013" "ZFS on Linux" "System Administration Commands"
  25
  26 .SH NAME
  27 zed \- ZFS Event Daemon
  28
  29 .SH SYNOPSIS
  30 .HP
  31 .B zed
  32 .\" [\fB\-c\fR \fIconfigfile\fR]
  33 [\fB\-d\fR \fIscriptdir\fR]
  34 [\fB\-f\fR]
  35 [\fB\-F\fR]
  36 [\fB\-h\fR]
  37 [\fB\-L\fR]
  38 [\fB\-M\fR]
  39 [\fB\-p\fR \fIpidfile\fR]
  40 [\fB\-s\fR \fIstatefile\fR]
  41 [\fB\-v\fR]
  42 [\fB\-V\fR]
  43 [\fB\-Z\fR]
  44
  45 .SH DESCRIPTION
  46 .PP
  47 \fBzed\fR (ZFS Event Daemon) monitors events generated by the ZFS kernel
  48 module.  When a ZFS event (zevent) is posted, \fBzed\fR will run any scripts
  49 that have been enabled for the corresponding zevent class.
  50
  51 .SH OPTIONS
  52 .TP
  53 .BI \-h
  54 Display a summary of the command-line options.
  55 .TP
  56 .BI \-L
  57 Display license information.
  58 .TP
  59 .BI \-V
  60 Display version information.
  61 .TP
  62 .BI \-v
  63 Be verbose.
  64 .TP
  65 .BI \-f
  66 Force the daemon to run if at all possible, disabling security checks and
  67 throwing caution to the wind.  Not recommended for use in production.
  68 .TP
  69 .BI \-F
  70 Run the daemon in the foreground.
  71 .TP
  72 .BI \-M
  73 Lock all current and future pages in the virtual memory address space.
  74 This may help the daemon remain responsive when the system is under heavy
  75 memory pressure.
  76 .TP
  77 .BI \-Z
  78 Zero the daemon's state, thereby allowing zevents still within the kernel
  79 to be reprocessed.
  80 .\" .TP
  81 .\" .BI \-c\  configfile
  82 .\" Read the configuration from the specified file.
  83 .TP
  84 .BI \-d\  scriptdir
  85 Read the enabled scripts from the specified directory.
  86 .TP
  87 .BI \-p\  pidfile
  88 Write the daemon's process ID to the specified file.
  89 .TP
  90 .BI \-s\  statefile
  91 Write the daemon's state to the specified file.
  92
  93 .SH ZEVENTS
  94 .PP
  95 A zevent is comprised of a list of name/value pairs (nvpairs).  Each zevent
  96 contains an EID (Event IDentifier) that uniquely identifies it throughout
  97 the lifetime of the loaded ZFS kernel module; this EID is a monotonically
  98 increasing integer that resets to 1 each time the kernel module is loaded.
  99 Each zevent also contains a class string that identifies the type of event.
 100 For brevity, a subclass string is defined that omits the leading components
 101 of the class string.  Additional nvpairs exist to provide event details.
 102 .PP
 103 The kernel maintains a list of recent zevents that can be viewed (along with
 104 their associated lists of nvpairs) using the "\fBzpool events \-v\fR" command.
 105
 106 .SH CONFIGURATION
 107 .PP
 108 The scripts to be invoked in response to zevents are located in the
 109 enabled-scripts directory.  These can be symlinked or copied from the
 110 installed-scripts directory; symlinks allow for automatic updates from the
 111 installed scripts, whereas copies preserve local modifications.  As a security
 112 measure, scripts must be owned by root.  They must have execute permissions
 113 for the user, but they must not have write permissions for group or other.
 114 Dotfiles are ignored.
 115 .PP
 116 Scripts are named after the zevent class for which they should be invoked.
 117 In particular, a script will be invoked for a given zevent if either its
 118 class or subclass string is a prefix of its filename (and is followed by
 119 a non-alphabetic character).  As a special case, the prefix "all" matches
 120 all zevents.  Multiple scripts may be invoked for a given zevent.
 121
 122 .SH SCRIPTS
 123 .PP
 124 Scripts should be written under the presumption they can be invoked
 125 concurrently, and they should use appropriate locking to access any shared
 126 resources.  Common variables used by the scripts can be stored in the default
 127 rc file which is sourced by the scripts; these variables should be prefixed
 128 with "ZED_".
 129 .PP
 130 The zevent nvpairs are passed to the scripts as environment variables.
 131 Each nvpair name is converted to an environment variable in the following
 132 manner: 1) it is prefixed with "ZEVENT_", 2) it is converted to uppercase,
 133 and 3) each non-alphanumeric character is converted to an underscore.
 134 Some additional environment variables have been defined to present certain
 135 nvpair values in a more convenient form.  An incomplete list of zevent
 136 environment variables is as follows:
 137 .TP
 138 .B
 139 ZEVENT_EID
 140 The Event IDentifier.
 141 .TP
 142 .B
 143 ZEVENT_CLASS
 144 The zevent class string.
 145 .TP
 146 .B
 147 ZEVENT_SUBCLASS
 148 The zevent subclass string.
 149 .TP
 150 .B
 151 ZEVENT_TIME
 152 The time at which the zevent was posted as
 153 "\fIseconds\fR\ \fInanoseconds\fR" since the Epoch.
 154 .TP
 155 .B
 156 ZEVENT_TIME_SECS
 157 The \fIseconds\fR component of ZEVENT_TIME.
 158 .TP
 159 .B
 160 ZEVENT_TIME_NSECS
 161 The \fInanoseconds\fR component of ZEVENT_TIME.
 162 .TP
 163 .B
 164 ZEVENT_TIME_STRING
 165 An almost-RFC3339-compliant string for ZEVENT_TIME.
 166 .PP
 167 Additionally, the following ZED & ZFS variables are defined:
 168 .TP
 169 .B
 170 ZED_PID
 171 The daemon's process ID.
 172 .TP
 173 .B
 174 ZED_SCRIPT_DIR
 175 The daemon's current enabled-scripts directory.
 176 .TP
 177 .B
 178 ZFS_ALIAS
 179 The ZFS alias (name-ver-rel) string used to build the daemon.
 180 .TP
 181 .B
 182 ZFS_VERSION
 183 The ZFS version used to build the daemon.
 184 .TP
 185 .B
 186 ZFS_RELEASE
 187 The ZFS release used to build the daemon.
 188 .PP
 189 Scripts may need to call other ZFS commands.  The installation paths of
 190 the following executables are defined: \fBZDB\fR, \fBZED\fR, \fBZFS\fR,
 191 \fBZINJECT\fR, and \fBZPOOL\fR.  These variables can be overridden in the
 192 zed.rc if needed.
 193
 194 .SH FILES
 195 .\" .TP
 196 .\" @sysconfdir@/zfs/zed.conf
 197 .\" The default configuration file for the daemon.
 198 .TP
 199 .I @sysconfdir@/zfs/zed.d
 200 The default directory for enabled scripts.
 201 .TP
 202 .I @sysconfdir@/zfs/zed.d/zed.rc
 203 The default rc file for common variables used by the scripts.
 204 .TP
 205 .I @libexecdir@/zfs/zed.d
 206 The default directory for installed scripts.
 207 .TP
 208 .I @runstatedir@/zed.pid
 209 The default file containing the daemon's process ID.
 210 .TP
 211 .I @runstatedir@/zed.state
 212 The default file containing the daemon's state.
 213
 214 .SH SIGNALS
 215 .TP
 216 .B HUP
 217 Reconfigure the daemon and rescan the directory for enabled scripts.
 218 .TP
 219 .B TERM
 220 Terminate the daemon.
 221
 222 .SH NOTES
 223 .PP
 224 \fBzed\fR requires root privileges.
 225 .\" Do not taunt zed.
 226
 227 .SH BUGS
 228 .PP
 229 Events are processed synchronously by a single thread.  This can delay the
 230 processing of simultaneous zevents.
 231 .PP
 232 There is no maximum timeout for script execution.  Consequently, a misbehaving
 233 script can delay the processing of subsequent zevents.
 234 .PP
 235 The ownership and permissions of the enabled-scripts directory (along
 236 with all parent directories) are not checked.  If any of these directories
 237 are improperly owned or permissioned, an unprivileged user could insert a
 238 script to be executed as root.  The requirement that scripts be owned by
 239 root mitigates this to some extent.
 240 .PP
 241 Scripts are unable to return state/status information to the kernel.
 242 .PP
 243 Some zevent nvpair types are not handled.  These are denoted by zevent
 244 environment variables having a "_NOT_IMPLEMENTED_" value.
 245 .PP
 246 Internationalization support via gettext has not been added.
 247 .PP
 248 The configuration file is not yet implemented.
 249 .PP
 250 The diagnosis engine is not yet implemented.
 251
 252 .SH COPYRIGHT
 253 .PP
 254 Developed at Lawrence Livermore National Laboratory (LLNL\-CODE\-403049).
 255 .br
 256 Copyright (C) 2013\-2014 Lawrence Livermore National Security, LLC.
 257
 258 .SH LICENSE
 259 .PP
 260 \fBzed\fR (ZFS Event Daemon) is distributed under the terms of the
 261 Common Development and Distribution License (CDDL\-1.0).
 262
 263 .SH SEE ALSO
 264 .BR zfs (8),
 265 .BR zpool (8)