DDNS is a system for decentralized domain names supporting a full range of DNS Records. DDNS operates under the “dns:” service abbreviation in the Denarius NVS.

Because of Denarius’s secure and distributed blockchain the domain name records are completely decentralized and uncensorable and cannot be altered, revoked or suspended by any authority. Only a record’s owner can modify or transfer it to another owner, and a record’s owner is determined by whoever controls the private key to the associated payment address.

Only DDNS record owners can manage their records: change values, lease times, or delete them or transfer ownership to another D address. These actions can be performed using the Denarius NVS in the Denarius native wallet QT, or via the name_new or name_update JSON RPC commands in the Denarius JSON RPC API.

DDNS records can easily be retrieved from any Denarius wallet using JSONRPC or the QT, a standard RFC1034 DNS protocol is built in to every Denarius wallet.

 

Supported DNS zones

Technically, DDNS can support any DNS-zone or TLD. However, for seamless integration into a standard DNS tree, and to prevent collisions with existing DNS-zones, we currently recommend creating DDNS records only in the zones: *.d, *.dnr, *.king, *.ipfs, *.sys, *.denarii, *.btc, *.bitcoin

Current root zones supported by DDNS, and their intended purpose:

Accessing DDNS zones

There are several ways that DDNS domains can be reached:

 

Browser extensions

Several 3rd-party browser plugins exist which allow you to easily visit DDNS domains:

• None available currently, WIP

OpenNIC & OpenDNS

• Not available yet

Proxy servers

3rd-party proxy servers can provide access to DDNS zones:

• None currently available, WIP

 

 

 

Creating and maintaining a DNS record

Denarius’s built-in DNS server supports the following DNS record types:

Note: SOA, WKS, and SRV records are not directly supported by Denarius’s built-in DNS server.

To insert a DNS record into the Denarius blockchain, create (or update) a name->value pair under the “dns:” service abbreviation in the Denarius NVS as follows:

"name" : "dns:<your_name_here>"
"value" : "<list of NS-records>"

For example:

"name" : "dns:example.d"
"value" : "A=192.168.0.123,127.0.0.1|AAAA=2607:f8b0:4004:806::1001|NS=ns1.google.com|TTL=4001"

In this example the domain example.d is specified by:

• two A-records (192.168.0.123 and 127.0.0.1);
• one AAAA-record (2607:f8b0:4004:806::1001);
• one NS-record (ns1.google.com);
• a TTL record.

The records are separated by the default separator vertical bar or pipe (“|”). If necessary, you can redefine the separator by prefixing the value with ~<new separator character>. For example, if you wish to use a hash character “#” as a separator instead of a pipe you can assign it with “~#” at the start of the value as follows:

"value" : "~#A=192.168.0.123,127.0.0.1#AAAA=2607:f8b0:4004:806::1001#NS=ns1.google.com#TTL=4001"

Note, if you use the space character ” ” as a separator, you will not be able use it inside the fields. Therefore, you should select an appropriate symbol as a separator for your records instead.

As described above, each record can contain multiple values. In the provided example, the A-record contains two values, separated by a comma “,”. You can also redefine the value separator with ~<new separator character>. The following example demonstrates how to redefine the separator two times: slash “/” as record separator, and asterisk “*” as value separators for multiple TXT-records:

"value" : "~/TXT=~*This is text, Hello!*2nd text/MX=gmail.com:33,mx.microsoft.com:66/CNAME=denarius.io/A=192.168.0.100,127.0.0.1"

In the last example we’ve demonstrated the usage of a MX record. The value of MX contains a mail exchanger reference and priority, separated by a colon “:”. If priority is omitted, the default value is 1.

Also, intentionally omitted in the last example is a TTL record. The default value for TTL is 24 hours.

 

 

Naming requirements

Domain names may be formed from the set of lowercase alphanumeric ASCII characters (a-z, 0-9). In addition the hyphen (“-“) is permitted if it is surrounded by characters, digits or hyphens, although it is not to start or end a name. Only lowercase letters are valid.

Internationalized domain names

Internationalized domain names (Arabic, Chinese, Cyrillic, etc) are technically possible using punycode.

For example, if we want the following internationalized domain name:

dns:президент.d

Then we must transcribe it using a punycode converter and register the result:

dns:xn--d1abbgf6aiiy.d

Subdomains

A general challenge with distributed DNS is that anyone can allocate any unique name, allowing someone to register a subdomain for a domain that they do not own. To remedy this situation, DDNS has special ways to manage subdomains:

