Le API di PowerDNS

PowerDNS offre un set di API HTTP/REST per controllare e integrare in modo programmatico sia il PowerDNS Authoritative Server sia il PowerDNS Recursor. Le API espongono funzionalità per la gestione delle zone, dei record, delle chiavi DNSSEC, delle statistiche, della cache e molto altro, utilizzando payload in formato JSON.

1. Architettura generale delle API di PowerDNS

Le API HTTP sono fornite da un web server integrato nei processi di PowerDNS e sono disponibili, a seconda del prodotto, su uno specifico host/porta e percorso:

  • Authoritative Server: tipicamente su http://127.0.0.1:8081/api/v1.
  • Recursor: tipicamente su http://127.0.0.1:8082/api/v1.

Entrambi espongono una gerarchia di endpoint che segue una struttura simile: 

GET /api
GET /api/v1
GET /api/v1/servers
GET /api/v1/servers/{server_id}/...

Nel caso del PowerDNS Authoritative, il valore di server_id è di solito localhost. Il Recursor invece usa in genere un identificatore come localhost o il nome configurato per l'istanza.

2. Abilitare le API nel PowerDNS Authoritative Server

Per usare le API, è necessario abilitare il web server interno nel file di configurazione pdns.conf. Un esempio minimale: 

api=yes
api-key=SuperSegretaChiaveAPI
webserver=yes
webserver-address=127.0.0.1
webserver-port=8081

Dopo aver modificato la configurazione, riavvia il servizio PowerDNS Authoritative. Una volta attivo, puoi verificare la raggiungibilità dell'API con: 

curl -H "X-API-Key: SuperSegretaChiaveAPI"   http://127.0.0.1:8081/api/v1/servers

2.1 Autenticazione

L'autenticazione avviene tramite l'intestazione HTTP X-API-Key: 

curl -H "X-API-Key: <CHIAVE_API>" http://host:porta/api/v1/...

La chiave API è statica e configurata in pdns.conf. Non sono richieste credenziali utente/password, ma è responsabilità dell'amministratore proteggere l'accesso alla porta dell'API (tipicamente limitandola a localhost o a una rete di management dedicata e possibilmente tunnelata via VPN o SSH).

3. Endpoint principali dell'Authoritative Server

Gli endpoint fondamentali per la gestione DNS sono quelli relativi a:

  • Server: informazioni generali e statistiche.
  • Zone: creazione, aggiornamento, cancellazione delle zone.
  • RRset: gestione dei record all'interno delle zone.
  • DNSSEC: gestione delle chiavi e dei parametri di firma.
  • Cache e ricerca: ricerca di oggetti e manipolazione della cache.

3.1 Server

Per elencare tutti i server disponibili: 

curl -H "X-API-Key: <CHIAVE_API>"   http://127.0.0.1:8081/api/v1/servers

Esempio di risposta semplificata: 

[
  {
    "id": "localhost",
    "type": "Server",
    "daemon_type": "authoritative",
    "version": "4.9.0",
    "url": "/api/v1/servers/localhost",
    "config_url": "/api/v1/servers/localhost/config"
  }
]

Per ottenere i dettagli di un singolo server: 

curl -H "X-API-Key: <CHIAVE_API>"   http://127.0.0.1:8081/api/v1/servers/localhost

3.2 Gestione delle zone

Le zone sono rappresentate da oggetti JSON che contengono informazioni come nome, tipo (primaria, secondaria), seriale, record, commenti e parametri DNSSEC.

3.2.1 Elenco delle zone

curl -H "X-API-Key: <CHIAVE_API>"   http://127.0.0.1:8081/api/v1/servers/localhost/zones

Esempio di frammento di risposta: 

[
  {
    "id": "example.com.",
    "name": "example.com.",
    "kind": "Master",
    "url": "/api/v1/servers/localhost/zones/example.com.",
    "serial": 2025012101,
    "dnssec": true
  }
]

3.2.2 Creazione di una zona

Per creare una zona primaria con un set minimo di record: 

{
  "name": "example.com.",
  "kind": "Master",
  "masters": [],
  "nameservers": [
    "ns1.example.com."
  ]
}

