From: Aki Tuomi Date: Wed, 5 Jun 2013 11:58:54 +0000 (+0300) Subject: Documentation for new features X-Git-Tag: rec-3.6.0-rc1~698^2~4 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=008174bc98ad3cdfdf13016badb9b9ffa23a7b5b;p=pdns Documentation for new features --- diff --git a/pdns/docs/pdns.xml b/pdns/docs/pdns.xml index 6ebe4f83b..0ae2d347c 100644 --- a/pdns/docs/pdns.xml +++ b/pdns/docs/pdns.xml @@ -19055,6 +19055,8 @@ record building scripts on his Important notices + Please do not use remotebackend shipped before version 3.3. This version has severe bug that can crash the entire process. Compiling To compile this backend, you need to configure --with-modules="remote pipe", for @@ -19063,7 +19065,7 @@ record building scripts on his Usage - The only configuration option for this backend is remote-connection-string. It comprises of two elements: type of backend, and parameters. + The only configuration optionss for backend are remote-connection-string and remote-dnssec. @@ -19099,12 +19101,16 @@ remote-connection-string=unix:command=/path/to/executable,timeout=2000 - HTTP backend + HTTP backend - parameters: url, url-suffix, timeout (default 2000) + parameters: url, url-suffix, post, post_json, cafile, capath, timeout (default 2000) - HTTP backend tries to do RESTful requests to your server. See examples. + HTTP backend tries to do RESTful requests to your server. See examples. You can also + use post to change behaviour so that it will send POST request to url/method + url_suffix + with parameters=json-formatted-parameters. If you use post and post_json, it will POST + url with text/javascript containing JSON formatted RPC request, just like for pipe and unix. + You can use '1', 'yes', 'on' or 'true' to turn these features on. URL should not end with /, and url-suffix is optional, but if you define it, it's @@ -19112,6 +19118,10 @@ remote-connection-string=unix:command=/path/to/executable,timeout=2000 URL. Timeout is divided by 1000 because libcurl only supports seconds, but this is given in milliseconds for consistency with other backends. + + You can use HTTPS requests. If cafile and capath is left empty, remote SSL certificate is not checked. + HTTP Authentication is not supported. SSL support requires that your cURL is compiled with it. + @@ -19308,7 +19318,7 @@ to appropriate value, otherwise things can go wrong. Query: -GET /dnsapi/list/example.com HTTP/1.1 +GET /dnsapi/list/-1/example.com HTTP/1.1 X-RemoteBackend-domain-id: -1 @@ -19344,7 +19354,7 @@ Content-Type: text/javascript; charset=utf-8 Description 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 +will be hashed when using NSEC3. 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. @@ -19496,7 +19506,7 @@ POST /dnsapi/setdomainmetadata/example.com/PRESIGNED HTTP/1.1 Content-Type: application/x-www-form-urlencoded Content-Length: 12 -value1=YES& +value[]=YES& @@ -20041,6 +20051,656 @@ Content-Type: text/javascript; charset=utf-8 + +Method: superMasterBackend + + + Mandatory: + No + + + Parameters: + ip,domain,nsset,account + + + Reply: + true for success, false for failure. can also return account=>name of account + + + Description + +Creates new domain with given record(s) as master servers. IP address is the address where notify is received from. nsset is array of NS resource records. + + + + Example JSON/RPC: + + + Query: + +{"method":"superMasterBackend","parameters":{"ip":"10.0.0.1","domain":"example.com","nsset":[{"qtype":"NS","qname":"example.com","qclass":1,"content":"ns1.example.com","ttl":300,"priority":0,"auth":true},{"qtype":"NS","qname":"example.com","qclass":1,"content":"ns2.example.com","ttl":300,"priority":0,"auth":true}]}} + + + + Response: + +{"result":true} + + Alternative response: + +{"result":{"account":"my account"}} + + + + + + Example HTTP/RPC: + + + Query: + +POST /dnsapi/supermasterbackend/10.0.0.1/example.com +Content-Type: application/x-www-form-urlencoded +Content-Length: 317 + +nsset[1][qtype]=NS&nsset[1][qname]=example.com&nsset[1][qclass]=1&nsset[1][content]=ns1.example.com&nsset[1][ttl]=300&nsset[1][priority]=0&nsset[1][auth]=true&nsset[2][qtype]=NS&nsset[2][qname]=example.com&nsset[2][qclass]=1&nsset[2][content]=ns2.example.com&nsset[2][ttl]=300&nsset[2][priority]=0&nsset[2][auth]=true + + + + Response: + +HTTP/1.1 200 OK +Content-Type: text/javascript; charset=utf-8 + +{"result":true} + + Alternative response + +HTTP/1.1 200 OK +Content-Type: text/javascript; charset=utf-8 + +{"result":{"account":"my account}} + + + + + + + + +Method: createSlaveDomain + + + Mandatory: + No + + + Parameters: + ip, domain + + + Optional parameters: + account + + + Reply: + true for success, false for failure + + + Description + +Creates new domain. This method is called when NOTIFY is received and you are superslaving. + + + + Example JSON/RPC: + + + Query: + +{"method":"createSlaveDomain","parameters":{"ip":"10.0.0.1","domain":"pirate.unit.test"}} + + + + Response: + +{"result":true} + + + + + + Example HTTP/RPC: + + + Query: + +POST /dnsapi/createslavedomain/10.0.0.1/pirate.unit.test +Content-Type: application/x-www-form-urlencoded +Content-Length: 0 + + + + Response: + +HTTP/1.1 200 OK +Content-Type: text/javascript; charset=utf-8 + +{"result":true} + + + + + + + +Method: replaceRRSet + + + Mandatory: + No + + + Parameters: + domain_id, qname, qtype, rrset + + + Reply: + true for success, false for failure + + + Description + +This method replaces a given resource record with new set. The new qtype can be different from the old. + + + + Example JSON/RPC: + + + Query: + +{"method":"replaceRRSet","parameters":{"domain_id":2,"qname":"replace.example.com","qtype":"A","trxid":1370416133,"rrset":[{"qtype":"A","qname":"replace.example.com","qclass":1,"content":"1.1.1.1","ttl":300,"priority":0,"auth":true}]}} + + + + Response: + +{"result":true} + + + + + + Example HTTP/RPC: + + + Query: + +POST /dnsapi/replacerrset/2/replace.example.com/A +Content-Type: application/x-www-form-urlencoded +Content-Length: 135 + +trxid=1370416133&rrset[qtype]=A&rrset[qname]=replace.example.com&rrset[qclass]=1&rrset[content]=1.1.1.1&rrset[priority]=0&rrset[auth]=1 + + + + Response: + +HTTP/1.1 200 OK +Content-Type: text/javascript; charset=utf-8 + +{"result":true} + + + + + + + +Method: feedRecord + + + Mandatory: + No + + + Parameters: rr, trxid + + + + Reply: + true for success, false for failure + + + Description + +Asks to feed new record into system. If startTransaction was called, trxId identifies a transaction. It is not always called by PowerDNS. + + + + Example JSON/RPC: + + + Query: + +{"method":"feedRecord","parameters":{"rr":{"qtype":"A","qname":"replace.example.com","qclass":1,"content":"127.0.0.1","ttl":300,"priority":0,"auth":true},"trxid":1370416133}} + + + + Response: + +{"result":true} + + + + + + Example HTTP/RPC: + + + Query: + +POST /dnsapi/feedrecord/1370416133 +Content-Type: application/x-www-form-urlencoded +Content-Length: 117 + +rr[qtype]=A&rr[qname]=replace.example.com&rr[qclass]=1&rr[content]=127.0.0.1&rr[ttl]=300&rr[priority]=0&rr[auth]=true + + + + Response: + +HTTP/1.1 200 OK +Content-Type: text/javascript; charset=utf-8 + +{"result":true} + + + + + + + +Method: feedEnts + + + Mandatory: + No + + + Parameters:nonterm, trxid + + + + Reply: + true for success, false for failure + + + Description + +This method is used by pdnssec rectify-zone to populate missing non-terminals. This is used when you have, say, record like _sip._upd.example.com, but no _udp.example.com. PowerDNS requires that there exists a non-terminal in between, and this instructs you to add one. If startTransaction is called, trxid identifies a transaction. + + + + Example JSON/RPC: + + + Query: + +{"method":"feedEnts","parameters":{"domain_id":2,"trxid":1370416133,"nonterm":["_sip._udp","_udp"]}} + + + + Response: + +{"result":true} + + + + + + Example HTTP/RPC: + + + Query: + +POST /dnsapi/feedents/2 +Content-Type: application/x-www-form-urlencoded +Content-Length: 50 + +trxid=1370416133&nonterm[]=_udp&nonterm[]=_sip.udp + + + + Response: + +HTTP/1.1 200 OK +Content-Type: text/javascript; charset=utf-8 + +{"result":true} + + + + + + + +Method: feedEnts3 + + + Mandatory: + No + + + Parameters:trxid, domain_id, domain, times, salt, narrow, nonterm + + + + Reply: + true for success, false for failure + + + Description + +Same as , but provides NSEC3 hashing parameters. Note that salt is BYTE value, and can be non-readable text. + + + + Example JSON/RPC: + + + Query: + +{"method":"feedEnts3","parameters":{"domain_id":2,"domain":"example.com","times":1,"salt":"9642","narrow":false,"trxid":1370416356,"nonterm":["_sip._udp","_udp"]}} + + + + Response: + +{"result":true} + + + + + + Example HTTP/RPC: + + + Query: + +POST /dnsapi/2/example.com +Content-Type: application/x-www-form-urlencoded +Content-Length: 78 + +trxid=1370416356&times=1&salt=9642&narrow=0&nonterm[]=_sip._udp&nonterm[]=_udp + + + + Response: + +HTTP/1.1 200 OK +Content-Type: text/javascript; charset=utf-8 + +{"result":true} + + + + + + + +Method: startTransaction + + + Mandatory: + No + + + Parameters:domain_id, domain, trxid + + + + Reply: + true for success, false for failure + + + Description + +Starts a new transaction. Transaction ID is chosen for you. Used to identify f.ex. AXFR transfer. + + + + Example JSON/RPC: + + + Query: + +{"method":"startTransaction","parameters":{"trxid":1234,"domain_id":1,"domain":"example.com"}} + + + + Response: + +{"result":true} + + + + + + Example HTTP/RPC: + + + Query: + +POST /dnsapi/starttransaction/1/example.com +Content-Type: application/x-www-form-urlencoded +Content-Length: 10 + +trxid=1234 + + + + Response: + +HTTP/1.1 200 OK +Content-Type: text/javascript; charset=utf-8 + +{"result":true} + + + + + + + +Method: commitTransaction + + + Mandatory: + No + + + Parameters: + trxid + + + Reply: + true for success, false for failure + + + Description + +Signals successful transfer and asks to commit data into permanent storage. + + + + Example JSON/RPC: + + + Query: + +{"method":"commitTransaction","parameters":{"trxid":1234}} + + + + Response: + +{"result":true} + + + + + + Example HTTP/RPC: + + + Query: + +POST /dnsapi/committransaction/1234 +Content-Type: application/x-www-form-urlencoded +Content-Length: 0 + + + + Response: + +HTTP/1.1 200 OK +Content-Type: text/javascript; charset=utf-8 + +{"result":true} + + + + + + + +Method: abortTransaction + + + Mandatory: + No + + + Parameters: + trxid + + + Reply: + true for success, false for failure + + + Description + +Signals failed transaction, and that you should rollback any changes. + + + + Example JSON/RPC: + + + Query: + +{"method":"abortTransaction","parameters":{"trxid":1234}} + + + + Response: + +{"result":true} + + + + + + Example HTTP/RPC: + + + Query: + +POST /dnsapi/aborttransaction/1234 +Content-Type: application/x-www-form-urlencoded +Content-Length: 0 + + + + Response: + +HTTP/1.1 200 OK +Content-Type: text/javascript; charset=utf-8 + +{"result":true} + + + + + + + +Method: calculateSOASerial + + + Mandatory: + No + + + Parameters: + domain,sd + + + Reply: + true for success, false for failure + + + Description + +Asks you to calculate a new serial based on the given data and update the serial. + + + + Example JSON/RPC: + + + Query: +{"method":"calculateSOASerial","parameters":{"domain":"unit.test","sd":{"qname":"unit.test","nameserver":"ns.unit.test","hostmaster":"hostmaster.unit.test","ttl":300,"serial":1,"refresh":2,"retry":3,"expire":4,"default_ttl":5,"domain_id":-1,"scopeMask":0}}} + + + + Response: + +{"result":2013060501} + + + + + + Example HTTP/RPC: + + + Query: + +POST /dnsapi/calculatesoaserial/unit.test +Content-Type: application/x-www-form-urlencoded +Content-Length: 198 + +sd[qname]=unit.test&sd[nameserver]=ns.unit.test&sd[hostmaster]=hostmaster.unit.test&sd[ttl]=300&sd[serial]=1&sd[refresh]=2&sd[retry]=3&sd[expire]=4&sd[default_ttl]=5&sd[domain_id]=-1&sd[scopemask]=0 + + + + Response: + +HTTP/1.1 200 OK +Content-Type: text/javascript; charset=utf-8 + +{"result":2013060501} + + + + + + +