Update to the latest upstream version.

1 files changed, 75 insertions, 20 deletions

diff --git a/README b/README
index cd36aea..c7c9fae 100644
--- a/README
+++ b/README
@@ -2,11 +2,16 @@ NAME
     nat-traverse - Use of UDP to traverse NAT gateways
 
 SYNOPSIS
+    To create a simple text-only tunnel, use the commands
+
       user@left  $ nat-traverse 40000:natgw-of-right:40001
       user@right $ nat-traverse 40001:natgw-of-left:40000
 
+    where 40000 is an unused UDP port on "left" and 40001 is an unused port
+    on "right". See "EXAMPLES" for more.
+
 VERSION
-    This document describes nat-traverse v0.4.
+    This document describes nat-traverse v0.5.
 
 DESCRIPTION
     nat-traverse establishes connections between nodes which are behind NAT
@@ -18,6 +23,10 @@ DESCRIPTION
 
     See "TECHNIQUE" for how this is achieved.
 
+    Limitation: nat-traverse does not work with gateways which change the
+    port numbers. This is a fundamental problem of nat-traverse's design, as
+    the changed port numbers are (in general) not predictable.
+
 OPTIONS
     "*local_port*:*peer*:*remote_port*" (required)
         Sets the local port to use and the remote address to connect to.
@@ -59,7 +68,7 @@ OPTIONS
     "--version", "--help"
 
 TECHNIQUE
-    nat-traverse establishes connections between hosts behind NAT gateways,
+    nat-traverse establishes connections between hosts behind NAT gateways
     without need for reconfiguration of the involved NAT gateways.
 
     1.  Firstly, nat-traverse on host "left" sends garbage UDP packets to
@@ -78,8 +87,8 @@ TECHNIQUE
 
     4.  Finally, both hosts send an acknowledgement packet to signal
         readiness. When these packets are received, the connection is
-        established and nat-traverse can either relay STDIN to the socket or
-        execute a program.
+        established and nat-traverse can either relay STDIN/STDOUT to the
+        socket or execute a program.
 
 EXAMPLES
   Setup of a small VPN with PPP
@@ -101,8 +110,9 @@ EXAMPLES
     tunnel uses UDP! Furthermore, you could even add IPv6 addresses to
     "ppp0" by running "ip -6 addr add..."!
 
-    Note though that although this VPN *is* a private network, it is *not*
-    secured in any way. You may want to use SSH to encrypt the connection.
+    Note though that although this VPN *is* arguably a private network, it
+    is *not* secured in any way. You may want to use SSH to encrypt the
+    connection.
 
   Port Forwarding with netcat
     You can use "netcat" to forward one of your local UDP or TCP ports to an
@@ -122,28 +132,73 @@ EXAMPLES
       # Will connect to right's SSH daemon!
 
     But do note that you lose the reliability of TCP in this example, as the
-    actual data is transported via UDP. If you want reliable streams, use
-    PPP on top of nat-traverse, as described above.
+    actual data is transported via UDP; so this is only a toy example. If
+    you want reliable streams, use PPP on top of nat-traverse, as described
+    above.
+
+  Setup of a VPN with OpenVPN
+    You can use <OpenVPN> over nat-traverse if you want to have a *secure*
+    VPN.
+
+    Using OpenVPN over nat-traverse requires only one change to OpenVPN's
+    configuration file, presuming that you don't want to use OpenVPN's
+    multi-client mode: You have to adjust the "code" and "lport" options
+    accordingly, for example:
+
+      # Options to add to left's and right's OpenVPN config:
+      port  60001
+      lport 60001
+
+      # Command to execute on left resp. right:
+      root@left  # until \
+                     nat-traverse --quit-after-connect 60001:right:60001 \
+                   do \
+                     sleep 5 \
+                   done; \
+                   openvpn [...]
+      root@right # until \
+                     nat-traverse --quit-after-connect 60001:left:60001 \
+                   do \
+                     sleep 5 \
+                   done; \
+                   openvpn [...]<!--
+
+    The "until" loop ensures that OpenVPN will not be started before
+    nat-traverse was able to establish the connection. Michael Kugele
+    ("michael (at) kugele.net") also reported a way to still be able to use
+    OpenVPN's multi-client mode with nat-traverse: As all instances of
+    nat-traverse have to use unique ports (because a connection is
+    identified by the source/destination port combination), you've to use
+    redirection rules to redirect the ports used by nat-traverse to the port
+    the OpenVPN daemon listens on:
+
+      iptables -t nat -A PREROUTING -p udp \
+        --dport $LPORT -j DNAT --to $HOST:$PORT
+      iptables -t nat -A PREROUTING -p udp \
+        --dport $PORT -j REDIRECT --to-port $LPORT
+
+    $LPORT specifies the source port nat-traverse uses on the server side,
+    and "$HOST:$PORT" is the address of the OpenVPN server.)
 
 LIMITATIONS
     Only IPv4 is supported, nat-traverse won't work with IPv6 addresses.
