| blob | 0e63fbe9b4e193f1fe092af9b9e75a697ac9131e |
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH SYSEVENTADM 8 "Sep 28, 2005"
7 .SH NAME
8 syseventadm \- sysevent event specification administration
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBsyseventadm\fR add [\fB-R\fR \fIrootdir\fR] [\fB-v\fR \fIvendor\fR] [\fB-p\fR \fIpublisher\fR]
13 [\fB-c\fR \fIclass\fR] [\fB-s\fR \fIsubclass\fR] [\fB-u\fR \fIusername\fR] \fIpath\fR [\fIargs\fR]
14 .fi
16 .LP
17 .nf
18 \fBsyseventadm\fR remove [\fB-R\fR \fIrootdir\fR] [\fB-v\fR \fIvendor\fR] [\fB-p\fR \fIpublisher\fR]
19 [\fB-c\fR \fIclass\fR] [\fB-s\fR \fIsubclass\fR] [\fB-u\fR \fIusername\fR] [\fIpath\fR [\fIargs\fR]]
20 .fi
22 .LP
23 .nf
24 \fBsyseventadm\fR list [\fB-R\fR \fIrootdir\fR] [\fB-v\fR \fIvendor\fR] [\fB-p\fR \fIpublisher\fR]
25 [\fB-c\fR \fIclass\fR] [\fB-s\fR \fIsubclass\fR] [\fB-u\fR \fIusername\fR] [\fIpath\fR [\fIargs\fR]]
26 .fi
28 .LP
29 .nf
30 \fBsyseventadm\fR restart
31 .fi
33 .SH DESCRIPTION
34 .sp
35 .LP
36 The \fBsyseventadm\fR command is an administrative front-end to add, remove and
37 list \fBsysevent\fR event handlers. You can also restart the sysevent daemon by
38 use of the restart command. \fBsyseventadm\fR can only be run by root.
39 .sp
40 .LP
41 The \fBsyseventadm\fR \fBadd\fR command adds a handler for a \fBsysevent\fR
42 event specified by at least one of vendor, publisher or class. If \fIclass\fR
43 is specified, it may be qualified with a \fIsub-class\fR. Only the values
44 specified for \fIvendor\fR, \fIpublisher\fR, \fIclass\fR and \fIsub-class\fR
45 when adding the handler are matched against \fBsysevent\fR events to determine
46 if the specification matches the event and the handler should be run.
47 \fIpath\fR is the full pathname of the command to be run in response to
48 matching events, with optional arguments (\fIargs\fR). If username is
49 specified, the command is invoked as user \fIusername\fR, otherwise as root.
50 .sp
51 .LP
52 The \fBsyseventadm\fR \fBremove\fR command removes handlers for matching
53 sysevent event specifications. Event specifications may be matched by
54 specifying at least one of \fIvendor\fR, \fIpublisher\fR, \fIclass\fR,
55 \fIusername\fR or \fIpath\fR. If \fIclass\fR is specified, it may be qualified
56 with a \fIsub-class\fR. Any of \fIvendor\fR, \fIpublisher\fR, \fIclass\fR,
57 \fIsub-class\fR, \fIusername\fR, \fIpath\fR or \fIargs\fR not specified match
58 the corresponding fields of all events. Handlers for all matching
59 specifications are removed.
60 .sp
61 .LP
62 The \fBsyseventadm\fR \fBlist\fR command lists the handlers for matching
63 \fBsysevent\fR event specifications using the same match criteria as the
64 \fBremove\fR command but without the requirement that at least one of
65 \fIvendor\fR, \fIpublisher\fR, \fIclass\fR, \fIusername\fR or \fIpath\fR be
66 specified. With no match criteria, all specifications are listed. The list
67 command output format is: [vendor=\fIvendor\fR] [publisher=\fIpublisher\fR]
68 [class=\fIclass\fR] [subclass=\fIsubclass\fR] [username=\fIusername\fR]
69 \fIpath\fR [\fIargs\fR] where each of \fIclass\fR, \fIsub-class\fR,
70 \fIvendor\fR, \fIpublisher\fR and \fIusername\fR is listed only if part of the
71 match criteria for the listed specification.
72 .sp
73 .LP
74 The \fBsyseventadm\fR \fBrestart\fR command informs the \fBsyseventd\fR daemon
75 to reread the \fBsysevent\fR registry after a change has been made by adding or
76 removing one or more \fBsysevent\fR handler specifications.
77 .SS "Argument Macro Substitution"
78 .sp
79 .LP
80 The \fBsysevent\fR handling facility provides extensive macro capability for
81 constructing the command line arguments to be executed in response to an event.
82 Macro expansion applies only to the command line \fIargs\fR specified for an
83 event handler, with macros expanded with data from the event itself.
84 Pre-defined macros are provided for the event \fIclass\fR, \fIsubclass\fR,
85 \fIpublisher\fR and \fIvendor\fR information. Macros not matching one of the
86 pre-defined macro names cause the attribute list attached to the event to be
87 searched for an attribute of that name, with the value of the matching
88 attribute substituted on the command line.
89 .sp
90 .LP
91 Macros are introduced by the \fB$\fR character, with the macro name being the
92 following token separated by a SPACE or TAB character. If the macro name is
93 embedded in text, it may be delineated by \fB${\fR and \fB}\fR. A \fB\e\fR
94 before the \fB$\fR causes macro expansion not to occur.
95 .sp
96 .ne 2
97 .na
98 \fB$\fIclass\fR\fR
99 .ad
100 .RS 14n
101 The class string defining the event
102 .RE
104 .sp
105 .ne 2
106 .na
107 \fB$\fIpublisher\fR\fR
108 .ad
109 .RS 14n
110 The publisher string defining the event
111 .RE
113 .sp
114 .ne 2
115 .na
116 \fB$\fIsequence\fR\fR
117 .ad
118 .RS 14n
119 The sequence number of the event.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB$\fIsubclass\fR\fR
126 .ad
127 .RS 14n
128 The subclass string defining the event
129 .RE
131 .sp
132 .ne 2
133 .na
134 \fB$\fItimestamp\fR\fR
135 .ad
136 .RS 14n
137 The timestamp of the event.
138 .RE
140 .sp
141 .ne 2
142 .na
143 \fB$\fIvendor\fR\fR
144 .ad
145 .RS 14n
146 The vendor string defining the event
147 .RE
149 .sp
150 .LP
151 Macro names other than those pre-defined are compared against the attribute
152 list provided with the event. An attribute with name matching the macro name
153 causes the value of the attribute to be substituted as \fBASCII\fR text on the
154 generated command line.
155 .sp
156 .LP
157 Use of a macro for which no attribute with that name is defined, or for which
158 multiple attributes with that name are provided, cause an error and the command
159 is not invoked.
160 .sp
161 .LP
162 Attributes with signed data types (\fBDATA_TYPE_INT16\fR, \fBDATA_TYPE_INT32\fR
163 and \fBDATA_TYPE_INT64\fR) are expanded as decimal digits.
164 .sp
165 .LP
166 Attributes with unsigned data types (\fBDATA_TYPE_BYTE\fR,
167 \fBDATA_TYPE_UINT16\fR, \fBDATA_TYPE_UINT32\fR, \fBDATA_TYPE_UINT64\fR and
168 \fBDATA_TYPE_HTTIME\fR) are expanded as hexadecimal digits with a \fB0x\fR
169 prefix.
170 .sp
171 .LP
172 Attributes with string data type (\fBDATA_TYPE_STRING\fR) are expanded with the
173 string data. The data is not quoted. If if it desired that the quoted strings
174 be generated on the command line, put quotes around the macro call in the
175 arguments.
176 .sp
177 .LP
178 Array types are expanded with each element expanded as defined for that scalar
179 type, with a space separating each element substitution.
180 .SH OPTIONS
181 .sp
182 .LP
183 The \fBadd\fR, \fBlist\fR and \fBremove\fR subcommands support the following
184 options:
185 .sp
186 .ne 2
187 .na
188 \fB\fB-c\fR \fIclass\fR\fR
189 .ad
190 .RS 16n
191 Specify the event class, \fIclass\fR.
192 .RE
194 .sp
195 .ne 2
196 .na
197 \fB\fB-p\fR \fIpublisher\fR\fR
198 .ad
199 .RS 16n
200 Specify the event publisher, \fIpublisher\fR.
201 .RE
203 .sp
204 .ne 2
205 .na
206 \fB\fB-R\fR \fIrootdir\fR\fR
207 .ad
208 .RS 16n
209 Specify an alternate root path, \fIrootdir\fR.
210 .LP
211 Note -
212 .sp
213 .RS 2
214 The root file system of any non-global zones must not be referenced with the
215 \fB-R\fR option. Doing so might damage the global zone's file system, might
216 compromise the security of the global zone, and might damage the non-global
217 zone's file system. See \fBzones\fR(5).
218 .RE
219 .RE
221 .sp
222 .ne 2
223 .na
224 \fB\fB-s\fR \fIsubclass\fR\fR
225 .ad
226 .RS 16n
227 Specify the event subclass, \fIsubclass\fR.
228 .RE
230 .sp
231 .ne 2
232 .na
233 \fB\fB-u\fR \fIusername\fR\fR
234 .ad
235 .RS 16n
236 Specify the username (\fIusername\fR) to invoke the command.
237 .RE
239 .sp
240 .ne 2
241 .na
242 \fB\fB-v\fR \fIvendor\fR\fR
243 .ad
244 .RS 16n
245 Specify the vendor (\fIvendor\fR) that defines the event. Events defined by
246 third-party software should specify the company's stock symbol as \fIvendor\fR.
247 Sun-defined events use \fBSUNW\fR.
248 .RE
250 .SH OPERANDS
251 .sp
252 .LP
253 The \fBadd\fR, \fBlist\fR and \fBremove\fR subcommands support the following
254 options:
255 .sp
256 .ne 2
257 .na
258 \fB\fIargs\fR\fR
259 .ad
260 .RS 8n
261 Command arguments
262 .RE
264 .sp
265 .ne 2
266 .na
267 \fB\fIpath\fR\fR
268 .ad
269 .RS 8n
270 Full path of command to be run in response to event
271 .RE
273 .SH EXAMPLES
274 .LP
275 \fBExample 1 \fRAdding an Event Handler
276 .sp
277 .LP
278 The following example adds an event handler for an event defined by vendor
279 \fBMYCO\fR ("My Company"), class \fBEC_ENV\fR and sub-class \fBESC_ENV_TEMP\fR.
280 The command to be run is \fB/opt/MYCOenv/bin/ec_env_temp\fR, with arguments
281 being the class name, sub-class name and pathname derived from the event
282 attributes. The \fB$\fR characters are preceded by a backslash to circumvent
283 shell interpretation. There is no need to restart the service after the change
284 since the registry is maintained on \fB$ALTROOT\fR.
286 .sp
287 .in +2
288 .nf
289 # syseventadm add -R \$ALTROOT -v MYCO -c EC_ENV -s ESC_ENV_TEMP \e
290 /opt/MYCOenv/bin/ec_env_temp \e$class \e$subclass \e$pathname
291 .fi
292 .in -2
293 .sp
295 .sp
296 .LP
297 Note the caveat on the use of the \fB-R\fR option in the description of that
298 option, above.
300 .LP
301 \fBExample 2 \fRRemoving an Event Handler
302 .sp
303 .LP
304 The following example removes the event handler added in Example 1.
306 .sp
307 .in +2
308 .nf
309 # syseventadm remove -R \$ALTROOT -v MYCO -c EC_ENV -s ESC_ENV_TEMP \e
310 /opt/MYCOenv/bin/ec_env_temp \${class} \${subclass} \${pathname}
311 .fi
312 .in -2
313 .sp
315 .sp
316 .LP
317 Note the caveat on the use of the \fB-R\fR option in the description of that
318 option, above.
320 .LP
321 \fBExample 3 \fRListing Event Handlers
322 .sp
323 .LP
324 The following example lists all event handlers for events of class
325 \fBEC_ENV\fR, subclass \fBESC_ENV_TEMP\fR, as defined by vendor \fBMYCO\fR:
327 .sp
328 .in +2
329 .nf
330 # syseventadm list -v MYCO -c EC_ENV -s ESC_ENV_TEMP \e
331 vendor=MYCO class=EC_ENV subclass=ESC_ENV_TEMP \e
332 /opt/MYCOenv/bin/ec_env_temp \e${class} \e${subclass} \e${pathname}
333 .fi
334 .in -2
335 .sp
337 .LP
338 \fBExample 4 \fRListing Event Handlers
339 .sp
340 .LP
341 The following example lists all event handlers defined by vendor \fBVRTS\fR.
343 .sp
344 .in +2
345 .nf
346 # syseventadm list -v VRTS
347 .fi
348 .in -2
349 .sp
351 .LP
352 \fBExample 5 \fRRemoving Event Handlers
353 .sp
354 .LP
355 The following example removes all event handlers defined by vendor \fBVRTS\fR,
356 and restarts service.
358 .sp
359 .in +2
360 .nf
361 # syseventadm remove -v VRTS
362 # syseventadm restart
363 .fi
364 .in -2
365 .sp
367 .LP
368 \fBExample 6 \fRListing All Event Handlers Specified to Run a Command
369 .sp
370 .LP
371 The following example lists all event handlers specified to run the command
372 \fB/opt/MYCOenv/bin/ec_env_temp\fR:
374 .sp
375 .in +2
376 .nf
377 # syseventadm list /opt/MYCOenv/bin/ec_env_temp
378 .fi
379 .in -2
380 .sp
382 .LP
383 \fBExample 7 \fRRemoving Event Handlers and Restarting Service
384 .sp
385 .LP
386 The following example removes all event handlers specified to run the command
387 \fB/opt/MYCOenv/bin/ec_env_temp\fR, and restarts service:
389 .sp
390 .in +2
391 .nf
392 # syseventadm remove /opt/MYCOenv/bin/ec_env_temp
393 # syseventadm restart
394 .fi
395 .in -2
396 .sp
398 .SH EXIT STATUS
399 .sp
400 .LP
401 The following exit values are returned:
402 .sp
403 .ne 2
404 .na
405 \fB\fB0\fR\fR
406 .ad
407 .RS 5n
408 Successful completion.
409 .RE
411 .sp
412 .ne 2
413 .na
414 \fB\fB1\fR\fR
415 .ad
416 .RS 5n
417 No matching event specification found (remove or list commands only).
418 .RE
420 .sp
421 .ne 2
422 .na
423 \fB\fB2\fR\fR
424 .ad
425 .RS 5n
426 Incorrect command usage.
427 .RE
429 .sp
430 .ne 2
431 .na
432 \fB\fB3\fR\fR
433 .ad
434 .RS 5n
435 Permission denied.
436 .RE
438 .sp
439 .ne 2
440 .na
441 \fB\fB4\fR\fR
442 .ad
443 .RS 5n
444 Command failed.
445 .RE
447 .sp
448 .ne 2
449 .na
450 \fB\fB5\fR\fR
451 .ad
452 .RS 5n
453 Out of memory.
454 .RE
456 .SH SEE ALSO
457 .sp
458 .LP
459 \fBsyseventd\fR(8), \fBsysevent_post_event\fR(3SYSEVENT), \fBattributes\fR(5),
460 \fBddi_log_sysevent\fR(9F)
461 .SH NOTES
462 .sp
463 .LP
464 To avoid upgrade problems, packages delivering a sysevent event handler should
465 install the event handler by running \fBsyseventadm\fR from the package's
466 postinstall script. The event handler can then be removed by running
467 \fBsyseventadm\fR from the package's preremove script using the same arguments
468 as when added.