Back to top

RcodeZero DNS - REST API

OpenAPI 3.0 Specification

This API is documented in the OpenAPI 3.0 format. The OpenAPI 3.0 Json file is available here.

A rendered version of the API is available here

Changelog

Version Author Changes
1.0 Michael Braunoeder Initial Release v1 API
1.1 Michael Braunoeder Updated ALIAS documentation
1.2 Michael Braunoeder Added base URL, use ISO 8601 as timestamp format
1.3 Michael Braunoeder Clarification for SOA Updates
1.4 Michael Braunoeder fixed ID in zonelist, ttl in rrset updates
1.5 Michael Braunoeder add names/types parameter to get RRsets call
1.6 Michael Braunoeder add zones/{zone}/outbound and tsig/out calls to configure outgoing zonetransfer per zone
1.7 Michael Braunoeder added link to OpenAPI 3.0 specification
1.8 Michael Braunoeder added ‘test’ parameter to add zone
1.9 Michael Braunoeder added ‘DELETE zones/{zone}/rrsets’ to remove all rrsets for a given zone

Overview

RcodeZero DNS is a globally distributed, easy to use anycast DNS network.

RcodeZero zone types:

  • Master Zones: no infrastructure on customer side is needed, configuration of zone entirely via web interface or API.

  • Slave Zones: requires a hidden master name server on customer side. The RcodeZero Network receives DNS NOTIFYs on changes, and subsequently performs transfers via Zone transfer (initial zone add is performed via API or Web)

The RcodeZero Anycast-Network is provisioned via web interface or REST-API.

Infrastructure

Clouds

The RcodeZero Anycast Network provides DNS service via two independend clouds. For resilience, each cloud has its own IP range (IPv4 and IPv6), a different set of locations and a seperate routing policy.

Cloud Hostname IPv4 IPv6
1 sec1.rcode0.net 192.174.68.100 2001:67c:1bc::100
2 sec2.rcode0.net 176.97.158.100 2001:67c:10b8::100

Control Servers

The Control Server are the “gateways” to the RcodeZero DNS Network. The control server consumes DNS Notifies from customers, transfers zone from hidden masters and redistributes zone in the anycast network.

DNS NOTIFYs must be sent to the following IP addresses:

NOTIFY target IP address
IPv4 83.136.34.7
IPv6 2a02:850:8::6

Zone transfers must be allowed from the following IP ranges:

Transfer Source Net range
IPv4 83.136.34.0/27
IPv6 2a02:850:8::/47

to retrieve the zone from the RcodeZero Anycast Network accepts NOTFIYs and request AXFR from the following IP adresses:

NOTIFY source/AXFR target IP address
IPv4 83.136.34.10
IPv6 2a02:850:9::8

Test System

RcodeZero provides a functionally identical test system. This is intended to in order to ‘play’ with the system or the API, and allows new customers to try out RcodeZero DNS. The test system is available at https://my-test.rcodezero.at, the server addresses are as follows:

Server Hostname IPv4 IPv6
DNS Unicast Nameserver 1 sectest1.rcode0.net 83.136.32.80 2a02:850:4:3::14
DNS Unicast Nameserver 2 sectest2.rcode0.net 83.136.32.81 2a02:850:4:3::15
NOTIFY target IP address
IPv4 83.136.34.26
IPv6 2a02:850:9::8
Transfer Source Net range
IPv4 83.316.34.30
IPv6 2a02:850:9::12
NOTIFY source/AXFR target IP address
IPv4 83.136.34.30
IPv6 2a02:850:9::12

The limitations of the test system with respect to the production system are:

  • No Service Level Agreements. While we strive to keep the test system available all the time, there may be outages due to deployment of new software revisions or other operational reasons.

  • Only 2 unicast name server nodes (the production system has 20+ anycast nodes).

  • May use newer software to beta-test new features.

Workflows

Master (Primary) Zones

  1. Add zone via API or web

  2. Configure RRSets via API or web (the serial number of the SOA-record is updated automatically)

  3. Changes are distributed automatically to the RcodeZero Anycast Network. Changes can take up to two minutes until the become visible in the DNS.

