Powerdns API

A Nodejs client for the PowerDns API with the most relevant functions.

Install

npm i @firstdorsal/powerdns-api

Usage

(async () => {
    //get enviroment variables from the .env file
    require("dotenv").config();
    //import the module
    const { PowerdnsClient } = require("@firstdorsal/powerdns-api");
    //create a powerdns client object
    const pdns = new PowerdnsClient(process.env.PDNS_API_ENDPOINT, process.env.PDNS_API_KEY);
    //use a function and return the results to console
    console.log(await pdns.getZone("example.com"));
})();

What is dotenv?

The line "require('dotenv').config();" gets the contents of a file called ".env" in which you should store your global and secret variables.

1. Install the module "dotenv" with

npm i dotenv

2. Create a file named ".env" in your applications root directory

.env

PDNS_API_KEY='YOUR PDNS API KEY'
PDNS_API_ENDPOINT='https://example.com/api/v1/servers/localhost'

3. Use your secret variables

process.env.PDNS_API_ENDPOINT
process.env.PDNS_API_KEY

IMPORTANT

if you are using domains with two labels for the TLD like yourdomain.com.au please use the setHomogeneousRecords function instead of setRecords

Documentation

Here

Need help or missing a feature?

Feel free to contact me via [email protected] in english or german

Automatic Let's Encrypt certificates via DNS with greenlock and PDNS

acme-dns-01-powerdns

PDNS WEB API Documentation

On the Web

And in full detail (Swagger)

Links

NPM

Documentation

Code

Modules

Typedefs

powerdns-api

• powerdns-api
  • .PowerdnsClient
    • new module.exports.PowerdnsClient(baseurl, apikey)
    • .getZones() ⇒ Array
    • .createZone(zoneName, [kind]) ⇒ Object
    • .getZoneWithMeta(zoneName) ⇒ object
    • .getZone(zoneName) ⇒ object
    • .deleteZone(zoneName) ⇒ boolean
    • .setHomogeneousRecords(records, [domain]) ⇒ boolean
    • .deleteRecords(records) ⇒ boolean
    • .search(search) ⇒ object
    • .appendRecord(record) ⇒ boolean
    • .createCryptokey(zoneName, [cryptokey], [returnPrivateKey]) ⇒ Object
    • .getCryptoKeys(zoneName) ⇒ Array.<Cryptokey>
    • .deleteCryptoKey(zoneName, cryptokeyId) ⇒ boolean
    • .setRecords(records) ⇒ Array
    • .replaceRecords(find, replace, zone) ⇒ Number
    • .replaceRecordsGlobal(find, replace) ⇒ Number
    • .findRecords(find, zone) ⇒ Array
    • .findRecordsGlobal(find) ⇒ Array
    • .createAndSetupZone(zone) ⇒ Boolean

powerdns-api.PowerdnsClient

Class representing the powerdns client

Kind: static class of powerdns-api

• .PowerdnsClient
  • new module.exports.PowerdnsClient(baseurl, apikey)
  • .getZones() ⇒ Array
  • .createZone(zoneName, [kind]) ⇒ Object
  • .getZoneWithMeta(zoneName) ⇒ object
  • .getZone(zoneName) ⇒ object
  • .deleteZone(zoneName) ⇒ boolean
  • .setHomogeneousRecords(records, [domain]) ⇒ boolean
  • .deleteRecords(records) ⇒ boolean
  • .search(search) ⇒ object
  • .appendRecord(record) ⇒ boolean
  • .createCryptokey(zoneName, [cryptokey], [returnPrivateKey]) ⇒ Object
  • .getCryptoKeys(zoneName) ⇒ Array.<Cryptokey>
  • .deleteCryptoKey(zoneName, cryptokeyId) ⇒ boolean
  • .setRecords(records) ⇒ Array
  • .replaceRecords(find, replace, zone) ⇒ Number
  • .replaceRecordsGlobal(find, replace) ⇒ Number
  • .findRecords(find, zone) ⇒ Array
  • .findRecordsGlobal(find) ⇒ Array
  • .createAndSetupZone(zone) ⇒ Boolean

new module.exports.PowerdnsClient(baseurl, apikey)

Create a powerdns client.

| Param | Type | Description | | --- | --- | --- | | baseurl | string | The base url where the api can be found | | apikey | string | The api key for the powerdns endpoint |

Example

(async () => {
    require('dotenv').config();

    const {
        PowerdnsClient
    } = require('@firstdorsal/powerdns-api');

    const pdns = new PowerdnsClient(process.env.PDNS_API_ENDPOINT, process.env.PDNS_API_KEY);

    console.log(await pdns.getZone('example.com'));
})();

powerdnsClient.getZones() ⇒ Array

