From acb3b17f7473426b849691f3888ab86ac4d8639f Mon Sep 17 00:00:00 2001 From: Stephen L Johnson Date: Mon, 15 Nov 1999 04:30:09 +0000 Subject: [PATCH] Initial revision --- www/docs/spong_message.html | 229 ++++++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100755 www/docs/spong_message.html diff --git a/www/docs/spong_message.html b/www/docs/spong_message.html new file mode 100755 index 0000000..8884128 --- /dev/null +++ b/www/docs/spong_message.html @@ -0,0 +1,229 @@ + + + + + + spong.hosts + + + +

+NAME

+spong.message - define rules on how and when to send messages +

+DESCRIPTION

+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. +

Each rule should have more of more of the following matching criteria +attributes: +

    * 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

+And each rule must have the following attributes: +

    * contacts           a list of contacts to notify

+The hosts are a list of host names that are matched against the host name +parameter passed to spong-message. +

The services are a list of services that are matched against the service +parameter passwd to spong-message. +

The exclude_hosts are a list of host names that are be excluded from +matching the rule. +

The exclude_services are a list of services that are to be excluded +from matching the rule. +

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. +

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). +

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. +

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. +

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 +

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 spong.hosts +and func is one of the message functions attributes defined for that human. +

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. +

+FORMAT

+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-). +

What is expected in this file are the definition for the $MESSAGING_RULES, +and $RULES_MATCH which determines how the rules are processed.. +If you are not comfortable with Perl lingo, then just think of them as +stanza definitions. +

    $MESSAGING_RULES = [ [stanza], [stanza], [stanza] ];

+where [stanza] is a second hash, that looks like the following: +

    { 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 },
+                   ],
+    },

+The $RULES_MATCH variable has three possible values: OLD +- Use Spong ver 2.1 messaging. Send notification the human defined in the +contact attibute for the host name of the message. FIRST-MATCH - +Rules are checked in order until the first one that matches. ALL +- Rules are checked into order. All rules that match are processed. +

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. +
+

+MATCHING LOGIC

+The primary factor of how spong.message rules are processed depends upon +the vaule of $RULES_MATCH. If set to 'OLD' then the +rules are not used at all. spong-message +reverts back to it Spong version 2.1 behaviour. Notify the human defined +in the contact attribute of the %HOSTS 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 $RULES_MATCH 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. +

All of the matching attributes except for exclude_hosts and exclude_services +have an automatic match if absent property. For example, if the hosts +
attribute is missing from a rule, that rule will match any host name. +The exclude_hosts and exclude_services 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 hosts => [ '.*.cic.my-company', +'.*.corp.my-company.com' ] and exclude_hosts[ 'my-pc' ] , a +host name of 'my-pc.corp.my-company.com' will not match against this rule +because of the host name matches the exclude_hosts attribute +

The times attribute's subattribues, days and times +, 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 days is missing from the stanza, any day of the week will +match againast the stanza. If the times sub-attribute is missing, +the stanza matches against any time. A times attribute match +succeeds if any stanza of the attribute matches. +

+EXAMPLES

+Here are some lines from our spong.hosts file to show you possible configurations. +

$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'] },
+                        ],
+        },
+
+  ];
+
+

+ +

+COMPATABILITY

+To use Spong version 2.1 message and messaging configurations set $RULES_MATCH +to 'OLD'. If $RULES_MATCH is not defined it will default to 'OLD'. +
+

+SEE ALSO

+the +spong-message manpage +

+AUTHOR

+Ed Hill (ed-hill@uiowa.edu), Unix +System Administrator, The University of Iowa +
Stephen L Johnson (stephen.johnson@mail.state.ar.us) +or (sjohnson@monsters.org), +Unix System Administator, DIS - State of Arkansas +

Based on code/ideas from Sean MacGuire (BB), and Helen Harrison (Pong). + + -- 2.30.2