SNMP Client XML Files

Example XML File

<?xml version="1.0" encoding="ISO-8859-1" ?>

<snmpclient_devices>
<dev id="1" peername="192.168.1.20" name="apc" version="3" maxVarBinds="3" pollTolerance="1" secLevel="3" username="jim" authType="MD5" authPhrase="jimsAuthPhrase" privType="DES" privPhrase="jimsPrivPhrase"/>/>
<dev id="2" peername="192.168.1.23" name="v210" version="2" community="private" maxVarBinds="3" pollTolerance="1"/>
</snmpclient_devices>

<snmpclient_read>
<map oid="1.3.6.1.4.1.3815.1.4.1.1.1.1.2.1" dev="1" localobj="14" poll="10.0"/>
<map oid="1.3.6.1.4.1.3815.1.4.1.1.1.1.2.2" dev="1" localobj="15" poll="10.0"/>
<map oid="1.3.6.1.4.1.3815.1.4.1.1.1.1.2.6" dev="2" localobj="17" poll="10.0"/>
<map oid="1.3.6.1.4.1.3815.1.4.1.1.1.1.2.3" dev="1" localobj="16" poll="10.0"/>
<map oid="1.3.6.1.4.1.3815.1.4.1.1.1.1.2.4" dev="2" localobj="18" poll="10.0"/>
<map oid="1.3.6.1.4.1.3815.1.4.1.1.1.1.2.5" dev="2" localobj="19" poll="10.0"/>
</snmpclient_read>

<snmpclient_write>
<map oid="1.3.6.1.4.1.3815.1.4.1.1.1.1.2.5" dev="2" localobj="20" asn="1" delta="0"/>
</snmpclient_write>

<snmpclient_walk>
<rule oid="1.3.6.1.2.1.33.1.6.2.1.*(2).*" dev="1" count="24" method="4" startobj="14" poll="10.0"/>
</snmpclient_walk>

</configuration>

<snmpclient_devices> section

id=”n” – A number ranging from 1 to device table size, and is referenced in read and write maps, and table walk rules, as the device to which the map applies.

peername=”xxxx” – Provides a definition of where on the network to find the device. The peername in simplest form will be an IP address as illustrated in the XML file example above. However, if the network has access to a DNS server and that server is configured in the network settings of the local device, then peername may be any name that can be found via DNS lookup.

rate=”n.nn” – Real or integer poll time in seconds, can be fractional. Used as default when read, write, or walk rule does not have a poll time specified.

version=”n” – Specifies what SNMP version should be used to send the SNMP Get or Set, which in turn determines certain aspects of how the message is formatted. Version may be 1, 2, or 3 where 2 means v2c.

timeout=”n” – Integer number of seconds for session timeout.

retries=”n” – Number of times that the SNMP engine should automatically retry a Get or Set if it fails.

maxVarBinds=”n” – Specifies the maximum number of varbinds that may be included in the same request. When multiple values are requested from the same device, the client will attempt to group them into a single SNMP Get or Set for efficiency (less network traffic). The client will group up to this many varbinds into the same request.

maxRecvSize=”n” – Provides a limit on the maximum message size that should be accepted, defaults to 1500 if omitted (recommended).

maxSendSize=”n” – Provides a limit on the maximum message size that should be sent, defaults to 1500 if omitted (recommended). The maxVarBinds should be set to 1 if the maxSendSize is reduced.

pollTolerance=”n.nn” – Real or integer poll tolerance in seconds, can be fractional. Poll tolerance refers to the amount of time overlap permitted when the client is attempting to group varbinds into a single Get or Set. In other words, if a map or rule timeout is not quite zero but is less than the poll tolerance, it will be treated as zero and grouped into the Get or Set that is already under way.

name=”xxxx” – Simply provides a reference name for use in the web UI.

community=”xxxx” – The community string as defined for SNMP v1 and v2c.

secLevel=”n” - Sets security level, 1=noAuthNoPriv, 2=authNoPriv, 3=authPriv. Those are the SNMP acronyms meaning (1) no authentication or privacy, (2) authentication required but privacy is not, (3) both authentication and privacy are required. The term “privacy” means encryption. (Used only for SNMPv3.)

username=”xxxx” - Sets the SNMP security name, analogous to username in SNMP terms. (Used only for SNMPv3.)

