@firstdorsal/powerdns-api

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

Usage no npm install needed!

<script type="module">
  import firstdorsalPowerdnsApi from 'https://cdn.skypack.dev/@firstdorsal/powerdns-api';
</script>

README

Powerdns API

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

npm NPM Snyk Vulnerabilities for npm package Website Website

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 xl9jthv_7bvgakv9o9wg0jabn2ylm91xxrzzgt0e@y.gy 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

powerdns-api

Typedefs

Cryptokey : object
Search : object
Records : Array.<Record>
Record : object

powerdns-api

powerdns-api.PowerdnsClient

Class representing the powerdns client

Kind: static class of powerdns-api

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:'hostmaster@paulisttoll.somedomain',
        
    })

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']}