.\" As its sole author, I explicitly place this file in the public domain.
.\" It may be used by anyone in any way for any purpose, though I would
.\" appreciate credit where it's due.
.\"		der Mouse, mouse@rodents.montreal.qc.ca, 1999-09-04
.Dd January 29, 2008
.Dt IPTUNNEL 1
.Os NetBSD 1.4T
.Sh NAME
.Nm iptunnel
.Nd IP-in-UDP and IP-in-TCP tunnels
.Sh SYNOPSIS
.Nm
.Op Fl e
.Op Fl v
.Op Fl unit Ar N
.Op Fl tun Ar Pa path
.Op Fl peer Ar addr
.Op Fl local Ar addr
.Op Fl udp Ar lport Ar rport
.Op Fl tcp-accept Ar lport
.Op Fl tcp-connect Ar rport
.Fl secret Ar string
.Ar port
.Sh DESCRIPTION
.Nm
implements IP-over-UDP and IP-over-TCP tunnels.  It is designed for
implementing rudimentary VPNs.
.Pp
Flags understood:
.Bl -tag -width indent
.It Fl e
Encrypt bulk data traffic.  This works only with TCP tunnels.
.It Fl v
Be significantly chattier.  The details of the resulting output are not
documented; this is really intended for debugging.
.It Fl unit Ar N
Use
.Xr tun 4
unit
.Ar N .
See also
.Fl tun
for another way to control this.
.It Fl tun Ar Pa path
Use
.Ar Pa path
as the path to the
.Xr tun 4
control device.  (In most cases,
.Fl unit
is sufficient and more convenient.)
.It Fl peer Ar addr
Use
.Ar addr
as the peer address.  This option must be given with
.Fl udp
and
.Fl tcp-connect
and must not be given with
.Fl tcp-accept .
When used with
.Fl udp ,
the
.Ar addr
may be the word
.Sq dynamic ,
which means that any peer address is acceptable, provided the packets
pass signature verification;
.Nm
will send traffic to the address from which an acceptable packet was
most recently received.  (No packets will be sent until at least one
acceptable packet is recieved.)  Dynamic mode also overrides the
.Ar rport
number specified with
.Fl udp
with the actual peer port.
.It Fl local Ar addr
Use
.Ar addr
as the local address.  Normally, this is omitted; it is necessary only
when there are multiple local addresses and you care which one is used.
.It Fl udp Ar lport Ar rport
Specifies UDP mode.
.Ar lport
is the local port number, at which packets are received, and
.Ar rport
is the remote port number, to which packets are sent.  (The remote
address is specified with
.Fl peer . )
.It Fl tcp-accept Ar lport
Specifies TCP mode, with this process accepting the connection.
.Ar lport
is the port number on which
.Nm
listens for connections.
.It Fl tcp-connect Ar rport
Specifies TCP mode, with this process initiating the connection.
.Ar rport
is the port number to which
.Nm
connects (the remote address is specified with
.Fl peer . )
.It Fl secret Ar string
Specifies a shared secret which is used to sign all traffic.  With
.Fl e ,
it is also leveraged to generate encryption keys.  By default, the
shared secret is the command-line argument literally, but if the
argument begins with @, the rest of it is taken as a file name, and the
shared secret is that file's contents.  (A shared secret specified on
the command line is compatible with a shared secret specified in a
file, but they must be identical; be careful of newlines.)
.Fl secret
must be given.
.El
.Pp
Machine addresses (eg, the argument to
.Fl peer )
can actually be names instead, in which case they are looked up using
the usual name-to-address resolution mechanisms.  Names can have
multiple addresses; this works sanely for TCP, but for UDP only the
first address found is used.  Port numbers can also be names, which are
looked up similarly.
.Pp
It is possible to specify configurations which cannot work under any
circumstances, such as giving
.Fl local
with an IPv4 address and
.Fl peer
with an IPv6 address.  Some such configurations will produce error
messages; others may just result in no communication.
.Pp
While the above description mentions UDP and TCP,
.Nm
is actually protocol-agnostic with respect to the underlying protocols.
It should run over anything supported by the local
.Xr getaddrinfo 3
and
.Xr socket 2 Ap s
.Dv SOCK_STREAM
and
.Dv SOCK_DGRAM .
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .