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