From 7ebd18449a170d0254f720607298ab40f203c768 Mon Sep 17 00:00:00 2001 From: Bogdan-Andrei Iancu Date: Mon, 27 Apr 2015 16:14:22 +0300 Subject: [PATCH] Docs updated and refurbished. (cherry picked from commit d154fe2749bd28cb8ace20df6ec88d7a9808b86b) --- modules/snmpstats/README | 136 ++++---- modules/snmpstats/doc/snmpstats_admin.xml | 378 +++++++++++----------- 2 files changed, 246 insertions(+), 268 deletions(-) diff --git a/modules/snmpstats/README b/modules/snmpstats/README index 923b05f228..5c0e8874ed 100644 --- a/modules/snmpstats/README +++ b/modules/snmpstats/README @@ -49,8 +49,8 @@ Jeffrey Magder 1.6. Installation and Running 1.6.1. Compiling the SNMPStats Module - 1.6.2. Configuring NetSNMP to allow connections from - the SNMPStats module. + 1.6.2. Configuring SNMP daemon to allow connections + from the SNMPStats module. 1.6.3. Configuring the SNMPStats module for communication with a Master Agent @@ -137,7 +137,7 @@ Chapter 1. Admin Guide respectively. The minor and major thresholds are described in the parameters section below. 2. The number of bytes waiting to be consumed across all of - OpenSIPSs listening ports has passed a minor or major + OpenSIPS's listening ports has passed a minor or major threshold. The idea is that a network operation centre can be made aware that a machine hosting a SIP server may be entering a degraded state, and to investigate why this is @@ -164,7 +164,7 @@ Chapter 1. Admin Guide 2. The SNMPStats modules openserSIPMsgQueueDepthMinorEvent and openserSIPMsgQueueDepthMajorEvent alarms rely on the OpenSIPS core to find out what interfaces, ports, and - transports OpenSIPS is listening on. However, the module + transports OpenSIPS is listening on. However,the module will actually query the proc file system to find out the number of bytes waiting to be consumed. (Currently, this will only work on systems providing the proc file system). @@ -173,11 +173,11 @@ Chapter 1. Admin Guide We have now explained how the SNMPStats module gathers its data. We still have not explained how it exports this data to a - NOC (Network Operations Centre), or administrator. + NOC (Network Operations Centre) or administrator. The SNMPStats module expects to connect to a Master Agent. This - would be a NetSNMP daemon running either on the same system as - the OpenSIPS instance, or on another system. (Communication can + would be a SNMP daemon running either on the same system as the + OpenSIPS instance, or on another system. (Communication can take place over TCP, so there is no restriction that this daemon need be on the same system as OpenSIPS). @@ -223,13 +223,17 @@ Chapter 1. Admin Guide The following libraries or applications must be installed before running OpenSIPS with this module loaded: - * NetSNMP v5.3 or greater - NetSNMP must be around at the - time of compilation. Furthermore, there are several shared - objects that must be loadable at the time SNMPStats is - loaded. This means that NetSNMP must be installed (but not - necessarily running) on the system that has loaded the - SNMPStats module. (Details can be found in the compilation - section below). + * Net SNMP DEV (libsnmp-dev on debian) - SNMP library + (development files) must be installed at the time of + compilation. Furthermore, there are several shared objects + that must be loadable at the time SNMPStats is loaded. This + means that SNMP lib must be installed (but not necessarily + running) on the system that has loaded the SNMPStats + module. (Details can be found in the compilation section + below). + * SNMP tools(snmp on debian) - SNMP tools package to provide + the snmpget command (internally used by the SNMPStats + module. 1.4. Exported Parameters @@ -322,7 +326,7 @@ modparam("snmpstats", "MsgQueueMajorThreshold", 5000) The SNMPStats module provides the openserSIPServiceStartTime scalar. This scalar requires the SNMPStats module to perform a snmpget query to the master agent. You can use this parameter - to set the path to your instance of NetSNMP's snmpget program. + to set the path to your instance of SNMP's snmpget program. Default value is “/usr/local/bin/”. @@ -357,77 +361,55 @@ modparam("snmpstats", "snmpCommunity", "customCommunityString") 1.6.1. Compiling the SNMPStats Module - In order for the SNMPStats module to compile, you will need at - least version 5.3 of the NetSNMP source code. The source can be - found at: - http://net-snmp.sourceforge.net/ - - For the specifics of installing NetSNMP, please see the INSTALL - document in the root of the NetSNMP source package. - - The SNMPStats modules makefile requires that the NetSNMP script - "net-snmp-config" can run. At a minimum, running - "net-snmp-config --agent-libs" from the OpenSIPS source - directory should return something similar to: - -L/usr/local/lib -lnetsnmpmibs -lnetsnmpagent -lnetsnmphelpers -lnet -snmp - - The specifics of what is returned depends on how the system was - configured. If your NetSNMP installation was installed from an - RPM (or another packaged version), then there is a good chance - that net-snmp-config will return something unecessarily longer. - It is highly recommended you install NetSNMP from source to - avoid bringing in excessive dependencies to the SNMPStats - module. - -1.6.2. Configuring NetSNMP to allow connections from the SNMPStats -module. - - The SNMPStats module will communicate with the NetSNMP Master + In order for the SNMPStats module to compile, you will need to + have installed the packages providing SNMP (Simple Network + Management Protocol) libray and development files. + + The SNMPStats modules makefile requires that the SNMP script + "net-snmp-config" can run. + +1.6.2. Configuring SNMP daemon to allow connections from the +SNMPStats module. + + The SNMPStats module will communicate with the SNMP Master Agent. This communication happens over a protocol known as - AgentX. This means that NetSNMP must have been compiled with - AgentX support. This will always be the case when you are - compiling from source unless you explicitly removed AgentX - support with ./configure. - - After AgentX support has been compiled into NetSNMP, its - configuration file needs to be changed to turn on AgentX - support. The exact location of the configuration file - (snmpd.conf) may vary depending on your system. On my system, - it is located in: - /usr/local/share/snmp/snmpd.conf. + AgentX. This means you need to have an SMP daemon (acting as + Master Agent) running - it can be on the same machine or on a + different one. + + First you need to turn on AgentX support. The exact location of + the configuration file (snmpd.conf) may vary depending on your + system. By default, via a package installation, it is located + in: + /etc/snmp/snmpd.conf. At the very end of the file add the following line: master agentx - The line tells NetSNMP to act as an AgentX master agent, so + The line tells SNMP daemon to act as an AgentX master agent, so that it can accept connections from sub-agents such as the SNMPStats module. - There is still one last step. Even though we have compiled and - configured NetSNMP to have AgentX support, we still need to - tell the daemon which interface and port to listen to for - AgentX connections. This is done when the daemon is started as - follows: - snmpd -x mySystemName:PortNumber - - On my system, I start the NetSNMP daemon with: - snmpd -x localhost:705 + There is still one last step. Even though we have configured + SNMP to have AgentX support, we still need to tell the daemon + which interface and port to listen to for AgentX connections. + This is done also via the configuration file (snmpd.conf) : + agentXSocket tcp:localhost:705 - This tells NetSNMP to act as a master agent, listening on the - localhost UDP interface at port 705. + This tells SNMP daemon to act as a master agent, listening on + the localhost UDP interface at port 705. 1.6.3. Configuring the SNMPStats module for communication with a Master Agent - The previous section explained how to set up a NetSNMP master + The previous section explained how to set up a SNMP master agent to accept AgentX connections. We now need to tell the SNMPStats module how to communicate with this master agent. - This is done by giving the SNMPStats module its own NetSNMP - configuration file. The file must be named snmpstats.conf, and - must be in the same folder as the snmpd.conf file that was - configured above. On my system this would be: - /usr/local/share/snmp/snmpstats.conf + This is done by giving the SNMPStats module its own SNMP + configuration file. The file must be named "snmpstats.conf", + and must be in the same folder as the "snmpd.conf" file that + was configured above. By default this would be: + /etc/snmp/snmpstats.conf The default configuration file included with the distribution can be used, and contains the following: @@ -437,13 +419,15 @@ Master Agent master agent on the localhost, port 705. The parameters should match up with the snmpd process. Note that the master agent (snmpd) does not need to be present on the same machine as - OpenSIPS. localhost could be replaced with any other machine. + OpenSIPS. The localhost could be replaced with any other + machine. 1.6.4. Testing for a proper Configuration As a quick test to make sure that the SNMPStats module - sub-agent can succesfully connect to the NetSNMP Master agent, - start snmpd with the following: + sub-agent can succesfully connect to the SNMP Master agent, be + sure the snmpd service is stopped (/etc/init.d/snmpd stop) and + manually start snmpd with the following: snmpd -f -Dagentx -x tcp:localhost:705 2>&1 | less You should see something similar to the following: @@ -469,8 +453,8 @@ Master Agent because of the -Dagentx snmpd switch. The large number of debug messages appear at startup as the SNMPStats module registers all of its scalars and tables with the Master Agent. If you - receive these messages, then SNMPStats module and NetSNMP - daemon have both been configured correctly. + receive these messages, then SNMPStats module and SNMP daemon + have both been configured correctly. Chapter 2. Frequently Asked Questions diff --git a/modules/snmpstats/doc/snmpstats_admin.xml b/modules/snmpstats/doc/snmpstats_admin.xml index 721b8015cd..77eeb158ec 100644 --- a/modules/snmpstats/doc/snmpstats_admin.xml +++ b/modules/snmpstats/doc/snmpstats_admin.xml @@ -9,36 +9,40 @@ The SNMPStats module provides an SNMP management interface to OpenSIPS. Specifically, it provides general SNMP queryable - scalar statistics, table representations of more complicated data such as - user and contact information, and alarm monitoring capabilities. + scalar statistics, table representations of more complicated data + such as user and contact information, and alarm monitoring + capabilities.
General Scalar Statistics - The SNMPStats module provides a number of general scalar statistics. + The SNMPStats module provides a number of general scalar + statistics. Details are available in OPENSER-MIB, OPENSER-REG-MIB, - OPENSER-SIP-COMMON-MIB, and OPENSER-SIP-SERVER-MIB. But briefly, + OPENSER-SIP-COMMON-MIB, and OPENSER-SIP-SERVER-MIB. But briefly, these scalars are: - openserSIPProtocolVersion, openserSIPServiceStartTime, openserSIPEntityType, + openserSIPProtocolVersion, openserSIPServiceStartTime, + openserSIPEntityType, openserSIPSummaryInRequests, openserSIPSummaryOutRequest, openserSIPSummaryInResponses, openserSIPSummaryOutResponses, openserSIPSummaryTotalTransactions, openserSIPCurrentTransactions, openserSIPNumUnsupportedUris, openserSIPNumUnsupportedMethods, openserSIPOtherwiseDiscardedMsgs, openserSIPProxyStatefulness openserSIPProxyRecordRoute, openserSIPProxyAuthMethod, - openserSIPNumProxyRequireFailures, openserSIPRegMaxContactExpiryDuration, + openserSIPNumProxyRequireFailures, + openserSIPRegMaxContactExpiryDuration, openserSIPRegMaxUsers, openserSIPRegCurrentUsers, - openserSIPRegDfltRegActiveInterval, openserSIPRegAcceptedRegistrations, + openserSIPRegDfltRegActiveInterval, + openserSIPRegAcceptedRegistrations, openserSIPRegRejectedRegistrations, openserMsgQueueDepth. openserCurNumDialogs, openserCurNumDialogsInProgress, openserCurNumDialogsInSetup, openserTotalNumFailedDialogSetups - There are also scalars associated with alarms. They are as follows: + There are also scalars associated with alarms. They are as follows: - openserMsgQueueMinorThreshold, openserMsgQueueMajorThreshold, openserMsgQueueDepthAlarmStatus, openserMsgQueueDepthMinorAlarm, @@ -51,30 +55,30 @@
SNMP Tables - The SNMPStats module provides several tables, containing more complicated - data. The current available tables are: + The SNMPStats module provides several tables, containing more + complicated data. The current available tables are: openserSIPPortTable, openserSIPMethodSupportedTable, - openserSIPStatusCodesTable, openserSIPRegUserTable, openserSIPContactTable, - openserSIPRegUserLookupTable + openserSIPStatusCodesTable, openserSIPRegUserTable, + openserSIPContactTable, openserSIPRegUserLookupTable
Alarm Monitoring - If enabled, the SNMPStats module will monitor for alarm conditions. - Currently, there are two alarm types defined. + If enabled, the SNMPStats module will monitor for alarm conditions. + Currently, there are two alarm types defined. - The number of active dialogs has passed a minor or major threshold. - The idea is that a network operation centre can be made aware that - their SIP servers may be overloaded, without having to explicitly - check for this condition. + The number of active dialogs has passed a minor or major + threshold. The idea is that a network operation centre can + be made aware that their SIP servers may be overloaded, + without having to explicitly check for this condition. If a minor or major condition has occured, then a @@ -86,23 +90,24 @@ - The number of bytes waiting to be consumed across all of OpenSIPSs - listening ports has passed a minor or major threshold. The idea is - that a network operation centre can be made aware that a machine - hosting a SIP server may be entering a degraded state, and to - investigate why this is so. + The number of bytes waiting to be consumed across all of + OpenSIPS's listening ports has passed a minor or major + threshold. The idea is that a network operation centre can + be made aware that a machine hosting a SIP server may be + entering a degraded state, and to investigate why this is so. If the number of bytes to be consumed passes a minor or major threshold, then a openserMsgQueueDepthMinorEvent or - openserMsgQueueDepthMajorEvent trap will be sent out, respectively. + openserMsgQueueDepthMajorEvent trap will be sent out, + respectively. - Full details of these traps can be found in the distributions OPENSER-MIB - file. + Full details of these traps can be found in the distributions + OPENSER-MIB file.
@@ -114,24 +119,26 @@
How the SNMPStats module gets its data - The SNMPStats module uses OpenSIPSs internal statistic framework to collect most of its - data. However, there are two exceptions. + The SNMPStats module uses OpenSIPSs internal statistic framework to + collect most of its data. However, there are two exceptions. - The openserSIPRegUserTable and openserSIPContactTable rely on the usrloc - modules callback system. Specifically, the SNMPStats module will receive - callbacks whenever a user/contact is added to the system. + The openserSIPRegUserTable and openserSIPContactTable rely on the + usrloc modules callback system. Specifically, the SNMPStats + module will receive callbacks whenever a user/contact is added to + the system. The SNMPStats modules openserSIPMsgQueueDepthMinorEvent and - openserSIPMsgQueueDepthMajorEvent alarms rely on the OpenSIPS core to find out - what interfaces, ports, and transports OpenSIPS is listening on. However, - the module will actually query the proc file system to find out the number - of bytes waiting to be consumed. (Currently, this will only work on systems - providing the proc file system). + openserSIPMsgQueueDepthMajorEvent alarms rely on the OpenSIPS + core to find out what interfaces, ports, and transports OpenSIPS + is listening on. However,the module will actually query the proc + file system to find out the number of bytes waiting to be consumed. + (Currently, this will only work on systems providing the proc file + system). @@ -140,28 +147,32 @@
How data is moved from the SNMPStats module to a NOC - We have now explained how the SNMPStats module gathers its data. We still have not - explained how it exports this data to a NOC (Network Operations Centre), or - administrator. + We have now explained how the SNMPStats module gathers its data. We still + have not explained how it exports this data to a NOC (Network Operations + Centre) or administrator. - The SNMPStats module expects to connect to a Master Agent. This - would be a NetSNMP daemon running either on the same system as the OpenSIPS instance, or - on another system. (Communication can take place over TCP, so there is no restriction + The SNMPStats module expects to connect to a + Master Agent. This would be a SNMP daemon running + either on the same system as the OpenSIPS instance, or on another system. + (Communication can take place over TCP, so there is no restriction that this daemon need be on the same system as OpenSIPS). - If the master agent is unavailable when OpenSIPS first starts up, the SNMPStats module will - continue to run. However, you will not be able to query it. Thankfully, the SNMPStats - module continually looks for its master agent. So even if the master agent is started late, - or if the link to the SNMPStats module is severed due to a temporary hardware failure - or crashed and restarted master agent, the link will eventually be re-established. No - data should be lost, and querying can begin again. + If the master agent is unavailable when OpenSIPS first starts up, the + SNMPStats module will continue to run. However, you will not be able to + query it. Thankfully, the SNMPStats module continually looks for its + master agent. So even if the master agent is started late, + or if the link to the SNMPStats module is severed due to a temporary + hardware failure or crashed and restarted master agent, the link will + eventually be re-established. No data should be lost, and querying can + begin again. - To request for this data, you will need to query the master agent. The master agent will - then redirect the request to the SNMPStats module, which will respond to the master agent, - which will in turn respond to your request. + To request for this data, you will need to query the master agent. The + master agent will then redirect the request to the SNMPStats module, which + will respond to the master agent, which will in turn respond to + your request.
@@ -172,34 +183,36 @@
&osips; Modules - The SNMPStats module provides a plethora of statistics, some of which are collected - by other modules. If the dependent modules are not loaded then those specific - statistics will still be returned, but with zeroed values. All other statistics will - continue to function normally. This means that the SNMPStats module has no - hard/mandatory dependencies on other modules. There are however, - soft dependencies, as follows: + The SNMPStats module provides a plethora of statistics, some of which + are collected by other modules. If the dependent modules are not + loaded then those specific statistics will still be returned, but with + zeroed values. All other statistics will continue to function + normally. This means that the SNMPStats module has no + hard/mandatory dependencies on other modules. + There are however, soft dependencies, as follows: - usrloc - all scalars and tables relating to users and contacts are - dependent on the usrloc module. If the module is not loaded, the respective tables - will be empty. + usrloc - all scalars and tables relating to users + and contacts are dependent on the usrloc module. If the module is + not loaded, the respective tables will be empty. - dialog - all scalars relating to the number of dialogs are - dependent on the presence of the dialog module. Furthermore, if the module is - not loaded, then the openserDialogLimitMinorEvent, and openserDialogLimitMajorEvent - alarm will be disabled. + dialog - all scalars relating to the number of + dialogs are dependent on the presence of the dialog module. + Furthermore, if the module is not loaded, then the + openserDialogLimitMinorEvent, and openserDialogLimitMajorEvent + alarm will be disabled. - The contents of the openserSIPMethodSupportedTable change depending on which modules - are loaded. + The contents of the openserSIPMethodSupportedTable change depending + on which modules are loaded.
@@ -210,12 +223,20 @@ - NetSNMP v5.3 or greater - NetSNMP must be around - at the time of compilation. Furthermore, there are several shared objects - that must be loadable at the time SNMPStats is loaded. This means that - NetSNMP must be installed (but not necessarily running) on the system that - has loaded the SNMPStats module. (Details can be found in the compilation - section below). + Net SNMP DEV (libsnmp-dev on debian) - SNMP + library (development files) must + be installed at the time of compilation. Furthermore, there are + several shared objects that must be loadable at the time SNMPStats + is loaded. This means that SNMP lib must be installed (but not + necessarily running) on the system that has loaded the SNMPStats + module. (Details can be found in the compilation section below). + + + + + SNMP tools(snmp on debian) - SNMP + tools package to provide the snmpget command (internally used by + the SNMPStats module. @@ -250,9 +271,9 @@ modparam("snmpstats", "sipEntityType", "proxyServer") - Note that as the above example shows, you can define this parameter more - than once. This is of course because a given OpenSIPS instance can take on - more than one role. + Note that as the above example shows, you can define this parameter + more than once. This is of course because a given OpenSIPS instance + can take on more than one role.
@@ -260,11 +281,12 @@ modparam("snmpstats", "sipEntityType", "proxyServer") <varname>MsgQueueMinorThreshold</varname> (Integer) - The SNMPStats module monitors the number of bytes waiting to be consumed by - OpenSIPS. If the number of bytes waiting to be consumed exceeds a minor - threshold, the SNMPStats module will send out an openserMsgQueueDepthMinorEvent - trap to signal that an alarm condition has occured. The minor threshold is set - with the MsgQueueMinorThreshold parameter. + The SNMPStats module monitors the number of bytes waiting to be + consumed by OpenSIPS. If the number of bytes waiting to be consumed + exceeds a minor threshold, the SNMPStats module will send out an + openserMsgQueueDepthMinorEvent trap to signal that an alarm condition + has occured. The minor threshold is set with the + MsgQueueMinorThreshold parameter. @@ -277,7 +299,8 @@ modparam("snmpstats", "MsgQueueMinorThreshold", 2000) - If this parameter is not set, then there will be no minor alarm monitoring. + If this parameter is not set, then there will be no minor alarm + monitoring.
@@ -285,15 +308,17 @@ modparam("snmpstats", "MsgQueueMinorThreshold", 2000) <varname>MsgQueueMajorThreshold</varname> (Integer) - The SNMPStats module monitors the number of bytes waiting to be consumed by - OpenSIPS. If the number of bytes waiting to be consumed exceeds a major - threshold, the SNMPStats module will send out an openserMsgQueueDepthMajorEvent - trap to signal that an alarm condition has occured. The major threshold is set - with the MsgQueueMajorThreshold parameter. + The SNMPStats module monitors the number of bytes waiting to be + consumed by OpenSIPS. If the number of bytes waiting to be consumed + exceeds a major threshold, the SNMPStats module will send out an + openserMsgQueueDepthMajorEvent trap to signal that an alarm condition + has occured. The major threshold is set with the + MsgQueueMajorThreshold parameter. - Setting the <varname>MsgQueueMajorThreshold</varname> parameter + Setting the <varname>MsgQueueMajorThreshold</varname> parameter + ... modparam("snmpstats", "MsgQueueMajorThreshold", 5000) @@ -302,7 +327,8 @@ modparam("snmpstats", "MsgQueueMajorThreshold", 5000) - If this parameter is not set, then there will be no major alarm monitoring. + If this parameter is not set, then there will be no major alarm + monitoring. @@ -310,14 +336,16 @@ modparam("snmpstats", "MsgQueueMajorThreshold", 5000) <varname>dlg_minor_threshold</varname> (Integer) - The SNMPStats module monitors the number of active dialogs. If the number of - active dialogs exceeds a minor threshold, the SNMPStats module will send out - an openserDialogLimitMinorEvent trap to signal that an alarm condition has - occured. The minor threshold is set with the dlg_minor_threshold parameter. + The SNMPStats module monitors the number of active dialogs. If the + number of active dialogs exceeds a minor threshold, the SNMPStats + module will send out an openserDialogLimitMinorEvent trap to signal + that an alarm condition has occured. The minor threshold is set with + the dlg_minor_threshold parameter. - Setting the <varname>dlg_minor_threshold</varname> parameter + Setting the <varname>dlg_minor_threshold</varname> parameter + ... modparam("snmpstats", "dlg_minor_threshold", 500) @@ -326,7 +354,8 @@ modparam("snmpstats", "MsgQueueMajorThreshold", 5000) - If this parameter is not set, then there will be no minor alarm monitoring. + If this parameter is not set, then there will be no minor alarm + monitoring. @@ -334,14 +363,16 @@ modparam("snmpstats", "MsgQueueMajorThreshold", 5000) <varname>dlg_major_threshold</varname> (Integer) - The SNMPStats module monitors the number of active dialogs. If the number of - active dialogs exceeds a major threshold, the SNMPStats module will send out - an openserDialogLimitMajorEvent trap to signal that an alarm condition has - occured. The major threshold is set with the dlg_major_threshold parameter. + The SNMPStats module monitors the number of active dialogs. If + the number of active dialogs exceeds a major threshold, the SNMPStats + module will send out an openserDialogLimitMajorEvent trap to signal + that an alarm condition has occured. The major threshold is set + with the dlg_major_threshold parameter. - Setting the <varname>dlg_major_threshold</varname> parameter + Setting the <varname>dlg_major_threshold</varname> parameter + ... modparam("snmpstats", "dlg_major_threshold", 750) @@ -350,7 +381,8 @@ modparam("snmpstats", "MsgQueueMajorThreshold", 5000) - If this parameter is not set, then there will be no major alarm monitoring. + If this parameter is not set, then there will be no major alarm + monitoring. @@ -361,7 +393,7 @@ modparam("snmpstats", "MsgQueueMajorThreshold", 5000) The SNMPStats module provides the openserSIPServiceStartTime scalar. This scalar requires the SNMPStats module to perform a snmpget query to the master agent. You can use this parameter to set the path to - your instance of NetSNMP's snmpget program. + your instance of SNMP's snmpget program. @@ -387,7 +419,7 @@ modparam("snmpstats", "snmpgetPath", "/my/custom/path/") The SNMPStats module provides the openserSIPServiceStartTime scalar. This scalar requires the SNMPStats module to perform a snmpget query to the master agent. If you have defined a custom community string - for the snmp daemon, you need to specify it with this parameter. + for the snmp daemon, you need to specify it with this parameter. @@ -425,84 +457,51 @@ modparam("snmpstats", "snmpCommunity", "customCommunityString") Compiling the SNMPStats Module - In order for the SNMPStats module to compile, you will need at least version - 5.3 of the NetSNMP source code. The source can be found at: - - - http://net-snmp.sourceforge.net/ - - - For the specifics of installing NetSNMP, please see the INSTALL document in the - root of the NetSNMP source package. + In order for the SNMPStats module to compile, you will need to have + installed the packages providing SNMP (Simple Network Management + Protocol) libray and development files. - The SNMPStats modules makefile requires that the NetSNMP script - "net-snmp-config" can run. At a minimum, running "net-snmp-config --agent-libs" - from the OpenSIPS source directory should return something similar to: - - - -L/usr/local/lib -lnetsnmpmibs -lnetsnmpagent -lnetsnmphelpers -lnetsnmp - - - The specifics of what is returned depends on how the system was configured. If - your NetSNMP installation was installed from an RPM (or another packaged - version), then there is a good chance that net-snmp-config will return - something unecessarily longer. It is highly recommended you install NetSNMP - from source to avoid bringing in excessive dependencies to the SNMPStats - module. + The SNMPStats modules makefile requires that the SNMP script + "net-snmp-config" can run. - +
- Configuring NetSNMP to allow connections from the SNMPStats module. + Configuring SNMP daemon to allow connections from the SNMPStats module. - The SNMPStats module will communicate with the NetSNMP Master Agent. This - communication happens over a protocol known as AgentX. This means that NetSNMP - must have been compiled with AgentX support. This will always be the case when - you are compiling from source unless you explicitly removed AgentX support with - ./configure. + The SNMPStats module will communicate with the SNMP Master Agent. This + communication happens over a protocol known as AgentX. This means you + need to have an SMP daemon (acting as Master Agent) running - it can + be on the same machine or on a different one. - - After AgentX support has been compiled into NetSNMP, its configuration file needs - to be changed to turn on AgentX support. The exact location of the configuration - file (snmpd.conf) may vary depending on your system. On my system, it is located in: - + First you need to turn on AgentX support. The exact location of + the configuration file (snmpd.conf) may vary depending on your system. + By default, via a package installation, it is located in: - /usr/local/share/snmp/snmpd.conf. - - + /etc/snmp/snmpd.conf. + At the very end of the file add the following line: - master agentx - - The line tells NetSNMP to act as an AgentX master agent, so that it can accept - connections from sub-agents such as the SNMPStats module. + The line tells SNMP daemon to act as an AgentX master agent, so that it + can accept connections from sub-agents such as the SNMPStats module. - - There is still one last step. Even though we have compiled and configured NetSNMP - to have AgentX support, we still need to tell the daemon which interface and - port to listen to for AgentX connections. This is done when the daemon is started - as follows: - + There is still one last step. Even though we have configured + SNMP to have AgentX support, we still need to tell the daemon which + interface and port to listen to for AgentX connections. This is done also + via the configuration file (snmpd.conf) : - snmpd -x mySystemName:PortNumber + agentXSocket tcp:localhost:705 - - On my system, I start the NetSNMP daemon with: - - - snmpd -x localhost:705 - - - This tells NetSNMP to act as a master agent, listening on the localhost UDP - interface at port 705. + This tells SNMP daemon to act as a master agent, listening on the + localhost UDP interface at port 705.
@@ -511,28 +510,26 @@ modparam("snmpstats", "snmpCommunity", "customCommunityString") Configuring the SNMPStats module for communication with a Master Agent - The previous section explained how to set up a NetSNMP master agent to accept - AgentX connections. We now need to tell the SNMPStats module how to communicate - with this master agent. This is done by giving the SNMPStats module its own - NetSNMP configuration file. The file must be named snmpstats.conf, and must be - in the same folder as the snmpd.conf file that was configured above. On my - system this would be: - + The previous section explained how to set up a SNMP master agent to accept + AgentX connections. We now need to tell the SNMPStats module how to + communicate with this master agent. This is done by giving the + SNMPStats module its own SNMP configuration file. The file must be named + "snmpstats.conf", and must be in the same folder as the "snmpd.conf" file + that was configured above. By default this would be: - /usr/local/share/snmp/snmpstats.conf + /etc/snmp/snmpstats.conf - - The default configuration file included with the distribution can be used, and - contains the following: - + The default configuration file included with the distribution can be used, + and contains the following: agentXSocket tcp:localhost:705 - - The above line tells the SNMPStats module to register with the master agent on - the localhost, port 705. The parameters should match up with the snmpd process. + The above line tells the SNMPStats module to register with the master + agent on the localhost, port 705. The parameters should match up with + the snmpd process. Note that the master agent (snmpd) does not need to be present on the same - machine as OpenSIPS. localhost could be replaced with any other machine. + machine as OpenSIPS. The localhost could be replaced with any other + machine. @@ -541,15 +538,14 @@ modparam("snmpstats", "snmpCommunity", "customCommunityString") Testing for a proper Configuration - As a quick test to make sure that the SNMPStats module sub-agent can succesfully - connect to the NetSNMP Master agent, start snmpd with the following: - + As a quick test to make sure that the SNMPStats module sub-agent can + succesfully connect to the SNMP Master agent, be sure the snmpd service + is stopped (/etc/init.d/snmpd stop) and manually start snmpd with the + following: snmpd -f -Dagentx -x tcp:localhost:705 2>&1 | less - You should see something similar to the following: - No log handling enabled - turning on stderr logging registered debug token agentx, 1 @@ -559,10 +555,8 @@ modparam("snmpstats", "snmpCommunity", "customCommunityString") agentx/master: initializing... DONE NET-SNMP version 5.3.1 - - Now, start up OpenSIPS in another window. In the snmpd window, you should see a - bunch of: - + Now, start up OpenSIPS in another window. In the snmpd window, you should + see a bunch of: agentx/master: handle pdu (req=0x2c58ebd4,trans=0x0,sess=0x0) agentx/master: open 0x81137c0 @@ -570,12 +564,12 @@ modparam("snmpstats", "snmpCommunity", "customCommunityString") agentx/master: send response, stat 0 (req=0x2c58ebd4,trans=0x0,sess=0x0) agentx_build: packet built okay - - The messages beginning with "agentx" are debug messages stating that something is happening - with an AgentX sub-agent, appearing because of the -Dagentx snmpd switch. The large number - of debug messages appear at startup as the SNMPStats module registers all of its scalars - and tables with the Master Agent. If you receive these messages, then SNMPStats module - and NetSNMP daemon have both been configured correctly. + The messages beginning with "agentx" are debug messages stating that + something is happening with an AgentX sub-agent, appearing because of + the -Dagentx snmpd switch. The large number of debug messages appear at + startup as the SNMPStats module registers all of its scalars + and tables with the Master Agent. If you receive these messages, then + SNMPStats module and SNMP daemon have both been configured correctly.