authType=”xxx” - Sets the authentication type, may be “NOAUTH”, “MD5”, or “SHA”. It determines how the username (security name) is hashed when transmitted. (Used only for SNMPv3.)

authPhrase=”xxx” - Sets the authentication phrase, analogous to an SNMP password. (Used only for SNMPv3.)

privType=”xxx” - Sets the privacy type, may be “NOPRIV”, “DES”, or “AES”. This determines which encryption algorithm will be used. (Used only for SNMPv3.)

privPhrase=”xxx” - Sets the privacy phrase which is used as the encryption key. (Used only for SNMPv3.)

Note: For sending traps with SNMPv3, you must know the engine ID of the recipient. The SNMPv3 client, however, will query the remote agent to learn engine ID as well as engine time and boots. It will then use this information to do the actual data query.

<snmpclient_read> section

Map Number is implied by order in XML – Used as a reference in the map list for ordering the maps. Polling is done in round robin fashion in the order of map number.

oid=”n.n.n.n….” – A dot field character string specifying the OID to be read from the remote SNMP device using a Get request. The string must have only digits and periods and no embedded spaces.

hint=”n” – Provides direction on how to interpret data in the event the value type is Octet String. All ASN data types are interpreted according to their type; however, Octet String will default to being interpreted as a character string unless this hint says otherwise. The exceptions are hint=”1” to interpret 4-octet Octet Strings as 32-bit floating point per RFC 6340, and hint=”2” to interpret 8-octet Octet Strings as 64-bit floating point per RFC 6340. If the hint is non-zero but the Octet String length is not 4 or 8, then it will still be treated as a character string.

dev=”n” – Identifies which device from the device list this map applies to, i.e., determines which IP address to try to establish a connection with.

scale=”n.nn” – Provides a scale factor if non-zero (has the effect of being 1 if zero). Data received from a remote SNMP device is multiplied by this factor (if non-zero) before being placed in the local object. Applies to numeric values and numeric local objects only.

offset=”n.nn” – Provides an offset to work in conjunction with scale factor. This value will be added to the data value received from a remote SNMP device before being placed in the local object. Applies to numeric values and numeric local objects only.

poll=”n.nn” – Real poll time in seconds, can be fractional. The sets the rate at which the remote SNMP device will be polled. This poll time is not guaranteed to be met. Polling is done in round-robin fashion. In a very busy system, more than this time may expire before the next poll. If less than this time has expired, then the system will wait this amount of time until polling again.

localObj=”n” – Specifies which local object the result of this read operation should be placed in.

default=”n.nn” – Provides the default value that the local object should be set to in the event the maxfail/failCount is exceeded.

maxfail=”n” – Optional, provides a count of read failures, if non-zero, that can occur before the local object will be set to the default value given in this map. If zero, the default value will never be applied. If 1, then the default value will be applied upon the first failure (probably not recommended), and so on. The count is reset by a successful read.

xobj=”n” – Optional, allows for selectively enabling this read operation. If an index object (local object number) is given, and its value matches the indexValue, then this read operation will take place. If an indexObject is given but the local object’s value does not match the indexValue, then this read operation will be skipped.

xvalue=”n” – Optional, used in conjunction with indexObject (see note above).

<snmpclient_write> section

Map Number is implied by order in XML – Used as a reference in the map list for ordering the maps. Polling is done in round robin fashion in the order of map number.

oid=”n.n.n.n….” – A dot field character string specifying the OID to be written in the remote SNMP device using a Set request. The string must have only digits and periods and no embedded spaces.

asn=”n” – Specifies how data should be formatted in the Set request. The code given here is a selector, not the actual ASN code. The selection is made from the following table:

