src/vpn/README

   1 For Users
   2 =========
   3
   4 To use the gnunet-vpn you have to have at least added "vpn" to the
   5 "DEFAULTSERVICES" option of arm.
   6
   7 If you start gnunet now, you will get a new network-interface called gnunet-vpn
   8 (you can rename it by adding the option "IFNAME" to a section called "vpn" in
   9 your ~/.gnunet/gnunet.conf) with the IP addresses 1234::1/32 and 10.11.10.1/16
  10 (Theese can be changed with "IPV6ADDR", "IPV6PREFIX", "IPV4ADDR" and
  11 "IPV4MASK"). You "normal" internet-usage should not be impaired (check that!)
  12 but you should be able to point your web browser to something like
  13 http://gnunet.gnunet/ and get the gnunet webpage! That's it, you are set to use
  14 gnunet to access legacy services!
  15
  16
  17 Offering Services
  18 -----------------
  19
  20 If you want to offer services such as your webpage via gnunet you have to have
  21 add "exit" to the DEFAULTSERVICES and an entry like the following to
  22 ~/.gnunet/gnunet.conf:
  23
  24 #v+
  25 [example.gnunet.]
  26 ALTERNATIVE_NAMES = www
  27 TCP_REDIRECTS = 80:example.com:80 22:localhost4:22
  28 UDP_REDIRECTS = 69:tftp.example.com:69
  29 TTL = 3600000
  30 #v-
  31
  32 This entry creates the hostnames example.gnunet and www.example.gnunet and
  33 send traffic to port 80 of this virtual host to the real host, sends traffic
  34 on port 22 to your local machine (the machine running GnuNET) and traffic on
  35 port 69 to tftp.example.com.
  36
  37 Note: The exit-daemon will also create a virtual network-interface with its
  38 own set of IPv4 and IPv6 addresses. These addresses can be accessed by
  39 localhost4 and localhost6 in the domain-configuration.
  40
  41 Now point you computer (or any other computer in the gnunet) to
  42 http://example.gnunet/ and you will get your website.
  43
  44 Offering Internet Access
  45 ------------------------
  46
  47 Add "PROVIDE_EXIT = YES" to the section "dns" of your configuration if you
  48 want to allow other peers to use your computer to resolve DNS-Queries.
  49
  50 If you want to allow other users to send traffic over your
  51 internet-connection, add the options "ENABLE_UDP = YES" and "ENABLE_TCP = YES"
  52 to the section "exit" of the configuration.
  53
  54 Be aware, that this enables people to use your internet connection for
  55 nefarious things which might make you liable!
  56
  57 For Developers
  58 ==============
  59
  60 The gnunet-vpn is a combination of three programs:
  61
  62 - gnunet-daemon-vpn opens a tun-interface, configures it and controls the
  63   network
  64 - gnunet-service-dns configures a hijack for outgoing DNS-requests, so that
  65   they get sent to gnunet-daemon-vpn, which sends them on to
  66   gnunet-service-dns which sends them on, either to their original destination
  67   or to gnunet. It also publishes names from dns.conf to the dht.
  68 - gnunet-daemon-exit takes connections from the gnunet and sends them on to
  69   the legacy internet.
  70
  71 The gnunet-service-dns decides where to send the query with an easy check:
  72
  73 - it is a query for something.gnunet: it gets sent to the dht
  74 - it is a query sent to the configured VIRT_DNS: it gets sent on to some other
  75   gnunet-service-dns somewhere in the gnunet (anyone having configured
  76   DNS_EXIT)
  77 - else: it gets sent to the original destination
  78
  79 These programs exchange whole TCP- or UDP-packets, they only strip of the
  80 IP-header. This way gnunet achieves translation between IPv6-services and
  81 IPv4-clients and vice versa!
  82
  83 The gnunet-daemon-vpn receives packets on the tun-interface and routes them:
  84 - everything to port 53 (dns) will be sent to the gnunet-service-dns
  85     replies to these queries will be sent from the gnunet-service-dns back to
  86     gnunet-daemon-vpn which will then fill in a newly generated IP-Adress, save
  87     it and a descriptor of what kind of address it is (for a .gnunet-service or for
  88     a "real" service) to a hashmap and send the reply back through the interface
  89 - for every non-dns packet the hashmap is queried if the destination-adress is known
  90   if it is, the packet gets sent to either the peer advertising the service or
  91   (via the mesh by-type mechanism) to any peer that allows exit-functionality
  92 - everything else is dropped
  93
  94 Hijacking the DNS-Traffic
  95 -------------------------
  96
  97 For access to services provided via GNUNet we need to make sure that we can
  98 inspect every DNS-Query made from the local machine. We briefly considered
  99 replacing the configured nameserver (i.e. saving and then changing
 100 \texttt{/etc/resolv.conf}) but rejected it out of practical considerations: A
 101 plethora of tools change this file, \textit{resolvconf} and the
 102 \textit{Network-Manager} being just the most prominent of them. We would have
 103 to monitor this file for changes. This scheme would also run into problems if
 104 some application would use its own nameserver without referring to
 105 \texttt{/etc/resolv.conf}.
 106
 107 A solution based on \textit{destination NAT} was also rejected: Since the
 108 captured packets would have no record of their original destination our
 109 application would not know where to send the query if it should not be
 110 answered internally.
 111
 112 We finally settled on a solution using \textit{policy based routing}. We would
 113 \textit{MARK} every outgoing DNS-packet if it was not sent by our application.
 114 Using a second routing table in the linux kernel these marked packets would be
 115 routed through our virtual network interface and could thus be captured
 116 unchanged.
 117
 118 Our application then reads the query and decides how to handle it: A query to
 119 an address ending in \texttt{.gnunet} would be resolved internally using a
 120 DHT. A reverse query for an address of the configured virtual network could be
 121 answered with records kept about previous forward queries. A query sent
 122 originally to our virtual address is resolved using the nearest peer that
 123 provides name resolution. Every other query will be sent to the original
 124 recipient. The answer to the query will always be sent back through the
 125 virtual interface with the original nameserver as source address.
 126
 127 iptables -t mangle -I OUTPUT 1 -p udp --sport $LOCALPORT --dport 53 -j ACCEPT
 128 iptables -t mangle -I OUTPUT 2 -p udp --dport 53 -j MARK --set-mark 3
 129 ip rule add fwmark 3 table2
 130 ip route add default via $VIRTUALDNS table2
 131
 132 Line 1 makes sure that all packets coming from a port our application opened
 133 beforehand (\texttt{\$LOCALPORT}) will be routed normally. Line 2 marks every
 134 other packet to a DNS-Server with mark $3$ (chosen arbitrarily). The third
 135 line adds a routing policy based on this mark $3$ via the routing table
 136 "table2" which is populated with just the default route.
 137
 138
 139 Performance Measurements
 140 ========================
 141
 142 These tests were done between hosts (i7 with 2.67GHz and Core 2 with 2GHz)
 143 connected by a switched Gigabit Ethernet.
 144
 145 scp direct (100MiB file):                                 33.3MiB/s (as shown by scp)
 146 udp echo direct (6 Bytes of data):                        0.000333 (measured by tcpdump)
 147
 148 scp over gnunet (100MiB file, stopped after 5 minutes):   20KiB/s (as shown by scp)
 149 udp echo over gnunet (6 Bytes of data):                   0.078410s (measured by tcpdump)