PowerDNS Driver Documentation

PowerDNS is an open-source DNS server.

The current libcloud PowerDNS driver uses the HTTP API from PowerDNS 3.x by default. Please read the PowerDNS 3 HTTP API documentation to enable the HTTP API on your PowerDNS server. Specifically, you will need to set the following in pdns.conf:

experimental-json-interface=yes
experimental-api-key=changeme
webserver=yes

For PowerDNS 4.x, please read the PowerDNS 4 HTTP API documentation. The pdns.conf options are slightly different (the options are no longer prefixed with experimental-, and json-interface is no longer required.):

api-key=changeme
webserver=yes

Be sure to reload the pdns service after any configuration changes.

Instantiating the driver

To instantiate the driver you need to pass the API key, hostname, and webserver HTTP port to the driver constructor as shown below.

from libcloud.dns.types import Provider
from libcloud.dns.providers import get_driver

cls = get_driver(Provider.POWERDNS)

# powerdns3.example.com is running PowerDNS v3.x.
driver = cls(key="changeme", host="powerdns3.example.com", port=8081)

# OR:

# powerdns4.example.com is running PowerDNS v4.x, so it uses api_version v1.
driver = cls(key="changeme", host="powerdns4.example.com", port=8081, api_version="v1")

API Docs

class libcloud.dns.drivers.powerdns.PowerDNSDriver(key, secret=None, secure=False, host=None, port=None, api_version='experimental', **kwargs)[source]

PowerDNS Driver defaulting to using PowerDNS 3.x API (ie “experimental”).

Parameters
  • key (str) – API key or username to used (required)

  • secure (bool) – Whether to use HTTPS or HTTP. Note: Off by default for PowerDNS.

  • host (str) – Hostname used for connections.

  • port (int) – Port used for connections.

  • api_version (str) – Specifies the API version to use. experimental and v1 are the only valid options. Defaults to using experimental (optional)

Returns

None

connectionCls

alias of libcloud.dns.drivers.powerdns.PowerDNSConnection

create_record(name, zone, type, data, extra=None)[source]

Create a new record.

There are two PowerDNS-specific quirks here. Firstly, this method will silently clobber any pre-existing records that might already exist. For example, if PowerDNS already contains a “test.example.com” A record, and you create that record using this function, then the old A record will be replaced with your new one.

Secondly, PowerDNS requires that you provide a ttl for all new records. In other words, the “extra” parameter must be {'ttl': <some-integer>} at a minimum.

Parameters
  • name (str) – FQDN of the new record, for example “www.example.com”.

  • zone (Zone) – Zone where the requested record is created.

  • type (RecordType) – DNS record type (A, AAAA, …).

  • data (str) – Data for the record (depends on the record type).

  • extra (dict) – Extra attributes (driver specific, e.g. ‘ttl’). Note that PowerDNS requires a ttl value for every record.

Return type

Record

create_zone(domain, type=None, ttl=None, extra={})[source]

Create a new zone.

There are two PowerDNS-specific quirks here. Firstly, the “type” and “ttl” parameters are ignored (no-ops). The “type” parameter is simply not implemented, and PowerDNS does not have an ability to set a zone-wide default TTL. (TTLs must be set per-record.)

Secondly, PowerDNS requires that you provide a list of nameservers for the zone upon creation. In other words, the “extra” parameter must be {'nameservers': ['ns1.example.org']} at a minimum.

Parameters
  • name (str) – Zone domain name (e.g. example.com)

  • domain (Zone) – Zone type (master / slave). (optional). Note that the PowerDNS driver does nothing with this parameter.

  • ttl (int) – TTL for new records. (optional). Note that the PowerDNS driver does nothing with this parameter.

  • extra (dict) – Extra attributes (driver specific). For example, specify extra={'nameservers': ['ns1.example.org']} to set a list of nameservers for this new zone.

Return type

Zone

delete_record(record)[source]

Use this method to delete a record.

Parameters

record (Record) – record to delete

Return type

bool

delete_zone(zone)[source]

Use this method to delete a zone.

Parameters

zone (Zone) – zone to delete

Return type

bool

export_zone_to_bind_format(zone)

Export Zone object to the BIND compatible format.

Parameters

zone (Zone) – Zone to export.

Returns

Zone data in BIND compatible format.

Return type

str

export_zone_to_bind_zone_file(zone, file_path)

Export Zone object to the BIND compatible format and write result to a file.

Parameters
  • zone (Zone) – Zone to export.

  • file_path (str) – File path where the output will be saved.

get_record(zone_id, record_id)

Return a Record instance.

Parameters
  • zone_id (str) – ID of the required zone

  • record_id (str) – ID of the required record

Return type

Record

get_zone(zone_id)[source]

Return a Zone instance.

(Note that PowerDNS does not support per-zone TTL defaults, so all Zone objects will have ttl=None.)

Parameters

zone_id (str) – name of the required zone with the trailing period, for example “example.com.”.

Return type

Zone

Raises

ZoneDoesNotExistError: If no zone could be found.

iterate_records(zone)

Return a generator to iterate over records for the provided zone.

Parameters

zone (Zone) – Zone to list records for.

Return type

generator of Record

iterate_zones()

Return a generator to iterate over available zones.

Return type

generator of Zone

list_record_types()

Return a list of RecordType objects supported by the provider.

Returns

list of RecordType

list_records(zone)[source]

Return a list of all records for the provided zone.

Parameters

zone (Zone) – Zone to list records for.

Returns

list of Record

list_zones()[source]

Return a list of zones.

Returns

list of Zone

update_record(record, name, type, data, extra=None)[source]

Update an existing record.

Parameters
  • record (Record) – Record to update.

  • name (str) – FQDN of the new record, for example “www.example.com”.

  • type (RecordType) – DNS record type (A, AAAA, …).

  • data (str) – Data for the record (depends on the record type).

  • extra (dict) – (optional) Extra attributes (driver specific).

Return type

Record

update_zone(zone, domain, type='master', ttl=None, extra=None)

Update an existing zone.

Parameters
  • zone (Zone) – Zone to update.

  • domain (str) – Zone domain name (e.g. example.com)

  • type (str) – Zone type (master / slave).

  • ttl (int) – TTL for new records. (optional)

  • extra (dict) – Extra attributes (driver specific). (optional)

Return type

Zone