Chiamata HTTP corrispondente: 

curl -X POST -H "X-API-Key: <CHIAVE_API>"   -H "Content-Type: application/json"   -d @zona-example.json   http://127.0.0.1:8081/api/v1/servers/localhost/zones

3.2.3 Dettagli, modifica e cancellazione di una zona

Per ottenere i dettagli di una singola zona: 

curl -H "X-API-Key: <CHIAVE_API>"   http://127.0.0.1:8081/api/v1/servers/localhost/zones/example.com.

Per cancellare una zona: 

curl -X DELETE -H "X-API-Key: <CHIAVE_API>"   http://127.0.0.1:8081/api/v1/servers/localhost/zones/example.com.

3.3 Gestione dei record tramite RRset

I record DNS sono gestiti tramite oggetti RRset. Ogni RRset contiene una combinazione di name e type e un elenco di record (ognuno con campo content, ttl e disabled).

Le modifiche avvengono tramite PATCH sulla zona, con un payload che specifica una lista di RRset e il relativo changetype: REPLACE, DELETE o talvolta ADD a seconda della versione.

3.3.1 Aggiunta o sostituzione di record

Esempio: aggiungere un record A per www.example.com: 

{
  "rrsets": [
    {
      "name": "www.example.com.",
      "type": "A",
      "changetype": "REPLACE",
      "ttl": 300,
      "records": [
        {
          "content": "203.0.113.10",
          "disabled": false
        }
      ]
    }
  ]
}

Chiamata HTTP: 

curl -X PATCH -H "X-API-Key: <CHIAVE_API>"   -H "Content-Type: application/json"   -d @rrset-www.json   http://127.0.0.1:8081/api/v1/servers/localhost/zones/example.com.

3.3.2 Cancellazione di record

Per cancellare tutti i record A di www.example.com: 

{
  "rrsets": [
    {
      "name": "www.example.com.",
      "type": "A",
      "changetype": "DELETE"
    }
  ]
}

3.4 DNSSEC, meta-dati e chiavi

L'API Authoritative espone endpoint dedicati per:

  • Cryptokey: gestione delle chiavi DNSSEC per le zone.
  • Metadata: parametri avanzati della zona (per esempio, modalità di firma).
  • TSIG Keys: chiavi TSIG utilizzate per AXFR, IXFR e notifiche.

Esempio di elenco delle chiavi DNSSEC per una zona: 

curl -H "X-API-Key: <CHIAVE_API>"   http://127.0.0.1:8081/api/v1/servers/localhost/zones/example.com./cryptokeys

3.5 Ricerca e cache

Per cercare una stringa all'interno di vari oggetti (zone, record, eccetera): 

curl -H "X-API-Key: <CHIAVE_API>"   "http://127.0.0.1:8081/api/v1/servers/localhost/search-data?q=example.com.&max=10"

Per manipolare la cache (ad esempio flush di un dominio): 

curl -X PUT -H "X-API-Key: <CHIAVE_API>"   "http://127.0.0.1:8081/api/v1/servers/localhost/cache/flush?domain=example.com."

3.6 Statistiche

PowerDNS Authoritative espone una serie di statistiche tramite l'endpoint /statistics: 

curl -H "X-API-Key: <CHIAVE_API>"   http://127.0.0.1:8081/api/v1/servers/localhost/statistics

Esempio di risposta semplificata: 

[
  {
    "name": "queries",
    "type": "StatisticItem",
    "value": 123456
  },
  {
    "name": "corrupt-packets",
    "type": "StatisticItem",
    "value": 12
  }
]

4. API del PowerDNS Recursor

Il PowerDNS Recursor espone un web server integrato con API HTTP simili a quelle dell'Authoritative, ma focalizzate su:

  • Statistiche dettagliate di risoluzione e cache.
  • Gestione della cache (flush, parametrizzazione).
  • Alcuni aspetti di configurazione dinamica.

4.1 Abilitazione dell'API del Recursor

Esempio di configurazione (file recursor.conf o YAML equivalente): 

webserver=yes
api-key=SuperSegretaChiaveRecursor
webserver-address=127.0.0.1
webserver-port=8082

