# SNMP Input Plugin The SNMP input plugin gathers metrics from SNMP agents ### Configuration: #### Very simple example In this example, the plugin will gather value of OIDS: - `.1.3.6.1.2.1.2.2.1.4.1` ```toml # Very Simple Example [[inputs.snmp]] [[inputs.snmp.host]] address = "127.0.0.1:161" # SNMP community community = "public" # default public # SNMP version (1, 2 or 3) # Version 3 not supported yet version = 2 # default 2 # Simple list of OIDs to get, in addition to "collect" get_oids = [".1.3.6.1.2.1.2.2.1.4.1"] ``` #### Simple example In this example, Telegraf gathers value of OIDS: - named **ifnumber** - named **interface_speed** With **inputs.snmp.get** section the plugin gets the oid number: - **ifnumber** => `.1.3.6.1.2.1.2.1.0` - **interface_speed** => *ifSpeed* As you can see *ifSpeed* is not a valid OID. In order to get the valid OID, the plugin uses `snmptranslate_file` to match the OID: - **ifnumber** => `.1.3.6.1.2.1.2.1.0` - **interface_speed** => *ifSpeed* => `.1.3.6.1.2.1.2.2.1.5` Also as the plugin will append `instance` to the corresponding OID: - **ifnumber** => `.1.3.6.1.2.1.2.1.0` - **interface_speed** => *ifSpeed* => `.1.3.6.1.2.1.2.2.1.5.1` In this example, the plugin will gather value of OIDS: - `.1.3.6.1.2.1.2.1.0` - `.1.3.6.1.2.1.2.2.1.5.1` ```toml # Simple example [[inputs.snmp]] ## Use 'oids.txt' file to translate oids to names ## To generate 'oids.txt' you need to run: ## snmptranslate -m all -Tz -On | sed -e 's/"//g' > /tmp/oids.txt ## Or if you have an other MIB folder with custom MIBs ## snmptranslate -M /mycustommibfolder -Tz -On -m all | sed -e 's/"//g' > oids.txt snmptranslate_file = "/tmp/oids.txt" [[inputs.snmp.host]] address = "127.0.0.1:161" # SNMP community community = "public" # default public # SNMP version (1, 2 or 3) # Version 3 not supported yet version = 2 # default 2 # Which get/bulk do you want to collect for this host collect = ["ifnumber", "interface_speed"] [[inputs.snmp.get]] name = "ifnumber" oid = ".1.3.6.1.2.1.2.1.0" [[inputs.snmp.get]] name = "interface_speed" oid = "ifSpeed" instance = "1" ``` #### Simple bulk example In this example, Telegraf gathers value of OIDS: - named **ifnumber** - named **interface_speed** - named **if_out_octets** With **inputs.snmp.get** section the plugin gets oid number: - **ifnumber** => `.1.3.6.1.2.1.2.1.0` - **interface_speed** => *ifSpeed* With **inputs.snmp.bulk** section the plugin gets the oid number: - **if_out_octets** => *ifOutOctets* As you can see *ifSpeed* and *ifOutOctets* are not a valid OID. In order to get the valid OID, the plugin uses `snmptranslate_file` to match the OID: - **ifnumber** => `.1.3.6.1.2.1.2.1.0` - **interface_speed** => *ifSpeed* => `.1.3.6.1.2.1.2.2.1.5` - **if_out_octets** => *ifOutOctets* => `.1.3.6.1.2.1.2.2.1.16` Also, the plugin will append `instance` to the corresponding OID: - **ifnumber** => `.1.3.6.1.2.1.2.1.0` - **interface_speed** => *ifSpeed* => `.1.3.6.1.2.1.2.2.1.5.1` And **if_out_octets** is a bulk request, the plugin will gathers all OIDS in the table. - `.1.3.6.1.2.1.2.2.1.16.1` - `.1.3.6.1.2.1.2.2.1.16.2` - `.1.3.6.1.2.1.2.2.1.16.3` - `.1.3.6.1.2.1.2.2.1.16.4` - `.1.3.6.1.2.1.2.2.1.16.5` - `...` In this example, the plugin will gather value of OIDS: - `.1.3.6.1.2.1.2.1.0` - `.1.3.6.1.2.1.2.2.1.5.1` - `.1.3.6.1.2.1.2.2.1.16.1` - `.1.3.6.1.2.1.2.2.1.16.2` - `.1.3.6.1.2.1.2.2.1.16.3` - `.1.3.6.1.2.1.2.2.1.16.4` - `.1.3.6.1.2.1.2.2.1.16.5` - `...` ```toml # Simple bulk example [[inputs.snmp]] ## Use 'oids.txt' file to translate oids to names ## To generate 'oids.txt' you need to run: ## snmptranslate -m all -Tz -On | sed -e 's/"//g' > /tmp/oids.txt ## Or if you have an other MIB folder with custom MIBs ## snmptranslate -M /mycustommibfolder -Tz -On -m all | sed -e 's/"//g' > oids.txt snmptranslate_file = "/tmp/oids.txt" [[inputs.snmp.host]] address = "127.0.0.1:161" # SNMP community community = "public" # default public # SNMP version (1, 2 or 3) # Version 3 not supported yet version = 2 # default 2 # Which get/bulk do you want to collect for this host collect = ["interface_speed", "if_number", "if_out_octets"] [[inputs.snmp.get]] name = "interface_speed" oid = "ifSpeed" instance = "1" [[inputs.snmp.get]] name = "if_number" oid = "ifNumber" [[inputs.snmp.bulk]] name = "if_out_octets" oid = "ifOutOctets" ``` #### Table example In this example, we remove collect attribute to the host section, but you can still use it in combination of the following part. Note: This example is like a bulk request a but using an other configuration Telegraf gathers value of OIDS of the table: - named **iftable1** With **inputs.snmp.table** section the plugin gets oid number: - **iftable1** => `.1.3.6.1.2.1.31.1.1.1` Also **iftable1** is a table, the plugin will gathers all OIDS in the table and in the subtables - `.1.3.6.1.2.1.31.1.1.1.1` - `.1.3.6.1.2.1.31.1.1.1.1.1` - `.1.3.6.1.2.1.31.1.1.1.1.2` - `.1.3.6.1.2.1.31.1.1.1.1.3` - `.1.3.6.1.2.1.31.1.1.1.1.4` - `.1.3.6.1.2.1.31.1.1.1.1....` - `.1.3.6.1.2.1.31.1.1.1.2` - `.1.3.6.1.2.1.31.1.1.1.2....` - `.1.3.6.1.2.1.31.1.1.1.3` - `.1.3.6.1.2.1.31.1.1.1.3....` - `.1.3.6.1.2.1.31.1.1.1.4` - `.1.3.6.1.2.1.31.1.1.1.4....` - `.1.3.6.1.2.1.31.1.1.1.5` - `.1.3.6.1.2.1.31.1.1.1.5....` - `.1.3.6.1.2.1.31.1.1.1.6....` - `...` ```toml # Table example [[inputs.snmp]] ## Use 'oids.txt' file to translate oids to names ## To generate 'oids.txt' you need to run: ## snmptranslate -m all -Tz -On | sed -e 's/"//g' > /tmp/oids.txt ## Or if you have an other MIB folder with custom MIBs ## snmptranslate -M /mycustommibfolder -Tz -On -m all | sed -e 's/"//g' > oids.txt snmptranslate_file = "/tmp/oids.txt" [[inputs.snmp.host]] address = "127.0.0.1:161" # SNMP community community = "public" # default public # SNMP version (1, 2 or 3) # Version 3 not supported yet version = 2 # default 2 # Which get/bulk do you want to collect for this host # Which table do you want to collect [[inputs.snmp.host.table]] name = "iftable1" # table without mapping neither subtables # This is like bulk request [[inputs.snmp.table]] name = "iftable1" oid = ".1.3.6.1.2.1.31.1.1.1" ``` #### Table with subtable example In this example, we remove collect attribute to the host section, but you can still use it in combination of the following part. Note: This example is like a bulk request a but using an other configuration Telegraf gathers value of OIDS of the table: - named **iftable2** With **inputs.snmp.table** section *AND* **sub_tables** attribute, the plugin will get OIDS from subtables: - **iftable2** => `.1.3.6.1.2.1.2.2.1.13` Also **iftable2** is a table, the plugin will gathers all OIDS in subtables: - `.1.3.6.1.2.1.2.2.1.13.1` - `.1.3.6.1.2.1.2.2.1.13.2` - `.1.3.6.1.2.1.2.2.1.13.3` - `.1.3.6.1.2.1.2.2.1.13.4` - `.1.3.6.1.2.1.2.2.1.13....` ```toml # Table with subtable example [[inputs.snmp]] ## Use 'oids.txt' file to translate oids to names ## To generate 'oids.txt' you need to run: ## snmptranslate -m all -Tz -On | sed -e 's/"//g' > /tmp/oids.txt ## Or if you have an other MIB folder with custom MIBs ## snmptranslate -M /mycustommibfolder -Tz -On -m all | sed -e 's/"//g' > oids.txt snmptranslate_file = "/tmp/oids.txt" [[inputs.snmp.host]] address = "127.0.0.1:161" # SNMP community community = "public" # default public # SNMP version (1, 2 or 3) # Version 3 not supported yet version = 2 # default 2 # Which table do you want to collect [[inputs.snmp.host.table]] name = "iftable2" # table without mapping but with subtables [[inputs.snmp.table]] name = "iftable2" sub_tables = [".1.3.6.1.2.1.2.2.1.13"] # note # oid attribute is useless ``` #### Table with mapping example In this example, we remove collect attribute to the host section, but you can still use it in combination of the following part. Telegraf gathers value of OIDS of the table: - named **iftable3** With **inputs.snmp.table** section the plugin gets oid number: - **iftable3** => `.1.3.6.1.2.1.31.1.1.1` Also **iftable2** is a table, the plugin will gathers all OIDS in the table and in the subtables - `.1.3.6.1.2.1.31.1.1.1.1` - `.1.3.6.1.2.1.31.1.1.1.1.1` - `.1.3.6.1.2.1.31.1.1.1.1.2` - `.1.3.6.1.2.1.31.1.1.1.1.3` - `.1.3.6.1.2.1.31.1.1.1.1.4` - `.1.3.6.1.2.1.31.1.1.1.1....` - `.1.3.6.1.2.1.31.1.1.1.2` - `.1.3.6.1.2.1.31.1.1.1.2....` - `.1.3.6.1.2.1.31.1.1.1.3` - `.1.3.6.1.2.1.31.1.1.1.3....` - `.1.3.6.1.2.1.31.1.1.1.4` - `.1.3.6.1.2.1.31.1.1.1.4....` - `.1.3.6.1.2.1.31.1.1.1.5` - `.1.3.6.1.2.1.31.1.1.1.5....` - `.1.3.6.1.2.1.31.1.1.1.6....` - `...` But the **include_instances** attribute will filter which OIDS will be gathered; As you see, there is an other attribute, `mapping_table`. `include_instances` and `mapping_table` permit to build a hash table to filter only OIDS you want. Let's say, we have the following data on SNMP server: - OID: `.1.3.6.1.2.1.31.1.1.1.1.1` has as value: `enp5s0` - OID: `.1.3.6.1.2.1.31.1.1.1.1.2` has as value: `enp5s1` - OID: `.1.3.6.1.2.1.31.1.1.1.1.3` has as value: `enp5s2` - OID: `.1.3.6.1.2.1.31.1.1.1.1.4` has as value: `eth0` - OID: `.1.3.6.1.2.1.31.1.1.1.1.5` has as value: `eth1` The plugin will build the following hash table: | instance name | instance id | |---------------|-------------| | `enp5s0` | `1` | | `enp5s1` | `2` | | `enp5s2` | `3` | | `eth0` | `4` | | `eth1` | `5` | With the **include_instances** attribute, the plugin will gather the following OIDS: - `.1.3.6.1.2.1.31.1.1.1.1.1` - `.1.3.6.1.2.1.31.1.1.1.1.5` - `.1.3.6.1.2.1.31.1.1.1.2.1` - `.1.3.6.1.2.1.31.1.1.1.2.5` - `.1.3.6.1.2.1.31.1.1.1.3.1` - `.1.3.6.1.2.1.31.1.1.1.3.5` - `.1.3.6.1.2.1.31.1.1.1.4.1` - `.1.3.6.1.2.1.31.1.1.1.4.5` - `.1.3.6.1.2.1.31.1.1.1.5.1` - `.1.3.6.1.2.1.31.1.1.1.5.5` - `.1.3.6.1.2.1.31.1.1.1.6.1` - `.1.3.6.1.2.1.31.1.1.1.6.5` - `...` Note: the plugin will add instance name as tag *instance* ```toml # Simple table with mapping example [[inputs.snmp]] ## Use 'oids.txt' file to translate oids to names ## To generate 'oids.txt' you need to run: ## snmptranslate -m all -Tz -On | sed -e 's/"//g' > /tmp/oids.txt ## Or if you have an other MIB folder with custom MIBs ## snmptranslate -M /mycustommibfolder -Tz -On -m all | sed -e 's/"//g' > oids.txt snmptranslate_file = "/tmp/oids.txt" [[inputs.snmp.host]] address = "127.0.0.1:161" # SNMP community community = "public" # default public # SNMP version (1, 2 or 3) # Version 3 not supported yet version = 2 # default 2 # Which table do you want to collect [[inputs.snmp.host.table]] name = "iftable3" include_instances = ["enp5s0", "eth1"] # table with mapping but without subtables [[inputs.snmp.table]] name = "iftable3" oid = ".1.3.6.1.2.1.31.1.1.1" # if empty. get all instances mapping_table = ".1.3.6.1.2.1.31.1.1.1.1" # if empty, get all subtables ``` #### Table with both mapping and subtable example In this example, we remove collect attribute to the host section, but you can still use it in combination of the following part. Telegraf gathers value of OIDS of the table: - named **iftable4** With **inputs.snmp.table** section *AND* **sub_tables** attribute, the plugin will get OIDS from subtables: - **iftable4** => `.1.3.6.1.2.1.31.1.1.1` Also **iftable2** is a table, the plugin will gathers all OIDS in the table and in the subtables - `.1.3.6.1.2.1.31.1.1.1.6.1 - `.1.3.6.1.2.1.31.1.1.1.6.2` - `.1.3.6.1.2.1.31.1.1.1.6.3` - `.1.3.6.1.2.1.31.1.1.1.6.4` - `.1.3.6.1.2.1.31.1.1.1.6....` - `.1.3.6.1.2.1.31.1.1.1.10.1` - `.1.3.6.1.2.1.31.1.1.1.10.2` - `.1.3.6.1.2.1.31.1.1.1.10.3` - `.1.3.6.1.2.1.31.1.1.1.10.4` - `.1.3.6.1.2.1.31.1.1.1.10....` But the **include_instances** attribute will filter which OIDS will be gathered; As you see, there is an other attribute, `mapping_table`. `include_instances` and `mapping_table` permit to build a hash table to filter only OIDS you want. Let's say, we have the following data on SNMP server: - OID: `.1.3.6.1.2.1.31.1.1.1.1.1` has as value: `enp5s0` - OID: `.1.3.6.1.2.1.31.1.1.1.1.2` has as value: `enp5s1` - OID: `.1.3.6.1.2.1.31.1.1.1.1.3` has as value: `enp5s2` - OID: `.1.3.6.1.2.1.31.1.1.1.1.4` has as value: `eth0` - OID: `.1.3.6.1.2.1.31.1.1.1.1.5` has as value: `eth1` The plugin will build the following hash table: | instance name | instance id | |---------------|-------------| | `enp5s0` | `1` | | `enp5s1` | `2` | | `enp5s2` | `3` | | `eth0` | `4` | | `eth1` | `5` | With the **include_instances** attribute, the plugin will gather the following OIDS: - `.1.3.6.1.2.1.31.1.1.1.6.1` - `.1.3.6.1.2.1.31.1.1.1.6.5` - `.1.3.6.1.2.1.31.1.1.1.10.1` - `.1.3.6.1.2.1.31.1.1.1.10.5` Note: the plugin will add instance name as tag *instance* ```toml # Table with both mapping and subtable example [[inputs.snmp]] ## Use 'oids.txt' file to translate oids to names ## To generate 'oids.txt' you need to run: ## snmptranslate -m all -Tz -On | sed -e 's/"//g' > /tmp/oids.txt ## Or if you have an other MIB folder with custom MIBs ## snmptranslate -M /mycustommibfolder -Tz -On -m all | sed -e 's/"//g' > oids.txt snmptranslate_file = "/tmp/oids.txt" [[inputs.snmp.host]] address = "127.0.0.1:161" # SNMP community community = "public" # default public # SNMP version (1, 2 or 3) # Version 3 not supported yet version = 2 # default 2 # Which table do you want to collect [[inputs.snmp.host.table]] name = "iftable4" include_instances = ["enp5s0", "eth1"] # table with both mapping and subtables [[inputs.snmp.table]] name = "iftable4" # if empty get all instances mapping_table = ".1.3.6.1.2.1.31.1.1.1.1" # if empty get all subtables # sub_tables could be not "real subtables" sub_tables=[".1.3.6.1.2.1.2.2.1.13", "bytes_recv", "bytes_send"] # note # oid attribute is useless # SNMP SUBTABLES [[plugins.snmp.subtable]] name = "bytes_recv" oid = ".1.3.6.1.2.1.31.1.1.1.6" unit = "octets" [[plugins.snmp.subtable]] name = "bytes_send" oid = ".1.3.6.1.2.1.31.1.1.1.10" unit = "octets" ``` #### Configuration notes - In **plugins.snmp.table** section, the `oid` attribute is useless if the `sub_tables` attributes is defined - In **plugins.snmp.subtable** section, you can put a name from `snmptranslate_file` as `oid` attribute instead of a valid OID ### Measurements & Fields: With the last example (Table with both mapping and subtable example): - ifHCOutOctets - ifHCOutOctets - ifInDiscards - ifInDiscards - ifHCInOctets - ifHCInOctets ### Tags: With the last example (Table with both mapping and subtable example): - ifHCOutOctets - host - instance - unit - ifInDiscards - host - instance - ifHCInOctets - host - instance - unit ### Example Output: With the last example (Table with both mapping and subtable example): ``` ifHCOutOctets,host=127.0.0.1,instance=enp5s0,unit=octets ifHCOutOctets=10565628i 1456878706044462901 ifInDiscards,host=127.0.0.1,instance=enp5s0 ifInDiscards=0i 1456878706044510264 ifHCInOctets,host=127.0.0.1,instance=enp5s0,unit=octets ifHCInOctets=76351777i 1456878706044531312 ```