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)