[GNUnet-SVN] [gnunet] branch master updated: updated ascension documentation

[gnunet]

This is an automated email from the git hooks/post-receive script.

rexxnor pushed a commit to branch master
in repository gnunet.

The following commit(s) were added to refs/heads/master by this push:
     new e3f6a5c29 updated ascension documentation
e3f6a5c29 is described below

commit e3f6a5c29d2ea1cef92e10f142b7883ee6347ca7
Author: rexxnor <address@hidden>
AuthorDate: Wed Jan 30 18:49:50 2019 +0100

    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(-)

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.
+
address@hidden
+# 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
address@hidden 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:
address@hidden @bullet
address@hidden A
address@hidden AAAA
address@hidden CNAME
address@hidden MX
address@hidden NS
address@hidden SRV
address@hidden TXT
address@hidden 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.
 
address@hidden 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.
+
address@hidden 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 <domain> [-d]
-    ascension.py <domain> -p <port> [-d]
-    ascension.py <domain> -ns <transferns> [-d]
-    ascension.py <domain> -ns <transferns> -p <port> [-d]
-    ascension.py -h | --help
-    ascension.py -v | --version
+    ascension <domain> [-d] [-p]
+    ascension <domain> <port> [-d] [-p]
+    ascension <domain> -ns <transferns> [-d] [-p]
+    ascension <domain> -ns <transferns> <port> [-d] [-p]
+    ascension -p | --public
+    ascension -h | --help
+    ascension -v | --version
 
 Options:
-    <port>          Port for zone transfer
     <domain>        Domain to migrate
+    <port>          Port for zone transfer
     <transferns>    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:
address@hidden
+$ gnunet-arm -s
address@hidden 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:
+
address@hidden
+$ ascension sy. -ns ns1.tld.sy. -p
address@hidden 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:
+
address@hidden
+$ gnunet-identity -d | grep ^sy | cut -d " " -f3
address@hidden 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.
 

-- 
To stop receiving notification emails like this one, please contact
address@hidden