path: root/usr/src/man/man8/syseventadm.8

'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH SYSEVENTADM 8 "Sep 28, 2005"
.SH NAME
syseventadm \- sysevent event specification administration
.SH SYNOPSIS
.LP
.nf
\fBsyseventadm\fR add [\fB-R\fR \fIrootdir\fR] [\fB-v\fR \fIvendor\fR] [\fB-p\fR \fIpublisher\fR]
     [\fB-c\fR \fIclass\fR] [\fB-s\fR \fIsubclass\fR] [\fB-u\fR \fIusername\fR] \fIpath\fR [\fIargs\fR]
.fi

.LP
.nf
\fBsyseventadm\fR remove [\fB-R\fR \fIrootdir\fR] [\fB-v\fR \fIvendor\fR] [\fB-p\fR \fIpublisher\fR]
     [\fB-c\fR \fIclass\fR] [\fB-s\fR \fIsubclass\fR] [\fB-u\fR \fIusername\fR] [\fIpath\fR [\fIargs\fR]]
.fi

.LP
.nf
\fBsyseventadm\fR list [\fB-R\fR \fIrootdir\fR] [\fB-v\fR \fIvendor\fR] [\fB-p\fR \fIpublisher\fR]
     [\fB-c\fR \fIclass\fR] [\fB-s\fR \fIsubclass\fR] [\fB-u\fR \fIusername\fR] [\fIpath\fR [\fIargs\fR]]
.fi

.LP
.nf
\fBsyseventadm\fR restart
.fi

.SH DESCRIPTION

.LP
The \fBsyseventadm\fR command is an administrative front-end to add, remove and
list \fBsysevent\fR event handlers. You can also restart the sysevent daemon by
use of the restart command. \fBsyseventadm\fR can only be run by root.
.sp
.LP
The \fBsyseventadm\fR \fBadd\fR command adds a handler for a \fBsysevent\fR
event specified by at least one of vendor, publisher or class. If \fIclass\fR
is specified, it may be qualified with a \fIsub-class\fR. Only the values
specified for \fIvendor\fR, \fIpublisher\fR, \fIclass\fR and \fIsub-class\fR
when adding the handler are matched against \fBsysevent\fR events to determine
if the specification matches the event and the handler should be run.
\fIpath\fR is the full pathname of the command to be run in response to
matching events, with optional arguments (\fIargs\fR). If username is
specified, the command is invoked as user \fIusername\fR, otherwise as root.
.sp
.LP
The \fBsyseventadm\fR \fBremove\fR command removes handlers for matching
sysevent event specifications. Event specifications may be matched by
specifying at least one of \fIvendor\fR, \fIpublisher\fR, \fIclass\fR,
\fIusername\fR or \fIpath\fR. If \fIclass\fR is specified, it may be qualified
with a \fIsub-class\fR. Any of \fIvendor\fR, \fIpublisher\fR, \fIclass\fR,
\fIsub-class\fR, \fIusername\fR, \fIpath\fR or \fIargs\fR not specified match
the corresponding fields of all events. Handlers for all matching
specifications are removed.
.sp
.LP
The \fBsyseventadm\fR \fBlist\fR command lists the handlers for matching
\fBsysevent\fR event specifications using the same match criteria as the
\fBremove\fR command but without the requirement that at least one of
\fIvendor\fR, \fIpublisher\fR, \fIclass\fR, \fIusername\fR or \fIpath\fR be
specified. With no match criteria, all specifications are listed. The list
command output format is: [vendor=\fIvendor\fR] [publisher=\fIpublisher\fR]
[class=\fIclass\fR] [subclass=\fIsubclass\fR] [username=\fIusername\fR]
\fIpath\fR [\fIargs\fR] where each of \fIclass\fR, \fIsub-class\fR,
\fIvendor\fR, \fIpublisher\fR and \fIusername\fR is listed only if part of the
match criteria for the listed specification.
.sp
.LP
The \fBsyseventadm\fR \fBrestart\fR command informs the \fBsyseventd\fR daemon
to reread the \fBsysevent\fR registry after a change has been made by adding or
removing one or more \fBsysevent\fR handler specifications.
.SS "Argument Macro Substitution"

