PowerDNS API Configuration¶

Overview¶

Poweradmin can interact with PowerDNS through its REST API in two ways:

Supplementary mode (default): The API enhances a traditional SQL-based setup with DNSSEC management, zone transfers, and metadata access. Poweradmin still queries the PowerDNS database directly for zone and record operations.
API backend mode (v4.3.0+): The API is the sole communication channel with PowerDNS. Poweradmin does not need access to the PowerDNS database at all. This is ideal for cloud-hosted PowerDNS, network-restricted environments, or API-first architectures.

This document explains how to configure both modes.

In both modes one Poweradmin installation manages one PowerDNS server, the one named by pdns_api.server_name. Managing several servers from a single installation is an open request, tracked in #660.

Prerequisites¶

PowerDNS server with API enabled
API key generated on PowerDNS server
Network connectivity between Poweradmin and PowerDNS API endpoint

Configuration Options¶

PowerDNS API settings are configured in the config/settings.php file under the pdns_api section.

Setting	Default value	Description	Added in version
pdns_api.url	''	The endpoint for establishing a connection to the PowerDNS API	3.7.0
pdns_api.key	''	The authentication key required for establishing a connection with the PowerDNS API	3.7.0
pdns_api.display_name	PowerDNS	PowerDNS name to identify server in the interface	4.0.0
pdns_api.server_name	localhost	PowerDNS server name used in API calls	4.0.0
pdns_api.timeout	10	PowerDNS API request timeout in seconds. GET requests are retried once on transient failures; writes are not retried.	4.4.0
dns.backend	sql	Backend mode: `sql` (database) or `api` (API only)	4.3.0

Configuration Example¶

return [
    'pdns_api' => [
        'display_name' => 'Production PowerDNS',
        'url' => 'http://localhost:8081',
        'key' => 'YOUR_API_KEY',
        'server_name' => 'localhost',
    ],
];

PowerDNS Server Setup¶

To enable the API in your PowerDNS configuration, add the following to your PowerDNS configuration file:

# Enable API and webserver
api=yes
api-key=YOUR_API_KEY
webserver=yes
webserver-port=8081
webserver-address=127.0.0.1  # Restrict to localhost for security

For production environments, it's recommended to secure the API with HTTPS:

webserver-port=8081
webserver-address=0.0.0.0
webserver-allow-from=192.168.0.0/24,127.0.0.1
webserver-password=YOUR_PASSWORD
webserver-loglevel=none

Testing Connection¶

You can verify the API connection by running:

curl -H "X-API-Key: YOUR_API_KEY" http://localhost:8081/api/v1/servers/localhost

If the connection is successful, you should receive a JSON response with server information.

Functionality Enabled by API¶

With the PowerDNS API properly configured, Poweradmin gains the following capabilities:

DNSSEC management (key creation, rotation, DS record handling)
Real-time zone transfers
Metadata management
Direct server statistics access
New zones served at once in SQL mode (v4.6.0+), see below
Send NOTIFY and Retrieve from primary on the zone edit page in SQL mode (v4.6.0+)

The PowerDNS Server Status page reports whether the server is reachable, its version, daemon type and uptime, and the connectivity of each configured autoprimary. It is shown when interface.show_pdns_status is true. Administrators can always open it; since v4.5.0 other users need the server_status_view permission, which makes a dedicated monitoring account possible without administrator rights.

The same data is available to monitoring systems as GET /api/v2/server/status, which uses Poweradmin's API keys and permissions instead of the PowerDNS API key. See API Endpoints.

New Zones and the PowerDNS Zone Cache¶

PowerDNS 4.5 and later keeps a list of the zones it serves in memory and reloads it from the database every zone-cache-refresh-interval seconds (300 by default). In SQL mode Poweradmin writes new zones straight to the database, so without help a new zone answers REFUSED until the next reload. Record changes can also show up late, because PowerDNS caches answers for cache-ttl and negquery-cache-ttl seconds.

Since v4.6.0, when pdns_api.url and pdns_api.key are set, Poweradmin calls the PowerDNS cache flush after creating or deleting a zone and after changing records. PowerDNS 4.6 and later then serves the change at once. A failed flush is logged and does not fail the save. In API backend mode PowerDNS handles this itself.

