Update to the latest upstream version.

5 files changed, 286 insertions, 110 deletions

diff --git a/ChangeLog b/ChangeLog
index 361d51d..f5be154 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,15 +1,20 @@
 nat-traverse -- Use of UDP to traverse NAT gateways
 
+2012-02-12
+    * v0.5: Adjusted the length of garbage and acknowledgements packets to
+            make nat-traverse work under Windows and Android.
+
 2005-08-23
-    * v0.4: New option --quit-after-connect quits nat-traverse after the tunnel
-	    has been established successfully.
+    * v0.4: New option --quit-after-connect to quit nat-traverse after
+	    establishing the tunnel.
 
 2005-06-29
     * v0.3: Made nat-traverse work with Perl 5.6.1 (previously Perl 5.8.0 was
-            required)
+            required).
 
 2005-06-26
-    * v0.2: Fixed a rare race condition
+    * v0.2: Fixed a race condition which caused the two nat-traverse instances
+            to sometimes miss each other.
 
 2005-06-25
-    * v0.1: Initial release
+    * v0.1: Initial release.
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
diff --git a/debian/changelog b/debian/changelog
index ca08a3d..c3bb0fd 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+nat-traverse (0.5-1) UNRELEASED; urgency=low
+
+  * New upstream release
+
+ -- Andrew O. Shadura <bugzilla@tut.by>  Wed, 15 Aug 2012 22:24:18 +0200
+
 nat-traverse (0.4-1) unstable; urgency=low
 
   * New upstream release.
diff --git a/nat-traverse b/nat-traverse
index ca7b54c..e887a8f 100755
--- a/nat-traverse
+++ b/nat-traverse
@@ -1,6 +1,6 @@
 #!/usr/bin/perl
 # nat-traverse -- Use of UDP to traverse NAT gateways
-# Copyright (C) 2005 Ingo Blechschmidt <iblech@web.de>
+# Copyright (C) 2005, 2012 Ingo Blechschmidt <iblech@web.de>
 #
 # This program is free software; you can redistribute it and/or
 # modify it under the terms of the GNU General Public License
@@ -14,7 +14,7 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
-# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
 # USA.
 
 use warnings;
@@ -27,7 +27,7 @@ use Getopt::Long;
 
 # More elegant use constant {...} not available in Perl 5.6.x.
 use constant GARBAGE_MAGIC => "nat-traverse-garbage";
-use constant ACK_MAGIC     => "nat-traverse-ack";
+use constant ACK_MAGIC     => "nat-traverse-ackacka";
 use constant PACKET_SIZE   => 8 * 1024;
 
 sub debug($);
@@ -38,7 +38,7 @@ GetOptions(
   "timeout=i"          => \(my $TIMEOUT = 10),
   "quit-after-connect" => \my $QUIT_AFTER_CONNECT,
   "cmd=s"              => \my $CMD,
-  "version"            => sub { print "nat-traverse 0.4\n" and exit },
+  "version"            => sub { print "nat-traverse 0.5\n"; exit },
   "help"               => \&usage,
 ) or usage();
 usage() unless @ARGV == 1;
@@ -60,7 +60,7 @@ sub sockgen {
   return $sock;
 }
 
