rcodezero

ISP/REGISTRARS

Choose from three different PRO products including 24/7 emergency hotline for highest security.

REGISTRIES

Use our TLD product as secondary Anycast to your existing DNS infrastructure.

ENTERPRISES

Our STARTER, MEDIUM & LARGE products are available as a cost-effective solution for a small number of zones.

References

Company

Information about ipcom.

Team & Contact

Get to know our RcodeZero DNS team.

News & Events

Current news and upcoming events.

FAQ

Frequently asked questions and answers about RcodeZero DNS.

Documentation

Here you can find documentations and workflows.

Contact

Do you have any questions? Contact us.

Search
Deutsch English
Login
rcodezero
Products
ISP/REGISTRARS
REGISTRIES
ENTERPRISES
References
About us
Company
Team & Contact
News & Events
Support
FAQ
Documentation
Contact

Deutsch

Already have an account? Login

Documentation & Workflow (Status July 2023)

1. OPENAPI 3.0 SPECIFICATION

This API is documented in the OpenAPI 3.0 format. The OpenAPI 3.0 Json file is available at https://my.rcodezero.at/openapi/rcode0api-latest.json.

Changelog and a rendered version of the API is available https://my.rcodezero.at/openapi/.

2. OVERVIEW

RcodeZero DNS is a globally distributed, easy to use Anycast DNS network. The RcodeZero Anycast network is provisioned via web interface or REST API and supports:

  • Primary zones: No infrastructure on customer side is needed, the configuration of the zone is done via web interface or API.
  • Secondary zones: This requires a (hidden) primary name server on customer side. The RcodeZero network receives DNS NOTIFYs on zone changes, and subsequently fetches the updated zone via AXFR zone transfer. Initially the zone must be provisioned on Rcodezero via web interface or API.

Both, primary and secondary zones, can use our DNSSEC signing service. Secondary zones can also be pre-signed.

  • 3. INFRASTRUCTURE


3.1. ANYCAST CLOUDS

The RcodeZero Anycast Network provides DNS service via two independent clouds. For resilience, each cloud has its own IP range (IPv4 and IPv6) in two separated autonomous systems (AS), a different set of locations and a separate routing policy. Each zone provisioned on RcodeZero is added to both clouds and the Anycast IP addresses are returned to the customer.

 

 

3.2. CONTROL SERVERS

The "Control Servers" are the “gateways” to the RcodeZero DNS Network. For secondary zones, the control servers consume DNS NOTIFYs and transfer zones from the customer's primary name servers, and redistribute the zones in the anycast network. Hence, the customer has to provision its primary name servers to send NOTIFYs to, and allow AXFR from RcodeZero. The respective IP addresses can be found in the RcodeZero DNS Dashboard (https://my.rcodezero.at/).

 

 

3.3. TEST SYSTEM

RcodeZero DNS provides a functionally identical test system (OT&E). This is intended 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 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 50+ Anycast nodes).
  • May use newer software to beta-test new features.

 

Please create accounts for the test system yourself at https://my-test.rcodezero.at/register. Then OpenAPI specification can be found at https://my-test.rcodezero.at/openapi/.

4. REST-API


4.1. AUTHENTICATION

This API uses Bearer Token for authentication. Obtain your Bearer token via the web interface https://my.rcodezero.at/ -> Settings -> API. 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.

 

 

