"Fossies" - the Fresh Open Source Software Archive

Member "opennms-31.0.8/README.notification" (9 May 2023, 9676 Bytes) of package /linux/misc/opennms-31.0.8-source.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 ==============================================================================
    2 Using The New Notification System For Fun And Profit
    3 ==============================================================================
    5 Here is an overview of how to configure and use the new Notification system.
    6 Configuration takes place in 5 xml files, users.xml, groups.xml,
    7 notifications.xml, destinationPaths.xml and notificationCommands.xml.  Use of
    8 each is explained below.
   10 TERMS:
   11 notification     - the act of contacting a user or group of users via some
   12                    contact medium
   13 notice           - a user/command instance
   14 destination path - a definition of what users or groups to contact, and when
   15                    to escalate if the page is not answered promptly
   16 target           - In destinationPaths.xml, a user or group to send a
   17                    notification to and the command to use to send that
   18                    notification.
   19 escalation       - similar to a target, but is delayed by a specified amount
   20                    of time
   21 path             - a named list of targets and escalations
   22 duty-schedule    - Indicates when a user is on duty.  Uses the first two
   23                    letters of each day, capitalizing the first and military
   24                    style timestamps.  (MoWeFr800-1700, TuTh900-1800)
   25 interval         - The time to wait between notifying users of a group
   26                    specified in the target tag of destinationPaths.xml.  The
   27                    time units are as follows:
   28                    ms - milliseconds
   29                    s  - seconds
   30                    m  - minutes
   31                    h  - hours
   32                    d  - days
   33 delay            - Specified in the same units as an interval, but indicates
   34                    the amount of time to wait before processing the targets of
   35                    an escalation, as specified in destinationPaths.xml.
   39 1)  Make sure there is at least one command listed in
   40     notificationCommands.xml.  If there aren't any copy the xml listed below
   41     under the explanation for notificationCommands.xml.
   43 2)  Enter at least one user in the users.xml.  This can be done via the admin
   44     interface of the Web UI.  If you want to send to a group then make an
   45     entry in groups.xml and add all desired users to the group.
   47 3)  Enter a <contact> for each user that will be contacted, with a type
   48     attribute that corresponds to a command listed in
   49     notificationCommands.xml.  Make sure the info attribute contains the
   50     correct information to contact the user via the command, i.e. if the
   51     "email" command is being used the set the info attribute to the user's
   52     email address.  This can be done via the admin interface of the Web UI.
   54 4)  Set up a destination path in destinationPaths.xml to indicate what user or
   55     group to contact.  Set the command attribute to the type attribute from
   56     notificationCommands.xml of the command you want to use.  If sending to a
   57     group set the desired interval between contacting group members.
   59 5)  Enter a UEI/Destination Path mapping in notifications.xml if there are
   60     none listed.  Typically the event
   61     "http://uei.opennms.org/nodes/nodeLostService" is
   62     notified on.  If you want to not notify based on devices enter the
   63     relevant rule (see the README.filters for how to write a rule).  Enter the
   64     destination path to use.  Enter a text message to send. This is applicable
   65     even if a numeric page is being sent, the text message will still be
   66     entered in the database.  Enter a subject if desired for an email message.
   67     Enter a numerical message if needed.
   69 6) Start the Notifd service.
   71 7)  Make sure that the status of notifications is set to on.  This can be done
   72     in the Web UI via the admin page.
   74 8)  Wait for a notice. If you think that a notice should have been delivered
   75     and one hasn't, double check the configuration and then check the
   76     notifd.log file (usually in /var/log/opennms) for any apparent errors.
   81 users.xml:
   82 This file holds the notification information for all users in the system.  In
   83 order for a user to actually receive a notice, there must be contact
   84 information listed in this config file (All notices will still be logged to
   85 the database, so if the information is missing or incorrect the database still
   86 has record of the notice).
   88 A simple contact for a user is as follows:
   89 <contact type="email" info="temp.user@opennms.org"/>
   91 The "type" attribute must match up to a type of command in the
   92 notificationCommands.xml (see below).  In this example, the type is "email",
   93 thus the "email" command will be used to send the notice to the user.  The
   94 "info" attribute will hold whatever information is needed to contact the user
   95 via the command that appears in "type", in this case its the email address.
   96 If a page was being sent the "info" attribute will probably hold the pin #.
   97 The "serviceProvider" attribute is optional, and can be used to indicate the
   98 service provider of the media being used for the notice.  
  100 The <duty-schedule> tag indicates when this user is "on duty" and able to
  101 receive notifications.  A notice will not be sent to this user if when the
  102 notice command is being run the user is listed as "off-duty".  If no duty
  103 schedules are listed for a user then the user is assumed to be "on duty" all
  104 the time.  A user can have more than one duty-schedule listed and they may
  105 overlap.
  108 groups.xml:
  109 This file holds a list of users associated with a group name. If Notifd is
  110 told to contact a group of users it will contact each of the users from the
  111 group in the order that they are listed.
  114 notifications.xml:
  115 The notifications.xml file contains the following information
  117    uei:              an event uei 
  119    rule:             a constraining filter that will try to match the
  120                      interface the event concerns.  If the interface falls in
  121                      the domain of the rule the notice will be sent.
  123    destinationPath:  who to contact and how to escalate (see
  124                      destinationPaths.xml)
  126    parameters:       information that needs to be sent via each notice to each
  127                      user expanded from the destination path.  This must
  128                      include the -tm parameter indicating what to tell the
  129                      user about the notice.
  131 When an event is found this file is searched to see if an entry exists for the
  132 uei, if there is one then a notification will be started.  The text of the
  133 message being sent is specified in this file as a parameter.  Any other
  134 information that needs to be included is also specified as a parameter.  Also,
  135 the nodeid, interface, and service from the event are checked against the
  136 rule.  If the interface is included in the result set of the rule the
  137 notification will be sent.  Each notification is named so that it can be
  138 referenced from the Web UI for configuration.  An single event uei may be
  139 associated with many notifications, but the first notification found that
  140 matches the rule will be used.
  143 destinationPaths.xml:
  144 This file defines how and when each user is contacted. It consists of three
  145 definitions, paths, targets and escalations.  A path is a named list of
  146 targets and escalations.  A target consists of a user or group to contact, the
  147 command to use to contact the user or group, and in the case of a group the
  148 amount of time to wait between contacting the members of the group can be
  149 specified.  If no interval is specified then all members of the group will be
  150 contacted at the same time.  The command is specified via a name that is used
  151 to search the <lookup> entries of a notification command (see
  152 notificationCommands.xml below).  More than one target can be specified, each
  153 target will start at the same time.  An escalation contains targets, but also
  154 specifies to wait a given amount of time prior to starting its targets.  Each
  155 target listed in an escalation will be started at the same time, after the
  156 specified delay has passed.
  159 notificationCommands.xml:
  160 This file contains the command line calls to the programs and scripts to
  161 actually send the notice to the users.  Each command is specified along with
  162 the arguments that need to be sent, along with directives as to what
  163 information needs to be pulled from the notification process.  The <name> tag
  164 indicates the command line call that will be made.  The <lookup> tags indicate
  165 how the destinationPath command attribute identifies what command to use.  The
  166 <argument> tags specify the arguments that need to be passed to the command.
  167 Each argument can specify a <switch> and <substitution>.  The <switch>
  168 indicates that information needs to be gathered from the notification process.
  169 The presence of a <substitution> tag will cause the substitution string to be
  170 placed into the command line before a switch.  If only the substitution or
  171 switch is specified then only that will appear in the command line.  If the
  172 streamed attribute of an argument is set to "true" then the information
  173 requested by the <switch> tag will be sent to the command line via an input
  174 stream.  The default on all arguments for this attribute is "false".
  176 Below is an example for sending emails via the mail command:
  178 <command type="email">
  179     <name>/bin/mail</name>
  180     <lookup>email</lookup>
  181     <lookup>mail</lookup>
  182     <comment>for sending email notifications</comment>
  183     <argument streamed="false">
  184       	<substitution>-s</substitution>
  185         <switch>-subject</switch>
  186     </argument>
  187 		<argument streamed="false">
  188   			<switch>-email</switch>
  189 		</argument>
  190 		<argument streamed="true">
  191   			<switch>-tm</switch>
  192     </argument>
  193 </command>