man/man8/zed.8.in

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