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:
commit
b819572f5e
170 changed files with 59193 additions and 0 deletions
15
doc/dest-unreach.css
Normal file
15
doc/dest-unreach.css
Normal 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
340
doc/socat-multicast.html
Normal 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 <
|
||||
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>
|
192
doc/socat-openssltunnel.html
Normal file
192
doc/socat-openssltunnel.html
Normal 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 >$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
165
doc/socat-tun.html
Normal 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
2877
doc/socat.1
Normal file
File diff suppressed because it is too large
Load diff
2686
doc/socat.html
Normal file
2686
doc/socat.html
Normal file
File diff suppressed because it is too large
Load diff
3026
doc/socat.yo
Normal file
3026
doc/socat.yo
Normal file
File diff suppressed because it is too large
Load diff
4959
doc/xio.help
Normal file
4959
doc/xio.help
Normal file
File diff suppressed because it is too large
Load diff
Loading…
Add table
Add a link
Reference in a new issue