dbc1e43cdcadffc5a3dde4024c9c27253e5c9a6f
[sip-router] / modules / snmpstats / README
1 SNMPStats Module (Simple Network Management Protocal Statistic Module)
2
3 Jeffrey Magder
4
5    SOMA Networks, Inc.
6
7 Edited by
8
9 Jeffrey Magder
10
11 Edited by
12
13 Olle E. Johansson
14
15    Copyright © 2006 SOMA Networks, Inc.
16
17    Copyright © 2013 Edvina AB, Sollentuna, Sweden
18      __________________________________________________________________
19
20    Table of Contents
21
22    1. Admin Guide
23
24         1. Overview
25
26               1.1. General Scalar Statistics
27               1.2. SNMP Tables
28               1.3. Alarm Monitoring
29
30         2. How it works
31
32               2.1. How the SNMPStats module gets its data
33               2.2. How data is moved from the SNMPStats module to a NOC
34
35         3. Dependencies
36
37               3.1. Kamailio Modules
38               3.2. External Libraries or Applications
39
40         4. Parameters
41
42               4.1. sipEntityType (String)
43               4.2. MsgQueueMinorThreshold (Integer)
44               4.3. MsgQueueMajorThreshold (Integer)
45               4.4. dlg_minor_threshold (Integer)
46               4.5. dlg_major_threshold (Integer)
47               4.6. snmpgetPath (String)
48               4.7. snmpCommunity (String)
49               4.8. export_registrar (int)
50
51         5. Functions
52         6. Installation and Running
53
54               6.1. Compiling the SNMPStats Module
55               6.2. Configuring NetSNMP to allow connections from the
56                       SNMPStats module.
57
58               6.3. Configuring the SNMPStats module for communication with
59                       a Master Agent
60
61               6.4. Testing for a proper Configuration
62
63    2. Frequently Asked Questions
64
65    List of Examples
66
67    1.1. Setting the sipEntityType parameter
68    1.2. Setting the MsgQueueMinorThreshold parameter
69    1.3. Setting the MsgQueueMajorThreshold parameter
70    1.4. Setting the dlg_minor_threshold parameter
71    1.5. Setting the dlg_major_threshold parameter
72    1.6. Setting the snmpgetPath parameter
73    1.7. Setting the snmpCommunity parameter
74    1.8. Setting the export_registrar parameter
75
76 Chapter 1. Admin Guide
77
78    Table of Contents
79
80    1. Overview
81
82         1.1. General Scalar Statistics
83         1.2. SNMP Tables
84         1.3. Alarm Monitoring
85
86    2. How it works
87
88         2.1. How the SNMPStats module gets its data
89         2.2. How data is moved from the SNMPStats module to a NOC
90
91    3. Dependencies
92
93         3.1. Kamailio Modules
94         3.2. External Libraries or Applications
95
96    4. Parameters
97
98         4.1. sipEntityType (String)
99         4.2. MsgQueueMinorThreshold (Integer)
100         4.3. MsgQueueMajorThreshold (Integer)
101         4.4. dlg_minor_threshold (Integer)
102         4.5. dlg_major_threshold (Integer)
103         4.6. snmpgetPath (String)
104         4.7. snmpCommunity (String)
105         4.8. export_registrar (int)
106
107    5. Functions
108    6. Installation and Running
109
110         6.1. Compiling the SNMPStats Module
111         6.2. Configuring NetSNMP to allow connections from the SNMPStats
112                 module.
113
114         6.3. Configuring the SNMPStats module for communication with a
115                 Master Agent
116
117         6.4. Testing for a proper Configuration
118
119 1. Overview
120
121    1.1. General Scalar Statistics
122    1.2. SNMP Tables
123    1.3. Alarm Monitoring
124
125    The SNMPStats module provides an SNMP management interface to Kamailio.
126    Specifically, it provides general SNMP queryable scalar statistics,
127    table representations of more complicated data such as user and contact
128    information, and alarm monitoring capabilities.
129
130    The MIB has been renamed in version 4.0.0 to reflect the product name.
131    Please note that all the OID names has changed, as well as the MIB
132    itself.
133
134 1.1. General Scalar Statistics
135
136    The SNMPStats module provides a number of general scalar statistics.
137    Details are available in KAMAILIO-MIB, KAMAILIO-REG-MIB,
138    KAMAILIO-SIP-COMMON-MIB, and KAMAILIO-SIP-SERVER-MIB. But briefly,
139    these scalars are:
140
141    kamailioSIPProtocolVersion, kamailioSIPServiceStartTime,
142    kamailioSIPEntityType, kamailioSIPSummaryInRequests,
143    kamailioSIPSummaryOutRequest, kamailioSIPSummaryInResponses,
144    kamailioSIPSummaryOutResponses, kamailioSIPSummaryTotalTransactions,
145    kamailioSIPCurrentTransactions, kamailioSIPNumUnsupportedUris,
146    kamailioSIPNumUnsupportedMethods, kamailioSIPOtherwiseDiscardedMsgs,
147    kamailioSIPProxyStatefulness kamailioSIPProxyRecordRoute,
148    kamailioSIPProxyAuthMethod, kamailioSIPNumProxyRequireFailures,
149    kamailioSIPRegMaxContactExpiryDuration, kamailioSIPRegMaxUsers,
150    kamailioSIPRegCurrentUsers, kamailioSIPRegDfltRegActiveInterval,
151    kamailioSIPRegAcceptedRegistrations,
152    kamailioSIPRegRejectedRegistrations, kamailioMsgQueueDepth.
153    kamailioCurNumDialogs, kamailioCurNumDialogsInProgress,
154    kamailioCurNumDialogsInSetup, kamailioTotalNumFailedDialogSetups
155
156    There are also scalars associated with alarms. They are as follows:
157
158    kamailioMsgQueueMinorThreshold, kamailioMsgQueueMajorThreshold,
159    kamailioMsgQueueDepthAlarmStatus, kamailioMsgQueueDepthMinorAlarm,
160    kamailioMsgQueueDepthMajorAlarm, kamailioDialogLimitMinorThreshold,
161    kamailioDialogLimitMajorThreshold, kamailioDialogUsageState,
162    kamailioDialogLimitAlarmStatus, kamailioDialogLimitMinorAlarm,
163    kamailioDialogLimitMajorAlarm
164
165    In Kamailio 4.1 a set of new OIDs was added to reflect the Kamailio
166    configuration, the version, core status (memory, connections),
167    transports and module data.
168
169 1.2. SNMP Tables
170
171    The SNMPStats module provides several tables, containing more
172    complicated data. The current available tables are:
173
174    kamailioSIPPortTable, kamailioSIPMethodSupportedTable,
175    kamailioSIPStatusCodesTable, kamailioSIPRegUserTable,
176    kamailioSIPContactTable, kamailioSIPRegUserLookupTable
177
178 1.3. Alarm Monitoring
179
180    If enabled, the SNMPStats module will monitor for alarm conditions.
181    Currently, there are two alarm types defined.
182     1. The number of active dialogs has passed a minor or major threshold.
183        The idea is that a network operation centre can be made aware that
184        their SIP servers may be overloaded, without having to explicitly
185        check for this condition.
186        If a minor or major condition has occured, then a
187        kamailioDialogLimitMinorEvent trap or a
188        kamailioDialogLimitMajorEvent trap will be generated, respectively.
189        The minor and major thresholds are described in the parameters
190        section below.
191     2. The number of bytes waiting to be consumed across all of Kamailios
192        listening ports has passed a minor or major threshold. The idea is
193        that a network operation centre can be made aware that a machine
194        hosting a SIP server may be entering a degraded state, and to
195        investigate why this is so.
196        If the number of bytes to be consumed passes a minor or major
197        threshold, then a kamailioMsgQueueDepthMinorEvent or
198        kamailioMsgQueueDepthMajorEvent trap will be sent out,
199        respectively.
200
201    Full details of these traps can be found in the distributions
202    KAMAILIO-MIB file.
203
204 2. How it works
205
206    2.1. How the SNMPStats module gets its data
207    2.2. How data is moved from the SNMPStats module to a NOC
208
209 2.1. How the SNMPStats module gets its data
210
211    The SNMPStats module uses Kamailios internal statistic framework to
212    collect most of its data. However, there are two exceptions.
213     1. The kamailioSIPRegUserTable and kamailioSIPContactTable rely on the
214        usrloc modules callback system. Specifically, the SNMPStats module
215        will receive callbacks whenever a user/contact is added to the
216        system.
217     2. The SNMPStats modules kamailioSIPMsgQueueDepthMinorEvent and
218        kamailioSIPMsgQueueDepthMajorEvent alarms rely on the Kamailio core
219        to find out what interfaces, ports, and transports Kamailio is
220        listening on. However, the module will actually query the proc file
221        system to find out the number of bytes waiting to be consumed.
222        (Currently, this will only work on systems providing the proc file
223        system).
224
225 2.2. How data is moved from the SNMPStats module to a NOC
226
227    We have now explained how the SNMPStats module gathers its data. We
228    still have not explained how it exports this data to a NOC (Network
229    Operations Centre), or administrator.
230
231    The SNMPStats module expects to connect to a Master Agent. This would
232    be a NetSNMP daemon running either on the same system as the Kamailio
233    instance, or on another system. (Communication can take place over TCP,
234    so there is no restriction that this daemon need be on the same system
235    as Kamailio).
236
237    If the master agent is unavailable when Kamailio first starts up, the
238    SNMPStats module will continue to run. However, you will not be able to
239    query it. Thankfully, the SNMPStats module continually looks for its
240    master agent. So even if the master agent is started late, or if the
241    link to the SNMPStats module is severed due to a temporary hardware
242    failure or crashed and restarted master agent, the link will eventually
243    be re-established. No data should be lost, and querying can begin
244    again.
245
246    To request for this data, you will need to query the master agent. The
247    master agent will then redirect the request to the SNMPStats module,
248    which will respond to the master agent, which will in turn respond to
249    your request.
250
251 3. Dependencies
252
253    3.1. Kamailio Modules
254    3.2. External Libraries or Applications
255
256 3.1. Kamailio Modules
257
258    The SNMPStats module provides a plethora of statistics, some of which
259    are collected by other modules. If the dependent modules are not loaded
260    then those specific statistics will still be returned, but with zeroed
261    values. All other statistics will continue to function normally. This
262    means that the SNMPStats module has no hard/mandatory dependencies on
263    other modules. There are however, soft dependencies, as follows:
264      * usrloc - all scalars and tables relating to users and contacts are
265        dependent on the usrloc module. If the module is not loaded, the
266        respective tables will be empty.
267      * dialog or dialog-ng - all scalars relating to the number of dialogs
268        are dependent on the presence of a dialog module. Furthermore, if
269        the module is not loaded, then the kamailioDialogLimitMinorEvent,
270        and kamailioDialogLimitMajorEvent alarm will be disabled.
271
272    The contents of the kamailioSIPMethodSupportedTable change depending on
273    which modules are loaded.
274
275 3.2. External Libraries or Applications
276
277    The following libraries or applications must be installed before
278    running Kamailio with this module loaded:
279      * NetSNMP v5.3 or greater - NetSNMP must be around at the time of
280        compilation. Furthermore, there are several shared objects that
281        must be loadable at the time SNMPStats is loaded. This means that
282        NetSNMP must be installed (but not necessarily running) on the
283        system that has loaded the SNMPStats module. (Details can be found
284        in the compilation section below).
285      * lm_sensors-dev - on some OS-es, this lib is required for
286        compilation (http://www.lm-sensors.org/).
287
288 4. Parameters
289
290    4.1. sipEntityType (String)
291    4.2. MsgQueueMinorThreshold (Integer)
292    4.3. MsgQueueMajorThreshold (Integer)
293    4.4. dlg_minor_threshold (Integer)
294    4.5. dlg_major_threshold (Integer)
295    4.6. snmpgetPath (String)
296    4.7. snmpCommunity (String)
297    4.8. export_registrar (int)
298
299 4.1. sipEntityType (String)
300
301    This parameter describes the entity type for this Kamailio instance,
302    and will be used in determining what is returned for the
303    kamailioSIPEntityType scalar. Valid parameters are:
304
305    registrarServer, redirectServer, proxyServer, userAgent,
306    edgeproxyServer, sipcaptureServer,other
307
308    Example 1.1. Setting the sipEntityType parameter
309 ...
310 modparam("snmpstats", "sipEntityType", "registrarServer")
311 modparam("snmpstats", "sipEntityType", "proxyServer")
312 ...
313
314    Note that as the above example shows, you can define this parameter
315    more than once. This is of course because a given Kamailio instance can
316    take on more than one role. The edgeproxyServer is an edge server using
317    the outbound module and path extensions. The sipcaptureServer is a
318    Homer Sip Capture server that collect SIP messages.
319
320 4.2. MsgQueueMinorThreshold (Integer)
321
322    The SNMPStats module monitors the number of bytes waiting to be
323    consumed by Kamailio. If the number of bytes waiting to be consumed
324    exceeds a minor threshold, the SNMPStats module will send out an
325    kamailioMsgQueueDepthMinorEvent trap to signal that an alarm condition
326    has occured. The minor threshold is set with the MsgQueueMinorThreshold
327    parameter.
328
329    Example 1.2. Setting the MsgQueueMinorThreshold parameter
330 ...
331 modparam("snmpstats", "MsgQueueMinorThreshold", 2000)
332 ...
333
334    If this parameter is not set, then there will be no minor alarm
335    monitoring.
336
337 4.3. MsgQueueMajorThreshold (Integer)
338
339    The SNMPStats module monitors the number of bytes waiting to be
340    consumed by Kamailio. If the number of bytes waiting to be consumed
341    exceeds a major threshold, the SNMPStats module will send out an
342    kamailioMsgQueueDepthMajorEvent trap to signal that an alarm condition
343    has occured. The major threshold is set with the MsgQueueMajorThreshold
344    parameter.
345
346    Example 1.3. Setting the MsgQueueMajorThreshold parameter
347 ...
348 modparam("snmpstats", "MsgQueueMajorThreshold", 5000)
349 ...
350
351    If this parameter is not set, then there will be no major alarm
352    monitoring.
353
354 4.4. dlg_minor_threshold (Integer)
355
356    The SNMPStats module monitors the number of active dialogs. If the
357    number of active dialogs exceeds a minor threshold, the SNMPStats
358    module will send out an kamailioDialogLimitMinorEvent trap to signal
359    that an alarm condition has occured. The minor threshold is set with
360    the dlg_minor_threshold parameter.
361
362    Example 1.4. Setting the dlg_minor_threshold parameter
363 ...
364   modparam("snmpstats", "dlg_minor_threshold", 500)
365 ...
366
367    If this parameter is not set, then there will be no minor alarm
368    monitoring.
369
370 4.5. dlg_major_threshold (Integer)
371
372    The SNMPStats module monitors the number of active dialogs. If the
373    number of active dialogs exceeds a major threshold, the SNMPStats
374    module will send out an kamailioDialogLimitMajorEvent trap to signal
375    that an alarm condition has occured. The major threshold is set with
376    the dlg_major_threshold parameter.
377
378    Example 1.5. Setting the dlg_major_threshold parameter
379 ...
380   modparam("snmpstats", "dlg_major_threshold", 750)
381 ...
382
383    If this parameter is not set, then there will be no major alarm
384    monitoring.
385
386 4.6. snmpgetPath (String)
387
388    The SNMPStats module provides the kamailioSIPServiceStartTime scalar.
389    This scalar requires the SNMPStats module to perform a snmpget query to
390    the master agent. You can use this parameter to set the path to your
391    instance of NetSNMP's snmpget program.
392
393    Default value is "/usr/local/bin/".
394
395    Example 1.6. Setting the snmpgetPath parameter
396 ...
397 modparam("snmpstats", "snmpgetPath",     "/my/custom/path/")
398 ...
399
400 4.7. snmpCommunity (String)
401
402    The SNMPStats module provides the kamailioSIPServiceStartTime scalar.
403    This scalar requires the SNMPStats module to perform a snmpget query to
404    the master agent. If you have defined a custom community string for the
405    snmp daemon, you need to specify it with this parameter.
406
407    Default value is "public".
408
409    Example 1.7. Setting the snmpCommunity parameter
410 ...
411 modparam("snmpstats", "snmpCommunity", "customCommunityString")
412 ...
413
414 4.8. export_registrar (int)
415
416    The SNMPStats module will export registrar (usrloc) records if this
417    parameter is set to 1. This will result in more memory usage and bigger
418    exporter structure.
419
420    If you enable this setting and NOT use it (i.e. not check the SNMP
421    tables for registrations) an internal memory queue of usrloc changes
422    will keep growing in shared (core) memory. To release the queue memory,
423    run snmpwalk or use a monitoring tool to check the tables with regular
424    intervals.
425
426    Default value is "0" (don't export).
427
428    Example 1.8. Setting the export_registrar parameter
429 ...
430 modparam("snmpstats", "export_registrar", 1)
431 ...
432
433 5. Functions
434
435    Currently, there are no exported functions.
436
437 6. Installation and Running
438
439    6.1. Compiling the SNMPStats Module
440    6.2. Configuring NetSNMP to allow connections from the SNMPStats
441           module.
442
443    6.3. Configuring the SNMPStats module for communication with a Master
444           Agent
445
446    6.4. Testing for a proper Configuration
447
448    There are several things that need to be done to get the SNMPStats
449    module compiled and up and running.
450
451 6.1. Compiling the SNMPStats Module
452
453    In order for the SNMPStats module to compile, you will need at least
454    version 5.3 of the NetSNMP source code. The source can be found at:
455     http://net-snmp.sourceforge.net/
456
457    For the specifics of installing NetSNMP, please see the INSTALL
458    document in the root of the NetSNMP source package.
459
460    The SNMPStats modules makefile requires that the NetSNMP script
461    "net-snmp-config" can run. At a minimum, running "net-snmp-config
462    --agent-libs" from the Kamailio source directory should return
463    something similar to:
464     -L/usr/local/lib -lnetsnmpmibs -lnetsnmpagent -lnetsnmphelpers -lnetsnmp
465
466    The specifics of what is returned depends on how the system was
467    configured. If your NetSNMP installation was installed from an RPM (or
468    another packaged version), then there is a good chance that
469    net-snmp-config will return something unecessarily longer. It is highly
470    recommended you install NetSNMP from source to avoid bringing in
471    excessive dependencies to the SNMPStats module.
472
473 6.2. Configuring NetSNMP to allow connections from the SNMPStats module.
474
475    The SNMPStats module will communicate with the NetSNMP Master Agent.
476    This communication happens over a protocol known as AgentX. This means
477    that NetSNMP must have been compiled with AgentX support. This will
478    always be the case when you are compiling from source unless you
479    explicitly removed AgentX support with ./configure.
480
481    After AgentX support has been compiled into NetSNMP, its configuration
482    file needs to be changed to turn on AgentX support. The exact location
483    of the configuration file (snmpd.conf) may vary depending on your
484    system. On my system, it is located in:
485     /usr/local/share/snmp/snmpd.conf.
486
487    At the very end of the file add the following line:
488     master agentx
489
490    The line tells NetSNMP to act as an AgentX master agent, so that it can
491    accept connections from sub-agents such as the SNMPStats module.
492
493    There is still one last step. Even though we have compiled and
494    configured NetSNMP to have AgentX support, we still need to tell the
495    daemon which interface and port to listen to for AgentX connections.
496    This is done when the daemon is started as follows:
497     snmpd -x mySystemName:PortNumber
498
499    On my system, I start the NetSNMP daemon with:
500     snmpd -x localhost:705
501
502    This tells NetSNMP to act as a master agent, listening on the localhost
503    UDP interface at port 705.
504
505 6.3. Configuring the SNMPStats module for communication with a Master Agent
506
507    The previous section explained how to set up a NetSNMP master agent to
508    accept AgentX connections. We now need to tell the SNMPStats module how
509    to communicate with this master agent. This is done by giving the
510    SNMPStats module its own NetSNMP configuration file. The file must be
511    named snmpstats.conf, and must be in the same folder as the snmpd.conf
512    file that was configured above. On my system this would be:
513     /usr/local/share/snmp/snmpstats.conf
514
515    The default configuration file included with the distribution can be
516    used, and contains the following:
517     agentXSocket tcp:localhost:705
518
519    The above line tells the SNMPStats module to register with the master
520    agent on the localhost, port 705. The parameters should match up with
521    the snmpd process. Note that the master agent (snmpd) does not need to
522    be present on the same machine as Kamailio. localhost could be replaced
523    with any other machine.
524
525 6.4. Testing for a proper Configuration
526
527    As a quick test to make sure that the SNMPStats module sub-agent can
528    succesfully connect to the NetSNMP Master agent, start snmpd with the
529    following:
530     snmpd -f -Dagentx -x tcp:localhost:705 2>&1 | less
531
532    You should see something similar to the following:
533     No log handling enabled - turning on stderr logging
534     registered debug token agentx, 1
535     ...
536     Turning on AgentX master support.
537     agentx/master: initializing...
538     agentx/master: initializing...   DONE
539     NET-SNMP version 5.3.1
540
541    Now, start up Kamailio in another window. In the snmpd window, you
542    should see a bunch of:
543     agentx/master: handle pdu (req=0x2c58ebd4,trans=0x0,sess=0x0)
544     agentx/master: open 0x81137c0
545     agentx/master: opened 0x814bbe0 = 6 with flags = a0
546     agentx/master: send response, stat 0 (req=0x2c58ebd4,trans=0x0,sess=0x0)
547     agentx_build: packet built okay
548
549    The messages beginning with "agentx" are debug messages stating that
550    something is happening with an AgentX sub-agent, appearing because of
551    the -Dagentx snmpd switch. The large number of debug messages appear at
552    startup as the SNMPStats module registers all of its scalars and tables
553    with the Master Agent. If you receive these messages, then SNMPStats
554    module and NetSNMP daemon have both been configured correctly.
555
556 Chapter 2. Frequently Asked Questions
557
558    2.1. Where can I find more about SNMP?
559    2.2. Where can I find more about NetSNMP?
560    2.3. Where can I find out more about AgentX?
561    2.4. Why am I not receiving any SNMP Traps?
562    2.5. Kamailio refuses to load the SNMPStats module. Why is it
563           displaying "load_module: could not open module snmpstats.so"?
564
565    2.6. How can I learn what all the scalars and tables are?
566    2.7. Why do snmpget, snmpwalk, and snmptable always time out?
567    2.8. How do I use snmpget?
568    2.9. How do I use snmptable?
569    2.10. Where can I find more about Kamailio?
570    2.11. Where can I post a question about this module?
571    2.12. How can I report a bug?
572
573    2.1.
574
575    Where can I find more about SNMP?
576
577    There are many websites that explain SNMP at all levels of detail. A
578    great general introduction can be found at
579    http://en.wikipedia.org/wiki/SNMP If you are interested in the nitty
580    gritty details of the protocol, then please look at RFC 3410. RFC 3410
581    maps out the many other RFCs that define SNMP, and can be found at
582    http://www.rfc-archive.org/getrfc.php?rfc=3410
583
584    2.2.
585
586    Where can I find more about NetSNMP?
587
588    NetSNMP source code, documentation, FAQs, and tutorials can all be
589    found at http://net-snmp.sourceforge.net/.
590
591    2.3.
592
593    Where can I find out more about AgentX?
594
595    The full details of the AgentX protocol are explained in RFC 2741,
596    available at: http://www.rfc-archive.org/getrfc.php?rfc=2741
597
598    2.4.
599
600    Why am I not receiving any SNMP Traps?
601
602    Assuming you've configured the trap thresholds in kamailio.cfg with
603    something similar to:
604     modparam("snmpstats", "MsgQueueMinorThreshold", 1234)
605     modparam("snmpstats", "MsgQueueMajorThreshold", 5678)
606
607     modparam("snmpstats", "dlg_minor_threshold", 500)
608     modparam("snmpstats", "dlg_minor_threshold", 600)
609
610    Then either Kamailio is not reaching these thresholds (which is a good
611    thing), or you haven't set up the trap monitor correctly. To prove this
612    to yourself, you can start NetSNMP with:
613     snmpd -f -Dtrap -x localhost:705
614
615    The -f tells the NetSNMP process to not daemonize, and the -Dtrap
616    enables trap debug logs. You should see something similar to the
617    following:
618     registered debug token trap, 1
619     trap: adding callback trap sink            ----- You should see both
620     trapsess: adding to trap table             ----- of these lines.
621     Turning on AgentX master support.
622     trap: send_trap 0 0 NET-SNMP-TC::linux
623     trap: sending trap type=167, version=1
624     NET-SNMP version 5.3.1
625
626    If the two lines above did not appear, then you probably have not
627    included the following in your snmpd.conf file.
628     trap2sink machineToSendTrapsTo:machinesPortNumber.
629
630    When a trap has been received by snmpd, the following will appear in
631    the above output:
632     sent_trap -1 -1 NET-SNMP-TC::linus
633     sending trap type=167, version=1
634
635    You'll also need a program to collect the traps and do something with
636    them (such as sending them to syslog). NetSNMP provides snmptrapd for
637    this. Other solutions exist as well. Google is your friend.
638
639    2.5.
640
641    Kamailio refuses to load the SNMPStats module. Why is it displaying
642    "load_module: could not open module snmpstats.so"?
643
644    On some systems, you may receive the following error at stdout or the
645    log files depending on the configuration.
646     ERROR: load_module: could not open module </usr/local/lib/kamailio/modules_k
647 /snmpstats.so>:
648            libnetsnmpmibs.so.10: cannot open shared object file: No such file or
649  directory.
650
651    This means one of two things:
652     1. You did not install NetSNMP. ("make install" if building from
653        source)
654     2. The dynamic linker cannot find the necessary libraries.
655
656    In the second case, the fix is as follows:
657     1. find / -name "libnetsnmpmibs*"
658           + You will find a copy unless you haven't installed NetSNMP.
659             Make note of the path.
660     2. less /etc/ld.so.conf
661           + If the file is missing the path from step 1, then add the path
662             to ld.so.conf
663     3. ldconfig
664     4. Try starting Kamailio again.
665
666    Alternatively, you may prefix your startup command with:
667     LD_LIBRARY_PATH=/path/noted/in/step/one/above
668
669    For example, on my system I ran:
670     LD_LIBRARY_PATH=/usr/local/lib kamctl start
671
672    2.6.
673
674    How can I learn what all the scalars and tables are?
675
676    All scalars and tables are named in the SNMPStats module overview. The
677    files KAMAILIO-MIB, KAMAILIO-REG-MIB, KAMAILIO-SIP-COMMON-MIB and
678    KAMAILIO-SIP-SERVER-MIB contain the full definitions and descriptions.
679    Note however, that the MIBs may actually contain scalars and tables
680    which are currently not provided by the SNMPStats module. Therefore, it
681    is better to use NetSNMP's snmptranslate as an alternative. Take the
682    kamailioSIPEntityType scalar as an example. You can invoke
683    snmptranslate as follows:
684     snmptranslate -TBd kamailioSIPEntityType
685
686    Which would result in something similar to the following:
687     -- FROM       KAMAILIO-SIP-COMMON-MIB
688     -- TEXTUAL CONVENTION KamailioSIPEntityRole
689     SYNTAX        BITS {other(0), userAgent(1), proxyServer(2), redirectServer(3
690 ), registrarServer(4)}
691     MAX-ACCESS    read-only
692     STATUS        current
693     DESCRIPTION   " This object identifies the list of SIP entities this
694                    row is related to. It is defined as a bit map.  Each
695                    bit represents a type of SIP entity.
696                    If a bit has value 1, the SIP entity represented by
697                    this row plays the role of this entity type.
698
699                    If a bit has value 0, the SIP entity represented by
700                    this row does not act as this entity type
701                    Combinations of bits can be set when the SIP entity
702                    plays multiple SIP roles."
703
704    2.7.
705
706    Why do snmpget, snmpwalk, and snmptable always time out?
707
708    If your snmp operations are always returning with: "Timeout: No
709    Response from localhost", then chances are that you are making the
710    query with the wrong community string. Default installs will most
711    likely use "public" as their default community strings. Grep your
712    snmpd.conf file for the string "rocommunity", and use the result as
713    your community string in your queries.
714
715    2.8.
716
717    How do I use snmpget?
718
719    NetSNMP's snmpget is used as follows:
720     snmpget -v 2c -c theCommunityString machineToSendTheMachineTo scalarElement.
721 0
722
723    For example, consider an snmpget on the kamailioSIPEntityType scalar,
724    run on the same machine running the Kamailio instance, with the default
725    "public" community string. The command would be:
726     snmpget -v2c -c public localhost kamailioSIPEntityType.0
727
728    Which would result in something similar to:
729     KAMAILIO-SIP-COMMON-MIB::kamailioSIPEntityType.0 = BITS: F8 \
730                 other(0) userAgent(1) proxyServer(2)          \
731                 redirectServer(3) registrarServer(4)
732
733    2.9.
734
735    How do I use snmptable?
736
737    NetSNMP's snmptable is used as follows:
738     snmptable -Ci -v 2c -c theCommunityString machineToSendTheMachineTo theTable
739 Name
740
741    For example, consider the kamailioSIPRegUserTable. If we run the
742    snmptable command on the same machine as the running Kamailio instance,
743    configured with the default "public" community string. The command
744    would be:
745     snmptable -Ci -v 2c -c public localhost kamailioSIPRegUserTable
746
747    Which would result in something similar to:
748     index kamailioSIPUserUri kamailioSIPUserAuthenticationFailures
749         1       DefaultUser                                    0
750         2            bogdan                                    0
751         3    jeffrey.magder                                    0
752
753    2.10.
754
755    Where can I find more about Kamailio?
756
757    Take a look at http://www.kamailio.org/.
758
759    2.11.
760
761    Where can I post a question about this module?
762
763    First at all check if your question was already answered on one of our
764    mailing lists:
765      * User Mailing List -
766        http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
767      * Developer Mailing List -
768        http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
769
770    E-mails regarding any stable Kamailio release should be sent to
771    <sr-users@lists.sip-router.org> and e-mails regarding development
772    versions should be sent to <sr-dev@lists.sip-router.org>.
773
774    If you want to keep the mail private, send it to
775    <sr-users@lists.sip-router.org>.
776
777    2.12.
778
779    How can I report a bug?
780
781    Please follow the guidelines provided at:
782    http://sip-router.org/tracker.