unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



evmchannel.conf(4)					   evmchannel.conf(4)



NAME

  evmchannel.conf - EVM	channel	configuration file

SYNOPSIS

  path		   ch_path
  cleanup_time	   [[hh:]mm:]ss

  channel {
	  name	       ch_name
	  path	       ch_path
	  events       evt_class
	  fn_get       get_function [arguments]
	  fn_details   details_function	[arguments]
	  fn_explain   explain_function
	  fn_monitor   monitor_function
	  fn_cleanup   cleanup_function
	  mon_period   monitor_period
	  }

DESCRIPTION

  The term event channel describes any facility	used to	publish	or retrieve
  event	information.  It might refer to	any of the following:

    +  A simple	log file

    +  An event	management system

    +  A program that runs in order to obtain a	snapshot of status informa-
       tion

  The EVM channel configuration	file, evmchannel.conf, defines the available
  event	channels and the functions that	operate	on them.  The file is read
  by:

    +  The EVM channel manager,	/usr/sbin/evmchmgr, to identify	the available
       channels, and to	determine when to run monitoring and cleanup func-
       tions.

    +  The evmshow command, when it is invoked with the	-d or -x option, to
       identify	the channel to which each event	belongs, and the program that
       must be run to produce a	detailed view or an explanation	of the event

    +  The evmget server program, /usr/sbin/evmget_srv,	to identify the
       available channels and their event retrieval functions

  Refer	to the evmchmgr(8), evmshow(1) and evmget(1) reference pages for more
  information.

  The channel configuration file is a text file	containing keyword/value or
  keyword/group	pairs.	Values containing spaces must be enclosed in double
  quotes.

  Any portion of a line	from an	unquoted number	sign (#) to the	end of line
  is a comment.	 Blank lines are ignored.


  The following	keywords are recognized:

  path ch_path
      The ch_path variable specifies a default directory containing execut-
      able programs that perform the various channel functions.	 This path
      may be overridden	by a ch_path variable specified	for an individual
      event channel.  The syntax for a global path and a channel specific
      path are the same.

  cleanup_time[[hh:]mm:]ss
      The time of day when the EVM channel manager executes the	channel
      cleanup function,	specified by the fn_cleanup keyword, for each chan-
      nel.  If no cleanup time is specified, the default is 2:00 a.m. (0200)
      local time.  The channel manager executes	cleanup	functions sequen-
      tially.

  channel
      The channel keyword introduces a channel definition.  The	configuration
      keywords and values for each channel must	be enclosed in braces.	There
      is no limit to the number	of channel definitions that can	be included
      in the file.

  name ch_name
      Specifies	a name to be associated	with the event channel.	 The name can
      include any printable character.

  events evt_class
      The class	of events associated with this channel.	 The evt_class is a
      dot delimited field with the same	syntax as an event name.

      When evmshow is run with the -d or -x option, it must find an event
      channel matching each event it receives, so that it can determine	which
      channel function to run.	The program scans the evt_class	value of each
      configured channel in turn, in the order in which	they appear in the
      configuration file, searching for	a class	that exactly matches the
      first few	components of the event's name.	 It stops searching when it
      finds the	first matching channel,	and does not attempt to	find a better
      match.

      If a star	(*) is supplied	as the evt_class the channel is	regarded as
      the default channel, meaning that	its functions will be invoked to pro-
      vide details and explanations for	any events whose names do not match
      the evt_class for	any other channel.  The	default	channel	should be
      specified	as the last channel in the file, since no further searching
      takes place once this channel has	been found.

  fn_get get_function [arguments]
      The get_function parameter identifies an executable program that is
      invoked by the evmget server program each	time evmget is run.  The
      server executes the get_functions	for each channel in turn, in the
      order in which the channels appear in the	configuration file.  If	the
      fn_get keyword is	omitted	from a channel definition, no events are
      retrieved	for that channel.

      A	get_function program must return a stream of zero or more EVM events
      to its stdout, directing any error messages to stderr for	display	on
      evmget's error stream.  The program is executed as specified in the
      configuration line, including any	arguments, but must accept an
      optional -f option and a filter string as	trailing arguments.  If	a
      filter is	supplied, the program must return only events that match the
      filter.  See EvmFilter(5)	for more information about filters.

  fn_details details_function [arguments]
      When evmshow is invoked with the -d option, for each event it receives
      it searches the configured channels for one whose	evt_class matches the
      event's name, and	then executes the program defined as the channel's
      details_function.	 The program should output lines of text giving	a
      detailed view of the contents of the event.

      If the fn_details	keyword	is omitted from	a channel definition, evmshow
      -d produces a formatted dump of any events it receives that belong to
      the channel.

      A	details_function program must accept EVM events	on stdin, and output
      text to stdout.  Error messages must be directed to stderr, for display
      on evmshow's error stream.  The program is executed as specified on the
      configuration line, including any	arguments.

  fn_explain explain_function
      When evmshow is invoked with the -x option, for each event it receives,
      it searches the configured channels for one whose	evt_class matches the
      event's name, and	then executes the program defined as the channel's
      explain_function.	 The program should output lines of text explaining
      the meaning of the event and, if appropriate, any	necessary action.
      Error messages may be written to stderr, for display by on evmshow's
      error stream.

      If the fn_explain	keyword	is omitted from	a channel definition, evmshow
      -x displays a message in place of	an explanation for any events it
      receives that belong to the channel.

      An explain_function program must support the following command syntax:

      my_events_explain	event_name[reference]



      event-name
	  The event's name.

      reference
	  The event's ref data item, if	it has one.  This value	is intended
	  to be	used in	conjunction with the event name	to retrieve the
	  explanation for the event from a database of explanation text.

      Refer to the EvmEvent(5) reference page for more information about an
      event's name and ref data	items.

  fn_monitor monitor_function
      The monitor function provides a mechanism	for monitoring the status of
      a	channel	and posting events as necessary.

      When the EVM Channel Manager (evmchmgr) is started by the	EVM daemon,
      it searches the channel configuration file for channels that define a
      monitor_function program,	and runs each one with the value init as an
      argument.	 The channel manager executes each program periodically
      thereafter, with no arguments, at	the frequency defined by the
      channel's	monitor_period value.  The program should use the presence or
      absence of the init argument to decide whether it	must perform any ini-
      tialization work.

      The purpose of the monitor program is generally to check status and to
      post events if it	detects	a significant change of	state, although	it is
      not restricted to	this type of activity.	The program should not write
      to stdout	or stderr, and,	since the channel manager waits	for its	com-
      pletion before it	can start its next action, the program should keep
      its execution time as short as possible.

      A	monitor_function program must support the following command syntax:

      my_events_monitor	[init]

      If the fn_monitor	keyword	is omitted from	a channel definition, no mon-
      itoring function is run on behalf	of that	channel.

  fn_cleanup cleanup_function
      The cleanup_function identifies an executable program that is invoked
      daily by the EVM Channel Manager at the time specified by	cleanup_time.

      The purpose of the cleanup program is generally to archive or purge old
      log information, although	it is not restricted to	this type of
      activity.	 The program should not	write to stdout	or stderr, and,	since
      the channel manager waits	for its	completion before it can start its
      next action, the program should keep its execution time as short as
      possible.

      The channel manager executes the cleanup command as specified in the
      configuration line, and does not supply additional arguments.

      If the fn_cleanup	keyword	is omitted from	a channel definition, no
      cleanup function is run on behalf	of that	channel.

  mon_period monitor_period
      The monitor_period value determines the frequency	at which the monitor
      function will be run for a particular channel.  It has the following
      syntax:

      [[[[days:]hours:]minutes:]seconds]

      All fields are optional, but the appropriate number of colon characters
      (:) must be included in order to specify the higher-order	components,
      for example, 1: would be interpreted as 1	minute and zero	seconds. Each
      of the four components can have a	value up to 9999.  It is acceptable
      to exceed	the natural limit for any component, regardless	of what	other
      components are included: for example, 90 is interpreted as 90 seconds,
      and 1:90 is interpreted as 150 seconds.

  Each ch_path specified may be	either relative	or absolute. The path is
  prepended to each function specified unless the function specifier is	abso-
  lute (begins with a slash).  If the function specifier is not	absolute,
  then standard	search rules are applied to find the executable	file.

  The keywords described may be	entered	in any mix of upper- and lower-case
  characters.  The allowable strings and the minimum number of characters is
  shown	in the following table.	 A minimum of zero (0) indicates that all
  characters are required.

  ______________________
  Keyword	 Minimum
  ______________________
  channel	 4
  cleanup_time	 0
  events	 5
  fn_cleanup	 8
  fn_details	 0
  fn_explain	 6
  fn_get	 0
  fn_monitor	 6
  mon_period	 0
  name		 0
  path		 0
  ______________________







NOTES

  If you are concerned with allowing your file to be used on other systems
  that support EVM in the future, you should use the built-in macro @SYS_VP@
  in place of the first	two components (sys.unix) of the name of any system
  event.  This will make it unnecessary	to change the file if the other	sys-
  tem uses a different event name prefix.

EXAMPLES

  The following	is an example of a channel configuration file:

       cleanup_time 03:00:00

       channel {
	   name	       my_events
	   path	       /var/evm/adm/channels/my_events
	   events      myco.myapp.my_events
	   fn_get      "my_events_get -r 8"
	   fn_details  my_events_details
	   fn_explain  my_events_explain
	   fn_monitor  my_events_monitor
	   fn_cleanup  "my_events_cleanup 7 31"
	   mon_period  15:0
       }

  The channel configuration file does the following:

   1.  The cleanup program for this and	all other defined channels will	be
       run at 3:00 a.m.	each day.

   2.  The event channel has the name my_events.

   3.  All channel functions are found in a directory named
       /var/evm/adm/channels/my_events.

   4.  This channel applies to events having myco.myapp.my_events as the
       first three components of their names.

   5.  Whenever	evmget is run, the program
       /var/evm/adm/channels/my_events/my_events_get is	invoked	to retrieve
       events of this class.  The arguments -r 8 are passed to the program
       each time it is executed	- these	arguments may be followed by -f	and a
       filter string.

   6.  Whenever	the command evmshow -d encounters an event in this class, the
       program /var/evm/adm/channels/my_events/my_events_details is invoked
       to provide the detailed description.

   7.  Whenever	the command evmshow -x encounters an explanation for an	event
       in this class, the program
       /var/evm/adm/channels/my_events/my_events_explain is invoked to pro-
       vide the	explanation.

   8.  The program /var/evm/adm/channels/my_events/my_events_cleanup is	run
       daily at	3:00 a.m.  The arguments 7 and 31 are passed to	the program
       each time it is executed.

   9.  The channel manager invokes the function
       /var/evm/adm/channels/my_events/my_events_monitor on startup (with the
       init parameter) and every 15 minutes thereafter.





FILES

  /etc/evmchannel.conf
      Location of the EVM channel configuration	file.

SEE ALSO

  Commands: evmget(1), evmshow(1), evmchmgr(8),	evmd(8)

  Files: evmdaemon.conf(4), evmlogger.conf(4)

  Event	Management: EVM(5)

  Event	Filter:	EvmFilter(5)