1
0
Fork 0
mirror of https://repo.or.cz/socat.git synced 2025-07-13 07:03:25 +00:00

socat V1.6.0.0 (initial GIT commit)

This commit is contained in:
Gerhard Rieger 2008-01-27 13:00:08 +01:00
commit b819572f5e
170 changed files with 59193 additions and 0 deletions

15
doc/dest-unreach.css Normal file
View file

@ -0,0 +1,15 @@
<!-- $Revision: 1.1 $ $Date: 2007/03/06 20:42:56 $ -->
<html><head>
<title>dest-unreach.org stylesheet</title>
<style type="text/css">
.frame { border-style:solid; border-width:4px; border-color:black; }
.shell { font-family:Courier;
padding:2px; padding-left:6px; padding-right:6px;
border-style:solid; border-width:1px; border-color:gray;
color:lightgreen; background-color:black;
}
</style>
</head>
<body>
</body>
</html>

340
doc/socat-multicast.html Normal file
View file

@ -0,0 +1,340 @@
<!-- $Revision: 1.1 $ $Date: 2007/03/06 20:54:43 $ -->
<html><head>
<title>IP Multicasting with Socat</title>
<link rel="stylesheet" type="text/css" href="dest-unreach.css">
</head>
<body>
<h1>IP Multicasting with Socat</h1>
<h2>Introduction</h2>
<p>
Multicasting (and broadcasting which is also discussed in this article)
provides a means to direct a single packet to more than one host. Special
addresses are defined for this purpose and are handled specially by network
adapters, networking hardware, and IP stacks.
</p>
<p>
IPv4 specifications provide broadcasting and multicasting; IPv6 provides
multicasting but replaces broadcasting by special multicast modes. UNIX domain
sockets do not know broadcasting or multicasting.
</p>
<p>
The following examples use UDP/IPv4 only. However, they can easily be
adapted for raw IPv4 sockets. IPv6 multicasting has not yet been successfully
used with socat; please contact the author if you have positive experiences or
ideas that go beyond <tt>IPV6_ADD_MEMBERSHIP</tt>.
</p>
<p>
All multicast examples presented in this document use multicast address
224.1.0.1; it can be replaced by any valid IPv4 multicast address (except
<a href="#ALLSYSTEMS">all-systems</a>).
</p>
<p>
We assume a local network with address 192.168.10.0 and mask 255.255.255.0; an
eventual "client" has 192.168.10.1, example "server" and example peer have
192.168.10.2 in all examples. Change these addresses and mask to your own
requirements.
</p>
<p>
All the following examples work bidirectionally except when otherwise noticed.
For "clients" we just use <tt>STDIO</tt>, and for "servers" we use <tt>EXEC:hostname</tt> which
ingores its input but shows us which host the reply comes from. Replace these
addresses with what is appropriate for you (e.g. shell script
invokations). Port 6666 can be replaced with any other port (but for ports &lt;
1024 root privilege might be required).
</p>
<p>
Different kinds of broadcast addresses exist: 255.255.255.255 is local network
only; for the IPv4 network 192.168.10.0/24 the "official" broadcast address
is 192.168.10.255; the network address 192.168.10.0 is also interpreted as
broadcast by some hosts. The two latter forms are routed by gateways. In the
following examples we only use broadcast address 192.168.10.255.
</p>
<h2>Example 1: Multicast client and servers</h2>
<p>This example builds something like a "supervisor" or "client" that
communicates with a set of "servers". The supervisor may send packets to the
multicast address, and the servers may send response packets. Note that the
servers would also respond to other clients' requests.</p>
<p>Multicast server:</p>
<span class="frame"><span class="shell">
socat UDP4-RECVFROM:6666,ip-add-membership=224.1.0.1:192.168.10.2,fork EXEC:hostname
</span></span>
<p>
This command receives multicast packets addressed to 224.1.0.1 and forks a
child process for each. The child processes may each send one or more reply
packets back to the particular sender. 192.168.10.2 means the address of the
interface where multicasts should be received.
Run this command on a number of hosts, and they will all respond in
parallel.</p>
<p>Multicast client:</p>
<span class="frame"><span class="shell">
socat STDIO UDP4-DATAGRAM:224.1.0.1:6666,range=192.168.10.0/24
</span></span>
<p>
This process transfers data from stdin to the multicast address, and transfers
packets received from the local network to stdout. It does not matter in which
direction the first data is passed.
A packet from the network is accepted by the IP stack for our socket if:
<ul>
<li>it is an incoming UDP/IPv4 packet</li>
<li>its target port matches the local port assigned to the socket (6666)</li>
<li>its target address matches one of the hosts local addresses or the any-host
multicast address</li>
</ul>
Of these packets, socat handles only those matching the following criteria:
<ul>
<li>the source address is within the given range</li>
<li>the source port is 6666</li>
</ul>
</p>
<h2>Example 2: Broadcast client and servers</h2>
<p>Broadcast server:</p>
<span class="frame"><span class="shell">
socat UDP4-RECVFROM:6666,broadcast,fork EXEC:hostname
</span></span>
<p>
This command receives packets addressed to a local broadcast address and forks
a child process for each. The child processes may each send one or more reply
packets back to the particular sender.
Run this command on a number of hosts, and they will all respond in
parallel.</p>
<p>Broadcast client:</p>
<span class="frame"><span class="shell">
socat STDIO UDP4-DATAGRAM:192.168.10.255:6666,broadcast,range=192.168.10.0/24
</span></span>
<p>
This process transfers data from stdin to the broadcast address, and transfers
packets received from the local network to stdout. It does not matter in which
direction the first data is passed.
A packet from the network is accepted by the IP stack for our socket if:
<ul>
<li>it is an incoming UDP/IPv4 packet</li>
<li>its target port matches the local port assigned to the socket (6666)</li>
<li>its target address matches one of the hosts local addresses or the any-host
multicast address, or a local broadcast address</li>
</ul>
Of these packets, socat handles only those matching the following criteria:
<ul>
<li>the source address is within the given range</li>
<li>the source port is 6666</li>
</ul>
</p>
<p>The <tt>broadcast</tt> option is only required for sending or receiving
local broadcasts.</p>
<h2>Example 3: Multicast peers</h2>
<p>It is possible to combine multicast sender and receiver in one socat
address. This allows to start processes on different hosts on the local network
that will communicate symmetrically, so each process can send messages that are
received by all the other ones.</p>
<span class="frame"><span class="shell">
socat STDIO UDP4-DATAGRAM:224.1.0.1:6666,bind=:6666,range=192.168.10.0/24,ip-add-membership=224.1.0.1:192.168.10.2
</span></span>
<p>
This command is valid for host 192.168.10.2; adapt this address to the
particular interface addresses of the hosts.
</p>
<p>
Starting this process opens a socket on port 6666 that will receive packets
directed to multicast address 224.1.0.1. Only packets with matching source
address and source port 6666 will be handled though. When this process sends
data to the network the packets will be addressed to 224.1.0.1:6666 and have a
source address of 192.168.10.2:6666, matching the accept criteria of the peers
on the local network.
</p>
<p>Note: this command receives the packets it just has sent; add option
<tt>ip-multicast-loop=0</tt> if this in undesired.</p>
<h2>Example 4: Broadcast peers</h2>
<p>Just as with multicast, it is possible to combine broadcast sender and
receiver in one socat address.</p>
<span class="frame"><span class="shell">
socat STDIO UDP4-DATAGRAM:255.255.255.255:6666,bind=:6666,range=192.168.10.0/24,broadcast
</span></span>
<p>
Starting this process opens a socket on port 6666 that will receive packets
directed to a local broadcast addresses. Only packets with matching source
address and source port 6666 will be handled though. When this process sends
data to the network the packets will be addressed to 255.255.255.255:6666 and
have a source address of 192.168.10.2:6666, matching the accept criteria of
the peers on the local network.
</p>
<p>Note: this command receives the packets it just has sent; there does not
seem to exist a simple way to prevent this.</p>
<h2>Troubleshooting</h2>
<p>
If you do not get an error message during operation, but the packets do not
reach the target processes, use <tt>tcpdump</tt> to see if the packets have the
correct source and destination addresses and ports, and if they leave and enter
the hosts as expected.
</p>
<p>
The following subsections discuss some typical sources of trouble.
</p>
<h3>IP filters</h3>
<p>
If you do not succeed in receiving multicast or broadcast packets, check if
iptables are activated on the receiving or sending host. They might be
configured to disallow this traffic.
</p>
<h3>Do not bind()</h3>
<p>
When using multicast communications, you should not bind the sockets to a
specific IP address. It seems that the (Linux) IP stack compares the
destination address with the bind address, not taking care of the multicast
property of the incoming packet.
</p>
<h3>Routing</h3>
<p>
When you receive an error like:</p>
<table border="1" bgcolor="#e08080"><tr><td><tt>... E sendto(3, 0x80c2e44, 4,
0, AF=2 224.1.0.1:6666, 16): Network is unreachable</tt></td></tr></table>
<p>you have a routing problem. The (Linux) IP stack seems to handle multicast
addresses just like unicast addresses when determining their route (interface and gateway).</p>
<p>
For the same reason, multicast packets will probably leave your host on the
interface with the default route.</p>
<p>
Set a multicast/broadcast route with the following command:</p>
<span class="frame"><span class="shell">
route add -net 224.0.0.0/3 gw 192.168.10.2
</span></span>
<h3>ALL-SYSTEMS multicast address</h3>
<p>
<a name="ALLSYSTEMS"><tt>224.0.0.1</tt></a> is the all-systems multicast address: all
datagram sockets appear to be automatically member of this group on all
interfaces. This membership cannot be dropped on Linux.
</p>
<h2>(In)Security</h2>
<p>When you use the above examples you should understand that all datagram
sockets without exception accept packets that are directly addressed to them;
the multi- and broadcast receiving features are just extensions to the normal
functionality. socat has no way to find out if an incoming packet is addressed
to a unicast, multicast or broadcast address. Please contact the author if you
know how the target address can be determined.</p>
<p>Authentication or encryption are not available.</p>
<p>It is very easy to fake the source address of UDP (or raw IP) packets. You
should understand whether your network is protected from address spoofing
attacks.</p>
<p>Broadcast and multicast traffic can trivially be received by <em>any</em>
host on the local network.</p>
<h2>History</h2>
Starting with version 1.5.0, socat provides a set of address types that
allow various operations on datagram oriented sockets:
<dl>
<dt>SENDTO</dt><dd>send packets to a remote socket and receive packet from this
remote socket only</dd>
<dt>RECV</dt><dd>receive all packets that arrive on the local socket, but do
not reply</dd>
<dt>RECVFROM</dt><dd>receive all packets that arrive on the local socket, and
reply using child processes</dd>
</dl>
<p>
These modes already enable several different client/server oriented operations.
Moreover, the SENDTO addresses can send to multicast and broadcast addresses
(the latter requires the <tt>broadcast</tt> option though). RECV and RECVFROM
also would accept packets addressed to a local broadcast address (with option
<tt>broadcast</tt>) or the all-systems multicast address.
</p>
<p>
These address types had, however, two major caveats:
<ul>
<li>Missing control of multicast group membership in the RECV and RECVFROM
addresses</li>
<li>The SENDTO address would never accept a reply to a broadcast or multicast
addressed packet because the source address of incoming replies would not match
the target address of the sent packet.
</ul>
</p>
<h3>New Features in socat 1.6.0</h3>
<p>
socat version 1.6.0 addresses these problems and provides a new more generic
datagram address type (*-DATAGRAM) and the new address option IP-ADD-MEMBERSHIP.
</p>
<p>
Please note that the new features could not be successfully tested on IPv6;
these sections thus apply to IPv4 only.
</p>
<p>This document was last modified in March 2007.</p>
<h2>More info about socat datagrams</h2>
<h3>Links regarding this tutorial</h3>
<a href="socat.html#ADDRESS_UDP4_DATAGRAM">address udp4-datagram</a><br>
<a href="socat.html#ADDRESS_UDP4_RECVFROM">address udp4-recvfrom</a><br>
<a href="socat.html#OPTION_RANGE">option range</a><br>
<a href="socat.html#OPTION_SO_BROADCAST">option broadcast</a><br>
<a href="socat.html#OPTION_IP_ADD_MEMBERSHIP">option ip-add-membership</a><br>
<a href="socat.html#OPTION_FORK">option fork</a><br>
<a href="socat.html#OPTION_BIND">option bind</a><br>
<h3>Other datagram addresses</h3>
<a href="socat.html#ADDRESS_UDP4_RECV">address udp4-recv</a>: pure datagram receiver<br>
<a href="socat.html#ADDRESS_UDP4_SENDTO">address udp4-sendto</a>: communicate
with one peer address<br>
<a href="socat.html#ADDRESS_UDP4_LISTEN">address udp4-listen</a>: pseudo stream server<br>
<a href="socat.html#ADDRESS_UDP4_CONNECT">address udp4-connect</a>: pseudo stream client<br>
<h3>Related socat option groups</h3>
<a href="socat.html#GROUP_IP">IP options</a><br>
<a href="socat.html#GROUP_SOCKET">socket options</a><br>
<a href="socat.html#GROUP_FD">file descriptor options</a><br>
<a href="socat.html#GROUP_RANGE">range options</a><br>
<a href="socat.html#GROUP_CHILD">child process options</a><br>
<h2>References</h2>
<a href="http://www.dest-unreach.org/socat">socat home page</a><br>
<a href="socat.html">socat man page</a><br>
<a href="http://en.wikipedia.org/wiki/Multicast">multicasting on Wikipedia</a><br>
<a href="http://en.wikipedia.org/wiki/Broadcast_address">broadcasting on Wikipedia</a><br>
<p>
<small>Copyright: Gerhard Rieger 2007</small><br>
<small>License: <a href="http://www.fsf.org/licensing/licenses/fdl.html">GNU Free Documentation License (FDL)</a></small>
</p>
</body>
</html>

