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/.
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:
Both, primary and secondary zones, can use our DNSSEC signing service. Secondary zones can also be pre-signed.
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.
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/).
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:
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/.
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.
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
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.
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.
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>"
}
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.
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.
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:
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?
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:
· 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.
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";
© 2020 - 2023 RcodeZero DNS | Imprint | Terms of Service | Privacy Policy | Sitemap