Without the API, Poweradmin cannot tell PowerDNS about a change. If the wait for new zones matters, lower zone-cache-refresh-interval in pdns.conf, for example to 60.

API Backend Mode (v4.3.0+)¶

API backend mode eliminates the need for Poweradmin to access the PowerDNS database. All DNS operations go through the PowerDNS REST API.

When to Use API Backend Mode¶

PowerDNS database is not accessible from the Poweradmin server
Running PowerDNS as a managed/cloud service
Network policies prevent direct database access
You prefer API-first integration

PowerDNS 4.7 or newer is recommended. API backend mode runs on any supported PowerDNS version, but zone listings are faster from 4.7 onward, where a single RRset can be fetched instead of a whole zone. See Requirements.

Configuration¶

Set dns.backend to api in your config/settings.php:

return [
    'dns' => [
        'backend' => 'api',
        'hostmaster' => 'hostmaster.example.com',
        'ns1' => 'ns1.example.com',
        'ns2' => 'ns2.example.com',
    ],

    'pdns_api' => [
        'url' => 'http://powerdns-server:8081',
        'key' => 'YOUR_API_KEY',
        'server_name' => 'localhost',
    ],

    // Poweradmin's own database (still required)
    'db_host' => 'localhost',
    'db_port' => 3306,
    'db_user' => 'poweradmin',
    'db_pass' => 'password',
    'db_name' => 'poweradmin',
    'db_type' => 'mysql',

    // PowerDNS database settings are NOT needed in API mode
];

Required: when dns.backend is api, both pdns_api.url and pdns_api.key must be set. Otherwise Poweradmin fails on the first DNS operation with:

dns.backend is set to "api" but pdns_api.url and/or pdns_api.key are not configured.
Set both values or change dns.backend to "sql".

There is no SQL fallback, so writes can't bypass the API path by accident.

New Installation with API Backend¶

The installer (Step 4) offers a choice between "Database" and "API" backend. Selecting API will:

Prompt for the PowerDNS API URL and key
Skip PowerDNS database configuration
Set dns.backend to api in the generated configuration

Installing Poweradmin on top of an existing PowerDNS¶

If PowerDNS already has zones (e.g., you imported them via mysqldump or directly into the domains table), those zones will not appear in Poweradmin immediately after installation.

This is expected behavior. The installer creates Poweradmin's schema and initial configuration - it does not import or reconcile existing PowerDNS zones. Poweradmin stores ownership and metadata in its own zones table, one row per PowerDNS domain, and those rows are added by the zone sync service at runtime.

To populate existing zones after a fresh install:

Log in as an administrator.
Navigate to Forward Zones (not the dashboard). Sync runs on that page load.
All zones from PowerDNS will appear with no owner assigned.
Assign owners (or zone-group access) as needed.

The dashboard may report "0 zones" until the sync has run at least once in API mode. Visiting Forward Zones triggers the sync.

Migrating from SQL to API Backend¶

Ensure the PowerDNS API is enabled and accessible
Run every database update script up to the installed version
Back up the database. The switch is one-way (see below), and the backup is the way back
Check that every zone has a stored name: the API backend finds zones by it, and a zone without one comes back as a new zone with no owners. Open the Database Consistency Check and fix any Zones Without A Stored Name, or run this query and expect 0:
```
SELECT COUNT(*) FROM domains d
WHERE NOT EXISTS (SELECT 1 FROM zones n WHERE n.domain_id = d.id AND n.zone_name = d.name)
  AND (EXISTS (SELECT 1 FROM zones z WHERE z.domain_id = d.id)
       OR EXISTS (SELECT 1 FROM zones_groups g WHERE g.domain_id = d.id)
       OR EXISTS (SELECT 1 FROM api_key_zones k WHERE k.zone_id = d.id));
```
With pdns_db_name, qualify domains with that database name.

