documentation

1 files changed, 84 insertions, 31 deletions

diff --git a/src/vpn/README b/src/vpn/README
index 9cc5264c5..9329e665b 100644
--- a/src/vpn/README
+++ b/src/vpn/README
@@ -1,49 +1,57 @@
 For Users
 =========
 
-To use the gnunet-vpn you have to have at least the following configuration in
-your ~/.gnunet/gnunet.conf:
+To use the gnunet-vpn you have to have at least added "vpn" to the
+"DEFAULTSERVICES" option of arm.
+
+If you start gnunet now, you will get a new network-interface called gnunet-vpn
+(you can rename it by adding the option "IFNAME" to a section called "vpn" in
+your ~/.gnunet/gnunet.conf) with the IP addresses 1234::1/32 and 10.11.10.1/16
+(Theese can be changed with "IPV6ADDR", "IPV6PREFIX", "IPV4ADDR" and
+"IPV4MASK"). You "normal" internet-usage should not be impaired (check that!)
+but you should be able to point your web browser to something like
+http://gnunet.gnunet/ and get the gnunet webpage! That's it, you are set to use
+gnunet to access legacy services!
 
-#v+
-TODO
-#v-
 
-If you start gnunet now, you will get a new network-interface called
-gnunet-vpn (or however you named it) with the IP addresses you configured. You
-"normal" internet-usage should not be impaired (check that!) but you should be
-able to point your web browser to something like http://gnunet.gnunet/ and the
-the gnunet webpage! That's it, you are set to use gnunet to access legacy
-services!
+Offering Services
+-----------------
 
 If you want to offer services such as your webpage vi gnunet you have to have
-a file ~/.gnunet/dns.conf with the following content:
+add "exit" to the DEFAULTSERVICES and an entry like the following to
+~/.gnunet/gnunet.conf:
 
 #v+
-TODO
+[example.gnunet.]
+ALTERNATIVE_NAMES = www
+TCP_REDIRECTS = 80:example.com:80 22:localhost4:22
+UDP_REDIRECTS = 69:tftp.example.com:69
+TTL = 3600000
 #v-
 
-Also you will have to configure and start the exit-daemon:
+This entry creates the hostnames example.gnunet and www.example.gnunet and
+send traffic to port 80 of this virtual host to the real host, sends traffic
+on port 22 to your local machine (the machine running GnuNET) and traffic on
+port 69 to tftp.example.com.
 
-#v+
-TODO
-#v-
+Note: The exit-daemon will also create a virtual network-interface with its
+own set of IPv4 and IPv6 addresses. These addresses can be accessed by
+localhost4 and localhost6 in the domain-configuration.
 
 Now point you computer (or any other computer in the gnunet) to
-http://yourwebsite.gnunet/ and you will get your website.
+http://example.gnunet/ and you will get your website.
 
-Add the following options if you want to resolve DNS-queries for other users
-of gnunet:
+Offering Internet Access
+------------------------
 
-#v+
-TODO
-#v-
+Add "PROVIDE_EXIT = YES" to the section "dns" of your configuration if you
+want to allow other peers to use your computer to resolve DNS-Queries.
 
-Add the following options if you want to provide access to your internet
-connection to other users of gnunet:
+If you want to allow other users to send traffic over your
+internet-connection, add the options "ENABLE_UDP = YES" and "ENABLE_TCP = YES"
+to the section "exit" of the configuration.
 
-#v+
-TODO
-#v-
+TODO: routing
 
 Be aware, that this enables people to use your internet connection for
 nefarious things which might make you liable!
@@ -59,17 +67,62 @@ The gnunet-vpn is a combination of three programs:
   they get sent to gnunet-daemon-vpn, which sends them on to
   gnunet-service-dns which sends them on, either to their original destination
   or to gnunet. It also publishes names from dns.conf to the dht.
-- gnunet-daemon-exit takes gets connections from the gnunet and sends them on
-  to the legacy internet.
+- gnunet-daemon-exit takes connections from the gnunet and sends them on to
+  the legacy internet.
 
 The gnunet-service-dns decides where to send the query with an easy check:
 
 - it is a query for something.gnunet: it gets sent to the dht
 - it is a query sent to the configured VIRT_DNS: it gets sent on to some other
   gnunet-service-dns somewhere in the gnunet (anyone having configured
-  DNS_EXIT TODO)
+  DNS_EXIT)
 - else: it gets sent to the original destination
 
 These programs exchange whole TCP- or UDP-packets, they only strip of the
 IP-header. This way gnunet achieves translation between IPv6-services and
 IPv4-clients and vice versa!
+
+
+Hijacking the DNS-Traffic
+-------------------------
+
+For access to services provided via GNUNet we need to make sure that we can
+inspect every DNS-Query made from the local machine. We briefly considered
+replacing the configured nameserver (i.e. saving and then changing
+\texttt{/etc/resolv.conf}) but rejected it out of practical considerations: A
+plethora of tools change this file, \textit{resolvconf} and the
+\textit{Network-Manager} being just the most prominent of them. We would have
+to monitor this file for changes. This scheme would also run into problems if
+some application would use its own nameserver without referring to
+\texttt{/etc/resolv.conf}.
+
+A solution based on \textit{destination NAT} was also rejected: Since the
+captured packets would have no record of their original destination our
+application would not know where to send the query if it should not be
+answered internally.
+
+We finally settled on a solution using \textit{policy based routing}. We would
+\textit{MARK} every outgoing DNS-packet if it was not sent by our application.
+Using a second routing table in the linux kernel these marked packets would be
+routed through our virtual network interface and could thus be captured
+unchanged.
+
+Our application then reads the query and decides how to handle it: A query to
+an address ending in \texttt{.gnunet} would be resolved internally using a
+DHT. A reverse query for an address of the configured virtual network could be
+answered with records kept about previous forward queries. A query sent
+originally to our virtual address is resolved using the nearest peer that
+provides name resolution. Every other query will be sent to the original
+recipient. The answer to the query will always be sent back through the
+virtual interface with the original nameserver as source address.
+
+iptables -t mangle -I OUTPUT 1 -p udp --sport $LOCALPORT --dport 53 -j ACCEPT
+iptables -t mangle -I OUTPUT 2 -p udp --dport 53 -j MARK --set-mark 3
+ip rule add fwmark 3 table2
+ip route add default via $VIRTUALDNS table2
+
+Line 1 makes sure that all packets coming from a port our application opened
+beforehand (\texttt{\$LOCALPORT}) will be routed normally. Line 2 marks every
+other packet to a DNS-Server with mark $3$ (chosen arbitrarily). The third
+line adds a routing policy based on this mark $3$ via the routing table
+"table2" which is populated with just the default route.