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 OpenZFS 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 .\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049)
  14 .\"
  15 .Dd May 26, 2021
  16 .Dt ZED 8
  17 .Os
  18 .
  19 .Sh NAME
  20 .Nm ZED
  21 .Nd ZFS Event Daemon
  22 .Sh SYNOPSIS
  23 .Nm
  24 .Op Fl fFhILMvVZ
  25 .Op Fl d Ar zedletdir
  26 .Op Fl p Ar pidfile
  27 .Op Fl P Ar path
  28 .Op Fl s Ar statefile
  29 .Op Fl j Ar jobs
  30 .
  31 .Sh DESCRIPTION
  32 The
  33 .Nm
  34 (ZFS Event Daemon) monitors events generated by the ZFS kernel
  35 module.
  36 When a zevent (ZFS Event) is posted, the
  37 .Nm
  38 will run any ZEDLETs (ZFS Event Daemon Linkage for Executable Tasks)
  39 that have been enabled for the corresponding zevent class.
  40 .
  41 .Sh OPTIONS
  42 .Bl -tag -width "-h"
  43 .It Fl h
  44 Display a summary of the command-line options.
  45 .It Fl L
  46 Display license information.
  47 .It Fl V
  48 Display version information.
  49 .It Fl v
  50 Be verbose.
  51 .It Fl f
  52 Force the daemon to run if at all possible, disabling security checks and
  53 throwing caution to the wind.
  54 Not recommended for use in production.
  55 .It Fl F
  56 Don't daemonise: remain attached to the controlling terminal,
  57 log to the standard I/O streams.
  58 .It Fl M
  59 Lock all current and future pages in the virtual memory address space.
  60 This may help the daemon remain responsive when the system is under heavy
  61 memory pressure.
  62 .It Fl I
  63 Request that the daemon idle rather than exit when the kernel modules are not loaded.
  64 Processing of events will start, or resume, when the kernel modules are (re)loaded.
  65 Under Linux the kernel modules cannot be unloaded while the daemon is running.
  66 .It Fl Z
  67 Zero the daemon's state, thereby allowing zevents still within the kernel
  68 to be reprocessed.
  69 .It Fl d Ar zedletdir
  70 Read the enabled ZEDLETs from the specified directory.
  71 .It Fl p Ar pidfile
  72 Write the daemon's process ID to the specified file.
  73 .It Fl P Ar path
  74 Custom
  75 .Ev $PATH
  76 for zedlets to use.
  77 Normally zedlets run in a locked-down environment, with hardcoded paths to the ZFS commands
  78 .Pq Ev $ZFS , $ZPOOL , $ZED , ... ,
  79 and a hard-coded
  80 .Ev $PATH .
  81 This is done for security reasons.
  82 However, the ZFS test suite uses a custom PATH for its ZFS commands, and passes it to
  83 .Nm
  84 with
  85 .Fl P .
  86 In short,
  87 .Fl P
  88 is only to be used by the ZFS test suite; never use
  89 it in production!
  90 .It Fl s Ar statefile
  91 Write the daemon's state to the specified file.
  92 .It Fl j Ar jobs
  93 Allow at most
  94 .Ar jobs
  95 ZEDLETs to run concurrently,
  96 delaying execution of new ones until they finish.
  97 Defaults to
  98 .Sy 16 .
  99 .El
 100 .Sh ZEVENTS
 101 A zevent is comprised of a list of nvpairs (name/value pairs).
 102 Each zevent 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.
 108 Additional nvpairs exist to provide event details.
 109 .Pp
 110 The kernel maintains a list of recent zevents that can be viewed (along with
 111 their associated lists of nvpairs) using the
 112 .Nm zpool Cm events Fl v
 113 command.
 114 .
 115 .Sh CONFIGURATION
 116 ZEDLETs to be invoked in response to zevents are located in the
 117 .Em enabled-zedlets
 118 directory
 119 .Pq Ar zedletdir .
 120 These can be symlinked or copied from the
 121 .Em installed-zedlets
 122 directory; symlinks allow for automatic updates
 123 from the installed ZEDLETs, whereas copies preserve local modifications.
 124 As a security measure, since ownership change is a privileged operation,
 125 ZEDLETs must be owned by root.
 126 They must have execute permissions for the user,
 127 but they must not have write permissions for group or other.
 128 Dotfiles are ignored.
 129 .Pp
 130 ZEDLETs are named after the zevent class for which they should be invoked.
 131 In particular, a ZEDLET will be invoked for a given zevent if either its
 132 class or subclass string is a prefix of its filename (and is followed by
 133 a non-alphabetic character).
 134 As a special case, the prefix
 135 .Sy all
 136 matches all zevents.
 137 Multiple ZEDLETs may be invoked for a given zevent.
 138 .
 139 .Sh ZEDLETS
 140 ZEDLETs are executables invoked by the ZED in response to a given zevent.
 141 They should be written under the presumption they can be invoked concurrently,
 142 and they should use appropriate locking to access any shared resources.
 143 Common variables used by ZEDLETs can be stored in the default rc file which
 144 is sourced by scripts; these variables should be prefixed with
 145 .Sy ZED_ .
 146 .Pp
 147 The zevent nvpairs are passed to ZEDLETs as environment variables.
 148 Each nvpair name is converted to an environment variable in the following
 149 manner:
 150 .Bl -enum
 151 .It
 152 it is prefixed with
 153 .Sy ZEVENT_ ,
 154 .It
 155 it is converted to uppercase, and
 156 .It
 157 each non-alphanumeric character is converted to an underscore.
 158 .El
 159 .Pp
 160 Some additional environment variables have been defined to present certain
 161 nvpair values in a more convenient form.
 162 An incomplete list of zevent environment variables is as follows:
 163 .Bl -tag -width "ZEVENT_TIME_STRING"
 164 .It Sy ZEVENT_EID
 165 The Event IDentifier.
 166 .It Sy ZEVENT_CLASS
 167 The zevent class string.
 168 .It Sy ZEVENT_SUBCLASS
 169 The zevent subclass string.
 170 .It Sy ZEVENT_TIME
 171 The time at which the zevent was posted as
 172 .Dq Em seconds nanoseconds
 173 since the Epoch.
 174 .It Sy ZEVENT_TIME_SECS
 175 The
 176 .Em seconds
 177 component of
 178 .Sy ZEVENT_TIME .
 179 .It Sy ZEVENT_TIME_NSECS
 180 The
 181 .Em nanoseconds
 182 component of
 183 .Sy ZEVENT_TIME .
 184 .It Sy ZEVENT_TIME_STRING
 185 An almost-RFC3339-compliant string for
 186 .Sy ZEVENT_TIME .
 187 .El
 188 .Pp
 189 Additionally, the following ZED & ZFS variables are defined:
 190 .Bl -tag -width "ZEVENT_TIME_STRING"
 191 .It Sy ZED_PID
 192 The daemon's process ID.
 193 .It Sy ZED_ZEDLET_DIR
 194 The daemon's current
 195 .Em enabled-zedlets
 196 directory.
 197 .It Sy ZFS_ALIAS
 198 The alias
 199 .Pq Dq Em name Ns - Ns Em version Ns - Ns Em release
 200 string of the ZFS distribution the daemon is part of.
 201 .It Sy ZFS_VERSION
 202 The ZFS version the daemon is part of.
 203 .It Sy ZFS_RELEASE
 204 The ZFS release the daemon is part of.
 205 .El
 206 .Pp
 207 ZEDLETs may need to call other ZFS commands.
 208 The installation paths of the following executables are defined as environment variables:
 209 .Sy ZDB ,
 210 .Sy ZED ,
 211 .Sy ZFS ,
 212 .Sy ZINJECT ,
 213 and
 214 .Sy ZPOOL .
 215 These variables may be overridden in the rc file.
 216 .
 217 .Sh FILES
 218 .Bl -tag -width "-c"
 219 .It Pa @sysconfdir@/zfs/zed.d
 220 The default directory for enabled ZEDLETs.
 221 .It Pa @sysconfdir@/zfs/zed.d/zed.rc
 222 The default rc file for common variables used by ZEDLETs.
 223 .It Pa @zfsexecdir@/zed.d
 224 The default directory for installed ZEDLETs.
 225 .It Pa @runstatedir@/zed.pid
 226 The default file containing the daemon's process ID.
 227 .It Pa @runstatedir@/zed.state
 228 The default file containing the daemon's state.
 229 .El
 230 .
 231 .Sh SIGNALS
 232 .Bl -tag -width "-c"
 233 .It Sy SIGHUP
 234 Reconfigure the daemon and rescan the directory for enabled ZEDLETs.
 235 .It Sy SIGTERM , SIGINT
 236 Terminate the daemon.
 237 .El
 238 .
 239 .Sh SEE ALSO
 240 .Xr zfs 8 ,
 241 .Xr zpool 8 ,
 242 .Xr zpool-events 8
 243 .
 244 .Sh NOTES
 245 The
 246 .Nm
 247 requires root privileges.
 248 .Pp
 249 Do not taunt the
 250 .Nm .
 251 .
 252 .Sh BUGS
 253 ZEDLETs are unable to return state/status information to the kernel.
 254 .Pp
 255 Internationalization support via gettext has not been added.