4.2. RATE LIMITS

  • IP addresses (IPv4, for IPv6 the corresponding /64) originating unauthorized requests will be blocked for 10 minutes after 10 requests.
  • Authenticated requests are limited to 1500 requests per minute and account. Request over the limit will be rejected with the HTTP error code 429.
  • Requests to the reports/ and stats/ endpoints are limited to 60 requests per minute. For mass downloading of zone statistics please use the /api/v2/reports/* endpoints. 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: 1500
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: 1500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1523441309

 

 

4.3. IP FILTER

Accounts can be limited to defined Source IP addresses or subnet. This can be configured via the web interface https://my.rcodezero.at/ -> Settings -> IP Filter. Requests from other IP addresses are rejected with HTTP error code 401.

 

 

4.4. 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.

 

 

4.5. 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>"
}

5. WORKFLOWS

5.1. PRIMARY ZONES

 

  • Add zone via API or web
  • Configure RRSets via API or web (the serial number of the SOA-record is updated automatically)
  • Changes are distributed automatically to the RcodeZero Anycast Network. Changes can take up to two minutes until the become visible in the DNS.

 

 

5.2. SECONDARY ZONES

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

 

  • Configure your firewalls to allow access for RcodeZero. In the firewall you have to allow port 53 UDP and port 53 TCP to your primary name server. The respective RcodeZero Control Server IP address can be found in https://my.rcodezero.at/ -> Dashboard.
  • Configure your primary name server(s) to allow zone transfers from the RcodeZero Control Server (allow-axfr).
  • Configure your primary name server(s) to send NOTIFYs to the RcodeZero Control Server (also-notify).
  • Add the zone to RcodeZero via the API or web, specifying the IP address(es) of the primary name server(s)
  • Add the RcodeZero name server(s) to the NS RRSet of your zone. Either use the RcodeZero host names mentioned in the dashboard or use your own branded name servers (vanity DNS). For branded nameservers, make sure their A/AAAA records point to the RcodeZero anycast IP addresses.

 

Example using RcodeZero name servers:

 

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

 

Example using vanity names:

 

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

Zone 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 you use your own IP prefix, obviously 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 name servers. 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 primary 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. A refresh value of 24h is used if the original value is lower than 24h. In all cases, it is mandatory for the primary 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. Even in this case, the serial MUST be increased on zone changes to ensure consistent zones over all RcodeZero nameservers.

 

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.

5.3. DNSSEC

RcodeZero supports pre-signed secondary zones. In this case the zone is signed on the primary name server on customer side. RcodeZero will automatically detect pre-signed zones and handle them correctly.

 

Both, primary and secondary zones, can use the RcodeZero DNSSEC signing service. In that case, the DNSSEC workflow contains some asynchronous processes. These processes generate notifications when they have finished and other transactions can be performed. The following notifications are defined:

 

  • DSSEEN: We saw the active DS-Record for the first time in the parent zone. This means the the initial signing or the KSK rollover process finished successfully. A new KSK rollover can be performed now.
  • DSUPDATE: When the DNSSEC signing service is activated, we generate the keys and sign the zone. Only after certain TTLs expire it is safe to publish the DS record in the parent zone. Hence, when the DSUPDATE notification is generated, it is safe to publish the DS record in the parent zone. The delay of when it is safe to publish the DS records is calculated with the following rule: max(soaminimum of zone, max TTL of zone records). Zones that get signed during the creation of the zone are not affected by this delay, only existing zones that are being signed have this delay to make sure that there are no issues.
  • 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 notifications 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 e-mail is sent to this address.

 

So, what is the typical RcodeZero DNSSEC workflow?

  • Add a domain: POST /zones
  • Sign the domain: POST /zones/<zone>/sign
  • Poll the message queue until the DSUPDATE event for the zone is retrieved: GET /messages
  • Acknowledge the message: DELETE /messages/<id>
  • Get the zone details to grab the DNSKEY/DS record: GET /zones/<zone>
  • Add DS to parent zone (by providing DS/DNSKEY to your registrar or the respective TLD)
  • Acknowledge that the DNSKEY/DS has been added to the parent zone (this automatically deletes all DSUPDATE notification for this domain from the message queue): POST /zones/<zone>/dsupdate

 

Note: If you add a zone and already know that this zone will be signed, then it is better to set the "dnssec=1" parameter while adding the zone. This way, it is safe to immediately publish the DS record in the parent zone leading to a much shorter workflow:

  • Add a domain: POST /zones with query parameter dnssec=1
  • Extract the DNSKEY/DS record from the response
  • Add DS to parent zone (by providing DS/DNSKEY to your registrar or the respective TLD)
  • Acknowledge that the DNSKEY/DS has been added to the parent zone (this automatically deletes all DSUPDATE notification for this domain from the message queue): POST /zones/<zone>/dsupdate

 

5.3.1. Important DNSSEC aspects


·         Serial Handling for Zones Signed by RcodeZero

DNSSEC requires periodical resigning of the zone. If a zone uses the DNSSEC signing service of RcodeZero, on every resigning we have to increase the zone's serial. This is done on every Thursday at 00:00 UTC by adding the number of weeks since 1.1.1970 (Unix time). This increased serial is only visibly on the name servers when queried via DNS protocol. In our internal database we keep the unmodified serial (which is identical to the serial on the customer's primary name server, in case of secondary zones). When a secondary zone gets updated on the customer's primary name server, the serial must be increased - compared to the serial stored internally in our database.

 

RcodeZero allows customers to AXFR the signed zone out from RcodeZero (Outbound XFR/Customer Secondaries). If a customer AXFRs the signed zone from our Control Server, and this zone gets unsigned, the customer must force a retransfer on its own Customer Secondaries. This is mandatory to ensure that the customer's secondary name servers are in sync with the RcodeZero name servers.

 

·         Serial Handling for Pre-Signed Zones (Only Supported for Secondary Zones)

If the customer re-signs the zone or updates the DNSKEY records, the serial MUST be increased so that RcodeZero AXFRs the zone with the new signatures/keys. Not doing so can lead to expired signatures on RcodeZero name servers. This is especially important if the customer uses PowerDNS for DNSSEC signing. PowerDNS by default does not increase the zone's serial on re-signing. PowerDNS re-signs the zone every Thursday at 00:00 UTC. So, either manually increase the zone's serial every Thursday, or configure PowerDNS to “fake” an increased serial for example by setting "default-soa-edit-signed=INCREMENT-WEEKS". Please see https://doc.powerdns.com/authoritative/dnssec/operational.html#soa-edit-ensure-signature-freshness-on-slaves and https://doc.powerdns.com/authoritative/dnssec/modes-of-operation.html#signatures for details about serial handling in PowerDNS. Further, make sure to increase the serial on the primary name server on DNSKEY related events, e.g. key roll-overs.

 

 ·         Hidden Primary

For zones using the DNSSEC signing service, the customers primary name server must be a "hidden" primary and the zone must not be delegated to that hidden primary. Further, if the zone is also hosted on a customer's secondary name servers, these name server must not transfer the zone from the customer's primary, but must transfer the signed zone from the RcodeZero Control Server. Both restrictions also apply for any parent zones that are provisioned on the customer's primary name server (i.e. .com is the parent zone of example.com). For details, why this also applies to parent zones see the following example:

 

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

 

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

 

Further, this name server acts as hidden primary 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.  IN  A  1.1.1.1
signed.example.com.      IN  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 primary 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 primary should not be queried by public resolvers – even for other zones.

5.4. ALIAS (ANAME) SUPPORT (deprecated)


ALIAS/ANAME is a feature to allow CNAME-like forwarding also on zone apex. ALIAS is the proprietary name introduced by the PowerDNS developers, ANAME is the name suggested in https://tools.ietf.org/html/draft-ietf-dnsop-aname. The IETF dnsop working group has decided to not standardize ANAME in favor of a client based solution using HTTPS/SVCB resource records. HTTPS/SVCB are currently defined in https://datatracker.ietf.org/doc/draft-ietf-dnsop-svcb-https/.

 

Note: Once HTTPS/SVCB is sufficiently supported by browser vendors, we plan to switch to the industry supported HTTPS/SVCB records and drop ALIAS support!

 

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. Due to caching in the name servers it may take several minutes until changes in the ALIAS target are reflected to the zone.

 

For Primary 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 primary 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.

 

Here is the sample code of the converter to integrate 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";

 

Hello, how can we help you?

optional
optional
Please enter the letters from the image below into the field below
Ticket # successfully created.
You will shortly receive an confirmation Email.

If you do not receive an Email, something went wrong. In that case please contact us by other means or try again later.

Additional nic.at products

Quicklinks

ENTERPRISES
ISP/REGISTRARS
REGISTRIES
FAQ
Login

Company

ipcom GmbH
Karlsplatz 1/2/9
1010 Vienna
UID-Nr.: ATU61437216

Contact

+43 1 294 00 40 -510
Contact form

Subscribe to newsletter

Subscribe to newsletter

By submitting this form I give my consent that my provided data will be processed as described in the privacy policy .

Facebook YouTube LinkedIn

© 2020 - 2025 RcodeZero DNS | Imprint | Terms of Service | Privacy Policy | Accessibility Statement | Sitemap