diff options
Diffstat (limited to 'doc/handbook/chapters')
-rw-r--r-- | doc/handbook/chapters/developer.texi | 119 | ||||
-rw-r--r-- | doc/handbook/chapters/installation.texi | 5 | ||||
-rw-r--r-- | doc/handbook/chapters/user.texi | 9 |
3 files changed, 125 insertions, 8 deletions
diff --git a/doc/handbook/chapters/developer.texi b/doc/handbook/chapters/developer.texi index 37e11cb11..af3ac0197 100644 --- a/doc/handbook/chapters/developer.texi +++ b/doc/handbook/chapters/developer.texi | |||
@@ -7743,6 +7743,7 @@ record types. | |||
7743 | * The GNS Client-Service Protocol:: | 7743 | * The GNS Client-Service Protocol:: |
7744 | * Hijacking the DNS-Traffic using gnunet-service-dns:: | 7744 | * Hijacking the DNS-Traffic using gnunet-service-dns:: |
7745 | * Serving DNS lookups via GNS on W32:: | 7745 | * Serving DNS lookups via GNS on W32:: |
7746 | * Importing DNS Zones into GNS:: | ||
7746 | @end menu | 7747 | @end menu |
7747 | 7748 | ||
7748 | @node libgnunetgns | 7749 | @node libgnunetgns |
@@ -8073,6 +8074,124 @@ applications that use alternative means of resolving names (such as | |||
8073 | sending queries to a DNS server directly by themselves). | 8074 | sending queries to a DNS server directly by themselves). |
8074 | This includes some of well known utilities, like "ping" and "nslookup". | 8075 | This includes some of well known utilities, like "ping" and "nslookup". |
8075 | 8076 | ||
8077 | @node Importing DNS Zones into GNS | ||
8078 | @subsection Importing DNS Zones into GNS | ||
8079 | |||
8080 | @c %**end of header | ||
8081 | |||
8082 | This section will mainly comprise of the challenges and problems faced when | ||
8083 | writing the ascension tool. | ||
8084 | |||
8085 | When considering to migrate existing into GNS there are a few things to | ||
8086 | consider. | ||
8087 | |||
8088 | @menu | ||
8089 | * Conversions between DNS and GNS:: | ||
8090 | * DNS Zone Size:: | ||
8091 | * Performance:: | ||
8092 | @end menu | ||
8093 | |||
8094 | @node Conversions between DNS and GNS | ||
8095 | @subsubsection Conversions between DNS and GNS | ||
8096 | |||
8097 | The differences between the two name systems lies in the details | ||
8098 | and is not visible from the start. For instance an SRV record is converted to a | ||
8099 | gnunet only BOX record. | ||
8100 | |||
8101 | This is done by building a BOX record from an existing SRV record: | ||
8102 | |||
8103 | @example | ||
8104 | # _service._proto.name. TTL class SRV priority weight port target | ||
8105 | _sip._tcp.example.com. 14000 IN SRV 0 0 5060 www.example.com. | ||
8106 | @end example | ||
8107 | |||
8108 | Which can be transformed to a GNS BOX record by converting it like this: | ||
8109 | |||
8110 | @example | ||
8111 | # TTL BOX flags port protocol recordtype priority weight port target | ||
8112 | 14000 BOX n 5060 6 33 0 0 5060 www.example.com | ||
8113 | @end example | ||
8114 | |||
8115 | Other records that have such a transformation is the MX record type, as well as | ||
8116 | the SOA record type. | ||
8117 | |||
8118 | Transformation of a SOA record into GNS works as described in the following | ||
8119 | example. Very important to note are the rname and mname keys. | ||
8120 | @example | ||
8121 | # BIND syntax for a clean SOA record | ||
8122 | @ IN SOA master.example.com. hostmaster.example.com. ( | ||
8123 | 2017030300 ; serial | ||
8124 | 3600 ; refresh | ||
8125 | 1800 ; retry | ||
8126 | 604800 ; expire | ||
8127 | 600 ) ; ttl | ||
8128 | # Recordline for adding the record | ||
8129 | gnunet-namestore -z example.com -a -n @ -t SOA -V rname=master.example.com \ | ||
8130 | mname=hostmaster.example.com 2017030300,3600,1800,604800,600 -e 7200s | ||
8131 | @end example | ||
8132 | |||
8133 | The transformation of MX records is done in a simple way. | ||
8134 | @example | ||
8135 | # mail.example.com. 3600 IN MX 10 mail.example.com. | ||
8136 | gnunet-namestore -z example.com -n mail -R 3600 MX n 10,mail | ||
8137 | @end example | ||
8138 | |||
8139 | Finally, one of the biggest struggling points was the NS records that are found | ||
8140 | in top level domain zones. The inteded behaviour for those is to add GNS2DNS | ||
8141 | records for the zone so that gnunet-gns can resolve the for those domain on it's | ||
8142 | own. Also a very important aspect of this is, that gnunet needs to be able to | ||
8143 | resolve the nameservers from it's own database. This requires migration of the | ||
8144 | DNS GLUE records as well. | ||
8145 | |||
8146 | This proved to be quite a challenge to implement, as in GNS every dot is a | ||
8147 | strict zone cut. | ||
8148 | |||
8149 | The issue was fixed by creating a hierarchical zone structure in GNS and linking | ||
8150 | the zones using PKEY records to one another. This allows the resolution of the | ||
8151 | nameservers to work within GNS. | ||
8152 | |||
8153 | @node DNS Zone Size | ||
8154 | @subsubsection DNS Zone Size | ||
8155 | |||
8156 | Another very big problem exists with very large zones. When migrating a small | ||
8157 | zone the delay between adding of records and their expiry is negligible. However | ||
8158 | when working with a TLD zone that has more that 1 million records this delay | ||
8159 | becomes a problem. | ||
8160 | |||
8161 | Records will start to expire well before the zone has finished migrating. This | ||
8162 | causes unwanted anomalies when trying to resolve records. | ||
8163 | |||
8164 | A good solution has not been found yet. One of the idea that floated around was | ||
8165 | that the records should be added with the s (shadow) flag to keep the records | ||
8166 | resolvable even if they expired. However this would introduce the problem of how | ||
8167 | to detect if a record has been removed from the zone and would require deletion | ||
8168 | of said record(s). | ||
8169 | |||
8170 | @node Performance | ||
8171 | @subsubsection Performance | ||
8172 | The performance when migrating a zone using the ascension tool is limited by a | ||
8173 | handful of factors. First of all ascension is written in python3 and calls the | ||
8174 | CLI tools of gnunet. Furthermore all the records that are added to the same | ||
8175 | label are signed using the zones private key. This signing operation is very | ||
8176 | resource heavy and was optimized during development by adding the '-R' | ||
8177 | (Recordline) option to gnunet-namestore. This allows to add multiple records | ||
8178 | at once using the CLI. | ||
8179 | |||
8180 | The result of this was a much faster migration of TLD zones, as most records | ||
8181 | with the same label have two nameservers. | ||
8182 | |||
8183 | Another improvement that could be made is with the addition of multiple threads | ||
8184 | when opening the gnunet CLI tools. This could be implemented by simply creating | ||
8185 | more workers in the program but performance improvements were not tested. | ||
8186 | |||
8187 | During the entire development of the ascension tool sqlite was used as a | ||
8188 | database backend. Other backends need to be tested in the future. | ||
8189 | |||
8190 | In conclusion there are many bottlenecks still around in the program, namely the | ||
8191 | signing process and the single threaded implementation. In the future a solution | ||
8192 | that uses the c api would be cleaner and better. | ||
8193 | |||
8194 | |||
8076 | @cindex GNS Namecache | 8195 | @cindex GNS Namecache |
8077 | @node GNS Namecache | 8196 | @node GNS Namecache |
8078 | @section GNS Namecache | 8197 | @section GNS Namecache |
diff --git a/doc/handbook/chapters/installation.texi b/doc/handbook/chapters/installation.texi index 5ce9805ed..9a64feef7 100644 --- a/doc/handbook/chapters/installation.texi +++ b/doc/handbook/chapters/installation.texi | |||
@@ -1712,10 +1712,9 @@ Or installed globally like this (not recommended): | |||
1712 | $ sudo python3 setup.py install | 1712 | $ sudo python3 setup.py install |
1713 | @end example | 1713 | @end example |
1714 | 1714 | ||
1715 | 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. | 1715 | 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 their dependencies. |
1716 | 1716 | ||
1717 | @c How to reference another section here? | 1717 | Using the tool is discussed in the user section of the documentation. |
1718 | Using the tool is discussed in another section. | ||
1719 | 1718 | ||
1720 | 1719 | ||
1721 | @node Configuring the GNUnet VPN | 1720 | @node Configuring the GNUnet VPN |
diff --git a/doc/handbook/chapters/user.texi b/doc/handbook/chapters/user.texi index 79c6563a1..76d39b50e 100644 --- a/doc/handbook/chapters/user.texi +++ b/doc/handbook/chapters/user.texi | |||
@@ -1632,8 +1632,6 @@ GNS currently supports the following record types: | |||
1632 | * ABE MASTER:: | 1632 | * ABE MASTER:: |
1633 | * RECLAIM OIDC CLIENT:: | 1633 | * RECLAIM OIDC CLIENT:: |
1634 | * RECLAIM OIDC REDIRECT:: | 1634 | * RECLAIM OIDC REDIRECT:: |
1635 | * Synchronizing with legacy DNS:: | ||
1636 | * Migrating an existing DNS zone into GNS:: | ||
1637 | @end menu | 1635 | @end menu |
1638 | 1636 | ||
1639 | @node NICK | 1637 | @node NICK |
@@ -1897,7 +1895,7 @@ option ``DISABLE'' to ``YES'' in section ``[namecache]''. | |||
1897 | @node Migrating an existing DNS zone into GNS | 1895 | @node Migrating an existing DNS zone into GNS |
1898 | @subsection Migrating an existing DNS zone into GNS | 1896 | @subsection Migrating an existing DNS zone into GNS |
1899 | 1897 | ||
1900 | After installing the tool according to the README file you have these options: | 1898 | After installing the tool according to the README file you have the following options: |
1901 | @example | 1899 | @example |
1902 | Ascension | 1900 | Ascension |
1903 | 1901 | ||
@@ -1926,8 +1924,9 @@ $ ascension sy. -ns ns1.tld.sy. | |||
1926 | 1924 | ||
1927 | This will take a while but after it has finished executing the zone will have been migrated into GNS. | 1925 | This will take a while but after it has finished executing the zone will have been migrated into GNS. |
1928 | 1926 | ||
1929 | @c remove this once daemonized | 1927 | The program will continue to run daemon and update once the refresh time specified in the zones SOA record has elapsed. |
1930 | 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. | 1928 | |
1929 | At this point it is trivial to write for example a systemd unit file and to enable the service, so that your zone is migrated periodically. | ||
1931 | 1930 | ||
1932 | @node re@:claim Identity Provider | 1931 | @node re@:claim Identity Provider |
1933 | @section re@:claim Identity Provider | 1932 | @section re@:claim Identity Provider |