doc/socat-exec.html - socat - Git at Google

 <!-- 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>
	<!-- 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>