• A subdomain (SD) record in the DNS parent’s NVS value, permits lookup and resolution of the subdomain directly within the Denarius DNS subsystem e.g. SD=www,ftp,mx
• A nameserver (NS) record in the DNS parent’s NVS value, allows reference to external nameserver(s) managed by the domain owner, to provide authoritative lookup and resolution of the subdomain external to Denarius DNS e.g. NS=ns.example.com

Subdomain resolution is applied in the following order, recursively to all third-level subdomains and deeper:

1. First, check SD record in the parent’s DNS value for reference to the requested subdomain. If a reference for the subdomain is found then look up the subdomain within the Denarius NVS subsystem.
2. Next, check for nameserver (NS) record in the parent’s DNS value. If found, generate reference to external nameserver.
3. If no resolution results from SD or NS records, return as per parent domain (i.e. ignore subdomain prefix).

NOTE: When utilizing external nameservers, please take care with correct name resolution in those servers, including any gateway-suffixes.

 

Example 1 – parent contains SD and NS records

[1] dns:example.d -> A=1.2.3.4|SD=www,gopher|NS=ns.example.com
[2] dns:www.example.d -> A=5.6.7.8

In this case, subdomains will resolve as follows:

• example.d will be resolved by record [1], and return A=1.2.3.4
• www.example.d will be approved by record [1], resolved by record [2] and return A=5.6.7.8
• gopher.example.d will be approved by record [1], and not resolved, since NVS does not contain an appropriate DNS record. This will return NXDOMAIN.
• mail.example.d will not be approved by record [1], but the NS record will generate a reference to external server ns.example.com, which may or may not resolve this subdomain.

Thus a single record [1] supports flexible hybrid resolving:

• www is resolved by Denarius NVS.
• gopher is blocked.
• all others are resolved by delegated NS=ns.example.com.

 

Example 2 – parent contains SD record only

[1] dns:example.d -> A=1.2.3.4|SD=www,gopher
[2] dns:www.example.d -> A=5.6.7.8

In this case, subdomains will resolve as follows:

• example.d will be resolved by record [1], and return A=1.2.3.4
• www.example.d will be approved by record [1], resolved by record [2] and return A=5.6.7.8
• gopher.example.d will be approved by record [1], and not resolved, since NVS does not contain an appropriate DNS record. This will return NXDOMAIN.
• mail.example.d will not be approved by record [1], and (because of missing NS record) prefix “mail” will be ignored and resolve the same as example.d.

 

Example 3 – parent contains NS record only

[1] dns:example.d -> A=1.2.3.4|NS=ns.example.com
[2] dns:www.example.d -> A=5.6.7.8

In this case, subdomains will resolve as follows:

• example.d will be resolved by record [1], and return A=1.2.3.4
• www.example.d will not be approved by record [1], and will generate a reference to external server ns.example.com, which may or may not resolve this subdomain.
• Record [2] will be ignored, and will not participate in DNS resolution.
• mail.example.d will not be approved by record [1], and will generate a reference to external server ns.example.com, which may or may not resolve this subdomain.

 

Example 4 – parent contains no references to subdomain

[1] dns:example.d -> "A=1.2.3.4"
[2] dns:mx.example.d -> "A=5.6.7.8"

In this case, subdomains will resolve as follows:

• example.d -> “A=1.2.3.4”
• mx.example.d -> “A=1.2.3.4”
• www.example.d -> “A=1.2.3.4”
• upload.ftp.example.d -> “A=1.2.3.4”

Because record [1] does not contain any SD or NS records, all subdomains will be resolved to the “parent domain” example.d. Record [2] will be ignored, and will not participate in DNS resolution.

 

 

 

Integration of DDNS into a regular DNS tree

First, activate the RFC1034 DNS server in Denarius by specifing two optional parameters in the denarius.conf config file, DDNS and DDNSport:

ddns=1 # Run D DNS server. Default is 0 (don't run)
ddnsport=NNN # Port for D DNS, default is 5333

To integrate Denarius DNS server into a regular DNS tree, you can use full-service DNS or caching DNS. The standard Windows DNS-client is unable to perform this work, so you should use an additional DNS proxy server to do it on Windows. Below we will show some examples.

 

 

 

 

 

Windows PC Acrylic DNS proxy for Denarius DDNS

Running the Denarius wallet and everything else on a single PC is the most simple case. For this we recommend to install the lightweight Acrylic DNS Proxy onto your PC. Acrylic will improve the performance of your PC by resolving DNS requests with the local cache, decreasing latencies with browsing or any other Internet activity.

For installation and initial configuration in Windows, see the guide on the Acrylic website. After installation you should configure Acrylic to integrate Denarius domain zones. A config file example is available online. To configure, you should forward all requests to DDNS zones (*.d, *.dnr, *.denarii, *.king, *.sys, *.ipfs) to the local Denarius wallet, and all requests to other zones to the default DNS provider. This can be configured in the Acrylic config file as follows:

