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