mirror of
https://repo.or.cz/socat.git
synced 2024-12-23 15:52:33 +00:00
115 lines
5.2 KiB
HTML
115 lines
5.2 KiB
HTML
|
<!-- 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>
|