added documentation for the ascension tool

3 files changed, 66 insertions, 4 deletions

diff --git a/doc/handbook/chapters/developer.texi b/doc/handbook/chapters/developer.texi
index d9c92247b..37e11cb11 100644
--- a/doc/handbook/chapters/developer.texi
+++ b/doc/handbook/chapters/developer.texi
@@ -8768,14 +8768,14 @@ regular expressions.
 
 Using the REST subsystem, you can expose REST-based APIs or services.
 The REST service is designed as a pluggable architecture.
-To create a new REST endpoint, simply add a library in the form 
+To create a new REST endpoint, simply add a library in the form
 ``plugin_rest_*''.
 The REST service will automatically load all REST plugins on startup.
 
 @strong{Configuration}
 
 The REST service can be configured in various ways.
-The reference config file can be found in 
+The reference config file can be found in
 @file{src/rest/rest.conf}:
 @example
 [rest]
diff --git a/doc/handbook/chapters/installation.texi b/doc/handbook/chapters/installation.texi
index c05f776f2..5ce9805ed 100644
--- a/doc/handbook/chapters/installation.texi
+++ b/doc/handbook/chapters/installation.texi
@@ -35,7 +35,7 @@ The mandatory libraries and applications are
 @item libextractor
 @item libidn
 @item libmicrohttpd @geq{}0.9.52
-@item libnss 
+@item libnss
 @item libunistring
 @item gettext
 @item glibc
@@ -1427,6 +1427,7 @@ and @code{[transport-https_client]} section of the configuration:
 * GNS Proxy Setup::
 * Setup of the GNS CA::
 * Testing the GNS setup::
+* Migrating existing DNS zones into GNS::
 @end menu
 
 
@@ -1693,6 +1694,29 @@ configured proxy) should give you a valid SSL certificate for
 @c FIXME: Image does not exist, create it or save it from Drupal?
 @c @image{images/gnunethpgns.png,5in,, picture of homepage.gnu in Webbrowser}
 
+@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.
+You can find the source code here: @code{}
+
+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):
+@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.
+
+@c How to reference another section here?
+Using the tool is discussed in another section.
+
 
 @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 ea41bbb6c..79c6563a1 100644
--- a/doc/handbook/chapters/user.texi
+++ b/doc/handbook/chapters/user.texi
@@ -1453,6 +1453,7 @@ the user. This results in non-unique name-value mappings as
 * Using Public Keys as Top Level Domains::
 * Resource Records in GNS::
 * Synchronizing with legacy DNS::
+* Migrating an existing DNS zone into GNS::
 @end menu
 
 
@@ -1631,6 +1632,8 @@ GNS currently supports the following record types:
 * ABE MASTER::
 * RECLAIM OIDC CLIENT::
 * RECLAIM OIDC REDIRECT::
+* Synchronizing with legacy DNS::
+* Migrating an existing DNS zone into GNS::
 @end menu
 
 @node NICK
@@ -1891,6 +1894,40 @@ DNS zone and that do not have a local gns service in use, it
 is thus advisable to disable the namecache by setting the
 option ``DISABLE'' to ``YES'' in section ``[namecache]''.
 
+@node Migrating an existing DNS zone into GNS
+@subsection Migrating an existing DNS zone into GNS
+
+After installing the tool according to the README file you have these 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
+
+Options:
+    <port>          Port for zone transfer
+    <domain>        Domain to migrate
+    <transferns>    DNS Server that does the zone transfer
+    -d --debug      Enable debugging
+    -h --help       Show this screen.
+    -v --version    Show version.
+@end example
+
+To migrate the Syrian top level domain - one of the few top level domains that still support zone transfers - use the following command:
+
+@example
+$ ascension sy. -ns ns1.tld.sy.
+@end example
+
+This will take a while but after it has finished executing the zone will have been migrated into GNS.
+
+@c remove this once daemonized
+Currently this will only snapshot the zone at it's current state and not update it. There is a plan to daemonize the migration process so you don't have to worry that a zone will stay up to date.
 
 @node re@:claim Identity Provider
 @section re@:claim Identity Provider
@@ -1962,7 +1999,7 @@ Further, the "ticket" can be re-used later to retrieve up-to-date attributes in
 
 To list all given authorizations (tickets) you can execute:
 @example
-$ gnunet-reclaim -e "friend" -T (TODO there is only a C and REST API for this at this time) 
+$ gnunet-reclaim -e "friend" -T (TODO there is only a C and REST API for this at this time)
 @end example
 
 
@@ -2292,3 +2329,4 @@ protocol (--tcp or --udp) and you will again receive an IP address
 that will terminate at the respective peer's service.
 
 
+