-# Helper sub to wait for a given char.
+# Helper sub to wait for a given string.
 sub waitfor {
   my ($sock, $match) = @_;
 
@@ -115,7 +115,7 @@ if(defined $CMD) {
   die "Couldn't fork: $!\n" unless defined $pid;
 
   if($pid) {
-    # Parent -- read chars from STDIN and send them to the socket.
+    # Parent -- read from STDIN and to the socket.
     my $buf;
     while(1) {
       my $ret = sysread STDIN, $buf, PACKET_SIZE;
@@ -131,7 +131,7 @@ if(defined $CMD) {
 
   } else {
     # Child -- print what's "in the socket".
-    print $_ while
+    print($_) or die "Couldn't write to STDOUT: $!\n" while
       defined(sysread $sock, $_, PACKET_SIZE) or
         die "Couldn't read from socket: $!\n";
   }
@@ -155,7 +155,7 @@ if(defined $CMD) {
 
 # Display usage info.
 sub usage { print STDERR <<'USAGE'; exit }
-nat-traverse v0.4 -- Use of UDP to traverse NAT gateways
+nat-traverse v0.5 -- Use of UDP to traverse NAT gateways
 
 Usage:
   user@left  $ nat-traverse [options] port1:natgw-of-right:port2
@@ -191,12 +191,17 @@ nat-traverse - Use of UDP to traverse NAT gateways
 
 =head1 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 C<40000> is an unused UDP port on C<left> and C<40001> is an unused port on
+C<right>. See L</EXAMPLES> for more.
+
 =head1 VERSION
 
-This document describes nat-traverse v0.4.
+This document describes nat-traverse v0.5.
 
 =head1 DESCRIPTION
 
@@ -209,6 +214,10 @@ either. I<nat-traverse works out-of-the-box.>
 
 See L</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.
+
 =head1 OPTIONS
 
 =over
@@ -257,7 +266,7 @@ nat-traverse -- thus OpenVPN would be able to cross NAT gateways.
 
 =head1 TECHNIQUE
 
-nat-traverse establishes connections between hosts behind NAT gateways, without need
+nat-traverse establishes connections between hosts behind NAT gateways without need
 for reconfiguration of the involved NAT gateways.
 
 =over
@@ -283,7 +292,7 @@ are replies to the packets sent in step 2.
 
 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.
+either relay STDIN/STDOUT to the socket or execute a program.
 
 =back
 
@@ -309,7 +318,7 @@ establish reliable TCP connections over the tunnel, even though the tunnel uses
 UDP!  Furthermore, you could even add IPv6 addresses to C<ppp0> by running C<ip
 -6 addr add...>!
 
-Note though that although this VPN I<is> a private network, it is I<not>
+Note though that although this VPN I<is> arguably a private network, it is I<not>
 secured in any way. You may want to use SSH to encrypt the connection.
 
 =head2 Port Forwarding with netcat
@@ -331,17 +340,62 @@ C<22>):
   # 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.
+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.
+
+=head2 Setup of a VPN with OpenVPN
+
+You can use L<OpenVPN|http://openvpn.net/> over nat-traverse if you want to
+have a I<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 C<code> and C<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 C<until> loop ensures that OpenVPN will not be started before
+nat-traverse was able to establish the connection. Michael Kugele
+(C<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
+
+C<$LPORT> specifies the source port nat-traverse uses on the server
+side, and C<$HOST:$PORT> is the address of the OpenVPN server.)
 
 =head1 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).
+Only IPv4 is supported, nat-traverse won't work with IPv6 addresses. 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.
 
 =head1 SEE ALSO
 
@@ -383,10 +437,10 @@ starten kann. Damit ist ein einfaches VPN schnell aufgebaut.
 
 =head1 AUTHOR
 
-Copyright (C) 2005 Ingo Blechschmidt, E<lt>iblech@web.deE<gt>.
+Copyright (C) 2005, 2012 Ingo Blechschmidt, E<lt>iblech@web.deE<gt>.
 
-You may want to visit nat-traverse's Freshmeat project page,
-L<http://freshmeat.net/projects/nat-traverse/>, for new releases.
+You may want to visit nat-traverse's Freecode project page,
+L<http://freecode.com/projects/nat-traverse/>.
 
 =head1 LICENSE
 
diff --git a/nat-traverse.1 b/nat-traverse.1
index 6847116..2e5bfa0 100644
--- a/nat-traverse.1
+++ b/nat-traverse.1
@@ -1,15 +1,7 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.07)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .if n .sp
@@ -25,11 +17,11 @@
 ..
 .\" Set up some character translations and predefined strings.  \*(-- will
 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote.  | will give a
-.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
-.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
-.\" expand to `' in nroff, nothing in troff, for use with C<>.
-.tr \(*W-|\(bv\*(Tr
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 .ie n \{\
 .    ds -- \(*W-
@@ -48,22 +40,25 @@
 .    ds R" ''
 'br\}
 .\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
 .\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
 .    de IX
 .    tm Index:\\$1\t\\n%\t"\\$2"
 ..
 .    nr % 0
 .    rr F
 .\}
-.\"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.el \{\
+.    de IX
+..
+.\}
 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
@@ -129,18 +124,27 @@
 .\" ========================================================================
 .\"
 .IX Title "NAT-TRAVERSE 1"
-.TH NAT-TRAVERSE 1 "2005-08-23" "perl v5.8.7" "User Contributed Perl Documentation"
+.TH NAT-TRAVERSE 1 "2012-02-12" "perl v5.10.0" "User Contributed Perl Documentation"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
 .SH "NAME"
 nat\-traverse \- Use of UDP to traverse NAT gateways
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
+To create a simple text-only tunnel, use the commands
+.PP
 .Vb 2
-\&  user@left  $ nat-traverse 40000:natgw-of-right:40001
-\&  user@right $ nat-traverse 40001:natgw-of-left:40000
+\&  user@left  $ nat\-traverse 40000:natgw\-of\-right:40001
+\&  user@right $ nat\-traverse 40001:natgw\-of\-left:40000
 .Ve
+.PP
+where \f(CW40000\fR is an unused \s-1UDP\s0 port on \f(CW\*(C`left\*(C'\fR and \f(CW40001\fR is an unused port on
+\&\f(CW\*(C`right\*(C'\fR. See \*(L"\s-1EXAMPLES\s0\*(R" for more.
 .SH "VERSION"
 .IX Header "VERSION"
-This document describes nat-traverse v0.4.
+This document describes nat-traverse v0.5.
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 nat-traverse establishes connections between nodes which are behind \s-1NAT\s0
@@ -148,9 +152,13 @@ gateways, i.e. hosts which do \fInot\fR have public \s-1IP\s0 addresses. Additio
 you can setup a small \s-1VPN\s0 by using pppd on top of nat-traverse (see
 \&\*(L"\s-1EXAMPLES\s0\*(R").  nat-traverse does \fInot\fR need an external server on the
 Internet, and it isn't necessary to reconfigure the involved \s-1NAT\s0 gateways,
-either. \fInat-traverse works out\-of\-the\-box.\fR
+either. \fInat-traverse works out-of-the-box.\fR
 .PP
 See \*(L"\s-1TECHNIQUE\s0\*(R" for how this is achieved.
+.PP
+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.
 .SH "OPTIONS"
 .IX Header "OPTIONS"
 .ie n .IP """\f(CIlocal_port\f(CW:\f(CIpeer\f(CW:\f(CIremote_port\f(CW"" (required)" 4
@@ -191,12 +199,12 @@ establish the tunnel.
 \&\f(CW\*(C`\-\-quit\-after\-connect\*(C'\fR is useful if you want another program to use the
 tunnel. For example, you could configure OpenVPN to use the the same ports as
 nat-traverse \*(-- thus OpenVPN would be able to cross \s-1NAT\s0 gateways.
-.ie n .IP """\-\-version""\fR, \f(CW""\-\-help""" 4
+.ie n .IP """\-\-version"", ""\-\-help""" 4
 .el .IP "\f(CW\-\-version\fR, \f(CW\-\-help\fR" 4
 .IX Item "--version, --help"
 .SH "TECHNIQUE"
 .IX Header "TECHNIQUE"
-nat-traverse establishes connections between hosts behind \s-1NAT\s0 gateways, without need
+nat-traverse establishes connections between hosts behind \s-1NAT\s0 gateways without need
 for reconfiguration of the involved \s-1NAT\s0 gateways.
 .IP "1." 4
 Firstly, nat-traverse on host \f(CW\*(C`left\*(C'\fR sends garbage \s-1UDP\s0 packets to the \s-1NAT\s0 gateway
@@ -212,22 +220,22 @@ are replies to the packets sent in step 2.
 .IP "4." 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 \s-1STDIN\s0 to the socket or execute a program.
+either relay \s-1STDIN/STDOUT\s0 to the socket or execute a program.
 .SH "EXAMPLES"
 .IX Header "EXAMPLES"
-.Sh "Setup of a small \s-1VPN\s0 with \s-1PPP\s0"
+.SS "Setup of a small \s-1VPN\s0 with \s-1PPP\s0"
 .IX Subsection "Setup of a small VPN with PPP"
 It's easy to setup a \s-1VPN\s0 (Virtual Private Network) by using the Point-to-Point
 Protocol Daemon, \f(CW\*(C`pppd\*(C'\fR:
 .PP
 .Vb 7
-\&  root@left # nat-traverse \e
-\&      --cmd="pppd updetach noauth passive notty \e
+\&  root@left # nat\-traverse \e
+\&      \-\-cmd="pppd updetach noauth passive notty \e
 \&             ipparam vpn 10.0.0.1:10.0.0.2"
-\&      40000:natgw-of-right:40001
-\&  root@right # nat-traverse \e
-\&      --cmd="pppd nodetach notty noauth"
-\&      40001:natgw-of-left:40000
+\&      40000:natgw\-of\-right:40001
+\&  root@right # nat\-traverse \e
+\&      \-\-cmd="pppd nodetach notty noauth"
+\&      40001:natgw\-of\-left:40000
 .Ve
 .PP
 \&\f(CW\*(C`pppd\*(C'\fR creates a new interface, typically \f(CW\*(C`ppp0\*(C'\fR.  Using this interface, you
@@ -237,19 +245,19 @@ establish reliable \s-1TCP\s0 connections over the tunnel, even though the tunne
 \&\s-1UDP\s0!  Furthermore, you could even add IPv6 addresses to \f(CW\*(C`ppp0\*(C'\fR by running \f(CW\*(C`ip
 \&\-6 addr add...\*(C'\fR!
 .PP
-Note though that although this \s-1VPN\s0 \fIis\fR a private network, it is \fInot\fR
+Note though that although this \s-1VPN\s0 \fIis\fR arguably a private network, it is \fInot\fR
 secured in any way. You may want to use \s-1SSH\s0 to encrypt the connection.
-.Sh "Port Forwarding with netcat"
+.SS "Port Forwarding with netcat"
 .IX Subsection "Port Forwarding with netcat"
 You can use \f(CW\*(C`netcat\*(C'\fR to forward one of your local \s-1UDP\s0 or \s-1TCP\s0 ports to an
 arbitrary \s-1UDP\s0 or \s-1TCP\s0 port of the remote host, similar to \f(CW\*(C`ssh \-L\*(C'\fR or \f(CW\*(C`ssh
 \&\-R\*(C'\fR:
 .PP
 .Vb 4
-\&  user@left  $ nat-traverse 10001:natgw-of-right:10002 \e
-\&        --cmd="nc -vlp 20000"
-\&  user@right $ nat-traverse 10002:natgw-of-left:10001 \e
-\&        --cmd="nc -vlp 22"
+\&  user@left  $ nat\-traverse 10001:natgw\-of\-right:10002 \e
+\&        \-\-cmd="nc \-vlp 20000"
+\&  user@right $ nat\-traverse 10002:natgw\-of\-left:10001 \e
+\&        \-\-cmd="nc \-vlp 22"
 .Ve
 .PP
 As soon as the tunnel is established (using \s-1UDP\s0 ports \f(CW10001\fR and \f(CW10002\fR),
@@ -257,52 +265,100 @@ As soon as the tunnel is established (using \s-1UDP\s0 ports \f(CW10001\fR and \
 \&\f(CW22\fR):
 .PP
 .Vb 2
-\&  user@some-other-host $ ssh -p 20000 user@left
-\&  # Will connect to right's SSH daemon!
+\&  user@some\-other\-host $ ssh \-p 20000 user@left
+\&  # Will connect to right\*(Aqs SSH daemon!
 .Ve
 .PP
 But do note that you lose the reliability of \s-1TCP\s0 in this example, as the actual
-data is transported via \s-1UDP\s0. If you want reliable streams, use \s-1PPP\s0 on top of
-nat\-traverse, as described above.
+data is transported via \s-1UDP\s0; so this is only a toy example. If you want
+reliable streams, use \s-1PPP\s0 on top of nat-traverse, as described above.
+.SS "Setup of a \s-1VPN\s0 with OpenVPN"
+.IX Subsection "Setup of a VPN with OpenVPN"
+You can use <OpenVPN> over nat-traverse if you want to
+have a \fIsecure\fR \s-1VPN\s0.
+.PP
+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 \f(CW\*(C`code\*(C'\fR and \f(CW\*(C`lport\*(C'\fR options
+accordingly, for example:
+.PP
+.Vb 3
+\&  # Options to add to left\*(Aqs and right\*(Aqs OpenVPN config:
+\&  port  60001
+\&  lport 60001
+\&
+\&  # Command to execute on left resp. right:
+\&  root@left  # until \e
+\&                 nat\-traverse \-\-quit\-after\-connect 60001:right:60001 \e
+\&               do \e
+\&                 sleep 5 \e
+\&               done; \e
+\&               openvpn [...]
+\&  root@right # until \e
+\&                 nat\-traverse \-\-quit\-after\-connect 60001:left:60001 \e
+\&               do \e
+\&                 sleep 5 \e
+\&               done; \e
+\&               openvpn [...]<!\-\-
+.Ve
+.PP
+The \f(CW\*(C`until\*(C'\fR loop ensures that OpenVPN will not be started before
+nat-traverse was able to establish the connection. Michael Kugele
+(\f(CW\*(C`michael (at) kugele.net\*(C'\fR) 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:
+.PP
+.Vb 4
+\&  iptables \-t nat \-A PREROUTING \-p udp \e
+\&    \-\-dport $LPORT \-j DNAT \-\-to $HOST:$PORT
+\&  iptables \-t nat \-A PREROUTING \-p udp \e
+\&    \-\-dport $PORT \-j REDIRECT \-\-to\-port $LPORT
+.Ve
+.PP
+\&\f(CW$LPORT\fR specifies the source port nat-traverse uses on the server
+side, and \f(CW\*(C`$HOST:$PORT\*(C'\fR is the address of the OpenVPN server.)
 .SH "LIMITATIONS"
 .IX Header "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 \s-1NAT\s0 with IPv6 (the address space IPv6
-provides is sufficient).
+Only IPv4 is supported, nat-traverse won't work with IPv6 addresses. Drop me a
+note if you do need IPv6 support.
 .PP
-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.
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
-.IP "\s-1RFC\s0 1631 at http://www.ietf.org/rfc/rfc1631.txt" 4
-.IX Item "RFC 1631 at http://www.ietf.org/rfc/rfc1631.txt"
+.IP "<\s-1RFC\s0 1631 at http://www.ietf.org/rfc/rfc1631.txt>" 4
+.IX Item "<RFC 1631 at http://www.ietf.org/rfc/rfc1631.txt>"
 The \s-1IP\s0 Network Address Translator (\s-1NAT\s0). K. Egevang, P. Francis.  May 1994.
 (Obsoleted by \s-1RFC3022\s0) (Status: \s-1INFORMATIONAL\s0)
-.IP "\s-1RFC\s0 3022 at http://www.ietf.org/rfc/rfc3022.txt" 4
-.IX Item "RFC 3022 at http://www.ietf.org/rfc/rfc3022.txt"
+.IP "<\s-1RFC\s0 3022 at http://www.ietf.org/rfc/rfc3022.txt>" 4
+.IX Item "<RFC 3022 at http://www.ietf.org/rfc/rfc3022.txt>"
 Traditional \s-1IP\s0 Network Address Translator (Traditional \s-1NAT\s0). P.  Srisuresh,
 K. Egevang. January 2001.  (Obsoletes \s-1RFC1631\s0) (Status: \s-1INFORMATIONAL\s0)
-.IP "\s-1RFC\s0 1661 at http://www.ietf.org/rfc/rfc1661.txt" 4
-.IX Item "RFC 1661 at http://www.ietf.org/rfc/rfc1661.txt"
+.IP "<\s-1RFC\s0 1661 at http://www.ietf.org/rfc/rfc1661.txt>" 4
+.IX Item "<RFC 1661 at http://www.ietf.org/rfc/rfc1661.txt>"
 The Point-to-Point Protocol (\s-1PPP\s0). W. Simpson, Ed.. July 1994.  (Obsoletes
 \&\s-1RFC1548\s0) (Updated by \s-1RFC2153\s0) (Also \s-1STD0051\s0) (Status: \s-1STANDARD\s0)
 .IP "<http://ppp.samba.org/>" 4
 .IX Item "<http://ppp.samba.org/>"
 Website of Paul's \s-1PPP\s0 Package (open source implementation of the
 Point-to-Point Protocol (\s-1PPP\s0) on Linux and Solaris)
-.IP "German talk about nat-traverse at http://linide.sourceforge.net/nat\-traverse/nat\-traverse\-talk.pdf" 4
-.IX Item "German talk about nat-traverse at http://linide.sourceforge.net/nat-traverse/nat-traverse-talk.pdf"
+.IP "<German talk about nat-traverse at http://linide.sourceforge.net/nat\-traverse/nat\-traverse\-talk.pdf>" 4
+.IX Item "<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 die Gegenseite
+vorgestellt, welches sowohl einfache TastendrA\*~Xcke an die Gegenseite
 weiterleiten, als auch beliebige Programme mit Verbindungen zur Gegenseite
 starten kann. Damit ist ein einfaches \s-1VPN\s0 schnell aufgebaut.
 .SH "AUTHOR"
 .IX Header "AUTHOR"
-Copyright (C) 2005 Ingo Blechschmidt, <iblech@web.de>.
+Copyright (C) 2005, 2012 Ingo Blechschmidt, <iblech@web.de>.
 .PP
-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/>.
 .SH "LICENSE"
 .IX Header "LICENSE"
 This program is free software; you can redistribute it and/or modify it under