From e3f6a5c29d2ea1cef92e10f142b7883ee6347ca7 Mon Sep 17 00:00:00 2001 From: rexxnor Date: Wed, 30 Jan 2019 18:49:50 +0100 Subject: updated ascension documentation --- doc/handbook/chapters/developer.texi | 71 ++++++++++++++++++++++++++------- doc/handbook/chapters/installation.texi | 24 +++++++---- doc/handbook/chapters/user.texi | 66 +++++++++++++++++++++++++----- 3 files changed, 131 insertions(+), 30 deletions(-) (limited to 'doc') diff --git a/doc/handbook/chapters/developer.texi b/doc/handbook/chapters/developer.texi index 2da262b34..a1b5583cb 100644 --- a/doc/handbook/chapters/developer.texi +++ b/doc/handbook/chapters/developer.texi @@ -8080,7 +8080,7 @@ This includes some of well known utilities, like "ping" and "nslookup". @c %**end of header This section discusses the challenges and problems faced when writing the -ascension tool. It also takes a look at possible improvements in the future. +Ascension tool. It also takes a look at possible improvements in the future. @menu * Conversions between DNS and GNS:: @@ -8093,7 +8093,7 @@ ascension tool. It also takes a look at possible improvements in the future. The differences between the two name systems lies in the details and is not always transparent. For instance an SRV record is converted to a -gnunet only BOX record. +GNS only BOX record. This is done by converting to a BOX record from an existing SRV record: @@ -8120,14 +8120,14 @@ example. Very important to note are the rname and mname keys. 604800 ; expire 600 ) ; ttl # Recordline for adding the record -gnunet-namestore -z example.com -a -n @ -t SOA -V rname=master.example.com \ - mname=hostmaster.example.com 2017030300,3600,1800,604800,600 -e 7200s +$ gnunet-namestore -z example.com -a -n @ -t SOA -V rname=master.example.com \ + mname=hostmaster.example.com 2017030300,3600,1800,604800,600 -e 7200s @end example The transformation of MX records is done in a simple way. @example # mail.example.com. 3600 IN MX 10 mail.example.com. -gnunet-namestore -z example.com -n mail -R 3600 MX n 10,mail +$ gnunet-namestore -z example.com -n mail -R 3600 MX n 10,mail @end example Finally, one of the biggest struggling points were the NS records that are found @@ -8136,9 +8136,47 @@ records for those so that gnunet-gns can resolve records for those domains on its own. This requires migration of the DNS GLUE records as well, provided that they are within the same zone. +The following two examples show one record with a GLUE record and the other one +does not have a GLUE record. This takes place in the 'com' TLD. + +@example +# ns1.example.com 86400 IN A 127.0.0.1 +# example.com 86400 IN NS ns1.example.com. +$ gnunet-namestore -z com -n example -R 86400 GNS2DNS n example.com@@127.0.0.1 + +# example.com 86400 IN NS ns1.example.org. +$ gnunet-namestore -z com -n example -R 86400 GNS2DNS n example.com@@ns1.example.org +@end example + +As you can see, one of the GNS2DNS records has an IP address listed and the +other one a DNS name. For the first one there is a GLUE record to do the +translation directly and the second one will issue another DNS query to figure +out the IP of ns1.example.org. + A solution was found by creating a hierarchical zone structure in GNS and linking the zones using PKEY records to one another. This allows the resolution of the -nameservers to work within GNS while not taking control over unwanted zones. +name servers to work within GNS while not taking control over unwanted zones. + +Currently the following record types are supported: +@itemize @bullet +@item A +@item AAAA +@item CNAME +@item MX +@item NS +@item SRV +@item TXT +@end itemize + +This is not due to a technical limitation but rather a practical one. The +problem occurs with DNSSEC enabled DNS zones. As records within those zones are +signed periodically, and every new signature is an update to the zone, there are +many revisions of zones. This results in a problem with bigger zones as there +are lots of records that have been signed again but no major changes. Also +trying to add records that are unknown that require a different format take time +as they cause a CLI call of the namestore. Furthermore certain record types +need transformation into a GNS compatible format which, depending on the record +type, takes more time. @node DNS Zone Size @subsubsection DNS Zone Size @@ -8162,11 +8200,17 @@ are still displayed when calling gnunet-namestore but do not resolve with gnunet-gns. When doing incremental zone transfers this becomes especially apparent. +I estimate that the limit lies at about 200'000 records in a zone as this is +the limit that my machine is capable of adding within one hour. This was +calculated by running cProfile on the application with a zone of 5000 records +and calculating what abouts a much bigger zones with 8 million records would +take. This results in a nice metric of records migrated per hour. + @node Performance @subsubsection Performance -The performance when migrating a zone using the ascension tool is limited by a -handful of factors. First of all ascension is written in python3 and calls the -CLI tools of gnunet. Furthermore all the records that are added to the same +The performance when migrating a zone using the Ascension tool is limited by a +handful of factors. First of all ascension is written in Python3 and calls the +CLI tools of GNUnet. Furthermore all the records that are added to the same label are signed using the zones private key. This signing operation is very resource heavy and was optimized during development by adding the '-R' (Recordline) option to gnunet-namestore. This allows to add multiple records @@ -8176,16 +8220,15 @@ The result of this was a much faster migration of TLD zones, as most records with the same label have two name servers. Another improvement that could be made is with the addition of multiple threads -when opening the gnunet CLI tools. This could be implemented by simply creating +when opening the GNUnet CLI tools. This could be implemented by simply creating more workers in the program but performance improvements were not tested. -During the entire development of the ascension tool sqlite was used as a -database backend. Other backends need to be tested in the future. +During the entire development of Ascension sqlite was used as a database +backend for GNUnet. Other backends have not been tested yet. In conclusion there are many bottlenecks still around in the program, namely the signing process and the single threaded implementation. In the future a solution -that uses the c api would be cleaner and better. - +that uses the C API would be cleaner and better. @cindex GNS Namecache @node GNS Namecache diff --git a/doc/handbook/chapters/installation.texi b/doc/handbook/chapters/installation.texi index bdff20802..fc580bdb7 100644 --- a/doc/handbook/chapters/installation.texi +++ b/doc/handbook/chapters/installation.texi @@ -1697,31 +1697,41 @@ configured proxy) should give you a valid SSL certificate for @node Migrating existing DNS zones into GNS @subsubsection Migrating existing DNS zones into GNS -To migrate an existing zone into GNS use the ascension tool. +To migrate an existing zone into GNS use the Ascension tool. Ascension transfers entire zones into GNS by doing incremental zone transfers and then adding the records to GNS. +Compared to the gnunet-zoneimport tool it strictly uses AXFR or IXFR depending +on whether or not there exists a SOA record for the zone. If that is the case it +will take the serial as a reference point and request the zone. The server will +either answer the IXFR request with a correct incremental zone or with the +entire zone, which depends on the server configuration. + You can find the source code here: @code{https://gnunet.org/git/ascension.git/} -The software can be installed into a python virtual environment like this: +The software can be installed into a Python virtual environment like this: @example $ python3 -m venv .venv $ source .venv/bin/activate $ python3 setup.py install @end example -Or installed globally like this (not recommended): +Or installed globally like this: @example $ sudo python3 setup.py install @end example -The advantage of using a virtual environment is, that all the dependencies can -be installed separately in different versions without touching your existing -python installation and its dependencies. +Pip will then install all the necessary requirements that are needed to run +Ascension. For development purposes a virtual environment should suffice. +Keeping a virtual environment helps with keeping things tidy and prevents +breaking of Ascension through a future Python update. -Using the tool is discussed in the user section of the documentation. +The advantage of using a virtual environment is, that all the dependencies can +be installed separately in different versions without touching your system +Python installation and its dependencies. +@xref{Migrating an existing DNS zone into GNS} for usage manual of the tool. @node Configuring the GNUnet VPN @subsection Configuring the GNUnet VPN diff --git a/doc/handbook/chapters/user.texi b/doc/handbook/chapters/user.texi index 0703adafc..fb47150ef 100644 --- a/doc/handbook/chapters/user.texi +++ b/doc/handbook/chapters/user.texi @@ -1895,38 +1895,86 @@ option ``DISABLE'' to ``YES'' in section ``[namecache]''. @node Migrating an existing DNS zone into GNS @subsection Migrating an existing DNS zone into GNS +Ascension is a tool to migrate existing DNS zones into GNS. + +@xref{Migrating existing DNS zones into GNS} for installation instructions and +further information about Ascension. + +Compared to the gnunet-zoneimport tool it strictly uses AXFR or IXFR depending +on whether or not there exists a SOA record for the zone. If that is the case it +will take the serial as a reference point and request the zone. The server will +either answer the IXFR request with a correct incremental zone or with the +entire zone, which depends on the server configuration. + After installing the tool according to the README file you have the following options: + @example Ascension Usage: - ascension.py [-d] - ascension.py -p [-d] - ascension.py -ns [-d] - ascension.py -ns -p [-d] - ascension.py -h | --help - ascension.py -v | --version + ascension [-d] [-p] + ascension [-d] [-p] + ascension -ns [-d] [-p] + ascension -ns [-d] [-p] + ascension -p | --public + ascension -h | --help + ascension -v | --version Options: - Port for zone transfer Domain to migrate + Port for zone transfer DNS Server that does the zone transfer + -p --public Make records public on the DHT -d --debug Enable debugging -h --help Show this screen. -v --version Show version. @end example +Before you can migrate any zone though, you need to start the GNUnet peer: +@example +$ gnunet-arm -s +@end example + To migrate the Syrian top level domain - one of the few top level domains that -still supports zone transfers - use the following command: +still supports zone transfers - into GNS use the following command: + +@example +$ ascension sy. -ns ns1.tld.sy. -p +@end example + +The -p flag will tell GNS to put these records on the DHT so that other users +may resolve these records by using the public key of the zone. + +Once the zone is migrated, Ascension will output a message telling you, that it +will refresh the zone after the time has elapsed. You can resolve the names in +the zone directly using GNS or if you want to use it with your browser, check +out the GNS manual section. @ref{Configuring the GNU Name System}. To resolve +the records from another system you need the zone PKEY. To get the zone key, +you can run the following command: + +@example +$ gnunet-identity -d | grep ^sy | cut -d " " -f3 +@end example + +Where "sy" is the name of the zone you want to migrate. + +As soon as the public flag is implemented, you can share the PKEY of the zone +with your friends. They can then resolve records in the zone by doing a lookup +replacing the zone label with your PKEY: @example -$ ascension sy. -ns ns1.tld.sy. +$ gnunet-gns -t SOA -u "@.$PKEY" @end example The program will continue to run as a daemon and update once the refresh time specified in the zones SOA record has elapsed. +The next step would be to add the PKEY record as a DNScurve style NS record +into the existing DNS zone to enable clients to detect that this zone has +already been migrated to GNS and to also have a means of distributing the PKEY +seamlessly. + At this point you might want to write for example a systemd unit file to start and enable the service, so that your zone is migrated automatically. -- cgit v1.2.3