Describes the procedure to write SNMP custom collector.
Create templates for the following in the collector-package/templates directory
collector-manager
Conf
Collecting.xml.ftl
kafka-connector
conf
kafka-connector.xml.ftl
snmp-collector
Conf
agents-groups.xml.ftl
slave-snmp-polller.xml.ftl
snmp-masks.xml
snmp-polling-distributions.xml
snmpcollector.xml
translations.xml
mibs
INET-ADDRESS-MIB.txt
PROJECT-CLEARWATER-MIB
variable-handling-filter
conf
property-ICSCFSessionEstablishmentNetworkTable.xml property
ICSCFSessionEstablishmentTable.xml property
QueueSuccessFailSuccessPercent.xml propertyS
CSCFInitialRegistrationTable.xml vhf-bono.xml.ftl
Custom filters files if required
Create the following files in the collector-package directory
meta_en.properties - metadata info for the Collectors.
questions.txt - defined user configured parameters for the collectors
questions_en.properties-- display values / description for Questions.txt
spb.properties-- versions and dependent modules along with respective versions
default.txt -default values for user configurable parameter
Collector-manager :
Collecting.xml.ftl
in this file user can define the collectors , Filters and Connectors configuration for the Collector.
<config>
<collectors>
<collector name=” Collector1 ” next=” Filter1 ”>
<!−− Collector1 will send data to Filter1 −−>
</ collector>
<collector name=”Collector2” next=”Filter1 Connector1”>
<!−− Collector2 will send data to Filter1 and Connector1 −−>
</ collector>
</ collectors>
<filters>
<filter name=” Filter1 ” next=”Connector1”>
<!−− Filter1 will send data to Filter1 −−>
</ filter>
</filters>
<connectors>
<connector name=”Connector1”> <!−− Connector1 will send data</connector>
</connectors>
</config>
Collecting.xml.ftl
[#ftl]
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns="http://www.watch4net.com/APG/Collecting" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.watch4net.com/APG/Collecting collecting.xsd ">
<collectors>
<collector enabled="true" name="CLEARWATER-SNMP" next="Param-CLEANUP" config="SNMP-Collector/${module['snmp-collector'].instance}/conf/snmpcollector.xml" />
</collectors>
<filters>
<filter enabled="true" name="Param-CLEANUP" next="Metric-Format" config="Variable-Handling-Filter/${module['variable-handling-filter'].instance}/conf/vhf-param-cleanup.xml"/>
</filters>
<connectors>
<connector enabled="true" name="Kafka" type="Kafka-Connector" config="Kafka-Connector/${module['kafka-connector'].instance}/conf/kafka-connector.xml" />
</connectors>
</config>
Snmpcollector.xml:
The config file, usually named snmpcollector.xml, contains the path and names of the XML files required to configure the SNMP Collector.
<?xml version="1.0" encoding="UTF-8"?> <config> <secondary-snmp-poller-file>conf/slave-snmp-poller.xml</secondary-snmp-poller-file> <snmp-masks-file>conf/snmp-masks.xml</snmp-masks-file> <snmp-polling-distribution-file>conf/snmp-polling-distribution.xml</snmp-polling-distribution-file> <translations-file>conf/translations.xml</translations-file> <mib-files-directory>mibs</mib-files-directory> </config>
It is recommend that those file names and path be kept unchanged unless several in- stances of the SNMP Collector are defined in the collecting.xml XML file. Moreover, please note that the basic configuration provided with the SNMP Collector is inert, in the sense that the SNMP Collector will launch along with the other configured collectors but it will not collect anything until the polling distribution (snmp-polling-distribution.xml) and SNMP collecting (snmp-masks.xml) have been configured.
slave-snmp-poller.xml
This XML file describes how the SNMP Collector will interact with its host networking hardware.
<?xml version="1.0" encoding="UTF-8"?>
<local-communication-settings hostIpAddress="localhost" communicationPort="2008" communicationInterfaceIPAddress="10.128.1.28" maxConcurrentSessions="48">
<out-interface-ip-addresses>
<out-interface-ip-address>10.128.9.29</out-interface-ip-address>
</out-interface-ip-addresses>
<accept-commands-from-list>
<accept-commands-from>10.128.1.25</accept-commands-from>
</accept-commands-from-list>
</local-communication-settings>
<polling-group>
</polling-group>
slave-snmp-poller.xml
[#ftl]
<?xml version="1.0" encoding="UTF-8"?>
[#assign sprout_pollingperiod=sproutpollingperiod]
[#assign bono_pollingperiod=bonopollingperiod]
<slave-snmp-poller name="ClearwaterCollector" pollerPrefix="SNMP-CLEARWATER" groupName="group" oidsThreads="100" tablesThreads="100" alwaysPushProperties="true" handleCounterWrapAround="true" usePollerPrefixInVariable="false" oidAsPropertyInRawValues="false">
<local-communication-settings hostIpAddress="localhost" communicationPort="52006" communicationInterfaceIPAddress="0.0.0.0" maxConcurrentSessions="98">
<out-interface-ip-addresses>
<out-interface-ip-address>0.0.0.0</out-interface-ip-address>
</out-interface-ip-addresses>
<accept-commands-from-list />
</local-communication-settings>
<polling-group name="PG_CLEARWATER-SPROUT" pollingPeriod="${sprout_pollingperiod}" tableDiscoveryTime="00:42:00" groupName="group" uniformTimestamps="false" startAtDefinedPeriod="false" enabled="true" startTimeOffset="0">
<polling-masks>
<polling-mask-name>CLEARWATER-SPROUT</polling-mask-name>
</polling-masks>
<polled-snmp-agents>
<snmp-agents-explicit-group-name>PG_CLEARWATER-SPROUT</snmp-agents-explicit-group-name>
</polled-snmp-agents>
</polling-group>
<polling-group name="PG_CLEARWATER-BONO" pollingPeriod="${bono_pollingperiod}" tableDiscoveryTime="00:42:00" groupName="group" uniformTimestamps="false" startAtDefinedPeriod="false" enabled="true" startTimeOffset="0">
<polling-masks>
<polling-mask-name>CLEARWATER-BONO</polling-mask-name>
</polling-masks>
<polled-snmp-agents>
<snmp-agents-explicit-group-name>PG_CLEARWATER-BONO</snmp-agents-explicit-group-name>
</polled-snmp-agents>
</polling-group>
</slave-snmp-poller>
Config details :
The first configuration line of the slave-snmp-poller.xml file describes the SNMP Collector’s runtime parameters:
<secondary-snmp-poller name="secondary1" pollerPrefix="thisPollerOnThatNetwork" groupName="group3600" oidsThreads="100" tablesThreads="100">
• name: This attribute identifies the SNMP Collector. It is also used to identify the list of SNMP agents to use in the snmp-polling-distribution file. This name must be unique among all used SNMP Collectors.
• pollerPrefix: This attribute contains the value for source property. All raw values generated by this collector will have their source property set to this value.
• usePollerPrefixInVariable: Setting this to “true” adds the poller prefix to the generated raw values variables. This has the effect of effectively binding the polled raw values from a SNMP Agent to its collector’s pollerPrefix. This can be beneficial when several collectors are used to poll different networks with overlapping IP addresses.
However, this behavior causes problems when using a distributed polling configuration, where the SNMP Agent may be polled by any collector.
There are two solutions to this problem:
– Use the same pollerPrefix on all SnmpCollectors and
set usePollerPrefixInVariable=“true”.
The poller prefix will still be in the raw value variable, thus binding this value (and SNMP Agent) to a specific group of SNMP Collectors which share the same pollerPrefix. This can be used when polling a network with several SNMP Collectors. A typical use case for this is when several networks, belonging to several clients, are polled by more than two SNMP Collector per network. Those individual networks could belong to distinct clients, causing IP Address overlapping. In this specific case, the poller prefix would in fact represent the network name (or the name of the client who actually uses or own this network).
– Use different poller Prefix on the SNMP Collectors and
setusePollerPrefixInVariable=“false”.
This may be used when several SNMP Collectors are used to poll a network without IP Ad- dress overlapping. In this case, the polling is distributed among several collectors and a specific SNMP Agent may be polled by any of them at any one time. No effect will be seen on the polled raw value variables when the SNMP Agent switches poller as the pollerPrefix is not part of the variable.
• groupName:This attribute contains the retention group name.The valid group names are defined in the config.xml file. All raw values generated by this collector will have their group property set to this value, unless it is overridden in the polling group where the raw value comes from.
• oidsThreads: The maximum number of threads used to poll single oids.
• tablesThreads: The maximum number of threads used to poll tables.
• alwaysPushProperties: Set this to “true” to send the raw values properties on every polling cycle. This is the default behaviour. Setting this to false will remove the properties from raw values, except when they are being refreshed.
• oidAsPropertyInRawValues: Setting this to “true” adds the polled oid to every raw value output by the SNMP Collector. This may be useful for debugging purposes. The default behaviour is not to add the oid to the raw value.
• handleCounterWrapAround:Settingthisto“true”ensuresthecollectorhandlescorrectlyacounter that wraps around (counter that resets to 0).
• configVersion: Configuration version. Should match SNMP collector’s version.
One must note the importance of setting the Threads attributes with adequate values as they will directly impact the SNMP collector’s performance. Providing values that are too small will cause contention at the thread level, therefore dramatically slowing down the polling process, while providing an excessively large value may have adverse consequences on system performance due to memory consumption and thread scheduling.
The following are guidelines to set “Threads” attributes values for a polling group:
• 1 oidThread per (SNMP Agent times snmp-oids) element.
• 1 tableThread per (SNMP Agent times snmp-table) element.
Basically, one should try to find out which of the polling-group is the most demanding for every Thread type (oidThread and tableThread) and assign the maximum calculated value for each Thread type to the Thread attribute. Experience will alow you to reduce those numbers in order to find the sweet spot between system load and polling time for every polling groups. These times are available in the collecting*.log files.
The second configuration block in the slave-snmp-poller.xml file defines the SNMP collector’s networking parameters:
<local-communication-settings hostIpAddress="localhost" communicationPort="2008" communicationInterfaceIPAddress="10.128.1.28" maxConcurrentSessions="300">
<out-interface-ip-addresses>
<out-interface-ip-address>10.128.9.29</out-interface-ip-address>
</out-interface-ip-addresses>
<accept-commands-from-list>
<accept-commands-from>10.128.1.25</accept-commands-from>
</accept-commands-from-list>
</local-communication-settings>
The local-communication-setting element has the following attributes:
• hostIpAddress: This specifies the collector’s host ip address.
• communicationPort: This specifies the collector’s communication command port. This port is used to receive SNMP requests as well as control and configuration commands from EMC M&R’s mib browser.
• communicationInferfaceIPAddress: This specifies the ip address of the interface on which the communication command port is bound. This attribute is optional as all of the host’s defined interfaces will be used if it is not specified.
• maxConcurrentSession: This specifies the maximum number of concurrent sessions used for polling.
The maxConcurrentSession attribute has a very high impact on the collector’s performance. Setting it too low will severely slow down polling performance while setting it too high may cause unexpected crashes as the system (O/S) may be unable to support a large number of connections. A good starting point for setting this value is the default, which is 98. Please check the collecting-*.log files to determine whether this is enough for the polling configuration. Increasing it will likely decrease polling times when numerous snmp-agent are polled. This setting value must be less than oidsThreads and tablesThreads.
The elements contained in the local-communication-settings element are both optional: • out-interface-ip-address: Specifies which interface to use when polling the SNMP agents. Currently, only one interface may be specified here. All available interfaces will be used for polling if none is specified here.
• accept-commands-from: Specifies the ip addresses from which SNMP requests and control commands may be sent. Adding one of those elements will tell the SNMP collector to accept commands from the specified ip address, while rejecting commands coming from any other addresses. Commands coming from all ip addresses will be accepted if no accept-commands- from element is provided.
SNMP Collector polling group configuration
The remainder of the slave-snmp-poller.xml file is used to define the polling groups:
<polling-group name="AllEquipments" pollingPeriod="10" tableDiscoveryTime="03:30:00" groupName="group1" enabled="true">
<polling-masks>
<polling-mask-name>AllEquipmentMask</polling-mask-name>
</polling-masks>
<polled-snmp-agents>
<snmp-agent-ip-address>10.128.2.28:161</snmp-agent-ip-address>
<snmp-agent-ip-address>10.128.7.2:161</snmp-agent-ip-address>
<snmp-agent-ip-address>10.128.7.1:1690</snmp-agent-ip-address>
<snmp-agent-ip-address>10.128.3.1:161</snmp-agent-ip-address>
<snmp-agents-ip-group-name>Network</snmp-agents-ip-group-name>
<snmp-agents-explicit-group-name>ExplicitGroup1</snmp-agents-explicit-group-name>
<snmp-agents-explicit-group-name>ExplicitGroup2</snmp-agents-explicit-group-name>
</polled-snmp-agents>
<subgroups>
<polling-group />
</subgroups>
</polling-group>
The polling-group element describes a polling group. Many polling groups may be defined in the slave-snmp-poller.xml file, the only limitation is that they MUST have a unique name, as it is the polling group’s identifier. The polling-group element has the following attributes: • name: The polling group’s name. As stated before, this name must be unique as it is an identifier. The value of this attribute is used to set the pollgrp property of the raw values resulting from this polling group.
• pollingPeriod: The polling group’s polling period, specified in seconds. This value indicate the time interval between each polling. 60 second is a minute, 240 seconds is 4 minutes and so on.
• tableDiscoveryTime: This attribute indicate the time at which the raw values’ properties will be refreshed, as well as any reference table resident in the SNMP collector. Refreshing the raw value’s properties may be slightly more demanding on the database side of the backend, there- fore, it is recommended to set this value at some off-hour time.
Please note that this value is formatted in 24h time, 00:00:00 being midnight, 08:00 being 8:00am, 20:00 being 8:00pm and so on. Property refresh may also be prevented by using the onRefreshPropertiesCommandOnly” value, instead of a valid 24h time. In this case, properties will be refreshed on the agent only when a refresh command is sent to the collector.
• groupName: This attribute overrides the retention group name specified in the secondary-snmp- poller element for this polling group and all of the ones defined under it.
• uniformTimestamps: When set to true, the polling will start at the next “round” period (0:04, 0:08... if polling period is set to 4 minutes) and all timestamps for the generated raw values will be the rounded to the polling cycle start time (0:04, 0:08...).
• startAtDefinedPeriod: When set to true, the polling will start at the next “round” period (0:04, 0:08... if polling period is set to 4 minutes). Raw value timestamps will be accurate.
• enabled: When set to false, the polling group will not run. True is the assumed default when not specified. This is a simple way to define polling groups but not use them.
• startTimeOffset: Setting this to a value other than 0 delays the polling group start time by ’n’ seconds. This modifies the ’startAtDefinedPeriod’ and ’uniformTimeStamps’ behavior. This attribute can be used to spread the polling group start time through a polling period window.
• polling-masks: This element set contains polling-mask-name elements. At least one polling- mask-name element must be provided per polling-group. The polling-mask-name is used to locate the correct snmp-mask in the snmp-masks.xml file. The snmp-mask element contains information about the SNMP oids to collect in this polling group. See section 6, page 30 of this document for further details on snmp-mask elements.
• polled-snmp-agents: This element set contains at least one snmp-agent-ip-address, snmp- agents-ip-group-name or snmp-agents-explicit-group-name element. These elements actually indicate which SNMP agent to poll in this polling group. SNMP agent and group definitions are done in the snmp-polling-distribution.xml file, which is presented in section 5, subsection 2 and 3 of this document. Please note that the port number should be specified when providing snmp- agent-ip-address as several agents may be running on the host specified by the ip address. If none is specified, port 161 (:161 suffix) will be used and it might not be suitable for your purposes.
• subgroups: This optional element set contains nested polling group. This allows the creation of polling groups hierarchies. These hierarchies can be used to set up polling groups by equipment types, the most general type being at the top of the hierarchy, while more specific types will be at the bottom. The following example typifies this
snmp-polling-distribution.xml
The polling distribution configuration is in fact the list of SNMP agents which may be polled by the SNMP Collector. It also defines the SNMP agents groups which may be used, alongside the individual agents, in the polling groups defined in the slave-snmp-poller.xml XML file. The snmp- polling-distribution.xml XML file describes those agents and groups:
<?xml version="1.0" encoding="UTF-8"?>
<snmp-polling-distribution>
<snmp-secondary-poller name="secondary1" enabled="true" host="10.128.2.28" port="2008" slaveSnmpPollerXmlFile="slave-snmp-poller.xml">
<snmp-agent name="Switch1" ipAddress="10.128.9.1" timeout="3000" retries="1" snmpVersion="v2c" snmpCommunityOrUserV3Name="123456" devtype="Switch"
transportProtocol="udp" snmpPort="161" maxBulkSize="50" onFailTryWith="v1"/>
<snmp-agent name="Switch2" ipAddress="10.128.9.2" timeout="3000" retries="2" snmpVersion="v2c" snmpCommunityOrUserV3Name="123" devtype="Switch" maxBulkSize="50" onFailTryWith="v2c"/>
<snmp-agent name="Switch3" ipAddress="10.128.9.3" timeout="3000" retries="2" snmpVersion="v2c" snmpCommunityOrUserV3Name="123" devtype="Switch" maxBulkSize="50" onFailTryWith="doNotRetry"/>
<snmp-agent name="Switch4" ipAddress="10.128.9.4" timeout="3000" retries="2" snmpVersion="v2c" snmpCommunityOrUserV3Name="123" devtype="Switch" maxBulkSize="20"/>
<snmp-agent name="Switch7" ipAddress="10.128.9.7" timeout="3000" retries="2" snmpVersion="v2c" snmpCommunityOrUserV3Name="123" devtype="Switch" maxBulkSize="10"/>
<snmp-agent name="Switch8" ipAddress="10.128.9.8" timeout="3000" retries="2" snmpVersion="v2c" snmpCommunityOrUserV3Name="123" devtype="Switch" maxBulkSize="30"/>
<snmp-agent name="Switch9" ipAddress="10.128.9.9" timeout="3000" retries="2" snmpVersion="v2c" snmpCommunityOrUserV3Name="123" devtype="Switch" maxBulkSize="20"/>
<snmp-agent name="Switch10" ipAddress="10.128.10.10" timeout="3000" retries="2" snmpVersion="v2c" snmpCommunityOrUserV3Name="123456" devtype="Switch">
<snmp-agent name="Switch11" ipAddress="10.128.10.11" timeout="3000" retries="2" snmpVersion="v2c" snmpCommunityOrUserV3Name="123456" devtype="Switch" snmpPort="161"/>
<snmp-agent name="Switch11" ipAddress="10.128.10.11" timeout="3000" retries="2"snmpVersion="v1" snmpCommunityOrUserV3Name="123456" devtype="Switch" snmpPort="1691" v1TableRowPolling="true"/>
<snmp-agent name="Host1" ipAddress="10.128.11.1" timeout="1000" retries="1" snmpVersion="v3" snmpCommunityOrUserV3Name="123456" devtype="Host" snmpV3AuthenticationPassword="12345" snmpV3AuthenticationProtocol="md5" snmpV3PrivacyPassword="123" snmpV3PrivacyProtocol="aes"/>
<snmp-agents-ip-group name="Network1" ipAddressMask="10.128.10.*"/>
<snmp-agents-explicit-group name="Network2">
<agent-ip-address>10.128.9.2:161</agent-ip-address>
<agent-ip-address>10.128.9.3:161</agent-ip-address>
</snmp-agents-explicit-group>
<snmp-agents-explicit-group name="Network3">
<agent-ip-address>10.128.9.6:161</agent-ip-address>
<agent-ip-address>10.128.9.8:161</agent-ip-address>
</snmp-agents-explicit-group>
<snmp-agents-explicit-group name="Network4">
<agent-ip-address>10.128.10.11:161</agent-ip-address>
<agent-ip-address>10.128.10.11:1691</agent-ip-address>
</snmp-agents-explicit-group>
</snmp-secondary-poller>
<snmp-secondary-poller name="secondary2" enabled="true" host="10.128.2.28" port="2008" slaveSnmpPollerXmlFile="slave-snmp-poller.xml">
<snmp-agent name="Switch100" ipAddress="10.128.9.100" timeout="3000" retries="1"
snmpVersion="v2c" snmpCommunityOrUserV3Name="123456" devtype="Switch" transportProtocol="udp" snmpPort="161"/>
</snmp-secondary-poller>
</snmp-polling-distribution>
The following fragment describes the polling distribution for the SNMP collector named ”secondary1”:
<snmp-secondary-poller name="secondary1" enabled="true" host="10.128.2.28" port="2008" slaveSnmpPollerXmlFile="slave-snmp-poller.xml">
Several snmp-secondary-poller elements may be defined in the snmp-polling-distribution.xml file. This allows several SNMP Collectors to use this file for SNMP agent configuration. The snmp-secondary- poller element requires the following attributes: • name:Thevalueofthisattributemusthavethesamevalueasthenameattributeinthesecondary- snmp-poller element located in the slave-snmp-poller.xml file. This is the name of the list of agents that are accessible by the same named SNMP collector. Please note that this is an identifier and that it must be unique.
• enabled: Reserved for future use. Leave this value to true for the time being.
• host: The ip address of the host on which the SNMP collector is running. It must be set to a valid address.
• port: This specifies the SNMP Collector’s communication command port on it’s host. This port is used to receive SNMP requests as well as control and configuration commands from EMC M&R’s mib browser. This must be set to a valid port number, which is the same as the one specified in the local-communication-settings’s communicationPort attribute of the slave-snmp- poller.xml configuration file.
• slaveSnmpPollerXmlFile: This specifies the name of the slave-snmp-poller.xml XML file. It is reserved for future use but must be set to a correct value.
SNMP agent configuration
At least one SNMP agent must be defined in the snmp-secondary-poller element:
<snmp-agent name="Host1" ipAddress="10.128.11.1" timeout="1000" retries="1" snmpVersion="v3" snmpCommunityOrUserV3Name="123456" devtype="Host" snmpV3AuthenticationPassword="12345" snmpV3AuthenticationProtocol="md5" snmpV3PrivacyPassword="123456" snmpV3PrivacyProtocol="aes"/>
1. ipAddress: This is the ipAddress of the SNMP agent. The combination of this ipAddress snmp- Port must be unique in the snmp-secondary-poller element as it identifies a specific snmp agent running on a specific host. It is required as this is address which will be used when pollling the SNMP agent. This will set the raw value’s ip property.
2. devType: This attribute must be set. It indicates the type of device which is described by the SNMP agent. All of the raw values polled on the SNMP agent will have their devtype property set to this value.
doNoUseGetBulkRequests: Applies to SNMP v2c and v3 agents only, do not use getBulk request for polling this agent when set to true. Must be set to true or false.
3. name: This attribute is required. It will set the device property for the raw values polled on this agent.
4. maxBulkSize: This attribute sets the maximum number of varbinds that can be specified in a snmpGetBulk request sent to this snmp-agent. The default value is 50, which should work with most cases. However, some device snmp agents do not implement RFC3416 correctly and simply do not answer to requests which response cannot fit in a single pdu instead of sending the largest possible response, thus triggering timeouts during polling and loss of polled data. Please note that this attribute only applies to SNMP v2c and v3 agents. Also, lowering this value to a very small number, such as 1, will negatively impact polling performance.
5. onFailTryWith: This attribute applies to table polling, using column-based methods. It tells the collector to retry a failed polling on a column, from the top of the column. The default behaviour does not perform this retry. However, it is possible to perform the retry by specifying the use of either SNMP v1 getNext requests (slow, but very reliable on most agents) or SNMP v2c getBulk requests (faster, but not supported on all agents). Possible values are: “doNotRetry”, “v1”, “v2c”. Single SNMP oid polling is also affected by this setting, when the value is set to either “v1” or “v2c”. But in this case, the retry will be performed by using atomic get requests (only 1 oid per request) instead of grouping the oids in the request. This gives the SNMP Agent the maximum number of chances to respond before finally timing out.
6. retries: The number of query retries when polling unresponsive SNMP agents. 0 means no retry.
snmpCommunityOrUserV3Name: The community string (when using SNMP v1 or v2c) or the user name (when using SNMP v3). This attribute’s value is required. The value set for this attribute is also the default context for the purpose of using <credentials-context> with SNMP v1/v2c agents..
7. snmpPort: This is the SNMP port to use when polling the SNMP agent. Port 161 is set by default when not specified.
8. snmpVersion: the SNMP version to use when polling the agent. May be either v1, v2c or v3. Defaults to v2c when not specified.
9. snmpV3AuthenticationProtocol: This must be set when using SNMP v3 only. It may be either md5 or sha. Usually required when polling SNMP V3 agents.
10. snmpV3AuthenticationPassword: The authentication password, used only with SNMP v3. Op- tional: if not provided: noAuthNoPriv is used. auth mode is used if no privacy password is set. authPriv mode is used when both snmpV3AuthenticationPassword and snmpV3PrivacyPassword are set.
11. snmpV3PrivacyProtocol: The SNMP v3 privacy protocol. May be set to aes or des. May be optional, depending upon the SNMP V3 agent’s configuration.
12. snmpV3PrivacyPassword: The SNMP v3 privacy password. Optional: when set, authPriv mode is used. When not: Auth mode or noAuthNoPriv mode is used, depending if snmpV3AuthenticationPassword is set or not.
13. snmpV3ContextName: The SNMP v3 context name. The agent default context name (empty string) is used if not specified or an empty string is provided. The value set for this attribute is also the default context for the purpose of using <credentials-context> with SNMP v3 agents.
14. useV3ContextNameInVariable:Ifsetto”true”,therawvalue’svariablewillusethecontextname as part of it.
15. snmpV3ContextEngineId: The SNMP v3 context engine id. Will be used if specified. Format is an hexadecimal character string (i.e.: 414242 for ”ABC”) which conforms with RFC3411’s snmpEngineID.
16. useV3useV3ContextEngineIdInVariable: If set to ”true”, the raw value’s variable will use the context engine ID as part of it.
17. timeout: The SNMP timeout for the agent’s response, stated in milliseconds. This timeout applies to every query sent 18. transportProtocol: This may be set to either udp or tcp. udp is set by default when not specified.
19. v1TableRowPolling: This attribute affects the way SNMP V1 agents are polled. Setting this to false is the standard failsafe mode. Table polling will be column-based, while setting this to true enables a more efficient row-based polling model (not correctly supported by all SNMP V1 agents). This attribute is optional and defaults to false.
SNMP agents grouping
<snmp-agents-ip-group name="Network1" ipAddressMask="10.128.10.*"/> <snmp-agents-explicit-group name="Network2"> <agent-ip-address>10.128.9.2:161</agent-ip-address> <agent-ip-address>10.128.9.3:161</agent-ip-address> </snmp-agents-explicit-group>
The SNMP agents defined in section 5, subsection 2 may be grouped in two fashions: either by applying a mask on their ip address or by grouping them explicitely. The following XML fragment from the snmp-polling-distribution.xml file shows how to do both: The first group definition tells the SNMP Collector to create an agent group based on their ip addresses. In this case, all of the SNMP agents which have an address that matches the 10.128.10.* regular expression will belong to the Network1 snmp-agents-ip-group. Any regular expression may be used to create a group. Also of note, the match will be performed on the ip address, suffixed by :portNumber. Therefore, an ipAddressMask=”10.128.10.2:1*” will match on agents defined on ip address 10.128.10.2, with port numbers starting with “1” (161, 1690, and any other agent defined on this ip address, with a port number starting with 1, will be part of the group).
The second group definition tells the SNMP Collector to create an agent group with the SNMP agents specified by their ip addresses and port number (www.xxx.yyy.zzz:portNumber).
Please note that, in both cases, the snmp-agents used to create the SNMP agent groups must be defined in the snmp-secondary-poller where the agent group is defined. The agent group names must be unique as they are identifiers.
Multiple SNMP agents on the same IP address configuration
Configuring the polling of mutiple SNMP agents on the same host (IP address) is possible, as shown in the example below:
<snmp-secondary-poller name="secondary1" enabled="true" host="10.128.2.28" port="2008"
slaveSnmpPollerXmlFile="slave-snmp-poller.xml">
<snmp-agent name="Switch11" ipAddress="10.128.10.11" timeout="3000" retries="2"
snmpVersion="v2c" snmpCommunityOrUserV3Name="123456" devtype="Switch"
snmpPort="161"/>
<snmp-agent name="Switch11" ipAddress="10.128.10.11" timeout="3000" retries="2"
snmpVersion="v2c" snmpCommunityOrUserV3Name="123456" devtype="Switch"
snmpPort="1691" />
<snmp-agents-ip-group name="Network5" ipAddressMask="10.128.10.11:.*"/>
<snmp-agents-explicit-group name="Network4">
<agent-ip-address>10.128.10.11:161</agent-ip-address>
<agent-ip-address>10.128.10.11:1691</agent-ip-address>
</snmp-agents-explicit-group>
</snmp-secondary-poller>
In this case, the SNMP agent’s key will be formed by it’s IP address and the SNMP port number it uses. In this case, there are two SNMP agents on the host at IP 10.128.10.11. One listens on port 161 and the other one listens on port 1691 These two agents may be part of a snmp-agents-explicit-group, such as the Network4 group show above, or even a snmp-agents-ip-group, such as the Network5 group (as long as the regular expression used to define it matches the IPAddress:SnmpPortNumber pattern). Also, one must note that the IPAddress:SnmpPortNumber format must be used to specify those SNMP agents in the polling groups defined in the slave-snmp-poller.xml file, other wise a port number 161 will be used by default.
snmp-masks.xml
The SNMP collecting process must be defined in the snmp-masks.xml XML file, for which a simple
example of the structure is shown below:
<?xml version="1.0" encoding="UTF-8"?>
<!-- SNMP polling masks definitions. -->
<snmp-masks>
<snmp-mask name="mask1" doNotEdit="true" version="myVersion1">
<snmp-properties>
<snmp-property .../>
</snmp-properties>
<snmp-oids>
<snmp-oid .../>
<snmp-oid .../>
</snmp-oids>
<snmp-tables>
<snmp-table .../>
<snmp-table .../>
</snmp-tables>
<mib-files>
<mib-file-name>RFC1213-MIB.mib</mib-file-name>
...
</mib-files>
</snmp-mask>
<snmp-mask name="mask2">
...
</snmp-mask>
</snmp-masks>
The structure itself is quite simple as the snmp-masks element must contain at least one named snmp-mask element.
The name of the snmp-mask is the key used in the snmp-slave-poller.xml’s polling groups’ polling-mask-name element.
Optional attributes can also be specified in the snmp-masks element:
• doNotEdit, which can be either true or false
• version, which is used for version management.Any string can be inserted in this attribute. It is up to you, or the snmp-mask editor, to keep it up to date.
Single oids polling configuration
The single oids polling configuration is very simple to accomplish. The XML fragment below shows how to do this:
<snmp-oids > <snmp-oid id="oid1" name="udpOutDatagramsRate" oid=".1.3.6.1.2.1.7.4.0" as="RATE" unit="datagrams/s"/> <snmp-oid id="oid2" name="udpInDatagrams" oid=".1.3.6.1.2.1.7.1.0" as="COUNTER" unit="datagrams"/> <snmp-oid id="oid3" name="snmpInTraps" oid=".1.3.6.1.2.1.11.19.0" as="DELTAP" unit="traps"/> <snmp-oid id="oid4" name="snmpOutTraps" oid=".1.3.6.1.2.1.11.29.0" as="RATEP" unit="traps"/> <snmp-oid id="oid5" name="hrMemorySize" oid=".1.3.6.1.2.1.25.2.2.0" unit="traps" partType="Main␣memory" part="Memory"> <property-value name="propname" value="propvalue" /> </snmp-oid> </snmp-oids>
There are no limit to the number of snmp-oid elements which may be present in the snmp-oids element. The following attributes must be provided: • id: the id for this oid. This value must be unique among all snmp-oid and snmp-table elements present in the snmp-masks.xml file.
• name: the human readable name for this oid. i.e.: sysUpTime. It’s value fills the name property value in the resulting rawValue.
• oid: the oid itself. i.e.: .1.3.6.1.2.1.1.3.0 The following attributes are optional: as, unit, part, partType.
• as: specifies how the polled values must be handled.
Possible values are: – COUNTER or nothing: Do not apply any calculation to the polled value. Send it as is. This is the default behaviour and does not require to be specified.
– DELTA: Calculate the difference between polled values and send this result as the polled value. PolledValue = PV2-PV1. Counter wrap around is handled, except on host restart, where the generated value will be negative.
– DELTAP: computes the same value as the DELTA transformation. However, negative values for types that are not COUNTERs will be discarded.
– RATE: Calculate the rate between polled values and send this result as the polled value. PolledValue = (PV2-PV1)/(T2-T1). Counter wrap around is handled, except on host restart, where the generated value will be negative.
– RATEP: computes the same value as the RATE transformation. However, negative values for types that are not COUNTERs will be discarded.
• unit: specifies the unit to apply to the polled value. Does not involve any calculation. It’s value fills the unit property in the resulting RawValue.
• part: this specifies the [SMARTS] part property value. It’s value fills the part property in the resulting RawValue.
• partType: this specifies the SMARTS parttype property value. It’s value fills the parttype prop- erty in the resulting RawValue. This is a hardcoded value.
Hard coded property and value elements may be nested in snmp-oid elements. Those property and value pairs will be set on the raw value generated by the parent snmp-oid element. Attributes of the property-value element are: • name: the name of the property. • value: the value of the property.
Simple table polling configuration
snmp-table element attributes
basic snmp-table element attributes, which must be provided: • id: the table’s id, which must be unique among all snmp-oid and snmp-table elements.
• name: the table’s name.
• oid: the table’s base oid. i.e.: ifTable is .1.3.6.1.2.1.2.2 • tableIndex: the table’s index columns. The form MUST BE AS FOLLOWS: “.1.1 .1.2” This indicates column 1 and 2 of the table.
The raw value’s variable name will be made using the tableIndex values, if nothing else is available (tableColNameOid is not set, no varNameGenOidSequence specified in snmp-column element and no usePropertyValueInVariableName=“true” is set in any snmp-reference-table).
When polling tables that have index columns whose values are not accessible (not readable), the user must specify a way to retrieve the index values from another polled column. Oids polled in a table always contain a suffix which identifies the row. It is the user’s taks to tell the snmp collector that it must extract this suffix to use it as the table’s index. In order to do this, specify a non-existant or non-accessible oid in table index, as follows: tableIndex=“.1.100” generate pseudo column 100 for indexing. This is the case for a table that has only one index column.
In this case, the indexEntryMask MUST be defined as follows: indexEntryMask=”oid. . .100” : the oid itself contains column 100, located 2 places after the table’s base oid. (Standard case)
Another valid form would be the following (not related to the previous example): tableIndex=“.1.100 .1.101” indexEntryMask=“oid. . .100.101.101.101.101” Where the index column 100 would be taken from the oid, 2 places after the table’s base oid, and index column 101 would be extracted from the 4 following places. This models the case of a table that has 2 index: an integer, followed by an IP address. This could be used with the ipNetToMediaTable, which has this type of index structure, although it’s index columns are specified explicitly. There is also another way to specify the indexEntryMask when the OID structure is not stable. In certain cases, OID’s length may vary on a row-by-row basis. This case warrants the use of the following syntax: tableIndex=“.1.100 .1.101” indexEntryMask=“oid. . .100.101+” In this case, it means that the OID index structure is made of one int, followed by an unspecified number of ints. One must note that the “oid. . .100.101+” syntax allows the use of only ONE element with an undefined number of occurences. Valid variations of this structure could be as follows:
• indexEntryMask=“oid. . .100+” • indexEntryMask=“oid. . .100+.101” • indexEntryMask=“oid. . .100.101+” • indexEntryMask=“oid. . .100.101+.102”
The following attributes are optional: • tableColNameOid: specifies which column values must be used, in the table, to set the part property for all polled columns. i.e.: tableColNameOid=“.1.1 .1.2” to use column 1 and 2 values.
• indexEntryMask: this describes the table’s rows oid structure and is used to generate index pseudo-columns when the table does not have explicit index columns. The following is an exam- ple which describes how it works: When polling table cpmProcessTable (.1.3.6.1.4.1.9.9.109.1.2.2.1), which is indexed by cpmCPUTotalIndex and cpmProcessPID, column 1, the resulting oid will have this form: cpmProcExtMemAllocated.1.2 where the .1 maps to cpmCPUTotalIndex and .2 is the cpmProcessPID.
By using indexEntryMask=“oid. . .100.101”, it is possible to assign the pseudo-column 100 to cpmCPUTotalIndex and pseudo-column 101 to cpmProcessPID.
It then becomes possible to use those index columns for joining external tables for filtering or referencing properties.
• partType: specifies the raw value’s property parttype. This is user defined.
Finally, the snmp-table element may contain columns-and-filters, snmp-reference-table and inner- join-on elements. We will start with simple examples, using only the columns-and-filters element. This element contains snmp-column (at least 1!), snmp-property-column and snmp-filter elements.
Simple table column polling
<snmp-table id="tableZ" name="hrStorageTable" oid=".1.3.6.1.2.1.25.2.3"
tableIndex=".1.1␣.1.3" tableColNameOid=".1.3">
<property-value name="propname" value="propvalue"/>
<columns-and-filters>
<snmp-column name="hrStorageSize" appendOid=".1.5" as="COUNTER" unit="KB"/>
<snmp-column name="hrStorageUsed" appendOid=".1.6" as="COUNTER" unit="KB" statistics="MIN,MAX
,SUM,AVG">
<property-value name="from" value="hrStorageTable"/>
</snmp-column>
<snmp-property-column name="hrIndexCol" appendOid=".1.1" usePropertyValueInVariableName="
false" hexValue="false" />
</columns-and-filters>
</snmp-table>
SNMP collector to: • PollvaluesfromthehrStorageTable(.1.3.6.1.2.1.25.2.3)columns5(hrStorageSize)and6(hrStorageUsed).
• Calculate and send the minimum (MIN), maximum (MAX), sum (SUM) and average (AVG) of the hrStorageUsed column as distinct raw values.
• Handle the polled values as COUNTER, with their units set as KB.
• Set part property with the value in column 3 (hrStorageDescr) of the table.
• Get the values from column 1 (hrIndexCol) and set property propname on polled values.
• Tag polled values hrStorageUsed with the hard coded property (property-value element: prop- name=“from”) • Tag all polled values from this table with the hard coded property (property-value element: prop- name=“propvalue”).
The variable names will be created using the values provided by the index columns, in this case column 1 and 3. According to the HOST-RESOURCES MIB, the index for this table shoud be column 1 only. However, there are no guarantee that the relation between the index column value and the hrStorageDescr will always be the same, that is why we must specify to use both columns 1 and 3: if the relation changes, a new variable will be generated but it will still be possible to find the older variables in the backend, therefore ensuring survival of the variable for reporting purposes. One would be tempted to use column 3 only instead of this combination but we must keep in mind that SNMP agents may be buggy and that column 3 may not contain any data, which would result in generating the raw value multiple times. Again, one must check the behaviour of the polled SNMP agent in order to write valid and useful configuration.
snmp-column attributes
The snmp-column element defines the table columns to poll. It may contain 0 or several snmp- filter elements which are used to determine which rows will produce rawValues.
The following attributes are required:
• name: the oid name. It may or may not be the same as the oid name specified in a MIB. This is the name property in the resulting rawValue.
• appendOid: This specifies the table’s column to poll. It’s format is ALWAYS “.1.X”, where X is the column number.
The following attributes are optional: • as: see snmp-oid element for description.
• unit: see snmp-oid element for description.
• varNameGenOidSequence:UsetheappendOids(”.1.2.1.3”)valuestogeneratethevariablename for this column. This is useful in certain cases, where the variable index cannot otherwise be generated.
• propertyName:addthenamedpropertytotheRawValueswhichresultsfrompollingthiscolumn. Poll the property value in the column specified by propertyValueAppendOid.
• propertyValueAppendOid: Used with the propertyName attribute to specify the column in which the value for the property will be found. It’s format is ALWAYS “.1.X”, where X is the column number. Several columns can be specified here, following this format: “.1.X .1.Y .1.Z”.
• refreshOnPropertyChange:refreshtherawvalue’spropertiesonchange.Setto“true”toenable this behaviour. Defaults to “false” if not specified.
• statistics: Contains a list of comma-separated statistics for this polled column. Optional. Allowable aggregations include:
– AVG: calculate the average value for the column (sum of column values / row count). Send a distinct raw value (name=AVG name) for this aggregate.
–COUNT:calculate the number of rows in the column.Send a distinct raw value(name=COUNT name) for this aggregate.
– MAX:calculate the maximum value for the column.Send a distinct raw value(name=MAX name) for this aggregate.
– MIN:calculate the minimum value for the column.Send a distinct raw value(name=MIN name) for this aggregate.
– SUM: calculate the sum of column values. Send a distinct raw value (name=COUNT name) for this aggregate.
filtering on table columns
Example 1:
The following is an example of filtering applied on polled columns. In this case, the filter is applied on all columns as it resides directly in the snmp-table element:
<snmp-table id="table1a" name="ifTable" oid=".1.3.6.1.2.1.2.2" tableIndex=".1.1" tableColNameOid=".1.2"> <columns-and-filters> <snmp-column name="ifInOctetsRate" appendOid=".1.10" as="RATE" unit="octets" propertyName="physAddr" propertyValueAppendOid=".1.6" varNameGenOidSequence=".1.1␣.1.2"/> <snmp-column name="ifOutOctetsRate" appendOid=".1.16" as="RATE" unit="octets" propertyName="physAddr" propertyValueAppendOid=".1.6" varNameGenOidSequence=".1.1␣.1.2"/> <snmp-filter name="ifType␣Ethernet" onTableColumnName="ifType" appendOid=".1.3" valueEquals="etherne.*"/> </columns-and-filters> </snmp-table>
In this case, we are telling the SNMP collector to poll ifInOctets (column 10) and ifOutOctets (col- umn 16) of the ifTable (.1.3.6.1.2.1.2.2) but keep only the table rows where the ifType matches the “etherne.*” regular expression. Then, set the resulting raw value’s physAddr property to the value found in column 6 of the ifTable, which is ifPhysAddr. Set the raw value’s part property to the value found in column 2 of the table (ifDescr) and, finally, use the values found in columns 1 and 2 of the table to create the variable name.
Example 2:
In this examplefiltering is applied only on the ifInOctetsRate column, while all of the values present in the ifOutOctets column will be polled:
<snmp-table id="table1y" name="ifTable" oid=".1.3.6.1.2.1.2.2" tableIndex=".1.1" tableColNameOid=".1.2"> <columns-and-filters> <snmp-column name="ifInOctetsRate" appendOid=".1.10" as="COUNTER" unit="octets" propertyName="physAddr" propertyValueAppendOid=".1.6" varNameGenOidSequence=".1.1␣.1.2"> <snmp-filter name="ifType␣Ethernet" onTableColumnName="ifType" appendOid=".1.3" valueEquals="etherne.*"/> </snmp-column> <snmp-column name="ifOutOctetsRate" appendOid=".1.16" as="COUNTER" unit="octets" propertyName="physAddr" propertyValueAppendOid=".1.6" varNameGenOidSequence=".1.1␣.1.2"/> </columns-and-filters> </snmp-table>
The snmp-filter elements may also be present on both levels but bear in mind that their effect can be cumulative.
In the following example
ifInOctetsRate column will be filtered through two criteria: ifType matches “eth- erne.*” and ifSpeed matches “100000000” while the ifOutOctetsRate will be filtered only by the ifSpeed criteria.
<snmp-table id="table1x" name="ifTable" oid=".1.3.6.1.2.1.2.2" tableIndex=".1.1" tableColNameOid=".1.2"> <columns-and-filters> <snmp-column name="ifInOctetsRate" appendOid=".1.10" as="COUNTER" unit="octets" propertyName="physAddr" propertyValueAppendOid=".1.6" varNameGenOidSequence=".1.1␣.1.2"> <snmp-filter name="ifTypeEthernet" onTableColumnName="ifType" appendOid=".1.3" valueEquals="etherne.*"/> </snmp-column> <snmp-column name="ifOutOctetsRate" appendOid=".1.16" as="COUNTER" unit="octets" propertyName="physAddr" propertyValueAppendOid=".1.6" varNameGenOidSequence=".1.1.1.2"/> <snmp-filter name="ifSpeed=100000000" onTableColumnName="ifSpeed" appendOid=".1.5" valueEquals="100000000"/> </columns-and-filters> </snmp-table>
regular expression may be used to provide OR filtering conditions. The following is a valid filter:
<snmp-filter name="ifSpeed=100000000" onTableColumnName="ifSpeed" appendOid=".1.5" valueEquals="10000000|57600"/>
In this case, we are filtering rows where the ifSpeed matches “10000000” or “57600”.
AND OR column filtering conditions
It is also possible to configure OR condition filtering by having several snmp-filter elements on the same level (in either snmp-column or snmp-filter element):
<snmp-table id="table1w" name="ifTable" oid=".1.3.6.1.2.1.2.2" tableIndex=".1.1" tableColNameOid=".1.2"> <columns-and-filters> <snmp-column name="ifInOctetsRate" appendOid=".1.10" as="COUNTER" unit="octets" propertyName="physAddr" propertyValueAppendOid=".1.6" varNameGenOidSequence=".1.1␣.1.2"> <snmp-filter name="ifType␣Ethernet" onTableColumnName="ifType" appendOid=".1.3" valueEquals="etherne.*"/> <snmp-filter name="ifSpeed=100000000" onTableColumnName="ifSpeed" appendOid=".1.5" valueEquals="100000000"/> </snmp-column> </columns-and-filters> </snmp-table>
In this case, we are telling the SNMP collector to poll the ifInOctets column and keep the rows that have their ifSpeed column value match the “100000000” regular expression OR their ifType column value match the “etherne.*” regular expression. The same can be done with snmp-filter elements located at the snmp-column level.
it is also possible to nest snmp-filter elements into a snmp-filter element. This is used to create AND conditions such as the one in the following example:
<snmp-table id="table1w" name="ifTable" oid=".1.3.6.1.2.1.2.2" tableIndex=".1.1" tableColNameOid=".1.2"> <columns-and-filters> <snmp-column name="ifInOctetsRate" appendOid=".1.10" as="COUNTER" unit="octets" propertyName="physAddr" propertyValueAppendOid=".1.6" varNameGenOidSequence=".1.1␣.1.2"> <snmp-filter name="ifType␣Ethernet" onTableColumnName="ifType" appendOid=".1.3" valueEquals="etherne.*"> <snmp-filter name="ifSpeed=100000000" onTableColumnName="ifSpeed" appendOid=".1.5" valueEquals="100000000"/></snmp-filter> </snmp-column> </columns-and-filters> </snmp-table>
In this case, we are telling the SNMP collector to poll the ifInOctets column and keep the rows that have their ifSpeed column value match the “100000000” regular expression AND their ifType column value match the “etherne.*” regular expression.
snmp-filter attributes
descriptions of the snmp-filter attributes. The following attributes are required:
• appendOid: The column on which filtering is applied. Must be in the ”.1.X” form, where X is the column number in the SNMP table.
• valueEquals: The value used for filtering. It is in effect a regular expression, which simplest form is an equality: – valueEquals=“value” performs the SQL equivalent of =, as in: SELECT ... FROM table WHERE column=’value’ – valueEquals=“ethernet.*” performs the SQL equivalent of LIKE, as in: SELECT ... FROM table WHERE column LIKE ’ethernet%’ The following attributes are optional: • indexEntryMask: Set this when filtered table does not have index columns for all it’s indexes.
See snmp-table element for details on how this works.
• onTableColumnName: This is user defined and has no effect on polling. It is used for comment only.
• name: This user defined and has no effect on polling. It is used for comment only.
• invertMatch: When set to true, this inverts the regular expression match. So, if the regular ex- pression matches a value, the line will be filtered out instead of being kept. The default behaviour is false.
SNMP properties configuration
SNMP properties are attached to every raw value produced by the snmp-mask which contains them. The following example shows how to configure them:
<snmp-properties> <snmp-property id="outsideProp1" name="someProp" value="hardCodedValue"/> <snmp-property id="outsideProp2" name="ipfrwd" oid=".1.3.6.1.2.1.4.1.0"/> </snmp-properties>
The following attributes are required:
• id: The property’s identifier. This is used internally.
• name: The property name. This will be the property key in the raw value. • value: The property value. This is hardcoded.
• oid: The oid to poll in order to get the property value.
Please note that either value or oid attribute may be present. In this case, all values resulting from this mask will have a property “someProp” set to “hardCodedValue” while the “ipfrwd” will be set to the value found at the specified oid. MIB translation will be applied to this value, if the correct MIB was loaded.
MIB files specification
MIB Files are used to get textual values from integer enumerated values. The textual value will be set as the property value if polled as a property. However, if polled as a value, the correct translation (see next section) must be defined in order to actually translate this textual value back to an actual floating point value.
INET-ADDRESS-MIB.txt is always loaded by default.
<mib-files> <mib-file-name>INET-ADDRESS-MIB.txt</mib-file-name> <mib-file-name>MY-CUSTOM-COLLECTOR.mib</mib-file-name> </mib-files>
Translations configuration
translations.xml
Value translations are required when polling SNMP oids of String-octet (which contain non-numeric
values) or Integer (enum) type as the resulting raw values can only contain numeric values. Configuring
the translation table is done by editing the translations.xml XML file, which is shown below:
<?xml version="1.0" encoding="UTF-8"?> <translations> <variable-specific-translations> <variable-value-translation name="Availability"> <value-match value="up" rename="100"/> <value-match value="down" rename="0"/> <value-match value="testing" rename="0"/> </variable-value-translation> </variable-specific-translations> </translations>
only translation configured in this file is applied to any polled value named Availability. This specific case could apply to the ifTable ifAdminStatus column if it were to be polled like this:
<snmp-table id="table200" name="ifTable" oid=".1.3.6.1.2.1.2.2" tableIndex=".1.1␣.1.2" tableColNameOid=".1.2"> <columns-and-filters> <snmp-column name="Availability" appendOid=".1.7" unit="%"/> </columns-and-filters> </snmp-table> <snmp-oids> <snmp-oid id="oid15" name="Availability" oid=".1.3.6.1.2.1.2.2.1.7.1" unit="%"/> <snmp-oids>
Or, alternately, like this:
<snmp-oids> <snmp-oid id="oid15" name="Availability" oid=".1.3.6.1.2.1.2.2.1.7.1" unit="%"/> <snmp-oids>
In this case, any polled oid which returns the “up” value will have it’s value translated to “100” while other values like “down” and “testing” will be translated to “0”. Note that in both cases, the unit is set to “%”, which reflect the availability percentage.
This translation process requires the correct MIB file to be loaded in the SNMP collector. In this case, the RFC-1213 MIB file would be required as it contains the value translation for the ifAdminStatus oid.
meta_en.properties
This file contains the metadata information about the collector
name=Custom_SNMP description=Collect SNMP Metrics from Custom Agent family=IMS custom_snmp=Custom SNMP collector custom_snmp.desc=Custom SNMP collector
questions.txt
This file contains the user configured parameters for the collectors
#EXPORT .sproutagent AS device(hostname) #EXPORT .bonoagent AS device(hostname) [+sproutagent] hostname = string port = port protocol = string(udp) community = password version = string(v2c) deploymentid= string orchestrator = string timeout = integer [+bonoagent] hostname = string port = port protocol = string(udp) community = password version = string(v2c) deploymentid = string orchestrator = string timeout = integer [node] host = hostname port = port [main] sproutagent * bonoagent * kafka.cluster sproutpollingperiod = integer[60,3600] bonopollingperiod = integer[60,3600]
Default.txt
default values for user configurable parameter
#collect sproutagent.want.default=true sproutagent.hostname.default = localhost sproutagent.port.default = 161 sproutagent.protocol.default = udp sproutagent.community.default = public sproutagent.version.default = v2c sproutagent.deploymentid.default= default sproutagent.orchestrator.default = default sproutagent.timeout.default = 30 bonoagent.want.default=true bonoagent.hostname.default = localhost bonoagent.port.default = 161 bonoagent.protocol.default = udp bonoagent.community.default = public bonoagent.version.default = v2c bonoagent.deploymentid.default= default bonoagent.orchestrator.default = default bonoagent.timeout.default = 30 sproutpollingperiod.default=300 bonopollingperiod.default=300
questions_en.properties
display values or description for Questions.txt
#clearwater sproutagent.hostname=Hostname or IP address of the Clearwater Sprout Node sproutagent.want=Configure an Clearwater Sprout Node sproutagent.help=Hostname or IP address of the Clearwater Sprout Node for the connection sproutagent.port=SNMP Port bonoagent.hostname=Hostname or IP address of the Clearwater Bono Node bonoagent.want=Configure an Clearwater Bono Node bonoagent.help=Hostname or IP address of the Clearwater bono Node for the connection
spb.properties
dependencies file for modules defined in collecting.xml
version=1.0.0.0 dependencies=+>=collector-manager-5.6, +>= snmp-collector-1.1, +>=kafka-connector-1.0u2, +>=variable-handling-filter-1.14
