kcalarm(1M)kcalarm(1M)NAMEkcalarm - add, delete, or list kernel tunable alarms, as well as turn
kernel tunable monitoring on and off.
SYNOPSISkcalarm threshold <event> interval comment <notification> tunable [tun‐
able...
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]
DESCRIPTIONkcalarm 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 sup‐
ported kernel tunables and enables graphs in the kcweb(1M) tool. Moni‐
toring 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 notification 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 speci‐
fied 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 specified.
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 spec‐
ified threshold (this can lead to a large
number of messages if the polling inter‐
val 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 min‐
utes 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 Open‐
View/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 applica‐
tion 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 his‐
torical 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 notifi‐
cation 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
notification 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 ALSOkcweb(1M), kcusage(1M), kcmond(1M)ems(5)kcalarm(1M)
