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