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 May 26, 2021 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. 161Common variables used by ZEDLETs can be stored in the default rc file which 162is sourced by scripts; these variables should be prefixed with 163.Sy ZED_ . 164.Pp 165The zevent nvpairs are passed to ZEDLETs as environment variables. 166Each nvpair name is converted to an environment variable in the following 167manner: 168.Bl -enum -compact 169.It 170it is prefixed with 171.Sy ZEVENT_ , 172.It 173it is converted to uppercase, and 174.It 175each non-alphanumeric character is converted to an underscore. 176.El 177.Pp 178Some additional environment variables have been defined to present certain 179nvpair values in a more convenient form. 180An incomplete list of zevent environment variables is as follows: 181.Bl -tag -compact -width "ZEVENT_TIME_STRING" 182.It Sy ZEVENT_EID 183The Event IDentifier. 184.It Sy ZEVENT_CLASS 185The zevent class string. 186.It Sy ZEVENT_SUBCLASS 187The zevent subclass string. 188.It Sy ZEVENT_TIME 189The time at which the zevent was posted as 190.Dq Em seconds nanoseconds 191since the Epoch. 192.It Sy ZEVENT_TIME_SECS 193The 194.Em seconds 195component of 196.Sy ZEVENT_TIME . 197.It Sy ZEVENT_TIME_NSECS 198The 199.Em nanoseconds 200component of 201.Sy ZEVENT_TIME . 202.It Sy ZEVENT_TIME_STRING 203An almost-RFC3339-compliant string for 204.Sy ZEVENT_TIME . 205.El 206.Pp 207Additionally, the following ZED & ZFS variables are defined: 208.Bl -tag -compact -width "ZEVENT_TIME_STRING" 209.It Sy ZED_PID 210The daemon's process ID. 211.It Sy ZED_ZEDLET_DIR 212The daemon's current 213.Em enabled-zedlets 214directory. 215.It Sy ZFS_ALIAS 216The alias 217.Pq Dq Em name Ns - Ns Em version Ns - Ns Em release 218string of the ZFS distribution the daemon is part of. 219.It Sy ZFS_VERSION 220The ZFS version the daemon is part of. 221.It Sy ZFS_RELEASE 222The ZFS release the daemon is part of. 223.El 224.Pp 225ZEDLETs may need to call other ZFS commands. 226The installation paths of the following executables are defined as environment 227variables: 228.Sy ZDB , 229.Sy ZED , 230.Sy ZFS , 231.Sy ZINJECT , 232and 233.Sy ZPOOL . 234These variables may be overridden in the rc file. 235. 236.Sh FILES 237.Bl -tag -width "-c" 238.It Pa @sysconfdir@/zfs/zed.d 239The default directory for enabled ZEDLETs. 240.It Pa @sysconfdir@/zfs/zed.d/zed.rc 241The default rc file for common variables used by ZEDLETs. 242.It Pa @zfsexecdir@/zed.d 243The default directory for installed ZEDLETs. 244.It Pa @runstatedir@/zed.pid 245The default file containing the daemon's process ID. 246.It Pa @runstatedir@/zed.state 247The default file containing the daemon's state. 248.El 249. 250.Sh SIGNALS 251.Bl -tag -width "-c" 252.It Sy SIGHUP 253Reconfigure the daemon and rescan the directory for enabled ZEDLETs. 254.It Sy SIGTERM , SIGINT 255Terminate the daemon. 256.El 257. 258.Sh SEE ALSO 259.Xr zfs 8 , 260.Xr zpool 8 , 261.Xr zpool-events 8 262. 263.Sh NOTES 264The 265.Nm 266requires root privileges. 267.Pp 268Do not taunt the 269.Nm . 270. 271.Sh BUGS 272ZEDLETs are unable to return state/status information to the kernel. 273.Pp 274Internationalization support via gettext has not been added. 275