The Cacti Manual
Prev	Chapter 10. Data Queries	Next

SNMP Query XML Syntax

<query>
   <name>Get SNMP Interfaces</name>
   <description>Queries a host for a list of monitorable interfaces</description>
   <oid_index>.1.3.6.1.2.1.2.2.1.1</oid_index>
   <oid_index_parse>OID/REGEXP:.*\.([0-9]{1,3}\.[0-9]{1,3})$</oid_index_parse>
   <oid_num_indexes>.1.3.6.1.2.1.2.1.0</oid_num_indexes>
   <index_order>ifDescr:ifName:ifIndex</index_order>
   <index_order_type>numeric</index_order_type>
   <index_title_format>|chosen_order_field|</index_title_format>

   <fields>
      <ifIndex>
         <name>Index</name>
         <method>walk</method>
         <source>value</source>
         <direction>input</direction>
         <oid>.1.3.6.1.2.1.2.2.1.1</oid>
      </ifIndex>
   </fields>
</query>

Table 10-3. SNMP Query XML Field Reference

Field	Description
query->name	(Optional) You can enter a "friendly name" for the SNMP query here. It will not be used by Cacti, and is for identification only.
query->description	(Optional) You can enter a description for the SNMP query here. It will not be used by Cacti, and is for identification only.
query->oid_index	Every SNMP query must have an OID that represents the index values for the query when walked. As described above, any data query in Cacti must contain a field that uniquely identifies each row returned by the query. In the example above, the oid_index points to the OID of ifIndex in the interface MIB. Note: Starting with version 0.8.6c, Cacti is able to parse unique indexes from the OID itself. While the regular expression used for parsing the value from the OID is defined below, you must still specify an OID that can be walked by Cacti in order to obtain the list of OID's. Any OID defined for one of your input fields should work in this case. The values returned from the snmpwalk walk will be completely disregarded.
query->oid_index_parse	This field should only be used if you are trying to parse the unique index from the OID itself. If this field is defined, to obtain a list of indexes, Cacti walks the OID provided in the oid_index field above. It then applies the regular expression provided in this field to the list of OID's that are returned. The matched substrings that remain become the list of indexes for this SNMP query.
query->oid_num_indexes	An OID that can be queried to determine the total number of available indexes. If specified, this will be used to determine when to automatically recache this SNMP query when it is attached to a device.
query->index_order	As of version 0.8.6, Cacti will attempt to find the best field to index off of based on whether each row in the query is unique and non-null. If specified, Cacti will perform this check on the fields listed here in the order specified. Only input fields can be specified and multiple fields should be delimited with a colon.
query->index_order_type	For sorting purposes, specify whether the index is numeric or alphanumeric. `numeric`: The indexes in this SNMP query are to be sorted numerically (ie. 1,2,3,10,20,31) `alphabetic`: The indexes in this SNMP query are to be sorted alphabetically (1,10,2,20,3,31).
query->index_title_format	Specify the title format to use when representing an index to the user. Any input field name can be used as a variable if enclosed in pipes (\|). The variable `\|chosen_order_field\|` will be substituted with the field chosen by Cacti to index off of (see index_order above).
query->fields	Each field contained within the SNMP query must be defined under this tag.
query->fields->ifIndex	Each defined field in the SNMP query must have a unique name given to it. Do not use spaces or any non-alphanumeric characters, this name must be identifiable within Cacti.
query->fields->ifIndex->name	Here you can specify a "friendly name" for the field. This name will be used by Cacti to help the user identify this field.
query->fields->ifIndex->method	Tell Cacti how you want it to gather SNMP information for this field. `get`: The 'get' method obtains a list of indexes and does an snmpget for each index of the OID specified for this field. `walk`: The 'walk' method does a walk of the OID specified for this field. Both methods will return the same values, even though the 'walk' method is typically more efficient.
query->fields->ifIndex->source	When Cacti obtains a list for this field, you need to tell it how to derive its value for each row. `value`: The 'value' option simply returns the result of the snmpget for each row. `OID/REGEXP:(regexp_match)`: The 'OID/REGEXP:(regexp_match)' can be used when you need to use a POSIX-based regular expression to derive the value from the OID. The most common example of this is to retreive the IP address of an interface, and can be seen in the 'interface.xml' file. `VALUE/REGEXP:(regexp_match)`: The 'OID/REGEXP:(regexp_match)' option can be used to parse the value based on a regular expression, returning the first match. `index`: Simply use the value of the index for this row as the value. If the index is being parsed from the OID using the oid_index_parse field, you must specify `index` here.
query->fields->ifIndex->direction	`input`: Input values are the "known" values that you will use to derive the output values, this is where the "query" part of SNMP query comes in. When you create a graph based on an SNMP query, Cacti will prompt you to choose the input value to base the graph on. `output`: Output values are "unknown" values that are returned from the script. An SNMP query may return multiple statistics for a single index. For instance, a single interface could return bytes/sec in, errors, packets/sec, etc. A rule of thumb is that input fields contain semi-static data that is not graphable, while the output fields contain the data that will be graphed.
query->fields->ifIndex->oid	You must specify the actual OID that corresponds with the field. Each value for this field can be obtained by doing an snmpget on 'oid.(each)snmpindex'.