docs/backends/remote.rst

   1 Remote Backend
   2 ==============
   3
   4 * Native: Yes
   5 * Master: Yes\*
   6 * Slave: Yes\*
   7 * Superslave: Yes\*
   8 * DNSSEC: Yes\*
   9 * Zone caching: Yes\*
  10 * Multiple instances: Yes
  11
  12 \* If provided by the responder (your script).
  13
  14 This backend provides Unix socket, Pipe, HTTP and ZeroMQ remoting for
  15 powerdns. You should think this as normal RPC thin client, which
  16 converts native C++ calls into JSON/RPC and passes them to you via
  17 connector.
  18
  19 Important notices
  20 -----------------
  21
  22 Please do not use remotebackend shipped before version 3.3. This version
  23 has severe bug that can crash the entire process.
  24
  25 There is a breaking change on v4.0 and later. Before version 4.0, the
  26 DNS names passed in queries were without trailing dot, after version 4.0
  27 the DNS names are sent with trailing dot. F.ex. example.org is now sent
  28 as example.org.
  29
  30 In some (broken) network setups, the IP addresses provided in the
  31 request (when this is an IPv6 address) may be suffixed with a ``%`` and
  32 the name of the network interface (e.g. ``%eth1``). Keep this in mind
  33 when checking the IP addresses.
  34
  35 Compiling
  36 ---------
  37
  38 To compile this backend, you need to configure
  39 ``--with-modules="remote"``.
  40
  41 For versions prior to 3.4.0, if you want to use http connector, you need
  42 libcurl and use ``--enable-remotebackend-http``.
  43
  44 If you want to use ZeroMQ connector, you need libzmq-dev or libzmq3-dev
  45 and use ``--enable-remotebackend-zeromq``.
  46
  47 Usage
  48 -----
  49
  50 The only configuration options for backend are remote-connection-string
  51 and remote-dnssec.
  52
  53 .. code-block:: ini
  54
  55     remote-connection-string=<type>:<param>=<value>,<param>=<value>...
  56
  57 You can pass as many parameters as you want. For unix and pipe
  58 connectors, these are passed along to the remote end as initialization.
  59 See :ref:`remote-api`. Initialize is not called for http connector.
  60
  61 Unix connector
  62 ^^^^^^^^^^^^^^
  63
  64 parameters: path, timeout (default 2000ms)
  65
  66 .. code-block:: ini
  67
  68     remote-connection-string=unix:path=/path/to/socket
  69
  70 Pipe connector
  71 ^^^^^^^^^^^^^^
  72
  73 parameters: command,timeout (default 2000ms)
  74
  75 .. code-block:: ini
  76
  77     remote-connection-string=pipe:command=/path/to/executable,timeout=2000
  78
  79 HTTP connector
  80 ^^^^^^^^^^^^^^
  81
  82 parameters: url, url-suffix, post, post_json, timeout (default 2000ms)
  83
  84 .. code-block:: ini
  85
  86     remote-connection-string=http:url=http://localhost:63636/dns,url-suffix=.php
  87
  88 HTTP connector tries to do RESTful requests to your server. See
  89 examples. You can also use post to change behaviour so that it will send
  90 POST request to url/method + url_suffix with
  91 parameters=json-formatted-parameters. If you use post and post_json, it
  92 will POST url with text/javascript containing JSON formatted RPC
  93 request, just like for pipe and unix. You can use '1', 'yes', 'on' or
  94 'true' to turn these features on.
  95
  96 URL should not end with /, and url-suffix is optional, but if you define
  97 it, it's up to you to write the ".php" or ".json". Lack of dot causes
  98 lack of dot in URL. Timeout is divided by 1000 because libcurl only
  99 supports seconds, but this is given in milliseconds for consistency with
 100 other connectors.
 101
 102 HTTPS is not supported, `stunnel <https://www.stunnel.org>`__ is the
 103 suggested workaround. HTTP Authentication is not supported.
 104
 105 ZeroMQ connector
 106 ^^^^^^^^^^^^^^^^
 107
 108 parameters: endpoint, timeout (default 2000ms)
 109
 110 .. code-block:: ini
 111
 112     remote-connection-string=zeromq:endpoint=ipc:///tmp/tmp.sock
 113
 114 0MQ connector implements a REQ/REP RPC model. Please see
 115 http://zeromq.org/ for more information.
 116
 117 .. _remote-api:
 118
 119 API
 120 ---
 121
 122 Queries
 123 ^^^^^^^
 124
 125 Unix, Pipe and ZeroMQ connectors send JSON formatted strings to the
 126 remote end. Each JSON query has two sections, 'method' and 'parameters'.
 127
 128 HTTP connector calls methods based on URL and has parameters in the
 129 query string. Most calls are GET; see the methods listing for details.
 130 You can change this with post and post_json attributes.
 131
 132 Replies
 133 ^^^^^^^
 134
 135 You **must** always reply with JSON hash with at least one key,
 136 'result'. This must be boolean false if the query failed. Otherwise it
 137 must conform to the expected result. For HTTP connector, to signal bare
 138 success, you can just reply with HTTP 200 OK, and omit any output. This
 139 will result in same outcome as sending {"result":true}.
 140
 141 You can optionally add an array of strings to the 'log' array; each line
 142 in this array will be logged in PowerDNS at loglevel ``info`` (6).
 143
 144 Methods
 145 ^^^^^^^
 146
 147 Methods required for different features
 148 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 149 :Always required: ``initialize``, ``lookup``
 150 :Master operation: ``list``, ``getUpdatedMasters``, ``setNotified``
 151 :Slave operation: ``getUnfreshSlaveInfos``, ``startTransaction``, ``commitTransaction``, ``abortTransaction``, ``feedRecord``, ``setFresh``
 152 :DNSSEC operation (live-signing): ``getDomainKeys``, ``getBeforeAndAfterNamesAbsolute``
 153 :Filling the Zone Cache: ``getAllDomains``
 154
 155 ``initialize``
 156 ~~~~~~~~~~~~~~
 157
 158 Called to initialize the backend. This is not called for HTTP connector.
 159 You should do your initializations here.
 160
 161 -  Mandatory: Yes (except HTTP connector)
 162 -  Parameters: all parameters in connection string
 163 -  Reply: true on success / false on failure
 164
 165 Example JSON/RPC
 166 ~~~~~~~~~~~~~~~~
 167
 168 Query:
 169
 170 .. code-block:: json
 171
 172     {"method":"initialize", "parameters":{"command":"/path/to/something", "timeout":"2000", "something":"else"}}
 173
 174 Response:
 175
 176 .. code-block:: json
 177
 178     {"result":true}
 179
 180 .. _remote-lookup:
 181
 182 ``lookup``
 183 ~~~~~~~~~~
 184
 185 This method is used to do the basic query. You can omit auth, but if you
 186 are using DNSSEC this can lead into trouble.
 187
 188 -  Mandatory: Yes
 189 -  Parameters: qtype, qname, zone_id
 190 -  Optional parameters: remote, local, real-remote
 191 -  Reply: array of ``qtype,qname,content,ttl,domain_id,scopeMask,auth``
 192 -  Optional values: domain_id, scopeMask and auth
 193 -  Note: priority field is required before 4.0, after 4.0 priority is
 194    added to content. This applies to any resource record which uses
 195    priority, for example SRV or MX.
 196
 197 Example JSON/RPC
 198 ''''''''''''''''
 199
 200 Query:
 201
 202 .. code-block:: json
 203
 204     {"method":"lookup", "parameters":{"qtype":"ANY", "qname":"www.example.com.", "remote":"192.0.2.24", "local":"192.0.2.1", "real-remote":"192.0.2.24", "zone-id":-1}}
 205
 206 Response:
 207
 208 .. code-block:: json
 209
 210     {"result":[{"qtype":"A", "qname":"www.example.com", "content":"203.0.113.2", "ttl": 60}]}
 211
 212 Example HTTP/RPC
 213 ''''''''''''''''
 214
 215 Query:
 216
 217 .. code-block:: http
 218
 219     GET /dnsapi/lookup/www.example.com./ANY HTTP/1.1
 220     X-RemoteBackend-remote: 192.0.2.24
 221     X-RemoteBackend-local: 192.0.2.1
 222     X-RemoteBackend-real-remote: 192.0.2.24
 223     X-RemoteBackend-zone-id: -1
 224
 225 Response:
 226
 227 .. code-block:: http
 228
 229     HTTP/1.1 200 OK
 230     Content-Type: text/javascript; charset=utf-8
 231
 232     {"result":[{"qtype":"A", "qname":"www.example.com", "content":"203.0.113.2", "ttl": 60}]}
 233
 234 ``list``
 235 ~~~~~~~~
 236
 237 Lists all records for the zonename. If you are running dnssec, you
 238 should take care of setting auth to appropriate value, otherwise things
 239 can go wrong.
 240
 241 -  Mandatory: No (Gives AXFR support)
 242 -  Parameters: zonename, domain_id
 243 -  Optional parameters: domain_id
 244 -  Reply: array of ``qtype,qname,content,ttl,domain_id,scopeMask,auth``
 245 -  Optional values: domain_id, scopeMask and auth
 246
 247 Example JSON/RPC
 248 ''''''''''''''''
 249
 250 Query:
 251
 252 .. code-block:: json
 253
 254     {"method":"list", "parameters":{"zonename":"example.com.","domain_id":-1}}
 255
 256 Response (split into lines for ease of reading)
 257
 258 .. code-block:: json
 259
 260     {"result":[
 261       {"qtype":"SOA", "qname":"example.com", "content":"dns1.icann.org. hostmaster.icann.org. 2012081600 7200 3600 1209600 3600", "ttl": 3600},
 262       {"qtype":"NS", "qname":"example.com", "content":"ns1.example.com", "ttl": 60},
 263       {"qtype":"MX", "qname":"example.com", "content":"10 mx1.example.com.", "ttl": 60},
 264       {"qtype":"A", "qname":"www.example.com", "content":"203.0.113.2", "ttl": 60},
 265       {"qtype":"A", "qname":"ns1.example.com", "content":"192.0.2.2", "ttl": 60},
 266       {"qtype":"A", "qname":"mx1.example.com", "content":"192.0.2.3", "ttl": 60}
 267     ]}
 268
 269 Example HTTP/RPC
 270 ''''''''''''''''
 271
 272 Query:
 273
 274 .. code-block:: http
 275
 276     GET /dnsapi/list/-1/example.com HTTP/1.1
 277     X-RemoteBackend-domain-id: -1
 278
 279 Response:
 280
 281 .. code-block:: http
 282
 283     HTTP/1.1 200 OK
 284     Content-Type: text/javascript; charset=utf-8
 285
 286     {"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":"10 mx1.example.com.", "ttl": 60},{"qtype":"A", "qname":"www.example.com", "content":"203.0.113.2", "ttl": 60},{"qtype":"A", "qname":"ns1.example.com", "content":"192.0.2.2", "ttl": 60},{"qtype":"A", "qname":"mx1.example.com", "content":"192.0.2.3", "ttl": 60}]}
 287
 288 ``getBeforeAndAfterNamesAbsolute``
 289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 290
 291 Asks the names before and after qname. qname is given without domain part.
 292 Care must be taken to handle wrap-around when qname is first or last in the ordered list.
 293 Do not return nil or an empty string for ``before`` and ``after``.
 294 When using NSEC, ``unhashed`` can be an empty string (but MUST be present in the response).
 295 The ``qname`` will be hashed when using NSEC3 and in the response, ``unhashed`` should be the records' real name without the domain part, and ``before`` and ``after`` should be the hashes.
 296
 297 -  Mandatory: for NSEC/NSEC3 non-narrow
 298 -  Parameters: id (domain ID), qname
 299 -  Reply: before, after, unhashed
 300
 301 Example JSON/RPC
 302 ''''''''''''''''
 303
 304 Query:
 305
 306 .. code-block:: json
 307
 308     {"method":"getBeforeAndAfterNamesAbsolute", "params":{"id":0,"qname":"www."}}
 309
 310 Response:
 311
 312 .. code-block:: json
 313
 314     {"result":{"before":"ns1","after":""}}
 315
 316 Example HTTP/RPC
 317 ''''''''''''''''
 318
 319 Query:
 320
 321 ::
 322
 323     /dnsapi/getbeforeandafternamesabsolute/0/www.example.com
 324
 325 Response:
 326
 327 .. code-block:: json
 328
 329     {"result":{"before":"ns1","after":""}}
 330
 331 ``getAllDomainMetadata``
 332 ~~~~~~~~~~~~~~~~~~~~~~~~
 333
 334 Returns the value(s) for variable kind for zone name. You **must**
 335 always return something, if there are no values, you shall return empty
 336 set.
 337
 338 *  Mandatory: yes
 339 *  Parameters: name
 340 *  Reply: hash of key to array of strings
 341
 342 Example JSON/RPC
 343 ''''''''''''''''
 344
 345 Query:
 346
 347 .. code-block:: json
 348
 349     {"method":"getalldomainmetadata", "parameters":{"name":"example.com"}}
 350
 351 Response:
 352
 353 .. code-block:: json
 354
 355     {"result":{"PRESIGNED":["0"]}}
 356
 357 Example HTTP/RPC
 358 ''''''''''''''''
 359
 360 Query:
 361
 362 .. code-block:: http
 363
 364     GET /dnsapi/getalldomainmetadata/example.com HTTP/1.1
 365
 366 Response:
 367
 368 .. code-block:: http
 369
 370     HTTP/1.1 200 OK
 371     Content-Type: text/javascript; charset=utf-8
 372
 373     {"result":{"PRESIGNED":["0"]}}
 374
 375 ``getDomainMetadata``
 376 ~~~~~~~~~~~~~~~~~~~~~
 377
 378 Returns the value(s) for variable kind for zone name. Most commonly it's
 379 one of NSEC3PARAM, PRESIGNED, SOA-EDIT. Can be others, too. You **must**
 380 always return something, if there are no values, you shall return empty
 381 array.
 382
 383 -  Mandatory: No
 384 -  Parameters: name, kind
 385 -  Reply: array of strings
 386
 387 Example JSON/RPC
 388 ''''''''''''''''
 389
 390 Query:
 391
 392 .. code-block:: json
 393
 394     {"method":"getdomainmetadata", "parameters":{"name":"example.com.","kind":"PRESIGNED"}}
 395
 396 Response:
 397
 398 .. code-block:: json
 399
 400     {"result":["0"]}
 401
 402 Example HTTP/RPC
 403 ''''''''''''''''
 404
 405 Query:
 406
 407 .. code-block:: http
 408
 409     GET /dnsapi/getdomainmetadata/example.com./PRESIGNED HTTP/1.1
 410
 411 Response:
 412
 413 .. code-block:: http
 414
 415     HTTP/1.1 200 OK
 416     Content-Type: text/javascript; charset=utf-8
 417
 418     {"result":["0"]}
 419
 420 ``setDomainMetadata``
 421 ~~~~~~~~~~~~~~~~~~~~~
 422
 423 Replaces the value(s) on domain name for variable kind to string(s) on
 424 array value. The old value is discarded. Value can be an empty array,
 425 which can be interpreted as deletion request.
 426
 427 -  Mandatory: No
 428 -  Parameters: name, kind, value
 429 -  Reply: true on success, false on failure
 430
 431 Example JSON/RPC
 432 ''''''''''''''''
 433
 434 Query:
 435
 436 .. code-block:: json
 437
 438     {"method":"setdomainmetadata","parameters":{"name":"example.com","kind":"PRESIGNED","value":["YES"]}}
 439
 440 Response:
 441
 442 .. code-block:: json
 443
 444     {"result":true}
 445
 446 Example HTTP/RPC
 447 ''''''''''''''''
 448
 449 Query:
 450
 451 .. code-block:: http
 452
 453     PATCH /dnsapi/setdomainmetadata/example.com/PRESIGNED HTTP/1.1
 454     Content-Type: application/x-www-form-urlencoded
 455     Content-Length: 12
 456
 457     value[]=YES&
 458
 459 Response:
 460
 461 .. code-block:: http
 462
 463     HTTP/1.1 200 OK
 464     Content-Type: text/javascript; charset=utf-8
 465
 466     {"result":true}
 467
 468 .. _remote-getdomainkeys:
 469
 470 ``getDomainKeys``
 471 ~~~~~~~~~~~~~~~~~
 472
 473 Retrieves any keys of kind. The id, flags are unsigned integers, and
 474 active and published are boolean. Content must be valid key record in format
 475 that PowerDNS understands. You are encouraged to implement :ref:`the
 476 section called "addDomainKey" <remote-adddomainkey>`, as you can use
 477 :doc:`../manpages/pdnsutil.1` to provision keys.
 478
 479 -  Mandatory: for DNSSEC
 480 -  Parameters: name, kind
 481 -  Reply: array of ``id, flags, active, published, content``
 482
 483 Example JSON/RPC
 484 ''''''''''''''''
 485
 486 Query:
 487
 488 .. code-block:: json
 489
 490     {"method":"getDomainKeys","parameters":{"name":"example.com."}}
 491
 492 Response:
 493
 494 .. code-block:: json
 495
 496     {"result":[{"id":1,"flags":256,"active":true,"published":true,"content":"Private-key-format: v1.2
 497     Algorithm: 8 (RSASHA256)
 498     Modulus: r+vmQll38ndQqNSCx9eqRBUbSOLcH4PZFX824sGhY2NSQChqt1G4ZfndzRwgjXMUwiE7GkkqU2Vbt/g4iP67V/+MYecMV9YHkCRnEzb47nBXvs9JCf8AHMCnma567GQjPECh4HevPE9wmcOfpy/u7UN1oHKSKRWuZJadUwcjbp8=
 499     PublicExponent: AQAB
 500     PrivateExponent: CYC93UtVnOM6wrFJZ+qA9+Yx+p5yk0CSi0Q7c+/6EVMuABQ5gNyTuu0j65lU3X81bwUk2wHPx6smfgoVDRAW5jjO4jgIFV6nE4inzk5YQKycQSL8YG3Nm9GciLFya1KUXs81sHsQpkvK7MNaSbvkaHZQ6iv16bZ4t73Wascwa/E=
 501     Prime1: 6a165cIC0nNsGlTW/s2jRu7idq5+U203iE1HzSIddmWgx5KIKE/s3I+pwfmXYRUmq+4H9ASd/Yot1lSYW98szw==
 502     Prime2: wLoCPKxxnuxDx6/9IKOYz8t9ZNLY74iCeQ85koqvTctkFmB9jpOUHTU9BhecaFY2euP9CuHV7z3PLtCoO8s1MQ==
 503     Exponent1: CuzJaiR/7UboLvL4ekEy+QYCIHpX/Z6FkiHK0ZRevEJUGgCHzRqvgEBXN3Jr2WYbwL4IMShmGoxzSCn8VY9BkQ==
 504     Exponent2: LDR9/tyu0vzuLwc20B22FzNdd5rFF2wAQTQ0yF/3Baj5NAi9w84l0u07KgKQZX4g0N8qUyypnU5YDyzc6ZoagQ==
 505     Coefficient: 6S0vhIQITWzqfQSLj+wwRzs6qCvJckHb1+SD1XpwYjSgMTEUlZhf96m8WiaE1/fIt4Zl2PC3fF7YIBoFLln22w=="}]}
 506
 507 Example HTTP/RPC
 508 ''''''''''''''''
 509
 510 Query:
 511
 512 .. code-block:: http
 513
 514     GET /dnsapi/getdomainkeys/example.com/0 HTTP/1.1
 515
 516 Response:
 517
 518 .. code-block:: http
 519
 520     HTTP/1.1 200 OK
 521     Content-Type: text/javascript; charset=utf-8
 522
 523     {"result":[{"id":1,"flags":256,"active":true,"published":true,"content":"Private-key-format: v1.2
 524     Algorithm: 8 (RSASHA256)
 525     Modulus: r+vmQll38ndQqNSCx9eqRBUbSOLcH4PZFX824sGhY2NSQChqt1G4ZfndzRwgjXMUwiE7GkkqU2Vbt/g4iP67V/+MYecMV9YHkCRnEzb47nBXvs9JCf8AHMCnma567GQjPECh4HevPE9wmcOfpy/u7UN1oHKSKRWuZJadUwcjbp8=
 526     PublicExponent: AQAB
 527     PrivateExponent: CYC93UtVnOM6wrFJZ+qA9+Yx+p5yk0CSi0Q7c+/6EVMuABQ5gNyTuu0j65lU3X81bwUk2wHPx6smfgoVDRAW5jjO4jgIFV6nE4inzk5YQKycQSL8YG3Nm9GciLFya1KUXs81sHsQpkvK7MNaSbvkaHZQ6iv16bZ4t73Wascwa/E=
 528     Prime1: 6a165cIC0nNsGlTW/s2jRu7idq5+U203iE1HzSIddmWgx5KIKE/s3I+pwfmXYRUmq+4H9ASd/Yot1lSYW98szw==
 529     Prime2: wLoCPKxxnuxDx6/9IKOYz8t9ZNLY74iCeQ85koqvTctkFmB9jpOUHTU9BhecaFY2euP9CuHV7z3PLtCoO8s1MQ==
 530     Exponent1: CuzJaiR/7UboLvL4ekEy+QYCIHpX/Z6FkiHK0ZRevEJUGgCHzRqvgEBXN3Jr2WYbwL4IMShmGoxzSCn8VY9BkQ==
 531     Exponent2: LDR9/tyu0vzuLwc20B22FzNdd5rFF2wAQTQ0yF/3Baj5NAi9w84l0u07KgKQZX4g0N8qUyypnU5YDyzc6ZoagQ==
 532     Coefficient: 6S0vhIQITWzqfQSLj+wwRzs6qCvJckHb1+SD1XpwYjSgMTEUlZhf96m8WiaE1/fIt4Zl2PC3fF7YIBoFLln22w=="}]}
 533
 534 .. _remote-adddomainkey:
 535
 536 ``addDomainKey``
 537 ~~~~~~~~~~~~~~~~
 538
 539 Adds key into local storage. See :ref:`remote-getdomainkeys` for more information.
 540
 541 -  Mandatory: No
 542 -  Parameters: name, key=\ ``<flags,active,published,content>``, id
 543 -  Reply: true for success, false for failure
 544
 545 Example JSON/RPC
 546 ''''''''''''''''
 547
 548 Query:
 549
 550 .. code-block:: json
 551
 552     {"method":"adddomainkey", "parameters":{"key":{"id":1,"flags":256,"active":true,"published":true,"content":"Private-key-format: v1.2
 553     Algorithm: 8 (RSASHA256)
 554     Modulus: r+vmQll38ndQqNSCx9eqRBUbSOLcH4PZFX824sGhY2NSQChqt1G4ZfndzRwgjXMUwiE7GkkqU2Vbt/g4iP67V/+MYecMV9YHkCRnEzb47nBXvs9JCf8AHMCnma567GQjPECh4HevPE9wmcOfpy/u7UN1oHKSKRWuZJadUwcjbp8=
 555     PublicExponent: AQAB
 556     PrivateExponent: CYC93UtVnOM6wrFJZ+qA9+Yx+p5yk0CSi0Q7c+/6EVMuABQ5gNyTuu0j65lU3X81bwUk2wHPx6smfgoVDRAW5jjO4jgIFV6nE4inzk5YQKycQSL8YG3Nm9GciLFya1KUXs81sHsQpkvK7MNaSbvkaHZQ6iv16bZ4t73Wascwa/E=
 557     Prime1: 6a165cIC0nNsGlTW/s2jRu7idq5+U203iE1HzSIddmWgx5KIKE/s3I+pwfmXYRUmq+4H9ASd/Yot1lSYW98szw==
 558     Prime2: wLoCPKxxnuxDx6/9IKOYz8t9ZNLY74iCeQ85koqvTctkFmB9jpOUHTU9BhecaFY2euP9CuHV7z3PLtCoO8s1MQ==
 559     Exponent1: CuzJaiR/7UboLvL4ekEy+QYCIHpX/Z6FkiHK0ZRevEJUGgCHzRqvgEBXN3Jr2WYbwL4IMShmGoxzSCn8VY9BkQ==
 560     Exponent2: LDR9/tyu0vzuLwc20B22FzNdd5rFF2wAQTQ0yF/3Baj5NAi9w84l0u07KgKQZX4g0N8qUyypnU5YDyzc6ZoagQ==
 561     Coefficient: 6S0vhIQITWzqfQSLj+wwRzs6qCvJckHb1+SD1XpwYjSgMTEUlZhf96m8WiaE1/fIt4Zl2PC3fF7YIBoFLln22w=="}}}
 562
 563 Response:
 564
 565 .. code-block:: json
 566
 567     {"result":true}
 568
 569 Example HTTP/RPC
 570 ''''''''''''''''
 571
 572 Query:
 573
 574 .. code-block:: http
 575
 576     PUT /dnsapi/adddomainkey/example.com HTTP/1.1
 577     Content-Type: application/x-www-form-urlencoded
 578     Content-Length: 965
 579
 580     flags=256&active=1&published=1&content=Private-key-format: v1.2
 581     Algorithm: 8 (RSASHA256)
 582     Modulus: r+vmQll38ndQqNSCx9eqRBUbSOLcH4PZFX824sGhY2NSQChqt1G4ZfndzRwgjXMUwiE7GkkqU2Vbt/g4iP67V/+MYecMV9YHkCRnEzb47nBXvs9JCf8AHMCnma567GQjPECh4HevPE9wmcOfpy/u7UN1oHKSKRWuZJadUwcjbp8=
 583     PublicExponent: AQAB
 584     PrivateExponent: CYC93UtVnOM6wrFJZ+qA9+Yx+p5yk0CSi0Q7c+/6EVMuABQ5gNyTuu0j65lU3X81bwUk2wHPx6smfgoVDRAW5jjO4jgIFV6nE4inzk5YQKycQSL8YG3Nm9GciLFya1KUXs81sHsQpkvK7MNaSbvkaHZQ6iv16bZ4t73Wascwa/E=
 585     Prime1: 6a165cIC0nNsGlTW/s2jRu7idq5+U203iE1HzSIddmWgx5KIKE/s3I+pwfmXYRUmq+4H9ASd/Yot1lSYW98szw==
 586     Prime2: wLoCPKxxnuxDx6/9IKOYz8t9ZNLY74iCeQ85koqvTctkFmB9jpOUHTU9BhecaFY2euP9CuHV7z3PLtCoO8s1MQ==
 587     Exponent1: CuzJaiR/7UboLvL4ekEy+QYCIHpX/Z6FkiHK0ZRevEJUGgCHzRqvgEBXN3Jr2WYbwL4IMShmGoxzSCn8VY9BkQ==
 588     Exponent2: LDR9/tyu0vzuLwc20B22FzNdd5rFF2wAQTQ0yF/3Baj5NAi9w84l0u07KgKQZX4g0N8qUyypnU5YDyzc6ZoagQ==
 589     Coefficient: 6S0vhIQITWzqfQSLj+wwRzs6qCvJckHb1+SD1XpwYjSgMTEUlZhf96m8WiaE1/fIt4Zl2PC3fF7YIBoFLln22w==
 590
 591 Response:
 592
 593 .. code-block:: http
 594
 595     HTTP/1.1 200 OK
 596     Content-Type: text/javascript; charset=utf-8
 597
 598     {"result":true}
 599
 600 ``removeDomainKey``
 601 ~~~~~~~~~~~~~~~~~~~
 602
 603 Removes key id from domain name.
 604
 605 -  Mandatory: No
 606 -  Parameters: name, id
 607 -  Reply: true for success, false for failure
 608
 609 Example JSON/RPC
 610 ''''''''''''''''
 611
 612 Query:
 613
 614 .. code-block:: json
 615
 616     {"method":"removedomainkey","parameters":{"name":"example.com","id":1}}
 617
 618 Response:
 619
 620 .. code-block:: json
 621
 622     {"result":true}
 623
 624 Example HTTP/RPC
 625 ''''''''''''''''
 626
 627 Query:
 628
 629 .. code-block:: http
 630
 631     DELETE /dnsapi/removedomainkey/example.com/1 HTTP/1.1
 632
 633 Response:
 634
 635 .. code-block:: http
 636
 637     HTTP/1.1 200 OK
 638     Content-Type: text/javascript; charset=utf-8
 639
 640     {"result":true}
 641
 642 ``activateDomainKey``
 643 ~~~~~~~~~~~~~~~~~~~~~
 644
 645 Activates key id for domain name.
 646
 647 -  Mandatory: No
 648 -  Parameters: name, id
 649 -  Reply: true for success, false for failure
 650
 651 Example JSON/RPC
 652 ''''''''''''''''
 653
 654 Query:
 655
 656 .. code-block:: json
 657
 658     {"method":"activatedomainkey","parameters":{"name":"example.com","id":1}}
 659
 660 Response:
 661
 662 .. code-block:: json
 663
 664     {"result":true}
 665
 666 Example HTTP/RPC
 667 ''''''''''''''''
 668
 669 Query:
 670
 671 .. code-block:: http
 672
 673     POST /dnsapi/activatedomainkey/example.com/1 HTTP/1.1
 674
 675 Response:
 676
 677 .. code-block:: http
 678
 679     HTTP/1.1 200 OK
 680     Content-Type: text/javascript; utf-8
 681
 682     {"result": true}
 683
 684 ``deactivateDomainKey``
 685 ~~~~~~~~~~~~~~~~~~~~~~~
 686
 687 Deactivates key id for domain name.
 688
 689 -  Mandatory: No
 690 -  Parameters: name, id
 691 -  Reply: true for success, false for failure
 692
 693 Example JSON/RPC
 694 ''''''''''''''''
 695
 696 Query:
 697
 698 .. code-block:: json
 699
 700     {"method":"deactivatedomainkey","parameters":{"name":"example.com","id":1}}
 701
 702 Response:
 703
 704 .. code-block:: json
 705
 706     {"result": true}
 707
 708 Example HTTP/RPC
 709 ''''''''''''''''
 710
 711 Query:
 712
 713 .. code-block:: http
 714
 715     POST /dnsapi/deactivatedomainkey/example.com/1 HTTP/1.1
 716
 717 Response:
 718
 719 .. code-block:: http
 720
 721     HTTP/1.1 200 OK
 722     Content-Type: text/javascript; utf-8
 723
 724     {"result": true}
 725
 726 ``publishDomainKey``
 727 ~~~~~~~~~~~~~~~~~~~~
 728
 729 Publish key id for domain name.
 730
 731 -  Mandatory: No
 732 -  Parameters: name, id
 733 -  Reply: true for success, false for failure
 734
 735 Example JSON/RPC
 736 ''''''''''''''''
 737
 738 Query:
 739
 740 .. code-block:: json
 741
 742     {"method":"publishdomainkey","parameters":{"name":"example.com","id":1}}
 743
 744 Response:
 745
 746 .. code-block:: json
 747
 748     {"result": true}
 749
 750 Example HTTP/RPC
 751 ''''''''''''''''
 752
 753 Query:
 754
 755 .. code-block:: http
 756
 757     POST /dnsapi/publishdomainkey/example.com/1 HTTP/1.1
 758
 759 Response:
 760
 761 .. code-block:: http
 762
 763     HTTP/1.1 200 OK
 764     Content-Type: text/javascript; utf-8
 765
 766     {"result": true}
 767
 768
 769 ``unpublishDomainKey``
 770 ~~~~~~~~~~~~~~~~~~~~~~
 771
 772 Unpublish key id for domain name.
 773
 774 -  Mandatory: No
 775 -  Parameters: name, id
 776 -  Reply: true for success, false for failure
 777
 778 Example JSON/RPC
 779 ''''''''''''''''
 780
 781 Query:
 782
 783 .. code-block:: json
 784
 785     {"method":"unpublishdomainkey","parameters":{"name":"example.com","id":1}}
 786
 787 Response:
 788
 789 .. code-block:: json
 790
 791     {"result": true}
 792
 793 Example HTTP/RPC
 794 ''''''''''''''''
 795
 796 Query:
 797
 798 .. code-block:: http
 799
 800     POST /dnsapi/unpublishdomainkey/example.com/1 HTTP/1.1
 801
 802 Response:
 803
 804 .. code-block:: http
 805
 806     HTTP/1.1 200 OK
 807     Content-Type: text/javascript; utf-8
 808
 809     {"result": true}
 810
 811
 812 ``getTSIGKey``
 813 ~~~~~~~~~~~~~~
 814
 815 Retrieves the key needed to sign AXFR.
 816
 817 -  Mandatory: No
 818 -  Parameters: name
 819 -  Reply: algorithm, content
 820
 821 Example JSON/RPC
 822 ''''''''''''''''
 823
 824 Query:
 825
 826 .. code-block:: json
 827
 828     {"method":"gettsigkey","parameters":{"name":"example.com."}}
 829
 830 Response:
 831
 832 .. code-block:: json
 833
 834     {"result":{"algorithm":"hmac-md5","content":"kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys="}}
 835
 836 Example HTTP/RPC
 837 ''''''''''''''''
 838
 839 Query:
 840
 841 .. code-block:: http
 842
 843     GET /dnsapi/gettsigkey/example.com. HTTP/1.1
 844
 845 Response:
 846
 847 .. code-block:: http
 848
 849     HTTP/1.1 200 OK
 850     Content-Type: text/javascript; charset=utf-8
 851
 852     {"result":{"algorithm":"hmac-md5","content":"kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys="}}
 853
 854 ``getDomainInfo``
 855 ~~~~~~~~~~~~~~~~~
 856
 857 Retrieves information about given domain from the backend. If your
 858 return value has no zone attribute, the backend will signal error.
 859 Everything else will default to something. Default values: serial:0,
 860 kind:NATIVE, id:-1, notified_serial:-1, last_check:0, masters: [].
 861 Masters, if present, must be array of strings.
 862
 863 -  Mandatory: No
 864 -  Parameters: name
 865 -  Reply: zone
 866 -  Optional values: serial, kind, id, notified_serial, last_check,
 867    masters
 868
 869 Example JSON/RPC
 870 ''''''''''''''''
 871
 872 Query:
 873
 874 .. code-block:: json
 875
 876     {"method":"getdomaininfo","parameters":{"name":"example.com"}}
 877
 878 Response:
 879
 880 .. code-block:: json
 881
 882     {"result":{"id":1,"zone":"example.com","kind":"NATIVE","serial":2002010100}}
 883
 884 Example HTTP/RPC
 885 ''''''''''''''''
 886
 887 Query:
 888
 889 .. code-block:: http
 890
 891     GET /dnsapi/getdomaininfo/example.com HTTP/1.1
 892
 893 Response:
 894
 895 .. code-block:: http
 896
 897     HTTP/1.1 200 OK
 898     content-Type: text/javascript: charset=utf-8
 899
 900     {"result":{id:1,"zone":"example.com","kind":"NATIVE","serial":2002010100}}
 901
 902 ``setNotified``
 903 ~~~~~~~~~~~~~~~
 904
 905 Updates last notified serial for the domain id. Any errors are ignored.
 906
 907 -  Mandatory: No
 908 -  Parameters: id, serial
 909 -  Reply: true for success, false for failure
 910
 911 Example JSON/RPC
 912 ''''''''''''''''
 913
 914 Query:
 915
 916 .. code-block:: json
 917
 918     {"method":"setnotified","parameters":{"id":1,"serial":2002010100}}
 919
 920 Response:
 921
 922 .. code-block:: json
 923
 924     {"result":true}
 925
 926 Example HTTP/RPC
 927 ''''''''''''''''
 928
 929 Query:
 930
 931 .. code-block:: http
 932
 933     PATCH /dnsapi/setnotified/1 HTTP/1.1
 934     Content-Type: application/x-www-form-urlencoded
 935     Content-Length: 17
 936
 937     serial=2002010100
 938
 939 Response:
 940
 941 .. code-block:: http
 942
 943     HTTP/1.1 200 OK
 944     Content-Type: text/javascript; charset=utf-8
 945
 946     {"result":true}
 947
 948 ``isMaster``
 949 ~~~~~~~~~~~~
 950
 951 Determines whether given IP is master for given domain name.
 952
 953 -  Mandatory: No
 954 -  Parameters: name,ip
 955 -  Reply: true for success, false for failure.
 956
 957 Example JSON/RPC
 958 ''''''''''''''''
 959
 960 Query:
 961
 962 .. code-block:: json
 963
 964     {"method":"isMaster","parameters":{"name":"example.com","ip":"198.51.100.0.1"}}
 965
 966 Response:
 967
 968 .. code-block:: json
 969
 970     {"result":true}
 971
 972 Example HTTP/RPC
 973 ''''''''''''''''
 974
 975 Query:
 976
 977 .. code-block:: http
 978
 979     GET /dnsapi/isMaster/example.com/198.51.100.0.1 HTTP/1.1
 980
 981 Response:
 982
 983 .. code-block:: http
 984
 985     HTTP/1.1 200 OK
 986     Content-Type: text/javascript; charset=utf-8
 987
 988     {"result":true}
 989
 990 ``superMasterBackend``
 991 ~~~~~~~~~~~~~~~~~~~~~~
 992
 993 Creates new domain with given record(s) as master servers. IP address is
 994 the address where notify is received from. nsset is array of NS resource
 995 records.
 996
 997 -  Mandatory: No
 998 -  Parameters: ip,domain,nsset,account
 999 -  Reply: true for success, false for failure. can also return
1000    account=>name of account< and nameserver.
1001
1002 Example JSON/RPC
1003 ''''''''''''''''
1004
1005 Query:
1006
1007 .. code-block:: json
1008
1009     {"method":"superMasterBackend","parameters":{"ip":"198.51.100.0.1","domain":"example.com","nsset":[{"qtype":"NS","qname":"example.com","qclass":1,"content":"ns1.example.com","ttl":300,"auth":true},{"qtype":"NS","qname":"example.com","qclass":1,"content":"ns2.example.com","ttl":300,"auth":true}]}}
1010
1011 Response:
1012
1013 .. code-block:: json
1014
1015     {"result":true}
1016
1017 Alternative response:
1018
1019 .. code-block:: json
1020
1021     {"result":{"account":"my account","nameserver":"ns2.example.com"}}
1022
1023 Example HTTP/RPC
1024 ''''''''''''''''
1025
1026 Query:
1027
1028 .. code-block:: http
1029
1030     POST /dnsapi/supermasterbackend/198.51.100.0.1/example.com HTTP/1.1
1031     Content-Type: application/x-www-form-urlencoded
1032     Content-Length: 317
1033
1034     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][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][auth]=true
1035
1036 Response:
1037
1038 .. code-block:: http
1039
1040     HTTP/1.1 200 OK
1041     Content-Type: text/javascript; charset=utf-8
1042
1043     {"result":true}
1044
1045 Alternative response
1046
1047 .. code-block:: http
1048
1049     HTTP/1.1 200 OK
1050     Content-Type: text/javascript; charset=utf-8
1051
1052     {"result":{"account":"my account"}}
1053
1054 ``createSlaveDomain``
1055 ~~~~~~~~~~~~~~~~~~~~~
1056 Creates new domain. This method is called when NOTIFY is received and
1057 you are superslaving.
1058
1059  - Mandatory: No
1060  - Parameters: ip, domain
1061  - Optional parameters: nameserver, account
1062  - Reply: true for success, false for failure
1063
1064 Example JSON/RPC
1065 ''''''''''''''''
1066
1067 Query:
1068
1069 .. code-block:: json
1070
1071     {"method":"createSlaveDomain","parameters":{"ip":"198.51.100.0.1","domain":"pirate.example.net"}}
1072
1073 Response:
1074
1075 .. code-block:: json
1076
1077     {"result":true}
1078
1079 Example HTTP/RPC
1080 ''''''''''''''''
1081
1082 Query:
1083
1084 .. code-block:: http
1085
1086     POST /dnsapi/createslavedomain/198.51.100.0.1/pirate.example.net HTTP/1.1
1087     Content-Type: application/x-www-form-urlencoded
1088     Content-Length: 0
1089
1090 Response:
1091
1092 .. code-block:: http
1093
1094     HTTP/1.1 200 OK
1095     Content-Type: text/javascript; charset=utf-8
1096
1097     {"result":true}
1098
1099 ``replaceRRSet``
1100 ~~~~~~~~~~~~~~~~
1101
1102 This method replaces a given resource record with new set. The new qtype
1103 can be different from the old.
1104
1105 -  Mandatory: No
1106 -  Parameters: domain_id, qname, qtype, rrset
1107 -  Reply: true for success, false for failure
1108
1109 Example JSON/RPC
1110 ''''''''''''''''
1111
1112 Query:
1113
1114 .. code-block:: json
1115
1116     {"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,"auth":true}]}}
1117
1118 Response:
1119
1120 .. code-block:: json
1121
1122     {"result":true}
1123
1124 Example HTTP/RPC
1125 ''''''''''''''''
1126
1127 Query:
1128
1129 .. code-block:: http
1130
1131     PATCH /dnsapi/replacerrset/2/replace.example.com/A HTTP/1.1
1132     Content-Type: application/x-www-form-urlencoded
1133     Content-Length: 135
1134
1135     trxid=1370416133&rrset[qtype]=A&rrset[qname]=replace.example.com&rrset[qclass]=1&rrset[content]=1.1.1.1&rrset[auth]=1
1136
1137 Response:
1138
1139 .. code-block:: http
1140
1141     HTTP/1.1 200 OK
1142     Content-Type: text/javascript; charset=utf-8
1143
1144     {"result":true}
1145
1146 ``feedRecord``
1147 ~~~~~~~~~~~~~~
1148
1149 Asks to feed new record into system. If startTransaction was called,
1150 trxId identifies a transaction. It is not always called by PowerDNS.
1151
1152 -  Mandatory: No
1153 -  Parameters: rr, trxid
1154 -  Reply: true for success, false for failure
1155
1156 Example JSON/RPC
1157 ''''''''''''''''
1158
1159 Query:
1160
1161 .. code-block:: json
1162
1163     {"method":"feedRecord","parameters":{"rr":{"qtype":"A","qname":"replace.example.com","qclass":1,"content":"127.0.0.1","ttl":300,"auth":true},"trxid":1370416133}}
1164
1165 Response:
1166
1167 .. code-block:: json
1168
1169     {"result":true}
1170
1171 Example HTTP/RPC
1172 ''''''''''''''''
1173
1174 Query:
1175
1176 .. code-block:: http
1177
1178     PATCH /dnsapi/feedrecord/1370416133 HTTP/1.1
1179     Content-Type: application/x-www-form-urlencoded
1180     Content-Length: 117
1181
1182     rr[qtype]=A&rr[qname]=replace.example.com&rr[qclass]=1&rr[content]=127.0.0.1&rr[ttl]=300&rr[auth]=true
1183
1184 Response:
1185
1186 .. code-block:: http
1187
1188     HTTP/1.1 200 OK
1189     Content-Type: text/javascript; charset=utf-8
1190
1191     {"result":true}
1192
1193 .. _remote-feedents:
1194
1195 ``feedEnts``
1196 ~~~~~~~~~~~~
1197
1198 This method is used by pdnsutil rectify-zone to populate missing
1199 non-terminals. This is used when you have, say, record like
1200 _sip._upd.example.com, but no _udp.example.com. PowerDNS requires
1201 that there exists a non-terminal in between, and this instructs you to
1202 add one. If startTransaction is called, trxid identifies a transaction.
1203
1204 -  Mandatory: No
1205 -  Parameters: nonterm, trxid
1206 -  Reply: true for success, false for failure
1207
1208 Example JSON/RPC
1209 ''''''''''''''''
1210
1211 Query:
1212
1213 .. code-block:: json
1214
1215     {"method":"feedEnts","parameters":{"domain_id":2,"trxid":1370416133,"nonterm":["_sip._udp","_udp"]}}
1216
1217 Response:
1218
1219 .. code-block:: json
1220
1221     {"result":true}
1222
1223 Example HTTP/RPC
1224 ''''''''''''''''
1225
1226 Query:
1227
1228 .. code-block:: http
1229
1230     PATCH /dnsapi/feedents/2 HTTP/1.1
1231     Content-Type: application/x-www-form-urlencoded
1232     Content-Length: 50
1233
1234     trxid=1370416133&nonterm[]=_udp&nonterm[]=_sip.udp
1235
1236 Response:
1237
1238 .. code-block:: http
1239
1240     HTTP/1.1 200 OK
1241     Content-Type: text/javascript; charset=utf-8
1242
1243     {"result":true}
1244
1245 ``feedEnts3``
1246 ~~~~~~~~~~~~~
1247
1248 Same as :ref:`remote-feedents`, but provides NSEC3 hashing
1249 parameters. Note that salt is BYTE value, and can be non-readable text.
1250
1251 -  Mandatory: No
1252 -  Parameters: trxid, domain_id, domain, times, salt, narrow, nonterm
1253 -  Reply: true for success, false for failure
1254
1255 Example JSON/RPC
1256 ''''''''''''''''
1257
1258 Query:
1259
1260 .. code-block:: json
1261
1262     {"method":"feedEnts3","parameters":{"domain_id":2,"domain":"example.com","times":1,"salt":"9642","narrow":false,"trxid":1370416356,"nonterm":["_sip._udp","_udp"]}}
1263
1264 Response:
1265
1266 .. code-block:: json
1267
1268     {"result":true}
1269
1270 Example HTTP/RPC
1271 ''''''''''''''''
1272
1273 Query:
1274
1275 .. code-block:: http
1276
1277     PATCH /dnsapi/2/example.com HTTP/1.1
1278     Content-Type: application/x-www-form-urlencoded
1279     Content-Length: 78
1280
1281     trxid=1370416356&times=1&salt=9642&narrow=0&nonterm[]=_sip._udp&nonterm[]=_udp
1282
1283 Response:
1284
1285 .. code-block:: http
1286
1287     HTTP/1.1 200 OK
1288     Content-Type: text/javascript; charset=utf-8
1289
1290     {"result":true}
1291
1292 ``startTransaction``
1293 ~~~~~~~~~~~~~~~~~~~~
1294
1295 Starts a new transaction. Transaction ID is chosen for you. Used to
1296 identify f.ex. AXFR transfer.
1297
1298 -  Mandatory: No
1299 -  Parameters: domain_id, domain, trxid
1300 -  Reply: true for success, false for failure
1301
1302 Example JSON/RPC
1303 ''''''''''''''''
1304
1305 Query:
1306
1307 .. code-block:: json
1308
1309     {"method":"startTransaction","parameters":{"trxid":1234,"domain_id":1,"domain":"example.com"}}
1310
1311 Response:
1312
1313 .. code-block:: json
1314
1315     {"result":true}
1316
1317 Example HTTP/RPC
1318 ''''''''''''''''
1319
1320 Query:
1321
1322 .. code-block:: http
1323
1324     POST /dnsapi/starttransaction/1/example.com HTTP/1.1
1325     Content-Type: application/x-www-form-urlencoded
1326     Content-Length: 10
1327
1328     trxid=1234
1329
1330 Response:
1331
1332 .. code-block:: http
1333
1334     HTTP/1.1 200 OK
1335     Content-Type: text/javascript; charset=utf-8
1336
1337     {"result":true}
1338
1339 ``commitTransaction``
1340 ~~~~~~~~~~~~~~~~~~~~~
1341
1342 Signals successful transfer and asks to commit data into permanent
1343 storage.
1344
1345 -  Mandatory: No
1346 -  Parameters: trxid
1347 -  Reply: true for success, false for failure
1348
1349 Example JSON/RPC
1350 ''''''''''''''''
1351
1352 Query:
1353
1354 .. code-block:: json
1355
1356     {"method":"commitTransaction","parameters":{"trxid":1234}}
1357
1358 Response:
1359
1360 .. code-block:: json
1361
1362     {"result":true}
1363
1364 Example HTTP/RPC
1365 ''''''''''''''''
1366
1367 Query:
1368
1369 .. code-block:: http
1370
1371     POST /dnsapi/committransaction/1234 HTTP/1.1
1372     Content-Type: application/x-www-form-urlencoded
1373     Content-Length: 0
1374
1375 Response:
1376
1377 .. code-block:: http
1378
1379     HTTP/1.1 200 OK
1380     Content-Type: text/javascript; charset=utf-8
1381
1382     {"result":true}
1383
1384 ``abortTransaction``
1385 ~~~~~~~~~~~~~~~~~~~~
1386
1387 Signals failed transaction, and that you should rollback any changes.
1388
1389 -  Mandatory: No
1390 -  Parameters: trxid
1391 -  Reply: true for success, false for failure
1392
1393 Example JSON/RPC
1394 ''''''''''''''''
1395
1396 Query:
1397
1398 .. code-block:: json
1399
1400     {"method":"abortTransaction","parameters":{"trxid":1234}}
1401
1402 Response:
1403
1404 .. code-block:: json
1405
1406     {"result":true}
1407
1408 Example HTTP/RPC
1409 ''''''''''''''''
1410
1411 Query:
1412
1413 .. code-block:: http
1414
1415     POST /dnsapi/aborttransaction/1234 HTTP/1.1
1416     Content-Type: application/x-www-form-urlencoded
1417     Content-Length: 0
1418
1419 Response:
1420
1421 .. code-block:: http
1422
1423     HTTP/1.1 200 OK
1424     Content-Type: text/javascript; charset=utf-8
1425
1426     {"result":true}
1427
1428 ``calculateSOASerial``
1429 ~~~~~~~~~~~~~~~~~~~~~~
1430
1431 Asks you to calculate a new serial based on the given data and update
1432 the serial.
1433
1434 -  Mandatory: No
1435 -  Parameters: domain,sd
1436 -  Reply: true for success, false for failure
1437
1438 Example JSON/RPC
1439 ''''''''''''''''
1440
1441 Query:
1442
1443 .. code-block:: json
1444
1445     {"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}}}
1446
1447 Response:
1448
1449 .. code-block:: json
1450
1451     {"result":2013060501}
1452
1453 Example HTTP/RPC
1454 ''''''''''''''''
1455
1456 Query:
1457
1458 .. code-block:: http
1459
1460     POST /dnsapi/calculatesoaserial/unit.test HTTP/1.1
1461     Content-Type: application/x-www-form-urlencoded
1462     Content-Length: 198
1463
1464     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
1465
1466 Response:
1467
1468 .. code-block:: http
1469
1470     HTTP/1.1 200 OK
1471     Content-Type: text/javascript; charset=utf-8
1472
1473     {"result":2013060501}
1474
1475 ``directBackendCmd``
1476 ~~~~~~~~~~~~~~~~~~~~
1477
1478 Can be used to send arbitrary commands to your backend using
1479 :doc:`../dnssec/pdnsutil`.
1480
1481 -  Mandatory: no
1482 -  Parameters: query
1483 -  Reply: anything but boolean false for success, false for failure
1484
1485 Example JSON/RPC
1486 ''''''''''''''''
1487
1488 Query:
1489
1490 .. code-block:: json
1491
1492     {"method":"directBackendCmd","parameters":{"query":"PING"}}
1493
1494 Response:
1495
1496 .. code-block:: json
1497
1498     {"result":"PONG"}
1499
1500 Example HTTP/RPC
1501 ''''''''''''''''
1502
1503 Query:
1504
1505 .. code-block:: http
1506
1507     POST /dnsapi/directBackendCmd HTTP/1.1
1508     Content-Type: application/x-www-form-urlencoded
1509     Content-Length: 10
1510
1511     query=PING
1512
1513 Response:
1514
1515 .. code-block:: http
1516
1517     HTTP/1.1 200 OK
1518     Content-Type: text/javascript; charset=utf-8
1519
1520     {"result":"PONG"}
1521
1522 ``getAllDomains``
1523 ~~~~~~~~~~~~~~~~~
1524
1525 Get DomainInfo records for all domains in your backend.
1526
1527 -  Mandatory: no
1528 -  Parameters: include_disabled
1529 -  Reply: array of DomainInfo
1530
1531 Example JSON/RPC
1532 ''''''''''''''''
1533
1534 Query:
1535
1536 .. code-block:: json
1537
1538     {"method": "getAllDomains", "parameters": {"include_disabled": true}}
1539
1540 Response:
1541
1542 .. code-block:: json
1543
1544     {"result":[{"id":1,"zone":"unit.test.","masters":["10.0.0.1"],"notified_serial":2,"serial":2,"last_check":1464693331,"kind":"native"}]}
1545
1546 Example HTTP/RPC
1547 ''''''''''''''''
1548
1549 Query:
1550
1551 .. code-block:: http
1552
1553     GET /dnsapi/getAllDomains?includeDisabled=true HTTP/1.1
1554
1555 Response:
1556
1557 .. code-block:: http
1558
1559     HTTP/1.1 200 OK
1560     Content-Type: text/javascript; charset=utf-8
1561     Content-Length: 135
1562     {"result":[{"id":1,"zone":"unit.test.","masters":["10.0.0.1"],"notified_serial":2,"serial":2,"last_check":1464693331,"kind":"native"}]}
1563
1564 ``searchRecords``
1565 ~~~~~~~~~~~~~~~~~
1566
1567 Can be used to search records from the backend. This is used by web api.
1568
1569 -  Mandatory: no
1570 -  Parameters: pattern, maxResults
1571 -  Reply: same as :ref:`remote-lookup` or false to indicate failed
1572    search
1573
1574 Example JSON/RPC
1575 ''''''''''''''''
1576
1577 Query:
1578
1579 .. code-block:: json
1580
1581     {"method":"searchRecords","parameters":{"pattern":"www.example*","maxResults":100}}
1582
1583 Response:
1584
1585 .. code-block:: json
1586
1587     {"result":[{"qtype":"A", "qname":"www.example.com", "content":"203.0.113.2", "ttl": 60}]}
1588
1589 Example HTTP/RPC
1590 ''''''''''''''''
1591
1592 Query:
1593
1594 .. code-block:: http
1595
1596     GET /dnsapi/searchRecords?q=www.example*&maxResults=100 HTTP/1.1
1597
1598 Response:
1599
1600 .. code-block:: http
1601
1602     HTTP/1.1 200 OK
1603     Content-Type: text/javascript; charset=utf-8
1604
1605     {"result":[{"qtype":"A", "qname":"www.example.com", "content":"203.0.113.2", "ttl": 60}]}
1606
1607
1608 ``getUpdatedMasters``
1609 ~~~~~~~~~~~~~~~~~~~~~
1610
1611 Used to find out any updates to master domains. This is used to trigger notifications in master mode.
1612
1613 -  Mandatory: no
1614 -  Parameters: none
1615 -  Reply: array of DomainInfo or at least the ``id``, ``zone``, ``serial`` and ``notified_serial`` fields
1616
1617 Example JSON/RPC
1618 ''''''''''''''''
1619
1620 Query:
1621
1622 .. code-block:: json
1623
1624     {"method": "getUpdatedMasters", "parameters": {}}
1625
1626 Response:
1627
1628 .. code-block:: json
1629
1630     {"result":[{"id":1,"zone":"unit.test.","masters":["10.0.0.1"],"notified_serial":2,"serial":2,"last_check":1464693331,"kind":"master"}]}
1631
1632 Example HTTP/RPC
1633 ''''''''''''''''
1634
1635 Query:
1636
1637 .. code-block:: http
1638
1639     GET /dnsapi/getUpdatedMasters HTTP/1.1
1640
1641 Response:
1642
1643 .. code-block:: http
1644
1645     HTTP/1.1 200 OK
1646     Content-Type: text/javascript; charset=utf-8
1647     Content-Length: 135
1648     {"result":[{"id":1,"zone":"unit.test.","masters":["10.0.0.1"],"notified_serial":2,"serial":2,"last_check":1464693331,"kind":"master"}]}
1649
1650 ``getUnfreshSlaveInfos``
1651 ~~~~~~~~~~~~~~~~~~~~~~~~
1652
1653 Used to find out if slave zones need checking of the master's SOA Serial.
1654
1655 -  Mandatory: no
1656 -  Parameters: none
1657 -  Reply: array of DomainInfo or at least the ``id``, ``zone``, ``serial`` and ``last_check`` fields
1658
1659 Example JSON/RPC
1660 ''''''''''''''''
1661
1662 Query:
1663
1664 .. code-block:: json
1665
1666     {"method": "getUnfreshSlaveInfos", "parameters": {}}
1667
1668 Response:
1669
1670 .. code-block:: json
1671
1672     {"result":[{"id":1,"zone":"unit.test.","masters":["10.0.0.1"],"serial":2,"last_check":1464693331,"kind":"slave"}]}
1673
1674 Example HTTP/RPC
1675 ''''''''''''''''
1676
1677 Query:
1678
1679 .. code-block:: http
1680
1681     GET /dnsapi/getUnfreshSlaveInfos HTTP/1.1
1682
1683 Response:
1684
1685 .. code-block:: http
1686
1687     HTTP/1.1 200 OK
1688     Content-Type: text/javascript; charset=utf-8
1689     Content-Length: 135
1690     {"result":[{"id":1,"zone":"unit.test.","masters":["10.0.0.1"],"serial":2,"last_check":1464693331,"kind":"slave"}]}
1691
1692 ``setFresh``
1693 ~~~~~~~~~~~~
1694
1695 Called when a slave freshness check succeeded. This does not indicate the
1696 zone was updated on the master.
1697
1698 -  Mandatory: No
1699 -  Parameters: id
1700 -  Reply: true for success, false for failure
1701
1702 Example JSON/RPC
1703 ''''''''''''''''
1704
1705 Query:
1706
1707 .. code-block:: json
1708
1709     {"method":"setFresh","parameters":{"id":1}}
1710
1711 Response:
1712
1713 .. code-block:: json
1714
1715     {"result":true}
1716
1717 Example HTTP/RPC
1718 ''''''''''''''''
1719
1720 Query:
1721
1722 .. code-block:: http
1723
1724     PATCH /dnsapi/setFresh/1 HTTP/1.1
1725     Content-Type: application/x-www-form-urlencoded
1726     Content-Length: 0
1727
1728 Response:
1729
1730 .. code-block:: http
1731
1732     HTTP/1.1 200 OK
1733     Content-Type: text/javascript; charset=utf-8
1734
1735     {"result":true}
1736
1737
1738 Examples
1739 --------
1740
1741 Scenario: SOA lookup via pipe, unix or zeromq connector
1742 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1743
1744 Query:
1745
1746 .. code-block:: json
1747
1748     {
1749       "method": "lookup",
1750       "parameters": {
1751          "qname": "example.com",
1752          "qtype": "SOA",
1753          "zone_id": "-1"
1754       }
1755     }
1756
1757 Reply:
1758
1759 .. code-block:: json
1760
1761     {
1762       "result":
1763        [
1764          { "qtype": "SOA",
1765            "qname": "example.com",
1766            "content": "dns1.icann.org. hostmaster.icann.org. 2012080849 7200 3600 1209600 3600",
1767            "ttl": 3600,
1768            "domain_id": -1
1769          }
1770        ]
1771     }
1772
1773 Scenario: SOA lookup with HTTP connector
1774 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1775
1776 Query:
1777
1778 ::
1779
1780     /dns/lookup/example.com/SOA
1781
1782 Reply:
1783
1784 .. code-block:: json
1785
1786     {
1787       "result":
1788        [
1789          { "qtype": "SOA",
1790            "qname": "example.com",
1791            "content": "dns1.icann.org. hostmaster.icann.org. 2012080849 7200 3600 1209600 3600",
1792            "ttl": 3600,
1793            "domain_id": -1
1794          }
1795        ]
1796     }