1.\" SPDX-License-Identifier: CDDL-1.0 2.\" 3.\" This file is part of the ZFS Event Daemon (ZED). 4.\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049). 5.\" Copyright (C) 2013-2014 Lawrence Livermore National Security, LLC. 6.\" Refer to the OpenZFS 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.\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049) 15.\" 16.Dd August 22, 2022 17.Dt ZED 8 18.Os 19. 20.Sh NAME 21.Nm ZED 22.Nd ZFS Event Daemon 23.Sh SYNOPSIS 24.Nm 25.Op Fl fFhILMvVZ 26.Op Fl d Ar zedletdir 27.Op Fl p Ar pidfile 28.Op Fl P Ar path 29.Op Fl s Ar statefile 30.Op Fl j Ar jobs 31.Op Fl b Ar buflen 32. 33.Sh DESCRIPTION 34The 35.Nm 36(ZFS Event Daemon) monitors events generated by the ZFS kernel 37module. 38When a zevent (ZFS Event) is posted, the 39.Nm 40will run any ZEDLETs (ZFS Event Daemon Linkage for Executable Tasks) 41that have been enabled for the corresponding zevent class. 42. 43.Sh OPTIONS 44.Bl -tag -width "-h" 45.It Fl h 46Display a summary of the command-line options. 47.It Fl L 48Display license information. 49.It Fl V 50Display version information. 51.It Fl v 52Be verbose. 53.It Fl f 54Force the daemon to run if at all possible, disabling security checks and 55throwing caution to the wind. 56Not recommended for use in production. 57.It Fl F 58Don't daemonize: remain attached to the controlling terminal, 59log to the standard I/O streams. 60.It Fl M 61Lock all current and future pages in the virtual memory address space. 62This may help the daemon remain responsive when the system is under heavy 63memory pressure. 64.It Fl I 65Request that the daemon idle rather than exit when the kernel modules are not 66loaded. 67Processing of events will start, or resume, when the kernel modules are 68(re)loaded. 69Under Linux the kernel modules cannot be unloaded while the daemon is running. 70.It Fl Z 71Zero the daemon's state, thereby allowing zevents still within the kernel 72to be reprocessed. 73.It Fl d Ar zedletdir 74Read the enabled ZEDLETs from the specified directory. 75.It Fl p Ar pidfile 76Write the daemon's process ID to the specified file. 77.It Fl P Ar path 78Custom 79.Ev $PATH 80for zedlets to use. 81Normally zedlets run in a locked-down environment, with hardcoded paths to the 82ZFS commands 83.Pq Ev $ZFS , $ZPOOL , $ZED , … , 84and a hard-coded 85.Ev $PATH . 86This is done for security reasons. 87However, the ZFS test suite uses a custom PATH for its ZFS commands, and passes 88it to 89.Nm 90with 91.Fl P . 92In short, 93.Fl P 94is only to be used by the ZFS test suite; never use 95it in production! 96.It Fl s Ar statefile 97Write the daemon's state to the specified file. 98.It Fl j Ar jobs 99Allow at most 100.Ar jobs 101ZEDLETs to run concurrently, 102delaying execution of new ones until they finish. 103Defaults to 104.Sy 16 . 105.It Fl b Ar buflen 106Cap kernel event buffer growth to 107.Ar buflen 108entries. 109This buffer is grown when the daemon misses an event, but results in 110unreclaimable memory use in the kernel. 111A value of 112.Sy 0 113removes the cap. 114Defaults to 115.Sy 1048576 . 116.El 117.Sh ZEVENTS 118A zevent is comprised of a list of nvpairs (name/value pairs). 119Each zevent contains an EID (Event IDentifier) that uniquely identifies it 120throughout 121the lifetime of the loaded ZFS kernel module; this EID is a monotonically 122increasing integer that resets to 1 each time the kernel module is loaded. 123Each zevent also contains a class string that identifies the type of event. 124For brevity, a subclass string is defined that omits the leading components 125of the class string. 126Additional nvpairs exist to provide event details. 127.Pp 128The kernel maintains a list of recent zevents that can be viewed (along with 129their associated lists of nvpairs) using the 130.Nm zpool Cm events Fl v 131command. 132. 133.Sh CONFIGURATION 134ZEDLETs to be invoked in response to zevents are located in the 135.Em enabled-zedlets 136directory 137.Pq Ar zedletdir . 138These can be symlinked or copied from the 139.Em installed-zedlets 140directory; symlinks allow for automatic updates 141from the installed ZEDLETs, whereas copies preserve local modifications. 142As a security measure, since ownership change is a privileged operation, 143ZEDLETs must be owned by root. 144They must have execute permissions for the user, 145but they must not have write permissions for group or other. 146Dotfiles are ignored. 147.Pp 148ZEDLETs are named after the zevent class for which they should be invoked. 149In particular, a ZEDLET will be invoked for a given zevent if either its 150class or subclass string is a prefix of its filename (and is followed by 151a non-alphabetic character). 152As a special case, the prefix 153.Sy all 154matches all zevents. 155Multiple ZEDLETs may be invoked for a given zevent. 156. 157.Sh ZEDLETS 158ZEDLETs are executables invoked by the ZED in response to a given zevent. 159They should be written under the presumption they can be invoked concurrently, 160and they should use appropriate locking to access any shared resources. 161The one exception to this are "synchronous zedlets", which are described later 162in this page. 163Common variables used by ZEDLETs can be stored in the default rc file which 164is sourced by scripts; these variables should be prefixed with 165.Sy ZED_ . 166.Pp 167The zevent nvpairs are passed to ZEDLETs as environment variables. 168Each nvpair name is converted to an environment variable in the following 169manner: 170.Bl -enum -compact 171.It 172it is prefixed with 173.Sy ZEVENT_ , 174.It 175it is converted to uppercase, and 176.It 177each non-alphanumeric character is converted to an underscore. 178.El 179.Pp 180Some additional environment variables have been defined to present certain 181nvpair values in a more convenient form. 182An incomplete list of zevent environment variables is as follows: 183.Bl -tag -compact -width "ZEVENT_TIME_STRING" 184.It Sy ZEVENT_EID 185The Event IDentifier. 186.It Sy ZEVENT_CLASS 187The zevent class string. 188.It Sy ZEVENT_SUBCLASS 189The zevent subclass string. 190.It Sy ZEVENT_TIME 191The time at which the zevent was posted as 192.Dq Em seconds nanoseconds 193since the Epoch. 194.It Sy ZEVENT_TIME_SECS 195The 196.Em seconds 197component of 198.Sy ZEVENT_TIME . 199.It Sy ZEVENT_TIME_NSECS 200The 201.Em nanoseconds 202component of 203.Sy ZEVENT_TIME . 204.It Sy ZEVENT_TIME_STRING 205An almost-RFC3339-compliant string for 206.Sy ZEVENT_TIME . 207.El 208.Pp 209Additionally, the following ZED & ZFS variables are defined: 210.Bl -tag -compact -width "ZEVENT_TIME_STRING" 211.It Sy ZED_PID 212The daemon's process ID. 213.It Sy ZED_ZEDLET_DIR 214The daemon's current 215.Em enabled-zedlets 216directory. 217.It Sy ZFS_ALIAS 218The alias 219.Pq Dq Em name Ns - Ns Em version Ns - Ns Em release 220string of the ZFS distribution the daemon is part of. 221.It Sy ZFS_VERSION 222The ZFS version the daemon is part of. 223.It Sy ZFS_RELEASE 224The ZFS release the daemon is part of. 225.El 226.Pp 227ZEDLETs may need to call other ZFS commands. 228The installation paths of the following executables are defined as environment 229variables: 230.Sy ZDB , 231.Sy ZED , 232.Sy ZFS , 233.Sy ZINJECT , 234and 235.Sy ZPOOL . 236These variables may be overridden in the rc file. 237. 238.Sh Synchronous ZEDLETS 239ZED's normal behavior is to spawn off zedlets in parallel and ignore their 240completion order. 241This means that ZED can potentially 242have zedlets for event ID number 2 starting before zedlets for event ID number 2431 have finished. 244Most of the time this is fine, and it actually helps when the system is getting 245hammered with hundreds of events. 246.Pp 247However, there are times when you want your zedlets to be executed in sequence 248with the event ID. 249That is where synchronous zedlets come in. 250.Pp 251ZED will wait for all previously spawned zedlets to finish before running 252a synchronous zedlet. 253Synchronous zedlets are guaranteed to be the only 254zedlet running. 255No other zedlets may run in parallel with a synchronous zedlet. 256Users should be careful to only use synchronous zedlets when needed, since 257they decrease parallelism. 258.Pp 259To make a zedlet synchronous, simply add a "-sync-" immediately following the 260event name in the zedlet's file name: 261.Pp 262.Sy EVENT_NAME-sync-ZEDLETNAME.sh 263.Pp 264For example, if you wanted a synchronous statechange script: 265.Pp 266.Sy statechange-sync-myzedlet.sh 267. 268.Sh FILES 269.Bl -tag -width "-c" 270.It Pa @sysconfdir@/zfs/zed.d 271The default directory for enabled ZEDLETs. 272.It Pa @sysconfdir@/zfs/zed.d/zed.rc 273The default rc file for common variables used by ZEDLETs. 274.It Pa @zfsexecdir@/zed.d 275The default directory for installed ZEDLETs. 276.It Pa @runstatedir@/zed.pid 277The default file containing the daemon's process ID. 278.It Pa @runstatedir@/zed.state 279The default file containing the daemon's state. 280.El 281. 282.Sh SIGNALS 283.Bl -tag -width "-c" 284.It Sy SIGHUP 285Reconfigure the daemon and rescan the directory for enabled ZEDLETs. 286.It Sy SIGTERM , SIGINT 287Terminate the daemon. 288.El 289. 290.Sh SEE ALSO 291.Xr zfs 8 , 292.Xr zpool 8 , 293.Xr zpool-events 8 294. 295.Sh NOTES 296The 297.Nm 298requires root privileges. 299.Pp 300Do not taunt the 301.Nm . 302. 303.Sh BUGS 304ZEDLETs are unable to return state/status information to the kernel. 305.Pp 306Internationalization support via gettext has not been added. 307