Browse code

snmpstats: add parameter to specify SNMP version

Marat Gareev authored on 07/09/2021 17:36:36 • Henning Westerholt committed on 09/09/2021 19:42:56
Showing 1 changed files
... ...
@@ -439,6 +439,32 @@ modparam("snmpstats", "snmpCommunity", "customCommunityString")
439 439
 		</example>
440 440
 	</section>
441 441
 
442
+	<section id ="snmpstats.p.snmpVersion">
443
+		<title><varname>snmpVersion</varname> (String)</title>
444
+
445
+		<para>
446
+		The SNMPStats module provides the kamailioSIPServiceStartTime scalar.
447
+		This scalar requires the SNMPStats module to perform a snmpget query
448
+		to the master agent.  You can use this parameter to set specific
449
+		SNMP version.
450
+		</para>
451
+
452
+		<para>
453
+		<emphasis>
454
+			Default value is <quote>3</quote>.
455
+		</emphasis>
456
+		</para>
457
+
458
+		<example>
459
+		<title>Setting the <varname>snmpVersion</varname> parameter</title>
460
+		<programlisting format="linespecific">
461
+...
462
+modparam("snmpstats", "snmpVersion", "2c")
463
+...
464
+		</programlisting>
465
+		</example>
466
+	</section>
467
+
442 468
 	<section id ="snmpstats.p.export_registrar">
443 469
 		<title><varname>export_registrar</varname> (int)</title>
444 470
 
Browse code

snmpstats: Fix typos in module documentation

Florian Floimair authored on 27/02/2018 20:57:17 • Daniel-Constantin Mierla committed on 28/02/2018 17:00:48
Showing 1 changed files
... ...
@@ -513,7 +513,7 @@ modparam("snmpstats", "export_registrar", 1)
513 513
 	The specifics of what is returned depends on how the system was configured. If
514 514
 	your NetSNMP installation was installed from an RPM (or another packaged
515 515
 	version), then there is a good chance that net-snmp-config will return
516
-	something unecessarily longer.  It is highly recommended you install NetSNMP
516
+	something unnecessarily longer.  It is highly recommended you install NetSNMP
517 517
 	from source to avoid bringing in excessive dependencies to the SNMPStats
518 518
 	module.
519 519
 	</para>
... ...
@@ -606,7 +606,7 @@ modparam("snmpstats", "export_registrar", 1)
606 606
 	Testing for a proper Configuration
607 607
 	</title>
608 608
 	<para>
609
-	As a quick test to make sure that the SNMPStats module sub-agent can succesfully
609
+	As a quick test to make sure that the SNMPStats module sub-agent can successfully
610 610
 	connect to the NetSNMP Master agent, start snmpd with the following:
611 611
 
612 612
 	<programlisting format="linespecific">
Browse code

doc, modules: updated the path to docbook entities and spec files

Daniel-Constantin Mierla authored on 07/12/2016 14:24:32
Showing 1 changed files
... ...
@@ -3,7 +3,7 @@
3 3
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4 4
 
5 5
 <!-- Include general documentation entities -->
6
-<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
6
+<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 7
 %docentities;
8 8
 
9 9
 ]>
Browse code

core, lib, modules: restructured source code tree

- new folder src/ to hold the source code for main project applications
- main.c is in src/
- all core files are subfolder are in src/core/
- modules are in src/modules/
- libs are in src/lib/
- application Makefiles are in src/
- application binary is built in src/ (src/kamailio)

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