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