Slave (Secondary) Zones

This is a suggested workflow to activate RcodeZero Anycast DNS for a slave zone. Of course this work flow can be adopted to fit your needs.

  1. Configure your master name server(s) to allow zone transfers towards our control name server (IP addresses listed below). If the master name server is a “hidden master”, also allow our control name server to query the master(s) (for serial number checks).

  2. Add the zone via the API or web

  3. Add the RcodeZero name server(s) to the NS RRSet of your zone. Either use the RcodeZero host names “sec1.rcode0.net” and “sec2.rcode0.net”, or use your own branded name servers. For branded nameservers, make sure their A/AAAA records point to the IP addresses indicated above.

Example with RcodeZero hostnames:

example.com.  IN  NS sec1.rcode0.net.
example.com.  IN  NS sec2.rcode0.net.

Example with RcodeZero hostnames:

example.com.  IN  NS ns1.provider-xyz.net.
example.com.  IN  NS ns2.provider-xyz.net.

ns1.provider-xyz.net. IN A    192.174.68.100
ns1.provider-xyz.net. IN AAAA 2001:67c:1bc::100
ns2.provider-xyz.net. IN A    176.97.158.100
ns2.provider-xyz.net. IN AAAA 2001:67c:10b8::100

NOTE: If your contract includes dedicated IP addresses or hosting your own network, obiously you should use the respective addresses.

Instead of adding RcodeZero Secondary DNS as additional name server by adding a new NS record to the zones, you can also replace one of your existing name servers with RcodeZero. In this case, you only have to change the A/AAAA records of the existing name server hostname to point to our anycast IP addresses. This does not require any changes to zones and registry – as long as the hostname is outside the zone and thus requires no glue records.

The master name server must send DNS NOTIFYs in order to trigger zone transfers. If NOTIFYs are not sent, the control name server checks for zone updates every “refresh” seconds, according to the value of the “refresh” field in the zone’s SOA record. To reduce SOA-query load on the control name server, a refresh value of 24h is used if the original value is lower than 24h. In all cases, it is mandatory for the master name server to increase the serial on zone changes. Otherwise, the changes will be ignored by RcodeZero. Additionally, zone transfers can be requested via the “retrieve” command on the API interface. In this case, the serial is ignored and the zone is transferred and deployed to the anycast nodes even if the serial has not increased.

NOTE: Even after a successful zone transfer, the Anycast name servers may respond with stale data for a few minutes due to caching in the name server software.

DNSSEC

RcodeZero supports pre-signed zones (the zone is signed on the hidden master on customer side) or signs (if wanted) the zone before distributing it on the RcodeZero network. At the moment only slave zones can be signed with the RcodeZero DNSSEC service, master zones will be supported soon.

The DNSSEC workflow contains some asynchronous processes. These processes generate notifies when they have finished and other transactions can be performed. The following notifies are used:

  • DSSEEN: We see the active DS-Record in the parent zone and finish the initial signing or key rollover process. A new KSK rollover can now be performed.

  • DSUPDATE: A new KSK has been pre-published and it is save now to publish the DS record in the parent zone

  • DSREMOVED: The DS record of the active KSK has been removed from the parent zone and the TTLs and the propagation delay has been expired. It is save now to perform an unsign transaction.

The notifies are added to the message queue of your account and can be retrieved and acknowledged via API or web interface. If your account has a notification E-Mail address configured (via web interface) an additional email is sent to this address.

So, what is the typical RcodeZero DNSSEC workflow?

  1. add a domain: POST /zone

  2. sign the domain: POST /zone/<zone>/sign

  3. poll the message queue until the DSUPDATE event for the zone is retrieved: GET /messages

  4. ack the message: DELETE /messages/<id>

  5. get the zone details to grab the DNSKEY/DS record: GET /zone/<zone>

  6. Add the DNSKEY/DS to the parent zone

  7. Acknowledge that the DNSKEY/DS has been added to the parent zone: POST /zone//dsupdate

Important DNSSEC aspects

  • Serial

