
about
-----

socat is a relay for bidirectional data transfer between two independent data
channels. Each of these data channels may be a file, pipe, device (serial line
etc. or a pseudo terminal), a socket (UNIX, IP4, IP6 - raw, UDP, TCP), an
SSL socket, proxy CONNECT connection, a file descriptor (stdin etc.), the GNU
line editor, a program, or a combination of two of these. 
These modes include generation of "listening" sockets, pipes and pseudo
terminals.

socat can be used, e.g., as TCP port forwarder (one-shot or daemon), as an
external socksifier, for attacking weak firewalls, as a shell interface to UNIX
sockets, IP6 relay, for redirecting TCP oriented programs to a serial line, to
logically connect serial lines on different computers, or to establish a
relatively secure environment (su and  chroot) for running client or server
shell scripts with network connections. 

Many options are available to refine socats behaviour:
terminal parameters, open() options, file permissions, file and process owners,
basic socket options like bind address, advanced socket options like IP source
routing, linger, TTL, TOS (type of service), or TCP performance tuning.

More capabilities, like daemon mode with forking, client address check,
"tail -f" mode, some stream data processing (line terminator conversion),
choosing sockets, pipes, or ptys for interprocess communication, debug and
trace options, logging to syslog, stderr or file, and last but not least
precise error messages make it a versatile tool for many different purposes.

In fact, many of these features already exist in specialized tools; but until
now, there does not seem to exists another tool that provides such a generic,
flexible, simple and almost comprehensive (UNIX) byte stream connector.


packages
--------

before bothering with compilers, dependencies and include files, you might
try to get a binary distribution that matches your platform. Have a look at 
the projects home page for actual information regarding socat binary 
distributions.

Binary packages with socat version 1.2 have been available for:

RedHat Linux 7.2 / i386
SuSE Linux 7.3 /i386
FreeBSD 4.6
Debian Linux (unstable)
OpenPKG
Zaurus


platforms
---------

socat 1.3 was compiled and tested under the following operating systems:
SuSE Linux 7.3 on i386 with kernel 2.4.10
AIX 5.1 on PPC with gcc 2.9
SunOS 5.8 on sparc with gcc 2.95.3
FreeBSD 4.7
MacOS X 10.1 on PPC

Some versions of socat have been reported to successfully compile under older
Linux versions back to RedHat 2.1 (kernel 1.2.13, gcc 2.7.0), under AIX 4.1 
and 4.3, SunOS 5.7, FreeBSD 4.2 - 4.6, Cygwin, OpenBSD, and Solaris 8 on x86.

It might well compile and run under other UN*X like operating systems.


install
-------

Get the tarball and extract it:
	gtar xzvf socat.tar.gz
	cd socat-1.3
	./configure
	make depend
	make
	su
	make install	# installs socat, filan, and procan in /usr/local/bin

For compiling  socat, gcc (or egc) is recommended.
If gcc is not available, the configure script will fail to determine
some features; then you'd better begin with one of the Makefiles and config.h's
from the Config directory.

If you have problems with the OpenSSL library, you can apply the option
"--disable-openssl" to configure.

If you have problems with the readline library or (n)curses, you can apply the
option "--disable-readline" to configure.

If you still get errors or a tremendous amount of warnings you can exclude 
the features for system call tracing and file descriptor analyzing by
applying the options "--disable-sycls --disable-filan" to configure.

You still need the functions vsnprintf and snprintf.

For other operating system, if socat
does not compile without errors, refer to the file PORTING.


platform specifics - solaris
----------------------------

If you have libreadline or libssl in a directory not usually searched by the
loader, 
e.g. /opt/sfw/lib, you must add this directory to $LD_LIBRARY_PATH, at least
for running configure and the socat executables, e.g.:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/sfw/lib:/usr/local/ssl/lib
For some shell scripts, it is preferable to have /usr/xpg4/bin at a prominent
position in $PATH.


documentation
-------------

socat.1 is the man page, socat.html is the HTML based man page. It is actual,
but describes only the more useful options.

xio.help is an older, but more comprehensive description in text form; some
details are outdated, but it describes all address options.


license
-------

socat is distributed under the terms of the GNU GPL;
except for install-sh, which is copyright MIT, with its own license;

In addition, as a special exception, the copyright holder
gives permission to link the code of this program with
any version of the OpenSSL library which is distributed
under a license identical to that listed in the included
COPYING.OpenSSL file, and distribute linked combinations
including the two. You must obey the GNU General Public
License in all respects for all of the code used other
than OpenSSL. If you modify this file, you may extend this
exception to your version of the file, but you are not
obligated to do so. If you do not wish to do so, delete
this exception statement from your version.


    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, version 2 of the License

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


contact
-------

For questions, bug reports, ideas, contributions etc. please contact
socat@dest-unreach.org

For socat source distribution, bug fixes, and latest news see
        http://www.dest-unreach.org/socat/
