Socat is a command line based utility that establishes two bidirectional byte
streams and transfers data between them. Because the streams can be constructed
from a large set of different types of data sinks and sources
(see address types), and because lots of
address options may be applied to the streams, socat can
be used for many different purposes.
It might be one of the tools that one `has already needed'.
Filan is a utility that prints information about its active file
descriptors to stdout. It has been written for debugging socat, but might be
useful for other purposes too. Use the -h option to find more infos.
Procan is a utility that prints information about process parameters to
stdout. It has been written to better understand
some UNIX process properties and for debugging socat, but might be
useful for other purposes too.
The life cycle of a socat instance typically consists of four phases.
In the init phase, the command line options are parsed and logging is
initialized.
During the open phase, socat opens the first address and afterwards the
second address. These steps are usually blocking; thus, for complex address types like socks,
connection requests or authentication dialogs must be completed before the next
step is started.
In the transfer phase, socat watches both streams' read and write file
descriptors via select(), and, when data is available on one side and
can be written to the other side, socat reads it, performs newline
character conversions if required, and writes the data to the write file
descriptor of the other stream, then continues waiting for more data in both
directions.
When one of the streams effectively reaches EOF, the closing phase
begins. Socat transfers the EOF condition to the other stream,
i.e. tries to shutdown only its write stream, thus giving it a chance to
terminate gracefully. For a defined time, socat continues to transfer data in
the other directionϚ)cK|7nӃ@2):}taFt;G xaP*趎O>P~# /klgeQ~V~wHV =\=|XDfS% -O$!>lsx .fB< M .:~ JznvX&"_ْ] MSpsMm}7nu+ _fk ck04;O#lzحp A2n>8쪍()Ee+oѨDghVi Z
&Vu
\\_|,? y qDny61RYv$68VkL :D AwxoYe^Xr.\][O;]M㣆<*vluzu}}]c+ :ryYj n:~1 hRk?}-$-MC玸γ;bs#iEM QfAܾN4=p:;#ߨrԭVрF
xѓt ^ pG; M wJSz &Kuݴne.}l2^,;pmb8,DP[Elɽ0BrGjLN%7bm+m@j}]_F w7;E=Q\XCw|@ܧԭ& ՝7i"N|SϦ]ƛ(^)}ɽJ)')8:tpD+HBKHY v~\C="5HپS /_6l\b|xR٪ 3י
D]r Hjٻ _߆qۛ1ϻ67J*T_BIDOV6 ./usr/share/doc/socat/FAQ 0000644 0000000 0000000 00000006571 10065406436 014051 0 ustar root root
Q: What is the clue of socat?
A: socat probably doesn't have any clue. It is more an attempt to smoothly
integrate similar I/O features that are usually handled differently under
UNIX.
Q: What does the prefix XIO mean?
A: XIO means "extended input/output". It is a library/API that provides a
common way for handling files, sockets and other forms of I/O. Its advantage is
that the application may reduce its I/O to open / read+write / close calls,
while the user controls all I/O details (and even basic process properties) by
packing options into the filename string. This is the basic part of socat.
Q: Is there a Windows port of socat available?
A: Try with Cygwin from http://www.cygwin.com/, or upgrade to Linux.
Q: I succeeded to configure and make socat, but ./test.sh says something
like:
./test.sh: No such file or directory
A: You need a bash shell, and its location must be correctly specified in the
first line of test.sh, e.g. /usr/local/bin/bash instead of /bin/bash.
Q: configure disables readline / openssl / libwrap support because it does not
find an include file / the library. How can I tell configure where these files
are?
A: For include locations, use the environment variable CPPFLAGS, for library
locations use LIBS, e.g.:
export CPPFLAGS="-I/home/user/ssl/include"
export LIBS="-L/home/user/ssl/lib"
On some systems (SunOS), you might also need to set LD_LIBRARY_PATH:
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/home/user/ssl/lib"
Then try again:
make distclean; ./configure; make
Q: I succeeded to make socat, but the test.sh script fails for many tests.
Is my socat build corrupt?
A: Probably your socat program is ok; the tests have been developed on Linux
2.4, and there they usually succeed.
But the following OS differences result in errors on non Linux systems:
* Linux allows to bind a socket to any address of range 127.0.0.0/8, not
only 127.0.0.1. Some tests are built on this feature, but they might fail on
other systems.
* Your OS might have no IP6 implementation
* MacOS X has some difficulties, e.g. distinguishing sockets and pipes.
* the OpenSSL tests require OpenSSL support by socat, must have openssl in
$PATH, and "openssl s_server ..." needs enough entropy to generate a key.
Q: When I specify a dual address (two partial addresses linked with "!!") on
the command line, I get some message "event not found", and my shell history
has the line truncated. Not even protecting the '!'s with '\' helps.
A: '!' is appearently used by your shell as history expansion character. Say
"set +H" and add this line to your (bash) profile.
Q: On Solaris, socat was built successfully, but when started, it gets killed
with something like "ld.so.1: ./socat: fatal: libreadline.so.4: open failed: no
such file or directory"
A: The configure script finds your libreadline, but the runtime loader
doesn't. Add the directory where the library resides to your LD_LIBRARY_PATH
variable, e.g.:
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/sfw/lib/
make distclean; ./configure; make
Q: On Solaris, socat was built successfully, but when started, an assertion
fails: "xioinitialize.c:25: failed assertion `3 << opt_crdly.arg3 == CRDLY'
A: Probably, in a second attempt you set the correct LD_LIBARY_PATH for socat,
but it had not been set during the ./configure run, or you did not "make clean"
before running configure. Try it again:
make distclean; ./configure; make
./usr/share/doc/socat/PORTING 0000644 0000000 0000000 00000006027 07703051070 014553 0 ustar root root
DEVELOPMENT PLATFORMS
Primary development platform for socat is currently SuSE Linux 8.2 with
a 2.4.20 kernel. New features are then ported to the non-Linux platforms on the
Sourceforge compile farm (per July 2003: SunOS 5.8 with gcc, and MacOS X 10.2),
and AIX 5.1 with gcc. But due to limited time resources and restricted
(non-root) access to these systems I cannot extensively test socat there.
PORTING STEPS
If you want to port socat to another operating system you will typically go
through two phases: First, you might just try to compile and run the actual
socat distribution (passive phase). Then, you should see if your platform
has some nice features that are not yet used in socat, and add code for
supporting them (active phase). At last, I encourage you to send me your
changes so I can integrate them into the main socat distribution.
PASSIVE PHASE:
* Generate Makefile and config.h:
. If you have gcc, then just invoke "./configure".
. If you use another C compiler, configure might not work properly;
You will have to adapt config.h and Makefile manually.
Change compiler options or defines to use all features of the operating
system (not only ANSI-C; e.g. HP-UX: -Ae!)
Some practical config..h examples have been included in the
Config directory of the source that might serve as starting point.
* Try to "make" socat; correct the errors. If some constants are undefined,
please disable these parts option-dependent, not platform-dependent (use
#ifdef TCP_OPTION instead of #if MY_OS)
* If you have big troubles compiling socat then try configure with options
--disable-filan --disable-sycls; this excludes some of the most system
dependent parts.
* After successful compilation and linking, run "make test" and try some
examples.
ACTIVE PHASE:
* Check the man pages of your operating system for open(2), fcntl(2),
setsockopt(2), ioctl(2), socket(7), ip(7), tcp(7), termios etc. and the
include files where you find the definitions of existing options, for new
options and implement them - again option-dependent.
Places to add code for the new options:
. xioopts.h: enum e_optcode (sorted numerically/alphabetically by name)
. xio-*.c: select the appropriate address file (e.g., xio-tcp.c for
TCP-options) and make a record of type struct optdesc: opt_newoption
. xio-*.h: the declation of struct optdesc
. xioopts.c: add records to struct optname optionnames for all appropriate
names (sorted strictly ASCII for binary search)
. filan.c: add the option to the appropriate array (sockopts, ipopts,
tcpopts)
. socat.html, socat.1, xio.help: write a short documentation and tell which
platform and version implements this option
* problems may occur especially:
. with 16 or 64 bit systems
. if snprintf() etc. is missing
. on UNIX emulations, e.g. Cygwin
INTEGRATION
* If you ported socat to another platform:
To let other people participate please send the modified files or a patch
file and the files generated by ./gatherinfo.sh to socat@dest-unreach.org.
./usr/share/doc/socat/SECURITY 0000644 0000000 0000000 00000003471 07546750417 014720 0 ustar root root
Tips for using socat in secured environments:
* Configure socat to only enable the required features, e.g. to protect your
filesystem from any accesses through socat:
make distclean
./configure --disable-file --disable-creat --disable-gopen \
--disable-pipe --disable-unix --disable-exec --disable-system
use "socat -V" to see what features are still enabled; see
./configure --help for more options to disable
* Do NOT install socat SUID root or so when you have untrusted users or
unprivileged daemons on your machine, because the full install of socat can
override arbitrary files and execute arbitrary programs!
* Set logging to "-d -d" (in special cases even higher)
* With files, protect against symlink attacks with nofollow (Linux), and
avoid accessing files in world-writable directories like /tmp
* When listening, use bind option (except UNIX domain sockets)
* When listening, use range option (currently only for IP4 sockets)
* When using socat with system, exec, or in a shell script, know what you do
* With system and exec, use absolute pathes or set the path option
* When starting programs with socat, consider using the chroot option (this
requires root, so use the substuser option too).
* Start socat as root only if required; if so, use substuser option
Note: starting a SUID program after applying substuser or setuid gives the
process the SUID owner, which might give root privileges again.
* Socat, like netcat, is what intruders like to have on their victims machine:
once they have gained a toehold they try to establish a versatile connection
back to their attack base, and they want to attack other systems. For both
purposes, socat could be helpful. Therefore, it might be useful to install
socat with owner/permissions root:socatgrp/750, and to make all trusted users
members of group socatgrp.
./usr/share/doc/socat/socat.html 0000644 0000000 0000000 00000410644 10310615646 015514 0 ustar root root
socat
Socat is a command line based utility that establishes two bidirectional byte
streams and transfers data between them. Because the streams can be constructed
from a large set of different types of data sinks and sources
(see address types), and because lots of
address options may be applied to the streams, socat can
be used for many different purposes.
It might be one of the tools that one `has already needed'.
Filan is a utility that prints information about its active file
descriptors to stdout. It has been written for debugging socat, but might be
useful for other purposes too. Use the -h option to find more infos.
Procan is a utility that prints information about process parameters to
stdout. It has been written to better understand
some UNIX process properties and for debugging socat, but might be
useful for other purposes too.
The life cycle of a socat instance typically consists of four phases.
In the init phase, the command line options are parsed and logging is
initialized.
During the open phase, socat opens the first address and afterwards the
second address. These steps are usually blocking; thus, for complex address types like socks,
connection requests or authentication dialogs must be completed before the next
step is started.
In the transfer phase, socat watches both streams' read and write file
descriptors via select(), and, when data is available on one side and
can be written to the other side, socat reads it, performs newline
character conversions if required, and writes the data to the write file
descriptor of the other stream, then continues waiting for more data in both
directions.
When one of the streams effectively reaches EOF, the closing phase
begins. Socat transfers the EOF condition to the other stream,
i.e. tries to shutdown only its write stream, thus giving it a chance to
terminate gracefully. For a defined time, socat continues to transfer data in
the other directionϚ)cK|7nӃ@2):}taFt;G xaP*趎O>P~# /klgeQ~V~wHV =\=|XDfS% -O$!>lsx .fB< M .:~ JznvX&"_ْ] MSpsMm}7nu+ _fk ck04;O#lzحp A2n>8쪍()Ee+oѨDghVi Z
&Vu
\\_|,? y qDny61RYv$68VkL :D AwxoYe^Xr.\][O;]M㣆<*vluzu}}]c+ :ryYj n:~1 hRk?}-$-MC玸γ;bs#iEM QfAܾN4=p:;#ߨrԭVрF
xѓt ^ pG; M wJSz &Kuݴne.}l2^,;pmb8,DP[Elɽ0BrGjLN%7bm+m@j}]_F w7;E=Q\XCw|@ܧԭ& ՝7i"N|SϦ]ƛ(^)}ɽJ)')8:tpD+HBKHY v~\C="5HپS /_6l\b|xR٪ 3י
D]r Hjٻ _߆qۛ1ϻ67J*T_BIDOV6 ./usr/share/doc/socat/FAQ 0000644 0000000 0000000 00000006571 10065406436 014051 0 ustar root root
Q: What is the clue of socat?
A: socat probably doesn't have any clue. It is more an attempt to smoothly
integrate similar I/O features that are usually handled differently under
UNIX.
Q: What does the prefix XIO mean?
A: XIO means "extended input/output". It is a library/API that provides a
common way for handling files, sockets and other forms of I/O. Its advantage is
that the application may reduce its I/O to open / read+write / close calls,
while the user controls all I/O details (and even basic process properties) by
packing options into the filename string. This is the basic part of socat.
Q: Is there a Windows port of socat available?
A: Try with Cygwin from http://www.cygwin.com/, or upgrade to Linux.
Q: I succeeded to configure and make socat, but ./test.sh says something
like:
./test.sh: No such file or directory
A: You need a bash shell, and its location must be correctly specified in the
first line of test.sh, e.g. /usr/local/bin/bash instead of /bin/bash.
Q: configure disables readline / openssl / libwrap support because it does not
find an include file / the library. How can I tell configure where these files
are?
A: For include locations, use the environment variable CPPFLAGS, for library
locations use LIBS, e.g.:
export CPPFLAGS="-I/home/user/ssl/include"
export LIBS="-L/home/user/ssl/lib"
On some systems (SunOS), you might also need to set LD_LIBRARY_PATH:
export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:/home/user/ssl/lib"
Then try again:
make distclean; ./configure; make
Q: I succeeded to make socat, but the test.sh script fails for many tests.
Is my socat build corrupt?
A: Probably your socat program is ok; the tests have been developed on Linux
2.4, and there they usually succeed.
But the following OS differences result in errors on non Linux systems:
* Linux allows to bind a socket to any address of range 127.0.0.0/8, not
only 127.0.0.1. Some tests are built on this feature, but they might fail on
other systems.
* Your OS might have no IP6 implementation
* MacOS X has some difficulties, e.g. distinguishing sockets and pipes.
* the OpenSSL tests require OpenSSL support by socat, must have openssl in
$PATH, and "openssl s_server ..." needs enough entropy to generate a key.
Q: When I specify a dual address (two partial addresses linked with "!!") on
the command line, I get some message "event not found", and my shell history
has the line truncated. Not even protecting the '!'s with '\' helps.
A: '!' is appearently used by your shell as history expansion character. Say
"set +H" and add this line to your (bash) profile.
Q: On Solaris, socat was built successfully, but when started, it gets killed
with something like "ld.so.1: ./socat: fatal: libreadline.so.4: open failed: no
such file or directory"
A: The configure script finds your libreadline, but the runtime loader
doesn't. Add the directory where the library resides to your LD_LIBRARY_PATH
variable, e.g.:
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/sfw/lib/
make distclean; ./configure; make
Q: On Solaris, socat was built successfully, but when started, an assertion
fails: "xioinitialize.c:25: failed assertion `3 << opt_crdly.arg3 == CRDLY'
A: Probably, in a second attempt you set the correct LD_LIBARY_PATH for socat,
but it had not been set during the ./configure run, or you did not "make clean"
before running configure. Try it again:
make distclean; ./configure; make
./usr/share/doc/socat/PORTING 0000644 0000000 0000000 00000006027 07703051070 014553 0 ustar root root
DEVELOPMENT PLATFORMS
Primary development platform for socat is currently SuSE Linux 8.2 with
a 2.4.20 kernel. New features are then ported to the non-Linux platforms on the
Sourceforge compile farm (per July 2003: SunOS 5.8 with gcc, and MacOS X 10.2),
and AIX 5.1 with gcc. But due to limited time resources and restricted
(non-root) access to these systems I cannot extensively test socat there.
PORTING STEPS
If you want to port socat to another operating system you will typically go
through two phases: First, you might just try to compile and run the actual
socat distribution (passive phase). Then, you should see if your platform
has some nice features that are not yet used in socat, and add code for
supporting them (active phase). At last, I encourage you to send me your
changes so I can integrate them into the main socat distribution.
PASSIVE PHASE:
* Generate Makefile and config.h:
. If you have gcc, then just invoke "./configure".
. If you use another C compiler, configure might not work properly;
You will have to adapt config.h and Makefile manually.
Change compiler options or defines to use all features of the operating
system (not only ANSI-C; e.g. HP-UX: -Ae!)
Some practical config..h examples have been included in the
Config directory of the source that might serve as starting point.
* Try to "make" socat; correct the errors. If some constants are undefined,
please disable these parts option-dependent, not platform-dependent (use
#ifdef TCP_OPTION instead of #if MY_OS)
* If you have big troubles compiling socat then try configure with options
--disable-filan --disable-sycls; this excludes some of the most system
dependent parts.
* After successful compilation and linking, run "make test" and try some
examples.
ACTIVE PHASE:
* Check the man pages of your operating system for open(2), fcntl(2),
setsockopt(2), ioctl(2), socket(7), ip(7), tcp(7), termios etc. and the
include files where you find the definitions of existing options, for new
options and implement them - again option-dependent.
Places to add code for the new options:
. xioopts.h: enum e_optcode (sorted numerically/alphabetically by name)
. xio-*.c: select the appropriate address file (e.g., xio-tcp.c for
TCP-options) and make a record of type struct optdesc: opt_newoption
. xio-*.h: the declation of struct optdesc
. xioopts.c: add records to struct optname optionnames for all appropriate
names (sorted strictly ASCII for binary search)
. filan.c: add the