PrimaryServerAddress=1.1.1.1
PrimaryServerProtocol=UDP
PrimaryServerDomainNameAffinityMask=^*.d;^*.dnr;^*.denarii;^*.sys;^*.king;^*.ipfs;*
SecondaryServerAddress=8.8.8.8
SecondaryServerPort=53
SecondaryServerProtocol=UDP
SecondaryServerDoHProtocolPath=
SecondaryServerDoHProtocolHost=
SecondaryServerDoHProtocolConnectionType=System
SecondaryServerDoHProtocolReuseConnections=Yes
SecondaryServerDoHProtocolUseWinHttp=Yes
SecondaryServerSocks5ProtocolProxyAddress=
SecondaryServerSocks5ProtocolProxyPort=
SecondaryServerDomainNameAffinityMask=^*.d;^*.dnr;^*.denarii;^*.sys;^*.king;^*.ipfs;^*.btc;^*.bitcoin;*
SecondaryServerQueryTypeAffinityMask=
IgnoreFailureResponsesFromSecondaryServer=No
IgnoreNegativeResponsesFromSecondaryServer=No
;
; The configuration of your tertiary Denarius DNS server.
; For more details refer to the primary DNS server configuration comments.
;
TertiaryServerAddress=127.0.0.1
TertiaryServerPort=5333
TertiaryServerProtocol=UDP
TertiaryServerDoHProtocolPath=
TertiaryServerDoHProtocolHost=
TertiaryServerDoHProtocolConnectionType=System
TertiaryServerDoHProtocolReuseConnections=Yes
TertiaryServerDoHProtocolUseWinHttp=Yes
TertiaryServerSocks5ProtocolProxyAddress=
TertiaryServerSocks5ProtocolProxyPort=
TertiaryServerDomainNameAffinityMask=*.d;*.denarii;*.dnr;*.sys;*.king;*.ipfs;*.btc;*.bitcoin;
TertiaryServerQueryTypeAffinityMask=
IgnoreFailureResponsesFromTertiaryServer=No
IgnoreNegativeResponsesFromTertiaryServer=No

In Windows, the default path to the Acrylic config file is: C:Program Files (x86)Acrylic DNS Proxy

