Built-in webserver

To visually interact with dnsdist, try add webserver() to the configuration:

webserver("127.0.0.1:8083", "supersecretpassword", "supersecretAPIkey")

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

Security of the Webserver

The built-in webserver serves its content from inside the binary, this means it will not and connot 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 by using the last parameter to webserver(). For example, to remove the X-Frame-Options header and add a X-Custom one:

webserver("127.0.0.1:8080", "supersecret", "apikey", {["X-Frame-Options"]= "", ["X-Custom"]="custom"}

dnsdist API

To access the API, the apikey must be set in the webserver() 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 methos is not allowed.

URL Endpoints

GET /jsonstat

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
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, "block-filter": 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
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}}
Query Parameters:
 
  • command – one of stats, dynblocklist or ebpfblocklist
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 StatisticItem.

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.

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

Allows you to add to the ACL. TODO how

JSON Objects

ConfigSetting

An object representing a global configuration element. The following configuration are returned:

Object Properties:
 
  • name (string) – The name of the setting
  • type (string) – “ConfigSetting”
  • value (string) – The value for this setting
Frontend

A description of a bind dnsdist is listening on.

Object Properties:
 
  • address (string) – IP and port that is listened on
  • id (integer) – Internal identifier
  • queries (integer) – The number of received queries on this bind
  • udp (boolean) – true if this is a UDP bind
  • tcp (boolean) – true if this is a TCP bind
Pool

A description of a pool of backend servers.

Object Properties:
 
  • id (integer) – Internal identifier
  • 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
  • cacheLookupCollisions (integer) – The number of times an entry retrieved from the cache based on the query hash did not match the actual query
  • 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
  • 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
Rule

This represents a policy that is applied to queries

Object Properties:
 
  • action (string) – The action taken when the rule matches (e.g. “to pool abuse”)
  • action-stats (dict) – A list of statistics whose content varies depending on the kind of rule
  • id (integer) – The position 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.”)
  • uuid (string) – The UUID of this rule
ResponseRule

This represents a policy that is applied to responses

Object Properties:
 
  • 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.”)
Server

This object represents a backend server.

Object Properties:
 
  • address (string) – The remote IP and port
  • id (integer) – Internal identifier
  • latency (integer) – The current latency of this backend server
  • name (string) – The name of this server
  • order (integer) – Order number
  • outstanding (integer) – Number of currently outstanding queries
  • pools ([string]) – The pools this server belongs to
  • 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
  • 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”)
  • weight (integer) – The weight assigned to this server
StatisticItem

This represents a statistics element.

Object Properties:
 
  • name (string) – The name of this statistic. See Statistics
  • type (string) – “StatisticItem”
  • value (integer) – The value for this item