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