diff options
author | rexxnor <rexxnor+gnunet@brief.li> | 2019-01-30 18:49:50 +0100 |
---|---|---|
committer | rexxnor <rexxnor+gnunet@brief.li> | 2019-01-30 18:53:05 +0100 |
commit | e3f6a5c29d2ea1cef92e10f142b7883ee6347ca7 (patch) | |
tree | fc00cb008568945fd947dc86f24efde7b35aed63 /doc | |
parent | 404c9065789248a5eba44fb4bc320bfeaa988da6 (diff) | |
download | gnunet-e3f6a5c29d2ea1cef92e10f142b7883ee6347ca7.tar.gz gnunet-e3f6a5c29d2ea1cef92e10f142b7883ee6347ca7.zip |
updated ascension documentation
Diffstat (limited to 'doc')
-rw-r--r-- | doc/handbook/chapters/developer.texi | 71 | ||||
-rw-r--r-- | doc/handbook/chapters/installation.texi | 24 | ||||
-rw-r--r-- | 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". | |||
8080 | @c %**end of header | 8080 | @c %**end of header |
8081 | 8081 | ||
8082 | This section discusses the challenges and problems faced when writing the | 8082 | This section discusses the challenges and problems faced when writing the |
8083 | ascension tool. It also takes a look at possible improvements in the future. | 8083 | Ascension 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 | ||
8094 | The differences between the two name systems lies in the details | 8094 | The differences between the two name systems lies in the details |
8095 | and is not always transparent. For instance an SRV record is converted to a | 8095 | and is not always transparent. For instance an SRV record is converted to a |
8096 | gnunet only BOX record. | 8096 | GNS only BOX record. |
8097 | 8097 | ||
8098 | This is done by converting to a BOX record from an existing SRV record: | 8098 | This 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 |
8123 | gnunet-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 | ||
8127 | The transformation of MX records is done in a simple way. | 8127 | The 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. |
8130 | gnunet-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 | ||
8133 | Finally, one of the biggest struggling points were the NS records that are found | 8133 | 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 | |||
8136 | its own. This requires migration of the DNS GLUE records as well, provided that | 8136 | its own. This requires migration of the DNS GLUE records as well, provided that |
8137 | they are within the same zone. | 8137 | they are within the same zone. |
8138 | 8138 | ||
8139 | The following two examples show one record with a GLUE record and the other one | ||
8140 | does 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 | |||
8151 | As you can see, one of the GNS2DNS records has an IP address listed and the | ||
8152 | other one a DNS name. For the first one there is a GLUE record to do the | ||
8153 | translation directly and the second one will issue another DNS query to figure | ||
8154 | out the IP of ns1.example.org. | ||
8155 | |||
8139 | A solution was found by creating a hierarchical zone structure in GNS and linking | 8156 | A solution was found by creating a hierarchical zone structure in GNS and linking |
8140 | the zones using PKEY records to one another. This allows the resolution of the | 8157 | the zones using PKEY records to one another. This allows the resolution of the |
8141 | nameservers to work within GNS while not taking control over unwanted zones. | 8158 | name servers to work within GNS while not taking control over unwanted zones. |
8159 | |||
8160 | Currently 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 | |||
8171 | This is not due to a technical limitation but rather a practical one. The | ||
8172 | problem occurs with DNSSEC enabled DNS zones. As records within those zones are | ||
8173 | signed periodically, and every new signature is an update to the zone, there are | ||
8174 | many revisions of zones. This results in a problem with bigger zones as there | ||
8175 | are lots of records that have been signed again but no major changes. Also | ||
8176 | trying to add records that are unknown that require a different format take time | ||
8177 | as they cause a CLI call of the namestore. Furthermore certain record types | ||
8178 | need transformation into a GNS compatible format which, depending on the record | ||
8179 | type, 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 | |||
8162 | gnunet-gns. When doing incremental zone transfers this becomes especially | 8200 | gnunet-gns. When doing incremental zone transfers this becomes especially |
8163 | apparent. | 8201 | apparent. |
8164 | 8202 | ||
8203 | I estimate that the limit lies at about 200'000 records in a zone as this is | ||
8204 | the limit that my machine is capable of adding within one hour. This was | ||
8205 | calculated by running cProfile on the application with a zone of 5000 records | ||
8206 | and calculating what abouts a much bigger zones with 8 million records would | ||
8207 | take. This results in a nice metric of records migrated per hour. | ||
8208 | |||
8165 | @node Performance | 8209 | @node Performance |
8166 | @subsubsection Performance | 8210 | @subsubsection Performance |
8167 | The performance when migrating a zone using the ascension tool is limited by a | 8211 | The performance when migrating a zone using the Ascension tool is limited by a |
8168 | handful of factors. First of all ascension is written in python3 and calls the | 8212 | handful of factors. First of all ascension is written in Python3 and calls the |
8169 | CLI tools of gnunet. Furthermore all the records that are added to the same | 8213 | CLI tools of GNUnet. Furthermore all the records that are added to the same |
8170 | label are signed using the zones private key. This signing operation is very | 8214 | label are signed using the zones private key. This signing operation is very |
8171 | resource heavy and was optimized during development by adding the '-R' | 8215 | resource 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 | |||
8176 | with the same label have two name servers. | 8220 | with the same label have two name servers. |
8177 | 8221 | ||
8178 | Another improvement that could be made is with the addition of multiple threads | 8222 | Another improvement that could be made is with the addition of multiple threads |
8179 | when opening the gnunet CLI tools. This could be implemented by simply creating | 8223 | when opening the GNUnet CLI tools. This could be implemented by simply creating |
8180 | more workers in the program but performance improvements were not tested. | 8224 | more workers in the program but performance improvements were not tested. |
8181 | 8225 | ||
8182 | During the entire development of the ascension tool sqlite was used as a | 8226 | During the entire development of Ascension sqlite was used as a database |
8183 | database backend. Other backends need to be tested in the future. | 8227 | backend for GNUnet. Other backends have not been tested yet. |
8184 | 8228 | ||
8185 | In conclusion there are many bottlenecks still around in the program, namely the | 8229 | In conclusion there are many bottlenecks still around in the program, namely the |
8186 | signing process and the single threaded implementation. In the future a solution | 8230 | signing process and the single threaded implementation. In the future a solution |
8187 | that uses the c api would be cleaner and better. | 8231 | that 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 | ||
1700 | To migrate an existing zone into GNS use the ascension tool. | 1700 | To migrate an existing zone into GNS use the Ascension tool. |
1701 | 1701 | ||
1702 | Ascension transfers entire zones into GNS by doing incremental zone transfers | 1702 | Ascension transfers entire zones into GNS by doing incremental zone transfers |
1703 | and then adding the records to GNS. | 1703 | and then adding the records to GNS. |
1704 | 1704 | ||
1705 | Compared to the gnunet-zoneimport tool it strictly uses AXFR or IXFR depending | ||
1706 | on whether or not there exists a SOA record for the zone. If that is the case it | ||
1707 | will take the serial as a reference point and request the zone. The server will | ||
1708 | either answer the IXFR request with a correct incremental zone or with the | ||
1709 | entire zone, which depends on the server configuration. | ||
1710 | |||
1705 | You can find the source code here: @code{https://gnunet.org/git/ascension.git/} | 1711 | You can find the source code here: @code{https://gnunet.org/git/ascension.git/} |
1706 | 1712 | ||
1707 | The software can be installed into a python virtual environment like this: | 1713 | The 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 | ||
1714 | Or installed globally like this (not recommended): | 1720 | Or 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 | ||
1719 | The advantage of using a virtual environment is, that all the dependencies can | 1725 | Pip will then install all the necessary requirements that are needed to run |
1720 | be installed separately in different versions without touching your existing | 1726 | Ascension. For development purposes a virtual environment should suffice. |
1721 | python installation and its dependencies. | 1727 | Keeping a virtual environment helps with keeping things tidy and prevents |
1728 | breaking of Ascension through a future Python update. | ||
1722 | 1729 | ||
1723 | Using the tool is discussed in the user section of the documentation. | 1730 | The advantage of using a virtual environment is, that all the dependencies can |
1731 | be installed separately in different versions without touching your system | ||
1732 | Python 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 | ||
1898 | Ascension is a tool to migrate existing DNS zones into GNS. | ||
1899 | |||
1900 | @xref{Migrating existing DNS zones into GNS} for installation instructions and | ||
1901 | further information about Ascension. | ||
1902 | |||
1903 | Compared to the gnunet-zoneimport tool it strictly uses AXFR or IXFR depending | ||
1904 | on whether or not there exists a SOA record for the zone. If that is the case it | ||
1905 | will take the serial as a reference point and request the zone. The server will | ||
1906 | either answer the IXFR request with a correct incremental zone or with the | ||
1907 | entire zone, which depends on the server configuration. | ||
1908 | |||
1898 | After installing the tool according to the README file you have the following | 1909 | After installing the tool according to the README file you have the following |
1899 | options: | 1910 | options: |
1911 | |||
1900 | @example | 1912 | @example |
1901 | Ascension | 1913 | Ascension |
1902 | 1914 | ||
1903 | Usage: | 1915 | Usage: |
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 | ||
1911 | Options: | 1924 | Options: |
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 | ||
1934 | Before you can migrate any zone though, you need to start the GNUnet peer: | ||
1935 | @example | ||
1936 | $ gnunet-arm -s | ||
1937 | @end example | ||
1938 | |||
1920 | To migrate the Syrian top level domain - one of the few top level domains that | 1939 | To migrate the Syrian top level domain - one of the few top level domains that |
1921 | still supports zone transfers - use the following command: | 1940 | still supports zone transfers - into GNS use the following command: |
1941 | |||
1942 | @example | ||
1943 | $ ascension sy. -ns ns1.tld.sy. -p | ||
1944 | @end example | ||
1945 | |||
1946 | The -p flag will tell GNS to put these records on the DHT so that other users | ||
1947 | may resolve these records by using the public key of the zone. | ||
1948 | |||
1949 | Once the zone is migrated, Ascension will output a message telling you, that it | ||
1950 | will refresh the zone after the time has elapsed. You can resolve the names in | ||
1951 | the zone directly using GNS or if you want to use it with your browser, check | ||
1952 | out the GNS manual section. @ref{Configuring the GNU Name System}. To resolve | ||
1953 | the records from another system you need the zone PKEY. To get the zone key, | ||
1954 | you can run the following command: | ||
1955 | |||
1956 | @example | ||
1957 | $ gnunet-identity -d | grep ^sy | cut -d " " -f3 | ||
1958 | @end example | ||
1959 | |||
1960 | Where "sy" is the name of the zone you want to migrate. | ||
1961 | |||
1962 | As soon as the public flag is implemented, you can share the PKEY of the zone | ||
1963 | with your friends. They can then resolve records in the zone by doing a lookup | ||
1964 | replacing 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 | ||
1927 | The program will continue to run as a daemon and update once the refresh time | 1970 | The program will continue to run as a daemon and update once the refresh time |
1928 | specified in the zones SOA record has elapsed. | 1971 | specified in the zones SOA record has elapsed. |
1929 | 1972 | ||
1973 | The next step would be to add the PKEY record as a DNScurve style NS record | ||
1974 | into the existing DNS zone to enable clients to detect that this zone has | ||
1975 | already been migrated to GNS and to also have a means of distributing the PKEY | ||
1976 | seamlessly. | ||
1977 | |||
1930 | At this point you might want to write for example a systemd unit file to start | 1978 | At this point you might want to write for example a systemd unit file to start |
1931 | and enable the service, so that your zone is migrated automatically. | 1979 | and enable the service, so that your zone is migrated automatically. |
1932 | 1980 | ||