View file

@ -0,0 +1,192 @@
<!-- $Revision: 1.1 $ $Date: 2007/03/06 20:54:43 $ -->
<html><head>
<title>Securing Traffic Between two Socat Instances Using SSL</title>
<link rel="stylesheet" type="text/css" href="dest-unreach.css">
</head>
<body>
<h1>Securing Traffic Between two Socat Instances Using SSL</h1>
<h2>Introduction</h2>
<p>
When you want to connect two socat processes running on different machines and
feel that you need to protect the connection against unauthorized access,
sniffing, data manipulation etc., you might want to encrypt the communications.
</p>
<p>
For this purpose socat integrates the OpenSSL library and provides SSL client
and server features.
</p>
<p>
SSL is a complex protocol that provides much more features than required for
protecting a single connection; in this document we present only a simple
scenario that provides just the basic security requirements.
</p>
<!-- discussion -->
<h2>Configuring OpenSSL in socat</h2>
<p>
This section shows how the SSL addresses can be configured in socat.
In this docu we only use self signed certificates for the sake of simplicity.
</p>
<p>We assume that the server host is called <tt>server.domain.org</tt> and the
server process uses port 4433. To keep it simple, we use a very simple server
funtionality that just echos data (<tt>echo</tt>), and <tt>stdio</tt> on the
client.</p>
<h3>Generate a server certificate</h3>
<p>Perform the following steps on a trusted host where OpenSSL is
installed. It might as well be the client or server host themselves.</p>
<p>Prepare a basename for the files related to the server certificate:</p>
<span class="frame"><span class="shell">FILENAME=server</span></span>
<p>Generate a public/private key pair:</p>
<span class="frame"><span class="shell">openssl genrsa -out $FILENAME.key 1024</span></span>
<p>Generate a self signed certificate:</p>
<span class="frame"><span class="shell">
openssl req -new -key $FILENAME.key -x509 -days 3653 -out $FILENAME.crt</span></span>
<p>You will be prompted for your country code, name etc.; you may quit all prompts
with the enter key.</p>
<p>Generate the PEM file by just appending the key and certificate files:<p>
<span class="frame"><span class="shell">cat $FILENAME.key $FILENAME.crt &gt;$FILENAME.pem</span></span>
<p>The files that contain the private key should be kept secret, thus adapt
their permissions:<p>
<span class="frame"><span class="shell">chmod 600 $FILENAME.key $FILENAME.pem</span></span>
<p>Now bring the file <tt>server.pem</tt> to the SSL server, e.g. to directory
<tt>$HOME/etc/</tt>, using a secure channel like USB memory stick or SSH. Keep
tight permissions on the file even on the target host, and remove all other
instances of <tt>server.key</tt> and <tt>server.pem</tt>.
</p>
<p>Copy the trust certificate server.crt to the SSL client host, e.g. to directory
<tt>$HOME/etc/</tt>; a secure channel is not required here, and the permissions
are not critical.
</p>
<h3>Generate a client certificate</h3>
<p>First prepare a different basename for the files related to the client certificate:</p>
<span class="frame"><span class="shell">FILENAME=client</span></span>
<p>Repeat the procedure for certificate generation described above.
Copy <tt>client.pem</tt> to the SSL client, and <tt>client.crt</tt> to the
server.</p>
<h3>OpenSSL Server</h3>
<p>Instead of using a tcp-listen (tcp-l) address, we use openssl-listen (ssl-l)
for the server, <tt>cert=...</tt> tells the program to the file containing its
ceritificate and private key, and <tt>cafile=...</tt> points to the file
containing the certificate of the peer; we trust clients only if they can proof
that they have the related private key (OpenSSL handles this for us):<p>
<span class="frame"><span class="shell">socat openssl-listen:4433,reuseaddr,cert=$HOME/etc/server.pem,cafile=$HOME/etc/client.crt echo</span></span>
<p>After starting this command, socat should be listening on port 4433, but
will require client authentication.</p>
<h3>OpenSSL Client</h3>
<p>Substitute your <tt>tcp-connect</tt> or <tt>tcp</tt> address keyword with
<tt>openssl-connect</tt> or just <tt>ssl</tt> and here too add the
<tt>cert</tt> and <tt>cafile</tt> options:<p>
<span class="frame"><span class="shell">socat stdio openssl-connect:server.domain.org:4433,cert=$HOME/etc/client.pem,cafile=$HOME/etc/server.crt</span></span>
<p>This command should establish a secured connection to the server
process.</p>
<h3>TCP/IP version 6</h3>
<p>If the communication is to go over IPv6, the above described commands have
to be adapted; <tt>ip6name.domain.org</tt> is assumed to resolve to the IPv6
address of the server:</p>
<p>Server:</p>
<span class="frame"><span class="shell">socat
openssl-listen:4433,<b style="color:yellow">pf=ip6</b>,reuseaddr,cert=$HOME/etc/server.pem,cafile=$HOME/etc/client.crt echo</span></span>
<p>Client:</p>
<span class="frame"><span class="shell">socat stdio openssl-connect:<b style="color:yellow">ip6name</b>.domain.org:4433,cert=$HOME/etc/client.pem,cafile=$HOME/etc/server.crt</span></span>
<h2>Troubleshooting</h2>
<h3>Test OpenSSL Integration</h3>
<p>
If you get error messages like this:</p>
<table border="1" bgcolor="#e08080"><tr><td><tt>... E unknown device/address "openssl-listen"</tt></td></tr></table>
<p>your socat executable probably does not have the OpenSSL library linked in.
Check socat's compile time configuration with the following command:</p>
<span class="frame"><span class="shell">socat -V |grep SSL</span></span>
<p>Positive output:
<tt>#define WITH_OPENSSL 1</tt><br>
Negative output:
<tt>#undef WITH_OPENSSL</tt><br>
</p>
<p>
In the latter case, make sure you have OpenSSL and its development package
(include files) installed, and check the run of the configure script.
</p>
<h2>History</h2>
<p>
A first OpenSSL client was implemented in socat 1.2.0; it did not support
client certificates and could not verify server certificates. It was rather
considered as a tool for probing typical SSL secured Internet services.
</p>
<p>
From version 1.4.0 on, socat provided experimental support for SSL client and
SSL server, implemented using the OpenSSL libraries. Only TCP/IPv4 transport
was supported. With both SSL client and server, trust certificates for checking
the peers authentication, and certificates for authentication could be
specified. This allowed for non interactive secure connection establishing.
The features were considered experimental; like most Internet sites, socat
server did not require the client to present a certificate per default, but the
client required a server certificate.
</p>
<p>
DSA certificate support is implemented since version 1.4.2.
</p>
<p>
Socat version 1.5.0 extended SSL to TCP/IPv6 transports.
</p>
<p>
With socat version 1.6.0, the SSL server per default requires the client to
present a trusted certificate. socat's OpenSSL implementation still does not
check the contents of a certificate like host name or host address.
</p>
<p>This document was last modified in March 2007.</p>
<h2>More info about socat OpenSSL</h2>
<h3>Links regarding this tutorial</h3>
<a href="socat.html#ADDRESS_OPENSSL_CONNECT">address openssl-connect</a><br>
<a href="socat.html#ADDRESS_OPENSSL_LISTEN">address openssl-listen</a><br>
<a href="socat.html#OPTION_OPENSSL_CERTIFICATE">option cert</a><br>
<a href="socat.html#OPTION_OPENSSL_CAFILE">option cafile</a><br>
<h3>More socat options for OpenSSL addresses</h3>
<a href="socat.html#GROUP_OPENSSL">OpenSSL options</a><br>
<a href="socat.html#GROUP_TCP">TCP options</a><br>
<a href="socat.html#GROUP_IP">IP options</a><br>
<a href="socat.html#GROUP_SOCKET">socket options</a><br>
<a href="socat.html#GROUP_FD">file descriptor options</a><br>
<a href="socat.html#GROUP_RETRY">retry options</a><br>
<p>For openssl-listen only:</p>
<a href="socat.html#GROUP_LISTEN">listen options</a><br>
<a href="socat.html#GROUP_CHILD">child options</a><br>
<a href="socat.html#GROUP_RANGE">range options</a><br>
<h2>References</h2>
<a href="http://www.dest-unreach.org/socat">socat home page</a><br>
<a href="socat.html">socat man page</a><br>
<a href="http://www.openssl.org/">OpenSSL home page</a><br>
<a href="http://www.stunnel.org/">stunnel home page</a><br>
<a href="http://en.wikipedia.org/wiki/Secure_Sockets_Layer">secure sockets layer on Wikipedia</a><br>
<p>
<small>Copyright: Gerhard Rieger 2007</small><br>
<small>License: <a href="http://www.fsf.org/licensing/licenses/fdl.html">GNU Free Documentation License (FDL)</a></small>
</p>
</body>
</html>

