Socat is a utility similar to the venerable Netcat that works over a number of protocols and through a files, pipes, devices (terminal or modem, etc.), sockets (Unix, IP4, IP6 - raw, UDP, TCP), a client for SOCKS4, proxy CONNECT, or SSL, etc. It provides forking, logging, and dumping, different modes for interprocess communication, and many more options. It can be used, for example, as a TCP relay (one-shot or daemon), as a daemon-based socksifier, as a shell interface to Unix sockets, as an IP6 relay, for redirecting TCP-oriented programs to a serial line, or to establish a relatively secure environment (su and chroot) for running client or server shell scripts with network connections.
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.
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, especially 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 andcan 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, giving it a chance to terminate gracefully. For a defined time socat continues to transfer data in the other direction, but then closes all remaining channels and terminates.
OPTIONS
Socat provides some command line options that modify the behaviour of the program. They have nothing to do with so called address options that are used as parts of address specifications.
-V- Print version and available feature information to stdout, and exit.
-h | -?- Print a help text to stdout describing command line options and available address types, and exit.
-hh | -??- Like -h, plus a list of the short names of all available address options. Some options are platform dependend, so this output is helpful for checking the particular implementation.
-hhh | -???- Like -hh, plus a list of all available address option names.
-d- Without this option, only fatal and error messages are generated; applying this option also prints warning messages. See DIAGNOSTICS for more information.
-d -d- Prints fatal, error, warning, and notice messages.
-d -d -d- Prints fatal, error, warning, notice, and info messages.
-d -d -d -d- Prints fatal, error, warning, notice, info, and debug messages.
-D- Logs information about file descriptors before starting the transfer phase.
-ly[<facility>]- Writes messages to syslog instead of stderr; severity as defined with -d option. With optional <facility>, the syslog type can be selected, default is "daemon". Third party libraries might not obey this option.
-lf<logfile>- Writes messages to <logfile> [filename] instead of stderr. Some third party libraries, in particular libwrap, might not obey this option.
-ls- Writes messages to stderr (this is the default). Some third party libraries might not obey this option, in particular libwrap appears to only log to syslog.
-lp<progname>- Overrides the program name printed in error messages and used for constructing environment variable names.
-lu- Extends the timestamp of error messages to microsecond resolution. Does not work when logging to syslog.
-lm[<facility>]- Mixed log mode. During startup messages are printed to stderr; when socat starts the transfer phase loop or daemon mode (i.e. after opening all streams and before starting data transfer, or, with listening sockets with fork option, before the first accept call), it switches logging to syslog. With optional <facility>, the syslog type can be selected, default is "daemon".
-lh- Adds hostname to log messages. Uses the value from environment variable HOSTNAME or the value retrieved with
uname()if HOSTNAME is not set. -v- Writes the transferred data not only to their target streams, but also to stderr. The output format is text with some conversions for readability, and prefixed with "> " or "< " indicating flow directions.
-x- Writes the transferred data not only to their target streams, but also to stderr. The output format is hexadecimal, prefixed with "> " or "< " indicating flow directions. Can be combined with
-v. -b<size>- Sets the data transfer block <size> [size_t]. At most <size> bytes are transferred per step. Default is 8192 bytes.
-s- By default, socat terminates when an error occurred to prevent the process from running when some option could not be applied. With this option, socat is sloppy with errors and tries to continue. Even with this option, socat will exit on fatals, and will abort connection attempts when security checks failed.
-t<timeout>- When one channel has reached EOF, the write part of the other channel is shut down. Then, socat waits <timeout> [timeval] seconds before terminating. Default is 0.5 seconds. This timeout only applies to addresses where write and read part can be closed independently. When during the timeout interval the read part gives EOF, socat terminates without awaiting the timeout.
-T<timeout>- Total inactivity timeout: when socat is already in the transfer loop and nothing has happened for <timeout> [timeval] seconds (no data arrived, no interrupt occurred...) then it terminates. Useful with protocols like UDP that cannot transfer EOF.
-u- Uses unidirectional mode. The first address is only used for reading, and the second address is only used for writing (example).
-U- Uses unidirectional mode in reverse direction. The first address is only used for writing, and the second address is only used for reading.
-g- During address option parsing, don't check if the option is considered useful in the given address environment. Use it if you want to force, e.g., appliance of a socket option to a serial device.
-L<lockfile>- If lockfile exists, exits with error. If lockfile does not exist, creates it and continues, unlinks lockfile on exit.
-W<lockfile>- If lockfile exists, waits until it disappears. When lockfile does not exist, creates it and continues, unlinks lockfile on exit.
-4- Use IP version 4 in case that the addresses do not implicitly or explicitly specify a version; this is the default.
-6- Use IP version 6 in case that the addresses do not implicitly or explicitly specify a version.
