Scope of the v6 API includes DNS / CNAME CRUD?

General Beta 6.0
1

Hey,

(Sorry I'm not really sure where to look for this info)

Will v6 have a "full" API, meaning that it will be possible to perform all tasks, including creating e.g. DNS records and CNAME records through it eventually? I would see a great use case for that for adding those records through automation (e.g. Ansible)

2

I did find the current API docs for v6 beta, btw, and that does not show DNS record management as an option, so question still stands :slight_smile:

3

It should be in /config with dns.hosts

4

Ah great, though that looks like a difficult to use API endpoint. This way, DNS record management (and DHCP lease management) is almost hidden away in a corner of the general settings API endpoint.

I had hoped it would be more like

/dns/A/${host}/${ip} and /dns/CNAME/${alias}/${host} or something like that, that would be a lot easier to do CRUD on, and DNS records would be a first class object that way

5

You're close:

$ curl -s --request PUT localhost/api/config/dns/hosts/10.10.10.10%20test | jq
{
  "took": 0.00929856300354004
}

$ curl -s localhost/api/config/dns/hosts | jq
{
  "config": {
    "dns": {
      "hosts": [
        "10.10.10.10 test"
      ]
    }
  },
  "took": 6.41345977783203e-05
}

$ dig +short @localhost test
10.10.10.10

$ curl -s --request PUT localhost/api/config/dns/cnameRecords/alias,pi.hole,330 | jq
{
  "took": 0.04300665855407715
}

$ curl -s localhost/api/config/dns/cnameRecords | jq
{
  "config": {
    "dns": {
      "cnameRecords": [
        "alias,pi.hole,0330"
      ]
    }
  },
  "took": 5.4836273193359375e-05
}

$ dig +short @localhost alias cname
pi.hole.

If want to see whats all in config:

curl -s localhost/api/config | jq

Or HTTPS:

curl -s https://localhost/api/config | jq

Or HTTPS with a self signed cert:

curl -ks https://localhost/api/config | jq

6

Oh that's actually much better than I thought :slight_smile:

Any idea on whether you can GET a single record (/api/config/dns/hosts/test or /api/config/dns/hosts/10.10.10.10)? How do you DELETE a record? Send a DELETE to /api/config/dns/hosts/test or send the whole JSON structure with all records, minus the one I want to delete, to /api/config/dns/hosts?

8

You said you already found the API documentation. It is abstract but it is this only to be generic and complete. Whenever you click on the individual endpoints, you will see examples.

In general, the API really follows the REST principle so, when you create an item using

yous should be able to undo this with
DELETE localhost/api/config/dns/hosts/10.10.10.10%20test

As the HTTP standard does not allow DELETE to have any payload, you can see the result based on the returned HTTP status code. All possible codes are described in the API documentation:

image
image1225×503 37.6 KB

This is not available. The reason is that you'd have to know the exact entry (in the example we're using here that'd be "10.10.10.10%20test") and - in case you know that - the entire GET request is pointless. Usually, all config endpoints are manipulated only through PATCH (like editing the file), Pi-hole adds the PUT and DELETE options for you pure convenience to those config options which are of type "array of strings" to ease handling from external scripts (no JSON parsing required).

1 Like
9

You can query with the JSON parser instead.
From below examples:

https://www.baeldung.com/linux/jq-command-json

$ curl -s localhost/api/config/dns/hosts | jq -r '.config.dns.hosts[] | select(.|test("router"))'
10.0.0.1 router.home.dehakkelaar.nl

$ curl -s localhost/api/config/dns/hosts | jq -r '.config.dns.hosts[] | select(.|test("10.0.0.3"))'
10.0.0.3 nas.home.dehakkelaar.nl

EDIT: Oh it might not be clear but I entered a blank Pi-hole password for easy tinkering:

sudo pihole setpassword

10

That looks very interesting :wink:

Thanks for all the information!

1 Like