man/man8/zed.8.in

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