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