Returns array of all zones from this pdns server.

Kind: instance method of PowerdnsClient
Returns: Array - array of zones
Example

await pdns.getZones();

powerdnsClient.createZone(zoneName, [kind]) ⇒ Object

Creates zone/domain and returns its SOA record on success.

Kind: instance method of PowerdnsClient
Returns: Object - just the rrsets of the zone

| Param | Type | Default | Description | | --- | --- | --- | --- | | zoneName | string | | takes a domain name | | [kind] | 'Native' | 'Master' | 'Slave' | Native | takes the kind of zone you want |

Example

await pdns.createZone('example.com');

powerdnsClient.getZoneWithMeta(zoneName) ⇒ object

Returns single zone with meta information.

Kind: instance method of PowerdnsClient
Returns: object - the zone with meta information

| Param | Type | Description | | --- | --- | --- | | zoneName | string | takes a domain name |

Example

await pdns.getZoneWithMeta('example.com');

powerdnsClient.getZone(zoneName) ⇒ object

Returns array with rrsets for zone.

Kind: instance method of PowerdnsClient
Returns: object - just the rrsets of the zone

| Param | Type | Description | | --- | --- | --- | | zoneName | string | takes a domain name |

Example

await pdns.getZone('example.com');

powerdnsClient.deleteZone(zoneName) ⇒ boolean

Deletes the whole zone with all attached metadata and rrsets.

Kind: instance method of PowerdnsClient
Returns: boolean - true on success

| Param | Type | Description | | --- | --- | --- | | zoneName | string | takes a domain name |

Example

await pdns.deleteZone('example.com');

powerdnsClient.setHomogeneousRecords(records, [domain]) ⇒ boolean

Takes records for a SINGLE domain as array and sets them. If records exist it replaces them.

Kind: instance method of PowerdnsClient
Returns: boolean - boolean indicating the success of the operation

| Param | Type | Description | | --- | --- | --- | | records | Records | array containing the records | | [domain] | string | optional domain name |

Example

await pdns.setHomogeneousRecords([{
           name: "example.com",
           type: "A",
           ttl: 300,
           content: ['1.1.1.1']
       }]);

powerdnsClient.deleteRecords(records) ⇒ boolean

Takes records as array and deletes them.

Kind: instance method of PowerdnsClient
Returns: boolean - boolean indicating the success of the operation

| Param | Type | Description | | --- | --- | --- | | records | Records | array containing the records to be deleted |

Example

await pdns.deleteRecords([{
           name: "example.com",
           type: "A"
       }]);

powerdnsClient.search(search) ⇒ object

Takes Search object and searches for matching elements in the pdns server.

Kind: instance method of PowerdnsClient
Returns: object - search results

| Param | Type | Description | | --- | --- | --- | | search | Search | object with the query paramters |

Example

await pdns.search({
           query: 'example.com',
           max: 100,
           object_type: "zone"
       });

powerdnsClient.appendRecord(record) ⇒ boolean

Takes ONE record as object and appends it not replacing other records with the same name.

Kind: instance method of PowerdnsClient
Returns: boolean - boolean indicating the success of the operation

| Param | Type | Description | | --- | --- | --- | | record | Record | array containing the records to be appended |

Example

await pdns.appendRecord({
           name: "example.com",
           type: "A",
           ttl: 300,
           content: ['1.1.1.1','2.2.2.2']
       });

powerdnsClient.createCryptokey(zoneName, [cryptokey], [returnPrivateKey]) ⇒ Object

Creates a DNS Cryptokey and enables it for DNSSEC. If you want to import your own please read the original documentation and put it in the Cryptokey parameter.

Kind: instance method of PowerdnsClient
Returns: Object - on success the public key and info will be returned

| Param | Type | Default | Description | | --- | --- | --- | --- | | zoneName | string | | name of the zone/domain | | [cryptokey] | Cryptokey | {keytype: "ksk", active: true} | a Cryptokey | | [returnPrivateKey] | boolean | false | setting to true returns the private key with the answer |

Example

await pdns.createCryptokey("example.com");

powerdnsClient.getCryptoKeys(zoneName) ⇒ Array.<Cryptokey>

Get the crypotkeys for a given zone.

Kind: instance method of PowerdnsClient
Returns: Array.<Cryptokey> - on success the cryptokeys of the zone will be returned

| Param | Type | Description | | --- | --- | --- | | zoneName | string | name of the zone/domain |

Example

await pdns.getCryptoKeys("example.com");

powerdnsClient.deleteCryptoKey(zoneName, cryptokeyId) ⇒ boolean

Delete a cryptokey with specified id from specified zone.

Kind: instance method of PowerdnsClient
Returns: boolean - true on success

