sys/contrib/openzfs/man/man8/zed.8.in

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