SYSEVENTADM(8) Maintenance Commands and Procedures SYSEVENTADM(8)

NAME

syseventadm - sysevent event specification administration

SYNOPSIS

syseventadm add [-R rootdir] [-v vendor] [-p publisher]
[-c class] [-s subclass] [-u username] path [args]


syseventadm remove [-R rootdir] [-v vendor] [-p publisher]
[-c class] [-s subclass] [-u username] [path [args]]


syseventadm list [-R rootdir] [-v vendor] [-p publisher]
[-c class] [-s subclass] [-u username] [path [args]]


syseventadm restart

DESCRIPTION

The syseventadm command is an administrative front-end to add, remove
and list sysevent event handlers. You can also restart the sysevent
daemon by use of the restart command. syseventadm can only be run by
root.


The syseventadm add command adds a handler for a sysevent event
specified by at least one of vendor, publisher or class. If class is
specified, it may be qualified with a sub-class. Only the values
specified for vendor, publisher, class and sub-class when adding the
handler are matched against sysevent events to determine if the
specification matches the event and the handler should be run. path
is the full pathname of the command to be run in response to matching
events, with optional arguments (args). If username is specified, the
command is invoked as user username, otherwise as root.


The syseventadm remove command removes handlers for matching sysevent
event specifications. Event specifications may be matched by
specifying at least one of vendor, publisher, class, username or
path. If class is specified, it may be qualified with a sub-class.
Any of vendor, publisher, class, sub-class, username, path or args
not specified match the corresponding fields of all events. Handlers
for all matching specifications are removed.


The syseventadm list command lists the handlers for matching sysevent
event specifications using the same match criteria as the remove
command but without the requirement that at least one of vendor,
publisher, class, username or path be specified. With no match
criteria, all specifications are listed. The list command output
format is: [vendor=vendor] [publisher=publisher] [class=class]
[subclass=subclass] [username=username] path [args] where each of
class, sub-class, vendor, publisher and username is listed only if
part of the match criteria for the listed specification.


The syseventadm restart command informs the syseventd daemon to
reread the sysevent registry after a change has been made by adding
or removing one or more sysevent handler specifications.

Argument Macro Substitution

The sysevent 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 args specified for an event handler, with macros expanded with
data from the event itself. Pre-defined macros are provided for the
event class, subclass, publisher and vendor 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.


Macros are introduced by the $ 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 ${ and }. A \
before the $ causes macro expansion not to occur.

$class
The class string defining the event


$publisher
The publisher string defining the event


$sequence
The sequence number of the event.


$subclass
The subclass string defining the event


$timestamp
The timestamp of the event.


$vendor
The vendor string defining the event


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 ASCII text on the generated command line.


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.


Attributes with signed data types (DATA_TYPE_INT16, DATA_TYPE_INT32
and DATA_TYPE_INT64) are expanded as decimal digits.


Attributes with unsigned data types (DATA_TYPE_BYTE,
DATA_TYPE_UINT16, DATA_TYPE_UINT32, DATA_TYPE_UINT64 and
DATA_TYPE_HTTIME) are expanded as hexadecimal digits with a 0x
prefix.


Attributes with string data type (DATA_TYPE_STRING) 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.


Array types are expanded with each element expanded as defined for
that scalar type, with a space separating each element substitution.

OPTIONS

The add, list and remove subcommands support the following options:

-c class
Specify the event class, class.


-p publisher
Specify the event publisher, publisher.


-R rootdir
Specify an alternate root path, rootdir.

Note -

The root file system of any non-global zones must
not be referenced with the -R 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
zones(7).


-s subclass
Specify the event subclass, subclass.


-u username
Specify the username (username) to invoke the
command.


-v vendor
Specify the vendor (vendor) that defines the event.
Events defined by third-party software should specify
the company's stock symbol as vendor. Sun-defined
events use SUNW.

OPERANDS

The add, list and remove subcommands support the following options:

args
Command arguments


path
Full path of command to be run in response to event

EXAMPLES

Example 1: Adding an Event Handler

The following example adds an event handler for an event defined by
vendor MYCO ("My Company"), class EC_ENV and sub-class ESC_ENV_TEMP.
The command to be run is /opt/MYCOenv/bin/ec_env_temp, with arguments
being the class name, sub-class name and pathname derived from the
event attributes. The $ 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
$ALTROOT.


# syseventadm add -R $ALTROOT -v MYCO -c EC_ENV -s ESC_ENV_TEMP \
/opt/MYCOenv/bin/ec_env_temp ${class} ${subclass} ${pathname}


Note the caveat on the use of the -R option in the description of
that option, above.

Example 2: Removing an Event Handler

The following example removes the event handler added in Example 1.


# syseventadm remove -R $ALTROOT -v MYCO -c EC_ENV -s ESC_ENV_TEMP \
/opt/MYCOenv/bin/ec_env_temp ${class} ${subclass} ${pathname}


Note the caveat on the use of the -R option in the description of
that option, above.

Example 3: Listing Event Handlers

The following example lists all event handlers for events of class
EC_ENV, subclass ESC_ENV_TEMP, as defined by vendor MYCO:


# syseventadm list -v MYCO -c EC_ENV -s ESC_ENV_TEMP \
vendor=MYCO class=EC_ENV subclass=ESC_ENV_TEMP \
/opt/MYCOenv/bin/ec_env_temp ${class} ${subclass} ${pathname}

Example 4: Listing Event Handlers

The following example lists all event handlers defined by vendor
VRTS.


# syseventadm list -v VRTS

Example 5: Removing Event Handlers

The following example removes all event handlers defined by vendor
VRTS, and restarts service.


# syseventadm remove -v VRTS
# syseventadm restart

Example 6: Listing All Event Handlers Specified to Run a Command

The following example lists all event handlers specified to run the
command /opt/MYCOenv/bin/ec_env_temp:


# syseventadm list /opt/MYCOenv/bin/ec_env_temp

Example 7: Removing Event Handlers and Restarting Service

The following example removes all event handlers specified to run the
command /opt/MYCOenv/bin/ec_env_temp, and restarts service:


# syseventadm remove /opt/MYCOenv/bin/ec_env_temp
# syseventadm restart

EXIT STATUS

The following exit values are returned:

0
Successful completion.


1
No matching event specification found (remove or list commands
only).


2
Incorrect command usage.


3
Permission denied.


4
Command failed.


5
Out of memory.

SEE ALSO

sysevent_post_event(3SYSEVENT), attributes(7), syseventd(8),
ddi_log_sysevent(9F)

NOTES

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

September 28, 2005 SYSEVENTADM(8)