"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 ==============================================================================
4
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.
9
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.
36
37 QUICK START GUIDE
38
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.
42
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.
46
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.
53
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.
58
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.
68
69 6) Start the Notifd service.
70
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.
73
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.
77
78
79 CONFIG FILE EXPLAINATIONS
80
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).
87
88 A simple contact for a user is as follows:
89 <contact type="email" info="temp.user@opennms.org"/>
90
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.
99
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.
106
107
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.
112
113
114 notifications.xml:
115 The notifications.xml file contains the following information
116
117 uei: an event uei
118
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.
122
123 destinationPath: who to contact and how to escalate (see
124 destinationPaths.xml)
125
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.
130
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.
141
142
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.
157
158
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".
175
176 Below is an example for sending emails via the mail command:
177
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>
194