Built-in webserver

To visually interact with dnsdist, a webserver can be enabled.

webserver:
  listen_address: "127.0.0.1:8083"
  password: "supersecretpassword"
  api_key: "supersecretAPIkey"

Add webserver() and setWebserverConfig() directives to the configuration:

webserver("127.0.0.1:8083")
setWebserverConfig({password="supersecretpassword", apiKey="supersecretAPIkey"})

Now point your browser at http://127.0.0.1:8083 and log in with any username, and that password. Enjoy!

Only connections from 127.0.0.1 and ::1 are allowed by default. To allow connections from 192.0.2.0/24 but not from 192.0.2.1

webserver:
  listen_address: "127.0.0.1:8083"
  password: "supersecretpassword"
  api_key: "supersecretAPIkey"
  acl:
    - "192.0.2.0/24"
    - "!192.0.2.1"

Add webserver() and setWebserverConfig() directives to the configuration:

webserver("127.0.0.1:8083")
setWebserverConfig({password="supersecretpassword", apiKey="supersecretAPIkey", acl="192.0.2.0/24, !192.0.2.1"})

Warning

To achieve defense-in-depth, expose the webserver only to client addresses that have a real need for access using the listen address and acls.

Security of the Webserver

The built-in webserver serves its content from inside the binary, this means it will not and cannot read from disk.

By default, our web server sends some security-related headers:

X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Permitted-Cross-Domain-Policies: none
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'

You can override those headers, or add custom headers. For example, to remove the X-Frame-Options header and add a X-Custom one:

webserver:
  listen_address: "127.0.0.1:8083"
  password: "supersecretpassword"
  api_key: "supersecretAPIkey"
  custom_headers:
    - key: "X-Frame-Options"
      value: ""
    - key: "X-Custom"
      value: "custom"

Use the last parameter to setWebserverConfig().

webserver("127.0.0.1:8083")
setWebserverConfig({password="supersecretpassword", apiKey="supersecretAPIkey", customHeaders={["X-Frame-Options"]= "", ["X-Custom"]="custom"} })

Credentials

The webserver uses two kind of authorization: one is HTTP basic auth, with name and password; username doesn’t matter, only password is checked. Second kind of authorization is with an API key, which must be in X-API-Key request header. Those keys can be different, and are two different options to setWebserverConfig().

There are also three different options for setWebserverConfig(), which can disable the auth for the calls altogether by setting them to false; they are true by default.

endpoint

option to disable auth

basic auth

API header auth

main dashboard

dashboardRequiresAuthentication

allowed

not allowed

/jsonstat

statsRequireAuthentication

allowed

allowed

/metrics

statsRequireAuthentication

allowed

allowed

/api/v1/servers/localhost

dashboardRequiresAuthentication

allowed

allowed

other /api/ endpoints

apiRequiresAuthentication

not allowed

allowed

Credentials can be changed at run time using the setWebserverConfig() function.

dnsdist API

To access the API, the apikey must be set in the setWebserverConfig() function. Use the API, this key will need to be sent to dnsdist in the X-API-Key request header. An HTTP 401 response is returned when a wrong or no API key is received. A 404 response is generated is the requested endpoint does not exist. And a 405 response is returned when the HTTP method is not allowed.

URL Endpoints

GET /jsonstat
Query Parameters:

  • command (string) – one of stats, dynblocklist or ebpfblocklist

Get statistics from dnsdist in JSON format. The Accept request header is ignored.

This endpoint accepts a command query for different statistics:

  • stats: Get all Statistics as a JSON dict

  • dynblocklist: Get all current dynamic blocks, keyed by netmask

  • ebpfblocklist: Idem, but for eBPF blocks

Example request:

GET /jsonstat?command=stats HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Connection: close
Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'
Content-Type: application/json
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Permitted-Cross-Domain-Policies: none
X-Xss-Protection: 1; mode=block

{"acl-drops": 0, "cache-hits": 0, "cache-misses": 0, "cpu-sys-msec": 633, "cpu-user-msec": 499, "downstream-send-errors": 0, "downstream-timeouts": 0, "dyn-block-nmg-size": 1, "dyn-blocked": 3, "empty-queries": 0, "fd-usage": 17, "latency-avg100": 7651.3982737482893, "latency-avg1000": 860.05142763680249, "latency-avg10000": 87.032142373878372, "latency-avg1000000": 0.87146026426551759, "latency-slow": 0, "latency0-1": 0, "latency1-10": 0, "latency10-50": 22, "latency100-1000": 1, "latency50-100": 0, "no-policy": 0, "noncompliant-queries": 0, "noncompliant-responses": 0, "over-capacity-drops": 0, "packetcache-hits": 0, "packetcache-misses": 0, "queries": 26, "rdqueries": 26, "real-memory-usage": 6078464, "responses": 23, "rule-drop": 0, "rule-nxdomain": 0, "rule-refused": 0, "self-answered": 0, "server-policy": "leastOutstanding", "servfail-responses": 0, "too-old-drops": 0, "trunc-failures": 0, "uptime": 412}

Example request:

GET /jsonstat?command=dynblocklist HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Connection: close
Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'
Content-Type: application/json
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Permitted-Cross-Domain-Policies: none
X-Xss-Protection: 1; mode=block

{"127.0.0.1/32": {"blocks": 3, "reason": "Exceeded query rate", "seconds": 10}}
GET /metrics

Get statistics from dnsdist in Prometheus format.

Example request:

GET /metrics HTTP/1.1

Example response:

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'
Content-Type: text/plain
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Permitted-Cross-Domain-Policies: none
X-Xss-Protection: 1; mode=block