DNSSEC requires periodical resigning of the zone, thus the zone serial number needs to be increased. Therefore, for signed zones the zone’s serial announced by the Anycast nodes will be greater than the serial number on the customers hidden master server. But, a higher serial on the anycast node is not an indication that the zone is up2date. Therefore, every time the serial is increased on the hidden master, the new serial number should be greater than the serial on the anycast node.

A convenient solution is to use the Unix epoch at the time of the zone update as the zone serial numer. This eases debugging and ensures proper zone updates even after un-signing a zone.

  • Hidden Master

For zones using the DNSSEC signing service, the customers master name server must be a hidden master and the zone must not be delegated to that hidden master. Further, if the zone is also hosted on a customers name server, this name server must not transfer the zone from the (customer) hidden master, but must transfer the signed zone from the RcodeZero Anycast control server (see “set secondaries” below). This is also required for parent zones.

Consider the following problematic example:

The name server ns1.isp.com hosts the zone example.com:

zone example.com:
aexample.com.        NS ns1.isp.com.
signed.example.com. NS sec1.rcode.net.

Further, this name server acts as hidden master for the zone signed.example.com. The zone is unsigned delivered to RcodeZero, and signed by RcodeZero. Therefore, the zone’s name server only point to the RcodeZero anycast name servers:

zone signed.example.com:
www.signed.example.com. A  1.1.1.1
signed.example.com.     NS sec1.rcode.net.

The problem here is, that resolvers which trace www.signed.example.com from the root zone on its way also query ns1.isp.com. Although ns1.isp.com is a hidden master for signed.example.com, it will authoritatively answer the request for www.signed.example.com without DNSSEC signatures. Therefore the validation will fail.

The hidden master should not be queried by public resolvers – even for other zones.

ALIAS (ANAME) support

ALIAS/ANAME is a feature to allow CNAME-like forwarding also on zone appex. ALIAS is the proprietary name introduced by the PowerDNS developers, ANAME will the new name once the feature becomes an RFC. See https://tools.ietf.org/html/draft-ietf-dnsop-aname-01.

RcodeZero supports the ALIAS record using the proprietary record type 65401 as implemented within PowerDNS. When RcodeZero receives an A or AAAA request for a label which does have an ALIAS record, RcodeZero resolves the ALIAS target and responds to the request with the resolved ALIAS target.

For Master-DNS it is quite simple to use: just select ALIAS as record type and provide the ALIAS target (a hostname, no IP address) as FQDN with trailing dot.

For Secondary-DNS just provision the ALIAS record on your master name server. How this is done exactly depends on your name server software. When using PowerDNS >= 4.0 you can just insert an ALIAS type into the records table. For other name server software you can specify the ALIAS in a generic, encoded form. For example: example.com should be an ALIAS to www.example.com:

PDNS >=4.0:

example.com. IN ALIAS www.example.com.

PDNS <4.0, Bind9:

example.com. IN TYPE65401 # 17 03777777076578616d706c6503636f6d00

Note: Using ALIAS with Secondary-DNS is not supported on DNSSEC signed zone - regardless if you sign yourself or use the DNSSEC signing service of RcodeZero! ALIAS with Secondary-DNS will work only on unsigned zones.

As ALIAS support is currently quite low, we provide you with an online converter:

https://api.rcode0.net/alias.php?alias=www.example.com

Here is the sample code of the converter to intgrate it into your systems:

<?php

  $alias = "www.exmaple.com.";

  $alias = trim($alias," \t\n\r\0\x0B.");
  if (preg_match("/[^A-Za-z0-9-_.]/", $alias)) {
    die("ERROR: Invalid Characters. Allowed: A-Za-z0-9-_.\n");
  }
 

  $labels = explode(".",$alias);
  $enc="";

  foreach ($labels as $label) {
    if (strlen($label) > 63) {
      die("ERROR: label $label is longer than 63 characters!\n");
    }

    // encode the length
    $enc .= sprintf('%02x', strlen($label));

    // encode the label
    foreach (str_split($label) as $char) {
      $enc .= sprintf('%02x', ord($char));
    }
  }

  // add trailing 00
  $enc .= sprintf('%02x', 0);

  echo "IN A TYPE65401 \# " . strlen($enc)/2 . " " . $enc . "\n";

