kcalarm(1M)															       kcalarm(1M)

NAME
kcalarm - add, delete, or list kernel tunable alarms, as well as turn kernel tunable monitoring on and off. SYNOPSIS
kcalarm threshold <event> interval comment <notification> tunable [tunable... kcalarm threshold <event> interval comment <notification> key tunable [tunable... kcalarm (on | off threshold <event> interval comment <notification> key tunable [tunable... kcalarm ] key [tunable... kcalarm (on |off | status <event> = (initial | repeat | return <notification> = notification_target:[data]:[port] DESCRIPTION
kcalarm is used to manage kernel tunable alarms and monitors; alarms and monitors are implemented in the kcmond(1M) daemon. Users can cre- ate, modify, delete, and list kernel tunable alarms. Alarms send a notification though various notification targets when a kernel tunable crosses a specified percentage threshold of its current setting. Monitoring is the process of collecting historical tunable data. When this feature is turned on, historical data is collected on the usage of supported tunables. This data is used by the kcusage (see kcusage(1M)) command to generate usage tables (including top consumers) for supported kernel tunables and enables graphs in the kcweb(1M) tool. Monitoring is turned on by default when the Kernel Configuration (kcweb) tool is installed. Root permissions are required to execute kcalarm when the -a, -d, -s, and -m (on|off) options are specified. Operands recognizes the following operands tunable Name of the kernel tunable. See kcusage(1M) for a list of tunables that can be monitored. If the token "any" is used as the tunable, an alarm is created that monitors all monitorable tunables, except dbc_max_pct and ninode; this alarm sends notifi- cation if any of them exceed the specified threshold. The list of valid tunables can be found on the kcusage(1M) manpage. If no options are provided, the kcalarm will list alarms for the specified tunable(s), or for all tunables if none are specified. Options recognizes the following options Add a kernel tunable alarm for the specified tunable(s). Separate alarms will be added for each tunable named with the -a option. The -a option should be used with the -n option, and with -t, -e and -i if values other than the defaults are desired. Delete a kernel tunable alarm for the specified tunable(s). If multiple alarms exist for a single tunable, -k, -t, -e, -i, and -n options can be used to clarify the delete request. The command will interactively confirm each delete request unless the -F (force) option is spec- ified. Force the deletion or change of status of an alarm, without confirming the request. This option is only valid with -d and -s options. This is a percentage of the current setting of the kernel tunable over which the alarm should sound (i.e 75 indicates 75 percent of the value of the current setting). The default is 80 percent. Only whole numbers are allowed. (initial|repeat|return) Event type. This determines what type of event will trigger a notification when the threshold is crossed. The three options are initial, repeat, and return. initial sends a notification from the first polling, and each time the threshold is exceeded (once per set of polls when the tunable exceeds the threshold). repeat sends a notification any time the tunable is polled and its value exceeds the specified threshold (this can lead to a large number of messages if the polling interval is small). return sends a notification at the first polling at which resource usage falls below threshold after exceeding it. The -e option can be specified multiple times to provide combinations of initial, repeat, and return. If no -e is provided with the -a option, the alarm will be added with the initial event type by default. This specifies how often the tunable data will be sampled (in minutes). If no interval is specified with the -a option, an interval of 5 minutes will be used by default. This is a user provided string to help identify the alarm request. This text is included in notifications. The comment is empty by default. Unique key used to disambiguate alarms from each other. Can be used with -s, -d and when listing. The value of the key is displayed when listing with the -l (long) option. Notification target if an alarm is triggered, where notification is a colon separated string (in quotes if it contains any spaces) in the form notification_target:[data]:[port]. The kcalarm command uses the Event Monitoring Service (EMS) infrastructure, and therefore supports any of the notification targets supported by EMS (see ems(5)). Valid choices are: opcmsg:(normal|warning|minor|major|critical): This option can be used with OpenView/IT/Operations notifications. (tcp|udp):host:port This option is used for any application that accepts these protocols and follows the rules defined in the EMS Developer's Kit. snmp:(normal|warning|minor|major|critical): This option can be used with any application that accepts SNMP traps, such as OpenView NNM, or IT/O. The application must be setup to recognize the SNMP traps generated. email:address: This option causes an email to be sent to the specified address when an alarm is triggered. If a comment is provided, it will be included in the body of the email message. syslog:: This option causes notifications to be written to syslog on the local system. If a comment is provided, it will be included in the syslog entry. textlog:filename: This option causes notifications to be written to the specified filename on the local system. If a comment is provided, it will be included in the textlog entry. console:: This option causes notifications to be written to the system console on the local system. If a comment is provided, it will be included. Long listing in machine readable format. By default output is in human readable format. Note that output will not be localized when the -l option is specified. Set the status of an alarm for the specified tunable(s), either on or off. This option allows temporarily disabling alarms without deleting them. If multiple alarms exist for a given tunable, -k, -t, -e, -i, and -n options can be used to clarify the on/off request. Turn kernel tunable monitoring on, off, or check the present status. This option is on by default when the Kernel Configuration tool is installed. This option must be on in order for kcusage to generate tables of historical tunable usage. Turning monitoring off will disable the features kcusage and kcweb that depend on the availability of historical data. RETURN VALUE
Upon completion, kcalarm returns one of the following values: Successful. Command failed, see STDERR for specifics. EXAMPLES
Add an alarm that monitors all kernel tunables, which will send notification to admin@corp.com if any kernel tunable resource exceeds 90% of the tunable's current setting. Default values for event type and polling interval will be used. kcalarm -a -t 90 -n email:admin@corp.com: any Add an alarm for the nproc kernel tunable with a threshold of 65%, repeat event type, polling interval of five minutes, with an email noti- fication target of admin@corp.com. kcalarm -a -t 65 -e repeat -i 5 -n email:admin@corp.com: nproc Delete the alarm added in the above example. The kcalarm command will confirm this request since the -F wasn't specified. kcalarm -d -t 65 -e repeat -i 5 -n email:admin@corp.com: nproc Force the deletion of ALL nproc alarms. kcalarm -d -F nproc List all of the alarms for the max_thread_proc kernel tunable. kcalarm max_thread_proc Turn off kernel tunable monitoring. kcalarm -m off AUTHORS
was developed by Hewlett-Packard. FILES
Log file for EMS clients, including kcalarm. Any errors are logged here. SEE ALSO
kcweb(1M), kcusage(1M), kcmond(1M) ems(5) kcalarm(1M)