165
doc/socat-tun.html Normal file
View file

@ -0,0 +1,165 @@
<!-- $Revision: 1.1 $ $Date: 2007/03/06 20:54:43 $ -->
<html><head>
<title>Building TUN based virtual networks with socat</title>
<link rel="stylesheet" type="text/css" href="dest-unreach.css">
</head>
<body>
<h1>Building TUN based virtual networks with socat</h1>
<h2>Introduction</h2>
<p>
Some operating systems allow the generation of virtual network interfaces that
do not connect to a wire but to a process that simulates the network. Often
these devices are called TUN or TAP.
</p>
<p>
socat provides an address type that creates a TUN device on Linux; the other
socat address can be any type; it transfer the "wire" data as desired.
</p>
<p>
This document shows how a simple virtual network can be created between
two hosts that may be far (many network hops) apart. On both hosts a socat
instance is started that connects to the other host using TCP and creates a TUN
device. See <a href="socat-openssltunnel.html">socat-openssltunnel.html</a> for
a guide on securing the connection using SSL.
</p>
<p>
The following IP addresses are used in the example; replace them in the
following commands with the requirements of your situation:</p>
<table border="1">
<tr><th>host</th><th>address</th><th>mask</th></tr>
<tr><td>physical "server" address</td><td>1.2.3.4</td><td>n/a</td></tr>
<tr><td>physical "client" address</td><td>223.2.3.4</td><td>n/a</td></tr>
<tr><td>TUN on "server"</td><td>192.168.255.1</td><td>255.255.255.0</td></tr>
<tr><td>TUN on "client"</td><td>192.168.255.2</td><td>255.255.255.0</td></tr>
</table>
<p>The TCP connection uses port 11443.</p>
<p>On "default" Linux installations, creating TUN/TAP devices might require
root privilege.</p>
<!-- discussion -->
<h2>Generate TUN devices with socat</h2>
<p>In this section two instances of socat are used to generate TUN devices on
different hosts and connect the "wire" sides, providing a simple virtual
network.
</p>
<p>
We distinguish server and client only with respect to the connection between
the two socat instances; the TUN interfaces both have the same quality.
</p>
<h3>TUN Server</h3>
<span class="frame"><span class="shell">socat -d -d TCP-LISTEN:11443,reuseaddr TUN:192.168.255.1/24,up</span></span>
<p>After starting this command, socat will wait for a connection and then
create a TUN pseudo network device with address 192.168.255.1; the bit number
specifies the mask of the network that is pretended to be connected on this
interface.</p>
<h3>TUN Client</h3>
<span class="frame"><span class="shell">socat TCP:1.2.3.4:11443 TUN:192.168.255.2/24,up</span></span>
<p>This command should establish a connection to the server and create the TUN
device on the client.</p>
<h3>Seeing it work</h3>
<p>
After successful connection both TUN interfaces should be active and transfer
date between each other using the TCP connection. Try this by pinging
192.168.255.1 from the client and 192.168.255.2 from the server.
</p>
<h3>TCP/IP version 6</h3>
<p>IPv6 as transport should work just like any TCP/IPv6 connection.</p>
<p>Creation of an IPv6 virtual interface is not directly possible, but you can
generate an IPv4 interface as described above, and add IPv6 addresses using
the <tt>ifconfig</tt> command.
<h2>Troubleshooting</h2>
<h3>Test TUN integration</h3>
<p>
If you get error messages like this:</p>
<table border="1" bgcolor="#e08080"><tr><td><tt>... E unknown device/address "tun"</tt></td></tr></table>
<p>your socat executable probably does not provide TUN/TAP support. Potential
reasons: you are not on Linux or are using an older version of socat.
</p>
<h3>Missing kernel support</h3>
<p>An error message like:</p>
<table border="1" bgcolor="#e08080"><tr><td><tt>... E open("/dev/net/tun", 02, 0666): No such file or directory</tt></td></tr></table>
<p>indicates that your kernel does not have TUN/TAP support compiled
in. Rebuild your kernel with the appropriate configuration (probably under
<b>Device driver / Network device support / Network device / Universal TUN/TAP</b>).
</p>
<h3>TUN cloning device permissions</h3>
<p>An error message like:</p>
<table border="1" bgcolor="#e08080"><tr><td><tt>... E open("/dev/net/tun", 02, 0666): Permission denied</tt></td></tr></table>
<p>indicates that you do not have permission to read or write the TUN cloning
device. Check its permission and ownership.</p>
<h3>Interface down</h3>
<p>If no error occurs but the pings do not work check if the network devices
have been created:</p>
<span class="frame"><span class="shell">ifconfig tun0</span></span>
<p>The output should look like:</p>
<pre>
tun0 Link encap:UNSPEC HWaddr 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00
inet addr:192.168.255.1 P-t-P:192.168.255.1 Mask:255.255.255.0
UP POINTOPOINT RUNNING NOARP MULTICAST MTU:1500 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:500
RX bytes:0 (0.0 b) TX bytes:0 (0.0 b)
</pre>
<p>Check the "UP" keyword; you forget the "up" option in the socat command if
it is missing.<p>
<p>Check if the correct IP address and network mask are displayed.</p>
<h3>Routing</h3>
<p></p>
<span class="frame"><span class="shell">netstat -an |fgrep 192.168.255</span></span>
<p>The output should look like:</p>
<pre>
192.168.255.0 0.0.0.0 255.255.255.0 U 0 0 0 tun0
</pre>
<h3>Other problems</h3>
<p>Another reason for failure might be iptables.</p>
<p>Run socat with options <tt>-d -d -d</tt>, this will show every data transfer
between the two processes. Each ping probe should cause a forth and a back
transfer.<p>
<h2>History</h2>
<p>
Linux TUN/TAP support was added to socat in version 1.6.0.</p>
<p>This document was last modified in March 2007.</p>
<h2>More info about socat TUN/TAP support</h2>
<h3>Links regarding this tutorial</h3>
<a href="socat.html#ADDRESS_TUN">socat address tun</a><br>
<h3>socat options for TUN/TAP addresses</h3>
<a href="socat.html#GROUP_TUN">TUN/TAP options</a><br>
<h2>References</h2>
<a href="http://www.dest-unreach.org/socat">socat home page</a><br>
<a href="socat.html">socat man page</a><br>
<a href="http://openvpn.net/">OpenVPN home page</a><br>
<a href="http://en.wikipedia.org/wiki/TUN/TAP">TUN/TAP on Wikipedia</a><br>
<p>
<small>Copyright: Gerhard Rieger 2007</small><br>
<small>License: <a href="http://www.fsf.org/licensing/licenses/fdl.html">GNU Free Documentation License (FDL)</a></small>
</p>
</body>
</html>

2877
doc/socat.1 Normal file

File diff suppressed because it is too large Load diff

2686
doc/socat.html Normal file

File diff suppressed because it is too large Load diff

3026
doc/socat.yo Normal file

File diff suppressed because it is too large Load diff

4959
doc/xio.help Normal file

File diff suppressed because it is too large Load diff