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 vi 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 TODO: routing
  55
  56 Be aware, that this enables people to use your internet connection for
  57 nefarious things which might make you liable!
  58
  59 For Developers
  60 ==============
  61
  62 The gnunet-vpn is a combination of three programs:
  63
  64 - gnunet-daemon-vpn opens a tap-interface, configures it and controls the
  65   network
  66 - gnunet-service-dns configures a hijack for outgoing DNS-requests, so that
  67   they get sent to gnunet-daemon-vpn, which sends them on to
  68   gnunet-service-dns which sends them on, either to their original destination
  69   or to gnunet. It also publishes names from dns.conf to the dht.
  70 - gnunet-daemon-exit takes connections from the gnunet and sends them on to
  71   the legacy internet.
  72
  73 The gnunet-service-dns decides where to send the query with an easy check:
  74
  75 - it is a query for something.gnunet: it gets sent to the dht
  76 - it is a query sent to the configured VIRT_DNS: it gets sent on to some other
  77   gnunet-service-dns somewhere in the gnunet (anyone having configured
  78   DNS_EXIT)
  79 - else: it gets sent to the original destination
  80
  81 These programs exchange whole TCP- or UDP-packets, they only strip of the
  82 IP-header. This way gnunet achieves translation between IPv6-services and
  83 IPv4-clients and vice versa!
  84
  85
  86 Hijacking the DNS-Traffic
  87 -------------------------
  88
  89 For access to services provided via GNUNet we need to make sure that we can
  90 inspect every DNS-Query made from the local machine. We briefly considered
  91 replacing the configured nameserver (i.e. saving and then changing
  92 \texttt{/etc/resolv.conf}) but rejected it out of practical considerations: A
  93 plethora of tools change this file, \textit{resolvconf} and the
  94 \textit{Network-Manager} being just the most prominent of them. We would have
  95 to monitor this file for changes. This scheme would also run into problems if
  96 some application would use its own nameserver without referring to
  97 \texttt{/etc/resolv.conf}.
  98
  99 A solution based on \textit{destination NAT} was also rejected: Since the
 100 captured packets would have no record of their original destination our
 101 application would not know where to send the query if it should not be
 102 answered internally.
 103
 104 We finally settled on a solution using \textit{policy based routing}. We would
 105 \textit{MARK} every outgoing DNS-packet if it was not sent by our application.
 106 Using a second routing table in the linux kernel these marked packets would be
 107 routed through our virtual network interface and could thus be captured
 108 unchanged.
 109
 110 Our application then reads the query and decides how to handle it: A query to
 111 an address ending in \texttt{.gnunet} would be resolved internally using a
 112 DHT. A reverse query for an address of the configured virtual network could be
 113 answered with records kept about previous forward queries. A query sent
 114 originally to our virtual address is resolved using the nearest peer that
 115 provides name resolution. Every other query will be sent to the original
 116 recipient. The answer to the query will always be sent back through the
 117 virtual interface with the original nameserver as source address.
 118
 119 iptables -t mangle -I OUTPUT 1 -p udp --sport $LOCALPORT --dport 53 -j ACCEPT
 120 iptables -t mangle -I OUTPUT 2 -p udp --dport 53 -j MARK --set-mark 3
 121 ip rule add fwmark 3 table2
 122 ip route add default via $VIRTUALDNS table2
 123
 124 Line 1 makes sure that all packets coming from a port our application opened
 125 beforehand (\texttt{\$LOCALPORT}) will be routed normally. Line 2 marks every
 126 other packet to a DNS-Server with mark $3$ (chosen arbitrarily). The third
 127 line adds a routing policy based on this mark $3$ via the routing table
 128 "table2" which is populated with just the default route.