# HELP dnsdist_responses Number of responses received from backends
# TYPE dnsdist_responses counter
dnsdist_responses 0
# HELP dnsdist_servfail_responses Number of SERVFAIL answers received from backends
# TYPE dnsdist_servfail_responses counter
dnsdist_servfail_responses 0
# HELP dnsdist_queries Number of received queries
# TYPE dnsdist_queries counter
dnsdist_queries 0
# HELP dnsdist_frontend_nxdomain Number of NXDomain answers sent to clients
# TYPE dnsdist_frontend_nxdomain counter
dnsdist_frontend_nxdomain 0
# HELP dnsdist_frontend_servfail Number of SERVFAIL answers sent to clients
# TYPE dnsdist_frontend_servfail counter
dnsdist_frontend_servfail 0
# HELP dnsdist_frontend_noerror Number of NoError answers sent to clients
# TYPE dnsdist_frontend_noerror counter
dnsdist_frontend_noerror 0
# HELP dnsdist_acl_drops Number of packets dropped because of the ACL
# TYPE dnsdist_acl_drops counter
dnsdist_acl_drops 0
# HELP dnsdist_rule_drop Number of queries dropped because of a rule
# TYPE dnsdist_rule_drop counter
dnsdist_rule_drop 0
# HELP dnsdist_rule_nxdomain Number of NXDomain answers returned because of a rule
# TYPE dnsdist_rule_nxdomain counter
dnsdist_rule_nxdomain 0
# HELP dnsdist_rule_refused Number of Refused answers returned because of a rule
# TYPE dnsdist_rule_refused counter
dnsdist_rule_refused 0
# HELP dnsdist_rule_servfail Number of SERVFAIL answers received because of a rule
# TYPE dnsdist_rule_servfail counter
dnsdist_rule_servfail 0
# HELP dnsdist_rule_truncated Number of truncated answers returned because of a rule
# TYPE dnsdist_rule_truncated counter
dnsdist_rule_truncated 0
# HELP dnsdist_self_answered Number of self-answered responses
# TYPE dnsdist_self_answered counter
dnsdist_self_answered 0
# HELP dnsdist_downstream_timeouts Number of queries not answered in time by a backend
# TYPE dnsdist_downstream_timeouts counter
dnsdist_downstream_timeouts 0
# HELP dnsdist_downstream_send_errors Number of errors when sending a query to a backend
# TYPE dnsdist_downstream_send_errors counter
dnsdist_downstream_send_errors 0
# HELP dnsdist_trunc_failures Number of errors encountered while truncating an answer
# TYPE dnsdist_trunc_failures counter
dnsdist_trunc_failures 0
# HELP dnsdist_no_policy Number of queries dropped because no server was available
# TYPE dnsdist_no_policy counter
dnsdist_no_policy 0
# HELP dnsdist_latency0_1 Number of queries answered in less than 1ms
# TYPE dnsdist_latency0_1 counter
dnsdist_latency0_1 0
# HELP dnsdist_latency1_10 Number of queries answered in 1-10 ms
# TYPE dnsdist_latency1_10 counter
dnsdist_latency1_10 0
# HELP dnsdist_latency10_50 Number of queries answered in 10-50 ms
# TYPE dnsdist_latency10_50 counter
dnsdist_latency10_50 0
# HELP dnsdist_latency50_100 Number of queries answered in 50-100 ms
# TYPE dnsdist_latency50_100 counter
dnsdist_latency50_100 0
# HELP dnsdist_latency100_1000 Number of queries answered in 100-1000 ms
# TYPE dnsdist_latency100_1000 counter
dnsdist_latency100_1000 0
# HELP dnsdist_latency_slow Number of queries answered in more than 1 second
# TYPE dnsdist_latency_slow counter
dnsdist_latency_slow 0
# HELP dnsdist_latency_avg100 Average response latency in microseconds of the last 100 packets
# TYPE dnsdist_latency_avg100 gauge
dnsdist_latency_avg100 0
# HELP dnsdist_latency_avg1000 Average response latency in microseconds of the last 1000 packets
# TYPE dnsdist_latency_avg1000 gauge
dnsdist_latency_avg1000 0
# HELP dnsdist_latency_avg10000 Average response latency in microseconds of the last 10000 packets
# TYPE dnsdist_latency_avg10000 gauge
dnsdist_latency_avg10000 0
# HELP dnsdist_latency_avg1000000 Average response latency in microseconds of the last 1000000 packets
# TYPE dnsdist_latency_avg1000000 gauge
dnsdist_latency_avg1000000 0
# HELP dnsdist_latency_tcp_avg100 Average response latency, in microseconds, of the last 100 packets received over TCP
# TYPE dnsdist_latency_tcp_avg100 gauge
dnsdist_latency_tcp_avg100 0
# HELP dnsdist_latency_tcp_avg1000 Average response latency, in microseconds, of the last 1000 packets received over TCP
# TYPE dnsdist_latency_tcp_avg1000 gauge
dnsdist_latency_tcp_avg1000 0
# HELP dnsdist_latency_tcp_avg10000 Average response latency, in microseconds, of the last 10000 packets received over TCP
# TYPE dnsdist_latency_tcp_avg10000 gauge
dnsdist_latency_tcp_avg10000 0
# HELP dnsdist_latency_tcp_avg1000000 Average response latency, in microseconds, of the last 1000000 packets received over TCP
# TYPE dnsdist_latency_tcp_avg1000000 gauge
dnsdist_latency_tcp_avg1000000 0
# HELP dnsdist_latency_dot_avg100 Average response latency, in microseconds, of the last 100 packets received over DoT
# TYPE dnsdist_latency_dot_avg100 gauge
dnsdist_latency_dot_avg100 0
# HELP dnsdist_latency_dot_avg1000 Average response latency, in microseconds, of the last 1000 packets received over DoT
# TYPE dnsdist_latency_dot_avg1000 gauge
dnsdist_latency_dot_avg1000 0
# HELP dnsdist_latency_dot_avg10000 Average response latency, in microseconds, of the last 10000 packets received over DoT
# TYPE dnsdist_latency_dot_avg10000 gauge
dnsdist_latency_dot_avg10000 0
# HELP dnsdist_latency_dot_avg1000000 Average response latency, in microseconds, of the last 1000000 packets received over DoT
# TYPE dnsdist_latency_dot_avg1000000 gauge
dnsdist_latency_dot_avg1000000 0
# HELP dnsdist_latency_doh_avg100 Average response latency, in microseconds, of the last 100 packets received over DoH
# TYPE dnsdist_latency_doh_avg100 gauge
dnsdist_latency_doh_avg100 0
# HELP dnsdist_latency_doh_avg1000 Average response latency, in microseconds, of the last 1000 packets received over DoH
# TYPE dnsdist_latency_doh_avg1000 gauge
dnsdist_latency_doh_avg1000 0
# HELP dnsdist_latency_doh_avg10000 Average response latency, in microseconds, of the last 10000 packets received over DoH
# TYPE dnsdist_latency_doh_avg10000 gauge
dnsdist_latency_doh_avg10000 0
# HELP dnsdist_latency_doh_avg1000000 Average response latency, in microseconds, of the last 1000000 packets received over DoH
# TYPE dnsdist_latency_doh_avg1000000 gauge
dnsdist_latency_doh_avg1000000 0
# HELP dnsdist_uptime Uptime of the dnsdist process in seconds
# TYPE dnsdist_uptime gauge
dnsdist_uptime 19
# HELP dnsdist_real_memory_usage Current memory usage in bytes
# TYPE dnsdist_real_memory_usage gauge
dnsdist_real_memory_usage 52269056
# HELP dnsdist_udp_in_errors From /proc/net/snmp InErrors
# TYPE dnsdist_udp_in_errors counter
dnsdist_udp_in_errors 0
# HELP dnsdist_udp_noport_errors From /proc/net/snmp NoPorts
# TYPE dnsdist_udp_noport_errors counter
dnsdist_udp_noport_errors 86
# HELP dnsdist_udp_recvbuf_errors From /proc/net/snmp RcvbufErrors
# TYPE dnsdist_udp_recvbuf_errors counter
dnsdist_udp_recvbuf_errors 0
# HELP dnsdist_udp_sndbuf_errors From /proc/net/snmp SndbufErrors
# TYPE dnsdist_udp_sndbuf_errors counter
dnsdist_udp_sndbuf_errors 0
# HELP dnsdist_udp_in_csum_errors From /proc/net/snmp InCsumErrors
# TYPE dnsdist_udp_in_csum_errors counter
dnsdist_udp_in_csum_errors 0
# HELP dnsdist_udp6_in_errors From /proc/net/snmp6 Udp6InErrors
# TYPE dnsdist_udp6_in_errors counter
dnsdist_udp6_in_errors 0
# HELP dnsdist_udp6_recvbuf_errors From /proc/net/snmp6 Udp6RcvbufErrors
# TYPE dnsdist_udp6_recvbuf_errors counter
dnsdist_udp6_recvbuf_errors 0
# HELP dnsdist_udp6_sndbuf_errors From /proc/net/snmp6 Udp6SndbufErrors
# TYPE dnsdist_udp6_sndbuf_errors counter
dnsdist_udp6_sndbuf_errors 0
# HELP dnsdist_udp6_noport_errors From /proc/net/snmp6 Udp6NoPorts
# TYPE dnsdist_udp6_noport_errors counter
dnsdist_udp6_noport_errors 195
# HELP dnsdist_udp6_in_csum_errors From /proc/net/snmp6 Udp6InCsumErrors
# TYPE dnsdist_udp6_in_csum_errors counter
dnsdist_udp6_in_csum_errors 0
# HELP dnsdist_tcp_listen_overflows From /proc/net/netstat ListenOverflows
# TYPE dnsdist_tcp_listen_overflows counter
dnsdist_tcp_listen_overflows 0
# HELP dnsdist_noncompliant_queries Number of queries dropped as non-compliant
# TYPE dnsdist_noncompliant_queries counter
dnsdist_noncompliant_queries 0
# HELP dnsdist_noncompliant_responses Number of answers from a backend dropped as non-compliant
# TYPE dnsdist_noncompliant_responses counter
dnsdist_noncompliant_responses 0
# HELP dnsdist_proxy_protocol_invalid Number of queries dropped because of an invalid Proxy Protocol header
# TYPE dnsdist_proxy_protocol_invalid counter
dnsdist_proxy_protocol_invalid 0
# HELP dnsdist_rdqueries Number of received queries with the recursion desired bit set
# TYPE dnsdist_rdqueries counter
dnsdist_rdqueries 0
# HELP dnsdist_empty_queries Number of empty queries received from clients
# TYPE dnsdist_empty_queries counter
dnsdist_empty_queries 0
# HELP dnsdist_cache_hits Number of times an answer was retrieved from cache
# TYPE dnsdist_cache_hits counter
dnsdist_cache_hits 0
# HELP dnsdist_cache_misses Number of times an answer not found in the cache
# TYPE dnsdist_cache_misses counter
dnsdist_cache_misses 0
# HELP dnsdist_cpu_iowait Time waiting for I/O to complete by the whole system, in units of USER_HZ
# TYPE dnsdist_cpu_iowait counter
dnsdist_cpu_iowait 0
# HELP dnsdist_cpu_steal Stolen time, which is the time spent by the whole system in other operating systems when running in a virtualized environment, in units of USER_HZ
# TYPE dnsdist_cpu_steal counter
dnsdist_cpu_steal 0
# HELP dnsdist_cpu_sys_msec Milliseconds spent by dnsdist in the system state
# TYPE dnsdist_cpu_sys_msec counter
dnsdist_cpu_sys_msec 38
# HELP dnsdist_cpu_user_msec Milliseconds spent by dnsdist in the user state
# TYPE dnsdist_cpu_user_msec counter
dnsdist_cpu_user_msec 38
# HELP dnsdist_fd_usage Number of currently used file descriptors
# TYPE dnsdist_fd_usage gauge
dnsdist_fd_usage 32
# HELP dnsdist_dyn_blocked Number of queries dropped because of a dynamic block
# TYPE dnsdist_dyn_blocked counter
dnsdist_dyn_blocked 0
# HELP dnsdist_dyn_block_nmg_size Number of dynamic blocks entries
# TYPE dnsdist_dyn_block_nmg_size gauge
dnsdist_dyn_block_nmg_size 0
# HELP dnsdist_security_status Security status of this software. 0=unknown, 1=OK, 2=upgrade recommended, 3=upgrade mandatory
# TYPE dnsdist_security_status gauge
dnsdist_security_status 0
# HELP dnsdist_doh_query_pipe_full Number of DoH queries dropped because the internal pipe used to distribute queries was full
# TYPE dnsdist_doh_query_pipe_full counter
dnsdist_doh_query_pipe_full 0
# HELP dnsdist_doh_response_pipe_full Number of DoH responses dropped because the internal pipe used to distribute responses was full
# TYPE dnsdist_doh_response_pipe_full counter
dnsdist_doh_response_pipe_full 0
# HELP dnsdist_outgoing_doh_query_pipe_full Number of outgoing DoH queries dropped because the internal pipe used to distribute queries was full
# TYPE dnsdist_outgoing_doh_query_pipe_full counter
dnsdist_outgoing_doh_query_pipe_full 0
# HELP dnsdist_tcp_query_pipe_full Number of TCP queries dropped because the internal pipe used to distribute queries was full
# TYPE dnsdist_tcp_query_pipe_full counter
dnsdist_tcp_query_pipe_full 0
# HELP dnsdist_tcp_cross_protocol_query_pipe_full Number of TCP cross-protocol queries dropped because the internal pipe used to distribute queries was full
# TYPE dnsdist_tcp_cross_protocol_query_pipe_full counter
dnsdist_tcp_cross_protocol_query_pipe_full 0
# HELP dnsdist_tcp_cross_protocol_response_pipe_full Number of TCP cross-protocol responses dropped because the internal pipe used to distribute queries was full
# TYPE dnsdist_tcp_cross_protocol_response_pipe_full counter
dnsdist_tcp_cross_protocol_response_pipe_full 0
# HELP dnsdist_latency Histogram of responses by latency (in milliseconds)
# TYPE dnsdist_latency histogram
dnsdist_latency_bucket{le="1"} 0
dnsdist_latency_bucket{le="10"} 0
dnsdist_latency_bucket{le="50"} 0
dnsdist_latency_bucket{le="100"} 0
dnsdist_latency_bucket{le="1000"} 0
dnsdist_latency_bucket{le="+Inf"} 0
dnsdist_latency_sum 0
dnsdist_latency_count 0
# HELP dnsdist_server_status Whether this backend is up (1) or down (0)
# TYPE dnsdist_server_status gauge
# HELP dnsdist_server_queries Amount of queries relayed to server
# TYPE dnsdist_server_queries counter
# HELP dnsdist_server_responses Amount of responses received from this server
# TYPE dnsdist_server_responses counter
# HELP dnsdist_server_noncompliantresponses Amount of non-compliant responses received from this server
# TYPE dnsdist_server_noncompliantresponses counter
# HELP dnsdist_server_drops Amount of queries not answered by server
# TYPE dnsdist_server_drops counter
# HELP dnsdist_server_latency Server's latency when answering questions in milliseconds
# TYPE dnsdist_server_latency gauge
# HELP dnsdist_server_senderrors Total number of OS send errors while relaying queries
# TYPE dnsdist_server_senderrors counter
# HELP dnsdist_server_outstanding Current number of queries that are waiting for a backend response
# TYPE dnsdist_server_outstanding gauge
# HELP dnsdist_server_order The order in which this server is picked
# TYPE dnsdist_server_order gauge
# HELP dnsdist_server_weight The weight within the order in which this server is picked
# TYPE dnsdist_server_weight gauge
# HELP dnsdist_server_tcpdiedsendingquery The number of TCP I/O errors while sending the query
# TYPE dnsdist_server_tcpdiedsendingquery counter
# HELP dnsdist_server_tcpdiedreadingresponse The number of TCP I/O errors while reading the response
# TYPE dnsdist_server_tcpdiedreadingresponse counter
# HELP dnsdist_server_tcpgaveup The number of TCP connections failing after too many attempts
# TYPE dnsdist_server_tcpgaveup counter
# HELP dnsdist_server_tcpconnecttimeouts The number of TCP connect timeouts
# TYPE dnsdist_server_tcpconnecttimeouts counter
# HELP dnsdist_server_tcpreadtimeouts The number of TCP read timeouts
# TYPE dnsdist_server_tcpreadtimeouts counter
# HELP dnsdist_server_tcpwritetimeouts The number of TCP write timeouts
# TYPE dnsdist_server_tcpwritetimeouts counter
# HELP dnsdist_server_tcpcurrentconnections The number of current TCP connections
# TYPE dnsdist_server_tcpcurrentconnections gauge
# HELP dnsdist_server_tcpmaxconcurrentconnections The maximum number of concurrent TCP connections
# TYPE dnsdist_server_tcpmaxconcurrentconnections counter
# HELP dnsdist_server_tcptoomanyconcurrentconnections Number of times we had to enforce the maximum number of concurrent TCP connections
# TYPE dnsdist_server_tcptoomanyconcurrentconnections counter
# HELP dnsdist_server_tcpnewconnections The number of established TCP connections in total
# TYPE dnsdist_server_tcpnewconnections counter
# HELP dnsdist_server_tcpreusedconnections The number of times a TCP connection has been reused
# TYPE dnsdist_server_tcpreusedconnections counter
# HELP dnsdist_server_tcpavgqueriesperconn The average number of queries per TCP connection
# TYPE dnsdist_server_tcpavgqueriesperconn gauge
# HELP dnsdist_server_tcpavgconnduration The average duration of a TCP connection (ms)
# TYPE dnsdist_server_tcpavgconnduration gauge
# HELP dnsdist_server_tlsresumptions The number of times a TLS session has been resumed
# TYPE dnsdist_server_tlsresumptions counter
# HELP dnsdist_server_tcplatency Server's latency when answering TCP questions in milliseconds
# TYPE dnsdist_server_tcplatency gauge
dnsdist_server_status{server="9_9_9_9:443",address="9.9.9.9:443"} 1
dnsdist_server_queries{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_responses{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_noncompliantresponses{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_drops{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_latency{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_tcplatency{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_senderrors{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_outstanding{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_order{server="9_9_9_9:443",address="9.9.9.9:443"} 1
dnsdist_server_weight{server="9_9_9_9:443",address="9.9.9.9:443"} 1
dnsdist_server_tcpdiedsendingquery{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_tcpdiedreadingresponse{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_tcpgaveup{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_tcpreadtimeouts{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_tcpwritetimeouts{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_tcpconnecttimeouts{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_tcpcurrentconnections{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_tcpmaxconcurrentconnections{server="9_9_9_9:443",address="9.9.9.9:443"} 1
dnsdist_server_tcptoomanyconcurrentconnections{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_tcpnewconnections{server="9_9_9_9:443",address="9.9.9.9:443"} 19
dnsdist_server_tcpreusedconnections{server="9_9_9_9:443",address="9.9.9.9:443"} 0
dnsdist_server_tcpavgqueriesperconn{server="9_9_9_9:443",address="9.9.9.9:443"} 0.173831
dnsdist_server_tcpavgconnduration{server="9_9_9_9:443",address="9.9.9.9:443"} 3.92628
dnsdist_server_tlsresumptions{server="9_9_9_9:443",address="9.9.9.9:443"} 18
# HELP dnsdist_frontend_queries Amount of queries received by this frontend
# TYPE dnsdist_frontend_queries counter
# HELP dnsdist_frontend_noncompliantqueries Amount of non-compliant queries received by this frontend
# TYPE dnsdist_frontend_noncompliantqueries counter
# HELP dnsdist_frontend_responses Amount of responses sent by this frontend
# TYPE dnsdist_frontend_responses counter
# HELP dnsdist_frontend_tcpdiedreadingquery Amount of TCP connections terminated while reading the query from the client
# TYPE dnsdist_frontend_tcpdiedreadingquery counter
# HELP dnsdist_frontend_tcpdiedsendingresponse Amount of TCP connections terminated while sending a response to the client
# TYPE dnsdist_frontend_tcpdiedsendingresponse counter
# HELP dnsdist_frontend_tcpgaveup Amount of TCP connections terminated after too many attempts to get a connection to the backend
# TYPE dnsdist_frontend_tcpgaveup counter
# HELP dnsdist_frontend_tcpclienttimeouts Amount of TCP connections terminated by a timeout while reading from the client
# TYPE dnsdist_frontend_tcpclienttimeouts counter
# HELP dnsdist_frontend_tcpdownstreamtimeouts Amount of TCP connections terminated by a timeout while reading from the backend
# TYPE dnsdist_frontend_tcpdownstreamtimeouts counter
# HELP dnsdist_frontend_tcpcurrentconnections Amount of current incoming TCP connections from clients
# TYPE dnsdist_frontend_tcpcurrentconnections gauge
# HELP dnsdist_frontend_tcpmaxconcurrentconnections Maximum number of concurrent incoming TCP connections from clients
# TYPE dnsdist_frontend_tcpmaxconcurrentconnections counter
# HELP dnsdist_frontend_tcpavgqueriesperconnection The average number of queries per TCP connection
# TYPE dnsdist_frontend_tcpavgqueriesperconnection gauge
# HELP dnsdist_frontend_tcpavgconnectionduration The average duration of a TCP connection (ms)
# TYPE dnsdist_frontend_tcpavgconnectionduration gauge
# HELP dnsdist_frontend_tlsqueries Number of queries received by dnsdist over TLS, by TLS version
# TYPE dnsdist_frontend_tlsqueries counter
# HELP dnsdist_frontend_tlsnewsessions Amount of new TLS sessions negotiated
# TYPE dnsdist_frontend_tlsnewsessions counter
# HELP dnsdist_frontend_tlsresumptions Amount of TLS sessions resumed
# TYPE dnsdist_frontend_tlsresumptions counter
# HELP dnsdist_frontend_tlsunknownticketkeys Amount of attempts to resume TLS session from an unknown key (possibly expired)
# TYPE dnsdist_frontend_tlsunknownticketkeys counter
# HELP dnsdist_frontend_tlsinactiveticketkeys Amount of TLS sessions resumed from an inactive key
# TYPE dnsdist_frontend_tlsinactiveticketkeys counter
# HELP dnsdist_frontend_tlshandshakefailures Amount of TLS handshake failures
# TYPE dnsdist_frontend_tlshandshakefailures counter
dnsdist_frontend_queries{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_noncompliantqueries{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_responses{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tcpdiedreadingquery{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tcpdiedsendingresponse{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tcpgaveup{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tcpclienttimeouts{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tcpdownstreamtimeouts{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tcpcurrentconnections{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tcpmaxconcurrentconnections{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tcpavgqueriesperconnection{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tcpavgconnectionduration{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tlsnewsessions{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tlsresumptions{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tlsunknownticketkeys{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tlsinactiveticketkeys{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0"} 0
dnsdist_frontend_tlsqueries{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",tls="tls10"} 0
dnsdist_frontend_tlsqueries{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",tls="tls11"} 0
dnsdist_frontend_tlsqueries{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",tls="tls12"} 0
dnsdist_frontend_tlsqueries{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",tls="tls13"} 0
dnsdist_frontend_tlsqueries{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",tls="unknown"} 0
dnsdist_frontend_tlshandshakefailures{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",error="dhKeyTooSmall"} 0
dnsdist_frontend_tlshandshakefailures{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",error="inappropriateFallBack"} 0
dnsdist_frontend_tlshandshakefailures{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",error="noSharedCipher"} 0
dnsdist_frontend_tlshandshakefailures{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",error="unknownCipherType"} 0
dnsdist_frontend_tlshandshakefailures{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",error="unknownKeyExchangeType"} 0
dnsdist_frontend_tlshandshakefailures{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",error="unknownProtocol"} 0
dnsdist_frontend_tlshandshakefailures{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",error="unsupportedEC"} 0
dnsdist_frontend_tlshandshakefailures{frontend="127.0.0.1:853",proto="TCP (DNS over TLS)",thread="0",error="unsupportedProtocol"} 0
dnsdist_frontend_queries{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_noncompliantqueries{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_responses{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tcpdiedreadingquery{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tcpdiedsendingresponse{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tcpgaveup{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tcpclienttimeouts{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tcpdownstreamtimeouts{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tcpcurrentconnections{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tcpmaxconcurrentconnections{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tcpavgqueriesperconnection{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tcpavgconnectionduration{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tlsnewsessions{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tlsresumptions{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tlsunknownticketkeys{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tlsinactiveticketkeys{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0"} 0
dnsdist_frontend_tlsqueries{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",tls="tls10"} 0
dnsdist_frontend_tlsqueries{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",tls="tls11"} 0
dnsdist_frontend_tlsqueries{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",tls="tls12"} 0
dnsdist_frontend_tlsqueries{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",tls="tls13"} 0
dnsdist_frontend_tlsqueries{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",tls="unknown"} 0
dnsdist_frontend_tlshandshakefailures{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",error="dhKeyTooSmall"} 0
dnsdist_frontend_tlshandshakefailures{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",error="inappropriateFallBack"} 0
dnsdist_frontend_tlshandshakefailures{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",error="noSharedCipher"} 0
dnsdist_frontend_tlshandshakefailures{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",error="unknownCipherType"} 0
dnsdist_frontend_tlshandshakefailures{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",error="unknownKeyExchangeType"} 0
dnsdist_frontend_tlshandshakefailures{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",error="unknownProtocol"} 0
dnsdist_frontend_tlshandshakefailures{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",error="unsupportedEC"} 0
dnsdist_frontend_tlshandshakefailures{frontend="[::1]:443",proto="TCP (DNS over HTTPS)",thread="0",error="unsupportedProtocol"} 0
dnsdist_frontend_queries{frontend="127.0.0.1:53",proto="UDP",thread="0"} 0
dnsdist_frontend_noncompliantqueries{frontend="127.0.0.1:53",proto="UDP",thread="0"} 0
dnsdist_frontend_responses{frontend="127.0.0.1:53",proto="UDP",thread="0"} 0
dnsdist_frontend_queries{frontend="127.0.0.1:53",proto="TCP",thread="0"} 0
dnsdist_frontend_noncompliantqueries{frontend="127.0.0.1:53",proto="TCP",thread="0"} 0
dnsdist_frontend_responses{frontend="127.0.0.1:53",proto="TCP",thread="0"} 0
dnsdist_frontend_tcpdiedreadingquery{frontend="127.0.0.1:53",proto="TCP",thread="0"} 0
dnsdist_frontend_tcpdiedsendingresponse{frontend="127.0.0.1:53",proto="TCP",thread="0"} 0
dnsdist_frontend_tcpgaveup{frontend="127.0.0.1:53",proto="TCP",thread="0"} 0
dnsdist_frontend_tcpclienttimeouts{frontend="127.0.0.1:53",proto="TCP",thread="0"} 0
dnsdist_frontend_tcpdownstreamtimeouts{frontend="127.0.0.1:53",proto="TCP",thread="0"} 0
dnsdist_frontend_tcpcurrentconnections{frontend="127.0.0.1:53",proto="TCP",thread="0"} 0
dnsdist_frontend_tcpmaxconcurrentconnections{frontend="127.0.0.1:53",proto="TCP",thread="0"} 0
dnsdist_frontend_tcpavgqueriesperconnection{frontend="127.0.0.1:53",proto="TCP",thread="0"} 0
dnsdist_frontend_tcpavgconnectionduration{frontend="127.0.0.1:53",proto="TCP",thread="0"} 0
# HELP dnsdist_frontend_http_connects Number of DoH TCP connections established to this frontend
# TYPE dnsdist_frontend_http_connects counter
# HELP dnsdist_frontend_doh_http_method_queries Number of DoH queries received by dnsdist, by HTTP method
# TYPE dnsdist_frontend_doh_http_method_queries counter
# HELP dnsdist_frontend_doh_http_version_queries Number of DoH queries received by dnsdist, by HTTP version
# TYPE dnsdist_frontend_doh_http_version_queries counter
# HELP dnsdist_frontend_doh_bad_requests Number of requests that could not be converted to a DNS query
# TYPE dnsdist_frontend_doh_bad_requests counter
# HELP dnsdist_frontend_doh_responses Number of responses sent, by type
# TYPE dnsdist_frontend_doh_responses counter
# HELP dnsdist_frontend_doh_version_status_responses Number of requests that could not be converted to a DNS query
# TYPE dnsdist_frontend_doh_version_status_responses counter
dnsdist_frontend_http_connects{frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_http_method_queries{method="get",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_http_method_queries{method="post",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_http_version_queries{version="1",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_http_version_queries{version="2",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_bad_requests{frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_responses{type="error",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_responses{type="redirect",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_responses{type="valid",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_version_status_responses{httpversion="1",status="200",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_version_status_responses{httpversion="1",status="400",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_version_status_responses{httpversion="1",status="403",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_version_status_responses{httpversion="1",status="500",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_version_status_responses{httpversion="1",status="502",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_version_status_responses{httpversion="1",status="other",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_version_status_responses{httpversion="2",status="200",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_version_status_responses{httpversion="2",status="400",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_version_status_responses{httpversion="2",status="403",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_version_status_responses{httpversion="2",status="500",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_version_status_responses{httpversion="2",status="502",frontend="[::1]:443",thread="0"} 0
dnsdist_frontend_doh_version_status_responses{httpversion="2",status="other",frontend="[::1]:443",thread="0"} 0
# HELP dnsdist_pool_servers Number of servers in that pool
# TYPE dnsdist_pool_servers gauge
# HELP dnsdist_pool_active_servers Number of available servers in that pool
# TYPE dnsdist_pool_active_servers gauge
# HELP dnsdist_pool_cache_size Maximum number of entries that this cache can hold
# TYPE dnsdist_pool_cache_size gauge
# HELP dnsdist_pool_cache_entries Number of entries currently present in that cache
# TYPE dnsdist_pool_cache_entries gauge
# HELP dnsdist_pool_cache_hits Number of hits from that cache
# TYPE dnsdist_pool_cache_hits counter
# HELP dnsdist_pool_cache_misses Number of misses from that cache
# TYPE dnsdist_pool_cache_misses counter
# HELP dnsdist_pool_cache_deferred_inserts Number of insertions into that cache skipped because it was already locked
# TYPE dnsdist_pool_cache_deferred_inserts counter
# HELP dnsdist_pool_cache_deferred_lookups Number of lookups into that cache skipped because it was already locked
# TYPE dnsdist_pool_cache_deferred_lookups counter
# HELP dnsdist_pool_cache_lookup_collisions Number of lookups into that cache that triggered a collision (same hash but different entry)
# TYPE dnsdist_pool_cache_lookup_collisions counter
# HELP dnsdist_pool_cache_insert_collisions Number of insertions into that cache that triggered a collision (same hash but different entry)
# TYPE dnsdist_pool_cache_insert_collisions counter
# HELP dnsdist_pool_cache_ttl_too_shorts Number of insertions into that cache skipped because the TTL of the answer was not long enough
# TYPE dnsdist_pool_cache_ttl_too_shorts counter
# HELP dnsdist_pool_cache_cleanup_count_total Number of times the cache has been scanned to remove expired entries, if any
# TYPE dnsdist_pool_cache_cleanup_count_total counter
dnsdist_pool_servers{pool="_default_"} 1
dnsdist_pool_active_servers{pool="_default_"} 1
dnsdist_pool_cache_size{pool="_default_"} 100
dnsdist_pool_cache_entries{pool="_default_"} 0
dnsdist_pool_cache_hits{pool="_default_"} 0
dnsdist_pool_cache_misses{pool="_default_"} 0
dnsdist_pool_cache_deferred_inserts{pool="_default_"} 0
dnsdist_pool_cache_deferred_lookups{pool="_default_"} 0
dnsdist_pool_cache_lookup_collisions{pool="_default_"} 0
dnsdist_pool_cache_insert_collisions{pool="_default_"} 0
dnsdist_pool_cache_ttl_too_shorts{pool="_default_"} 0
dnsdist_pool_cache_cleanup_count_total{pool="_default_"} 0
# HELP dnsdist_rule_hits Number of hits of that rule
# TYPE dnsdist_rule_hits counter
# HELP dnsdist_dynblocks_nmg_top_offenders_hits_per_second Number of hits per second blocked by Dynamic Blocks (netmasks) for the top offenders, averaged over the last 60s
# TYPE dnsdist_dynblocks_nmg_top_offenders_hits_per_second gauge
# HELP dnsdist_dynblocks_smt_top_offenders_hits_per_second Number of this per second blocked by Dynamic Blocks (suffixes) for the top offenders, averaged over the last 60s
# TYPE dnsdist_dynblocks_smt_top_offenders_hits_per_second gauge
# HELP dnsdist_info Info from dnsdist, value is always 1
# TYPE dnsdist_info gauge
dnsdist_info{version="1.7.3"} 1

Example prometheus configuration:

This is just the scrape job description, for details see the prometheus documentation.

job_name: dnsdist
scrape_interval: 10s
scrape_timeout: 2s
metrics_path: /metrics
basic_auth:
  username: dontcare
  password: yoursecret
DELETE /api/v1/cache
Query Parameters:

  • pool (string) – Name of the pool

  • name (string) – DNS name to wipe

  • type (string) – DNS type, optional. Defaults to all types when unset

  • suffix (string) – Set to any value to wipe treat name as a suffix

Allows removing entries from a cache. The pool to which the cache is associated should be specified in the pool parameter, and the name to remove in the name parameter. By default only entries matching the exact name will be removed, but it is possible to remove all entries below that name by passing the suffix parameter set to any value. By default entries for all types for the name are removed, but it is possible to only remove entries for a specific type by passing the type parameter set to the requested type. Supported values are DNS type names as a strings (AAAA), or numerical values (as either #64 or TYPE64).

Example request:

DELETE /api/v1/cache?pool=&name=free.fr HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: localhost:8080
X-API-Key: supersecretAPIkey

Example response:

HTTP/1.1 200 OK
Connection: close
Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'
Content-Type: application/json
Transfer-Encoding: chunked
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Permitted-Cross-Domain-Policies: none
X-Xss-Protection: 1; mode=block

{
    "count": "1",
    "status": "purged"
}
GET /api/v1/servers/localhost

Get a quick overview of several parameters.

Response JSON Object:

  • acl (string) – A string of comma-separated netmasks currently allowed by the ACL.

  • cache-hit-response-rules (list) – A list of ResponseRule objects applied on cache hits

  • self-answered-response-rules (list) – A list of ResponseRule objects applied on self-answered queries

  • daemon_type (string) – The type of daemon, always “dnsdist”

  • frontends (list) – A list of Frontend objects

  • pools (list) – A list of Pool objects

  • response-rules (list) – A list of ResponseRule objects

  • rules (list) – A list of Rule objects

  • servers (list) – A list of Server objects

  • version (string) – The running version of dnsdist

GET /api/v1/servers/localhost/statistics

Returns a list of all statistics as StatisticsItem.

GET /api/v1/servers/localhost/config

Returns a list of ConfigSetting objects.

GET /api/v1/servers/localhost/config/allow-from

Gets you the allow-from ConfigSetting, who’s value is a list of strings of all the netmasks in the ACL.

Example request:

GET /api/v1/servers/localhost/config/allow-from HTTP/1.1
X-API-Key: supersecretAPIkey

Example response:

HTTP/1.1 200 OK
Connection: close
Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'
Content-Type: application/json
Transfer-Encoding: chunked
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Permitted-Cross-Domain-Policies: none
X-Xss-Protection: 1; mode=block

{
    "name": "allow-from",
    "type": "ConfigSetting",
    "value": [
        "fc00::/7",
        "169.254.0.0/16",
        "100.64.0.0/10",
        "fe80::/10",
        "10.0.0.0/8",
        "127.0.0.0/8",
        "::1/128",
        "172.16.0.0/12",
        "192.168.0.0/16"
    ]
}
PUT /api/v1/servers/localhost/config/allow-from

Allows you to update the allow-from ACL with a list of netmasks.

Make sure you made the API writable using setAPIWritable(). Changes to the ACL are directly applied, no restart is required. However, restarting the dnsdist server will restore the ALC to the one configured in the configuration file.

Request JSON Object:

  • value ([string]) – A list of IP subnets to add to the ACL.

Example request:

PUT /api/v1/servers/localhost/config/allow-from HTTP/1.1
Content-Length: 37
Content-Type: application/json
X-API-Key: supersecretAPIkey

{
    "value": [
        "127.0.0.0/8",
        "::1/128"
    ]
}

Example response:

HTTP/1.1 200 OK
Connection: close
Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'
Content-Type: application/json
Transfer-Encoding: chunked
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Permitted-Cross-Domain-Policies: none
X-Xss-Protection: 1; mode=block

{
    "name": "allow-from",
    "type": "ConfigSetting",
    "value": [
        "127.0.0.0/8",
        "::1/128"
    ]
}
GET /api/v1/servers/localhost/pool

Get a quick overview of the pool named “pool-name”.

Query Parameters:

  • pool-name (string) – Name of the pool, required

Response JSON Object:

  • list – A list of metrics related to that pool

  • servers (list) – A list of Server objects present in that pool

GET /api/v1/servers/localhost/rings

Added in version 1.9.0.

Get the most recent queries and responses from the in-memory ring buffers. Returns up to maxQueries query entries if set, up to maxResponses responses if set, and the whole content of the ring buffers otherwise.

Query Parameters:

  • maxQueries (integer) – Return up to this many queries. When unset, return all

  • maxResponses (integer) – Return up to this many responses. When unset, return all

Response JSON Object:

  • queries (list) – The list of the most recent queries, as RingEntry objects

  • responses (list) – The list of the most recent responses, as RingEntry objects

JSON Objects

json ConfigSetting : object

An object representing a global configuration element.

The following configuration are returned:

Optional members:
name : string

The name of the setting

type : string

ConfigSetting

value : string

The value for this setting

json Frontend : object

A description of a bind dnsdist is listening on.

Optional members:
address : string

IP and port that is listened on

id : integer

Internal identifier

nonCompliantQueries : integer

Amount of non-compliant queries received by this frontend

queries : integer

The number of received queries on this bind

responses : integer

Amount of responses sent by this frontend

tcp : boolean

true if this is a TCP bind

tcpAvgConnectionDuration : integer

The average duration of a TCP connection (ms)

tcpAvgQueriesPerConnection : integer

The average number of queries per TCP connection

tcpClientTimeouts : integer

Amount of TCP connections terminated by a timeout while reading from the client

tcpCurrentConnections : integer

Amount of current incoming TCP connections from clients

tcpDiedReadingQuery : integer

Amount of TCP connections terminated while reading the query from the client

tcpDiedSendingResponse : integer

Amount of TCP connections terminated while sending a response to the client

tcpDownstreamTimeouts : integer

Amount of TCP connections terminated by a timeout while reading from the backend

tcpGaveUp : integer

Amount of TCP connections terminated after too many attempts to get a connection to the backend

tcpMaxConcurrentConnections : integer

Maximum number of concurrent incoming TCP connections from clients

tls10Queries : integer

Number of queries received by dnsdist over TLS 1.0

tls11Queries : integer

Number of queries received by dnsdist over TLS 1.1

tls12Queries : integer

Number of queries received by dnsdist over TLS 1.2

tls13Queries : integer

Number of queries received by dnsdist over TLS 1.3

tlsHandshakeFailuresDHKeyTooSmall : integer

Amount of TLS connections where the client has negotiated a not strong enough diffie-hellman key during the TLS handshake

tlsHandshakeFailuresInappropriateFallBack : integer

Amount of TLS connections where the client tried to negotiate an invalid, too old, TLS version

tlsHandshakeFailuresNoSharedCipher : integer

Amount of TLS connections were no cipher shared by both the client and the server could been found during the TLS handshake

tlsHandshakeFailuresUnknownCipher : integer

Amount of TLS connections where the client has tried to negotiate an unknown TLS cipher

tlsHandshakeFailuresUnknownKeyExchangeType : integer

Amount of TLS connections where the client has tried to negotiate an unknown TLS key-exchange mechanism

tlsHandshakeFailuresUnknownProtocol : integer

Amount of TLS connections where the client has tried to negotiate an unknown TLS version

tlsHandshakeFailuresUnsupportedEC : integer

Amount of TLS connections where the client has tried to negotiate an unsupported elliptic curve

tlsHandshakeFailuresUnsupportedProtocol : integer

Amount of TLS connections where the client has tried to negotiate an unsupported TLS version

tlsInactiveTicketKey : integer

Amount of TLS sessions resumed from an inactive key

tlsNewSessions : integer

Amount of new TLS sessions negotiated

tlsResumptions : integer

Amount of TLS sessions resumed

tlsUnknownQueries : integer

Number of queries received by dnsdist over an unknown TLS version

tlsUnknownTicketKey : integer

Amount of attempts to resume TLS session from an unknown key (possibly expired)

type : string

UDP, TCP, DoT or DoH

udp : boolean

true if this is a UDP bind

json DohFrontend : object

A description of a DoH bind dnsdist is listening on.

Optional members:
bad-requests : integer

Number of requests that could not be converted to a DNS query

error-responses : integer

Number of HTTP responses sent with a non-200 code

get-queries : integer

Number of DoH queries received via the GET HTTP method

http-connects : integer

Number of DoH TCP connections established to this frontend

http1-queries : integer

Number of DoH queries received over HTTP/1 (or connection attempts with a HTTP/1.1 ALPN when the nghttp2 provider is used)

http1-x00-responses : integer

Number of DoH responses sent, over HTTP/1, per response code (200, 400, 403, 500, 502)

http1-other-responses : integer

Number of DoH responses sent, over HTTP/1, with another response code

http2-queries : integer

Number of DoH queries received over HTTP/2

http2-x00-responses : integer

Number of DoH responses sent, over HTTP/2, per response code (200, 400, 403, 500, 502)

post-queries : integer

Number of DoH queries received via the POST HTTP method

redirect-responses : integer

Number of HTTP redirect responses sent

valid-responses : integer

Number of valid DoH (2xx) responses sent

json StatisticsItem : object

This represents a statistics element.

Optional members:
name : string

The name of this statistic. See Statistics

type : "StatisticItem"
value : integer

The value for this item

json RingEntry : object

This represents an entry in the in-memory ring buffers.

Optional members:
age

How long ago was the query or response received, in seconds

id : integer

The DNS ID

name : string

The requested domain name

requestor : string

The client IP and port

size : integer

The size of the query or response

qtype : integer

The requested DNS type

protocol : string

The DNS protocol the query or response was received over

rd : boolean

The RD flag

mac : string

The MAC address of the device sending the query

latency

The time it took for the response to be sent back to the client, in microseconds

rcode

The response code

tc : boolean

The TC flag

aa : boolean

The AA flag

answers : integer

The number of records in the answer section of the response

backend : string

The IP and port of the backend that returned the response, or “Cache” if it was a cache-hit

json Pool : object

A description of a pool of backend servers.

Optional members:
id : integer

Internal identifier

cacheCleanupCount : integer

Number of times that cache was scanned for expired entries, or just to remove entries because it is full

cacheDeferredInserts : integer

The number of times an entry could not be inserted in the associated cache, if any, because of a lock

cacheDeferredLookups : integer

The number of times an entry could not be looked up from the associated cache, if any, because of a lock

cacheEntries : integer

The current number of entries in the associated cache, if any

cacheHits : integer

The number of cache hits for the associated cache, if any

cacheInsertCollisions : integer

The number of times an entry could not be inserted into the cache because a different entry with the same hash already existed

cacheLookupCollisions : integer

The number of times an entry retrieved from the cache based on the query hash did not match the actual query

cacheMisses : integer

The number of cache misses for the associated cache, if any

cacheSize : integer

The maximum number of entries in the associated cache, if any

cacheTTLTooShorts : integer

The number of times an entry could not be inserted into the cache because its TTL was set below the minimum threshold

name : string

Name of the pool

serversCount : integer

Number of backends in this pool

json Server : object

This object represents a backend server.

Optional members:
address : string

The remote IP and port

id : integer

Internal identifier

latency : integer

The current latency of this backend server for UDP queries, in milliseconds

name : string

The name of this server

nonCompliantResponses : integer

Amount of non-compliant responses

order : integer

Order number

outstanding : integer

Number of currently outstanding queries

pools : array of string

The pools this server belongs to

protocol : string

The protocol used by this server (Do53, DoT, DoH)

qps : integer

The current number of queries per second to this server

qpsLimit : integer

The configured maximum number of queries per second

queries : integer

Total number of queries sent to this backend

responses : integer

Amount of responses received from this server

reuseds : integer

Number of queries for which a response was not received in time

sendErrors : integer

Number of network errors while sending a query to this server

state : string

The state of the server (e.g. “DOWN” or “up”)

tcpAvgConnectionDuration : integer

The average duration of a TCP connection (ms)

tcpAvgQueriesPerConnection : integer

The average number of queries per TCP connection

tcpConnectTimeouts : integer

The number of TCP connect timeouts

tcpCurrentConnections : integer

The number of current TCP connections

tcpDiedReadingResponse : integer

The number of TCP I/O errors while reading the response

tcpDiedSendingQuery : integer

The number of TCP I/O errors while sending the query

tcpGaveUp : integer

The number of TCP connections failing after too many attempts

tcpLatency : integer

Server’s latency when answering TCP questions in milliseconds

tcpMaxConcurrentConnections : integer

The maximum number of concurrent TCP connections

tcpNewConnections : integer

The number of established TCP connections in total

tcpReadTimeouts : integer

The number of TCP read timeouts

tcpReusedConnections : integer

The number of times a TCP connection has been reused

tcpTooManyConcurrentConnections : integer

Number of times we had to enforce the maximum number of concurrent TCP connections

tcpWriteTimeouts : integer

The number of TCP write timeouts

tlsResumptions : integer

The number of times a TLS session has been resumed

weight : integer

The weight assigned to this server

dropRate

The amount of packets dropped (timing out) per second by this server

healthCheckFailures : integer

Number of health check attempts that failed (total)

healthCheckFailureParsing : integer

Number of health check attempts that failed because the payload could not be parsed

healthCheckFailureTimeout : integer

Number of health check attempts that failed because the response was not received in time

healthCheckFailureNetwork : integer

Number of health check attempts that failed because of a network error

healthCheckFailureMismatch : integer

Number of health check attempts that failed because the ID, qname, qtype or qclass did not match

healthCheckFailureInvalid : integer

Number of health check attempts that failed because the DNS response was not valid

json Rule : object

This represents a policy that is applied to queries

Optional members:
action : string

The action taken when the rule matches (e.g. “to pool abuse”)

action-stats

A list of statistics whose content varies depending on the kind of rule

creationOrder : integer

The order in which a rule has been created, mostly used for automated tools

id : integer

The position of this rule

matches : integer

How many times this rule was hit

name : string

The name assigned to this rule by the administrator, if any

rule : string

The matchers for the packet (e.g. “qname==bad-domain1.example., bad-domain2.example.”)

uuid : string

The UUID of this rule

json ResponseRule : object

This represents a policy that is applied to responses

Optional members:
action : string

The action taken when the rule matches (e.g. “drop”)

id : integer

The identifier (or order) of this rule

matches : integer

How many times this rule was hit

rule : string

The matchers for the packet (e.g. “qname==bad-domain1.example., bad-domain2.example.”)