aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorrexxnor <rexxnor+gnunet@brief.li>2019-01-30 18:49:50 +0100
committerrexxnor <rexxnor+gnunet@brief.li>2019-01-30 18:53:05 +0100
commite3f6a5c29d2ea1cef92e10f142b7883ee6347ca7 (patch)
treefc00cb008568945fd947dc86f24efde7b35aed63 /doc
parent404c9065789248a5eba44fb4bc320bfeaa988da6 (diff)
downloadgnunet-e3f6a5c29d2ea1cef92e10f142b7883ee6347ca7.tar.gz
gnunet-e3f6a5c29d2ea1cef92e10f142b7883ee6347ca7.zip
updated ascension documentation
Diffstat (limited to 'doc')
-rw-r--r--doc/handbook/chapters/developer.texi71
-rw-r--r--doc/handbook/chapters/installation.texi24
-rw-r--r--doc/handbook/chapters/user.texi66
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".
8080@c %**end of header 8080@c %**end of header
8081 8081
8082This section discusses the challenges and problems faced when writing the 8082This section discusses the challenges and problems faced when writing the
8083ascension tool. It also takes a look at possible improvements in the future. 8083Ascension tool. It also takes a look at possible improvements in the future.
8084 8084
8085@menu 8085@menu
8086* Conversions between DNS and GNS:: 8086* Conversions between DNS and GNS::
@@ -8093,7 +8093,7 @@ ascension tool. It also takes a look at possible improvements in the future.
8093 8093
8094The differences between the two name systems lies in the details 8094The differences between the two name systems lies in the details
8095and is not always transparent. For instance an SRV record is converted to a 8095and is not always transparent. For instance an SRV record is converted to a
8096gnunet only BOX record. 8096GNS only BOX record.
8097 8097
8098This is done by converting to a BOX record from an existing SRV record: 8098This is done by converting to a BOX record from an existing SRV record:
8099 8099
@@ -8120,14 +8120,14 @@ example. Very important to note are the rname and mname keys.
8120 604800 ; expire 8120 604800 ; expire
8121 600 ) ; ttl 8121 600 ) ; ttl
8122# Recordline for adding the record 8122# Recordline for adding the record
8123gnunet-namestore -z example.com -a -n @ -t SOA -V rname=master.example.com \ 8123$ gnunet-namestore -z example.com -a -n @ -t SOA -V rname=master.example.com \
8124 mname=hostmaster.example.com 2017030300,3600,1800,604800,600 -e 7200s 8124 mname=hostmaster.example.com 2017030300,3600,1800,604800,600 -e 7200s
8125@end example 8125@end example
8126 8126
8127The transformation of MX records is done in a simple way. 8127The transformation of MX records is done in a simple way.
8128@example 8128@example
8129# mail.example.com. 3600 IN MX 10 mail.example.com. 8129# mail.example.com. 3600 IN MX 10 mail.example.com.
8130gnunet-namestore -z example.com -n mail -R 3600 MX n 10,mail 8130$ gnunet-namestore -z example.com -n mail -R 3600 MX n 10,mail
8131@end example 8131@end example
8132 8132
8133Finally, one of the biggest struggling points were the NS records that are found 8133Finally, 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
8136its own. This requires migration of the DNS GLUE records as well, provided that 8136its own. This requires migration of the DNS GLUE records as well, provided that
8137they are within the same zone. 8137they are within the same zone.
8138 8138
8139The following two examples show one record with a GLUE record and the other one
8140does not have a GLUE record. This takes place in the 'com' TLD.
8141
8142@example
8143# ns1.example.com 86400 IN A 127.0.0.1
8144# example.com 86400 IN NS ns1.example.com.
8145$ gnunet-namestore -z com -n example -R 86400 GNS2DNS n example.com@@127.0.0.1
8146
8147# example.com 86400 IN NS ns1.example.org.
8148$ gnunet-namestore -z com -n example -R 86400 GNS2DNS n example.com@@ns1.example.org
8149@end example
8150
8151As you can see, one of the GNS2DNS records has an IP address listed and the
8152other one a DNS name. For the first one there is a GLUE record to do the
8153translation directly and the second one will issue another DNS query to figure
8154out the IP of ns1.example.org.
8155
8139A solution was found by creating a hierarchical zone structure in GNS and linking 8156A solution was found by creating a hierarchical zone structure in GNS and linking
8140the zones using PKEY records to one another. This allows the resolution of the 8157the zones using PKEY records to one another. This allows the resolution of the
8141nameservers to work within GNS while not taking control over unwanted zones. 8158name servers to work within GNS while not taking control over unwanted zones.
8159
8160Currently the following record types are supported:
8161@itemize @bullet
8162@item A
8163@item AAAA
8164@item CNAME
8165@item MX
8166@item NS
8167@item SRV
8168@item TXT
8169@end itemize
8170
8171This is not due to a technical limitation but rather a practical one. The
8172problem occurs with DNSSEC enabled DNS zones. As records within those zones are
8173signed periodically, and every new signature is an update to the zone, there are
8174many revisions of zones. This results in a problem with bigger zones as there
8175are lots of records that have been signed again but no major changes. Also
8176trying to add records that are unknown that require a different format take time
8177as they cause a CLI call of the namestore. Furthermore certain record types
8178need transformation into a GNS compatible format which, depending on the record
8179type, takes more time.
8142 8180
8143@node DNS Zone Size 8181@node DNS Zone Size
8144@subsubsection DNS Zone Size 8182@subsubsection DNS Zone Size
@@ -8162,11 +8200,17 @@ are still displayed when calling gnunet-namestore but do not resolve with
8162gnunet-gns. When doing incremental zone transfers this becomes especially 8200gnunet-gns. When doing incremental zone transfers this becomes especially
8163apparent. 8201apparent.
8164 8202
8203I estimate that the limit lies at about 200'000 records in a zone as this is
8204the limit that my machine is capable of adding within one hour. This was
8205calculated by running cProfile on the application with a zone of 5000 records
8206and calculating what abouts a much bigger zones with 8 million records would
8207take. This results in a nice metric of records migrated per hour.
8208
8165@node Performance 8209@node Performance
8166@subsubsection Performance 8210@subsubsection Performance
8167The performance when migrating a zone using the ascension tool is limited by a 8211The performance when migrating a zone using the Ascension tool is limited by a
8168handful of factors. First of all ascension is written in python3 and calls the 8212handful of factors. First of all ascension is written in Python3 and calls the
8169CLI tools of gnunet. Furthermore all the records that are added to the same 8213CLI tools of GNUnet. Furthermore all the records that are added to the same
8170label are signed using the zones private key. This signing operation is very 8214label are signed using the zones private key. This signing operation is very
8171resource heavy and was optimized during development by adding the '-R' 8215resource heavy and was optimized during development by adding the '-R'
8172(Recordline) option to gnunet-namestore. This allows to add multiple records 8216(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
8176with the same label have two name servers. 8220with the same label have two name servers.
8177 8221
8178Another improvement that could be made is with the addition of multiple threads 8222Another improvement that could be made is with the addition of multiple threads
8179when opening the gnunet CLI tools. This could be implemented by simply creating 8223when opening the GNUnet CLI tools. This could be implemented by simply creating
8180more workers in the program but performance improvements were not tested. 8224more workers in the program but performance improvements were not tested.
8181 8225
8182During the entire development of the ascension tool sqlite was used as a 8226During the entire development of Ascension sqlite was used as a database
8183database backend. Other backends need to be tested in the future. 8227backend for GNUnet. Other backends have not been tested yet.
8184 8228
8185In conclusion there are many bottlenecks still around in the program, namely the 8229In conclusion there are many bottlenecks still around in the program, namely the
8186signing process and the single threaded implementation. In the future a solution 8230signing process and the single threaded implementation. In the future a solution
8187that uses the c api would be cleaner and better. 8231that uses the C API would be cleaner and better.
8188
8189 8232
8190@cindex GNS Namecache 8233@cindex GNS Namecache
8191@node GNS Namecache 8234@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
1697@node Migrating existing DNS zones into GNS 1697@node Migrating existing DNS zones into GNS
1698@subsubsection Migrating existing DNS zones into GNS 1698@subsubsection Migrating existing DNS zones into GNS
1699 1699
1700To migrate an existing zone into GNS use the ascension tool. 1700To migrate an existing zone into GNS use the Ascension tool.
1701 1701
1702Ascension transfers entire zones into GNS by doing incremental zone transfers 1702Ascension transfers entire zones into GNS by doing incremental zone transfers
1703and then adding the records to GNS. 1703and then adding the records to GNS.
1704 1704
1705Compared to the gnunet-zoneimport tool it strictly uses AXFR or IXFR depending
1706on whether or not there exists a SOA record for the zone. If that is the case it
1707will take the serial as a reference point and request the zone. The server will
1708either answer the IXFR request with a correct incremental zone or with the
1709entire zone, which depends on the server configuration.
1710
1705You can find the source code here: @code{https://gnunet.org/git/ascension.git/} 1711You can find the source code here: @code{https://gnunet.org/git/ascension.git/}
1706 1712
1707The software can be installed into a python virtual environment like this: 1713The software can be installed into a Python virtual environment like this:
1708@example 1714@example
1709$ python3 -m venv .venv 1715$ python3 -m venv .venv
1710$ source .venv/bin/activate 1716$ source .venv/bin/activate
1711$ python3 setup.py install 1717$ python3 setup.py install
1712@end example 1718@end example
1713 1719
1714Or installed globally like this (not recommended): 1720Or installed globally like this:
1715@example 1721@example
1716$ sudo python3 setup.py install 1722$ sudo python3 setup.py install
1717@end example 1723@end example
1718 1724
1719The advantage of using a virtual environment is, that all the dependencies can 1725Pip will then install all the necessary requirements that are needed to run
1720be installed separately in different versions without touching your existing 1726Ascension. For development purposes a virtual environment should suffice.
1721python installation and its dependencies. 1727Keeping a virtual environment helps with keeping things tidy and prevents
1728breaking of Ascension through a future Python update.
1722 1729
1723Using the tool is discussed in the user section of the documentation. 1730The advantage of using a virtual environment is, that all the dependencies can
1731be installed separately in different versions without touching your system
1732Python installation and its dependencies.
1724 1733
1734@xref{Migrating an existing DNS zone into GNS} for usage manual of the tool.
1725 1735
1726@node Configuring the GNUnet VPN 1736@node Configuring the GNUnet VPN
1727@subsection Configuring the GNUnet VPN 1737@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]''.
1895@node Migrating an existing DNS zone into GNS 1895@node Migrating an existing DNS zone into GNS
1896@subsection Migrating an existing DNS zone into GNS 1896@subsection Migrating an existing DNS zone into GNS
1897 1897
1898Ascension is a tool to migrate existing DNS zones into GNS.
1899
1900@xref{Migrating existing DNS zones into GNS} for installation instructions and
1901further information about Ascension.
1902
1903Compared to the gnunet-zoneimport tool it strictly uses AXFR or IXFR depending
1904on whether or not there exists a SOA record for the zone. If that is the case it
1905will take the serial as a reference point and request the zone. The server will
1906either answer the IXFR request with a correct incremental zone or with the
1907entire zone, which depends on the server configuration.
1908
1898After installing the tool according to the README file you have the following 1909After installing the tool according to the README file you have the following
1899options: 1910options:
1911
1900@example 1912@example
1901Ascension 1913Ascension
1902 1914
1903Usage: 1915Usage:
1904 ascension.py <domain> [-d] 1916 ascension <domain> [-d] [-p]
1905 ascension.py <domain> -p <port> [-d] 1917 ascension <domain> <port> [-d] [-p]
1906 ascension.py <domain> -ns <transferns> [-d] 1918 ascension <domain> -ns <transferns> [-d] [-p]
1907 ascension.py <domain> -ns <transferns> -p <port> [-d] 1919 ascension <domain> -ns <transferns> <port> [-d] [-p]
1908 ascension.py -h | --help 1920 ascension -p | --public
1909 ascension.py -v | --version 1921 ascension -h | --help
1922 ascension -v | --version
1910 1923
1911Options: 1924Options:
1912 <port> Port for zone transfer
1913 <domain> Domain to migrate 1925 <domain> Domain to migrate
1926 <port> Port for zone transfer
1914 <transferns> DNS Server that does the zone transfer 1927 <transferns> DNS Server that does the zone transfer
1928 -p --public Make records public on the DHT
1915 -d --debug Enable debugging 1929 -d --debug Enable debugging
1916 -h --help Show this screen. 1930 -h --help Show this screen.
1917 -v --version Show version. 1931 -v --version Show version.
1918@end example 1932@end example
1919 1933
1934Before you can migrate any zone though, you need to start the GNUnet peer:
1935@example
1936$ gnunet-arm -s
1937@end example
1938
1920To migrate the Syrian top level domain - one of the few top level domains that 1939To migrate the Syrian top level domain - one of the few top level domains that
1921still supports zone transfers - use the following command: 1940still supports zone transfers - into GNS use the following command:
1941
1942@example
1943$ ascension sy. -ns ns1.tld.sy. -p
1944@end example
1945
1946The -p flag will tell GNS to put these records on the DHT so that other users
1947may resolve these records by using the public key of the zone.
1948
1949Once the zone is migrated, Ascension will output a message telling you, that it
1950will refresh the zone after the time has elapsed. You can resolve the names in
1951the zone directly using GNS or if you want to use it with your browser, check
1952out the GNS manual section. @ref{Configuring the GNU Name System}. To resolve
1953the records from another system you need the zone PKEY. To get the zone key,
1954you can run the following command:
1955
1956@example
1957$ gnunet-identity -d | grep ^sy | cut -d " " -f3
1958@end example
1959
1960Where "sy" is the name of the zone you want to migrate.
1961
1962As soon as the public flag is implemented, you can share the PKEY of the zone
1963with your friends. They can then resolve records in the zone by doing a lookup
1964replacing the zone label with your PKEY:
1922 1965
1923@example 1966@example
1924$ ascension sy. -ns ns1.tld.sy. 1967$ gnunet-gns -t SOA -u "@.$PKEY"
1925@end example 1968@end example
1926 1969
1927The program will continue to run as a daemon and update once the refresh time 1970The program will continue to run as a daemon and update once the refresh time
1928specified in the zones SOA record has elapsed. 1971specified in the zones SOA record has elapsed.
1929 1972
1973The next step would be to add the PKEY record as a DNScurve style NS record
1974into the existing DNS zone to enable clients to detect that this zone has
1975already been migrated to GNS and to also have a means of distributing the PKEY
1976seamlessly.
1977
1930At this point you might want to write for example a systemd unit file to start 1978At this point you might want to write for example a systemd unit file to start
1931and enable the service, so that your zone is migrated automatically. 1979and enable the service, so that your zone is migrated automatically.
1932 1980