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