Add initial packaging by GRML project.

1 files changed, 184 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..cd36aea
--- /dev/null
+++ b/README
@@ -0,0 +1,184 @@
+NAME
+    nat-traverse - Use of UDP to traverse NAT gateways
+
+SYNOPSIS
+      user@left  $ nat-traverse 40000:natgw-of-right:40001
+      user@right $ nat-traverse 40001:natgw-of-left:40000
+
+VERSION
+    This document describes nat-traverse v0.4.
+
+DESCRIPTION
+    nat-traverse establishes connections between nodes which are behind NAT
+    gateways, i.e. hosts which do *not* have public IP addresses.
+    Additionally, you can setup a small VPN by using pppd on top of
+    nat-traverse (see "EXAMPLES"). nat-traverse does *not* need an external
+    server on the Internet, and it isn't necessary to reconfigure the
+    involved NAT gateways, either. *nat-traverse works out-of-the-box.*
+
+    See "TECHNIQUE" for how this is achieved.
+
+OPTIONS
+    "*local_port*:*peer*:*remote_port*" (required)
+        Sets the local port to use and the remote address to connect to.
+
+        Note that you have to give the IP address or hostname of the *NAT
+        gateway* of the host you want to connect to, as the target host
+        doesn't have a public IP address.
+
+    "--cmd="*pppd...*""
+        Runs the specified command after establishing the connection.
+
+        The command will be run with its STDIN and STDOUT bound to the
+        socket, i.e. everything the command writes to STDOUT will be
+        forwarded to the peer.
+
+        If no command is specified, nat-traverse will relay input from STDIN
+        to the peer and vice versa, i.e. nat-traverse degrades to netcat.
+
+    "--window=*10*"
+        Sets the number of initial garbage packets to send. The default, 10,
+        should work with most firewalls.
+
+    "--timeout=*10*"
+        Sets the maximum number of seconds to wait for an acknowledgement by
+        the peer.
+
+    "--quit-after-connect"
+        Quits nat-traverse after the tunnel has been established
+        successfully.
+
+        nat-traverse returns a non-0 statuscode to indicate that it wasn't
+        able to establish the tunnel.
+
+        "--quit-after-connect" 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
+        NAT gateways.
+
+    "--version", "--help"
+
+TECHNIQUE
+    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
+        the NAT gateway of "right". These packets are, of course, discarded
+        by the firewall.
+
+    2.  Then "right"'s nat-traverse sends garbage UDP packets to the NAT
+        gateway of "left". These packets are *not* discarded, as "left"'s
+        NAT gateway thinks these packets are replies to the packets sent in
+        step 1!
+
+    3.  "left"'s nat-traverse continues to send garbage packets to "right"'s
+        NAT gateway. These packets are now not dropped either, as the NAT
+        gateway thinks the packets are replies to the packets sent in step
+        2.
+
+    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.
+
+EXAMPLES
+  Setup of a small VPN with PPP
+    It's easy to setup a VPN (Virtual Private Network) by using the
+    Point-to-Point Protocol Daemon, "pppd":
+
+      root@left # nat-traverse \
+          --cmd="pppd updetach noauth passive notty \
+                 ipparam vpn 10.0.0.1:10.0.0.2"
+          40000:natgw-of-right:40001
+      root@right # nat-traverse \
+          --cmd="pppd nodetach notty noauth"
+          40001:natgw-of-left:40000
+
+    "pppd" creates a new interface, typically "ppp0". Using this interface,
+    you can ping 10.0.0.1 or 10.0.0.2. As you can see, "pppd" upgrades the
+    data-only tunnel nat-traverse provides to a full IP tunnel. Thus you can
+    establish reliable TCP connections over the tunnel, even though the
+    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.
+
+  Port Forwarding with netcat
+    You can use "netcat" to forward one of your local UDP or TCP ports to an
+    arbitrary UDP or TCP port of the remote host, similar to "ssh -L" or
+    "ssh -R":
+
+      user@left  $ nat-traverse 10001:natgw-of-right:10002 \
+            --cmd="nc -vlp 20000"
+      user@right $ nat-traverse 10002:natgw-of-left:10001 \
+            --cmd="nc -vlp 22"
+
+    As soon as the tunnel is established (using UDP ports 10001 and 10002),
+    "left"'s TCP port 20000 is forwarded to "right"'s SSH Daemon (TCP port
+    22):
+
+      user@some-other-host $ ssh -p 20000 user@left
+      # 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.
+
+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).
+
+    If you do need IPv6 support, drop me a note and I'll patch nat-traverse.
+
+SEE ALSO
+    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
+        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
+        The Point-to-Point Protocol (PPP). W. Simpson, Ed.. July 1994.
+        (Obsoletes RFC1548) (Updated by RFC2153) (Also STD0051) (Status:
+        STANDARD)
+
+    <http://ppp.samba.org/>
+        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
+        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 weiterleiten, als auch beliebige Programme mit
+        Verbindungen zur Gegenseite starten kann. Damit ist ein einfaches
+        VPN schnell aufgebaut.
+
+AUTHOR
+    Copyright (C) 2005 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.
+
+LICENSE
+    This program is free software; you can redistribute it and/or modify it
+    under the terms of the GNU General Public License as published by the
+    Free Software Foundation; either version 2 of the License, or (at your
+    option) any later version.
+
+    This program is distributed in the hope that it will be useful, but
+    WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+    Public License for more details.
+
+    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, USA.
+