docs/http-api/index.rst

   1 Built-in Webserver and HTTP API
   2 ===============================
   3
   4 The PowerDNS Authoritative Server features a built-in built-in webserver that exposes a JSON/REST API.
   5 This API allows for controlling several functions and reading statistics.
   6
   7 Webserver
   8 ---------
   9
  10 To launch the internal webserver, add a :ref:`setting-webserver` to the configuration file.
  11 This will instruct PowerDNS to start a webserver on localhost at port 8081, without password protection.
  12 By default the webserver listens on localhost, meaning only local users (on the same host) will be able to access the webserver. Since the default ACL before 4.1.0 allows access from everywhere if :ref:`setting-webserver-address` is set to a different value, we strongly advise the use of a password protection.
  13 The webserver lists a lot of potentially sensitive information about the PowerDNS process, including frequent queries, frequently failing queries, lists of remote hosts sending queries, hosts sending corrupt queries etc.
  14 The webserver does not allow remote management of the daemon, but allows control over the size of the queries and response rings that may be used to monitor activities.
  15 The following webserver related configuration items are available:
  16
  17 * :ref:`setting-webserver`: If set to anything but 'no', a webserver is launched.
  18 * :ref:`setting-webserver-address`: Address to bind the webserver to. Defaults to 127.0.0.1, which implies that only the local computer is able to connect to the nameserver! To allow remote hosts to connect, change to 0.0.0.0 or the physical IP address of your nameserver.
  19 * :ref:`setting-webserver-password`: If set, viewers will have to enter this plaintext password in order to gain access to the statistics.
  20 * :ref:`setting-webserver-port`: Port to bind the webserver to.
  21 * :ref:`setting-webserver-allow-from`: Netmasks that are allowed to connect to the webserver
  22
  23 Enabling the API
  24 ----------------
  25
  26 To enable the API, the webserver and the HTTP API need to be enabled.
  27 Add these lines to the ``pdns.conf``::
  28
  29     api=yes
  30     api-key=changeme
  31     webserver=yes
  32     webserver-port=8081
  33
  34 The API endpoints run off of the same webserver, but the :ref:`setting-api` is required to enable API access. Setting :ref:`setting-api` also implicitly enables the webserver v4.1.x onwards.
  35
  36 And restart, the following examples should start working::
  37
  38     curl -v -H 'X-API-Key: changeme' http://127.0.0.1:8081/api/v1/servers/localhost | jq .
  39     curl -v -H 'X-API-Key: changeme' http://127.0.0.1:8081/api/v1/servers/localhost/zones | jq .
  40
  41 JSON Objects
  42 ------------
  43
  44 The following documents describe the JSON objects available in the API:
  45
  46 .. toctree::
  47     :maxdepth: 1
  48
  49     ../common/api/dataformat
  50     ../common/api/server
  51     zone
  52     ../common/api/configsetting
  53     ../common/api/statisticitem
  54     cryptokeyitem
  55     zonemetadata
  56
  57 URL Endpoints
  58 -------------
  59
  60 All API endpoints for the PowerDNS Recursor are documented here:
  61
  62 .. toctree::
  63   :maxdepth: 1
  64
  65   ../common/api/endpoint-api
  66   ../common/api/endpoint-servers
  67   ../common/api/endpoint-servers-config
  68   ../common/api/endpoint-statistics
  69   ../common/api/endpoint-logging
  70   endpoint-search
  71   endpoint-zones
  72   endpoint-zone-metadata
  73   endpoint-cryptokeys