.LP
The \fBsysevent\fR handling facility provides extensive macro capability for
constructing the command line arguments to be executed in response to an event.
Macro expansion applies only to the command line \fIargs\fR specified for an
event handler, with macros expanded with data from the event itself.
Pre-defined macros are provided for the event \fIclass\fR, \fIsubclass\fR,
\fIpublisher\fR and \fIvendor\fR information. Macros not matching one of the
pre-defined macro names cause the attribute list attached to the event to be
searched for an attribute of that name, with the value of the matching
attribute substituted on the command line.
.sp
.LP
Macros are introduced by the \fB$\fR character, with the macro name being the
following token separated by a SPACE or TAB character. If the macro name is
embedded in text, it may be delineated by \fB${\fR and \fB}\fR. A \fB\e\fR
before the \fB$\fR causes macro expansion not to occur.
.sp
.ne 2
.na
\fB$\fIclass\fR\fR
.ad
.RS 14n
The class string defining the event
.RE

.sp
.ne 2
.na
\fB$\fIpublisher\fR\fR
.ad
.RS 14n
The publisher string defining the event
.RE

.sp
.ne 2
.na
\fB$\fIsequence\fR\fR
.ad
.RS 14n
The sequence number of the event.
.RE

.sp
.ne 2
.na
\fB$\fIsubclass\fR\fR
.ad
.RS 14n
The subclass string defining the event
.RE

.sp
.ne 2
.na
\fB$\fItimestamp\fR\fR
.ad
.RS 14n
The timestamp of the event.
.RE

.sp
.ne 2
.na
\fB$\fIvendor\fR\fR
.ad
.RS 14n
The vendor string defining the event
.RE

.sp
.LP
Macro names other than those pre-defined are compared against the attribute
list provided with the event. An attribute with name matching the macro name
causes the value of the attribute to be substituted as \fBASCII\fR text on the
generated command line.
.sp
.LP
Use of a macro for which no attribute with that name is defined, or for which
multiple attributes with that name are provided, cause an error and the command
is not invoked.
.sp
.LP
Attributes with signed data types (\fBDATA_TYPE_INT16\fR, \fBDATA_TYPE_INT32\fR
and \fBDATA_TYPE_INT64\fR) are expanded as decimal digits.
.sp
.LP
Attributes with unsigned data types (\fBDATA_TYPE_BYTE\fR,
\fBDATA_TYPE_UINT16\fR, \fBDATA_TYPE_UINT32\fR, \fBDATA_TYPE_UINT64\fR and
\fBDATA_TYPE_HTTIME\fR) are expanded as hexadecimal digits with a \fB0x\fR
prefix.
.sp
.LP
Attributes with string data type (\fBDATA_TYPE_STRING\fR) are expanded with the
string data. The data is not quoted. If if it desired that the quoted strings
be generated on the command line, put quotes around the macro call in the
arguments.
.sp
.LP
Array types are expanded with each element expanded as defined for that scalar
type, with a space separating each element substitution.
.SH OPTIONS

.LP
The \fBadd\fR, \fBlist\fR and \fBremove\fR subcommands support the following
options:
.sp
.ne 2
.na
\fB\fB-c\fR \fIclass\fR\fR
.ad
.RS 16n
Specify the event class, \fIclass\fR.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIpublisher\fR\fR
.ad
.RS 16n
Specify the event publisher, \fIpublisher\fR.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR \fIrootdir\fR\fR
.ad
.RS 16n
Specify an alternate root path, \fIrootdir\fR.
.LP
Note -
.sp
.RS 2
The root file system of any non-global zones must not be referenced with the
\fB-R\fR option. Doing so might damage the global zone's file system, might
compromise the security of the global zone, and might damage the non-global
zone's file system. See \fBzones\fR(7).
.RE
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIsubclass\fR\fR
.ad
.RS 16n
Specify the event subclass, \fIsubclass\fR.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR \fIusername\fR\fR
.ad
.RS 16n
Specify the username (\fIusername\fR) to invoke the command.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR \fIvendor\fR\fR
.ad
.RS 16n
Specify the vendor (\fIvendor\fR) that defines the event. Events defined by
third-party software should specify the company's stock symbol as \fIvendor\fR.
Sun-defined events use \fBSUNW\fR.
.RE

.SH OPERANDS

.LP
The \fBadd\fR, \fBlist\fR and \fBremove\fR subcommands support the following
options:
.sp
.ne 2
.na
\fB\fIargs\fR\fR
.ad
.RS 8n
Command arguments
.RE

