<!-- source: socat-exec.html -->
<!-- Copyright Gerhard Rieger 2009 -->
<html><head>
<title>Executing programs using socat</title>
<link rel="stylesheet" type="text/css" href="dest-unreach.css">
</head>
<body>
<h1>Executing programs using socat</h1>
<h2>Introduction</h2>
<p>From its very beginning socat provided the <tt>EXEC</tt> and <tt>SYSTEM</tt>
address types for executing programs or scripts and exchanging data with
them. Beginning with version 2 - with implementation of the address chain
feature (inter addresses) - these address types were enhanced to allow
execution of programs also in inter address context.
</p>
<h2>Program context types</h2>
<p>Currently socat provides three contexts (interfaces) for program or script
execution:
<ul>
<li>The <em>endpoint</em> context: this is the classical situation where
socat equips the program with stdin and stdout. It does not
matter if the program uses other external communication channels. Address
keywords: EXEC, SYSTEM. This variant should be easy to understand in terms
of socat version 1 functionality and is therefore not further
discussed here.</li>
<li>The <em>bidirectional inter address</em> context: socat expects the
program to use two bidirectional channels: stdin and stdout on its "left"
side and file descriptors 3 and 4 on its "right" side. This allows to
provide nearly arbitrary data manipulations within the context of socat
chains. Address keywords: EXEC, SYSTEM.</li>
<li>The <em>unidirectional inter address</em> context: for easy
integration of standard UNIX programs socat provides the EXEC1 and SYSTEM1
address types where socat provides stdin on the "left" side and stdout on
the "right" side of the program, or vice versa for right-to-left
transfers.</li>
</ul>
</p>
<p>Note: The <em>endpoint</em> and the <em>unidirectional inter address</em>
contexts both just use the program's stdio to communicate with it. However,
in practice the last form will in most cases just manipulate and transfer
data, while the first form will usually have side effects by communicating
with exteral resources or by writing to the file system etc.
</p>
<h2>Executing programs in bidirectional inter address context</h2>
<p>socat address chains concatenate internal modules that communicate
bidirectionally.
For example, a chain that establishes encrypted connection to a socks server
might look something like this (parameters and options dropped):
</p>
<p><code>"SOCKS:... | OPENSSL-CLIENT | TCP:..."</code></p>
<p>If you have a program that implements a new encryption protocol the chain
could be changed to:
</p>
<p><code>"SOCKS:... | EXEC:myencrypt.sh | TCP:..."</code></p>
<p>The complete example:</p>
<p><code>socat - "SOCKS:www.domain.com:80 | EXEC:myencrypt.sh | TCP:encrypt.secure.org:444"</code></p>
<p>The <tt>myencrypt.sh</tt> script would be a wrapper around some myencrypt
program. It must adhere a few rules: It reads and writes cleartext data on
its left side (FDs 0 and 1), and it reads and writes encrypted data on its
right side (FDs 3 and 4). Thus, cleartext data would come from the left on FD
0, be encrypted, and sent to the right side through FD 4. Encrypted data would
come from the the right on FD 3, be unencrypted, and sent to the left side
through FD 1. It does not matter if the encryption protocol would required
negotiations or multiple packets on the right side.
</p>
<p>The <tt>myencrypt.sh</tt> script might log to syslog, its own log
file, or to stderr - this is independend of socat. It might have almost
arbitrary side effects.
</p>
<p>For optimal integration the script should be able to perform half-close and
should be able work with different file descriptor types (sockets, pipes,
ptys).
</p>
<p>The socat source distribution contains two example scripts that focus on
partial aspects:
<ul>
<li><tt>predialog.sh</tt> implements an initial dialog on the "right" script
side and, after successful completion, begins to transfer data unmodified in
both directions.</li>
<li><tt>cat2.sh</tt> shows how to use two programs unidirectionally to gain
bidirectional transfer. The important aspects here are the shell based
input / output redirections that are necessary for half-close.</li>
</ul>
<h2>Using unidirectional inter addresses</h2>
<p>There exist lots of UNIX programs that perform data manipulation like
compression or encoding from stdin to stdout, while related programs perform
the reverse operation (decompression, decoding...) also from stdin to
stdout. socat makes it easy to use those programs directly, i.e. without the
need to write a bidirectional wrapper shell script.
</p>
<p><code>socat - "exec1:gzip % exec1:gunzip | tcp:remotehost:port"</code>
</p>
<p>The % character creates a dual communication context where different
inter addresses are used for left-to-right and right-to-left transer (see
<a href="socat-addresschain.html">socat-addresschain.html#dual</a>. socat
generates stdin/stdout file descriptors for both programs independently.
</p>
<p>
<small>Copyright: Gerhard Rieger 2009</small><br>
<small>License: <a href="http://www.fsf.org/licensing/licenses/fdl.html">GNU Free Documentation License (FDL)</a></small>
</p>
</body>
</html>