Migrating DNS zones to GNS

If you run a DNS zone, you can make it available in GNS as well. Which tool to use depends on where the authoritative data lives:

  • You have the zone file, because you are the operator: import it with gnunet-namestore-zonefile, and keep DNS and GNS in sync yourself.

  • The zone supports zone transfers (AXFR/IXFR): use Ascension, which mirrors the zone and keeps it updated.

  • The zone only publishes a list of delegated names, as some top-level domain registries do: use gnunet-zoneimport.

When importing very large zones (millions of records), see also Large zones. In addition, the NAMESTORE by default pre-populates the NAMECACHE, which is cryptographically expensive. On a system that only serves to import a large zone, and does not resolve names itself, disable the namecache by setting DISABLE = YES in the [namecache] section.

gnunet-namestore-zonefile

gnunet-namestore-zonefile reads a DNS zone file, as used by BIND and other DNS servers, from standard input and stores its records in GNS:

$ gnunet-namestore-zonefile < myzonefile

For each $ORIGIN directive in the file, a zone named after the origin is created unless it already exists: $ORIGIN example.com. creates or uses the zone example.com. The records following the directive are imported into that zone. If the file has no $ORIGIN directive at the beginning, or you want to override the first one, name the zone explicitly:

$ gnunet-namestore-zonefile -z myorigin < myzonefile

The conversion is not lossless. GNS maps the origin to the label @ wherever possible, so equivalent DNS spellings collapse into one. DNS $TTL values in seconds are converted to GNS expiration times, which are measured in microseconds. Converting a GNS zone back into a zone file would therefore not reproduce the original file (and is not implemented).

For example, both of the following lines describe the same record, and become one MX record under @ in GNS:

$ORIGIN example.com.
$TTL 3600
example.com.    IN  MX    10 mail.example.com.
@               IN  MX    10 mail.example.com.

Ascension

Ascension is a separate tool that mirrors DNS zones into GNS using zone transfers. If the zone has an SOA record, Ascension uses its serial number to request incremental transfers (IXFR); depending on the server, the answer is an incremental update or the full zone (AXFR). Ascension keeps running and refreshes the zone when the refresh time given in the SOA record has elapsed.

With your peer running, the following command mirrors the Syrian top-level domain, one of the few that allow zone transfers, and publishes it (-p):

$ ascension sy. -n ns1.tld.sy. -p

To let others resolve the mirrored zone, give them its key:

$ gnunet-identity -d -q -e sy

They can then use the key as top-level domain, or delegate to it as described in Managing your zones:

$ gnunet-gns -t SOA -u "$KEY"

DNSCurve-style records are supported and imported as delegations to the respective GNS zone.

There are unofficial Debian packages: python3-ascension adds a system user ascension and runs a GNUnet peer in the background, and ascension-bind detects locally running DNS zones that allow zone transfers, asks which of them to migrate, and installs a systemd unit that keeps them up to date.

gnunet-zoneimport

Some registries, for example AFNIC for .fr, do not permit zone transfers but publish the list of registered names. gnunet-zoneimport reads such a list of domain names from standard input, queries the authoritative DNS servers for each of them, converts the answers where possible, and stores them in the NAMESTORE. It is not perfect at tracking updates and expirations, but it makes mirroring such zones possible at all.

For example, with AFNIC’s NomsDeDomaineEnPointFr open-data file:

$ cut -d';' -f 1 OPENDATA_A-NomsDeDomaineEnPointFr.csv | tail -n+2 \
    | gnunet-zoneimport 194.0.9.1

This takes the first column of each line as the domain name and skips the header line. The argument is the IP address of an authoritative DNS server for the zone; it must be authoritative, not a recursive resolver.

The ZONEMASTER service then publishes the imported records in the DHT. To make the mirrored zone available under its usual name on a peer, map the suffix to the zone key in the [gns] section, for example:

$ gnunet-config -s gns -o .fr -V 000G0...ZONEKEY