-    Even though it would be relatively trivial to add IPv6 support, I
-    refrained from doing that, as there's no need to use NAT with IPv6 (the
-    address space IPv6 provides is sufficient).
+    Drop me a note if you do need IPv6 support.
 
-    If you do need IPv6 support, drop me a note and I'll patch nat-traverse.
+    nat-traverse does not work with gateways which change the port numbers.
+    This is a fundamental problem of nat-traverse's design, as the changed
+    port numbers are (in general) not predictable.
 
 SEE ALSO
-    RFC 1631 at http://www.ietf.org/rfc/rfc1631.txt
+    <RFC 1631 at http://www.ietf.org/rfc/rfc1631.txt>
         The IP Network Address Translator (NAT). K. Egevang, P. Francis. May
         1994. (Obsoleted by RFC3022) (Status: INFORMATIONAL)
 
-    RFC 3022 at http://www.ietf.org/rfc/rfc3022.txt
+    <RFC 3022 at http://www.ietf.org/rfc/rfc3022.txt>
         Traditional IP Network Address Translator (Traditional NAT). P.
         Srisuresh, K. Egevang. January 2001. (Obsoletes RFC1631) (Status:
         INFORMATIONAL)
 
-    RFC 1661 at http://www.ietf.org/rfc/rfc1661.txt
+    <RFC 1661 at http://www.ietf.org/rfc/rfc1661.txt>
         The Point-to-Point Protocol (PPP). W. Simpson, Ed.. July 1994.
         (Obsoletes RFC1548) (Updated by RFC2153) (Also STD0051) (Status:
         STANDARD)
@@ -152,8 +207,8 @@ SEE ALSO
         Website of Paul's PPP Package (open source implementation of the
         Point-to-Point Protocol (PPP) on Linux and Solaris)
 
-    German talk about nat-traverse at
-    http://linide.sourceforge.net/nat-traverse/nat-traverse-talk.pdf
+    <German talk about nat-traverse at
+    http://linide.sourceforge.net/nat-traverse/nat-traverse-talk.pdf>
         Dieser Vortrag zeigt, wie man einen Tunnel zwischen zwei Computern,
         die beide hinter NAT-Gateways sitzen, hinbekommt. Dazu wird ein
         neues Programm vorgestellt, welches sowohl einfache Tastendrücke an
@@ -162,10 +217,10 @@ SEE ALSO
         VPN schnell aufgebaut.
 
 AUTHOR
-    Copyright (C) 2005 Ingo Blechschmidt, <iblech@web.de>.
+    Copyright (C) 2005, 2012 Ingo Blechschmidt, <iblech@web.de>.
 
-    You may want to visit nat-traverse's Freshmeat project page,
-    <http://freshmeat.net/projects/nat-traverse/>, for new releases.
+    You may want to visit nat-traverse's Freecode project page,
+    <http://freecode.com/projects/nat-traverse/>.
 
 LICENSE
     This program is free software; you can redistribute it and/or modify it