From 4.6.0 the SQL backend stores the name whenever it writes a zone row, so only zones last changed by an older version can be affected. 5. Add pdns_api.url and pdns_api.key to config/settings.php and verify the API is reachable (see Testing Connection above) 6. Change dns.backend from sql to api 7. Load any page - the zone sync service automatically populates cached zone metadata

All existing zone ownership, group assignments, and permissions are preserved, except on a zone id two zones share (see Zone IDs Shared by Two Zones).

The switch is one-way. Zone ids the API backend writes are not valid PowerDNS domain ids, so under the SQL backend owners, group grants, API key restrictions and logs would point at other zones. From 4.6.0 Poweradmin refuses to run with dns.backend set to sql on a database the API backend has written zones to: web pages show the error, the API answers 503, and the command line and dynamic DNS updates stop with the same message. A database used with the API backend before 4.6.0 is recognised from its zone rows the first time the SQL backend starts. To go back, restore the backup taken before the switch. If Poweradmin refuses a database that was never used with the API backend (possible on SQLite when a zone was deleted outside Poweradmin and its id given to a new zone), set the backend.zone_ids row in app_settings to sql. The /api/health endpoint reports the database as down while the backend is refused.

What changes at runtime:

All zone and record writes go through the PowerDNS API, so cache flush and DNSSEC rectify/signing are triggered automatically. In SQL mode these required manual pdns_control cache-flush calls.
NOTIFY is not sent as a side effect of an API write. PowerDNS only sends one from the explicit PUT /zones/{id}/notify endpoint, which Poweradmin does not call, or from the primary's periodic serial-check loop - which needs primary=yes (formerly master=yes) in pdns.conf and behaves the same way in SQL mode.
The Poweradmin app no longer needs credentials for the PowerDNS database. You can remove pdns_db_* settings and revoke the corresponding database grants.
When PowerDNS no longer lists more than half of the zones Poweradmin knows, the automatic zone sync changes nothing and logs a warning, because that usually means pdns_api.url points at the wrong or an empty server. An administrator's manual sync on the Forward Zones page applies the changes.

Zone IDs Shared by Two Zones¶

A zone created in API backend mode and a zone migrated from SQL mode can end up with the same zone id. From 4.5.0 Poweradmin handles this as follows:

The id opens one of the two zones. Zone lists, search and zone counts show only that zone.
Extra owners and group grants keyed by the shared id are ignored. Only the direct owner of the zone the id opens keeps access; administrators are not affected.
Adding owners or groups to a shared id is refused. The web forms say so, and the API v2 POST /zones/{id}/owners answers 409 with "Owners cannot be added to this zone: its ID is shared with another zone".
The owner and group grants keyed by the shared id are removed when either zone is deleted, when the zone sync removes a zone that was deleted from PowerDNS, and when a zone whose old entry was left behind is added again.

From 4.6.0 the Database Consistency Check lists every shared id with both zone names, so an administrator can separate them. Poweradmin does not separate them automatically.

Zone Sync Service¶

In API backend mode, a sync service keeps the local zones table in sync with PowerDNS:

Automatic: Runs on zone list page loads, throttled to once per 5 minutes per session
Adds zones created directly in PowerDNS (assigned no owner - admin must assign access)
Removes local entries for zones deleted from PowerDNS
Updates cached zone type and master when changed

Manual Sync (v4.4.0+)¶

If you've just created zones in PowerDNS through pdnsutil or another tool and don't want to wait for the next scheduled sync, the Forward Zones page now has a Sync from PowerDNS button. Clicking it triggers an immediate sync against the PowerDNS API.

The button is only shown to ueberusers, and the server re-checks that permission when the CSRF-protected POST arrives. Unlike the automatic sync, the manual press is not throttled: it always runs a full reconciliation.

What Happens When the API is Down¶

If PowerDNS becomes unreachable, sync stops but the dashboard does not throw a stack trace at users. Instead:

The cached zone count from the last successful sync is kept on display, so you don't see "0 zones" during a transient outage.
Admin pages show an API-error banner with the HTTP status and a short hint at what to check next (network, credentials, capabilities endpoint).
Sync retries are not throttled during outages - once the API comes back, the next page load reconciles normally.

Large Installations¶

