6789a37d43289fcfdf81fedccefaceb542f4ff1b
[sip-router] / modules / snmpstats / doc / snmpstats_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13         
14         <title>&adminguide;</title>
15         
16         <section>
17                 <title>Overview</title>
18
19                 <para>The SNMPStats module provides an SNMP management interface
20                 to Kamailio.  Specifically, it provides general SNMP queryable 
21                 scalar statistics, table representations of more complicated data such as 
22                 user and contact information, and alarm monitoring capabilities.
23                 </para>
24                 <para>
25                 The MIB has been renamed in version 4.0.0 to reflect the product name. Please
26                 note that all the OID names has changed, as well as the MIB itself.
27                 </para>
28                 <section>
29                         <title>General Scalar Statistics</title>
30                         <para>
31                         The SNMPStats module provides a number of general scalar statistics.  
32                         Details are available in KAMAILIO-MIB, KAMAILIO-REG-MIB, 
33                         KAMAILIO-SIP-COMMON-MIB, and KAMAILIO-SIP-SERVER-MIB.  But briefly, 
34                         these scalars are:
35                         </para>
36                         <para>
37                         kamailioSIPProtocolVersion, kamailioSIPServiceStartTime, kamailioSIPEntityType,
38                         kamailioSIPSummaryInRequests, kamailioSIPSummaryOutRequest, 
39                         kamailioSIPSummaryInResponses, kamailioSIPSummaryOutResponses,
40                         kamailioSIPSummaryTotalTransactions, kamailioSIPCurrentTransactions, 
41                         kamailioSIPNumUnsupportedUris, kamailioSIPNumUnsupportedMethods, 
42                         kamailioSIPOtherwiseDiscardedMsgs, kamailioSIPProxyStatefulness
43                         kamailioSIPProxyRecordRoute, kamailioSIPProxyAuthMethod, 
44                         kamailioSIPNumProxyRequireFailures, kamailioSIPRegMaxContactExpiryDuration,
45                         kamailioSIPRegMaxUsers, kamailioSIPRegCurrentUsers, 
46                         kamailioSIPRegDfltRegActiveInterval, kamailioSIPRegAcceptedRegistrations,
47                         kamailioSIPRegRejectedRegistrations, kamailioMsgQueueDepth.
48                         kamailioCurNumDialogs, kamailioCurNumDialogsInProgress, 
49                         kamailioCurNumDialogsInSetup, kamailioTotalNumFailedDialogSetups
50                         </para>
51                         <para>
52                         There are also scalars associated with alarms.  They are as follows:
53                         </para>
54
55                         <para>
56                         kamailioMsgQueueMinorThreshold, kamailioMsgQueueMajorThreshold,
57                         kamailioMsgQueueDepthAlarmStatus, kamailioMsgQueueDepthMinorAlarm,
58                         kamailioMsgQueueDepthMajorAlarm, kamailioDialogLimitMinorThreshold,
59                         kamailioDialogLimitMajorThreshold, kamailioDialogUsageState,
60                         kamailioDialogLimitAlarmStatus, kamailioDialogLimitMinorAlarm,
61                         kamailioDialogLimitMajorAlarm
62                         </para>
63                         <para>
64                         In Kamailio 4.1 a set of new OIDs was added to reflect the
65                         &kamailio; configuration, the version, core status (memory, connections),
66                         transports and module data.
67                         </para>
68                 </section>
69                 <section>
70                         <title>SNMP Tables</title>
71                         <para>
72                         The SNMPStats module provides several tables, containing more complicated
73                         data.  The current available tables are:
74                         </para>
75
76                         <para>
77                         kamailioSIPPortTable, kamailioSIPMethodSupportedTable, 
78                         kamailioSIPStatusCodesTable, kamailioSIPRegUserTable, kamailioSIPContactTable,
79                         kamailioSIPRegUserLookupTable
80                         </para>
81                 </section>
82                 <section>
83                         <title>Alarm Monitoring</title>
84                         <para>
85                         If enabled, the SNMPStats module will monitor for alarm conditions. 
86                         Currently, there are two alarm types defined.  
87                         </para>
88                         
89                         <orderedlist numeration="arabic">
90                         <listitem>
91                                 <para>
92                                 The number of active dialogs has passed a minor or major threshold.
93                                 The idea is that a network operation centre can be made aware that 
94                                 their SIP servers may be overloaded, without having to explicitly
95                                 check for this condition.
96                                 </para>
97                                 <para>
98                                 If a minor or major condition has occured, then a 
99                                 kamailioDialogLimitMinorEvent trap or a 
100                                 kamailioDialogLimitMajorEvent trap will be generated, 
101                                 respectively. The minor and major thresholds are
102                                 described in the parameters section below.
103                                 </para>
104                         </listitem>
105                         <listitem>
106                                 <para>
107                                 The number of bytes waiting to be consumed across all of Kamailios
108                                 listening ports has passed a minor or major threshold.  The idea is
109                                 that a network operation centre can be made aware that a machine 
110                                 hosting a SIP server may be entering a degraded state, and to 
111                                 investigate why this is so. 
112                                 </para>
113                                 <para>
114                                 If the number of bytes to be consumed passes a minor or major 
115                                 threshold, then a kamailioMsgQueueDepthMinorEvent or 
116                                 kamailioMsgQueueDepthMajorEvent trap will be sent out, respectively.
117                                 </para>
118                         </listitem>
119
120                         </orderedlist>
121                         <para>
122                         Full details of these traps can be found in the distributions KAMAILIO-MIB
123                         file.  
124                         </para>
125                 </section>
126         </section>
127
128         
129         <section>
130         <title>How it works</title>
131
132         <section>
133         <title>How the SNMPStats module gets its data</title>
134         <para>
135         The SNMPStats module uses Kamailios internal statistic framework to collect most of its
136         data. However, there are two exceptions.  
137         <orderedlist>
138                 <listitem>
139                         <para>
140                         The kamailioSIPRegUserTable and kamailioSIPContactTable rely on the usrloc 
141                         modules callback system.  Specifically, the SNMPStats module will receive 
142                         callbacks whenever a user/contact is added to the system.
143                         </para>
144                 </listitem>
145                 <listitem>
146                         <para>
147                         The SNMPStats modules kamailioSIPMsgQueueDepthMinorEvent and 
148                         kamailioSIPMsgQueueDepthMajorEvent alarms rely on the Kamailio core to find out
149                         what interfaces, ports, and transports Kamailio is listening on.  However,
150                         the module will actually query the proc file system to find out the number
151                         of bytes waiting to be consumed.  (Currently, this will only work on systems
152                         providing the proc file system).
153                         </para>
154                 </listitem>
155         </orderedlist> 
156         </para>
157         </section>
158         <section>
159         <title>How data is moved from the SNMPStats module to a NOC</title>
160         <para>
161         We have now explained how the SNMPStats module gathers its data. We still have not
162         explained how it exports this data to a NOC (Network Operations Centre), or
163         administrator.
164         </para>
165         <para>
166         The SNMPStats module expects to connect to a <emphasis>Master Agent</emphasis>.  This
167         would be a NetSNMP daemon running either on the same system as the Kamailio instance, or 
168         on another system.  (Communication can take place over TCP, so there is no restriction
169         that this daemon need be on the same system as Kamailio).
170         </para>
171         <para>
172         If the master agent is unavailable when Kamailio first starts up, the SNMPStats module will
173         continue to run.  However, you will not be able to query it.  Thankfully, the SNMPStats
174         module continually looks for its master agent.  So even if the master agent is started late, 
175         or if the link to the SNMPStats module is severed due to a temporary hardware failure
176         or crashed and restarted master agent, the link will eventually be re-established.  No
177         data should be lost, and querying can begin again. 
178         </para>
179         <para>
180         To request for this data, you will need to query the master agent.  The master agent will
181         then redirect the request to the SNMPStats module, which will respond to the master agent, 
182         which will in turn respond to your request.  
183         </para>
184         </section>
185
186         </section>
187
188         <section>
189         <title>Dependencies</title>
190         <section>
191                 <title>&kamailio; Modules</title>
192                 <para>
193                 The SNMPStats module provides a plethora of statistics, some of which are collected
194                 by other modules.  If the dependent modules are not loaded then those specific 
195                 statistics will still be returned, but with zeroed values.  All other statistics will
196                 continue to function normally.  This means that the SNMPStats module has no  
197                 <emphasis>hard/mandatory</emphasis> dependencies on other modules.  There are however,
198                 <emphasis>soft</emphasis> dependencies, as follows:
199                 <itemizedlist>
200                 
201                 <listitem>
202                 <para>
203                 <emphasis>usrloc</emphasis> - all scalars and tables relating to users and contacts are
204                 dependent on the usrloc module.  If the module is not loaded, the respective tables
205                 will be empty. 
206                 </para>
207                 </listitem>
208                 
209                 <listitem>
210                 <para>
211                 <emphasis>dialog or dialog-ng</emphasis> - all scalars relating to the number of dialogs are 
212                 dependent on the presence of a dialog module.  Furthermore, if the module is 
213                 not loaded, then the kamailioDialogLimitMinorEvent, and kamailioDialogLimitMajorEvent
214                 alarm will be disabled. 
215                 </para>
216                 </listitem>
217                 
218                 </itemizedlist>
219                 The contents of the kamailioSIPMethodSupportedTable change depending on which modules
220                 are loaded.  
221                 </para>
222         </section>
223         <section>
224         <title>External Libraries or Applications</title>
225         <para>
226         The following libraries or applications must be installed before running
227         &kamailio; with this module loaded:
228                 <itemizedlist>
229                 <listitem>
230                 <para>
231                         <emphasis>NetSNMP v5.3 or greater</emphasis> - NetSNMP must be around 
232                         at the time of compilation.  Furthermore, there are several shared objects
233                         that must be loadable at the time SNMPStats is loaded.  This means that
234                         NetSNMP must be installed (but not necessarily running) on the system that
235                         has loaded the SNMPStats module.  (Details can be found in the compilation 
236                         section below).
237                 </para>
238                 </listitem>
239                 <listitem>
240                 <para>
241                         <emphasis>lm_sensors-dev</emphasis> - on some OS-es, this lib is
242                         required for compilation (http://www.lm-sensors.org/).
243                 </para>
244                 </listitem>
245                 </itemizedlist>
246         </para>
247         </section>
248         </section>
249         <section>
250         <title>Parameters</title>
251         <section id ="snmpstats.p.sipentitytape">
252                 <title><varname>sipEntityType</varname> (String) </title>
253
254                 <para>
255                 This parameter describes the entity type for this Kamailio instance,
256                 and will be used in determining what is returned for the
257                 kamailioSIPEntityType scalar. Valid parameters are:
258                 </para>
259
260                 <para>
261                 <emphasis>
262                 registrarServer, redirectServer, proxyServer, userAgent, edgeproxyServer, sipcaptureServer,other
263                 </emphasis>
264                 </para>
265
266                 <example>
267                 <title>Setting the <varname>sipEntityType</varname> parameter</title>
268                 <programlisting format="linespecific">
269 ...
270 modparam("snmpstats", "sipEntityType", "registrarServer")
271 modparam("snmpstats", "sipEntityType", "proxyServer")
272 ...
273                 </programlisting>
274                 </example>
275
276                 <para>
277                 Note that as the above example shows, you can define this parameter more
278                 than once.  This is of course because a given Kamailio instance can take on
279                 more than one role. The edgeproxyServer is an edge server using the outbound
280                 module and path extensions. The sipcaptureServer is a Homer Sip Capture
281                 server that collect SIP messages.
282                 </para>
283         </section>
284
285         <section id ="snmpstats.p.MsqQueueMinorTreshold">
286                 <title><varname>MsgQueueMinorThreshold</varname> (Integer)</title>
287
288                 <para>
289                 The SNMPStats module monitors the number of bytes waiting to be consumed by 
290                 Kamailio.  If the number of bytes waiting to be consumed exceeds a minor
291                 threshold, the SNMPStats module will send out an kamailioMsgQueueDepthMinorEvent
292                 trap to signal that an alarm condition has occured.  The minor threshold is set
293                 with the MsgQueueMinorThreshold parameter.  
294                 </para>
295
296                 <example>
297                 <title>Setting the <varname>MsgQueueMinorThreshold</varname> parameter</title>
298                 <programlisting format="linespecific">
299 ...
300 modparam("snmpstats", "MsgQueueMinorThreshold", 2000)
301 ...
302                 </programlisting>
303                 </example>
304
305                 <para>
306                 If this parameter is not set, then there will be no minor alarm monitoring.
307                 </para>
308         </section>
309         
310         <section id ="snmpstats.p.MsqQueueMajorTreshold">
311                 <title><varname>MsgQueueMajorThreshold</varname> (Integer)</title>
312
313                 <para>
314                 The SNMPStats module monitors the number of bytes waiting to be consumed by 
315                 Kamailio.  If the number of bytes waiting to be consumed exceeds a major
316                 threshold, the SNMPStats module will send out an kamailioMsgQueueDepthMajorEvent
317                 trap to signal that an alarm condition has occured.  The major threshold is set
318                 with the MsgQueueMajorThreshold parameter.  
319                 </para>
320
321                 <example>
322                 <title>Setting the <varname>MsgQueueMajorThreshold</varname> parameter</title>
323                 <programlisting format="linespecific">
324 ...
325 modparam("snmpstats", "MsgQueueMajorThreshold", 5000)
326 ...
327                 </programlisting>
328                 </example>
329
330                 <para>
331                 If this parameter is not set, then there will be no major alarm monitoring.
332                 </para>
333         </section>
334
335         <section id ="snmpstats.p.dlg_minor_treshold">
336                 <title><varname>dlg_minor_threshold</varname> (Integer)</title>
337
338                 <para>
339                 The SNMPStats module monitors the number of active dialogs.  If the number of
340                 active dialogs exceeds a minor threshold, the SNMPStats module will send out 
341                 an kamailioDialogLimitMinorEvent trap to signal that an alarm condition has 
342                 occured.  The minor threshold is set with the dlg_minor_threshold parameter.  
343                 </para>
344
345                 <example>
346                 <title>Setting the <varname>dlg_minor_threshold</varname> parameter</title>
347                 <programlisting format="linespecific">
348 ...
349   modparam("snmpstats", "dlg_minor_threshold", 500)
350 ...
351                 </programlisting>
352                 </example>
353
354                 <para>
355                 If this parameter is not set, then there will be no minor alarm monitoring.
356                 </para>
357         </section>
358
359         <section id ="snmpstats.p.dlg_major_treshold">
360                 <title><varname>dlg_major_threshold</varname> (Integer)</title>
361
362                 <para>
363                 The SNMPStats module monitors the number of active dialogs.  If the number of
364                 active dialogs exceeds a major threshold, the SNMPStats module will send out 
365                 an kamailioDialogLimitMajorEvent trap to signal that an alarm condition has 
366                 occured.  The major threshold is set with the dlg_major_threshold parameter.  
367                 </para>
368
369                 <example>
370                 <title>Setting the <varname>dlg_major_threshold</varname> parameter</title>
371                 <programlisting format="linespecific">
372 ...
373   modparam("snmpstats", "dlg_major_threshold", 750)
374 ...
375                 </programlisting>
376                 </example>
377
378                 <para>
379                 If this parameter is not set, then there will be no major alarm monitoring.
380                 </para>
381         </section>
382
383         <section id ="snmpstats.p.snmpgetPath">
384                 <title><varname>snmpgetPath</varname> (String)</title>
385
386                 <para>
387                 The SNMPStats module provides the kamailioSIPServiceStartTime scalar.
388                 This scalar requires the SNMPStats module to perform a snmpget query
389                 to the master agent.  You can use this parameter to set the path to 
390                 your instance of NetSNMP's snmpget program.  
391                 </para>
392
393                 <para>
394                 <emphasis>
395                         Default value is <quote>/usr/local/bin/</quote>.
396                 </emphasis>
397                 </para>
398
399                 <example>
400                 <title>Setting the <varname>snmpgetPath</varname> parameter</title>
401                 <programlisting format="linespecific">
402 ...
403 modparam("snmpstats", "snmpgetPath",     "/my/custom/path/")
404 ...
405                 </programlisting>
406                 </example>
407         </section>
408         
409         <section id ="snmpstats.p.snmpCommunity">
410                 <title><varname>snmpCommunity</varname> (String)</title>
411
412                 <para>
413                 The SNMPStats module provides the kamailioSIPServiceStartTime scalar.
414                 This scalar requires the SNMPStats module to perform a snmpget query
415                 to the master agent.  If you have defined a custom community string
416                 for the snmp daemon, you need to specify it with this parameter.  
417                 </para>
418
419                 <para>
420                 <emphasis>
421                         Default value is <quote>public</quote>.
422                 </emphasis>
423                 </para>
424
425                 <example>
426                 <title>Setting the <varname>snmpCommunity</varname> parameter</title>
427                 <programlisting format="linespecific">
428 ...
429 modparam("snmpstats", "snmpCommunity", "customCommunityString")
430 ...
431                 </programlisting>
432                 </example>
433         </section>
434
435         <section id ="snmpstats.p.export_registrar">
436                 <title><varname>export_registrar</varname> (int)</title>
437
438                 <para>
439                 The SNMPStats module will export registrar (usrloc) records if
440                 this parameter is set to 1. This will result in more memory usage
441                 and bigger exporter structure.
442                 </para>
443                 <para>
444                 If you enable this setting and NOT use it (i.e. not check the SNMP tables
445                 for registrations) an internal memory queue of usrloc changes will
446                 keep growing in shared (core) memory. To release the queue memory,
447                 run snmpwalk or use a monitoring tool to check the tables with
448                 regular intervals.
449                 </para>
450
451                 <para>
452                 <emphasis>
453                         Default value is <quote>0</quote> (don't export).
454                 </emphasis>
455                 </para>
456
457                 <example>
458                 <title>Setting the <varname>export_registrar</varname> parameter</title>
459                 <programlisting format="linespecific">
460 ...
461 modparam("snmpstats", "export_registrar", 1)
462 ...
463                 </programlisting>
464                 </example>
465         </section>
466
467         </section>
468         <section>
469         <title>Functions</title>
470                 <para>
471                 Currently, there are no exported functions.
472                 </para>
473         </section>
474         <section>
475         <title>Installation and Running</title>
476         <para>
477         There are several things that need to be done to get the SNMPStats module
478         compiled and up and running.
479         </para>
480
481         <section>
482         <title>
483         Compiling the SNMPStats Module
484         </title>
485         <para>
486         In order for the SNMPStats module to compile, you will need at least version
487         5.3 of the NetSNMP source code.  The source can be found at:
488
489         <programlisting format="linespecific">
490     http://net-snmp.sourceforge.net/ 
491         </programlisting>
492
493         For the specifics of installing NetSNMP, please see the INSTALL document in the
494         root of the NetSNMP source package.  
495         </para>
496
497         <para>
498         The SNMPStats modules makefile requires that the NetSNMP script
499         "net-snmp-config" can run.  At a minimum, running "net-snmp-config --agent-libs"
500         from the Kamailio source directory should return something similar to: 
501
502         <programlisting format="linespecific">
503     -L/usr/local/lib -lnetsnmpmibs -lnetsnmpagent -lnetsnmphelpers -lnetsnmp
504         </programlisting>
505
506         The specifics of what is returned depends on how the system was configured. If
507         your NetSNMP installation was installed from an RPM (or another packaged
508         version), then there is a good chance that net-snmp-config will return
509         something unecessarily longer.  It is highly recommended you install NetSNMP
510         from source to avoid bringing in excessive dependencies to the SNMPStats
511         module.
512         </para>
513         </section>
514         
515         <section>
516         <title>
517         Configuring NetSNMP to allow connections from the SNMPStats module.
518         </title>
519         <para>
520         The SNMPStats module will communicate with the NetSNMP Master Agent.  This 
521         communication happens over a protocol known as AgentX. This means that NetSNMP
522         must have been compiled with AgentX support.  This will always be the case when
523         you are compiling from source unless you explicitly removed AgentX support with
524         ./configure.  
525         </para>
526
527         <para>
528         After AgentX support has been compiled into NetSNMP, its configuration file needs
529         to be changed to turn on AgentX support.  The exact location of the configuration 
530         file (snmpd.conf) may vary depending on your system.  On my system, it is located in:
531  
532         <programlisting format="linespecific">
533     /usr/local/share/snmp/snmpd.conf.
534         </programlisting>
535
536         At the very end of the file add the following line:
537
538         <programlisting format="linespecific">
539     master agentx
540         </programlisting>
541
542         The line tells NetSNMP to act as an AgentX master agent, so that it can accept
543         connections from sub-agents such as the SNMPStats module.  
544         </para>
545
546         <para>
547         There is still one last step.  Even though we have compiled and configured NetSNMP
548         to have AgentX support, we still need to tell the daemon which interface and 
549         port to listen to for AgentX connections. This is done when the daemon is started
550         as follows:
551
552         <programlisting format="linespecific">
553     snmpd -x mySystemName:PortNumber
554         </programlisting>
555
556         On my system, I start the NetSNMP daemon with:
557
558         <programlisting format="linespecific">
559     snmpd -x localhost:705
560         </programlisting>
561
562         This tells NetSNMP to act as a master agent, listening on the localhost UDP
563         interface at port 705.  
564         </para>
565         </section>
566         
567         <section>
568         <title>
569         Configuring the SNMPStats module for communication with a Master Agent
570         </title>
571         <para>
572         The previous section explained how to set up a NetSNMP master agent to accept
573         AgentX connections.  We now need to tell the SNMPStats module how to communicate
574         with this master agent.  This is done by giving the SNMPStats module its own
575         NetSNMP configuration file.  The file must be named snmpstats.conf, and must be
576         in the same folder as the snmpd.conf file that was configured above. On my 
577         system this would be:
578
579         <programlisting format="linespecific">
580     /usr/local/share/snmp/snmpstats.conf
581         </programlisting>
582
583         The default configuration file included with the distribution can be used, and
584         contains the following:
585
586         <programlisting format="linespecific">
587     agentXSocket tcp:localhost:705
588         </programlisting>
589
590         The above line tells the SNMPStats module to register with the master agent on
591         the localhost, port 705.  The parameters should match up with the snmpd process.
592         Note that the master agent (snmpd) does not need to be present on the same
593         machine as Kamailio.  localhost could be replaced with any other machine. 
594         </para>
595         </section>
596         
597         <section>
598         <title>
599         Testing for a proper Configuration
600         </title>
601         <para>
602         As a quick test to make sure that the SNMPStats module sub-agent can succesfully
603         connect to the NetSNMP Master agent, start snmpd with the following:
604
605         <programlisting format="linespecific">
606     snmpd -f -Dagentx -x tcp:localhost:705 2>&amp;1 | less
607         </programlisting>
608
609         You should see something similar to the following:
610
611         <programlisting format="linespecific">
612     No log handling enabled - turning on stderr logging
613     registered debug token agentx, 1
614     ...
615     Turning on AgentX master support.
616     agentx/master: initializing...
617     agentx/master: initializing...   DONE
618     NET-SNMP version 5.3.1
619         </programlisting>
620
621         Now, start up Kamailio in another window.  In the snmpd window, you should see a
622         bunch of:
623
624         <programlisting format="linespecific">
625     agentx/master: handle pdu (req=0x2c58ebd4,trans=0x0,sess=0x0)
626     agentx/master: open 0x81137c0
627     agentx/master: opened 0x814bbe0 = 6 with flags = a0
628     agentx/master: send response, stat 0 (req=0x2c58ebd4,trans=0x0,sess=0x0)
629     agentx_build: packet built okay
630         </programlisting>
631
632         The messages beginning with "agentx" are debug messages stating that something is happening
633         with an AgentX sub-agent, appearing because of the -Dagentx snmpd switch.  The large number
634         of debug messages appear at startup as the SNMPStats module registers all of its scalars
635         and tables with the Master Agent.  If you receive these messages, then SNMPStats module
636         and NetSNMP daemon have both been configured correctly.
637         </para>
638         </section>
639
640         </section>
641 </chapter>
642