diff options
Diffstat (limited to 'doc/handbook')
-rw-r--r-- | doc/handbook/chapters/developer.texi | 338 | ||||
-rw-r--r-- | doc/handbook/chapters/installation.texi | 15 | ||||
-rw-r--r-- | doc/handbook/chapters/keyconcepts.texi | 1 | ||||
-rw-r--r-- | doc/handbook/chapters/user.texi | 273 | ||||
-rw-r--r-- | doc/handbook/images/ascension_interaction.png | bin | 0 -> 1992878 bytes | |||
-rw-r--r-- | doc/handbook/images/ascension_ssd.png | bin | 0 -> 69446 bytes |
6 files changed, 255 insertions, 372 deletions
diff --git a/doc/handbook/chapters/developer.texi b/doc/handbook/chapters/developer.texi index 228603cda..830a345a8 100644 --- a/doc/handbook/chapters/developer.texi +++ b/doc/handbook/chapters/developer.texi | |||
@@ -79,6 +79,7 @@ new chapters, sections or insightful comments. | |||
79 | * File-sharing (FS) Subsystem:: | 79 | * File-sharing (FS) Subsystem:: |
80 | * REGEX Subsystem:: | 80 | * REGEX Subsystem:: |
81 | * REST Subsystem:: | 81 | * REST Subsystem:: |
82 | * RPS Subsystem:: | ||
82 | @end menu | 83 | @end menu |
83 | 84 | ||
84 | @node Developer Introduction | 85 | @node Developer Introduction |
@@ -556,7 +557,7 @@ stacked together to construct complex buildings and it is generally easy | |||
556 | to swap one block for a different one that has the same shape. GNUnet's | 557 | to swap one block for a different one that has the same shape. GNUnet's |
557 | architecture is based on LEGOs: | 558 | architecture is based on LEGOs: |
558 | 559 | ||
559 | @c @image{images/service_lego_block,5in,,picture of a LEGO block stack - 3 APIs as connectors upon Network Protocol on top of a Service} | 560 | @image{images/service_lego_block,5in,,picture of a LEGO block stack - 3 APIs upon IPC/network protocol provided by a service} |
560 | 561 | ||
561 | This chapter documents the GNUnet LEGO system, also known as GNUnet's | 562 | This chapter documents the GNUnet LEGO system, also known as GNUnet's |
562 | system architecture. | 563 | system architecture. |
@@ -573,10 +574,14 @@ Like services, they have holes to be filled by APIs of other services. | |||
573 | Unlike services, daemons do not implement their own network protocol and | 574 | Unlike services, daemons do not implement their own network protocol and |
574 | they have no API: | 575 | they have no API: |
575 | 576 | ||
577 | @image{images/daemon_lego_block,5in,,A daemon in GNUnet is a component that does not offer an API for others to build upon} | ||
578 | |||
576 | The GNUnet system provides a range of services, daemons and user | 579 | The GNUnet system provides a range of services, daemons and user |
577 | interfaces, which are then combined into a layered GNUnet instance (also | 580 | interfaces, which are then combined into a layered GNUnet instance (also |
578 | known as a peer). | 581 | known as a peer). |
579 | 582 | ||
583 | @image{images/service_stack,5in,,A GNUnet peer consists of many layers of services} | ||
584 | |||
580 | Note that while it is generally possible to swap one service for another | 585 | Note that while it is generally possible to swap one service for another |
581 | compatible service, there is often only one implementation. However, | 586 | compatible service, there is often only one implementation. However, |
582 | during development we often have a "new" version of a service in parallel | 587 | during development we often have a "new" version of a service in parallel |
@@ -1876,7 +1881,6 @@ Testbed API can accessed by including the | |||
1876 | * Hosts file format:: | 1881 | * Hosts file format:: |
1877 | * Topology file format:: | 1882 | * Topology file format:: |
1878 | * Testbed Barriers:: | 1883 | * Testbed Barriers:: |
1879 | * Automatic large-scale deployment in the PlanetLab testbed:: | ||
1880 | * TESTBED Caveats:: | 1884 | * TESTBED Caveats:: |
1881 | @end menu | 1885 | @end menu |
1882 | 1886 | ||
@@ -2140,168 +2144,6 @@ message from its upward propagation --- the upward propagation is needed | |||
2140 | for ensuring that the barrier is reached by all the controllers and the | 2144 | for ensuring that the barrier is reached by all the controllers and the |
2141 | downward propagation is for triggering that the barrier is crossed. | 2145 | downward propagation is for triggering that the barrier is crossed. |
2142 | 2146 | ||
2143 | @cindex PlanetLab testbed | ||
2144 | @node Automatic large-scale deployment in the PlanetLab testbed | ||
2145 | @subsection Automatic large-scale deployment in the PlanetLab testbed | ||
2146 | |||
2147 | PlanetLab is a testbed for computer networking and distributed systems | ||
2148 | research. It was established in 2002 and as of June 2010 was composed of | ||
2149 | 1090 nodes at 507 sites worldwide. | ||
2150 | |||
2151 | To automate the GNUnet we created a set of automation tools to simplify | ||
2152 | the large-scale deployment. We provide you a set of scripts you can use | ||
2153 | to deploy GNUnet on a set of nodes and manage your installation. | ||
2154 | |||
2155 | Please also check @uref{https://old.gnunet.org/installation-fedora8-svn} and | ||
2156 | @uref{https://old.gnunet.org/installation-fedora12-svn} to find detailed | ||
2157 | instructions how to install GNUnet on a PlanetLab node. | ||
2158 | |||
2159 | |||
2160 | @c *********************************************************************** | ||
2161 | @menu | ||
2162 | * PlanetLab Automation for Fedora8 nodes:: | ||
2163 | * Install buildslave on PlanetLab nodes running fedora core 8:: | ||
2164 | * Setup a new PlanetLab testbed using GPLMT:: | ||
2165 | * Why do i get an ssh error when using the regex profiler?:: | ||
2166 | @end menu | ||
2167 | |||
2168 | @node PlanetLab Automation for Fedora8 nodes | ||
2169 | @subsubsection PlanetLab Automation for Fedora8 nodes | ||
2170 | |||
2171 | @c *********************************************************************** | ||
2172 | @node Install buildslave on PlanetLab nodes running fedora core 8 | ||
2173 | @subsubsection Install buildslave on PlanetLab nodes running fedora core 8 | ||
2174 | @c ** Actually this is a subsubsubsection, but must be fixed differently | ||
2175 | @c ** as subsubsection is the lowest. | ||
2176 | |||
2177 | Since most of the PlanetLab nodes are running the very old Fedora core 8 | ||
2178 | image, installing the buildslave software is quite some pain. For our | ||
2179 | PlanetLab testbed we figured out how to install the buildslave software | ||
2180 | best. | ||
2181 | |||
2182 | @c This is a very terrible way to suggest installing software. | ||
2183 | @c FIXME: Is there an official, safer way instead of blind-piping a | ||
2184 | @c script? | ||
2185 | @c FIXME: Use newer pypi URLs below. | ||
2186 | Install Distribute for Python: | ||
2187 | |||
2188 | @example | ||
2189 | curl http://python-distribute.org/distribute_setup.py | sudo python | ||
2190 | @end example | ||
2191 | |||
2192 | Install Distribute for zope.interface <= 3.8.0 (4.0 and 4.0.1 will not | ||
2193 | work): | ||
2194 | |||
2195 | @example | ||
2196 | export PYPI=@value{PYPI-URL} | ||
2197 | wget $PYPI/z/zope.interface/zope.interface-3.8.0.tar.gz | ||
2198 | tar xzvf zope.interface-3.8.0.tar.gz | ||
2199 | cd zope.interface-3.8.0 | ||
2200 | sudo python setup.py install | ||
2201 | @end example | ||
2202 | |||
2203 | Install the buildslave software (0.8.6 was the latest version): | ||
2204 | |||
2205 | @example | ||
2206 | export GCODE="http://buildbot.googlecode.com/files" | ||
2207 | wget $GCODE/buildbot-slave-0.8.6p1.tar.gz | ||
2208 | tar xvfz buildbot-slave-0.8.6p1.tar.gz | ||
2209 | cd buildslave-0.8.6p1 | ||
2210 | sudo python setup.py install | ||
2211 | @end example | ||
2212 | |||
2213 | The setup will download the matching twisted package and install it. | ||
2214 | It will also try to install the latest version of zope.interface which | ||
2215 | will fail to install. Buildslave will work anyway since version 3.8.0 | ||
2216 | was installed before! | ||
2217 | |||
2218 | @c *********************************************************************** | ||
2219 | @node Setup a new PlanetLab testbed using GPLMT | ||
2220 | @subsubsection Setup a new PlanetLab testbed using GPLMT | ||
2221 | |||
2222 | @itemize @bullet | ||
2223 | @item Get a new slice and assign nodes | ||
2224 | Ask your PlanetLab PI to give you a new slice and assign the nodes you | ||
2225 | need | ||
2226 | @item Install a buildmaster | ||
2227 | You can stick to the buildbot documentation:@ | ||
2228 | @uref{http://buildbot.net/buildbot/docs/current/manual/installation.html} | ||
2229 | @item Install the buildslave software on all nodes | ||
2230 | To install the buildslave on all nodes assigned to your slice you can use | ||
2231 | the tasklist @code{install_buildslave_fc8.xml} provided with GPLMT: | ||
2232 | |||
2233 | @example | ||
2234 | ./gplmt.py -c contrib/tumple_gnunet.conf -t \ | ||
2235 | contrib/tasklists/install_buildslave_fc8.xml -a -p <planetlab password> | ||
2236 | @end example | ||
2237 | |||
2238 | @item Create the buildmaster configuration and the slave setup commands | ||
2239 | |||
2240 | The master and the and the slaves have need to have credentials and the | ||
2241 | master has to have all nodes configured. This can be done with the | ||
2242 | @file{create_buildbot_configuration.py} script in the @file{scripts} | ||
2243 | directory. | ||
2244 | |||
2245 | This scripts takes a list of nodes retrieved directly from PlanetLab or | ||
2246 | read from a file and a configuration template and creates: | ||
2247 | |||
2248 | @itemize @bullet | ||
2249 | @item a tasklist which can be executed with gplmt to setup the slaves | ||
2250 | @item a master.cfg file containing a PlanetLab nodes | ||
2251 | @end itemize | ||
2252 | |||
2253 | A configuration template is included in the <contrib>, most important is | ||
2254 | that the script replaces the following tags in the template: | ||
2255 | |||
2256 | %GPLMT_BUILDER_DEFINITION :@ GPLMT_BUILDER_SUMMARY@ GPLMT_SLAVES@ | ||
2257 | %GPLMT_SCHEDULER_BUILDERS | ||
2258 | |||
2259 | Create configuration for all nodes assigned to a slice: | ||
2260 | |||
2261 | @example | ||
2262 | ./create_buildbot_configuration.py -u <planetlab username> \ | ||
2263 | -p <planetlab password> -s <slice> -m <buildmaster+port> \ | ||
2264 | -t <template> | ||
2265 | @end example | ||
2266 | |||
2267 | Create configuration for some nodes in a file: | ||
2268 | |||
2269 | @example | ||
2270 | ./create_buildbot_configuration.p -f <node_file> \ | ||
2271 | -m <buildmaster+port> -t <template> | ||
2272 | @end example | ||
2273 | |||
2274 | @item Copy the @file{master.cfg} to the buildmaster and start it | ||
2275 | Use @code{buildbot start <basedir>} to start the server | ||
2276 | @item Setup the buildslaves | ||
2277 | @end itemize | ||
2278 | |||
2279 | @c *********************************************************************** | ||
2280 | @node Why do i get an ssh error when using the regex profiler? | ||
2281 | @subsubsection Why do i get an ssh error when using the regex profiler? | ||
2282 | |||
2283 | Why do i get an ssh error "Permission denied (publickey,password)." when | ||
2284 | using the regex profiler although passwordless ssh to localhost works | ||
2285 | using publickey and ssh-agent? | ||
2286 | |||
2287 | You have to generate a public/private-key pair with no password:@ | ||
2288 | @code{ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_localhost}@ | ||
2289 | and then add the following to your ~/.ssh/config file: | ||
2290 | |||
2291 | @code{Host 127.0.0.1@ IdentityFile ~/.ssh/id_localhost} | ||
2292 | |||
2293 | now make sure your hostsfile looks like | ||
2294 | |||
2295 | @example | ||
2296 | [USERNAME]@@127.0.0.1:22@ | ||
2297 | [USERNAME]@@127.0.0.1:22 | ||
2298 | @end example | ||
2299 | |||
2300 | You can test your setup by running @code{ssh 127.0.0.1} in a | ||
2301 | terminal and then in the opened session run it again. | ||
2302 | If you were not asked for a password on either login, | ||
2303 | then you should be good to go. | ||
2304 | |||
2305 | @cindex TESTBED Caveats | 2147 | @cindex TESTBED Caveats |
2306 | @node TESTBED Caveats | 2148 | @node TESTBED Caveats |
2307 | @subsection TESTBED Caveats | 2149 | @subsection TESTBED Caveats |
@@ -8116,6 +7958,14 @@ This section discusses the challenges and problems faced when writing the | |||
8116 | Ascension tool. It also takes a look at possible improvements in the | 7958 | Ascension tool. It also takes a look at possible improvements in the |
8117 | future. | 7959 | future. |
8118 | 7960 | ||
7961 | Consider the following diagram that shows the workflow of Ascension: | ||
7962 | |||
7963 | @image{images/ascension_ssd,6in,,Ascensions workflow} | ||
7964 | |||
7965 | Further the interaction between components of GNUnet are shown in the diagram | ||
7966 | below: | ||
7967 | @center @image{images/ascension_interaction,,6in,Ascensions workflow} | ||
7968 | |||
8119 | @menu | 7969 | @menu |
8120 | * Conversions between DNS and GNS:: | 7970 | * Conversions between DNS and GNS:: |
8121 | * DNS Zone Size:: | 7971 | * DNS Zone Size:: |
@@ -8126,9 +7976,9 @@ future. | |||
8126 | @node Conversions between DNS and GNS | 7976 | @node Conversions between DNS and GNS |
8127 | @subsubsection Conversions between DNS and GNS | 7977 | @subsubsection Conversions between DNS and GNS |
8128 | 7978 | ||
8129 | The differences between the two name systems lies in the details | 7979 | The differences between the two name systems lies in the details and is not |
8130 | and is not always transparent. | 7980 | always transparent. For instance an SRV record is converted to a BOX record |
8131 | For instance an SRV record is converted to a GNS only BOX record. | 7981 | which is unique to GNS. |
8132 | 7982 | ||
8133 | This is done by converting to a BOX record from an existing SRV record: | 7983 | This is done by converting to a BOX record from an existing SRV record: |
8134 | 7984 | ||
@@ -8141,7 +7991,7 @@ _sip._tcp.example.com. 14000 IN SRV 0 0 5060 www.example.com. | |||
8141 | 14000 BOX n 5060 6 33 0 0 5060 www.example.com | 7991 | 14000 BOX n 5060 6 33 0 0 5060 www.example.com |
8142 | @end example | 7992 | @end example |
8143 | 7993 | ||
8144 | Other records that have such a transformation is the MX record type, | 7994 | Other records that need to undergo such transformation is the MX record type, |
8145 | as well as the SOA record type. | 7995 | as well as the SOA record type. |
8146 | 7996 | ||
8147 | Transformation of a SOA record into GNS works as described in the | 7997 | Transformation of a SOA record into GNS works as described in the |
@@ -8156,8 +8006,9 @@ following example. Very important to note are the rname and mname keys. | |||
8156 | 604800 ; expire | 8006 | 604800 ; expire |
8157 | 600 ) ; ttl | 8007 | 600 ) ; ttl |
8158 | # Recordline for adding the record | 8008 | # Recordline for adding the record |
8159 | $ gnunet-namestore -z example.com -a -n @ -t SOA -V rname=master.example.com \ | 8009 | $ gnunet-namestore -z example.com -a -n @ -t SOA -V \ |
8160 | mname=hostmaster.example.com 2017030300,3600,1800,604800,600 -e 7200s | 8010 | rname=master.example.com mname=hostmaster.example.com \ |
8011 | 2017030300,3600,1800,604800,600 -e 7200s | ||
8161 | @end example | 8012 | @end example |
8162 | 8013 | ||
8163 | The transformation of MX records is done in a simple way. | 8014 | The transformation of MX records is done in a simple way. |
@@ -8166,10 +8017,10 @@ The transformation of MX records is done in a simple way. | |||
8166 | $ gnunet-namestore -z example.com -n mail -R 3600 MX n 10,mail | 8017 | $ gnunet-namestore -z example.com -n mail -R 3600 MX n 10,mail |
8167 | @end example | 8018 | @end example |
8168 | 8019 | ||
8169 | Finally, one of the biggest struggling points were the NS records that are found | 8020 | Finally, one of the biggest struggling points were the NS records that are |
8170 | in top level domain zones. The intended behaviour for those is to add GNS2DNS | 8021 | found in top level domain zones. The intended behaviour for those is to add |
8171 | records for those so that gnunet-gns can resolve records for those domains on | 8022 | GNS2DNS records for those so that gnunet-gns can resolve records for those |
8172 | its own. This requires migration of the DNS GLUE records as well, provided that | 8023 | domains on its own. Those require the values from DNS GLUE records, provided |
8173 | they are within the same zone. | 8024 | they are within the same zone. |
8174 | 8025 | ||
8175 | The following two examples show one record with a GLUE record and the other one | 8026 | The following two examples show one record with a GLUE record and the other one |
@@ -8178,10 +8029,12 @@ does not have a GLUE record. This takes place in the 'com' TLD. | |||
8178 | @example | 8029 | @example |
8179 | # ns1.example.com 86400 IN A 127.0.0.1 | 8030 | # ns1.example.com 86400 IN A 127.0.0.1 |
8180 | # example.com 86400 IN NS ns1.example.com. | 8031 | # example.com 86400 IN NS ns1.example.com. |
8181 | $ gnunet-namestore -z com -n example -R 86400 GNS2DNS n example.com@@127.0.0.1 | 8032 | $ gnunet-namestore -z com -n example -R 86400 GNS2DNS n \ |
8033 | example.com@@127.0.0.1 | ||
8182 | 8034 | ||
8183 | # example.com 86400 IN NS ns1.example.org. | 8035 | # example.com 86400 IN NS ns1.example.org. |
8184 | $ gnunet-namestore -z com -n example -R 86400 GNS2DNS n example.com@@ns1.example.org | 8036 | $ gnunet-namestore -z com -n example -R 86400 GNS2DNS n \ |
8037 | example.com@@ns1.example.org | ||
8185 | @end example | 8038 | @end example |
8186 | 8039 | ||
8187 | As you can see, one of the GNS2DNS records has an IP address listed and the | 8040 | As you can see, one of the GNS2DNS records has an IP address listed and the |
@@ -8204,7 +8057,7 @@ Currently the following record types are supported: | |||
8204 | @item TXT | 8057 | @item TXT |
8205 | @end itemize | 8058 | @end itemize |
8206 | 8059 | ||
8207 | This is not due to a technical limitation but rather a practical one. The | 8060 | This is not due to technical limitations but rather a practical ones. The |
8208 | problem occurs with DNSSEC enabled DNS zones. As records within those zones are | 8061 | problem occurs with DNSSEC enabled DNS zones. As records within those zones are |
8209 | signed periodically, and every new signature is an update to the zone, there are | 8062 | signed periodically, and every new signature is an update to the zone, there are |
8210 | many revisions of zones. This results in a problem with bigger zones as there | 8063 | many revisions of zones. This results in a problem with bigger zones as there |
@@ -8214,16 +8067,22 @@ as they cause a CLI call of the namestore. Furthermore certain record types | |||
8214 | need transformation into a GNS compatible format which, depending on the record | 8067 | need transformation into a GNS compatible format which, depending on the record |
8215 | type, takes more time. | 8068 | type, takes more time. |
8216 | 8069 | ||
8070 | Further a blacklist was added to drop for instance DNSSEC related records. Also | ||
8071 | if a record type is neither in the white list nor the blacklist it is considered | ||
8072 | as a loss of data and a message is shown to the user. This helps with | ||
8073 | transparency and also with contributing, as the not supported record types can | ||
8074 | then be added accordingly. | ||
8075 | |||
8217 | @node DNS Zone Size | 8076 | @node DNS Zone Size |
8218 | @subsubsection DNS Zone Size | 8077 | @subsubsection DNS Zone Size |
8219 | |||
8220 | Another very big problem exists with very large zones. When migrating a small | 8078 | Another very big problem exists with very large zones. When migrating a small |
8221 | zone the delay between adding of records and their expiry is negligible. However | 8079 | zone the delay between adding of records and their expiry is negligible. However |
8222 | when working with a TLD zone that has more that 1 million records this delay | 8080 | when working with big zones that easily have more than a few million records |
8223 | becomes a problem. | 8081 | this delay becomes a problem. |
8224 | 8082 | ||
8225 | Records will start to expire well before the zone has finished migrating. This | 8083 | Records will start to expire well before the zone has finished migrating. This |
8226 | causes unwanted anomalies when trying to resolve records. | 8084 | is usually not a problem but can cause a high CPU load when a peer is restarted |
8085 | and the records have expired. | ||
8227 | 8086 | ||
8228 | A good solution has not been found yet. One of the idea that floated around was | 8087 | A good solution has not been found yet. One of the idea that floated around was |
8229 | that the records should be added with the s (shadow) flag to keep the records | 8088 | that the records should be added with the s (shadow) flag to keep the records |
@@ -8233,45 +8092,51 @@ of said record(s). | |||
8233 | 8092 | ||
8234 | Another problem that still persists is how to refresh records. Expired records | 8093 | Another problem that still persists is how to refresh records. Expired records |
8235 | are still displayed when calling gnunet-namestore but do not resolve with | 8094 | are still displayed when calling gnunet-namestore but do not resolve with |
8236 | gnunet-gns. When doing incremental zone transfers this becomes especially | 8095 | gnunet-gns. Zonemaster will sign the expired records again and make sure that |
8237 | apparent. | 8096 | the records are still valid. With a recent change this was fixed as gnunet-gns |
8097 | to improve the suffix lookup which allows for a fast lookup even with thousands | ||
8098 | of local egos. | ||
8099 | |||
8100 | Currently the pace of adding records in general is around 10 records per second. | ||
8101 | Crypto is the upper limit for adding of records. The performance of your machine | ||
8102 | can be tested with the perf_crypto_* tools. There is still a big discrepancy | ||
8103 | between the pace of Ascension and the theoretical limit. | ||
8238 | 8104 | ||
8239 | I estimate that the limit lies at about 200'000 records in a zone as this is | 8105 | A performance metric for measuring improvements has not yet been implemented in |
8240 | the limit that my machine is capable of adding within one hour. This was | 8106 | Ascension. |
8241 | calculated by running cProfile on the application with a zone of 5000 records | ||
8242 | and calculating what abouts a much bigger zones with 8 million records would | ||
8243 | take. This results in a nice metric of records migrated per hour. | ||
8244 | 8107 | ||
8245 | @node Performance | 8108 | @node Performance |
8246 | @subsubsection Performance | 8109 | @subsubsection Performance |
8247 | The performance when migrating a zone using the Ascension tool is limited by a | 8110 | The performance when migrating a zone using the Ascension tool is limited by a |
8248 | handful of factors. First of all ascension is written in Python3 and calls the | 8111 | handful of factors. First of all ascension is written in Python3 and calls the |
8249 | CLI tools of GNUnet. Furthermore all the records that are added to the same | 8112 | CLI tools of GNUnet. This is comparable to a fork and exec call which costs a |
8113 | few CPU cycles. Furthermore all the records that are added to the same | ||
8250 | label are signed using the zones private key. This signing operation is very | 8114 | label are signed using the zones private key. This signing operation is very |
8251 | resource heavy and was optimized during development by adding the '-R' | 8115 | resource heavy and was optimized during development by adding the '-R' |
8252 | (Recordline) option to gnunet-namestore. This allows to add multiple records | 8116 | (Recordline) option to gnunet-namestore which allows to specify multiple records |
8253 | at once using the CLI. | 8117 | using the CLI tool. Assuming that in a TLD zone every domain has at least two |
8254 | 8118 | name servers this halves the amount of signatures needed. | |
8255 | The result of this was a much faster migration of TLD zones, as most records | ||
8256 | with the same label have two name servers. | ||
8257 | 8119 | ||
8258 | Another improvement that could be made is with the addition of multiple threads | 8120 | Another improvement that could be made is with the addition of multiple threads |
8259 | when opening the GNUnet CLI tools. This could be implemented by simply creating | 8121 | or using asynchronous subprocesses when opening the GNUnet CLI tools. This could |
8260 | more workers in the program but performance improvements were not tested. | 8122 | be implemented by simply creating more workers in the program but performance |
8123 | improvements were not tested. | ||
8261 | 8124 | ||
8262 | During the entire development of Ascension sqlite was used as a database | 8125 | Ascension was tested using different hardware and database backends. Performance |
8263 | backend for GNUnet. Other backends have not been tested yet. | 8126 | differences between SQLite and postgresql are marginal and almost non existent. |
8127 | What did make a huge impact on record adding performance was the storage medium. | ||
8128 | On a traditional mechanical hard drive adding of records were slow compared to a | ||
8129 | solid state disk. | ||
8264 | 8130 | ||
8265 | In conclusion there are many bottlenecks still around in the program, namely the | 8131 | In conclusion there are many bottlenecks still around in the program, namely the |
8266 | signing process and the single threaded implementation. In the future a solution | 8132 | single threaded implementation and inefficient, sequential calls of |
8267 | that uses the C API would be cleaner and better. | 8133 | gnunet-namestore. In the future a solution that uses the C API would be cleaner |
8134 | and better. | ||
8268 | 8135 | ||
8269 | @cindex GNS Namecache | 8136 | @cindex GNS Namecache |
8270 | @node GNS Namecache | 8137 | @node GNS Namecache |
8271 | @section GNS Namecache | 8138 | @section GNS Namecache |
8272 | 8139 | ||
8273 | |||
8274 | |||
8275 | The NAMECACHE subsystem is responsible for caching (encrypted) resolution | 8140 | The NAMECACHE subsystem is responsible for caching (encrypted) resolution |
8276 | results of the GNU Name System (GNS). GNS makes zone information available | 8141 | results of the GNU Name System (GNS). GNS makes zone information available |
8277 | to other users via the DHT. However, as accessing the DHT for every | 8142 | to other users via the DHT. However, as accessing the DHT for every |
@@ -9007,3 +8872,72 @@ so please make sure that endpoints are unambiguous. | |||
9007 | 8872 | ||
9008 | This is WIP. Endpoints should be documented appropriately. | 8873 | This is WIP. Endpoints should be documented appropriately. |
9009 | Preferably using annotations. | 8874 | Preferably using annotations. |
8875 | |||
8876 | |||
8877 | @cindex RPS Subsystem | ||
8878 | @node RPS Subsystem | ||
8879 | @section RPS Subsystem | ||
8880 | |||
8881 | In literature, Random Peer Sampling (RPS) refers to the problem of | ||
8882 | reliably drawing random samples from an unstructured p2p network. | ||
8883 | |||
8884 | Doing so in a reliable manner is not only hard because of inherent | ||
8885 | problems but also because of possible malicious peers that could try to | ||
8886 | bias the selection. | ||
8887 | |||
8888 | It is useful for all kind of gossip protocols that require the selection | ||
8889 | of random peers in the whole network like gathering statistics, | ||
8890 | spreading and aggregating information in the network, load balancing and | ||
8891 | overlay topology management. | ||
8892 | |||
8893 | The approach chosen in the rps implementation in GNUnet follows the | ||
8894 | Brahms@uref{https://bib.gnunet.org/full/date.html\#2009_5f0} design. | ||
8895 | |||
8896 | The current state is "work in progress". There are a lot of things that | ||
8897 | need to be done, primarily finishing the experimental evaluation and a | ||
8898 | re-design of the API. | ||
8899 | |||
8900 | The abstract idea is to subscribe to connect to/start the rps service | ||
8901 | and request random peers that will be returned when they represent a | ||
8902 | random selection from the whole network with high probability. | ||
8903 | |||
8904 | An additional feature to the original Brahms-design is the selection of | ||
8905 | sub-groups: The GNUnet implementation of rps enables clients to ask for | ||
8906 | random peers from a group that is defined by a common shared secret. | ||
8907 | (The secret could of course also be public, depending on the use-case.) | ||
8908 | |||
8909 | Another addition to the original protocol was made: The sampler | ||
8910 | mechanism that was introduced in Brahms was slightly adapted and used to | ||
8911 | actually sample the peers and returned to the client. | ||
8912 | This is necessary as the original design only keeps peers connected to | ||
8913 | random other peers in the network. In order to return random peers to | ||
8914 | client requests independently random, they cannot be drawn from the | ||
8915 | connected peers. | ||
8916 | The adapted sampler makes sure that each request for random peers is | ||
8917 | independent from the others. | ||
8918 | |||
8919 | @node Brahms | ||
8920 | @subsection Brahms | ||
8921 | The high-level concept of Brahms is two-fold: Combining push-pull gossip | ||
8922 | with locally fixing a assumed bias using cryptographic min-wise | ||
8923 | permutations. | ||
8924 | The central data structure is the view - a peer's current local sample. | ||
8925 | This view is used to select peers to push to and pull from. | ||
8926 | This simple mechanism can be biased easily. For this reason Brahms | ||
8927 | 'fixes' the bias by using the so-called sampler. A data structure that | ||
8928 | takes a list of elements as input and outputs a random one of them | ||
8929 | independently of the frequency in the input set. Both an element that | ||
8930 | was put into the sampler a single time and an element that was put into | ||
8931 | it a million times have the same probability of being the output. | ||
8932 | This is achieved this is achieved with exploiting min-wise independent | ||
8933 | permutations. In rps we use HMACs: On the initialisation of a sampler | ||
8934 | element, a key is chosen at random. On each input the HMAC with the | ||
8935 | random key is computed. The sampler element keeps the element with the | ||
8936 | minimal HMAC. | ||
8937 | |||
8938 | In order to fix the bias in the view, a fraction of the elements in the | ||
8939 | view are sampled through the sampler from the random stream of peer IDs. | ||
8940 | |||
8941 | According to the theoretical analysis of Bortnikov et al. this suffices | ||
8942 | to keep the network connected and having random peers in the view. | ||
8943 | |||
diff --git a/doc/handbook/chapters/installation.texi b/doc/handbook/chapters/installation.texi index d02fc7f82..a508feb6a 100644 --- a/doc/handbook/chapters/installation.texi +++ b/doc/handbook/chapters/installation.texi | |||
@@ -1786,10 +1786,21 @@ Keeping a virtual environment helps with keeping things tidy and prevents | |||
1786 | breaking of Ascension through a future Python update. | 1786 | breaking of Ascension through a future Python update. |
1787 | 1787 | ||
1788 | The advantage of using a virtual environment is, that all the dependencies can | 1788 | The advantage of using a virtual environment is, that all the dependencies can |
1789 | be installed separately in different versions without touching your system | 1789 | be installed separately in different versions without touching your systems |
1790 | Python installation and its dependencies. | 1790 | Python installation and its dependencies. |
1791 | 1791 | ||
1792 | @xref{Migrating an existing DNS zone into GNS}, for usage manual of the tool. | 1792 | Another way to install Ascension on Debian is to install the python3-ascension |
1793 | package. It can be found within the above mentioned Ascension git repository. | ||
1794 | This also adds a system user ascension and runs a GNUnet peer in the | ||
1795 | background. Attention: This only works if a recent version of GNUnet is | ||
1796 | installed on your system. The version number of Ascension is chosen according | ||
1797 | to the required feature level of GNUnet. I.e. Ascension 0.11.5 is only | ||
1798 | compatible with GNUnet 0.11.5 and upwards. As Debian's packages for GNUnet are | ||
1799 | outdated even in experimental, you will need to install GNUnet manually. | ||
1800 | @xref{Installing GNUnet} | ||
1801 | |||
1802 | Please check @xref{Migrating an existing DNS zone into GNS}, for usage manual | ||
1803 | of the tool. | ||
1793 | 1804 | ||
1794 | @node Configuring the GNUnet VPN | 1805 | @node Configuring the GNUnet VPN |
1795 | @subsection Configuring the GNUnet VPN | 1806 | @subsection Configuring the GNUnet VPN |
diff --git a/doc/handbook/chapters/keyconcepts.texi b/doc/handbook/chapters/keyconcepts.texi index 4900ed328..bdfa5b631 100644 --- a/doc/handbook/chapters/keyconcepts.texi +++ b/doc/handbook/chapters/keyconcepts.texi | |||
@@ -319,3 +319,4 @@ Egos are your "identities" in GNUnet. Any user can assume multiple | |||
319 | identities, for example to separate their activities online. Egos can | 319 | identities, for example to separate their activities online. Egos can |
320 | correspond to "pseudonyms" or "real-world identities". Technically an | 320 | correspond to "pseudonyms" or "real-world identities". Technically an |
321 | ego is first of all a key pair of a public- and private-key. | 321 | ego is first of all a key pair of a public- and private-key. |
322 | |||
diff --git a/doc/handbook/chapters/user.texi b/doc/handbook/chapters/user.texi index 55518bc34..fcf5e7871 100644 --- a/doc/handbook/chapters/user.texi +++ b/doc/handbook/chapters/user.texi | |||
@@ -526,7 +526,7 @@ shell) and create an entry home-phone in your master zone. | |||
526 | For the record type, select PHONE. You should then see the | 526 | For the record type, select PHONE. You should then see the |
527 | PHONE dialog: | 527 | PHONE dialog: |
528 | 528 | ||
529 | @c image here | 529 | @image{images/gnunet-namestore-gtk-phone,5in,,Dialog to publish a PHONE record} |
530 | 530 | ||
531 | Note: Do not choose the expiry time to be 'Never'. If you | 531 | Note: Do not choose the expiry time to be 'Never'. If you |
532 | do that, you assert that this record will never change and | 532 | do that, you assert that this record will never change and |
@@ -645,7 +645,7 @@ Now, using your normal user (not the @code{gnunet} system user), run | |||
645 | master zone. For the record type, select @code{VPN}. You should then | 645 | master zone. For the record type, select @code{VPN}. You should then |
646 | see the VPN dialog: | 646 | see the VPN dialog: |
647 | 647 | ||
648 | @c insert image | 648 | @image{images/gnunet-namestore-gtk-vpn,5in,,Dialog to publish a VPN record} |
649 | 649 | ||
650 | Under peer, you need to supply the peer identity of your own peer. You can | 650 | Under peer, you need to supply the peer identity of your own peer. You can |
651 | obtain the respective string by running @command{gnunet-peerinfo -sq} | 651 | obtain the respective string by running @command{gnunet-peerinfo -sq} |
@@ -926,7 +926,7 @@ concepts that are used to achieve these goals. | |||
926 | * Files:: | 926 | * Files:: |
927 | * Keywords:: | 927 | * Keywords:: |
928 | * Directories:: | 928 | * Directories:: |
929 | * Pseudonyms:: | 929 | * Egos and File-Sharing:: |
930 | * Namespaces:: | 930 | * Namespaces:: |
931 | * Advertisements:: | 931 | * Advertisements:: |
932 | * Anonymity level:: | 932 | * Anonymity level:: |
@@ -984,69 +984,55 @@ typically includes the mime-type, description, a filename and | |||
984 | other meta information, and possibly even the full original file | 984 | other meta information, and possibly even the full original file |
985 | (if it was small). | 985 | (if it was small). |
986 | 986 | ||
987 | @node Pseudonyms | 987 | @node Egos and File-Sharing |
988 | @subsubsection Pseudonyms | 988 | @subsubsection Egos and File-Sharing |
989 | 989 | ||
990 | When sharing files, it is sometimes desirable to build a reputation as | ||
991 | a source for quality information. With egos, publishers can | ||
992 | (cryptographically) sign files, thereby demonstrating that various | ||
993 | files were published by the same entity. An ego thus allows users to | ||
994 | link different publication events, thereby deliberately reducing | ||
995 | anonymity to pseudonymity. | ||
990 | 996 | ||
991 | @b{Please note that the text in this subsection is outdated and needs} | 997 | Egos used in GNUnet's file-sharing for such pseudonymous publishing |
992 | @b{to be rewritten for version 0.10!} | 998 | also correspond to the egos used to identify and sign zones in the |
993 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | 999 | GNU Name System. However, if the same ego is used for file-sharing |
1000 | and for a GNS zone, this will weaken the privacy assurances provided | ||
1001 | by the anonymous file-sharing protocol. | ||
994 | 1002 | ||
995 | Pseudonyms in GNUnet are essentially public-private (RSA) key pairs | 1003 | Note that an ego is NOT bound to a GNUnet peer. There can be multiple |
996 | that allow a GNUnet user to maintain an identity (which may or may not | 1004 | egos for a single user, and users could (theoretically) share |
997 | be detached from their real-life identity). GNUnet's pseudonyms are not | 1005 | the private keys of an ego by copying the respective private keys. |
998 | file-sharing specific --- and they will likely be used by many GNUnet | ||
999 | applications where a user identity is required. | ||
1000 | 1006 | ||
1001 | Note that a pseudonym is NOT bound to a GNUnet peer. There can be multiple | ||
1002 | pseudonyms for a single user, and users could (theoretically) share the | ||
1003 | private pseudonym keys (currently only out-of-band by knowing which files | ||
1004 | to copy around). | ||
1005 | 1007 | ||
1006 | @node Namespaces | 1008 | @node Namespaces |
1007 | @subsubsection Namespaces | 1009 | @subsubsection Namespaces |
1008 | 1010 | ||
1011 | A namespace is a set of files that were signed by the same ego. | ||
1012 | Today, namespaces are implemented independently of GNS zones, but | ||
1013 | in the future we plan to merge the two such that a GNS zone can | ||
1014 | basically contain files using a file-sharing specific record type. | ||
1009 | 1015 | ||
1010 | @b{Please note that the text in this subsection is outdated and needs} | 1016 | Files (or directories) that have been signed and placed into a |
1011 | @b{to be rewritten for version 0.10!} | 1017 | namespace can be updated. Updates are identified as authentic if the |
1012 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | 1018 | same secret key was used to sign the update. |
1013 | |||
1014 | A namespace is a set of files that were signed by the same pseudonym. | ||
1015 | Files (or directories) that have been signed and placed into a namespace | ||
1016 | can be updated. Updates are identified as authentic if the same secret | ||
1017 | key was used to sign the update. Namespaces are also useful to establish | ||
1018 | a reputation, since all of the content in the namespace comes from the | ||
1019 | same entity (which does not have to be the same person). | ||
1020 | 1019 | ||
1021 | @node Advertisements | 1020 | @node Advertisements |
1022 | @subsubsection Advertisements | 1021 | @subsubsection Advertisements |
1023 | 1022 | ||
1024 | |||
1025 | @b{Please note that the text in this subsection is outdated and needs} | ||
1026 | @b{to be rewritten for version 0.10!} | ||
1027 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1028 | |||
1029 | Advertisements are used to notify other users about the existence of a | 1023 | Advertisements are used to notify other users about the existence of a |
1030 | namespace. Advertisements are propagated using the normal keyword search. | 1024 | namespace. Advertisements are propagated using the normal keyword |
1031 | When an advertisement is received (in response to a search), the namespace | 1025 | search. When an advertisement is received (in response to a search), |
1032 | is added to the list of namespaces available in the namespace-search | 1026 | the namespace is added to the list of namespaces available in the |
1033 | dialogs of gnunet-fs-gtk and printed by @code{gnunet-identity}. Whenever a | 1027 | namespace-search dialogs of gnunet-fs-gtk and printed by |
1034 | namespace is created, an appropriate advertisement can be generated. | 1028 | @code{gnunet-identity}. Whenever a namespace is created, an |
1035 | The default keyword for the advertising of namespaces is "namespace". | 1029 | appropriate advertisement can be generated. The default keyword for |
1036 | 1030 | the advertising of namespaces is "namespace". | |
1037 | Note that GNUnet differentiates between your pseudonyms (the identities | 1031 | |
1038 | that you control) and namespaces. If you create a pseudonym, you will | ||
1039 | not automatically see the respective namespace. You first have to create | ||
1040 | an advertisement for the namespace and find it using keyword | ||
1041 | search --- even for your own namespaces. The @command{gnunet-identity} | ||
1042 | tool is currently responsible for both managing pseudonyms and namespaces. | ||
1043 | This will likely change in the future to reduce the potential for | ||
1044 | confusion. | ||
1045 | 1032 | ||
1046 | @node Anonymity level | 1033 | @node Anonymity level |
1047 | @subsubsection Anonymity level | 1034 | @subsubsection Anonymity level |
1048 | 1035 | ||
1049 | |||
1050 | The anonymity level determines how hard it should be for an adversary to | 1036 | The anonymity level determines how hard it should be for an adversary to |
1051 | determine the identity of the publisher or the searcher/downloader. An | 1037 | determine the identity of the publisher or the searcher/downloader. An |
1052 | anonymity level of zero means that anonymity is not required. The default | 1038 | anonymity level of zero means that anonymity is not required. The default |
@@ -1066,10 +1052,10 @@ delays traffic. | |||
1066 | While higher anonymity levels may offer better privacy, they can also | 1052 | While higher anonymity levels may offer better privacy, they can also |
1067 | significantly hurt performance. | 1053 | significantly hurt performance. |
1068 | 1054 | ||
1055 | |||
1069 | @node Content Priority | 1056 | @node Content Priority |
1070 | @subsubsection Content Priority | 1057 | @subsubsection Content Priority |
1071 | 1058 | ||
1072 | |||
1073 | Depending on the peer's configuration, GNUnet peers migrate content | 1059 | Depending on the peer's configuration, GNUnet peers migrate content |
1074 | between peers. Content in this sense are individual blocks of a file, | 1060 | between peers. Content in this sense are individual blocks of a file, |
1075 | not necessarily entire files. When peers run out of space (due to | 1061 | not necessarily entire files. When peers run out of space (due to |
@@ -1083,10 +1069,10 @@ lowest priority. The priority of a block is decided by its popularity | |||
1083 | published locally, the base-priority that was specified by the user | 1069 | published locally, the base-priority that was specified by the user |
1084 | when the block was published initially. | 1070 | when the block was published initially. |
1085 | 1071 | ||
1072 | |||
1086 | @node Replication | 1073 | @node Replication |
1087 | @subsubsection Replication | 1074 | @subsubsection Replication |
1088 | 1075 | ||
1089 | |||
1090 | When peers migrate content to other systems, the replication level | 1076 | When peers migrate content to other systems, the replication level |
1091 | of a block is used to decide which blocks need to be migrated most | 1077 | of a block is used to decide which blocks need to be migrated most |
1092 | urgently. GNUnet will always push the block with the highest | 1078 | urgently. GNUnet will always push the block with the highest |
@@ -1098,99 +1084,37 @@ selection is simply random. | |||
1098 | @node Namespace Management | 1084 | @node Namespace Management |
1099 | @subsection Namespace Management | 1085 | @subsection Namespace Management |
1100 | 1086 | ||
1101 | 1087 | The @code{gnunet-identity} tool can be used to create egos. | |
1102 | @b{Please note that the text in this subsection is outdated and needs} | 1088 | By default, @code{gnunet-identity -D} simply |
1103 | @b{to be rewritten for version 0.10!} | 1089 | lists all locally available egos. |
1104 | |||
1105 | The @code{gnunet-identity} tool can be used to create pseudonyms and | ||
1106 | to advertise namespaces. By default, @code{gnunet-identity -D} simply | ||
1107 | lists all locally available pseudonyms. | ||
1108 | 1090 | ||
1109 | 1091 | ||
1110 | @menu | 1092 | @menu |
1111 | * Creating Pseudonyms:: | 1093 | * Creating Egos:: |
1112 | * Deleting Pseudonyms:: | 1094 | * Deleting Egos:: |
1113 | * Advertising namespaces:: | ||
1114 | * Namespace names:: | ||
1115 | * Namespace root:: | ||
1116 | @end menu | 1095 | @end menu |
1117 | 1096 | ||
1118 | @node Creating Pseudonyms | 1097 | @node Creating Egos |
1119 | @subsubsection Creating Pseudonyms | 1098 | @subsubsection Creating Egos |
1120 | 1099 | ||
1100 | With the @command{-C NICK} option it can also be used to create a new | ||
1101 | ego. An ego is the virtual identity of the entity in control of a | ||
1102 | namespace or GNS zone. Anyone can create any number of egos. The | ||
1103 | provided NICK name automatically corresponds to a GNU Name System | ||
1104 | domain name. Thus, henceforth name resolution for any name ending in | ||
1105 | ``.NICK'' will use the NICK's zone. You should avoid using NICKs that | ||
1106 | collide with well-known DNS names. | ||
1121 | 1107 | ||
1122 | @b{Please note that the text in this subsection is outdated and needs} | 1108 | @node Deleting Egos |
1123 | @b{to be rewritten for version 0.10!} | 1109 | @subsubsection Deleting Egos |
1124 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1125 | 1110 | ||
1126 | With the @command{-C NICK} option it can also be used to | 1111 | With the @command{-D NICK} option egos can be deleted. Once the ego |
1127 | create a new pseudonym. A pseudonym is the virtual identity | 1112 | has been deleted it is impossible to add content to the corresponding |
1128 | of the entity in control of a namespace. Anyone can create | 1113 | namespace or zone. However, the existing GNS zone data is currently |
1129 | any number of pseudonyms. Note that creating a pseudonym can | 1114 | not dropped. This may change in the future. |
1130 | take a few minutes depending on the performance of the machine | ||
1131 | used. | ||
1132 | 1115 | ||
1133 | @node Deleting Pseudonyms | 1116 | Deleting the pseudonym does not make the namespace or any content in |
1134 | @subsubsection Deleting Pseudonyms | 1117 | it unavailable. |
1135 | |||
1136 | |||
1137 | @b{Please note that the text in this subsection is outdated and needs} | ||
1138 | @b{to be rewritten for version 0.10!} | ||
1139 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1140 | |||
1141 | With the @command{-D NICK} option pseudonyms can be deleted. | ||
1142 | Once the pseudonym has been deleted it is impossible to add | ||
1143 | content to the corresponding namespace. Deleting the | ||
1144 | pseudonym does not make the namespace or any content in it | ||
1145 | unavailable. | ||
1146 | |||
1147 | @node Advertising namespaces | ||
1148 | @subsubsection Advertising namespaces | ||
1149 | |||
1150 | |||
1151 | @b{Please note that the text in this subsection is outdated and needs} | ||
1152 | @b{to be rewritten for version 0.10!} | ||
1153 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1154 | |||
1155 | Each namespace is associated with meta-data that describes | ||
1156 | the namespace. This meta-data is provided by the user at | ||
1157 | the time that the namespace is advertised. Advertisements | ||
1158 | are published under keywords so that they can be found using | ||
1159 | normal keyword-searches. This way, users can learn about new | ||
1160 | namespaces without relying on out-of-band communication or directories. | ||
1161 | A suggested keyword to use for all namespaces is simply "namespace". | ||
1162 | When a keyword-search finds a namespace advertisement, | ||
1163 | it is automatically stored in a local list of known namespaces. | ||
1164 | Users can then associate a rank with the namespace to remember | ||
1165 | the quality of the content found in it. | ||
1166 | |||
1167 | @node Namespace names | ||
1168 | @subsubsection Namespace names | ||
1169 | |||
1170 | |||
1171 | @b{Please note that the text in this subsection is outdated and needs} | ||
1172 | @b{to be rewritten for version 0.10!} | ||
1173 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1174 | |||
1175 | While the namespace is uniquely identified by its ID, another way | ||
1176 | to refer to the namespace is to use the NICKNAME. | ||
1177 | The NICKNAME can be freely chosen by the creator of the namespace and | ||
1178 | hence conflicts are possible. If a GNUnet client learns about more | ||
1179 | than one namespace using the same NICKNAME, the ID is appended | ||
1180 | to the NICKNAME to get a unique identifier. | ||
1181 | |||
1182 | @node Namespace root | ||
1183 | @subsubsection Namespace root | ||
1184 | |||
1185 | |||
1186 | @b{Please note that the text in this subsection is outdated and needs} | ||
1187 | @b{to be rewritten for version 0.10!} | ||
1188 | @b{This especially concerns the terminology of Pseudonym/Ego/Identity.} | ||
1189 | |||
1190 | An item of particular interest in the namespace advertisement is | ||
1191 | the ROOT. The ROOT is the identifier of a designated entry in the | ||
1192 | namespace. The idea is that the ROOT can be used to advertise an | ||
1193 | entry point to the content of the namespace. | ||
1194 | 1118 | ||
1195 | @node File-Sharing URIs | 1119 | @node File-Sharing URIs |
1196 | @subsection File-Sharing URIs | 1120 | @subsection File-Sharing URIs |
@@ -1314,12 +1238,12 @@ To publish a file, select "File Sharing" in the menu bar just below the | |||
1314 | 1238 | ||
1315 | Afterwards, the following publishing dialog will appear: | 1239 | Afterwards, the following publishing dialog will appear: |
1316 | 1240 | ||
1317 | @c Add image here | 1241 | @image{images/gnunet-gtk-0-10-fs-publish,5in,,The gnunet-fs-gtk publishing dialog} |
1318 | 1242 | ||
1319 | In this dialog, select the "Add File" button. This will open a | 1243 | In this dialog, select the "Add File" button. This will open a |
1320 | file selection dialog: | 1244 | file selection dialog: |
1321 | 1245 | ||
1322 | @c Add image here | 1246 | @image{images/gnunet-gtk-0-10-fs-publish-select,5in,,Dialog to select the file to publish (looks may differ for other Gtk+ versions)} |
1323 | 1247 | ||
1324 | Now, you should select a file from your computer to be published on | 1248 | Now, you should select a file from your computer to be published on |
1325 | GNUnet. To see more of GNUnet's features later, you should pick a | 1249 | GNUnet. To see more of GNUnet's features later, you should pick a |
@@ -1335,12 +1259,12 @@ and potential errors that might be encountered during processing. | |||
1335 | After the progress dialog automatically disappears, your file | 1259 | After the progress dialog automatically disappears, your file |
1336 | should now appear in the publishing dialog: | 1260 | should now appear in the publishing dialog: |
1337 | 1261 | ||
1338 | @c Add image here | 1262 | @image{images/gnunet-gtk-0-10-fs-publish-with-file,5in,,Publishing dialog with file added} |
1339 | 1263 | ||
1340 | Now, select the file (by clicking on the file name) and then click | 1264 | Now, select the file (by clicking on the file name) and then click |
1341 | the "Edit" button. This will open the editing dialog: | 1265 | the "Edit" button. This will open the editing dialog: |
1342 | 1266 | ||
1343 | @c Add image here | 1267 | @image{images/gnunet-gtk-0-10-fs-publish-editing,5in,,Editing meta data of a file to be published} |
1344 | 1268 | ||
1345 | In this dialog, you can see many details about your file. In the | 1269 | In this dialog, you can see many details about your file. In the |
1346 | top left area, you can see meta data extracted about the file, | 1270 | top left area, you can see meta data extracted about the file, |
@@ -1364,9 +1288,7 @@ You should now be back at the "Publish content on GNUnet" dialog. Select | |||
1364 | "Execute" in the bottom right to close the dialog and publish your file | 1288 | "Execute" in the bottom right to close the dialog and publish your file |
1365 | on GNUnet! Afterwards, you should see the main dialog with a new area | 1289 | on GNUnet! Afterwards, you should see the main dialog with a new area |
1366 | showing the list of published files (or ongoing publishing operations | 1290 | showing the list of published files (or ongoing publishing operations |
1367 | with progress indicators): | 1291 | with progress indicators). |
1368 | |||
1369 | @c Add image here | ||
1370 | 1292 | ||
1371 | @node gtk-Searching | 1293 | @node gtk-Searching |
1372 | @subsubsection Searching | 1294 | @subsubsection Searching |
@@ -1920,33 +1842,42 @@ options: | |||
1920 | 1842 | ||
1921 | @example | 1843 | @example |
1922 | Ascension | 1844 | Ascension |
1923 | |||
1924 | Usage: | 1845 | Usage: |
1925 | ascension <domain> [-d] [-p] | 1846 | ascension <domain> [-d] [-p] [-s] [--minimum-ttl=<ttl>] \ |
1926 | ascension <domain> <port> [-d] [-p] | 1847 | [--dry-run] |
1927 | ascension <domain> -n <transferns> [-d] [-p] | 1848 | ascension <domain> <port> [-d] [-p] [-s] \ |
1928 | ascension <domain> -n <transferns> <port> [-d] [-p] | 1849 | [--minimum-ttl=<ttl>] [--dry-run] |
1850 | ascension <domain> -n <transferns> [-d] [-p] \ | ||
1851 | [-s] [--minimum-ttl=<ttl>] [--dry-run] | ||
1852 | ascension <domain> -n <transferns> <port> [-d] \ | ||
1853 | [-p] [-s] [--minimum-ttl=<ttl>] [--dry-run] | ||
1929 | ascension -p | --public | 1854 | ascension -p | --public |
1855 | ascension -d | --debug | ||
1856 | ascension -s | --standalone | ||
1930 | ascension -h | --help | 1857 | ascension -h | --help |
1931 | ascension -v | --version | 1858 | ascension -v | --version |
1932 | 1859 | ||
1933 | Options: | 1860 | Options: |
1934 | <domain> Domain to migrate | 1861 | <domain> Domain to migrate |
1935 | <port> Port for zone transfer | 1862 | <port> Port for zone transfer |
1936 | <transferns> DNS Server that does the zone transfer | 1863 | <transferns> DNS Server that does the zone transfer |
1937 | -p --public Make records public on the DHT | 1864 | --minimum-ttl=<ttl> Minimum TTL for records to migrate \ |
1938 | -d --debug Enable debugging | 1865 | [default: 3600] |
1939 | -h --help Show this screen. | 1866 | --dry-run Only try if a zone transfer is allowed |
1940 | -v --version Show version. | 1867 | -p --public Make records public on the DHT |
1868 | -s --standalone Run ascension once | ||
1869 | -d --debug Enable debugging | ||
1870 | -h --help Show this screen. | ||
1871 | -v --version Show version. | ||
1941 | @end example | 1872 | @end example |
1942 | 1873 | ||
1943 | Before you can migrate any zone though, you need to start the GNUnet peer: | 1874 | Before you can migrate any zone though, you need to start a local GNUnet peer: |
1944 | @example | 1875 | @example |
1945 | $ gnunet-arm -s | 1876 | $ gnunet-arm -s |
1946 | @end example | 1877 | @end example |
1947 | 1878 | ||
1948 | To migrate the Syrian top level domain - one of the few top level domains that | 1879 | To migrate the Syrian top level domain - one of the few top level domains that |
1949 | still supports zone transfers - into GNS use the following command: | 1880 | support zone transfers - into GNS use the following command: |
1950 | 1881 | ||
1951 | @example | 1882 | @example |
1952 | $ ascension sy. -n ns1.tld.sy. -p | 1883 | $ ascension sy. -n ns1.tld.sy. -p |
@@ -1959,33 +1890,39 @@ Once the zone is migrated, Ascension will output a message telling you, that it | |||
1959 | will refresh the zone after the time has elapsed. You can resolve the names in | 1890 | will refresh the zone after the time has elapsed. You can resolve the names in |
1960 | the zone directly using GNS or if you want to use it with your browser, check | 1891 | the zone directly using GNS or if you want to use it with your browser, check |
1961 | out the GNS manual section. @ref{Configuring the GNU Name System}. To resolve | 1892 | out the GNS manual section. @ref{Configuring the GNU Name System}. To resolve |
1962 | the records from another system you need the zone PKEY. To get the zone key, | 1893 | the records from another system you need the respective zones PKEY. To get the |
1963 | you can run the following command: | 1894 | zones public key, you can run the following command: |
1964 | 1895 | ||
1965 | @example | 1896 | @example |
1966 | $ gnunet-identity -d | grep ^sy | cut -d " " -f3 | 1897 | $ gnunet-identity -dqe sy |
1967 | @end example | 1898 | @end example |
1968 | 1899 | ||
1969 | Where "sy" is the name of the zone you want to migrate. | 1900 | Where "sy" is the name of the zone you want to migrate. |
1970 | 1901 | ||
1971 | As soon as the public flag is implemented, you can share the PKEY of the zone | 1902 | You can share the PKEY of the zone with your friends. They can then resolve |
1972 | with your friends. They can then resolve records in the zone by doing a lookup | 1903 | records in the zone by doing a lookup replacing the zone label with your PKEY: |
1973 | replacing the zone label with your PKEY: | ||
1974 | 1904 | ||
1975 | @example | 1905 | @example |
1976 | $ gnunet-gns -t SOA -u "@.$PKEY" | 1906 | $ gnunet-gns -t SOA -u "$PKEY" |
1977 | @end example | 1907 | @end example |
1978 | 1908 | ||
1979 | The program will continue to run as a daemon and update once the refresh time | 1909 | The program will continue to run as a daemon and update once the refresh time |
1980 | specified in the zones SOA record has elapsed. | 1910 | specified in the zones SOA record has elapsed. |
1981 | 1911 | ||
1982 | The next step would be to add the PKEY record as a DNScurve style NS record | 1912 | DNSCurve style records are supported in the latest release and they are added |
1983 | into the existing DNS zone to enable clients to detect that this zone has | 1913 | as a PKEY record to be referred to the respective GNS public key. Key |
1984 | already been migrated to GNS and to also have a means of distributing the PKEY | 1914 | distribution is still a problem but provided someone else has a public key |
1985 | seamlessly. | 1915 | under a given label it can be looked up. |
1916 | |||
1917 | There is an unofficial Debian package called python3-ascension that adds a | ||
1918 | system user ascension and runs a GNUnet peer in the background. | ||
1986 | 1919 | ||
1987 | At this point you might want to write for example a systemd unit file to start | 1920 | Ascension-bind is also an unofficial Debian package that on installation checks |
1988 | and enable the service, so that your zone is migrated automatically. | 1921 | for running DNS zones and whether or not they are transferable using DNS zone |
1922 | transfer (AXFR). It asks the administrator which zones to migrate into GNS and | ||
1923 | installs a systemd unit file to keep the zone up to date. If you want to | ||
1924 | migrate different zones you might want to check the unit file from the package | ||
1925 | as a guide. | ||
1989 | 1926 | ||
1990 | @node reclaimID Identity Provider | 1927 | @node reclaimID Identity Provider |
1991 | @section reclaimID Identity Provider | 1928 | @section reclaimID Identity Provider |
diff --git a/doc/handbook/images/ascension_interaction.png b/doc/handbook/images/ascension_interaction.png new file mode 100644 index 000000000..84e2e9c0f --- /dev/null +++ b/doc/handbook/images/ascension_interaction.png | |||
Binary files differ | |||
diff --git a/doc/handbook/images/ascension_ssd.png b/doc/handbook/images/ascension_ssd.png new file mode 100644 index 000000000..3b142ab31 --- /dev/null +++ b/doc/handbook/images/ascension_ssd.png | |||
Binary files differ | |||