| Param | Type | Description | | --- | --- | --- | | zoneName | string | name of the zone/domain | | cryptokeyId | string | id of the cryptokey |

Example

await pdns.deleteCryptoKey("example.com",171);

powerdnsClient.setRecords(records) ⇒ Array

Takes records for single or mixed domains as array and sets them. If records exist it replaces them.

Kind: instance method of PowerdnsClient
Returns: Array - array of booleans indicating the success of each entry

| Param | Type | Description | | --- | --- | --- | | records | Records | array containing the records |

Example

await pdns.setRecords([{
           name: "example.com",
           type: "A",
           ttl: 300,
           content: ['1.1.1.1']
       },{
           name: "example.org",
           type: "A",
           ttl: 300,
           content: ['1.1.1.1']
       },{
           name: "example.me",
           type: "A",
           ttl: 300,
           content: ['1.1.1.1','2.2.2.2.']
       }]);

powerdnsClient.replaceRecords(find, replace, zone) ⇒ Number

Searches for records in a zone by comparing the RECORDS field NOT the name field. Replaces the found records with the replace string.

Kind: instance method of PowerdnsClient
Returns: Number - number of replaced entries

| Param | Type | Description | | --- | --- | --- | | find | String | string to search for | | replace | String | string to replace the find string with | | zone | String | zone to search through |

Example

await pdns.replaceRecords('1.1.1.1','2.2.2.2','example.com');

powerdnsClient.replaceRecordsGlobal(find, replace) ⇒ Number

Searches for records on the pdns server by comparing the RECORDS field NOT the name field. Replaces the found records with the replace string.

Kind: instance method of PowerdnsClient
Returns: Number - number of replaced entries

| Param | Type | Description | | --- | --- | --- | | find | String | string to search for | | replace | String | string to replace the find string with |

Example

await pdns.replaceRecordsGlobal('1.1.1.1','2.2.2.2');

powerdnsClient.findRecords(find, zone) ⇒ Array

Searches for records in a zone by comparing the RECORDS field NOT the name field

Kind: instance method of PowerdnsClient
Returns: Array - records matching the find string in the content field

| Param | Type | Description | | --- | --- | --- | | find | String | string to search for | | zone | String | zone to search through |

Example

await pdns.findRecords('1.1.1.1', 'example.com');

powerdnsClient.findRecordsGlobal(find) ⇒ Array

Searches for records on the pdns server by comparing the RECORDS field NOT the name field

Kind: instance method of PowerdnsClient
Returns: Array - records matching the find string in the content field

| Param | Type | Description | | --- | --- | --- | | find | String | string to search for |

Example

await pdns.findRecordsGlobal('1.1.1.1');

powerdnsClient.createAndSetupZone(zone) ⇒ Boolean

Higher level function for creating a zone with a custom soa record, name servers and dnssec/cryptokey. Skips creating zone and/or cryptokey if it exists.

Kind: instance method of PowerdnsClient
Returns: Boolean - true on success

| Param | Type | Description | | --- | --- | --- | | zone | Object | string to search for |

Example

await pdns.createAndSetupZone({
             domain: 'example.com',
             nameserver: ['ns1.paulisttoll.somedomain', 'ns2.paulisttoll.somedomain', 'ns3.paulisttoll.somedomain'],
             hostmasterEmail:'[email protected]',
        
    })

Cryptokey : object

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | keytype | 'ksk' | 'zsk' | 'csk' | The type of the key possible values are | | active | boolean | Whether or not the key is in active use | | published | boolean | Whether or not the DNSKEY record is published in the zone | | dnskey | string | The DNSKEY record for this key | | privateKey | string | The private key in ISC format | | algorithm | string | The name of the algorithm of the key, should be a mnemonic |

Search : object

Kind: global typedef
Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | query | string | | query to search for | | [max] | number | 10 | limits the ammount of returned values | | [object_type] | 'all' | 'zone' | 'record' | 'comment' | record | for what kind of pdns object to search |

Example

{query: 'example.com', max: 100, object_type: "zone"}

Records : Array.<Record>

Kind: global typedef
Example

[{
    name: "example.com",
    type: "A",
    ttl: 300,
    content: ['1.1.1.1', '8.8.8.8']
}, {
    name: "*.example.com",
    type: "A",
    ttl: 300,
    content: ['1.1.1.1', '8.8.8.8']
}]

Record : object

Kind: global typedef
Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | name | string | | key name of the record | | [type] | string | "'A'" | type of the record | | [ttl] | number | 3600 | time to live of the record | | content | Array | | value array with content of the record |

Example

{name: "example.com", type: "A", ttl: 300, content: ['1.1.1.1', '8.8.8.8']}