?>

Debugging

For debugging problems, it is essential to understand how Secondary-DNS works. Read the overview section in the beginning to understand which components are involved.

Q: How can I check if some zones cause problems?

A: The web interface provides a page page called “Problematic Zones”. Alternatively, an identical list is provided via the API call [/reports/problematiczones]

This report contains all your zones for which the control server failed to check the serial number or failed to transfer the zone. Additionally you will receive an email with problematic zones once a day (only if there are any problematic zones) .

Q: How can I check the status of a certain zone within the RcodeZero network?

A: First, you should check the serial of the zone on the control server (of course this implies, that the master server always increases the serial on zone changes). This can be done either by viewing the zone details on the web site or by querying the control server for the SOA record, e. g.:

dig @83.136.34.7 yourdomain.com SOA

If the serial is smaller than the serial on the master server, then possible problems can be that the control server is not allowed to query and transfer the zone from the master. Make sure to allow query and zone transfer from the control server IP addresses 83.136.34.7 and 2A02:850:8::6. The control server will check the zone’s SOA record every “refresh” seconds (minimum refresh value: 24 hours) or when NOTIFYs are received. Further, immediate zone transfers can be initiated by using the “retrieve” API call.

If the zone on the control server is up-to-date, you can also check the zone data on an anycast name server. Note that changes may take up to 5 minutes to show up on all nodes due to replication and name server caching.

dig @sec1.rcode0.net yourdomain.com SOA

Q: How long does it take until an updated zone is propagated to the individual anycast nodes?

A: Short answer: typically under 3 minutes.

Long answer: this depends on several facts and timers which needs to be accumulated:

  • DNS NOTIFY: On zone updates, the master server must send NOTIFYs with an increased serial number to our control server to initiate a zone transfer. The transfer will usually start immediately, but may take a few minutes in periods of heavy workload (lots of zone updates).

  • Zone data distribution: The control server will distribute the new zone date to all anycast nodes. This takes usually below 1 minute.

  • DNS Caching: Our name servers cache DNS responses for 4 minutes. Thus, if the domain was queried just before the zone was updated, the name server will respond with the old data for 4 minutes. Note: As anycast locations typically contain multiple load-balanced name servers, it can happen that some responses still contain the old data while some responses already contain the new data.

API

Base URL

The base URL for the API is

https://my.rcodezero.at/api/v1

Authentication

This API uses Bearer Token for authentication. Obtain your Bearer token via the web interface https://my.rcodezero.at/enableapi This token must be included as an HTTP Header in each API request.

Authorization: Bearer <token>

Unauthorized request will be rejected with HTTP error code 401.

Rate Limits

IP addresses (IPv4, for IPv6 the corresponding /64) originating unauthorized requests will be blocked for 10 minutes after 10 requests. Further requests will be rejected with the HTTP Error code 429.

Authenticated requests are limited to 200 requests per minute and IP address. Request over the limit will be rejected with the HTTP error code 429

The Rate Limit and the remaining requests are reported in every response with the headers

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199

If a request has been rejected an additional header contains the timestamp when the limit will be reseted:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1523441309

IP Filter

Accounts can be limited to defined Source IP addresses or subnet. This can be configured via the Webinterface. Requests from other IP addresses are rejected with HTTP error code 401.

Pagination

Request that might return a lot of data like GET /zones or GET /reports/problematiczones are paginated. To get the next page use the ?page parameter. The default number of items per page is 100 and can be changed via the ?page_size parameter.

Responses

The REST call return HTTP Status codes 2xx for successfull calls, and 4xx/5xx if an error occured.

If a call does not return objects (e.g. if a action is processed), the call return a structure with the attributes “status” and “message”. If the action has been processed without an error the response looks like

{
  "status": "ok",
  "message": "Zone testzone1.at successfully added"
}

Otherwise a “status: failed” with an error message will be returned

{
  "status": "failed",
  "message": <error message>
}