.sp
.ne 2
.na
\fB\fIpath\fR\fR
.ad
.RS 8n
Full path of command to be run in response to event
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRAdding an Event Handler
.sp
.LP
The following example adds an event handler for an event defined by vendor
\fBMYCO\fR ("My Company"), class \fBEC_ENV\fR and sub-class \fBESC_ENV_TEMP\fR.
The command to be run is \fB/opt/MYCOenv/bin/ec_env_temp\fR, with arguments
being the class name, sub-class name and pathname derived from the event
attributes. The \fB$\fR characters are preceded by a backslash to circumvent
shell interpretation. There is no need to restart the service after the change
since the registry is maintained on \fB$ALTROOT\fR.

.sp
.in +2
.nf
# syseventadm add -R $ALTROOT -v MYCO -c EC_ENV -s ESC_ENV_TEMP \e
     /opt/MYCOenv/bin/ec_env_temp ${class} ${subclass} ${pathname}
.fi
.in -2
.sp

.sp
.LP
Note the caveat on the use of the \fB-R\fR option in the description of that
option, above.

.LP
\fBExample 2 \fRRemoving an Event Handler
.sp
.LP
The following example removes the event handler added in Example 1.

.sp
.in +2
.nf
# syseventadm remove -R $ALTROOT -v MYCO -c EC_ENV -s ESC_ENV_TEMP \e
     /opt/MYCOenv/bin/ec_env_temp ${class} ${subclass} ${pathname}
.fi
.in -2
.sp

.sp
.LP
Note the caveat on the use of the \fB-R\fR option in the description of that
option, above.

.LP
\fBExample 3 \fRListing Event Handlers
.sp
.LP
The following example lists all event handlers for events of class
\fBEC_ENV\fR, subclass \fBESC_ENV_TEMP\fR, as defined by vendor \fBMYCO\fR:

.sp
.in +2
.nf
# syseventadm list -v MYCO -c EC_ENV -s ESC_ENV_TEMP \e
     vendor=MYCO class=EC_ENV subclass=ESC_ENV_TEMP \e
     /opt/MYCOenv/bin/ec_env_temp ${class} ${subclass} ${pathname}
.fi
.in -2
.sp

.LP
\fBExample 4 \fRListing Event Handlers
.sp
.LP
The following example lists all event handlers defined by vendor \fBVRTS\fR.

.sp
.in +2
.nf
# syseventadm list -v VRTS
.fi
.in -2
.sp

.LP
\fBExample 5 \fRRemoving Event Handlers
.sp
.LP
The following example removes all event handlers defined by vendor \fBVRTS\fR,
and restarts service.

.sp
.in +2
.nf
# syseventadm remove -v VRTS
# syseventadm restart
.fi
.in -2
.sp

.LP
\fBExample 6 \fRListing All Event Handlers Specified to Run a Command
.sp
.LP
The following example lists all event handlers specified to run the command
\fB/opt/MYCOenv/bin/ec_env_temp\fR:

.sp
.in +2
.nf
# syseventadm list /opt/MYCOenv/bin/ec_env_temp
.fi
.in -2
.sp

.LP
\fBExample 7 \fRRemoving Event Handlers and Restarting Service
.sp
.LP
The following example removes all event handlers specified to run the command
\fB/opt/MYCOenv/bin/ec_env_temp\fR, and restarts service:

.sp
.in +2
.nf
# syseventadm remove /opt/MYCOenv/bin/ec_env_temp
# syseventadm restart
.fi
.in -2
.sp

.SH EXIT STATUS

.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
No matching event specification found (remove or list commands only).
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.RS 5n
Incorrect command usage.
.RE

.sp
.ne 2
.na
\fB\fB3\fR\fR
.ad
.RS 5n
Permission denied.
.RE

.sp
.ne 2
.na
\fB\fB4\fR\fR
.ad
.RS 5n
Command failed.
.RE

.sp
.ne 2
.na
\fB\fB5\fR\fR
.ad
.RS 5n
Out of memory.
.RE

.SH SEE ALSO

.LP
.BR sysevent_post_event (3SYSEVENT),
.BR attributes (7),
.BR syseventd (8),
.BR ddi_log_sysevent (9F)
.SH NOTES

.LP
To avoid upgrade problems, packages delivering a sysevent event handler should
install the event handler by running \fBsyseventadm\fR from the package's
postinstall script. The event handler can then be removed by running
\fBsyseventadm\fR from the package's preremove script using the same arguments
as when added.