PowerdnsApiClient
class PowerdnsApiClient (View source)
Typed wrapper over the PowerDNS /api/v1 server endpoints: zones, RRsets, DNSSEC keys, metadata, TSIG, views.
Constants
| private API_VERSION_PATH |
|
| private MAX_CACHED_READS |
One save reads about five distinct narrowed endpoints for a single name, so this covers it with room for a second name |
| private RRSET_FILTER_MIN_VERSION |
Filtered zone reads only return disabled records from this version on |
| private ZONE_LIST_CATALOG_MIN_VERSION |
The zone list reports each zone's catalog from this version on; 4.7 and 4.8 leave it empty |
Methods
No description
Drop PowerDNS's cached answers for a zone and (re)load it into the zone cache, so a zone written straight to the database is served without waiting.
Get all zones from the PowerDNS server
Get zone stats (DNSSEC, serial) for all zones in a single API call.
Count the zones PowerDNS serves by kind and how many of them are signed, from a single zone list request.
Get zone kind/masters/catalog for all zones in a single API call. Used to keep the local zones-table cache aligned with PowerDNS when zone kinds change outside Poweradmin (e.g. via pdnsutil set-kind), and to resolve catalog membership without a per-zone lookup.
The form PowerDNS itself stores in domains.catalog: lowercase, no trailing dot. Its member lookup is an exact string match, so anything else produces a zone that is accepted and then silently never published.
Get the DNSSEC keys of a zone, telling a failed request apart from a zone without keys.
Add a DNSSEC key and return the key PowerDNS created.
Create a DNSSEC key from an existing private key and return the key PowerDNS created.
Fetch a single cryptokey including its privatekey field, which
PowerDNS only returns from the per-key GET endpoint (the list view
omits it). Returns null when the key cannot be retrieved.
Check if a zone is secured with DNSSEC, telling a failed request apart from an unsigned zone
Update metadata for a zone, replacing existing entries of the given kind
Get PowerDNS configuration
Get PowerDNS server information
getConfig() flattened to a name => value map for settings lookups.
Get PowerDNS server metrics
Fetch the RRsets at one name instead of the whole zone body. Leaving the type out returns every type at that name.
PowerDNS 4.7 and 4.8 have catalog zones but leave the catalog field of the zone list empty; only a single zone read reports it.
A zone's catalog from a single zone read, canonicalised like getAllZoneKinds().
Get a single zone with its RRsets
Create a zone with full data and return the response
Update zone properties (kind, masters, account, etc.)
Trigger an immediate AXFR transfer of a secondary zone from its master.
Queue a NOTIFY to the secondaries of a primary zone.
Patch zone RRsets (add, modify, or delete records)
What PowerDNS said when it refused the last patchZoneRRsets() call, or null when the call succeeded or failed without a PowerDNS verdict (transport, auth).
The HTTP status of the answer behind getLastWriteRejection(), or null without one.
Search across zones, records, and comments
Get all autoprimaries
Add an autoprimary
Delete an autoprimary
Get all TSIG keys
Create a TSIG key
Delete a TSIG key
Update a TSIG key
List all views configured on the server.
List zones assigned to a specific view. Zone strings are returned in the upstream "zone..variant" form (e.g. "example.com..trusted").
Add a zone (in "zone..variant" form) to a view. Creates the view if it doesn't exist yet, per upstream behaviour.
No description
List all network -> view mappings. Each entry is of the form ['network' => '192.168.0.0/16', 'view' => 'trusted'].
Assign a CIDR block to a view. PowerDNS expects the CIDR in path form, e.g. PUT /networks/192.168.0.0/16.
No description
Details
__construct(HttpClient $httpClient, string $serverName, ApiStatusRecorderInterface $apiStatus, LoggerInterface|null $logger = null, string|null $serverVersion = null)
No description
bool
flushZoneCache(string $zoneName)
Drop PowerDNS's cached answers for a zone and (re)load it into the zone cache, so a zone written straight to the database is served without waiting.
bool
rectifyZone(Zone $zone)
Rectify a zone
bool
secureZone(Zone $zone)
Enable DNSSEC for a zone
bool
unsecureZone(Zone $zone)
Disable DNSSEC for a zone
array
getAllZones(bool $withDnssec = true)
Get all zones from the PowerDNS server
array
getAllZoneStats(bool $withDnssec = true)
Get zone stats (DNSSEC, serial) for all zones in a single API call.
The zone list response carries no record count, so callers that need one must fetch it per zone.
array|null
getZoneCounts()
Count the zones PowerDNS serves by kind and how many of them are signed, from a single zone list request.
array
getAllZoneKinds(bool $withDnssec = false)
Get zone kind/masters/catalog for all zones in a single API call. Used to keep the local zones-table cache aligned with PowerDNS when zone kinds change outside Poweradmin (e.g. via pdnsutil set-kind), and to resolve catalog membership without a per-zone lookup.
Only kind/masters/catalog are read here, so the DNSSEC lookup is skipped by default. Callers that also read the zone list with DNSSEC state should pass true so both reads share one response rather than fetching the list under two different URLs.
static string
canonicalZoneName(string $name)
The form PowerDNS itself stores in domains.catalog: lowercase, no trailing dot. Its member lookup is an exact string match, so anything else produces a zone that is accepted and then silently never published.
bool
createZone(Zone $zone)
Create a new zone
bool
updateZone(Zone $zone)
Update a zone
bool
deleteZone(Zone $zone)
Delete a zone
array
getZoneKeys(Zone $zone)
Get DNSSEC keys for a zone
array|null
fetchZoneKeys(Zone $zone)
Get the DNSSEC keys of a zone, telling a failed request apart from a zone without keys.
CryptoKey|null
createZoneKey(Zone $zone, CryptoKey $key, bool $active = false)
Add a DNSSEC key and return the key PowerDNS created.
CryptoKey|DnssecKeyOutcome
createZoneKeyFromPrivateKey(Zone $zone, string $keyType, string $privateKey, bool $active = false)
Create a DNSSEC key from an existing private key and return the key PowerDNS created.
The private key is in the ISC/BIND format ("Private-key-format: v1.x"), which PowerDNS accepts on POST /cryptokeys since 4.1. Only keytype, privatekey and active are sent: PowerDNS derives algorithm and size from the key and answers 422 when algorithm or bits are sent as well. The private key is never logged.
array|null
getZoneKeyWithPrivate(Zone $zone, int $keyId)
Fetch a single cryptokey including its privatekey field, which
PowerDNS only returns from the per-key GET endpoint (the list view
omits it). Returns null when the key cannot be retrieved.
bool
isZoneSecured(Zone $zone)
Check if a zone is secured with DNSSEC
bool|null
fetchZoneSecured(Zone $zone)
Check if a zone is secured with DNSSEC, telling a failed request apart from an unsigned zone
array
getZoneMetadata(Zone $zone)
Get all metadata for a zone
array
getZoneMetadataKind(Zone $zone, string $kind)
Get a specific metadata kind for a zone
bool
createZoneMetadata(Zone $zone, string $kind, array $metadata)
Create metadata for a zone
bool
updateZoneMetadata(Zone $zone, string $kind, array $metadata)
Update metadata for a zone, replacing existing entries of the given kind
bool
deleteZoneMetadata(Zone $zone, string $kind)
Delete all metadata of a given kind for a zone
array
getConfig()
Get PowerDNS configuration
array
getServerInfo()
Get PowerDNS server information
array
getServerConfig()
getConfig() flattened to a name => value map for settings lookups.
array
getMetrics()
Get PowerDNS server metrics
array|null
getZoneRrset(string $zoneName, string $rrsetName, string|null $rrsetType = null)
Fetch the RRsets at one name instead of the whole zone body. Leaving the type out returns every type at that name.
PowerDNS below 4.7 does not know these filters, ignores them and returns the entire zone, so callers must still scan the RRsets they get back.
bool
zoneListOmitsCatalog()
PowerDNS 4.7 and 4.8 have catalog zones but leave the catalog field of the zone list empty; only a single zone read reports it.
string
getZoneCatalogName(string $zoneName)
A zone's catalog from a single zone read, canonicalised like getAllZoneKinds().
Kept for the request because the zone read cache holds only a few bodies.
array|null
getZone(string $zoneName, bool $includeRrsets = true, array $filters = [])
Get a single zone with its RRsets
array|null
createZoneWithData(array $zoneData)
Create a zone with full data and return the response
bool
updateZoneProperties(string $zoneName, array $data)
Update zone properties (kind, masters, account, etc.)
bool
retrieveZone(string $zoneName)
Trigger an immediate AXFR transfer of a secondary zone from its master.
Asks PowerDNS to pull the zone now instead of waiting for the next scheduled refresh. Returns false when the master refuses the transfer.
bool
notifyZone(string $zoneName)
Queue a NOTIFY to the secondaries of a primary zone.
bool
patchZoneRRsets(string $zoneName, array $rrsets)
Patch zone RRsets (add, modify, or delete records)
string|null
getLastWriteRejection()
What PowerDNS said when it refused the last patchZoneRRsets() call, or null when the call succeeded or failed without a PowerDNS verdict (transport, auth).
int|null
getLastWriteRejectionStatus()
The HTTP status of the answer behind getLastWriteRejection(), or null without one.
array
searchData(string $query, string $objectType = 'all', int $max = 100)
Search across zones, records, and comments
array
getAutoprimaries()
Get all autoprimaries
bool
addAutoprimary(string $ip, string $nameserver, string $account = '')
Add an autoprimary
bool
deleteAutoprimary(string $ip, string $nameserver)
Delete an autoprimary
array
getTsigKeys()
Get all TSIG keys
array|null
createTsigKey(string $name, string $algorithm, string $key = '')
Create a TSIG key
bool
deleteTsigKey(string $keyId)
Delete a TSIG key
bool
updateTsigKey(string $keyId, array $data)
Update a TSIG key
array
listViews()
List all views configured on the server.
array
listViewZones(string $view)
List zones assigned to a specific view. Zone strings are returned in the upstream "zone..variant" form (e.g. "example.com..trusted").
bool
addZoneToView(string $view, string $zoneName)
Add a zone (in "zone..variant" form) to a view. Creates the view if it doesn't exist yet, per upstream behaviour.
bool
removeZoneFromView(string $view, string $zoneName)
No description
array
listNetworks()
List all network -> view mappings. Each entry is of the form ['network' => '192.168.0.0/16', 'view' => 'trusted'].
bool
setNetworkView(string $cidr, string $view)
Assign a CIDR block to a view. PowerDNS expects the CIDR in path form, e.g. PUT /networks/192.168.0.0/16.
bool
deleteNetwork(string $cidr)
No description