gnunet-handbook

The GNUnet Handbook
Log | Files | Refs

migration.rst (4819B)


      1 .. _gns-migration:
      2 
      3 Migrating DNS zones to GNS
      4 ==========================
      5 
      6 If you run a DNS zone, you can make it available in GNS as well.  Which tool
      7 to use depends on where the authoritative data lives:
      8 
      9 - **You have the zone file**, because you are the operator: import it with
     10   `gnunet-namestore-zonefile`_, and keep DNS and GNS in sync yourself.
     11 - **The zone supports zone transfers (AXFR/IXFR)**: use `Ascension`_, which
     12   mirrors the zone and keeps it updated.
     13 - **The zone only publishes a list of delegated names**, as some top-level
     14   domain registries do: use `gnunet-zoneimport`_.
     15 
     16 When importing very large zones (millions of records), see also
     17 :ref:`Large zones <gns-zones>`.  In addition, the NAMESTORE by default
     18 pre-populates the NAMECACHE, which is cryptographically expensive.  On a
     19 system that only serves to import a large zone, and does not resolve names
     20 itself, disable the namecache by setting ``DISABLE = YES`` in the
     21 ``[namecache]`` section.
     22 
     23 gnunet-namestore-zonefile
     24 -------------------------
     25 
     26 ``gnunet-namestore-zonefile`` reads a DNS zone file, as used by BIND and
     27 other DNS servers, from standard input and stores its records in GNS:
     28 
     29 .. code-block:: console
     30 
     31    $ gnunet-namestore-zonefile < myzonefile
     32 
     33 For each ``$ORIGIN`` directive in the file, a zone named after the origin is
     34 created unless it already exists: ``$ORIGIN example.com.`` creates or uses
     35 the zone ``example.com``.  The records following the directive are imported
     36 into that zone.  If the file has no ``$ORIGIN`` directive at the beginning,
     37 or you want to override the first one, name the zone explicitly:
     38 
     39 .. code-block:: console
     40 
     41    $ gnunet-namestore-zonefile -z myorigin < myzonefile
     42 
     43 The conversion is not lossless.  GNS maps the origin to the label ``@``
     44 wherever possible, so equivalent DNS spellings collapse into one.  DNS
     45 ``$TTL`` values in seconds are converted to GNS expiration times, which are
     46 measured in microseconds.  Converting a GNS zone back into a zone file would
     47 therefore not reproduce the original file (and is not implemented).
     48 
     49 For example, both of the following lines describe the same record, and
     50 become one ``MX`` record under ``@`` in GNS:
     51 
     52 .. code-block:: text
     53 
     54    $ORIGIN example.com.
     55    $TTL 3600
     56    example.com.    IN  MX    10 mail.example.com.
     57    @               IN  MX    10 mail.example.com.
     58 
     59 Ascension
     60 ---------
     61 
     62 Ascension is a separate tool that mirrors DNS zones into GNS using zone
     63 transfers.  If the zone has an ``SOA`` record, Ascension uses its serial
     64 number to request incremental transfers (IXFR); depending on the server, the
     65 answer is an incremental update or the full zone (AXFR).  Ascension keeps
     66 running and refreshes the zone when the refresh time given in the ``SOA``
     67 record has elapsed.
     68 
     69 With your peer running, the following command mirrors the Syrian top-level
     70 domain, one of the few that allow zone transfers, and publishes it
     71 (``-p``):
     72 
     73 .. code-block:: console
     74 
     75    $ ascension sy. -n ns1.tld.sy. -p
     76 
     77 To let others resolve the mirrored zone, give them its key:
     78 
     79 .. code-block:: console
     80 
     81    $ gnunet-identity -d -q -e sy
     82 
     83 They can then use the key as top-level domain, or delegate to it as
     84 described in :ref:`gns-zones`:
     85 
     86 .. code-block:: console
     87 
     88    $ gnunet-gns -t SOA -u "$KEY"
     89 
     90 DNSCurve-style records are supported and imported as delegations to the
     91 respective GNS zone.
     92 
     93 There are unofficial Debian packages: ``python3-ascension`` adds a system
     94 user ``ascension`` and runs a GNUnet peer in the background, and
     95 ``ascension-bind`` detects locally running DNS zones that allow zone
     96 transfers, asks which of them to migrate, and installs a systemd unit that
     97 keeps them up to date.
     98 
     99 gnunet-zoneimport
    100 -----------------
    101 
    102 Some registries, for example AFNIC for ``.fr``, do not permit zone transfers
    103 but publish the list of registered names.  ``gnunet-zoneimport`` reads such a
    104 list of domain names from standard input, queries the authoritative DNS
    105 servers for each of them, converts the answers where possible, and stores
    106 them in the NAMESTORE.  It is not perfect at tracking updates and
    107 expirations, but it makes mirroring such zones possible at all.
    108 
    109 For example, with AFNIC's ``NomsDeDomaineEnPointFr`` open-data file:
    110 
    111 .. code-block:: console
    112 
    113    $ cut -d';' -f 1 OPENDATA_A-NomsDeDomaineEnPointFr.csv | tail -n+2 \
    114        | gnunet-zoneimport 194.0.9.1
    115 
    116 This takes the first column of each line as the domain name and skips the
    117 header line.  The argument is the IP address of an authoritative DNS server
    118 for the zone; it must be authoritative, not a recursive resolver.
    119 
    120 The ZONEMASTER service then publishes the imported records in the DHT.  To
    121 make the mirrored zone available under its usual name on a peer, map the
    122 suffix to the zone key in the ``[gns]`` section, for example:
    123 
    124 .. code-block:: console
    125 
    126    $ gnunet-config -s gns -o .fr -V 000G0...ZONEKEY