]>
Commit | Line | Data |
---|---|---|
223bb49e PL |
1 | Built-in Webserver and HTTP API |
2 | =============================== | |
3 | ||
4 | The PowerDNS Recursor 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 | The following documents contain the information for the PowerDNS API: | |
8 | ||
9 | .. toctree:: | |
10 | :maxdepth: 1 | |
11 | ||
12 | ../common/api/dataformat | |
13 | ../common/api/server | |
6d500cf4 | 14 | zone |
223bb49e PL |
15 | ../common/api/configsetting |
16 | ../common/api/statisticitem | |
17 | ||
18 | ||
19 | Webserver | |
20 | --------- | |
21 | ||
22 | To launch the internal webserver, add a :ref:`setting-webserver` to the configuration file. | |
23 | This will instruct PowerDNS to start a webserver on localhost at port 8081, without password protection. | |
a5607c95 | 24 | 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. |
be3e1477 | 25 | 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. |
223bb49e PL |
26 | The webserver does not allow remote management. |
27 | The following webserver related configuration items are available: | |
28 | ||
29 | * :ref:`setting-webserver`: If set to anything but 'no', a webserver is launched. | |
30 | * :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. | |
a7d3cdad | 31 | * :ref:`setting-webserver-password`: If set, viewers will have to enter this password in order to gain access to the statistics. |
223bb49e PL |
32 | * :ref:`setting-webserver-port`: Port to bind the webserver to. |
33 | * :ref:`setting-webserver-allow-from`: Netmasks that are allowed to connect to the webserver | |
34 | ||
35 | Enabling the API | |
36 | ---------------- | |
37 | ||
d7500fe0 | 38 | To enable the API, the webserver and the HTTP API need to be enabled. |
223bb49e PL |
39 | Add these lines to the ``recursor.conf``:: |
40 | ||
41 | webserver=yes | |
42 | webserver-port=8082 | |
43 | api-key=changeme | |
44 | ||
45 | And restart ``pdns_recursor``, the following examples should start working:: | |
46 | ||
47 | curl -v -H 'X-API-Key: changeme' http://127.0.0.1:8082/api/v1/servers/localhost | jq . | |
48 | curl -v -H 'X-API-Key: changeme' http://127.0.0.1:8082/api/v1/servers/localhost/zones | jq . | |
49 | ||
c0a2615c OM |
50 | A few examples for zone manipulation follow, first one is to create a forwarding zone:: |
51 | ||
52 | curl --no-progress-meter -H 'X-API-Key: changeme' -H 'Content-type: application/json' -X POST --data-binary @- http://localhost:8082/api/v1/servers/localhost/zones << EOF | jq | |
53 | { | |
54 | "name": "example.com.", | |
55 | "type": "Zone", | |
56 | "kind": "Forwarded", | |
57 | "servers": ["192.168.178.1", "192.168.178.2:5353"], | |
58 | "recursion_desired" : false | |
59 | } | |
60 | EOF | |
61 | ||
62 | Example output of the above command:: | |
63 | ||
64 | { | |
65 | "id": "example.com.", | |
66 | "kind": "Forwarded", | |
67 | "name": "example.com.", | |
68 | "records": [], | |
69 | "recursion_desired": false, | |
70 | "servers": [ | |
71 | "192.168.178.1:53", | |
72 | "192.168.178.2:5353" | |
73 | ], | |
74 | "url": "/api/v1/servers/localhost/zones/example.com." | |
75 | } | |
76 | ||
77 | To delete the forwarding zone added above:: | |
78 | ||
79 | curl --no-progress-meter -H 'X-API-Key: changeme' -X DELETE http://localhost:8082/api/v1/servers/localhost/zones/example.com. | |
80 | ||
223bb49e PL |
81 | URL Endpoints |
82 | ------------- | |
83 | ||
84 | All API endpoints for the PowerDNS Recursor are documented here: | |
85 | ||
86 | .. toctree:: | |
87 | :maxdepth: 1 | |
88 | ||
8b4030fb | 89 | prometheus |
223bb49e PL |
90 | ../common/api/endpoint-api |
91 | ../common/api/endpoint-servers | |
0e2063c3 | 92 | endpoint-servers-config |
223bb49e PL |
93 | ../common/api/endpoint-statistics.rst |
94 | endpoint-zones | |
95 | endpoint-trace | |
96 | endpoint-cache | |
223bb49e | 97 | endpoint-failure |
4fe8a79f | 98 | endpoint-rpz-stats |
18e5a5ba | 99 | endpoint-jsonstat |