--- /dev/null
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <meta name="GENERATOR" content="Mozilla/4.61 [en] (X11; U; Linux 2.2.12-20 i686) [Netscape]">
+ <title>spong.hosts</title>
+</head>
+<body>
+
+<hr>
+<h1>
+<a NAME="spong.hosts_name_0"></a>NAME</h1>
+<b>spong.message</b> - define rules on how and when to send messages
+<p>
+<hr>
+<h1>
+<a NAME="spong.hosts_description_0"></a>DESCRIPTION</h1>
+The spong.message file defines the rules that spong-messge program used
+for notifications. The rules consist of attributes which define crieria
+which events are matched against and a list of contacts to notifiy if all
+of the matching criteria are met.
+<p>Each rule should have more of more of the following matching criteria
+attributes:
+<pre> * hosts a list of hosts to match
+
+ * services a list of services to match
+
+ * exclude_hosts a list of hosts to exclude
+
+ * exclude_services a list of services to exclude
+
+ * times a list of days/times to match</pre>
+And each rule must have the following attributes:
+<pre> * contacts a list of contacts to notify</pre>
+The hosts are a list of host names that are matched against the host name
+parameter passed to spong-message.
+<p>The services are a list of services that are matched against the service
+parameter passwd to spong-message.
+<p>The exclude_hosts are a list of host names that are be excluded from
+matching the rule.
+<p>The exclude_services are a list of services that are to be excluded
+from matching the rule.
+<p>The times are a list of stanzas the have days of the week and/or time
+ranges to match against the time parameter passed to spong-message. Each
+times stanza can have a days and/or a times attribute which are lists of
+days and times ranges to be matched.
+<p>The days attribute are a list of strings with the following format -
+'d' or 'd-d'. Where d is the day of the where (0-6, 0=Sunday, 6=Staurday).
+And 'd-'d represents a range of days (i.e. 1-5 = Monday - Friday).
+<p>The times attribute are a list of string with the following format -
+'hh:mm-hh:mm'. This is a starting and ending time of a time range in 24
+hour format.
+<p>Each of the elements of the hosts, services, exclude_hosts, and exclude_services
+are actually Perl regular expressions. You can use wide cards to specify
+who groups of hosts or services to match.
+<p>The down attribute is a list of ``downtimes''. It is a list (well reference
+to one anyway) of one or more strings in the following format - ``d:hh:mm-hh:mm''.
+``d'' is the day of the week (0-6, 0 = Sunday, 6 = Saturday), if ``d''
+is ``*'', then every day of the week is matched. The string to the right
+of the day is the start and end time of the down time in 24 hour format
+<p>The contacts is a list of stanzas representing the contacts to notify
+if the all of the rules' matching criteria are met. Each stanza can be
+a string or a contact stanza. The strings can be one of the following
+formats - 'human' or 'human:func' where human is a strings represent an
+entry from the %HUMANS defined in <a href="spong_hosts.html#humans">spong.hosts</a>
+and func is one of the message functions attributes defined for that human.
+<p>A contact stanza can must have a rcpt attribute which is a strings are
+defined above. It can optiionally can have a delay and/or a repeat attributes.
+The delay attribute is the duration, in seconds, that an event must have
+before the rcpt is notified. The repeat is the time interval, in seconds,
+in which notifications are resent once an initial notification is sent.
+<p>
+<hr>
+<h1>
+<a NAME="spong.hosts_format_0"></a>FORMAT</h1>
+The spong.message file is simply Perl code that gets imported by each spong
+program, so the only real format restrictions is just what is syntactically
+correct in Perl (which some would say is anything 8-).
+<p>What is expected in this file are the definition for the $<b>MESSAGING_RULES,</b>
+and <b>$RULES_MATCH</b> which determines how the rules are processed..
+If you are not comfortable with Perl lingo, then just think of them as
+stanza definitions.
+<pre> $MESSAGING_RULES = [ [stanza], [stanza], [stanza] ];</pre>
+where [stanza] is a second hash, that looks like the following:
+<pre> { hosts => [ 'unixweb', '.*-ops.cic.myschool.edu', 'steves-pc' ]
+
+ services => [ '.*' ],
+
+ exclude_hosts => [ 'backup-ops.cic.myschool.edu'],
+
+ exclude_services => [ 'dns', 'ssh'],
+
+ times => [
+ {
+ days=> ['0','1-3','4-5'],
+ times=> ['06:30-18:30','21:00-22:00'
+ },
+ { days => ['5','6','0-2'] },
+ { times => ['13:00-15:23','00:00-23:39'] },
+ ],
+
+ contacts => [ 'ops', 'sjohnson:email',
+ { rcpt=>'sjohnson:teletouch', delay=>900, repeat=>600 },
+ { rcpt=>'the_supervisor:teletouch',
+ delay=3600, repeat=>1800 },
+ { rcpt=>'the_boss', delay=>7200, repeat=>3600 },
+ ],
+ },</pre>
+The <b>$RULES_MATCH</b> variable has three possible values: <b>OLD</b>
+- Use Spong ver 2.1 messaging. Send notification the human defined in the
+contact attibute for the host name of the message. <b>FIRST-MATCH</b> -
+Rules are checked in order until the first one that matches. <b>ALL</b>
+- Rules are checked into order. All rules that match are processed.
+<p>I know the format can be a little odd at first, but I chose it because
+of both its simplicity to work with in the code (I don't have to parse
+anything - Perl does all the work), and because it is easy to extend -
+adding additional attributes is quite straightforward.
+<br>
+<hr WIDTH="100%">
+<h1>
+<a NAME="logic"></a>MATCHING LOGIC</h1>
+The primary factor of how spong.message rules are processed depends upon
+the vaule of <b>$RULES_MATCH.</b> If set to 'OLD' then the
+rules are not used at all. <b><a href="spong-message.html">spong-message</a></b>
+reverts back to it Spong version 2.1 behaviour. Notify the human defined
+in the contact attribute of the <b>%HOSTS</b> entry for the host. If set
+to 'FIRST-MATCH' then the rules are check in order until the first rule
+matching the event parameter is. spong-message will then begin notification
+processing. If <b>$RULES_MATCH</b> is set to 'ALL' then al of the rules
+are scan in order. The contacts of all matching rules are adding to the
+list of recipients that will be notified.
+<p>All of the matching attributes except for <b>exclude_hosts</b> and <b>exclude_services</b>
+have an automatic match if absent property. For example, if the <b>hosts</b>
+<br>attribute is missing from a rule, that rule will match any host name.
+The <b>exclude_hosts</b> and <b>exclude_services</b> have a slightly different
+matching behaviour man the other matching attributes, if there is a match
+against either of them, the rule will not match even if all of the other
+matching attreibute match. For example, if a rules has <b>hosts => [ '.*.cic.my-company',
+'.*.corp.my-company.com' ]</b> and <b>exclude_hosts[ 'my-pc' ]</b> , a
+host name of 'my-pc.corp.my-company.com' will not match against this rule
+because of the host name matches the <b>exclude_hosts</b> attribute
+<p>The <b>times</b> attribute's subattribues, <b>days</b> and <b>times</b>
+, have the automatic match if absent property. If one of the sub-attributes
+is missing from a stanza any check against that attribute will succeed.
+That is <b>days</b> is missing from the stanza, any day of the week will
+match againast the stanza. If the <b>times</b> sub-attribute is missing,
+the stanza matches against any time. A <b>times</b> attribute match
+succeeds if any stanza of the attribute matches.
+<p>
+<hr>
+<h1>
+<a NAME="spong.hosts_examples_0"></a>EXAMPLES</h1>
+Here are some lines from our spong.hosts file to show you possible configurations.
+<pre>$MESSAGING_RULES = [
+
+ # Franks Notifications
+ # Let him know about if it has been down for 30 minute or more.
+ {
+ hosts => [ '.*' ],
+ services => [ '.*' ],
+ contacts => [ {rcpt=>'fsipes', delay=>1800}, ],
+ exclude_hosts => ['tunixt'],
+ exclude_services => ['test'],
+ },
+
+ # Let Dwayne in Engineering know when a system does down and dns problems
+ # except for the test box
+ {
+ hosts => ['.*'],
+ services => ['ping','ftp','smtp','dns'],
+ exclude_hosts => ['tunixt'],
+ contacts => [ 'dstucker' ],
+ },
+
+ # Let me know about everything except the test box except late at
+ # night
+ {
+ hosts => ['.*'],
+ services => ['.*'],
+ exclude_services => ['nntp','ntp'],
+ exclude_hosts => ['tunixt'],
+ contacts => ['sjohnson'],
+ times => [
+ { times => ['06:00-21:00'] },
+ ],
+ },
+
+ # Notify the unix oncall pager about the k12 systems after hours
+ # during week days and anytime on the weekend and repeat them
+ # every 15 minutes until acknowledged
+ {
+ hosts => ['.*.k12.ar.us'],
+ services => ['.*'],
+ exclude_services => ['nntp','ntp'],
+ exclude_hosts => ['tunixt'],
+ contacts => [ { rcpt=>'unix-oncall:teletouch', repeat=>900}, ],
+ times => [
+ { days => ['1-5'], times => ['17:00-23:59','00:00-08:00'] },
+ { days => ['0','6'] },
+ ],
+ },
+
+ ];
+
+</pre>
+
+<hr WIDTH="100%">
+<h1>
+COMPATABILITY</h1>
+To use Spong version 2.1 message and messaging configurations set <b>$RULES_MATCH</b>
+to 'OLD'. If <b>$RULES_MATCH</b> is not defined it will default to 'OLD'.
+<br>
+<hr>
+<h1>
+<a NAME="spong.hosts_see_0"></a>SEE ALSO</h1>
+the
+<i>spong-message</i> manpage
+<p>
+<hr>
+<h1>
+<a NAME="spong.hosts_author_0"></a>AUTHOR</h1>
+Ed Hill (<a href="MAILTO:ed-hill@uiowa.edu">ed-hill@uiowa.edu</a>), Unix
+System Administrator, The University of Iowa
+<br>Stephen L Johnson (<a href="MAILTO:stephen.johnson@mail.state.ar.us">stephen.johnson@mail.state.ar.us</a>)
+or (<a href="MAILTO:sjohnson@monsters.org">sjohnson@monsters.org</a>),
+Unix System Administator, DIS - State of Arkansas
+<p>Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong).
+</body>
+</html>
projects / spong.git / commitdiff