--- title: Telegraf Documentation description: Telegraf plugin for collecting metrics from Unbound url: https://docs.influxdata.com/telegraf/v1/input-plugins/unbound/ estimated_tokens: 2810 product: Telegraf version: v1 --- - Telegraf v1.5.0+ # Unbound Input Plugin This plugin gathers stats from an [Unbound](https://www.unbound.net) DNS resolver. **Introduced in:** Telegraf v1.5.0 **Tags:** server, network **OS support:** all ## Global configuration options Plugins support additional global and plugin configuration settings for tasks such as modifying metrics, tags, and fields, creating aliases, and configuring plugin ordering. See [CONFIGURATION.md](/telegraf/v1/configuration/#plugins) for more details. ## Configuration ```toml # A plugin to collect stats from the Unbound DNS resolver [[inputs.unbound]] ## Address of server to connect to, read from unbound conf default, optionally ':port' ## Will lookup IP if given a hostname server = "127.0.0.1:8953" ## If running as a restricted user you can prepend sudo for additional access: # use_sudo = false ## The default location of the unbound-control binary can be overridden with: # binary = "/usr/sbin/unbound-control" ## The default location of the unbound config file can be overridden with: # config_file = "/etc/unbound/unbound.conf" ## The default timeout of 1s can be overridden with: # timeout = "1s" ## When set to true, thread metrics are tagged with the thread id. ## ## The default is false for backwards compatibility, and will be changed to ## true in a future version. It is recommended to set to true on new ## deployments. thread_as_tag = false ## Collect metrics with the histogram of the recursive query times: # histogram = false ``` ### Permissions It’s important to note that this plugin references unbound-control, which may require additional permissions to execute successfully. Depending on the user/group permissions of the telegraf user executing this plugin, you may need to alter the group membership, set facls, or use sudo. #### Group membership (recommended) ```bash $ groups telegraf telegraf : telegraf $ usermod -a -G unbound telegraf $ groups telegraf telegraf : telegraf unbound ``` #### Sudo privileges If you use this method, you will need the following in your telegraf config: ```toml [[inputs.unbound]] use_sudo = true ``` You will also need to update your sudoers file: ```bash $ visudo # Add the following line: Cmnd_Alias UNBOUNDCTL = /usr/sbin/unbound-control telegraf ALL=(ALL) NOPASSWD: UNBOUNDCTL Defaults!UNBOUNDCTL !logfile, !syslog, !pam_session ``` Please use the solution you see as most appropriate. ## Metrics This is the full list of stats provided by unbound-control and potentially collected depending of your unbound configuration. Extended statistics can also be imported (“extended-statistics: yes” in unbound configuration). In the output, the dots in the unbound-control stat name are replaced by underscores(see [https://www.unbound.net/documentation/unbound-control.html](https://www.unbound.net/documentation/unbound-control.html) for details). Shown metrics are with `thread_as_tag` enabled. - unbound - fields: total\_num\_queries total\_num\_cachehits total\_num\_cachemiss total\_num\_prefetch total\_num\_recursivereplies total\_requestlist\_avg total\_requestlist\_max total\_requestlist\_overwritten total\_requestlist\_exceeded total\_requestlist\_current\_all total\_requestlist\_current\_user total\_recursion\_time\_avg total\_recursion\_time\_median time\_now time\_up time\_elapsed mem\_total\_sbrk mem\_cache\_rrset mem\_cache\_message mem\_mod\_iterator mem\_mod\_validator num\_query\_type\_A num\_query\_type\_PTR num\_query\_type\_TXT num\_query\_type\_AAAA num\_query\_type\_SRV num\_query\_type\_ANY num\_query\_class\_IN num\_query\_opcode\_QUERY num\_query\_tcp num\_query\_ipv6 num\_query\_flags\_QR num\_query\_flags\_AA num\_query\_flags\_TC num\_query\_flags\_RD num\_query\_flags\_RA num\_query\_flags\_Z num\_query\_flags\_AD num\_query\_flags\_CD num\_query\_edns\_present num\_query\_edns\_DO num\_answer\_rcode\_NOERROR num\_answer\_rcode\_SERVFAIL num\_answer\_rcode\_NXDOMAIN num\_answer\_rcode\_nodata num\_answer\_secure num\_answer\_bogus num\_rrset\_bogus unwanted\_queries unwanted\_replies - unbound\_thread - tags: - thread - fields: - num\_queries - num\_cachehits - num\_cachemiss - num\_prefetch - num\_recursivereplies - requestlist\_avg - requestlist\_max - requestlist\_overwritten - requestlist\_exceeded - requestlist\_current\_all - requestlist\_current\_user - recursion\_time\_avg - recursion\_time\_median If `histogram` is set to true, the following metrics are also collected, with the field name indicating the lower bound of each histogram bin: - unbound: - fields: histogram\_.000000 histogram\_.000001 histogram\_.000002 histogram\_.000004 histogram\_.000008 histogram\_.000016 histogram\_.000032 histogram\_.000064 histogram\_.000128 histogram\_.000256 histogram\_.000512 histogram\_.001024 histogram\_.002048 histogram\_.004096 histogram\_.008192 histogram\_.016384 histogram\_.032768 histogram\_.065536 histogram\_.131072 histogram\_.262144 histogram\_.524288 histogram\_1.000000 histogram\_2.000000 histogram\_4.000000 histogram\_8.000000 histogram\_16.000000 histogram\_32.000000 histogram\_64.000000 histogram\_128.000000 histogram\_256.000000 histogram\_512.000000 histogram\_1024.000000 histogram\_2048.000000 histogram\_4096.000000 histogram\_8192.000000 histogram\_16384.000000 histogram\_32768.000000 histogram\_65536.000000 histogram\_131072.000000 histogram\_262144.000000 ## Example Output ```text unbound,host=localhost total_requestlist_avg=0,total_requestlist_exceeded=0,total_requestlist_overwritten=0,total_requestlist_current_user=0,total_recursion_time_avg=0.029186,total_tcpusage=0,total_num_queries=51,total_num_queries_ip_ratelimited=0,total_num_recursivereplies=6,total_requestlist_max=0,time_now=1522804978.784814,time_elapsed=310.435217,total_num_cachemiss=6,total_num_zero_ttl=0,time_up=310.435217,total_num_cachehits=45,total_num_prefetch=0,total_requestlist_current_all=0,total_recursion_time_median=0.016384 1522804979000000000 unbound_threads,host=localhost,thread=0 num_queries_ip_ratelimited=0,requestlist_current_user=0,recursion_time_avg=0.029186,num_prefetch=0,requestlist_overwritten=0,requestlist_exceeded=0,requestlist_current_all=0,tcpusage=0,num_cachehits=37,num_cachemiss=6,num_recursivereplies=6,requestlist_avg=0,num_queries=43,num_zero_ttl=0,requestlist_max=0,recursion_time_median=0.032768 1522804979000000000 unbound_threads,host=localhost,thread=1 num_zero_ttl=0,recursion_time_avg=0,num_queries_ip_ratelimited=0,num_cachehits=8,num_prefetch=0,requestlist_exceeded=0,recursion_time_median=0,tcpusage=0,num_cachemiss=0,num_recursivereplies=0,requestlist_max=0,requestlist_overwritten=0,requestlist_current_user=0,num_queries=8,requestlist_avg=0,requestlist_current_all=0 1522804979000000000 ``` #### Related - [Configure plugins](/telegraf/v1/configure_plugins/) - [Unbound Plugin Source](https://github.com/influxdata/telegraf/tree/v1.38.4/plugins/inputs/unbound/README.md)