With the SQL backend there is no sync: pages read the PowerDNS tables directly, so nothing has to run or finish before a zone shows up.

In API backend mode the sync makes one GET /zones request. It reads only the zone list (names, kinds and primaries), never the records of each zone, and runs at most once per 5 minutes per session. With dnssec.enabled (or the signed serial column) turned on, the same request also asks PowerDNS for each zone's DNSSEC state, which PowerDNS works out zone by zone and which makes the response slower on large servers. New zones are added in a single transaction. The zone list page reads the same response, so on servers with tens of thousands of zones, raise pdns_api.timeout (default 10 seconds) if the list or the sync times out.

Known Issue: Backslash Escapes on PowerDNS Auth 5.1¶

PowerDNS Auth 5.1.x removes one level of backslash escaping from record content written through its REST API (PowerDNS issue 18159). This affects API backend mode on every Poweradmin version that has it (4.3.0 and later). The SQL backend writes to the database directly and is not affected.

Content sent	PowerDNS 5.1.x stores	Served as
`"a\\b"`	`"a\b"`	`"ab"`
`"a\"b"`	refused with `422`	-

Poweradmin saves a record by sending back every record with the same name and type, so saving any of them also rewrites the others. A TXT record holding \\ loses a backslash even when you only add, edit or delete its neighbour. One holding \" makes every save at that name and type fail.

From 4.5.0, the zone, add record, bulk add and edit record pages warn in API backend mode. They list the affected records and flag content you type that contains a backslash. The save still goes ahead.

Until PowerDNS fixes this, edit these records with pdnsutil, for example:

pdnsutil rrset replace example.com. txt.example.com. TXT 3600 '"a\\b"'

PowerDNS Auth 5.1.5 does not contain the fix yet.

Known Issue: LUA Records Refused on PowerDNS Auth 5.1¶

PowerDNS Auth 5.1.0 added enable-lua-record-updates, which defaults to no. While it is off, PowerDNS refuses to create, update or delete LUA records over its REST API (and through AXFR and DNS UPDATE). In API backend mode Poweradmin therefore cannot add, edit or delete LUA records, and creating a zone from a template that contains LUA records fails. The SQL backend writes to the database directly and is not affected.

The web record forms show the PowerDNS reason. From 4.6.0 the API v2 does too: it answers 422 with "Failed to create record" (or "Failed to update record" / "Failed to delete record") followed by the reason, for example "update of Lua records is not allowed". Creating a zone from such a template fails with "Failed to create LUA record for zone: ". Versions before 4.6.0 answer 500 with only the generic message (poweradmin/poweradmin#1779); the reason is in the Poweradmin log. To allow these writes, set this in pdns.conf and restart PowerDNS:

enable-lua-record-updates=yes

PowerDNS 5 Views and View Variants (v4.5.2+)¶

With PowerDNS Auth 5 on the LMDB backend and views=yes, a zone can have per-view variants named zone..variant, created with pdnsutil zone create example.com..internal. In API backend mode Poweradmin opens and edits these zones: records are shown and written under the apex name (www becomes www.example.com), and the SOA serial bump and the SOA badge work. From 4.5.2, Dynamic DNS updates prefer the base zone over its variant. Earlier versions could not open a variant. The fix is in 4.6.0, 4.5.2 and 4.4.4. Reverse zone variants are not yet treated as reverse zones (poweradmin/poweradmin#1786).

Record Comments on LMDB¶

Before PowerDNS Auth 5.1.5, the LMDB backend kept a zone's or RRset's comments after the zone or RRset was deleted. 5.1.5 deletes them together (PowerDNS pull request 18111).

Docker¶

For Docker deployments, set the backend via environment variable:

environment:
  PA_DNS_BACKEND: api
  PA_PDNS_API_URL: http://powerdns:8081
  PA_PDNS_API_KEY: your-api-key

Security Considerations¶

Always use HTTPS for production environments
Restrict API access to trusted IP addresses
Use a strong API key and rotate it regularly
Consider using a reverse proxy for additional security
Keep PowerDNS and Poweradmin updated to the latest versions
In API backend mode, the API key grants full control over PowerDNS - protect it accordingly