path: root/nat-traverse.1

.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" 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.  \*(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-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    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 (.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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.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.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "NAT-TRAVERSE 1"
.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
.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.5.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
nat-traverse establishes connections between nodes which are behind \s-1NAT\s0
gateways, i.e. hosts which do \fInot\fR have public \s-1IP\s0 addresses. Additionally,
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
.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
.el .IP "\f(CW\f(CIlocal_port\f(CW:\f(CIpeer\f(CW:\f(CIremote_port\f(CW\fR (required)" 4
.IX Item "local_port:peer:remote_port (required)"
Sets the local port to use and the remote address to connect to.
.Sp
Note that you have to give the \s-1IP\s0 address or hostname of the \fI\s-1NAT\s0 gateway\fR of
the host you want to connect to, as the target host doesn't have a public \s-1IP\s0
address.
.ie n .IP """\-\-cmd=""\f(CIpppd...\f(CW""""" 4
.el .IP "\f(CW\-\-cmd=``\f(CIpppd...\f(CW''\fR" 4
.IX Item "--cmd=""pppd..."""
Runs the specified command after establishing the connection.
.Sp
The command will be run with its \s-1STDIN\s0 and \s-1STDOUT\s0 bound to the socket, i.e.
everything the command writes to \s-1STDOUT\s0 will be forwarded to the peer.
.Sp
If no command is specified, nat-traverse will relay input from \s-1STDIN\s0 to the peer
and vice versa, i.e. nat-traverse degrades to netcat.
.ie n .IP """\-\-window=\f(CI10\f(CW""" 4
.el .IP "\f(CW\-\-window=\f(CI10\f(CW\fR" 4
.IX Item "--window=10"
Sets the number of initial garbage packets to send. The default, 10, should
work with most firewalls.
.ie n .IP """\-\-timeout=\f(CI10\f(CW""" 4
.el .IP "\f(CW\-\-timeout=\f(CI10\f(CW\fR" 4
.IX Item "--timeout=10"
Sets the maximum number of seconds to wait for an acknowledgement by the peer.
.ie n .IP """\-\-quit\-after\-connect""" 4
.el .IP "\f(CW\-\-quit\-after\-connect\fR" 4
.IX Item "--quit-after-connect"
Quits nat-traverse after the tunnel has been established successfully.
.Sp
nat-traverse returns a non\-\f(CW0\fR statuscode to indicate that it wasn't able to
establish the tunnel.
.Sp
\&\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"", ""\-\-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
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
of \f(CW\*(C`right\*(C'\fR. These packets are, of course, discarded by the firewall.
.IP "2." 4
Then \f(CW\*(C`right\*(C'\fR's nat-traverse sends garbage \s-1UDP\s0 packets to the \s-1NAT\s0 gateway of
\&\f(CW\*(C`left\*(C'\fR. These packets are \fInot\fR discarded, as \f(CW\*(C`left\*(C'\fR's \s-1NAT\s0 gateway thinks
these packets are replies to the packets sent in step 1!
.IP "3." 4
\&\f(CW\*(C`left\*(C'\fR's nat-traverse continues to send garbage packets to \f(CW\*(C`right\*(C'\fR's \s-1NAT\s0 gateway.
These packets are now not dropped either, as the \s-1NAT\s0 gateway thinks the packets
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/STDOUT\s0 to the socket or execute a program.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.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
\&             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
.Ve
.PP
\&\f(CW\*(C`pppd\*(C'\fR creates a new interface, typically \f(CW\*(C`ppp0\*(C'\fR.  Using this interface, you
can ping \f(CW10.0.0.1\fR or \f(CW10.0.0.2\fR. As you can see, \f(CW\*(C`pppd\*(C'\fR upgrades the
data-only tunnel nat-traverse provides to a full \s-1IP\s0 tunnel. Thus you can
establish reliable \s-1TCP\s0 connections over the tunnel, even though the tunnel uses
\&\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 arguably a private network, it is \fInot\fR
secured in any way. You may want to use \s-1SSH\s0 to encrypt the connection.
.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"
.Ve
.PP
As soon as the tunnel is established (using \s-1UDP\s0 ports \f(CW10001\fR and \f(CW10002\fR),
\&\f(CW\*(C`left\*(C'\fR's \s-1TCP\s0 port \f(CW20000\fR is forwarded to \f(CW\*(C`right\*(C'\fR's \s-1SSH\s0 Daemon (\s-1TCP\s0 port
\&\f(CW22\fR):
.PP
.Vb 2
\&  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; 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. Drop me a
note if you do need IPv6 support.
.PP
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>"
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>"
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>"
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>"
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 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, 2012 Ingo Blechschmidt, <iblech@web.de>.
.PP
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
the terms of the \s-1GNU\s0 General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
.PP
This program is distributed in the hope that it will be useful, but \s-1WITHOUT\s0 \s-1ANY\s0
\&\s-1WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A
\&\s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the \s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
Street, Fifth Floor, Boston, \s-1MA\s0  02110\-1301, \s-1USA\s0.