From: Peter van Dijk Date: Fri, 5 Oct 2012 08:40:49 +0000 (+0000) Subject: add initial remotebackend docs X-Git-Tag: auth-3.2-rc1~126 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=62a409982a71458c02dcdc0784abb621b27d03e7;p=thirdparty%2Fpdns.git add initial remotebackend docs git-svn-id: svn://svn.powerdns.com/pdns/trunk/pdns@2756 d19b8d6e-7fed-0310-83ef-9ca221ded41b --- diff --git a/pdns/docs/pdns.xml b/pdns/docs/pdns.xml index 8eba0259a8..8697dcc9d8 100644 --- a/pdns/docs/pdns.xml +++ b/pdns/docs/pdns.xml @@ -17369,7 +17369,231 @@ record building scripts on his tinycdb version 0.77. - + + Remote Backend + + + + The Remote Backend is available since PowerDNS Authoritative Server 3.2. This backend is marked as experimental! + + + + + Remote backend capabilities + + + NativeYes + Master + Slave + Superslave + Autoserial + DNSSECYes + Multiple instancesYes + + +
+ + This backend provides unix socket / pipe / http remoting for powerdns. + + Compiling + + Install following libraries for dependencies: libjsoncpp, libcurl. To compile this backend, you need to configure --with-modules="remote pipe", for now. + + + Usage + + 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 . + + + Unix backend + + parameters: path + + + +remote-connection-string=unix:path=/path/to/socket + + + + + Pipe backend + + parameters: command + + + +remote-connection-string=unix:command=/path/to/executable + + + + + + HTTP backend + + parameters: url, url-suffix + + + 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. + + + + + API + Queries + + 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. + The calls are always GET calls. + + + Replies + + You *must* always reply with JSON hash with at least one key, 'result'. This + must be false if the query failed. Otherwise it must conform to the expected + result. + + + You can optionally add 'log' array, each line in this array will be logged in + PowerDNS. + + + Methods + +The following methods are used: + + + +Method: lookup +Parameters: qtype, domain, remote, local, real-remote, zone_id +Reply: array of <qtype,qname,content,ttl,domaind_id,priority,scopeMask> +Optional values: domain_id and scopeMask + +Method: list +Parameters: zonename, domain_id +Reply: array of <qtype,qname,content,ttl,domaind_id,priority,scopeMask> +Optional values: domain_id and scopeMask + +Method: getBeforeAndAfterNamesAbsolute +Parameters: id, qname +Reply: unhashed, before, after + +Method: getBeforeAndAfterNames +Parameters: id, zonename, qname +Reply: before, after + +Method: getDomainMetadata +Parameters: name, kind +Reply: array of strings + +Method: getDomainKeys +Parameters: name, kind +Reply: array of domain keys <id,flags,active,content> + +Method: getTSIGKey +Parameters: name +Reply: algorithm, content + +Method: setDomainMetadata +Parameters: name, kind, value +Reply: true or false + +Method: addDomainKey +Parameters: flags, active, content +Reply: id-of-key + +Method: remoteDomainKey +Parameters: name, id +Reply: true or false + +Method: activateDomainKey +Parameters: name, id +Reply: true or false + +Method: deactivateDomainKey +Parameters: name, id +Reply: true or false + + + + + +Examples + + 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 + } + ] +} + + + + PDNS internals