![]() | Warning |
---|---|
The Remote Backend is available since PowerDNS Authoritative Server 3.2. This backend is marked as experimental! |
Table A.14. Remote backend capabilities
Native | Yes |
Master | Yes* |
Slave | |
Superslave | |
Autoserial | Yes* |
DNSSEC | Yes* |
Multiple instances | Yes |
* If provided by the underlying backend.
This backend provides unix socket / pipe / http remoting for powerdns.
To compile this backend, you need to configure --with-modules="remote pipe", for now. If you want to use http connector, you need libcurl and use --enable-remotebackend-http.
The only configuration option for this backend is remote-connection-string. It comprises of two elements: type of backend, and parameters.
remote-connection-string=<type>:<param>=<value>,<param>=<value>...
You can pass as many parameters as you want. For unix and pipe backends, these are passed along to the remote end as initialization. See Section 15.3, “API”. Initialize is not called for http backend.
parameters: path, timeout (default 2000ms)
remote-connection-string=unix:path=/path/to/socket
parameters: command,timeout (default 2000ms)
remote-connection-string=unix:command=/path/to/executable,timeout=2000
parameters: url, url-suffix, timeout (default 2000)
HTTP backend tries to do RESTful requests to your server. See examples.
URL should not end with /, and url-suffix is optional, but if you define it, it's up to you to write the ".php" or ".json". Lack of dot causes lack of dot in URL. Timeout is divided by 1000 because libcurl only supports seconds, but this is given in milliseconds for consistency with other backends.
Unix and Pipe backend sends JSON formatted string to the remote end. Each JSON query has two sections, 'method' and 'parameters'.
HTTP backend calls methods based on URL and has parameters in the query string. Most calls are GET; see the methods listing for details.
You *must* always reply with JSON hash with at least one key, 'result'. This must be boolean false if the query failed. Otherwise it must conform to the expected result. For HTTP backend, to signal bare success, you can just reply with HTTP 200 OK, and omit any output. This will result in same outcome as sending {"result":true}.
You can optionally add 'log' array, each line in this array will be logged in PowerDNS.
Yes (except HTTP backend)
all parameters in connection string
true on success / false on failure
Called to initialize the backend. This is not called for HTTP backend. You should do your initializations here.
Query:
{"method":"initialize", "parameters":{"command":"/path/to/something", "timeout":"2000", "something":"else"}}
Response:
{"result":true}
Yes
qtype, qname, zone_id
remote, local, real-remote
array of <qtype,qname,content,ttl,domain_id,priority,scopeMask,auth>
domain_id, scopeMask and auth
This method is used to do the basic query. You can omit auth, but if you are using DNSSEC this can lead into trouble.
Query:
{"method":"lookup", "parameters":{"qtype":"ANY", "qname":"www.example.com", "remote":"192.168.0.24", "local":"192.168.0.1", "real-remote":"192.168.0.24", "zone-id":-1}}
Response:
{"result":[{"qtype":"A", "qname":"www.example.com", "content":"192.168.1.2", "ttl": 60}]}
Query:
GET /dnsapi/lookup/www.example.com/ANY HTTP/1.1 X-RemoteBackend-remote: 192.168.0.24 X-RemoteBackend-local: 192.168.0.1 X-RemoteBackend-real-remote: 192.168.0.24 X-RemoteBackend-zone-id: -1
Response:
HTTP/1.1 200 OK Content-Type: text/javascript; charset=utf-8 {"result":[{"qtype":"A", "qname":"www.example.com", "content":"192.168.1.2", "ttl": 60}]}
No (Gives AXFR support)
zonename, domain_id
domain_id
array of <qtype,qname,content,ttl,domain_id,priority,scopeMask,auth>
domain_id, scopeMask and auth
Lists all records for the zonename. If you are running dnssec, you should take care of setting auth to appropriate value, otherwise things can go wrong.
Query:
{"method":"list", "parameters":{"zonename":"example.com","domain_id":-1}}
Response (split into lines for ease of reading)
{"result":[ {"qtype":"SOA", "qname":"example.com", "content":"dns1.icann.org. hostmaster.icann.org. 2012081600 7200 3600 1209600 3600", "ttl": 3600}, {"qtype":"NS", "qname":"example.com", "content":"ns1.example.com", "ttl": 60}, {"qtype":"MX", "qname":"example.com", "content":"mx1.example.com.", "ttl": 60, "priority":10}, {"qtype":"A", "qname":"www.example.com", "content":"192.168.1.2", "ttl": 60}, {"qtype":"A", "qname":"ns1.example.com", "content":"192.168.0.2", "ttl": 60}, {"qtype":"A", "qname":"mx1.example.com", "content":"192.168.0.3", "ttl": 60} ]}
Query:
GET /dnsapi/list/example.com HTTP/1.1 X-RemoteBackend-domain-id: -1
Response:
HTTP/1.1 200 OK Content-Type: text/javascript; charset=utf-8 {"result":[{"qtype":"SOA", "qname":"example.com", "content":"dns1.icann.org. hostmaster.icann.org. 2012081600 7200 3600 1209600 3600", "ttl": 3600},{"qtype":"NS", "qname":"example.com", "content":"ns1.example.com", "ttl": 60},{"qtype":"MX", "qname":"example.com", "content":"mx1.example.com.", "ttl": 60, "priority":10},{"qtype":"A", "qname":"www.example.com", "content":"192.168.1.2", "ttl": 60},{"qtype":"A", "qname":"ns1.example.com", "content":"192.168.0.2", "ttl": 60},{"qtype":"A", "qname":"mx1.example.com", "content":"192.168.0.3", "ttl": 60}]}
for NSEC/NSEC3 non-narrow
id, qname
before, after
Asks the names before and after qname. qname is given without dots or domain part. The query can also be hashed. Care must be taken to handle wrap-around when qname is first or last in the ordered list. Do not return nil for either one.
Query:
{"method":"getbeforeandafternamesabsolute", "params":{"id":0,"qname":"www.example.com"}}
Response:
{”result":{"before":"ns1","after":""}}
Query:
/dnsapi/getbeforeandafternamesabsolute/0/www.example.com
Response:
{”result":{"before":"ns1","after":""}}
No
name, kind
array of strings
Returns the value(s) for variable kind for zone name. Most commonly it's one of NSEC3PARAM, PRESIGNED, SOA-EDIT. Can be others, too. You *must* always return something, if there are no values, you shall return empty array or false.
Query:
{"method":"getdomainmetadata", "parameters":{"name":"example.com","kind":"PRESIGNED"}}
Response:
{"result":["NO"]}
Query:
GET /dnsapi/getdomainmetadata/example.com/PRESIGNED HTTP/1.1
Response:
HTTP/1.1 200 OK Content-Type: text/javascript; charset=utf-8 {"result":["NO"]}
No
name, kind, value
true on success, false on failure
Replaces the value(s) on domain name for variable kind to string(s) on array value. The old value is discarded. Value can be an empty array, which can be interprepted as deletion request.
Query:
{"method":"setdomainmetadata","parameters":{"name":"example.com","kind":"PRESIGNED","value":["YES"]}}
Response:
{"result":true}
Query:
POST /dnsapi/setdomainmetadata/example.com/PRESIGNED HTTP/1.1 Content-Type: application/x-www-form-urlencoded Content-Length: 12 value1=YES&
Response:
HTTP/1.1 200 OK Content-Type: text/javascript; charset=utf-8 {"result":true}
for DNSSEC
name, kind
array of <id, flags, active, content>
Retrieves any keys of kind. The id, flags are unsigned integers, and active is boolean. Content must be valid key record in format that PowerDNS understands. You are encouraged to implement the section called “Method: addDomainKey”, as you can use Section 5, “'pdnssec' for PowerDNSSEC command & control” to provision keys.
Query:
{"method":"getdomainkeys","parameters":{"name":"example.com","kind":0}}
Response:
{"result":[{"id":1,"flags":256,"active":true,"content":"Private-key-format: v1.2 Algorithm: 8 (RSASHA256) Modulus: r+vmQll38ndQqNSCx9eqRBUbSOLcH4PZFX824sGhY2NSQChqt1G4ZfndzRwgjXMUwiE7GkkqU2Vbt/g4iP67V/+MYecMV9YHkCRnEzb47nBXvs9JCf8AHMCnma567GQjPECh4HevPE9wmcOfpy/u7UN1oHKSKRWuZJadUwcjbp8= PublicExponent: AQAB PrivateExponent: CY93UtVnOM6wrFJZ+qA9+Yx+p5yk0CSi0Q7c+/6EVMuABQ5gNyTuu0j65lU3X81bwUk2wHPx6smfgoVDRAW5jjO4jgIFV6nE4inzk5YQKycQSL8YG3Nm9GciLFya1KUXs81sHsQpkvK7MNaSbvkaHZQ6iv16bZ4t73Wascwa/E= Prime1: 6a165cIC0nNsGlTW/s2jRu7idq5+U203iE1HzSIddmWgx5KIKE/s3I+pwfmXYRUmq+4H9ASd/Yot1lSYW98szw== Prime2: wLoCPKxxnuxDx6/9IKOYz8t9ZNLY74iCeQ85koqvTctkFmB9jpOUHTU9BhecaFY2euP9CuHV7z3PLtCoO8s1MQ== Exponent1: CuzJaiR/7UboLvL4ekEy+QYCIHpX/Z6FkiHK0ZRevEJUGgCHzRqvgEBXN3Jr2WYbwL4IMShmGoxzSCn8VY9BkQ== Exponent2: LDR9/tyu0vzuLwcommit 20B22FzNdd5rFF2wAQTQ0yF/3Baj5NAi9w84l0u07KgKQZX4g0N8qUyypnU5YDyzc6ZoagQ== Coefficient: 6S0vhIQITWzqfQSLj+wwRzs6qCvJckHb1+SD1XpwYjSgMTEUlZhf96m8WiaE1/fIt4Zl2PC3fF7YIBoFLln22w=="}]}
Query:
GET /dnsapi/getdomainkeys/example.com/0 HTTP/1.1
Response:
HTTP/1.1 200 OK Content-Type: text/javascript; charset=utf-8 {"result":[{"id":1,"flags":256,"active":true,"content":"Private-key-format: v1.2 Algorithm: 8 (RSASHA256) Modulus: r+vmQll38ndQqNSCx9eqRBUbSOLcH4PZFX824sGhY2NSQChqt1G4ZfndzRwgjXMUwiE7GkkqU2Vbt/g4iP67V/+MYecMV9YHkCRnEzb47nBXvs9JCf8AHMCnma567GQjPECh4HevPE9wmcOfpy/u7UN1oHKSKRWuZJadUwcjbp8= PublicExponent: AQAB PrivateExponent: CY93UtVnOM6wrFJZ+qA9+Yx+p5yk0CSi0Q7c+/6EVMuABQ5gNyTuu0j65lU3X81bwUk2wHPx6smfgoVDRAW5jjO4jgIFV6nE4inzk5YQKycQSL8YG3Nm9GciLFya1KUXs81sHsQpkvK7MNaSbvkaHZQ6iv16bZ4t73Wascwa/E= Prime1: 6a165cIC0nNsGlTW/s2jRu7idq5+U203iE1HzSIddmWgx5KIKE/s3I+pwfmXYRUmq+4H9ASd/Yot1lSYW98szw== Prime2: wLoCPKxxnuxDx6/9IKOYz8t9ZNLY74iCeQ85koqvTctkFmB9jpOUHTU9BhecaFY2euP9CuHV7z3PLtCoO8s1MQ== Exponent1: CuzJaiR/7UboLvL4ekEy+QYCIHpX/Z6FkiHK0ZRevEJUGgCHzRqvgEBXN3Jr2WYbwL4IMShmGoxzSCn8VY9BkQ== Exponent2: LDR9/tyu0vzuLwcommit 20B22FzNdd5rFF2wAQTQ0yF/3Baj5NAi9w84l0u07KgKQZX4g0N8qUyypnU5YDyzc6ZoagQ== Coefficient: 6S0vhIQITWzqfQSLj+wwRzs6qCvJckHb1+SD1XpwYjSgMTEUlZhf96m8WiaE1/fIt4Zl2PC3fF7YIBoFLln22w=="}]}
No
name, key=<flags,active,content>
true for success, false for failure
Adds key into local storage. See the section called “Method: getDomainKeys” for more information.
Query:
{"method":"adddomainkey", "parameters":{"key":{"id":1,"flags":256,"active":true,"content":"Private-key-format: v1.2 Algorithm: 8 (RSASHA256) Modulus: r+vmQll38ndQqNSCx9eqRBUbSOLcH4PZFX824sGhY2NSQChqt1G4ZfndzRwgjXMUwiE7GkkqU2Vbt/g4iP67V/+MYecMV9YHkCRnEzb47nBXvs9JCf8AHMCnma567GQjPECh4HevPE9wmcOfpy/u7UN1oHKSKRWuZJadUwcjbp8= PublicExponent: AQAB PrivateExponent: CY93UtVnOM6wrFJZ+qA9+Yx+p5yk0CSi0Q7c+/6EVMuABQ5gNyTuu0j65lU3X81bwUk2wHPx6smfgoVDRAW5jjO4jgIFV6nE4inzk5YQKycQSL8YG3Nm9GciLFya1KUXs81sHsQpkvK7MNaSbvkaHZQ6iv16bZ4t73Wascwa/E= Prime1: 6a165cIC0nNsGlTW/s2jRu7idq5+U203iE1HzSIddmWgx5KIKE/s3I+pwfmXYRUmq+4H9ASd/Yot1lSYW98szw== Prime2: wLoCPKxxnuxDx6/9IKOYz8t9ZNLY74iCeQ85koqvTctkFmB9jpOUHTU9BhecaFY2euP9CuHV7z3PLtCoO8s1MQ== Exponent1: CuzJaiR/7UboLvL4ekEy+QYCIHpX/Z6FkiHK0ZRevEJUGgCHzRqvgEBXN3Jr2WYbwL4IMShmGoxzSCn8VY9BkQ== Exponent2: LDR9/tyu0vzuLwcommit 20B22FzNdd5rFF2wAQTQ0yF/3Baj5NAi9w84l0u07KgKQZX4g0N8qUyypnU5YDyzc6ZoagQ== Coefficient: 6S0vhIQITWzqfQSLj+wwRzs6qCvJckHb1+SD1XpwYjSgMTEUlZhf96m8WiaE1/fIt4Zl2PC3fF7YIBoFLln22w=="}}}
Response:
{"result":true}
Query:
POST /dnsapi/adddomainkey/example.com Content-Type: application/x-www-form-urlencoded Content-Length: 965 flags=256&active=1&content=Private-key-format: v1.2 Algorithm: 8 (RSASHA256) Modulus: r+vmQll38ndQqNSCx9eqRBUbSOLcH4PZFX824sGhY2NSQChqt1G4ZfndzRwgjXMUwiE7GkkqU2Vbt/g4iP67V/+MYecMV9YHkCRnEzb47nBXvs9JCf8AHMCnma567GQjPECh4HevPE9wmcOfpy/u7UN1oHKSKRWuZJadUwcjbp8= PublicExponent: AQAB PrivateExponent: CY93UtVnOM6wrFJZ+qA9+Yx+p5yk0CSi0Q7c+/6EVMuABQ5gNyTuu0j65lU3X81bwUk2wHPx6smfgoVDRAW5jjO4jgIFV6nE4inzk5YQKycQSL8YG3Nm9GciLFya1KUXs81sHsQpkvK7MNaSbvkaHZQ6iv16bZ4t73Wascwa/E= Prime1: 6a165cIC0nNsGlTW/s2jRu7idq5+U203iE1HzSIddmWgx5KIKE/s3I+pwfmXYRUmq+4H9ASd/Yot1lSYW98szw== Prime2: wLoCPKxxnuxDx6/9IKOYz8t9ZNLY74iCeQ85koqvTctkFmB9jpOUHTU9BhecaFY2euP9CuHV7z3PLtCoO8s1MQ== Exponent1: CuzJaiR/7UboLvL4ekEy+QYCIHpX/Z6FkiHK0ZRevEJUGgCHzRqvgEBXN3Jr2WYbwL4IMShmGoxzSCn8VY9BkQ== Exponent2: LDR9/tyu0vzuLwcommit 20B22FzNdd5rFF2wAQTQ0yF/3Baj5NAi9w84l0u07KgKQZX4g0N8qUyypnU5YDyzc6ZoagQ== Coefficient: 6S0vhIQITWzqfQSLj+wwRzs6qCvJckHb1+SD1XpwYjSgMTEUlZhf96m8WiaE1/fIt4Zl2PC3fF7YIBoFLln22w==
Response:
HTTP/1.1 200 OK Content-Type: text/javascript; charset=utf-8 {"result":true}
No
name, id
true for success, false for failure
Removes key id from domain name.
Query:
{"method":"removedomainkey","parameters":"{"name":"example.com","id":1}}
Response:
{"result":true}
Query:
DELETE /dnsapi/removedomainkey/example.com/1 HTTP/1.1
Response:
HTTP/1.1 200 OK Content-Type: text/javascript; charset=utf-8 {"result":true}
No
name, id
true for success, false for failure
Activates key id for domain name.
Query:
{"method":"activatedomainkey","parameters":{"name":"example.com","id":1}}
Response:
{"result":true}
Query:
POST /dnsapi/activatedomainkey/example.com/1 HTTP/1.1
Response:
HTTP/1.1 200 OK Content-Type: text/javascript; utf-8 {"result": true}
No
name, id
true for success, false for failure
Deactivates key id for domain name.
Query:
{"method":"deactivatedomainkey","parameters":{"name":"example.com","id":1}}
Response:
{"result": true}
Query:
POST /dnsapi/deactivatedomainkey/example.com/1 HTTP/1.1
Response:
HTTP/1.1 200 OK Content-Type: text/javascript; utf-8 {"result": true}
No
name
algorithm, content
Retrieves the key needed to sign AXFR.
Query:
{"method":"gettsigkey","parameters":{"name":"example.com"}}
Response:
{"result":{"algorithm":"hmac-md5","content:"kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys="}}
Query:
GET /dnsapi/gettsigkey/example.com
Response:
HTTP/1.1 200 OK Content-Type: text/javascript; charset=utf-8 {"result":{"algorithm":"hmac-md5","content:"kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys="}}
No
name
zone
serial, kind, id, notified_serial, last_check, masters
Retrieves information about given domain from the backend. If your return value has no zone attribute, the backend will signal error. Everything else will default to something. Default values: serial:0, kind:NATIVE, id:-1, notified_serial:-1, last_check:0, masters: []. Masters, if present, must be array of strings.
Query:
{"method":"getdomaininfo","parameters":{"name":"example.com"}}
Response:
{"result":{id:1,"zone":"example.com","kind":"NATIVE","serial":2002010100}}
Query:
GET /dnsapi/getdomaininfo/example.com HTTP/1.1
Response:
HTTP/1.1 200 OK content-Type: text/javascript: charset=utf-8 {"result":{id:1,"zone":"example.com","kind":"NATIVE","serial":2002010100}}
No
id, serial
true for success, false for failure
Updates last notified serial for the domain id. Any errors are ignored.
Query:
{"method":"setnotified","parameters":{"id":1,"serial":2002010100}}
Response:
{"result":true}
Query:
POST /dnsapi/setnotified/1 Content-Type: application/x-www-form-urlencoded Content-Length: 17 serial=2002010100
Response:
HTTP/1.1 200 OK Content-Type: text/javascript; charset=utf-8 {"result":true}
Scenario: SOA lookup via pipe or unix
Query:
{ "method": "lookup", "parameters": { "qname": "example.com", "qtype": "SOA", "zone_id": "-1" } }
Reply:
{ "result": [ { "qtype": "SOA", "qname": "example.com", "content": "dns1.icann.org. hostmaster.icann.org. 2012080849 7200 3600 1209600 3600", "ttl": 3600, "priority": 0, "domain_id": -1 } ] }
Scenario: SOA lookup via HTTP backend
Query:
/dns/lookup/example.com/SOA
Reply:
{ "result": [ { "qtype": "SOA", "qname": "example.com", "content": "dns1.icann.org. hostmaster.icann.org. 2012080849 7200 3600 1209600 3600", "ttl": 3600, "priority": 0, "domain_id": -1 } ] }