Verifica della radice dell'API: 

curl -H "X-API-Key: SuperSegretaChiaveRecursor"   http://127.0.0.1:8082/api/v1

4.2 Endpoint comuni del Recursor

Alcuni endpoint tipici sono:

  • /api/v1/servers: elenco dei server recursor.
  • /api/v1/servers/{server_id}: informazioni su una singola istanza.
  • /api/v1/servers/{server_id}/statistics: statistiche dettagliate.
  • /api/v1/servers/{server_id}/cache/flush: flush della cache.
  • /api/v1/servers/{server_id}/config: alcune impostazioni runtime.

4.3 Esempio: lettura delle statistiche

curl -H "X-API-Key: SuperSegretaChiaveRecursor"   http://127.0.0.1:8082/api/v1/servers/localhost/statistics

Risposta semplificata: 

[
  {
    "name": "questions",
    "value": 98765,
    "type": "StatisticItem"
  },
  {
    "name": "cache-hits",
    "value": 76543,
    "type": "StatisticItem"
  }
]

4.4 Esempio: flush della cache

Per svuotare l'intera cache: 

curl -X PUT -H "X-API-Key: SuperSegretaChiaveRecursor"   "http://127.0.0.1:8082/api/v1/servers/localhost/cache/flush"

Per svuotare solo le voci relative a un dominio specifico: 

curl -X PUT -H "X-API-Key: SuperSegretaChiaveRecursor"   "http://127.0.0.1:8082/api/v1/servers/localhost/cache/flush?domain=example.com."

5. Integrazione delle API in applicazioni e strumenti

Grazie al fatto che le API utilizzano HTTP e JSON, possono essere facilmente integrate in qualsiasi linguaggio o framework che supporti richieste HTTP. Alcuni scenari tipici:

  • Portali self-service per creare e gestire zone e record per utenti finali.
  • Automazione DevOps e infrastruttura as code (Terraform, Ansible, eccetera).
  • Integrazione con sistemi di provisioning (per esempio, creazione di record quando si attiva un nuovo server).
  • Monitoraggio avanzato tramite raccolta delle statistiche ed esposizione verso sistemi come Prometheus, Netdata o Datadog.

5.1 Esempio di script Python per creare un record

Esempio minimale con la libreria requests: 

import json
import requests

API_KEY = "SuperSegretaChiaveAPI"
API_URL = "http://127.0.0.1:8081/api/v1/servers/localhost/zones/example.com."

payload = {
    "rrsets": [
        {
            "name": "api.example.com.",
            "type": "A",
            "changetype": "REPLACE",
            "ttl": 300,
            "records": [
                {"content": "198.51.100.42", "disabled": False}
            ]
        }
    ]
}

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

response = requests.patch(API_URL, headers=headers, data=json.dumps(payload))
response.raise_for_status()
print("Record creato, stato:", response.status_code)

6. Sicurezza e buone pratiche

Poiché le API di PowerDNS permettono modifiche dirette alla configurazione DNS, è fondamentale adottare alcune misure di sicurezza:

  • Limitare l'esposizione del web server a 127.0.0.1 o a una rete di management dedicata.
  • Utilizzare firewall e, se possibile, tunnel cifrati (VPN, SSH) per l'accesso remoto.
  • Proteggere il file di configurazione che contiene la chiave API.
  • Ruotare periodicamente le chiavi API.
  • Integrare l'accesso alle API in un sistema di automazione controllato, invece di usarle manualmente da postazioni non protette.

7. Conclusioni

Le API di PowerDNS trasformano il server DNS da semplice componente infrastrutturale a servizio pienamente integrabile nei flussi di automazione e nelle piattaforme self-service. Con pochi endpoint ben progettati è possibile gestire in modo sicuro e ripetibile zone, record, chiavi DNSSEC e statistiche, sia per l'Authoritative Server sia per il Recursor.

Partendo dagli esempi mostrati in questo articolo, puoi costruire strumenti personalizzati, pipeline CI/CD che aggiornano automaticamente i record DNS, integrazioni con sistemi di provisioning e console di monitoraggio centralizzate.

Torna su