You can download this AcrylicConfiguration.ini file (https://ipfs.denarius.io/ipfs/QmWrk7AkDGRJdSx1Ng6eSf5aS9vVD5KrEN7VXww7Zkmm7x), pre-configured to use Cloudflare and Google as the primary & secondary DNS-provider (for regular DNS-tree), and a local Denarius wallet as the ternary provider, for domain zones *.d, *.dnr, *.denarii, *.king, *.sys, *.ipfs, *.btc, *.bitcoin.

 

 

 

 

Any PC BIND DNS proxy

Instead of installing a DNS proxy, you also have the option to install a full service DNS server. Fortunately, the full DNS server “BIND” is available for Windows, and is free. You can find many tutorials on the internet that show how to install BIND onto Windows. For example, see this manual.

After installation you should tell BIND to forward D-zones to the local Denarius wallet by adding to the BIND configuration file named.conf as follows:

zone "d" {
 type forward;
 forward only;
 forwarders {
   127.0.0.1 port 5333; // Local Denarius wallet
 };
};
zone "dnr" {
 type forward;
 forward only;
 forwarders {
   127.0.0.1 port 5333; // Local Denarius wallet
 };
};
zone "denarii" {
 type forward;
 forward only;
 forwarders {
   127.0.0.1 port 5333; // Local Denarius wallet
 };
};
zone "ipfs" {
 type forward;
 forward only;
 forwarders {
   127.0.0.1 port 5333; // Local Denarius wallet
 };
};
zone "king" {
 type forward;
 forward only;
 forwarders {
   127.0.0.1 port 5333; // Local Denarius wallet
 };
};
zone "sys" {
 type forward;
 forward only;
 forwarders {
   127.0.0.1 port 5333; // Local Denarius wallet
 };
};
zone "btc" {
 type forward;
 forward only;
 forwarders {
   127.0.0.1 port 5333; // Local Denarius wallet
 };
};
zone "bitcoin" {
 type forward;
 forward only;
 forwarders {
   127.0.0.1 port 5333; // Local Denarius wallet
 };
};

Local network, BIND DNS proxy

If you have a server with a static IP address in your LAN, you can install BIND onto your server, and point your desktop PC’s primary DNS address to your BIND server. On the server you can run a headless Denarius wallet to which BIND will forward requests to the appropriate zones. In this case configuration of BIND is exactly the same as above.

Also you can run the Denarius wallet on any PC of your LAN, instead of on the BIND server. If so, you should change the forwarding address in the BIND configuration from 127.0.0.1 to the IP address of that PC. Of course that PC should have a static LAN IP.

 

 

 

DNSMASQ proxy

Modern routers usually contain a built-in proxy DNS in their firmware. Usually this is DNSMASQ. Some router firmware like DD-WRT and OpenWrt (as well as others) allow you to configure the built-in DNS proxy (for instance, see DD-WRT DNSMASQ manual[] or OpenWrt DNSMASQ manual).

In this case the wallet should be run on a PC with a static LAN IP and DNSMASQ from the router would send DNS requests to that PC. Following are examples of the configuration lines needed to add into dnsmasq.conf. In this example the PC running Denarius has the LAN IP address 192.168.1.53.

server=/d/192.168.1.53#5333
server=/dnr/192.168.1.53#5333
server=/denarii/192.168.1.53#5333
server=/king/192.168.1.53#5333
server=/ipfs/192.168.1.53#5333
server=/sys/192.168.1.53#5333
server=/btc/192.168.1.53#5333
server=/bitcoin/192.168.1.53#5333

Public Internet, direct gateway

The ability also exists to make a public gateway from a regular DNS tree into DDNS. In this case, you can lease any public domain or subdomain, and point the NS records for this domain to a machine that is running the Denarius wallet with an active DNS server on port 53 (see in the next paragraph for how to define the port). Once you do this, all regular NS requests to that domain will be resolved by the DNS server, and answers will be retrieved from the Denarius NVS database in the Denarius wallet.

Thus, if you register any name with Denarius DNS, the name would be resolved by any Denarius DNS gateway. And your site site.d will be available through any such gateway, by links such as site.d.somedgateway.com, or site.d.another.com.

To configure a new domain as a public Denarius DNS gateway, you need to specify DNS servers as authoritative for your zone (domain). For the domain exampled.com, we specified two Name Servers (NS), authoritative for this domain with our domain registrar:

Name Server: SEED1.EXAMPLED.COM
Name Server: SEED2.EXAMPLED.COM

You can check this info using whois.

On each of these nameservers runs an Denarius wallet with an active DNS server which serves the gateway and local zone for exampled.com. DNS specific config parameters for the file denarius.conf are as follows:

If you are only running a DNS gateway for your local computer (with Acrylic or BIND) or for your LAN, it is enough to specify just a single parameter in denarius.conf:

# enable D dns
ddns=1

This will activate Denarius’s DNS server and run it on default port 5333, as allowed for DNS forwarding by DNS proxies (Acrylic, BIND, dnsmasq, etc).

To run as a public DNS gateway, you need to specify some additional parameters:

# Gateway suffix. This suffix will be ignored when a request is passed to the internal gateway.
# Requests for other domain suffixes will be ignored.
ddnssuffix=.exampled.com

# NS Server port 53 is the default NS port and must be used if the server is public and "not forward only".
ddnsport=53

# Filter for allowed zones. Protection for "cool hackers", who try to lookup any external domains through our server
# or attack someone else by DNS amplification mechanism. Currently, only the four D-zones are allowed.
ddnsallowed=.d|.dnr|.denarii|.king|.ipfs|.sys|.btc|.bitcoin

# Optional path for a file that contains names in the local gateway's NS zone (like www.exampled.com).
# Must be full path. Example:
ddnslocalcf=/usr/share/denarius/ddnslocal.conf

The local config file (DDNSlocal.conf above) contains pairs in the format “name=value”. An empty name assumes “gateway as is”. The values use the same format as DDNS values in the blockchain. For example, the local file for exampled.com is as follows:

# This is local zone config
# For built-in Denarius DNS

=A=192.241.241.153|TXT=Denarius site
www=A=192.241.241.153|TXT=Denarius www-site

 

Virtual webhosts (vhosts)

When you run virtual hosts, you will be required to modify your web server’s config to correctly distinguish your hostname with as many possible gateway-suffixes as you wish (or without suffix if name resolved by LAN or locally). This is easy to do by creating a vname-alias with an asterisk “*” as the suffix. The following example shows the appropriate Apache web server config for the virtual server exchange.d. Note the ServerAlias line:

<VirtualHost *:80>
  ServerAdmin [email protected]
  DocumentRoot "/var/www/exchange.d/html"
  ServerName exchanged
  ServerAlias exchange.d*
  ErrorLog  "/var/log/exchange.d-error_log"
  CustomLog "/var/log/exchange.d-access_log" common
  ScriptAlias /cgi-bin/ "/usr/local/libexec/cgi-bin/"
</VirtualHost>