From b889d108b5068f3e893e8f399ed545ff956db818 Mon Sep 17 00:00:00 2001 From: rexxnor Date: Thu, 10 Jan 2019 13:31:23 +0100 Subject: [PATCH] added documentation for the ascension tool --- doc/handbook/chapters/developer.texi | 4 +-- doc/handbook/chapters/installation.texi | 26 +++++++++++++++- doc/handbook/chapters/user.texi | 40 ++++++++++++++++++++++++- 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 [-d] + ascension.py -p [-d] + ascension.py -ns [-d] + ascension.py -ns -p [-d] + ascension.py -h | --help + ascension.py -v | --version + +Options: + Port for zone transfer + Domain to migrate + 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. + -- 2.25.1