ASN select	ASN type used	Hint assumed	Description
1	ASN Integer	0	32-bit signed integer
2	ASN Timeticks	0	32-bit unsigned integer
3	ASN Gauge	0	32-bit unsigned integer
4	ASN Counter	0	32-bit unsigned integer
5	ASN Octet String	0	String of 8-bit bytes
6	ASN Counter64	0	64-bit unsigned integer
7	ASN Opaque Float	0	Net-SNMP floating point
8	ASN Opaque Double	0	Net-SNMP floating point
9	ASN Opaque U64	0	64-bit unsigned integer
10	ASN Opaque I64	0	64-bit signed integer
11	ASN Opaque Counter64	0	64-bit unsigned integer
12	ASN Bit String	0	Bit string per standard ASN
13	ASN Object ID	0	Object ID per standard ASN
14	ASN IP Address	0	IP address per standard ASN
15	ASN Octet String	1 (RFC 6340 Float)	RFC 6340 32-bit IEEE 754
16	ASN Octet String	2 (RFC 6340 Double)	RFC 6340 64-bit IEEE 754

dev=”n” – Identifies which device from the device list this map applies to, i.e., determines which IP address to try to establish a connection with.

scale=”n.nn” – Provides a scale factor if non-zero (has the effect of being 1 if zero). Data to be written is retrieved from the local object and then multiplied by this scale factor before being sent to the remote SNMP device. Applies to numeric values and numeric local objects only.

offset=”n.nn” – Provides an offset to work in conjunction with scale factor. This value is added to the value retrieved from the local object (after being multiplied by scale) before being sent to the remote SNMP device. Applies to numeric values and numeric local objects only.

poll=”n.nn” - Real poll time in seconds, can be fractional. This poll time is not guaranteed to be met. Polling is done in round-robin fashion. In a very busy system, more than this time may expire before the next poll. If less than this time has expired, then the system will wait this amount of time until polling again. The sets the rate at which the remote SNMP device will be updated, provided “sendPeriodic” has been enabled. This poll time will be disregarded if sendPeriodic is not enabled. The Send Periodic feature is automatically enabled by the presence of this tag in the XML file.

maxquiet=”n.nn” – Real time in seconds, can be fractional. If a Set request has not been made either as a result of poll timing or value changing by delta within this time period, then a Set request will be made anyway. This specifies the maximum amount of time that should expire without any Set request being made for any reason. The Max Quiet Time feature is automatically enabled by the presence of this tag in the XML file.

minquiet=”n.nn” – Real time in seconds, can be fractional. This specifies the mínimum amount of time that should elapse between sending of Set requests for this write map. The minimum quiet time has the effect of throttling network traffic.

delta=”n.nn” – Specifies the margin by which the local object value should change before sending another Set request to send the new value to a remote SNMP device. Once the changed value has been sent, the new local value is retained for future comparison in determining subsequent additional change. The delta value is disregarded if sendDelta is not enabled. The Send on Delta feature is enabled automatically by the presence of this tag in the XML file.

localObj=”n” – Specifies the local object number that contains the data that should be sent by this write map.

xobj=”n” – Optional, allows for selectively enabling this write operation. If an index object (local object number) is given, and its value matches the indexValue, then this write operation will take place. If an indexObject is given but the local object’s value does not match the indexValue, then this write operation will be skipped.

xvalue=”n” – Optional, used in conjunction with indexObject (see note above).

<snmpclient_walk> section

Rule Number is implied by order in XML – Used as a reference in the rule list for ordering the maps. Polling is done in round robin fashion in the order of rule number.

oid=”n.n.n.n….” – A dot field character string specifying the starting OID for the table walk. The table is walked using GetNext requests, therefore the OID must specify an OID preceeding the first OID that one wishes to read.

The table OID is different than OIDs for read and write maps. The table OID includes optional wildcard fields when the walk method is Index or Mask. For example, to walk the alarm table of a UPS using RFC 1628, the OID would be 1.3.6.1.2.1.33.1.6.2.1.*(2).*. The *(2) means allow any value in the second to last field but only act on the value when this field is 2. The last asterisk means disregard the last field entirely (which for RFC 1628 increments with each new alarm until reaching some rollover point, then starts back at 1 again).

method=”n” – Defines the method of table walk to be used with values as follows:

0 = Normal
1 = Sparse
2 = Wildcard
3 = Index
4 = Mask

The table walking process can become complicated by the fact that tables are allowed to have missing rows, or rows may have intermittent missing columns. In some applications, rows will be populated only temporarily and then they will disappear. The table walk method identified as "Normal" expects the given column to exist in all rows through the range of rows defined by the starting OID and the count. The remaining methods accommodate the other complications permitted by SNMP.

Method "Normal" will simply produce a 1 to 1 correlation between table entries and object numbers, placing successive values in successive objects. Data will be interpreted according to the data hint if an octet string is returned, otherwise the ASN encoding will take precedence. If the Get-Next sequence fails to return enough OIDs to fill the 'count' criteria, an error code is set for the device indicating that the table came up short on data.

Method "Sparse" is the same as Normal, except missing OIDs in the sequence is anticipated, and the corresponding local objects in the sequence are skipped over if the respective OID is not included in the Get-Next sequence. No error is flagged for table being short on data.

Method "Wildcard" allows wildcard fields in the table OID. The walk does not care about order of OIDs returned by Get-Next as long as they match the OID given after discounting wildcard fields. No attempt is made to sequentially pair OIDs with objects. The next 'count' OIDs that successfully match the OID with wildcards will fill the next 'count' of objects beginning with the starting local object number. The OID sent out in the first Get-Next request will have zero in any wildcard fields, and each successive Get-Next will send out the OID from the response to the previous Get-Next.

Method "Index" will walk the table, but expect to find that values are OIDs. In other words, the table name is an OID, but the contents of the variable at that name will be another OID. The result is that the OID index (last field of OID) from the value will be used as the offset to calculate which object number is to be affected, and that object will be set to 1 indicating this OID is present in the table. This seemingly odd means of table walking is required in order to translate the alarm table from RFC 1628 for UPS systems into indexable local objects that indicate the presence or absence of alarms defined in RFC 1628. (Note that the alarm table in RFC 1628 is "sparse" meaning its table entries are only present if an alarm is present, and the table is empty if there are no alarms. One cannot simply query OIDs to determine presence of an alarm. Alarms are implied by presence of a table entry that only exists while the alarm is present. Furthermore, the alarm table is simply a circular buffer of alarm entries, and the table index means nothing.)

The object set to 1 by the Index method will not be reset to zero by anything in the table walk rule. Use the timeout feature available in the definition of the object itself to set it to a default value after some amount of time, typically a time longer than the rate at which this table is walked. The result will be a object that is set to 1 when the corresponding alarm exists, and automatically reset to zero sometime after the alarm no longer is found in the alarm table.

Method "Mask" is a modified version of "Index". It will walk the table in the same manner, but set bits within the same single object corresponding to the OID index field. OID index .1 will be bit 0, index .2 will be bit 1, and so on. In this case, starting object is the only object number affected, and "count" is the number of bits that will be affected in that one object. If the Index method is used and one wishes to recognize the full range of alarms known to RFC 1628, then 24 objects will be consumed. Using the Mask method, only one 32-bit object is used. Furthermore, non-present alarms will have their corresponding bits cleared without any timeout default value. (Timeout and default should not be used in this case since the single object represents as many as 24 individual states.)

hint=”n” – Provides direction on how to interpret data in the event the value type is Octet String. All ASN data types are interpreted according to their type; however, Octet String will default to being interpreted as a character string unless this hint says otherwise. The exceptions are hint=”1” to interpret 4-octet Octet Strings as 32-bit floating point per RFC 6340, and hint=”2” to interpret 8-octet Octet Strings as 64-bit floating point per RFC 6340. If the hint is non-zero but the Octet String length is not 4 or 8, then it will still be treated as a character string.

dev=”n” – Identifies which device from the device list this rule applies to, i.e., determines which IP address to try to establish a connection with.

poll=”n.nn” - Real poll time in seconds, can be fractional. The sets the rate at which the table in the remote SNMP device will be walked. This poll time is not guaranteed to be met. Polling is done in round-robin fashion. In a very busy system, more than this time may expire before the next poll. If less than this time has expired, then the system will wait this amount of time until polling again.

startObj=”n” – Specifies the first local object number that may be filled by this table walk, used in conjunction with count (below).

count=”n” – Specifies the number of local objects, starting at startObject, that may be filled by this table walk. Most table walks are going to result in filling multiple objects with data.

xobj=”n” – Optional, allows for selectively enabling this table walk. If an index object (local object number) is given, and its value matches the indexValue, then this table walk will take place. If an indexObject is given but the local object’s value does not match the indexValue, then this table walk will be skipped.

xvalue=”n” – Optional, used in conjunction with indexObject (see note above).

SNMP Client XML Files

Contents