From 2b3afcf425ca1d5b569b82caa1a3898a359d2ebb Mon Sep 17 00:00:00 2001 From: Gerhard Rieger Date: Mon, 28 Jan 2008 20:33:15 +0100 Subject: [PATCH] derive doc from doc/socat.yo --- CHANGES | 3 + Makefile.in | 13 +- README | 12 + doc/socat.1 | 2877 ------------------------------------------------ doc/socat.html | 2686 -------------------------------------------- 5 files changed, 27 insertions(+), 5564 deletions(-) delete mode 100644 doc/socat.1 delete mode 100644 doc/socat.html diff --git a/CHANGES b/CHANGES index 8148136..0234aa0 100644 --- a/CHANGES +++ b/CHANGES @@ -1,4 +1,7 @@ +new features: + docu source doc/socat.yo released + ####################### V 1.6.0.0: new features: diff --git a/Makefile.in b/Makefile.in index 4d76144..f847b35 100644 --- a/Makefile.in +++ b/Makefile.in @@ -81,7 +81,18 @@ OSFILES = Config/Makefile.Linux-2-6-16 Config/config.Linux-2-6-16.h \ Config/Makefile.Tru64-5-1B Config/config.Tru64-5-1B.h -all: progs +all: progs doc + +doc: doc/socat.1 doc/socat.html + +docclean: + rm -f doc/socat.1 doc/socat.html + +doc/socat.1: doc/socat.yo + yodl2man -o $@ $+ + +doc/socat.html: doc/socat.yo + yodl2html -o $@ $+ progs: $(PROGS) diff --git a/README b/README index a30bf66..76faf12 100644 --- a/README +++ b/README @@ -225,6 +225,18 @@ doc/socat-multicast.html is a short tutorial for multicast and broadcast communications. doc/socat-tun shows how to build a virtual network between two hosts. +socat.1 and socat.html can be generated from socat.yo (which is released with +socat 1.6.1 and later) using the yodl document language package. Maintenance +of yodl had been discontinued by its author +(http://www.xs4all.nl/~jantien/yodl/) (there seems to be a revival at +http://yodl.sourceforge.net/ though). For socat, the old version 1.31 is used; +an rpm is still distributed with recent OpenSuSE versions (confirmed for +OpenSuSE 10.1 in suse/i586/yodl-1.31.18-1142.i586.rpm). It appears to install +smoothly also under RedHat Linux. After yodl 1.31 installation, the following +correction must be performed in /usr/share/yodl/shared.yo in two places: +< whenhtml(htmlcommand())) +> whenhtml(htmlcommand())) + license ------- diff --git a/doc/socat.1 b/doc/socat.1 deleted file mode 100644 index 3be5004..0000000 --- a/doc/socat.1 +++ /dev/null @@ -1,2877 +0,0 @@ -.TH "socat" "1" "March 2007" "socat" "" -.PP -.PP -.SH "NAME" -socat \- Multipurpose relay (SOcket CAT) -.PP -.SH "SYNOPSIS" -\f(CWsocat [options]
\fP -.br -\f(CWsocat -V\fP -.br -\f(CWsocat -h[h[h]] | -?[?[?]]\fP -.br -\f(CWfilan\fP -.br -\f(CWprocan\fP -.PP -.SH "DESCRIPTION" -.PP -\fBSocat\fP 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\'\&. -.PP -\fBFilan\fP is a utility that prints information about its active file -descriptors to stdout\&. It has been written for debugging \fBsocat\fP, but might be -useful for other purposes too\&. Use the -h option to find more infos\&. -.PP -\fBProcan\fP 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 \fBsocat\fP, but might be -useful for other purposes too\&. -.PP -The life cycle of a \fBsocat\fP instance typically consists of four phases\&. -.PP -In the \fIinit\fP phase, the command line options are parsed and logging is -initialized\&. -.PP -During the \fIopen\fP phase, \fBsocat\fP 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\&. -.PP -In the \fItransfer\fP phase, \fBsocat\fP watches both streams\' read and write file -descriptors via \f(CWselect()\fP, and, when data is available on one side \fIand\fP -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\&. -.PP -When one of the streams effectively reaches EOF, the \fIclosing\fP phase -begins\&. \fBSocat\fP 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 \fBsocat\fP continues to transfer data in -the other direction, but then closes all remaining channels and terminates\&. -.PP -.SH "OPTIONS" -.PP -\fBSocat\fP 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\&. -.PP -.IP "\fB\f(CW-V\fP\fP" -Print version and available feature information to stdout, and exit\&. -.IP "\fB\f(CW-h | -?\fP\fP" -Print a help text to stdout describing command line options and available address -types, and exit\&. -.IP "\fB\f(CW-hh | -??\fP\fP" -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\&. -.IP "\fB\f(CW-hhh | -???\fP\fP" -Like -hh, plus a list of all available address option names\&. -.IP "\fB\f(CW-d\fP\fP" -Without this option, only fatal and error messages are generated; applying -this option also prints warning messages\&. See DIAGNOSTICS -for more information\&. -.IP "\fB\f(CW-d -d\fP\fP" -Prints fatal, error, warning, and notice messages\&. -.IP "\fB\f(CW-d -d -d\fP\fP" -Prints fatal, error, warning, notice, and info messages\&. -.IP "\fB\f(CW-d -d -d -d\fP\fP" -Prints fatal, error, warning, notice, info, and debug -messages\&. -.IP "\fB\f(CW-D\fP\fP" -Logs information about file descriptors before starting the transfer phase\&. -.IP "\fB\f(CW-ly[]\fP\fP" -Writes messages to syslog instead of stderr; severity as defined with -d -option\&. With optional , the syslog type can -be selected, default is "daemon"\&. -.IP "\fB\f(CW-lf\fP\fP\f(CW \fP" -Writes messages to [filename] instead of -stderr\&. -.IP "\fB\f(CW-ls\fP\fP" -Writes messages to stderr (this is the default)\&. -.IP "\fB\f(CW-lp\fP\fP\f(CW\fP" -Overrides the program name printed in error messages\&. -.IP "\fB\f(CW-lu\fP\fP" -Extends the timestamp of error messages to microsecond resolution\&. Does not -work when logging to syslog\&. -.IP "\fB\f(CW-lm[]\fP\fP" -Mixed log mode\&. During startup messages are printed to stderr; when \fBsocat\fP -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 , the syslog type can be -selected, default is "daemon"\&. -.IP "\fB\f(CW-lh\fP\fP" -Adds hostname to log messages\&. Uses the value from environment variable -HOSTNAME or the value retrieved with \f(CWuname()\fP if HOSTNAME is not set\&. -.IP "\fB\f(CW-v\fP\fP" -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\&. -.IP "\fB\f(CW-x\fP\fP" -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 \f(CW-v\fP\&. -.IP "\fB\f(CW-b\fP\fP\f(CW\fP" -Sets the data transfer block [size_t]\&. -At most bytes are transferred per step\&. Default is 8192 bytes\&. -.IP "\fB\f(CW-s\fP\fP" -By default, \fBsocat\fP terminates when an error occurred to prevent the process -from running when some option could not be applied\&. With this -option, \fBsocat\fP 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\&. -.IP "\fB\f(CW-t\fP\fP\f(CW\fP" -When one channel has reached EOF, the write part of the other channel is shut -down\&. Then, \fBsocat\fP waits [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 intervall the read part gives EOF, socat terminates without -awaiting the timeout\&. -.IP "\fB\f(CW-T\fP\fP\f(CW\fP" -Total inactivity timeout: when socat is already in the transfer loop and -nothing has happened for [timeval] seconds -(no data arrived, no interrupt occurred\&.\&.\&.) then it terminates\&. -Useful with protocols like UDP that cannot transfer EOF\&. -.IP "\fB\f(CW-u\fP\fP" -Uses unidirectional mode\&. The first address is only used for reading, and the -second address is only used for writing (example)\&. -.IP "\fB\f(CW-U\fP\fP" -Uses unidirectional mode in reverse direction\&. The first address is only -used for writing, and the second address is only used for reading\&. -.IP "\fB\f(CW-g\fP\fP" -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\&. -.IP "\fB\f(CW-L\fP\fP\f(CW\fP" -If lockfile exists, exits with error\&. If lockfile does not exist, creates it -and continues, unlinks lockfile on exit\&. -.IP "\fB\f(CW-W\fP\fP\f(CW\fP" -If lockfile exists, waits until it disappears\&. When lockfile does not exist, -creates it and continues, unlinks lockfile on exit\&. -.IP "\fB\f(CW-4\fP\fP" -Use IP version 4 in case that the addresses do not implicitly or explicitly -specify a version; this is the default\&. -.IP "\fB\f(CW-6\fP\fP" -Use IP version 6 in case that the addresses do not implicitly or explicitly -specify a version\&. -.PP -.SH "ADDRESS SPECIFICATIONS" -.PP -With the address command line arguments, the user gives \fBsocat\fP instructions and -the necessary information for establishing the byte streams\&. -.PP -An address specification usually consists of an address type -keyword, zero or more required address parameters separated by \':\' from the keyword and -from each -other, and zero or more address options separated by \',\'\&. -.PP -The keyword specifies the address type (e\&.g\&., TCP4, OPEN, EXEC)\&. For some -keywords there exist synonyms (\'-\' for STDIO, TCP for TCP4)\&. Keywords are case -insensitive\&. -For a few special address types, the keyword may be omitted: -Address specifications starting with a number are assumed to be FD (raw file -descriptor) addresses; -if a \'/\' is found before the first \':\' or \',\', GOPEN (generic file open) is -assumed\&. -.PP -The required number and type of address parameters depend on the address -type\&. E\&.g\&., TCP4 requires a server specification (name or address), and a port -specification (number or service name)\&. -.PP -Zero or more address options may be given with each address\&. They influence the -address in some ways\&. -Options consist of an option keyword or an option keyword and a value, -separated by \'=\'\&. Option keywords are case insensitive\&. -For filtering the options that are useful with an address -type, each option is member of one option group\&. For -each address type there is a set of option groups allowed\&. Only options -belonging to one of these address groups may be used (except with option -g)\&. -.PP -Address specifications following the above schema are also called \fIsingle\fP -address specifications\&. -Two single addresses can be combined with "!!" to form a \fIdual\fP type -address for one channel\&. Here, the first address is used by \fBsocat\fP for reading -data, and the -second address for writing data\&. There is no way to specify an option only once -for being applied to both single addresses\&. -.PP -Usually, addresses are opened in read/write -mode\&. When an address is part of a dual address specification, or when -option -u or -U is used, an address might be -used only for reading or for writing\&. Considering this is important with some -address types\&. -.PP -With socat version 1\&.5\&.0 and higher, the lexical analysis tries to handle -quotes and parenthesis meaningfully and allows escaping of special characters\&. -If one of the characters ( { [ \' is found, the corresponding closing -character - ) } ] \' - is looked for; they may also be nested\&. Within these -constructs, socats special characters and strings : , !! are not handled -specially\&. All those characters and strings can be escaped with \e or within "" -.PP -.SH "ADDRESS TYPES" -.PP -This section describes the available address types with their keywords, -parameters, and semantics\&. -.PP -.IP "\fB\f(CWCREATE:\fP\fP" -Opens with \f(CWcreat()\fP and uses the file -descriptor for writing\&. -This address type requires write-only context, because a file opened with -\f(CWcreat\fP cannot be read from\&. - must be a valid existing or not existing path\&. -If is a named pipe, \f(CWcreat()\fP might block; -if refers to a socket, this is an error\&. -.br -Option groups: FD,REG,NAMED -.br -Useful options: -mode, -user, -group, -unlink-early, -unlink-late, -append -.br -See also: OPEN, GOPEN -.IP "\fB\f(CWEXEC:\fP\fP" -Forks a sub process that establishes communication with its parent process -and invokes the specified program with \f(CWexecvp()\fP\&. - is a simple command -with arguments separated by single spaces\&. If the program name -contains a \'/\', the part after the last \'/\' is taken as ARGV[0]\&. If the -program name is a relative -path, the \f(CWexecvp()\fP semantics for finding the program via -\f(CW$PATH\fP -apply\&. After successful program start, \fBsocat\fP writes data to stdin of the -process and reads from its stdout using a UNIX domain socket generated by -\f(CWsocketpair()\fP per default\&. (example) -.br -Option groups: FD,SOCKET,EXEC,FORK,TERMIOS -.br -Useful options: -path, -fdin, -fdout, -chroot, -su, -su-d, -nofork, -pty, -stderr, -ctty, -setsid, -pipes, -login, -sigint, -sigquit -.br -See also: SYSTEM -.IP "\fB\f(CWFD:\fP\fP" -Uses the file descriptor \&. It must already exist as -valid UN*X file descriptor\&. -.br -Option groups: FD (TERMIOS,REG,SOCKET) -.br -See also: -STDIO, -STDIN, -STDOUT, -STDERR -.IP "\fB\f(CWGOPEN:\fP\fP" -(Generic open) This address type tries to handle any file system entry -except directories usefully\&. may be a -relative or absolute path\&. If it already exists, its type is checked\&. -In case of a UNIX domain socket, \fBsocat\fP connects; if connecting fails, -\fBsocat\fP assumes a datagram socket and uses \f(CWsendto()\fP calls\&. -If the entry is not a socket, \fBsocat\fP opens it applying the \f(CWO_APPEND\fP -flag\&. -If it does not exist, it is opened with flag -\f(CWO_CREAT\fP as a regular file (example)\&. -.br -Option groups: FD,REG,SOCKET,NAMED,OPEN -.br -See also: -OPEN, -CREATE, -UNIX-CONNECT -.IP -.IP "\fB\f(CWIP-SENDTO::\fP\fP" -Opens a raw IP socket\&. Depending on host specification or option pf, IP procotol version -4 or 6 is used\&. It uses to send packets -to [IP address] and receives packets from -host, ignores packets from other hosts\&. -Protocol 255 uses the raw socket with the IP header being part of the -data\&. -.br -Option groups: FD,SOCKET,IP4,IP6 -.br -Useful options: -pf, -ttl -See also: -IP4-SENDTO, -IP6-SENDTO, -IP-RECVFROM, -IP-RECV, -UDP-SENDTO -UNIX-SENDTO -.IP "\fB\f(CWIP4-SENDTO::\fP\fP" -Like IP-SENDTO, but always uses IPv4\&. -.br -Option groups: FD,SOCKET,IP4 -.br -.IP "\fB\f(CWIP6-SENDTO::\fP\fP" -Like IP-SENDTO, but always uses IPv6\&. -.br -Option groups: FD,SOCKET,IP6 -.br -.IP -.IP "\fB\f(CWIP-DATAGRAM:
:\fP\fP" -Sends outgoing data to the specified address which may in particular be a -broadcast or multicast address\&. Packets arriving on the local socket are -checked if their source addresses match -eventual RANGE or TCPWRAP -options\&. This address type can for example be used for implementing -symmetric or asymmetric broadcast or multicast communications\&. -.br -Option groups: FD, SOCKET, -IP4, IP6, RANGE -.br -Useful options: -range, -tcpwrap, -broadcast, -ip-multicast-loop, -ip-multicast-ttl, -ip-multicast-if, -ip-add-membership, -ttl, -tos, -bind, -pf -.br -See also: -IP4-DATAGRAM, -IP6-DATAGRAM, -IP-SENDTO, -IP-RECVFROM, -IP-RECV, -UDP-DATAGRAM -.IP "\fB\f(CWIP4-DATAGRAM::\fP\fP" -Like IP-DATAGRAM, but always uses IPv4\&. -(example) -.br -Option groups: FD, SOCKET, -IP4, RANGE -.br -.IP "\fB\f(CWIP6-DATAGRAM::\fP\fP" -Like IP-DATAGRAM, but always uses IPv6\&. Please -note that IPv6 does not know broadcasts\&. -.br -Option groups: FD, SOCKET, -IP6, RANGE -.br -.IP -.IP "\fB\f(CWIP-RECVFROM:\fP\fP" -Opens a raw IP socket of \&. Depending on option pf, IP procotol version -4 or 6 is used\&. It receives one packet from an unspecified peer and may send one or more answer packets to that peer\&. -This mode is particularly useful with fork option where each arriving packet - from arbitrary peers - is handled by its own sub process\&. -This allows a behaviour similar to typical UDP based servers like ntpd or named\&. -This address works well with IP-SENDTO address peers (see above)\&. -Protocol 255 uses the raw socket with the IP header being part of the -data\&. -.br -Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE -.br -Useful options: -pf, -fork, -range, -ttl, -broadcast -.br -See also: -IP4-RECVFROM, -IP6-RECVFROM, -IP-SENDTO, -IP-RECV, -UDP-RECVFROM, -UNIX-RECVFROM -.IP "\fB\f(CWIP4-RECVFROM:\fP\fP" -Like IP-RECVFROM, but always uses IPv4\&. -.br -Option groups: FD,SOCKET,IP4,CHILD,RANGE -.br -.IP "\fB\f(CWIP6-RECVFROM:\fP\fP" -Like IP-RECVFROM, but always uses IPv6\&. -.br -Option groups: FD,SOCKET,IP6,CHILD,RANGE -.br -.IP -.IP "\fB\f(CWIP-RECV:\fP\fP" -Opens a raw IP socket of \&. Depending on option pf, IP procotol version -4 or 6 is used\&. It receives packets from multiple unspecified peers and merges the data\&. -No replies are possible\&. -It can be, e\&.g\&., addressed by socat IP-SENDTO address peers\&. -Protocol 255 uses the raw socket with the IP header being part of the -data\&. -.br -Option groups: FD,SOCKET,IP4,IP6,RANGE -.br -Useful options: -pf, -range -.br -See also: -IP4-RECV, -IP6-RECV, -IP-SENDTO, -IP-RECVFROM, -UDP-RECV, -UNIX-RECV -.IP "\fB\f(CWIP4-RECV:\fP\fP" -Like IP-RECV, but always uses IPv4\&. -.br -Option groups: FD,SOCKET,IP4,RANGE -.br -.IP "\fB\f(CWIP6-RECV:\fP\fP" -Like IP-RECV, but always uses IPv6\&. -.br -Option groups: FD,SOCKET,IP6,RANGE -.br -.IP -.IP "\fB\f(CWOPEN:\fP\fP" -Opens using the \f(CWopen()\fP system call -(example)\&. -This operation fails on UNIX domain sockets\&. -.br -Note: This address type is rarly useful in bidirectional mode\&. -.br -Option groups: FD,REG,NAMED,OPEN -.br -Useful options: -creat, -excl, -noatime, -nofollow, -append, -rdonly, -wronly, -lock, -readbytes, -ignoreeof -.br -See also: -CREATE, -GOPEN, -UNIX-CONNECT -.IP "\fB\f(CWOPENSSL::\fP\fP" -Tries to establish a SSL connection to [TCP -service] on - [IP address] using TCP/IP version 4 or 6 -depending on address specification, name resolution, or option -pf\&. -.br -NOTE: The server certificate is only checked for validity against -cafile or capath, -but not for match with the server\'s name or its IP address! -.br -Option groups: FD,SOCKET,IP4,IP6,TCP,OPENSSL,RETRY -.br -Useful options: -cipher, -method, -verify, -cafile, -capath, -certificate, -bind, -pf, -connect-timeout, -sourceport, -retry -.br -See also: -OPENSSL-LISTEN, -TCP -.IP "\fB\f(CWOPENSSL-LISTEN:\fP\fP" -Listens on tcp [TCP service]\&. -The IP version is 4 or the one specified with -pf\&. When a -connection is accepted, this address behaves as SSL server\&. -.br -Note: You probably want to use the certificate option with this address\&. -.br -NOTE: The client certificate is only checked for validity against -cafile or capath, -but not for match with the client\'s name or its IP address! -.br -Option groups: FD,SOCKET,IP4,IP6,TCP,LISTEN,OPENSSL,CHILD,RANGE,RETRY -.br -Useful options: -pf, -cipher, -method, -verify, -cafile, -capath, -certificate, -fork, -bind, -range, -tcpwrap, -su, -reuseaddr, -retry -.br -See also: -OPENSSL, -TCP -.IP "\fB\f(CWPIPE:\fP\fP" -If already exists, it is opened\&. -If is does not exist, a named pipe is created and opened\&. Beginning with -socat version 1\&.4\&.3, the named pipe is removed when the address is closed -(but see option unlink-close -.br -Note: When a pipe is used for both reading and writing, it works -as echo service\&. -.br -Note: When a pipe is used for both reading and writing, and socat tries -to write more bytes than the pipe can buffer (Linux 2\&.4: 2048 bytes), socat -might block\&. Consider using socat option, e\&.g\&., \f(CW-b 2048\fP -.br -Option groups: FD,NAMED,OPEN -.br -Useful options: -rdonly, -nonblock, -group, -user, -mode, -unlink-early -.br -See also: unnamed pipe -.IP "\fB\f(CWPIPE\fP\fP" -Creates an unnamed pipe and uses it for reading and writing\&. It works as an -echo, because everything written -to it appeares immediately as read data\&. -.br -Note: When socat tries to write more bytes than the pipe can queue (Linux -2\&.4: 2048 bytes), socat might block\&. Consider, e\&.g\&., using -option \f(CW-b 2048\fP -.br -Option groups: FD -.br -See also: named pipe -.IP "\fB\f(CWPROXY:::\fP\fP" -Connects to an HTTP proxy server on port 8080 using TCP/IP version 4 or 6 -depending on address specification, name resolution, or option -pf, and sends a CONNECT -request for hostname:port\&. If the proxy grants access and succeeds to -connect to the target, data transfer between socat and the target can -start\&. Note that the traffic need not be HTTP but can be an arbitrary -protocol\&. -.br -Option groups: FD,SOCKET,IP4,IP6,TCP,HTTP,RETRY -.br -Useful options: -proxyport, -ignorecr, -proxyauth, -resolve, -crnl, -bind, -connect-timeout, -mss, -sourceport, -retry -.br -See also: SOCKS, TCP -.IP "\fB\f(CWPTY\fP\fP" -Generates a pseudo terminal (pty) and uses its master side\&. Another process -may open the pty\'s slave side using it like a serial line or terminal\&. -(example)\&. If -both the ptmx and the openpty mechanisms are available, ptmx is used -(POSIX)\&. -.br -Option groups: FD,NAMED,PTY,TERMIOS -.br -Useful options: -link, -openpty, -wait-slave, -mode, -user, -group -.br -See also: -UNIX-LISTEN, -PIPE, -EXEC, SYSTEM -.IP "\fB\f(CWREADLINE\fP\fP" -Uses GNU readline and history on stdio to allow editing and reusing input -lines (example)\&. This requires the GNU readline and -history libraries\&. Note that stdio should be a (pseudo) terminal device, -otherwise readline does not seem to work\&. -.br -Option groups: FD,READLINE,TERMIOS -.br -Useful options: -history, -noecho -.br -See also: -STDIO -.IP "\fB\f(CWSOCKS4:::\fP\fP" -Connects via [IP address] -to [IPv4 address] -on [TCP service], -using socks version 4 protocol over IP version 4 or 6 depending on address specification, name resolution, or option -pf (example)\&. -.br -Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY -.br -Useful options: -socksuser, -socksport, -sourceport, -pf, -retry -.br -See also: -SOCKS4A, -PROXY, -TCP -.IP "\fB\f(CWSOCKS4A:::\fP\fP" -like SOCKS4, but uses socks protocol version 4a, thus -leaving host name resolution to the socks server\&. -.br -Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY -.br -.IP "\fB\f(CWSTDERR\fP\fP" -Uses file descriptor 2\&. -.br -Option groups: FD (TERMIOS,REG,SOCKET) -.br -See also: FD -.IP "\fB\f(CWSTDIN\fP\fP" -Uses file descriptor 0\&. -.br -Option groups: FD (TERMIOS,REG,SOCKET) -.br -Useful options: -readbytes -.br -See also: FD -.IP "\fB\f(CWSTDIO\fP\fP" -Uses file descriptor 0 for reading, and 1 for writing\&. -.br -Option groups: FD (TERMIOS,REG,SOCKET) -.br -Useful options: -readbytes -.br -See also: FD -.IP "\fB\f(CWSTDOUT\fP\fP" -Uses file descriptor 1\&. -.br -Option groups: FD (TERMIOS,REG,SOCKET) -.br -See also: FD -.IP "\fB\f(CWSYSTEM:\fP\fP" -Forks a sub process that establishes communication with its parent process -and invokes the specified program with \f(CWsystem()\fP\&. Please note that - [string] must -not contain \',\' or "!!", and that shell meta characters may have to be -protected\&. -After successful program start, \fBsocat\fP writes data to stdin of the -process and reads from its stdout\&. -.br -Option groups: FD,SOCKET,EXEC,FORK,TERMIOS -.br -Useful options: -path, -fdin, -fdout, -chroot, -su, -su-d, -nofork, -pty, -stderr, -ctty, -setsid, -pipes, -sigint, -sigquit -.br -See also: EXEC -.IP "\fB\f(CWTCP::\fP\fP" -Connects to [TCP service] on - [IP address] using TCP/IP version 4 or 6 -depending on address specification, name resolution, or option -pf\&. -.br -Option groups: FD,SOCKET,IP4,IP6,TCP,RETRY -.br -Useful options: -crnl, -bind, -pf, -connect-timeout, -tos, -mtudiscover, -mss, -nodelay, -nonblock, -sourceport, -retry, -readbytes -.br -See also: -TCP4, -TCP6, -TCP-LISTEN, -UDP, -UNIX-CONNECT -.IP "\fB\f(CWTCP4::\fP\fP" -Like TCP, but only supports IPv4 protocol (example)\&. -.br -Option groups: FD,SOCKET,IP4,TCP,RETRY -.br -.IP "\fB\f(CWTCP6::\fP\fP" -Like TCP, but only supports IPv6 protocol\&. -.br -Option groups: FD,SOCKET,IP6,TCP,RETRY -.br -.IP "\fB\f(CWTCP-LISTEN:\fP\fP" -Listens on [TCP service] and accepts a -TCP/IP connection\&. The IP version is 4 or the one specified with -pf\&. -Note that opening -this address usually blocks until a client connects\&. -.br -Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,TCP,RETRY -.br -Useful options: -crnl, -fork, -bind, -range, -tcpwrap, -pf, -backlog, -mss, -su, -reuseaddr, -retry, -retry -.br -See also: -TCP4-LISTEN, -TCP6-LISTEN, -UDP-LISTEN, -UNIX-LISTEN, -OPENSSL-LISTEN -.IP "\fB\f(CWTCP4-LISTEN:\fP\fP" -Like TCP-LISTEN, but only supports IPv4 -protocol (example)\&. -.br -Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,TCP,RETRY -.br -.IP "\fB\f(CWTCP6-LISTEN:\fP\fP" -Like TCP-LISTEN, but only supports IPv6 -protocol\&. -.br -Additional useful option: -ipv6only -.br -Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,TCP,RETRY -.br -.IP "\fB\f(CWTUN:/\fP\fP" -Creates a Linux TUN/TAP device and assignes to it the address and netmask -defined by the parameters\&. The resulting network interface is ready for use -by other processes; socat serves its "wire side"\&. This address requires read -and write access to the tunnel cloning device, usually \f(CW/dev/net/tun\fP\&. -.br -Option groups: FD,NAMED,OPEN,TUN -.br -Useful options: -iff-up, -tun-device, -tun-name, -tun-type, -iff-no-pi -.br -See also: -ip-recv -.IP "\fB\f(CWUDP::\fP\fP" -Connects to [UDP service] on - [IP address] using UDP/IP version 4 or 6 -depending on address specification, name resolution, or option -pf\&. -.br -Please note that, -due to UDP protocol properties, no real connection is established; data has -to be sent for `connecting\' to the server, and no end-of-file condition can -be transported\&. -.br -Option groups: FD,SOCKET,IP4,IP6 -.br -Useful options: -ttl, -tos, -bind, -sourceport, -pf -.br -See also: -UDP4, -UDP6, -UDP-LISTEN, -TCP, -IP -.IP "\fB\f(CWUDP4::\fP\fP" -Like UDP, but only supports IPv4 protocol\&. -.br -Option groups: FD,SOCKET,IP4 -.br -.IP "\fB\f(CWUDP6::\fP\fP" -Like UDP, but only supports IPv6 protocol\&. -.br -Option groups: FD,SOCKET,IP6 -.br -.IP "\fB\f(CWUDP-DATAGRAM:
:\fP\fP" -Sends outgoing data to the specified address which may in particular be a -broadcast or multicast address\&. Packets arriving on the local socket are -checked for the correct remote port and if their source addresses match -eventual RANGE or TCPWRAP -options\&. This address type can for example be used for implementing -symmetric or asymmetric broadcast or multicast communications\&. -.br -Option groups: FD,SOCKET,IP4,IP6,RANGE -.br -Useful options: -range, -tcpwrap, -broadcast, -ip-multicast-loop, -ip-multicast-ttl, -ip-multicast-if, -ip-add-membership, -ttl, -tos, -bind, -sourceport, -pf -.br -See also: -UDP4-DATAGRAM, -UDP6-DATAGRAM, -UDP-SENDTO, -UDP-RECVFROM, -UDP-RECV, -UDP-CONNECT, -UDP-LISTEN, -IP-DATAGRAM -.IP "\fB\f(CWUDP4-DATAGRAM:
:\fP\fP" -Like UDP-DATAGRAM, but only supports IPv4 -protocol (example1, -example2)\&. -.br -Option groups: FD, SOCKET, -IP4, RANGE -.IP "\fB\f(CWUDP6-DATAGRAM:
:\fP\fP" -Like UDP-DATAGRAM, but only supports IPv6 -protocol\&. -.br -Option groups: FD,SOCKET, -IP6,RANGE -.IP "\fB\f(CWUDP-LISTEN:\fP\fP" -Waits for a UDP/IP packet arriving on -[UDP service] and `connects\' back to sender\&. -The accepted IP version is 4 or the one specified with option -pf\&. -Please note that, -due to UDP protocol properties, no real connection is established; data has -to arrive from the peer first, and no end-of-file condition can be -transported\&. Note that opening -this address usually blocks until a client connects\&. -.br -Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6 -.br -Useful options: -fork, -bind, -range, -pf -.br -See also: -UDP, -UDP4-LISTEN, -UDP6-LISTEN, -TCP-LISTEN -.IP "\fB\f(CWUDP4-LISTEN:\fP\fP" -Like UDP-LISTEN, but only support IPv4 -protocol\&. -.br -Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4 -.br -.IP "\fB\f(CWUDP6-LISTEN:\fP\fP" -Like UDP-LISTEN, but only support IPv6 -protocol\&. -.br -Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6 -.br -.IP "\fB\f(CWUDP-SENDTO::\fP\fP" -Communicates with the specified peer socket, defined by [UDP -service] on - [IP address], using UDP/IP version 4 or 6 -depending on address specification, name resolution, or option -pf\&. It sends packets to and receives packets -from that peer socket only\&. -This address effectively implements a datagram client\&. -It works well with socat UDP-RECVFROM and UDP-RECV address peers\&. -.br -Option groups: FD,SOCKET,IP4,IP6 -.br -Useful options: -ttl, -tos, -bind, -sourceport, -pf -.br -See also: -UDP4-SENDTO, -UDP6-SENDTO, -UDP-RECVFROM, -UDP-RECV, -UDP-CONNECT, -UDP-LISTEN, -IP-SENDTO -.IP "\fB\f(CWUDP4-SENDTO::\fP\fP" -Like UDP-SENDTO, but only supports IPv4 -protocol\&. -.br -Option groups: FD,SOCKET,IP4 -.IP "\fB\f(CWUDP6-SENDTO::\fP\fP" -Like UDP-SENDTO, but only supports IPv6 -protocol\&. -.br -Option groups: FD,SOCKET,IP6 -.IP -.IP "\fB\f(CWUDP-RECVFROM:\fP\fP" -Creates a UDP socket on [UDP service] using -UDP/IP version 4 or 6 -depending on option pf\&. -It receives one packet from an unspecified peer and may send one or more -answer packets to that peer\&. This mode is particularly useful with fork -option -where each arriving packet - from arbitrary peers - is handled by its own sub -process\&. This allows a behaviour similar to typical UDP based servers like ntpd -or named\&. This address works well with socat SENDTO address peers\&. -.br -Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE -.br -Useful options: -fork, -ttl, -tos, -bind, -sourceport, -pf -.br -See also: -UDP4-RECVFROM, -UDP6-RECVFROM, -UDP-SENDTO, -UDP-RECV, -UDP-CONNECT, -UDP-LISTEN, -IP-RECVFROM, -UNIX-RECVFROM -.IP "\fB\f(CWUDP4-RECVFROM:\fP\fP" -Like UDP-RECVFROM, but only supports IPv4 protocol\&. -.br -Option groups: FD,SOCKET,IP4,CHILD,RANGE -.IP "\fB\f(CWUDP6-RECVFROM:\fP\fP" -Like UDP-RECVFROM, but only supports IPv6 protocol\&. -.br -Option groups: FD,SOCKET,IP6,CHILD,RANGE -.IP -.IP "\fB\f(CWUDP-RECV:\fP\fP" -Creates a UDP socket on [UDP service] using UDP/IP version 4 or 6 -depending on option pf\&. -It receives packets from multiple unspecified peers and merges the data\&. -No replies are possible\&. It works well with, e\&.g\&., socat UDP-SENDTO address peers; it behaves similar to a syslog server\&. -.br -Option groups: FD,SOCKET,IP4,IP6,RANGE -.br -Useful options: -fork, -pf, -bind, -sourceport, -ttl, -tos -.br -See also: -UDP4-RECV, -UDP6-RECV, -UDP-SENDTO, -UDP-RECVFROM, -UDP-CONNECT, -UDP-LISTEN, -IP-RECV, -UNIX-RECV -.IP "\fB\f(CWUDP4-RECV:\fP\fP" -Like UDP-RECV, but only supports IPv4 protocol\&. -.br -Option groups: FD,SOCKET,IP4,RANGE -.IP "\fB\f(CWUDP6-RECV:\fP\fP" -Like UDP-RECV, but only supports IPv6 protocol\&. -.br -Option groups: FD,SOCKET,IP6,RANGE -.IP -.IP "\fB\f(CWUNIX-CONNECT:\fP\fP" -Connects to assuming it is a UNIX domain -socket\&. -If does not exist, this is an error; -if is not a UNIX domain socket, this is an error; -if is a UNIX domain socket, but no process is listening, this is -an error\&. -.br -Option groups: FD,SOCKET, -NAMED,RETRY, -UNIX -.br -) -Useful options: -bind -.br -See also: -UNIX-LISTEN, -UNIX-SENDTO, -TCP -.IP -.IP "\fB\f(CWUNIX-LISTEN:\fP\fP" -Listens on using a UNIX domain stream -socket and accepts a connection\&. -If exists and is not a socket, this is an error\&. -If exists and is a UNIX domain socket, binding to the address -fails (use option unlink-early!)\&. -Note that opening this address usually blocks until a client connects\&. -Beginning with socat version 1\&.4\&.3, the file system entry is removed when -this address is closed (but see option unlink-close) (example)\&. -.br -Option groups: FD,SOCKET, -NAMED,LISTEN, -CHILD,RETRY, -UNIX -.br -Useful options: -fork, -umask, -mode, -user, -group, -unlink-early -.br -See also: -UNIX-CONNECT, -UNIX-RECVFROM, -UNIX-RECV, -TCP-LISTEN -.IP -.IP "\fB\f(CWUNIX-SENDTO:\fP\fP" -Communicates with the specified peer socket, defined by [] assuming it is a UNIX domain datagram socket\&. -It sends packets to and receives packets from that peer socket only\&. -It works well with socat UNIX-RECVFROM and UNIX-RECV address peers\&. -.br -Option groups: FD,SOCKET, -NAMED,UNIX -.br -Useful options: -bind -.br -See also: -UNIX-RECVFROM, -UNIX-RECV, -UNIX-CONNECT, -UDP-SENDTO, -IP-SENDTO -.IP -.IP "\fB\f(CWUNIX-RECVFROM:\fP\fP" -Creates a UNIX domain datagram socket []\&. -Receives one packet and may send one or more answer packets to that peer\&. -This mode is particularly useful with fork option where each arriving packet - from arbitrary peers - is handled by its own sub process\&. -This address works well with socat UNIX-SENDTO address peers\&. -.br -Option groups: FD,SOCKET, -NAMED,CHILD, -UNIX -.br -Useful options: -fork -.br -See also: -UNIX-SENDTO, -UNIX-RECV, -UNIX-LISTEN, -UDP-RECVFROM, -IP-RECVFROM -.IP -.IP "\fB\f(CWUNIX-RECV:\fP\fP" -Creates a UNIX domain datagram socket []\&. -Receives packets from multiple unspecified peers and merges the data\&. -No replies are possible\&. It can be, e\&.g\&., addressed by socat UNIX-SENDTO address peers\&. -It behaves similar to a syslog server\&. -Option groups: FD,SOCKET, -NAMED,UNIX -.br -See also: -UNIX-SENDTO, -UNIX-RECVFROM, -UNIX-LISTEN, -UDP-RECV, -IP-RECV -.IP -.IP "\fB\f(CWUNIX-CLIENT:\fP\fP" -Communicates with the specified peer socket, defined by -[] assuming it is a UNIX domain socket\&. -It first tries to connect and, if that fails, assumes it is a datagram -socket, thus supporting both types\&. -.br -Option groups: FD,SOCKET, -NAMED,UNIX -.br -Useful options: -bind -.br -See also: -UNIX-CONNECT, -UNIX-SENDTO, -GOPEN -.IP -.IP "\fB\f(CWABSTRACT-CONNECT:\fP\fP" -.IP "\fB\f(CWABSTRACT-LISTEN:\fP\fP" -.IP "\fB\f(CWABSTRACT-SENDTO:\fP\fP" -.IP "\fB\f(CWABSTRACT-RECVFROM:\fP\fP" -.IP "\fB\f(CWABSTRACT-RECV:\fP\fP" -.IP "\fB\f(CWABSTRACT-CLIENT:\fP\fP" -The ABSTRACT addresses are almost identical to the related UNIX addresses -except that they do not address file system based sockets but an alternate -UNIX domain address space\&. To archieve this the socket address strings are -prefixed with "\e0" internally\&. This feature is available (only?) on Linux\&. -Option groups are the same as with the related UNIX addresses, except that -the ABSTRACT addresses are not member of the NAMED group\&. -.PP -.SH "ADDRESS OPTIONS" -.PP -Address options can be applied to address specifications to influence the -process of opening the addresses and the -properties of the resulting data channels\&. -.PP -For technical reasons not every option can be -applied to every address type; e\&.g\&., applying a socket option to a regular file -will fail\&. To catch most useless combinations as early as in the open phase, -the concept of \fIoption groups\fP was introduced\&. Each option belongs to one -or more option groups\&. Options can be used only with address types that support -at least one of their option groups (but see option -g)\&. -.PP -Address options have data types that their values must conform to\&. -Every address option consists of just a keyword or a keyword followed by -"=value", where value must conform to the options type\&. -Some address options manipulate parameters of system calls; -e\&.g\&., option sync sets the \f(CWO_SYNC\fP flag with the \f(CWopen()\fP call\&. -Other options cause a system or library call; e\&.g\&., with option `ttl=value\' -the \f(CWsetsockopt(fd, SOL_IP, IP_TTL, value, sizeof(int))\fP call is applied\&. -Other -options set internal \fBsocat\fP variables that are used during data transfer; -e\&.g\&., `crnl\' causes explicit character conversions\&. -A few options have more complex implementations; e\&.g\&., su-d -(substuser-delayed) inquires some user and group infos, stores them, and -applies them later after a possible \f(CWchroot()\fP call\&. -.PP -If multiple options are given to an address, their sequence in the address specification has (almost) no -effect on the sequence of their execution/application\&. Instead, \fBsocat\fP has -built in an \fIoption phase\fP model that tries to bring the options in a useful -order\&. Some options exist in different forms (e\&.g\&., -unlink, unlink-early, unlink-late) to control the time of their execution\&. -.PP -If the same option is specified more than once within one address -specification, with equal or different values, the effect depends on the kind of option\&. Options -resulting in function calls like \f(CWsetsockopt()\fP cause multiple -invocations\&. With options that set parameters for a required call like -\f(CWopen()\fP -or set internal flags, the value of the last option occurrence is effective\&. -.PP -The existence or semantics of many options are system dependent\&. \fBSocat\fP -usually does NOT try to emulate missing libc or kernel features, it just -provides an -interface to the underlying system\&. So, if an operating system lacks a feature, -the related option is simply not available on this platform\&. -.PP -The following paragraphs introduce just the more common address options\&. For -a more comprehensive reference and to find information about canonical option -names, alias names, option phases, and platforms see file \fBxio\&.help\fP\&. -.br -.br -.PP -.br -.PP -\fI\fBFD option group\fP\fP -.PP -This option group contains options that are applied to a UN*X -style file descriptor, no matter how it was generated\&. -Because all current \fBsocat\fP address types are file descriptor based, these -options may be applied to any address\&. -.br -Note: Some of these options are also member of another option group, that -provides an other, non-fd based mechanism\&. -For these options, it depends on the actual address type and its option groups -which mechanism is used\&. The second, non-fd based mechanism is prioritized\&. -.IP "\fB\f(CWcloexec=\fP\fP" -Sets the \f(CWFD_CLOEXEC\fP flag with the \f(CWfcntl()\fP system call to value -\&. If set, -the file descriptor is closed on \f(CWexec()\fP family function calls\&. \fBSocat\fP -internally handles -this flag for the fds it controls, so in most cases there will be no need to -apply this option\&. -.IP "\fB\f(CWsetlk\fP\fP" -Tries to set a discretionary write lock to the whole file using the \f(CWfcntl(fd, -F_SETLK, \&.\&.\&.)\fP system call\&. If the file is already locked, this call results -in an error\&. -On Linux, when the file permissions for group are "S" (g-x,g+s), and the -file system is locally mounted with the "mand" option, the lock is -mandatory, i\&.e\&. prevents other processes from opening the file\&. -.IP "\fB\f(CWsetlkw\fP\fP" -Tries to set a discretionary waiting write lock to the whole file using the -\f(CWfcntl(fd, F_SETLKW, \&.\&.\&.)\fP system call\&. If the file is already locked, -this call blocks\&. -See option setlk for information about making this -lock mandatory\&. -.IP "\fB\f(CWsetlk-rd\fP\fP" -Tries to set a discretionary read lock to the whole file using the \f(CWfcntl(fd, -F_SETLK, \&.\&.\&.)\fP system call\&. If the file is already write locked, this call -results in an error\&. -See option setlk for information about making this -lock mandatory\&. -.IP "\fB\f(CWsetlkw-rd\fP\fP" -Tries to set a discretionary waiting read lock to the whole file using the -\f(CWfcntl(fd, F_SETLKW, \&.\&.\&.)\fP system call\&. If the file is already write -locked, this call blocks\&. -See option setlk for information about making this -lock mandatory\&. -.IP "\fB\f(CWflock-ex\fP\fP" -Tries to set a blocking exclusive advisory lock to the file using the -\f(CWflock(fd, LOCK_EX)\fP system call\&. \fBSocat\fP hangs in this call if the file -is locked by another process\&. -.IP "\fB\f(CWflock-ex-nb\fP\fP" -Tries to set a nonblocking exclusive advisory lock to the file using the -\f(CWflock(fd, LOCK_EX|LOCK_NB)\fP system call\&. If the file is already locked, -this option results in an error\&. -.IP "\fB\f(CWflock-sh\fP\fP" -Tries to set a blocking shared advisory lock to the file using the -\f(CWflock(fd, LOCK_SH)\fP system call\&. \fBSocat\fP hangs in this call if the file -is locked by another process\&. -.IP "\fB\f(CWflock-sh-nb\fP\fP" -Tries to set a nonblocking shared advisory lock to the file using the -\f(CWflock(fd, LOCK_SH|LOCK_NB)\fP system call\&. If the file is already locked, -this option results in an error\&. -.IP "\fB\f(CWlock\fP\fP" -Sets a blocking lock on the file\&. Uses the setlk or flock mechanism -depending on availability on the particular platform\&. If both are available, -the POSIX variant (setlkw) is used\&. -.IP "\fB\f(CWuser=\fP\fP" -Sets the (owner) of the stream\&. -If the address is member of the NAMED option group, -\fBsocat\fP uses the \f(CWchown()\fP system call after opening the -file or binding to the UNIX domain socket (race condition!)\&. -Without filesystem entry, \fBsocat\fP sets the user of the stream -using the \f(CWfchown()\fP system call\&. -These calls might require root privilege\&. -.IP "\fB\f(CWuser-late=\fP\fP" -Sets the owner of the fd to with the \f(CWfchown()\fP -system call after opening -or connecting the channel\&. -This is useful only on file system entries\&. -.IP "\fB\f(CWgroup=\fP\fP" -Sets the of the stream\&. -If the address is member of the NAMED option group, -\fBsocat\fP uses the \f(CWchown()\fP system call after opening the -file or binding to the UNIX domain socket (race condition!)\&. -Without filesystem entry, \fBsocat\fP sets the group of the stream -with the \f(CWfchown()\fP system call\&. -These calls might require group membership or root privilege\&. -.IP "\fB\f(CWgroup-late=\fP\fP" -Sets the group of the fd to with the -\f(CWfchown()\fP system call after opening -or connecting the channel\&. -This is useful only on file system entries\&. -.IP "\fB\f(CWmode=\fP\fP" -Sets the [mode_t] (permissions) of the stream\&. -If the address is member of the NAMED option group and -uses the \f(CWopen()\fP or \f(CWcreat()\fP call, the mode is applied with these\&. -If the address is member of the NAMED option group without using these -system calls, \fBsocat\fP uses the \f(CWchmod()\fP system call after opening the -filesystem entry or binding to the UNIX domain socket (race condition!)\&. -Otherwise, \fBsocat\fP sets the mode of the stream -using \f(CWfchmod()\fP\&. -These calls might require ownership or root privilege\&. -.IP "\fB\f(CWperm-late=\fP\fP" -Sets the permissions of the fd to value -[mode_t] using the \f(CWfchmod()\fP system call after -opening or connecting the channel\&. -This is useful only on file system entries\&. -.IP "\fB\f(CWappend=\fP\fP" -Always writes data to the actual end of file\&. -If the address is member of the OPEN option group, -\fBsocat\fP uses the \f(CWO_APPEND\fP flag with the \f(CWopen()\fP system call -(example)\&. -Otherwise, \fBsocat\fP applies the \f(CWfcntl(fd, F_SETFL, O_APPEND)\fP call\&. -.IP "\fB\f(CWnonblock=\fP\fP" -Tries to open or use file in nonblocking mode\&. Its only effects are that the -\f(CWconnect()\fP call of TCP addresses does not block, and that opening a -named pipe for reading does not block\&. -If the address is member of the OPEN option group, -\fBsocat\fP uses the \f(CWO_NONBLOCK\fP flag with the \f(CWopen()\fP system call\&. -Otherwise, \fBsocat\fP applies the \f(CWfcntl(fd, F_SETFL, O_NONBLOCK)\fP call\&. -.IP "\fB\f(CWbinary\fP\fP" -Opens the file in binary mode to avoid implicit line terminator -conversions (Cygwin)\&. -.IP "\fB\f(CWtext\fP\fP" -Opens the file in text mode to force implicit line terminator conversions -(Cygwin)\&. -.IP "\fB\f(CWnoinherit\fP\fP" -Does not keep this file open in a spawned process (Cygwin)\&. -.IP "\fB\f(CWcool-write\fP\fP" -Takes it easy when write fails with EPIPE or ECONNRESET and logs the message -with \fInotice\fP level instead of \fIerror\fP\&. -This prevents the log file from being filled with useless error messages -when socat is used as a high volume server or proxy where clients often -abort the connection\&. -.br -This option is experimental\&. -.IP "\fB\f(CWend-close\fP\fP" -Changes the (address dependent) method of ending a connection to just close -the file descriptors\&. This is useful when the connection is to be reused by -or shared with other processes (example)\&. -.br -Normally, socket connections will be ended with \f(CWshutdown(2)\fP which -terminates the socket even if it is shared by multiple processes\&. -\f(CWclose(2)\fP "unlinks" the socket from the process but keeps it active as -long as there are still links from other processes\&. -.br -Similarly, when an address of type EXEC or SYSTEM is ended, socat usually -will explicitely kill the sub process\&. With this option, it will just close -the file descriptors\&. -.PP -.br -.PP -\fI\fBNAMED option group\fP\fP -.PP -These options work on file system entries\&. -.br -See also options user, group, and -mode\&. -.PP -.IP "\fB\f(CWuser-early=\fP\fP" -Changes the (owner) of the file system entry before -accessing it, using the -\f(CWchown()\fP system call\&. This call might require root privilege\&. -.IP "\fB\f(CWgroup-early=\fP\fP" -Changes the of the file system entry before -accessing it, using the -\f(CWchown()\fP system call\&. This call might require group membership or root -privilege\&. -.IP "\fB\f(CWperm-early=\fP\fP" -Changes the [mode_t] of the file system entry -before accessing it, using the -\f(CWchmod()\fP system call\&. This call might require ownership or root -privilege\&. -.IP "\fB\f(CWumask=\fP\fP" -Sets the umask of the process to [mode_t] before -accessing the file system entry (useful -with UNIX domain sockets!)\&. This call might affect all further operations -of the \fBsocat\fP process! -.IP "\fB\f(CWunlink-early\fP\fP" -Unlinks (removes) the file before opening it and even before applying -user-early etc\&. -.IP "\fB\f(CWunlink\fP\fP" -Unlinks (removes) the file before accessing it, but after user-early etc\&. -.IP "\fB\f(CWunlink-late\fP\fP" -Unlinks (removes) the file after opening it to make it inaccessible for -other processes after a short race condition\&. -.IP "\fB\f(CWunlink-close\fP\fP" -Removes the addresses file system entry when closing the address\&. -For named pipes, -listening unix domain sockets, -and the symbolic links of pty addresses, -the default is 1; for created files, -opened files, -generic opened files, and -client unix domain sockets the default is 0\&. -.PP -.br -.PP -\fI\fBOPEN option group\fP\fP -.PP -The OPEN group options allow to set flags with the \f(CWopen()\fP system call\&. -E\&.g\&., option `creat\' sets the \f(CWO_CREAT\fP flag\&. -.br -See also options append and -nonblock\&. -.IP "\fB\f(CWcreat=\fP\fP" -Creates the file if it does not exist (example)\&. -.IP "\fB\f(CWdsync=\fP\fP" -Blocks \f(CWwrite()\fP calls until metainfo is physically written to media\&. -.IP "\fB\f(CWexcl=\fP\fP" -With option creat, if file exists this is an error\&. -.IP "\fB\f(CWlargefile=\fP\fP" -On 32 bit systems, allows a file larger than 2^31 bytes\&. -.IP "\fB\f(CWnoatime\fP\fP" -Sets the O_NOATIME options, so reads do not change the access timestamp\&. -.IP "\fB\f(CWnoctty=\fP\fP" -Does not make this file the controlling terminal\&. -.IP "\fB\f(CWnofollow=\fP\fP" -Does not follow symbolic links\&. -.IP "\fB\f(CWnshare=\fP\fP" -Does not allow to share this file with other processes\&. -.IP "\fB\f(CWrshare=\fP\fP" -Does not allow other processes to open this file for writing\&. -.IP "\fB\f(CWrsync=\fP\fP" -Blocks \f(CWwrite()\fP until metainfo is physically written to media\&. -.IP "\fB\f(CWsync=\fP\fP" -Blocks \f(CWwrite()\fP until data is physically written to media\&. -.IP "\fB\f(CWrdonly=\fP\fP" -Opens the file for reading only\&. -.IP "\fB\f(CWwronly=\fP\fP" -Opens the file for writing only\&. -.IP "\fB\f(CWtrunc\fP\fP" -Truncates the file to size 0 during opening it\&. -.PP -.br -.PP -\fI\fBREG and BLK option group\fP\fP -.PP -These options are usually applied to a UN*X file descriptor, but their -semantics make sense only on a file supporting random access\&. -.IP "\fB\f(CWseek=\fP\fP" -Applies the \f(CWlseek(fd, , SEEK_SET)\fP (or \f(CWlseek64\fP) system -call, thus positioning the file pointer absolutely to -[off_t or off64_t]\&. -.IP "\fB\f(CWseek-cur=\fP\fP" -Applies the \f(CWlseek(fd, , SEEK_CUR)\fP (or \f(CWlseek64\fP) system -call, thus positioning the file pointer [off_t or -off64_t] bytes relatively to its current position (which -is usually 0)\&. -.IP "\fB\f(CWseek-end=\fP\fP" -Applies the \f(CWlseek(fd, , SEEK_END)\fP (or \f(CWlseek64\fP) system -call, thus positioning the file pointer [off_t or -off64_t] bytes relatively to the files current end\&. -.IP "\fB\f(CWftruncate=\fP\fP" -Applies the \f(CWftruncate(fd, )\fP -(or \f(CWftruncate64\fP if available) system call, thus -truncating the file at the position [off_t or -off64_t]\&. -.IP -.IP "\fB\f(CWsecrm=\fP\fP" -.IP "\fB\f(CWunrm=\fP\fP" -.IP "\fB\f(CWcompr=\fP\fP" -.IP "\fB\f(CWext2-sync=\fP\fP" -.IP "\fB\f(CWimmutable=\fP\fP" -.IP "\fB\f(CWext2-append=\fP\fP" -.IP "\fB\f(CWnodump=\fP\fP" -.IP "\fB\f(CWext2-noatime=\fP\fP" -.IP "\fB\f(CWjournal-data=\fP\fP" -.IP "\fB\f(CWnotail=\fP\fP" -.IP "\fB\f(CWdirsync=\fP\fP" -These options change non standard file attributes on operating systems and -file systems that support these features, like Linux with ext2fs, -ext3fs, or reiserfs\&. See man 1 chattr for information on these options\&. -Please note that there might be a race condition between creating the file -and applying these options\&. -.PP -.br -.PP -\fI\fBPROCESS option group\fP\fP -.PP -Options of this group change the process properties instead of just affecting -one data channel\&. -For EXEC and SYSTEM addresses and for LISTEN and CONNECT type addresses with -option FORK, -these options apply to the child processes instead of the main socat process\&. -.IP "\fB\f(CWchroot=\fP\fP" -Performs a \f(CWchroot()\fP operation to -after processing the address (example)\&. This call might require root privilege\&. -.IP "\fB\f(CWchroot-early=\fP\fP" -Performs a \f(CWchroot()\fP operation to -before opening the address\&. This call might require root privilege\&. -.IP "\fB\f(CWsetgid=\fP\fP" -Changes the primary of the process after -processing the address\&. This call might require root privilege\&. -.IP "\fB\f(CWsetgid-early=\fP\fP" -Changes the primary of the process before opening -the address\&. This call might require root privilege\&. -.IP "\fB\f(CWsetuid=\fP\fP" -Changes the (owner) of the process after processing -the address\&. This call might require root privilege\&. -.IP "\fB\f(CWsetuid-early=\fP\fP" -Changes the (owner) of the process before opening -the address\&. This call might require root privilege\&. -.IP "\fB\f(CWsu=\fP\fP" -Changes the (owner) and groups of the process after -processing the address (example)\&. This call might require root privilege\&. -.IP "\fB\f(CWsu-d=\fP\fP" -Short name for \fB\f(CWsubstuser-delayed\fP\fP\&. -Changes the -(owner) and groups of the process after processing the address (example)\&. -The user and his groups are retrieved \fIbefore\fP a possible -\f(CWchroot()\fP\&. This call might require root privilege\&. -.IP "\fB\f(CWsetpgid=\fP\fP" -Makes the process a member of the specified process group -\&. If no value -is given, or if the value is 0 or 1, the process becomes leader of a new -process group\&. -.IP "\fB\f(CWsetsid\fP\fP" -Makes the process the leader of a new session (example)\&. -.PP -.br -.PP -\fI\fBREADLINE option group\fP\fP -.PP -These options apply to the readline address type\&. -.IP "\fB\f(CWhistory=\fP\fP" -Reads and writes history from/to (example)\&. -.IP "\fB\f(CWnoprompt\fP\fP" -Since version 1\&.4\&.0, socat per default tries to determine a prompt - -that is then passed to the readline call - by remembering the last -incomplete line of the output\&. With this option, socat does not pass a -prompt to readline, so it begins line editing in the first column -of the terminal\&. -.IP "\fB\f(CWnoecho=\fP\fP" -Specifies a regular pattern for a prompt that prevents the following input -line from being displayed on the screen and from being added to the history\&. -The prompt is defined as the text that was output to the readline address -after the lastest newline character and before an input character was -typed\&. The pattern is a regular expression, e\&.g\&. -"^[Pp]assword:\&.*$" or "([Uu]ser:|[Pp]assword:)"\&. See regex(7) for details\&. -(example) -.IP "\fB\f(CWprompt=\fP\fP" -Passes the string as prompt to the readline function\&. readline prints this -prompt when stepping through the history\&. If this string matches a constant -prompt issued by an interactive program on the other socat address, -consistent look and feel can be archieved\&. -.PP -.br -.PP -\fI\fBAPPLICATION option group\fP\fP -.PP -This group contains options that work at data level\&. -Note that these options only apply to the "raw" data transferred by socat, -but not to protocol data used by addresses like -PROXY\&. -.IP "\fB\f(CWcr\fP\fP" -Converts the default line termination character NL (\'\en\', 0x0a) to/from CR -(\'\er\', 0x0d) when writing/reading on this channel\&. -.IP "\fB\f(CWcrnl\fP\fP" -Converts the default line termination character NL (\'\en\', 0x0a) to/from CRNL -("\er\en", 0x0d0a) when writing/reading on this channel (example)\&. -Note: socat simply strips all CR characters\&. -.IP "\fB\f(CWignoreeof\fP\fP" -When EOF occurs on this channel, \fBsocat\fP ignores it and tries to read more -data (like "tail -f") (example)\&. -.IP "\fB\f(CWreadbytes=\fP\fP" -\fBsocat\fP reads only so many bytes from this address (the address provides -only so many bytes for transfer and pretends to be at EOF afterwards)\&. -Must be greater than 0\&. -.IP "\fB\f(CWlockfile=\fP\fP" -If lockfile exists, exits with error\&. If lockfile does not exist, creates it -and continues, unlinks lockfile on exit\&. -.IP "\fB\f(CWwaitlock=\fP\fP" -If lockfile exists, waits until it disappears\&. When lockfile does not exist, -creates it and continues, unlinks lockfile on exit\&. -.PP -.br -.PP -\fI\fBSOCKET option group\fP\fP -.PP -These options are intended for all kinds of sockets, e\&.g\&. IP or UNIX domain\&. Most are applied with a \f(CWsetsockopt()\fP call\&. -.IP "\fB\f(CWbind=\fP\fP" -Binds the socket to the given socket address using the \f(CWbind()\fP system -call\&. The form of is socket domain dependent: -IP4 and IP6 allow the form [hostname|hostaddress][:(service|port)] (example), -UNIX domain sockets require \&. -.IP "\fB\f(CWconnect-timeout=\fP\fP" -Abort the connection attempt after [timeval] -with error status\&. -.IP "\fB\f(CWinterface=\fP\fP" -Binds the socket to the given \&. -This option might require root privilege\&. -.IP "\fB\f(CWbroadcast\fP\fP" -For datagram sockets, allows sending to broadcast addresses and receiving -packets addressed to broadcast addresses\&. -.IP "\fB\f(CWbsdcompat\fP\fP" -Emulates some (old?) bugs of the BSD socket implementation\&. -.IP "\fB\f(CWdebug\fP\fP" -Enables socket debugging\&. -.IP "\fB\f(CWdontroute\fP\fP" -Only communicates with directly connected peers, does not use routers\&. -.IP "\fB\f(CWkeepalive\fP\fP" -Enables sending keepalives on the socket\&. -.IP "\fB\f(CWlinger=\fP\fP" -Blocks \f(CWshutdown()\fP or \f(CWclose()\fP until data transfers have finished -or the given timeout [int] expired\&. -.IP "\fB\f(CWoobinline\fP\fP" -Places out-of-band data in the input data stream\&. -.IP "\fB\f(CWpriority=\fP\fP" -Sets the protocol defined [] for outgoing -packets\&. -.IP "\fB\f(CWrcvbuf=\fP\fP" -Sets the size of the receive buffer after the \f(CWsocket()\fP call to - [int]\&. With TCP -sockets, this value corresponds to the socket\'s maximal window size\&. -.IP "\fB\f(CWrcvbuf-late=\fP\fP" -Sets the size of the receive buffer when the socket is already -connected to [int]\&. -With TCP sockets, this value corresponds to the socket\'s -maximal window size\&. -.IP "\fB\f(CWrcvlowat=\fP\fP" -Specifies the minimum number of received bytes [int] until -the socket layer will pass the buffered data to \fBsocat\fP\&. -.IP "\fB\f(CWrcvtimeo=\fP\fP" -Sets the receive timeout [timeval]\&. -.IP "\fB\f(CWreuseaddr\fP\fP" -Allows other sockets to bind to an address even if parts of it (e\&.g\&. the -local port) are already in use by \fBsocat\fP (example)\&. -.IP "\fB\f(CWsndbuf=\fP\fP" -Sets the size of the send buffer after the \f(CWsocket()\fP call to - [int]\&. -.IP "\fB\f(CWsndbuf-late=\fP\fP" -Sets the size of the send buffer when the socket is connected to - [int]\&. -.IP "\fB\f(CWsndlowat=\fP\fP" -Specifies the minimum number of bytes in the send buffer until the socket -layer will send the data to [int]\&. -.IP "\fB\f(CWsndtimeo=\fP\fP" -Sets the send timeout to seconds [timeval]\&. -.IP "\fB\f(CWtype=\fP\fP" -Sets the type of the socket, usually as argument to the \f(CWsocket()\fP or -\f(CWsocketpair()\fP call, to [int]\&. -Under Linux, 1 means stream oriented socket, 2 means datagram socket, and 3 -means raw socket\&. -.IP "\fB\f(CWpf=\fP\fP" -Forces the use of the specified IP version\&. can be -something like "ip4" or "ip6"\&. -.PP -.br -.PP -\fI\fBUNIX option group\fP\fP -.PP -These options apply to UNIX domain based addresses\&. -.IP "\fB\f(CWunix-tightsocklen=[0|1]\fP\fP" -On socket operations, pass a socket address length that does not include the -whole \f(CWstruct sockaddr_un\fP record but (besides other components) only -the relevant part of the filename or abstract string\&. Default is 1\&. -.PP -\fI\fBIP4 and IP6 option groups\fP\fP -.PP -These options can be used with IPv4 and IPv6 based sockets\&. -.IP "\fB\f(CWtos=\fP\fP" -Sets the TOS (type of service) field of outgoing packets to -[byte] (see RFC 791)\&. -.IP "\fB\f(CWttl=\fP\fP" -Sets the TTL (time to live) field of outgoing packets to -[byte]\&. -.IP "\fB\f(CWipoptions=\fP\fP" -Sets IP options like source routing\&. Must be given in binary form, -recommended format is a leading "x" followed by an even number of hex -digits\&. This option may be used multiple times, data are appended\&. -E\&.g\&., to connect to host 10\&.0\&.0\&.1 via some gateway using a loose source -route, use the gateway as address parameter and set a loose source route -using the option \f(CWipoptions=x8307040a000001\fP\&. -.br -IP options are defined in RFC 791\&. -.br -.IP "\fB\f(CWmtudiscover=<0|1|2>\fP\fP" -Takes 0, 1, 2 to never, want, or always use path MTU discover on this -socket\&. -.IP "\fB\f(CWip-add-membership=\fP\fP" -.IP "\fB\f(CWip-add-membership=\fP\fP" -.IP "\fB\f(CWip-add-membership=\fP\fP" -.IP "\fB\f(CWip-add-membership=\fP\fP" -.IP "\fB\f(CWip-add-membership=\fP\fP" -Makes the socket member of the specified multicast group\&. This is currently -only implemented for IPv4\&. The option takes the IP address of the multicast -group and info about the desired network interface\&. The most common syntax -is the first one, while the others are only available on systems that -provide \f(CWstruct mreqn\fP (Linux)\&. -.br -The indices of active network interfaces can be shown using the utility -\fBprocan\fP\&. -dif(\fB\f(CWip-multicast-if=\fP\fP) -Specifies hostname or address of the network interface to be used for -multicast traffic\&. -dif(\fB\f(CWip-multicast-loop=\fP\fP) -Specifies if outgoing multicast traffic should loop back to the interface\&. -dif(\fB\f(CWip-multicast-ttl=\fP\fP) -Sets the TTL used for outgoing multicast traffic\&. Default is 1\&. -.IP "\fB\f(CWres-debug\fP\fP" -.IP "\fB\f(CWres-aaonly\fP\fP" -.IP "\fB\f(CWres-usevc\fP\fP" -.IP "\fB\f(CWres-primary\fP\fP" -.IP "\fB\f(CWres-igntc\fP\fP" -.IP "\fB\f(CWres-recurse\fP\fP" -.IP "\fB\f(CWres-defnames\fP\fP" -.IP "\fB\f(CWres-stayopen\fP\fP" -.IP "\fB\f(CWres-dnsrch\fP\fP" -These options set the corresponding resolver (name resolution) option flags\&. -Append "=0" to clear a default option\&. See man resolver(5) for more -information on these options\&. Note: these options are valid only for the -address they are applied to\&. -.IP -.PP -.br -.PP -\fI\fBIP6 option group\fP\fP -.PP -These options can only be used on IPv6 based sockets\&. See IP -options for options that can be applied to both IPv4 and IPv6 -sockets\&. -.IP "\fB\f(CWipv6only=\fP\fP" -Sets the IPV6_V6ONLY socket option\&. If 0, the TCP stack will also accept -connections using IPv4 protocol on the same port\&. The default is system -dependent\&. -.PP -.br -.PP -\fI\fBTCP option group\fP\fP -.PP -These options may be applied to TCP sockets\&. They work by invoking \f(CWsetsockopt()\fP with the appropriate parameters\&. -.IP "\fB\f(CWcork\fP\fP" -Doesn\'t send packets smaller than MSS (maximal segment size)\&. -.IP "\fB\f(CWdefer-accept\fP\fP" -While listening, accepts connections only when data from the peer arrived\&. -.IP "\fB\f(CWkeepcnt=\fP\fP" -Sets the number of keepalives before shutting down the socket to - [int]\&. -.IP "\fB\f(CWkeepidle=\fP\fP" -Sets the idle time before sending the first keepalive to -[int]\&. -.IP "\fB\f(CWkeepintvl=\fP\fP" -Sets the intervall between two keepalives to -[int]\&. -.IP "\fB\f(CWlinger2=\fP\fP" -Sets the time to keep the socket in FIN-WAIT-2 state to -[int]\&. -.IP "\fB\f(CWmss=\fP\fP" -Sets the MSS (maximum segment size) after the \f(CWsocket()\fP call to -[int]\&. This -value is then proposed to the peer with the SYN or SYN/ACK packet -(example)\&. -.IP "\fB\f(CWmss-late=\fP\fP" -Sets the MSS of the socket after connection has been established to -[int]\&. -.IP "\fB\f(CWnodelay\fP\fP" -Turns off the Nagle algorithm for measuring the RTT (round trip time)\&. -.IP "\fB\f(CWrfc1323\fP\fP" -Enables RFC1323 TCP options: TCP window scale, round-trip time measurement -(RTTM), and protect against wrapped sequence numbers (PAWS) (AIX)\&. -.IP "\fB\f(CWstdurg\fP\fP" -Enables RFC1122 compliant urgent pointer handling (AIX)\&. -.IP "\fB\f(CWsyncnt=\fP\fP" -Sets the maximal number of SYN retransmits during connect to -[int]\&. -.IP "\fB\f(CWmd5sig\fP\fP" -Enables generation of MD5 digests on the packets (FreeBSD)\&. -.IP "\fB\f(CWnoopt\fP\fP" -Disables use of TCP options (FreeBSD, MacOSX)\&. -.IP "\fB\f(CWnopush\fP\fP" -sets the TCP_NOPUSH socket option (FreeBSD, MacOSX)\&. -.IP "\fB\f(CWsack-disable\fP\fP" -Disables use the selective acknowledge feature (OpenBSD)\&. -.IP "\fB\f(CWsignature-enable\fP\fP" -Enables generation of MD5 digests on the packets (OpenBSD)\&. -.IP "\fB\f(CWabort-threshold=\fP\fP" -Sets the time to wait for an answer of the peer on an established connection -(HP-UX)\&. -.IP "\fB\f(CWconn-abort-threshold=\fP\fP" -Sets the time to wait for an answer of the server during the initial connect -(HP-UX)\&. -.IP "\fB\f(CWkeepinit\fP\fP" -Sets the time to wait for an answer of the server during connect() before -giving up\&. Value in half seconds, default is 150 (75s) (Tru64)\&. -.IP "\fB\f(CWpaws\fP\fP" -Enables the "protect against wrapped sequence numbers" feature (Tru64)\&. -.IP "\fB\f(CWsackena\fP\fP" -Enables selective acknowledge (Tru64)\&. -.IP "\fB\f(CWtsoptena\fP\fP" -Enables the time stamp option that allows RTT recalculation on existing -connections (Tru64)\&. -.PP -.br -.PP -\fI\fBUDP and TCP option groups\fP\fP -.PP -Here we find options that are related to the network port mechanism and that -thus can be used with UDP and TCP, client and server addresses\&. -.IP "\fB\f(CWsourceport=\fP\fP" -For outgoing (client) TCP and UDP connections, it sets the source - using an extra \f(CWbind()\fP call\&. -With TCP or UDP listen addresses, socat immediately shuts down the -connection if the client does not use this sourceport (example)\&. -.IP "\fB\f(CWlowport\fP\fP" -Outgoing (client) TCP and UDP connections with this option use -an unused random source port between 640 and 1023 incl\&. On UNIX class operating -systems, this requires root privilege, and thus indicates that the -client process is authorized by local root\&. -TCP and UDP listen addresses with this option immediately shut down the -connection if the client does not use a sourceport <= 1023\&. -This mechanism can provide limited authorization under some circumstances\&. -.PP -.br -.PP -\fI\fBSOCKS option group\fP\fP -.PP -When using SOCKS type addresses, some socks specific options can be set\&. -.IP "\fB\f(CWsocksport=\fP\fP" -Overrides the default "socks" service or port 1080 for the socks server -port with \&. -.IP "\fB\f(CWsocksuser=\fP\fP" -Sends the [string] in the username field to the -socks server\&. Default is the actual user name ($LOGNAME or $USER) (example)\&. -.PP -.br -.PP -\fI\fBHTTP option group\fP\fP -.PP -Options that can be provided with HTTP type addresses\&. The only HTTP address -currently implemented is proxy-connect\&. -.PP -.IP "\fB\f(CWproxyport=\fP\fP" -Overrides the default HTTP proxy port 8080 with -\&. -.IP "\fB\f(CWignorecr\fP\fP" -The HTTP protocol requires the use of CR+NL as line terminator\&. When a proxy -server violates this standard, socat might not understand its answer\&. -This option directs socat to interprete NL as line terminator and -to ignore CR in the answer\&. Nevertheless, socat sends CR+NL to the proxy\&. -.IP "\fB\f(CWproxyauth=:\fP\fP" -Provide "basic" authentication to the proxy server\&. The argument to the -option is used with a "Proxy-Authorization: Base" header in base64 encoded -form\&. -.br -Note: username and password are visible for every user on the local machine -in the process list; username and password are transferred to the proxy -server unencrypted (base64 encoded) and might be sniffed\&. -.IP "\fB\f(CWresolve\fP\fP" -Per default, socat sends to the proxy a CONNECT request containing the -target hostname\&. With this option, socat resolves the hostname locally and -sends the IP address\&. Please note that, according to RFC 2396, only name -resolution to IPv4 addresses is implemented\&. -.PP -.br -.PP -\fI\fBRANGE option group\fP\fP -.PP -These options check if a connecting client should be granted access\&. They can -be applied to listening and receiving network sockets\&. tcp-wrappers options -fall into this group\&. -.IP "\fB\f(CWrange=\fP\fP" -After accepting a connection, tests if the peer is within \fIrange\fP\&. For -IPv4 addresses, address-range takes the form address/bits, e\&.g\&. -10\&.0\&.0\&.0/8, or address:mask, e\&.g\&. 10\&.0\&.0\&.0:255\&.0\&.0\&.0 (example); for IPv6, it is [ip6-address/bits], e\&.g\&. [::1/128]\&. -If the client address does not match, \fBsocat\fP issues a warning and keeps -listening/receiving\&. -.IP "\fB\f(CWtcpwrap[=]\fP\fP" -Uses Wietse Venema\'s libwrap (tcpd) library to determine -if the client is allowed to connect\&. The configuration files are -/etc/hosts\&.allow and /etc/hosts\&.deny per default, see "man 5 hosts_access" -for more information\&. The optional (type string) -is passed to the wrapper functions as daemon process name (example)\&. -If omitted, the basename of socats invocation (argv[0]) is passed\&. -If both tcpwrap and range options are applied to an address, both -conditions must be fulfilled to allow the connection\&. -.IP "\fB\f(CWallow-table=\fP\fP" -Takes the specified file instead of /etc/hosts\&.allow\&. -.IP "\fB\f(CWdeny-table=\fP\fP" -Takes the specified file instead of /etc/hosts\&.deny\&. -.IP "\fB\f(CWtcpwrap-etc=\fP\fP" -Looks for hosts\&.allow and hosts\&.deny in the specified directory\&. Is -overridden by options hosts-allow -and hosts-deny\&. -.PP -.br -.PP -\fI\fBLISTEN option group\fP\fP -.PP -Options specific to listening sockets\&. -.IP "\fB\f(CWbacklog=\fP\fP" -Sets the backlog value passed with the \f(CWlisten()\fP system call to -[int]\&. Default is 5\&. -.br -.PP -\fI\fBCHILD option group\fP\fP -.PP -Options for addresses with multiple connections via child processes\&. -.IP "\fB\f(CWfork\fP\fP" -After establishing a connection, handles its channel in a child process and -keeps the parent process attempting to produce more connections, either by -listening or by connecting in a loop (example)\&. -.br -SSL-CONNECT and SSL-LISTEN differ in when they actually fork off the child: -SSL-LISTEN forks \fIbefore\fP the SSL handshake, while SSL-CONNECT forks -\fIafterwards\fP\&. -RETRY and FOREVER options are not inherited by the child process\&. -.br -.PP -.br -.PP -\fI\fBEXEC option group\fP\fP -.PP -Options for addresses that invoke a program\&. -.IP "\fB\f(CWpath=\fP\fP" -Overrides the PATH environment variable for searching the program with -\&. This -\f(CW$PATH\fP value is effective in the child process too\&. -.IP "\fB\f(CWlogin\fP\fP" -Prefixes \f(CWargv[0]\fP for the \f(CWexecvp()\fP call with \'-\', thus making a -shell behave as login shell\&. -.PP -.br -.PP -\fI\fBFORK option group\fP\fP -.PP -EXEC or SYSTEM addresses invoke a program using a child process and transfer data between \fBsocat\fP and the program\&. The interprocess communication mechanism can be influenced with the following options\&. Per -default, a \f(CWsocketpair()\fP is created and assigned to stdin and stdout of -the child process, while stderr is inherited from the \fBsocat\fP process, and the -child process uses file descriptors 0 and 1 for communicating with the main -socat process\&. -.IP "\fB\f(CWnofork\fP\fP" -Does not fork a subprocess for executing the program, instead calls execvp() -or system() directly from the actual socat instance\&. This avoids the -overhead of another process between the program and its peer, -but introduces a lot of restrictions: -.IP o -this option can only be applied to the second \fBsocat\fP address\&. -.IP o -it cannot be applied to a part of a dual address\&. -.IP o -the first socat address cannot be OPENSSL or READLINE -.IP o -socat options -b, -t, -D, -l, -v, -x become useless -.IP o -for both addresses, options ignoreeof, cr, and crnl become useless -.IP o -for the second address (the one with option nofork), options -append, cloexec, flock, user, group, mode, nonblock, -perm-late, setlk, and setpgid cannot be applied\&. Some of these could be -used on the first address though\&. -.IP "\fB\f(CWpipes\fP\fP" -Creates a pair of unnamed pipes for interprocess communication instead of a -socket pair\&. -.IP "\fB\f(CWopenpty\fP\fP" -Establishes communication with the sub process using a pseudo terminal -created with \f(CWopenpty()\fP instead of the default (socketpair or ptmx)\&. -.IP "\fB\f(CWptmx\fP\fP" -Establishes communication with the sub process using a pseudo terminal -created by opening \fB/dev/ptmx\fP or \fB/dev/ptc\fP instead of the default -(socketpair)\&. -.IP "\fB\f(CWpty\fP\fP" -Establishes communication with the sub process using a pseudo terminal -instead of a socket pair\&. Creates the pty with an available mechanism\&. If -openpty and ptmx are both available, it uses ptmx because this is POSIX -compliant (example)\&. -.IP "\fB\f(CWctty\fP\fP" -Makes the pty the controlling tty of the sub process (example)\&. -.IP "\fB\f(CWstderr\fP\fP" -Directs stderr of the sub process to its output channel by making stderr a -\f(CWdup()\fP of stdout (example)\&. -.IP "\fB\f(CWfdin=\fP\fP" -Assigns the sub processes input channel to its file descriptor - -instead of stdin (0)\&. The program started from the subprocess has to use -this fd for reading data from \fBsocat\fP (example)\&. -.IP "\fB\f(CWfdout=\fP\fP" -Assigns the sub processes output channel to its file descriptor - -instead of stdout (1)\&. The program started from the subprocess has to use -this fd for writing data to \fBsocat\fP (example)\&. -.IP "\fB\f(CWsighup\fP\fP, \fB\f(CWsigint\fP\fP, \fB\f(CWsigquit\fP\fP" -Has \fBsocat\fP pass an eventual signal of this type to the sub process\&. -If no address has this option, socat terminates on these signals\&. -.PP -.br -.PP -\fI\fBTERMIOS option group\fP\fP -.PP -For addresses that work on a tty (e\&.g\&., stdio, file:/dev/tty, exec:\&.\&.\&.,pty), the terminal parameters defined in the UN*X termios mechanism are made available as address option parameters\&. -Please note that changes of the parameters of your interactive terminal -remain effective after \fBsocat\fP\'s termination, so you might have to enter "reset" -or "stty sane" in your shell afterwards\&. -For EXEC and SYSTEM addresses with option PTY, -these options apply to the pty by the child processes\&. -.PP -.IP "\fB\f(CWb0\fP\fP" -Disconnects the terminal\&. -.IP "\fB\f(CWb19200\fP\fP" -Sets the serial line speed to 19200 baud\&. Some other rates are possible; use -something like \f(CWsocat -hh |grep \' b[1-9]\'\fP to find all speeds supported by -your implementation\&. -.br -Note: On some operating systems, these options may not be -available\&. Use ispeed or ospeed -instead\&. -.IP "\fB\f(CWecho=\fP\fP" -Enables or disables local echo (example)\&. -.IP "\fB\f(CWicanon=\fP\fP" -Sets or clears canonical mode, enabling line buffering and some special -characters\&. -.IP "\fB\f(CWraw\fP\fP" -Sets raw mode, thus passing input and output almost unprocessed (example)\&. -.IP "\fB\f(CWignbrk=\fP\fP" -Ignores or interpretes the BREAK character (e\&.g\&., ^C) -.IP "\fB\f(CWbrkint=\fP\fP" -.IP "\fB\f(CWbs0\fP\fP" -.IP "\fB\f(CWbs1\fP\fP" -.IP "\fB\f(CWbsdly=<0|1>\fP\fP" -.IP "\fB\f(CWclocal=\fP\fP" -.IP -\.LP -\.nf -\fBcr0 -cr1 -cr2 -cr3\fP -\.fi -\.IP -Sets the carriage return delay to 0, 1, 2, or 3, respectively\&. -0 means no delay, the other values are terminal dependent\&. -.IP -.IP "\fB\f(CWcrdly=<0|1|2|3>\fP\fP" -.IP "\fB\f(CWcread=\fP\fP" -.IP "\fB\f(CWcrtscts=\fP\fP" -.IP -\.LP -\.nf -\fBcs5 -cs6 -cs7 -cs8\fP -\.fi -\.IP -Sets the character size to 5, 6, 7, or 8 bits, respectively\&. -.IP -.IP "\fB\f(CWcsize=<0|1|2|3>\fP\fP" -.IP "\fB\f(CWcstopb=\fP\fP" -Sets two stop bits, rather than one\&. -.IP "\fB\f(CWdsusp=\fP\fP" -Sets the value for the VDSUSP character that suspends the current foreground -process and reactivates the shell (all except Linux)\&. -.IP "\fB\f(CWechoctl=\fP\fP" -Echos control characters in hat notation (e\&.g\&. ^A) -.IP "\fB\f(CWechoe=\fP\fP" -.IP "\fB\f(CWechok=\fP\fP" -.IP "\fB\f(CWechoke=\fP\fP" -.IP "\fB\f(CWechonl=\fP\fP" -.IP "\fB\f(CWechoprt=\fP\fP" -.IP "\fB\f(CWeof=\fP\fP" -.IP "\fB\f(CWeol=\fP\fP" -.IP "\fB\f(CWeol2=\fP\fP" -.IP "\fB\f(CWerase=\fP\fP" -.IP "\fB\f(CWdiscard=\fP\fP" -.IP "\fB\f(CWff0\fP\fP" -.IP "\fB\f(CWff1\fP\fP" -.IP "\fB\f(CWffdly=\fP\fP" -.IP "\fB\f(CWflusho=\fP\fP" -.IP "\fB\f(CWhupcl=\fP\fP" -.IP "\fB\f(CWicrnl=\fP\fP" -.IP "\fB\f(CWiexten=\fP\fP" -.IP "\fB\f(CWigncr=\fP\fP" -.IP "\fB\f(CWignpar=\fP\fP" -.IP "\fB\f(CWimaxbel=\fP\fP" -.IP "\fB\f(CWinlcr=\fP\fP" -.IP "\fB\f(CWinpck=\fP\fP" -.IP "\fB\f(CWintr=\fP\fP" -.IP "\fB\f(CWisig=\fP\fP" -.IP "\fB\f(CWispeed=\fP\fP" -Set the baud rate for incoming data on this line\&. -.br -See also: ospeed, b19200 -dif(\fB\f(CWistrip=\fP\fP) -.IP "\fB\f(CWiuclc=\fP\fP" -.IP "\fB\f(CWixany=\fP\fP" -.IP "\fB\f(CWixoff=\fP\fP" -.IP "\fB\f(CWixon=\fP\fP" -.IP "\fB\f(CWkill=\fP\fP" -.IP "\fB\f(CWlnext=\fP\fP" -.IP "\fB\f(CWmin=\fP\fP" -.IP "\fB\f(CWnl0\fP\fP" -Sets the newline delay to 0\&. -.IP "\fB\f(CWnl1\fP\fP" -.IP "\fB\f(CWnldly=\fP\fP" -.IP "\fB\f(CWnoflsh=\fP\fP" -.IP "\fB\f(CWocrnl=\fP\fP" -.IP "\fB\f(CWofdel=\fP\fP" -.IP "\fB\f(CWofill=\fP\fP" -.IP "\fB\f(CWolcuc=\fP\fP" -.IP "\fB\f(CWonlcr=\fP\fP" -.IP "\fB\f(CWonlret=\fP\fP" -.IP "\fB\f(CWonocr=\fP\fP" -.IP "\fB\f(CWopost=\fP\fP" -Enables or disables output processing; e\&.g\&., converts NL to CR-NL\&. -.IP "\fB\f(CWospeed=\fP\fP" -Set the baud rate for outgoing data on this line\&. -.br -See also: ispeed, b19200 -.IP "\fB\f(CWparenb=\fP\fP" -Enable parity generation on output and parity checking for input\&. -.IP "\fB\f(CWparmrk=\fP\fP" -.IP "\fB\f(CWparodd=\fP\fP" -.IP "\fB\f(CWpendin=\fP\fP" -.IP "\fB\f(CWquit=\fP\fP" -.IP "\fB\f(CWreprint=\fP\fP" -.IP "\fB\f(CWsane\fP\fP" -Brings the terminal to something like a useful default state\&. -.IP "\fB\f(CWstart=\fP\fP" -.IP "\fB\f(CWstop=\fP\fP" -.IP "\fB\f(CWsusp=\fP\fP" -.IP "\fB\f(CWswtc=\fP\fP" -.IP "\fB\f(CWtab0\fP\fP" -.IP "\fB\f(CWtab1\fP\fP" -.IP "\fB\f(CWtab2\fP\fP" -.IP "\fB\f(CWtab3\fP\fP" -.IP "\fB\f(CWtabdly=\fP\fP" -.IP "\fB\f(CWtime=\fP\fP" -.IP "\fB\f(CWtostop=\fP\fP" -.IP "\fB\f(CWvt0\fP\fP" -.IP "\fB\f(CWvt1\fP\fP" -.IP "\fB\f(CWvtdly=\fP\fP" -.IP "\fB\f(CWwerase=\fP\fP" -.IP "\fB\f(CWxcase=\fP\fP" -.IP "\fB\f(CWxtabs\fP\fP" -.PP -.br -.PP -\fI\fBPTY option group\fP\fP -.PP -These options are intended for use with the pty address -type\&. -.PP -.IP "\fB\f(CWlink=\fP\fP" -Generates a symbolic link that points to the actual pseudo terminal -(pty)\&. This might help -to solve the problem that ptys are generated with more or less -unpredictable names, making it difficult to directly access the socat -generated pty automatically\&. With this option, the user can specify a "fix" -point in the file hierarchy that helps him to access the actual pty -(example)\&. -Beginning with \fBsocat\fP version 1\&.4\&.3, the symbolic link is removed when -the address is closed (but see option unlink-close)\&. -.IP "\fB\f(CWwait-slave\fP\fP" -Blocks the open phase until a process opens the slave side of the pty\&. -Usually, socat continues after generating the pty with opening the next -address or with entering the transfer loop\&. With the wait-slave option, -socat waits until some process opens the slave side of the pty before -continuing\&. -This option only works if the operating system provides the \f(CWpoll()\fP -system call\&. And it depends on an undocumented behaviour of pty\'s, so it -does not work on all operating systems\&. It has successfully been tested on -Linux, FreeBSD, NetBSD, and on Tru64 with openpty\&. -.IP "\fB\f(CWpty-intervall=\fP\fP" -When the wait-slave option is set, socat -periodically checks the HUP condition using \f(CWpoll()\fP to find if the pty\'s -slave side has been opened\&. The default polling intervall is 1s\&. Use the -pty-intervall option [timeval] to change this value\&. -.PP -.br -.PP -\fI\fBOPENSSL option group\fP\fP -.PP -These options apply to the openssl and -openssl-listen address types\&. -.PP -.IP "\fB\f(CWcipher=\fP\fP" -Selects the list of ciphers that may be used for the connection\&. -See the man page of \f(CWciphers\fP, section \fBCIPHER LIST FORMAT\fP, for -detailed information about syntax, values, and default of \&. -.br -Several cipher strings may be given, separated by \':\'\&. -Some simple cipher strings: -.IP "3DES" -Uses a cipher suite with triple DES\&. -.IP "MD5" -Uses a cipher suite with MD5\&. -.IP "aNULL" -Uses a cipher suite without authentication\&. -.IP "NULL" -Does not use encryption\&. -.IP "HIGH" -Uses a cipher suite with "high" encryption\&. -Note that the peer must support the selected property, or the negotiation -will fail\&. -.IP "\fB\f(CWmethod=\fP\fP" -Sets the protocol version to be used\&. Valid strings (not case sensitive) -are: -.IP "\f(CWSSLv2\fP" -Select SSL protocol version 2\&. -.IP "\f(CWSSLv3\fP" -Select SSL protocol version 3\&. -.IP "\f(CWSSLv23\fP" -Select SSL protocol version 2 or 3\&. This is the default when -this option is not provided\&. -.IP "\f(CWTLSv1\fP" -Select TLS protocol version 1\&. -.IP "\fB\f(CWverify=\fP\fP" -Controls check of the peer\'s certificate\&. Default is 1 (true)\&. Disabling -verify might open your socket for everyone, making the encryption useless! -.IP "\fB\f(CWcert=\fP\fP" -Specifies the file with the certificate and private key for authentication\&. -The certificate must be in OpenSSL format (*\&.pem)\&. -With openssl-listen, use of this option is strongly -recommended\&. Except with cipher aNULL, "no shared ciphers" error will -occur when no certificate is given\&. -.IP "\fB\f(CWkey=\fP\fP" -Specifies the file with the private key\&. The private key may be in this -file or in the file given with the cert option\&. The party that has -to proof that it is the owner of a certificate needs the private key\&. -.IP "\fB\f(CWdhparams=\fP\fP" -Specifies the file with the Diffie Hellman parameters\&. These parameters may -also be in the file given with the cert -option in which case the dhparams option is not needed\&. -.IP "\fB\f(CWcafile=\fP\fP" -Specifies the file with the trusted (root) authority certificates\&. The file -must be in PEM format and should contain one or more certificates\&. The party -that checks the authentication of its peer trusts only certificates that are -in this file\&. -.IP "\fB\f(CWcapath=\fP\fP" -Specifies the directory with the trusted (root) certificates\&. The directory -must contain certificates in PEM format and their hashes (see OpenSSL -documentation) -.IP "\fB\f(CWegd=\fP\fP" -On some systems, openssl requires an explicit source of random data\&. Specify -the socket name where an entropy gathering daemon like egd provides random -data, e\&.g\&. /dev/egd-pool\&. -.IP "\fB\f(CWpseudo\fP\fP" -On systems where openssl cannot find an entropy source and where no entropy -gathering daemon can be utilized, this option activates a mechanism for -providing pseudo entropy\&. This is archieved by taking the current time in -microseconds for feeding the libc pseudo random number generator with an -initial value\&. openssl is then feeded with output from random() calls\&. -.br -NOTE:This mechanism is not sufficient for generation of secure keys! -.IP "\fB\f(CWfips\fP\fP" -Enables FIPS mode if compiled in\&. For info about the FIPS encryption -implementation standard see http://oss-institute\&.org/fips-faq\&.html\&. -This mode might require that the involved certificates are generated with a -FIPS enabled version of openssl\&. Setting or clearing this option on one -socat address affects all OpenSSL addresses of this process\&. -.PP -.br -.PP -\fI\fBRETRY option group\fP\fP -.PP -Options that control retry of some system calls, especially connection -attempts\&. -.PP -.IP "\fB\f(CWretry=\fP\fP" -Number of retries before the connection or listen attempt is aborted\&. -Default is 0, which means just one attempt\&. -.IP "\fB\f(CWintervall=\fP\fP" -Time between consecutive attempts (seconds, -[timespec])\&. Default is 1 second\&. -.IP "\fB\f(CWforever\fP\fP" -Performs an unlimited number of retry attempts\&. -.PP -.br -.PP -\fI\fBTUN option group\fP\fP -.PP -Options that control Linux TUN/TAP interface device addresses\&. -.PP -.IP "\fB\f(CWtun-device=\fP\fP" -Instructs socat to take another path for the TUN clone device\&. Default is -\f(CW/dev/net/tun\fP\&. -.IP "\fB\f(CWtun-name=\fP\fP" -Gives the resulting network interface a specific name instead of the system -generated (tun0, tun1, etc\&.) -.IP "\fB\f(CWtun-type=[tun|tap]\fP\fP" -Sets the type of the TUN device; use this option to generate a TAP -device\&. See the Linux docu for the difference between these types\&. -When you try to establish a tunnel between two TUN devices, their types -should be the same\&. -.IP "\fB\f(CWiff-no-pi\fP\fP" -Sets the IFF_NO_PI flag which controls if the device includes additional -packet information in the tunnel\&. -When you try to establish a tunnel between two TUN devices, these flags -should have the same values\&. -.IP "\fB\f(CWiff-up\fP\fP" -Sets the TUN network interface status UP\&. Strongly recommended\&. -.IP "\fB\f(CWiff-broadcast\fP\fP" -Sets the BROADCAST flag of the TUN network interface\&. -.IP "\fB\f(CWiff-debug\fP\fP" -Sets the DEBUG flag of the TUN network interface\&. -.IP "\fB\f(CWiff-loopback\fP\fP" -Sets the LOOPBACK flag of the TUN network interface\&. -.IP "\fB\f(CWiff-pointopoint\fP\fP" -Sets the POINTOPOINT flag of the TUN device\&. -.IP "\fB\f(CWiff-notrailers\fP\fP" -Sets the NOTRAILERS flag of the TUN device\&. -.IP "\fB\f(CWiff-running\fP\fP" -Sets the RUNNING flag of the TUN device\&. -.IP "\fB\f(CWiff-noarp\fP\fP" -Sets the NOARP flag of the TUN device\&. -.IP "\fB\f(CWiff-promisc\fP\fP" -Sets the PROMISC flag of the TUN device\&. -.IP "\fB\f(CWiff-allmulti\fP\fP" -Sets the ALLMULTI flag of the TUN device\&. -.IP "\fB\f(CWiff-master\fP\fP" -Sets the MASTER flag of the TUN device\&. -.IP "\fB\f(CWiff-slave\fP\fP" -Sets the SLAVE flag of the TUN device\&. -.IP "\fB\f(CWiff-multicast\fP\fP" -Sets the MULTICAST flag of the TUN device\&. -.IP "\fB\f(CWiff-portsel\fP\fP" -Sets the PORTSEL flag of the TUN device\&. -.IP "\fB\f(CWiff-automedia\fP\fP" -Sets the AUTOMEDIA flag of the TUN device\&. -.IP "\fB\f(CWiff-dynamic\fP\fP" -Sets the DYNAMIC flag of the TUN device\&. -.PP -.br -.PP -.SH "DATA VALUES" -.PP -This section explains the different data types that address parameters and -address options can take\&. -.PP -.IP "address-range" -Is currently only implemented for IPv4 and IPv6\&. See address-option -`range\' -.IP "bool" -"0" or "1"; if value is omitted, "1" is taken\&. -.IP "byte" -An unsigned int number, read with \f(CWstrtoul()\fP, lower or equal to -\f(CWUCHAR_MAX\fP\&. -.IP "command-line" -A string specifying a program name and its arguments, separated by single -spaces\&. -.IP "data" -A raw data specification following \fIdalan\fP syntax\&. The only documented -form is a string starting with \'x\' followed by an even number of hex digits\&. -.IP "directory" -A string with usual UN*X directory name semantics\&. -.IP "facility" -The name of a syslog facility in lower case characters\&. -.IP "fdnum" -An unsigned int type, read with \f(CWstrtoul()\fP, specifying a UN*X file -descriptor\&. -.IP "filename" -A string with usual UN*X filename semantics\&. -.IP "group" -If the first character is a decimal digit, the value is read with -\f(CWstrtoul()\fP as unsigned integer specifying a group id\&. Otherwise, it -must be an existing group name\&. -.IP "int" -A number following the rules of the \f(CWstrtol()\fP function with base -"0", i\&.e\&. decimal number, octal number with leading "0", or hexadecimal -number with leading "0x"\&. The value must fit into a C int\&. -.IP "interface" -A string specifying the device name of a network interface, e\&.g\&. "eth0"\&. -.IP "IP address" -An IPv4 address in numbers-and-dots notation, an IPv6 address in hex -notation enclosed in brackets, or a hostname that resolves to an IPv4 or an -IPv6 address\&. -.br -Examples: 127\&.0\&.0\&.1, [::1], www\&.dest-unreach\&.org, dns1 -.IP "IPv4 address" -An IPv4 address in numbers-and-dots notation or a hostname that resolves to -an IPv4 address\&. -.br -Examples: 127\&.0\&.0\&.1, www\&.dest-unreach\&.org, dns2 -.IP "IPv6 address" -An iPv6 address in hexnumbers-and-colons notation enclosed in brackets, or a -hostname that resolves to an IPv6 address\&. -.br -Examples: [::1], [1234:5678:9abc:def0:1234:5678:9abc:def0], -ip6name\&.domain\&.org -.IP "long" -A number read with \f(CWstrtol()\fP\&. The value must fit into a C long\&. -.IP "long long" -A number read with \f(CWstrtoll()\fP\&. The value must fit into a C long long\&. -.IP "off_t" -An implementation dependend signed number, usually 32 bits, read with strtol -or strtoll\&. -.IP "off64_t" -An implementation dependend signed number, usually 64 bits, read with strtol -or strtoll\&. -.IP "mode_t" -An unsigned integer, read with \f(CWstrtoul()\fP, specifying mode (permission) -bits\&. -.IP "pid_t" -A number, read with \f(CWstrtol()\fP, specifying a process id\&. -.IP "port" -A uint16_t (16 bit unsigned number) specifying a TCP or UDP port, read -with \f(CWstrtoul()\fP\&. -.IP "protocol" -An unsigned 8 bit number, read with \f(CWstrtoul()\fP\&. -.IP "size_t" -An unsigned number with size_t limitations, read with \f(CWstrtoul\fP\&. -.IP "sockname" -A socket address\&. See address-option `bind\' -.IP "string" -A sequence of characters, not containing \'\e0\' and, depending on -the position within the command line, \':\', \',\', or "!!"\&. Note -that you might have to escape shell meta characters in the command line\&. -.IP "TCP service" -A service name, not starting with a digit, that is resolved by -\f(CWgetservbyname()\fP, or an unsigned int 16 bit number read with -\f(CWstrtoul()\fP\&. -.IP "timeval" -A double float specifying seconds; the number is mapped into a -struct timeval, consisting of seconds and microseconds\&. -.IP "timespec" -A double float specifying seconds; the number is mapped into a -struct timespec, consisting of seconds and nanoseconds\&. -.IP "UDP service" -A service name, not starting with a digit, that is resolved by -\f(CWgetservbyname()\fP, or an unsigned int 16 bit number read with -\f(CWstrtoul()\fP\&. -.IP "unsigned int" -A number read with \f(CWstrtoul()\fP\&. The value must fit into a C unsigned -int\&. -.IP "user" -If the first character is a decimal digit, the value is read with -\f(CWstrtoul()\fP as unsigned integer specifying a user id\&. Otherwise, it must -be an existing user name\&. -.PP -.SH "EXAMPLES" -.PP -.IP -.IP "\fB\f(CWsocat - TCP4:www\&.domain\&.org:80\fP\fP" -.IP -Transfers data between STDIO (-) and a -TCP4 connection to port 80 of host -www\&.domain\&.org\&. This example results in an interactive connection similar to -telnet or netcat\&. The stdin terminal parameters are not changed, so you may -close the relay with ^D or abort it with ^C\&. -.IP -\.LP -\.nf -\fBsocat -d -d READLINE,history=$HOME/.http_history \\ -TCP4:www.domain.org:www,crnl\fP -\.fi -.IP -.IP -This is similar to the previous example, but you can edit the current line in a -bash like manner (READLINE) and use the -history file \&.http_history; \fBsocat\fP -prints messages about progress (-d -d)\&. The port is specified by service name -(www), and correct network line termination characters (crnl) instead of NL -are used\&. -.IP -.IP "\fB\f(CWsocat TCP4-LISTEN:www TCP4:www\&.domain\&.org:www\fP\fP" -.IP -Installs a simple TCP port forwarder\&. With -TCP4-LISTEN it listens on local port "www" until a -connection comes in, accepts it, then connects to the remote host -(TCP4) and starts data transfer\&. It will not accept a -second connection\&. -.IP -\.LP -\.nf -\fBsocat -d -d -lmlocal2 \\ -TCP4-LISTEN:80,bind=myaddr1,reuseaddr,fork,su=nobody,range=10.0.0.0/8 \\ -TCP4:www.domain.org:80,bind=myaddr2\fP -\.fi -.IP -.IP -TCP port forwarder, each side bound to another local IP address -(bind)\&. This example handles an almost -arbitrary number of parallel or consecutive connections by -fork\'ing a new -process after each \f(CWaccept()\fP\&. It provides a little security by -su\'ing to user -nobody after forking; it only permits connections from the private 10 network (range); -due to reuseaddr, it allows immediate restart after master process\'s -termination, even if some child sockets are not completely shut down\&. -With -lmlocal2, socat logs to stderr until successfully -reaching the accept loop\&. Further logging is directed to syslog with facility -local2\&. -.IP -\.LP -\.nf -\fBsocat TCP4-LISTEN:5555,fork,tcpwrap=script \\ -EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr\fP -\.fi -.IP -.IP -A simple server that accepts connections -(TCP4-LISTEN) and fork\'s a new -child process for each connection; every child acts as single relay\&. -The client must match the rules for daemon process name "script" in -/etc/hosts\&.allow and /etc/hosts\&.deny, otherwise it is refused access (see "man -5 hosts_access")\&. -For EXEC\'uting the program, the child process -chroot\'s -to \fB/home/sandbox\fP, su\'s to user sandbox, and then starts -the program \fB/home/sandbox/bin/myscript\fP\&. \fBSocat\fP and -myscript communicate via a pseudo tty (pty); myscript\'s -stderr is redirected to stdout, -so its error messages are transferred via \fBsocat\fP to the connected client\&. -.IP -\.LP -\.nf -\fBsocat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \\ -TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512\fP -\.fi -.IP -.IP -\fBmail\&.sh\fP is a shell script, distributed with \fBsocat\fP, that implements a -simple -SMTP client\&. It is programmed to "speak" SMTP on its FDs 3 (in) and 4 (out)\&. -The fdin and fdout options tell \fBsocat\fP -to use these FDs for communication with -the program\&. Because mail\&.sh inherits stdin and stdout while \fBsocat\fP does not -use them, the script can read a -mail body from stdin\&. \fBSocat\fP makes alias1 your local source address -(bind), cares for correct network line termination -(crnl) and sends -at most 512 data bytes per packet (mss)\&. -.IP -.IP "\fB\f(CWsocat - /dev/ttyS0,raw,echo=0,crnl\fP\fP" -.IP -Opens an interactive connection via the serial line, e\&.g\&. for talking with a -modem\&. raw and echo set ttyS0\'s terminal -parameters to practicable values, crnl -converts to correct newline characters\&. Consider using -READLINE instead of `-\'\&. -.IP -\.LP -\.nf -\fBsocat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \\ -SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20\fP -\.fi -.IP -.IP -With UNIX-LISTEN, \fBsocat\fP opens a listening -UNIX domain socket \fB/tmp/\&.X11-unix/X1\fP\&. This path corresponds -to local XWindow display :1 on your machine, so XWindow client connections to -DISPLAY=:1 are accepted\&. \fBSocat\fP then speaks with -the SOCKS4 server host\&.victim\&.org that might permit -sourceport 20 based connections due to an FTP related -weakness in its static IP filters\&. \fBSocat\fP -pretends to be invoked by socksuser nobody, and -requests to be connected to -loopback port 6000 (only weak sockd configurations will allow this)\&. So we get -a connection to the victims XWindow server and, if it does not require MIT -cookies or Kerberos authentication, we can start work\&. Please note that there -can only be one connection at a time, because TCP can establish only one -session with a given set of addresses and ports\&. -.IP -.IP "\fB\f(CWsocat -u /tmp/readdata,seek-end=0,ignoreeof -\fP\fP" -.IP -This is an example for unidirectional data transfer -(-u)\&. \fBSocat\fP transfers data -from file /tmp/readdata (implicit address GOPEN), starting -at its current end (seek-end=0 lets \fBsocat\fP start -reading at current end of file; use seek=0 or no -seek option to first read the existing data) in a "tail -f" like mode -(ignoreeof)\&. The "file" -might also be a listening UNIX domain socket (do not use a seek option then)\&. -.IP -\.LP -\.nf -\fB(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) | -socat - EXEC:'ssh -l user server',pty,setsid,ctty\fP -\.fi -.IP -.IP -EXEC\'utes an ssh session to server\&. Uses a pty for communication between \fBsocat\fP and -ssh, makes it ssh\'s controlling tty (ctty), -and makes this pty the owner of -a new process group (setsid), so ssh accepts the password from \fBsocat\fP\&. -.IP -\.LP -\.nf -\fBsocat -u TCP4-LISTEN:3334,reuseaddr,fork \\ -OPEN:/tmp/in.log,creat,append\fP -\.fi -.IP -.IP -Implements a simple network based message collector\&. -For each client connecting to port 3334, a new child process is generated (option fork)\&. -All data sent by the clients are append\'ed to the file /tmp/in\&.log\&. -If the file does not exist, socat creat\'s it\&. -Option reuseaddr allows immediate restart of the server -process\&. -.IP -.IP -.IP "\fB\f(CWsocat READLINE,noecho=\'[Pp]assword:\' EXEC:\'ftp ftp\&.server\&.com\',pty,setsid,ctty\fP\fP" -.IP -Wraps a command line history (READLINE) around the EXEC\'uted ftp client utility\&. -This allows editing and reuse of FTP commands for relatively comfortable -browsing through the ftp directory hierarchy\&. The password is echoed! -pty is required to have ftp issue a prompt\&. -Nevertheless, there may occur some confusion with the password and FTP -prompts\&. -.IP -(\fB\f(CWsocat PTY,link=$HOME/dev/vmodem0,raw,echo=0,waitslave EXEC:\'"ssh modemserver\&.us\&.org socat - /dev/ttyS0,nonblock,raw,echo=0"\'\fP\fP) -.IP -Generates a pseudo terminal -device (PTY) on the client that can be reached under the -symbolic link \fB$HOME/dev/vmodem0\fP\&. -An application that expects a serial line or modem -can be configured to use \fB$HOME/dev/vmodem0\fP; its traffic will be directed -to a modemserver via ssh where another socat instance links it with -\fB/dev/ttyS0\fP\&. -.IP -\.LP -\.nf -\fBsocat TCP4-LISTEN:2022,reuseaddr,fork \\ -PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass\fP -\.fi -.IP -.IP -starts a forwarder that accepts connections on port 2022, and directs them -through the proxy daemon listening on port 3128 -(proxyport) on host proxy, using the -CONNECT method, where they are authenticated as "user" with "pass" (proxyauth)\&. The proxy -should establish connections to host www\&.domain\&.org on port 22 then\&. -.IP -.IP "\fB\f(CWsocat - SSL:server:4443,cafile=server\&.crt,cert=client\&.pem\fP\fP" -.IP -is an OpenSSL client that tries to establish a secure connection to an SSL -server\&. Option cafile specifies a file that -contains trust certificates: we trust the server only when it presents one of -these certificates and proofs that it owns the related private key\&. -Otherwise the connection is terminated\&. -With cert a file containing the client certificate -and the associated private key is specified\&. This is required in case the -server wishes a client authentication; many Internet servers do not\&. -.br -The first address (\'-\') can be replaced by almost any other socat address\&. -.IP -.IP "\fB\f(CWsocat SSL-LISTEN:4443,reuseaddr,pf=ip4,fork,cert=server\&.pem,cafile=client\&.crt PIPE\fP\fP" -.IP -is an OpenSSL server that accepts TCP connections, presents the certificate -from the file server\&.pem and forces the client to present a certificate that is -verified against cafile\&.crt\&. -.br -The second address (\'PIPE\') can be replaced by almost any other socat -address\&. -.br -For instructions on generating and distributing OpenSSL keys and certificates -see the additional socat docu \f(CWsocat-openssl\&.txt\fP\&. -.IP -.IP "\fB\f(CWecho |socat -u - file:/tmp/bigfile,create,largefile,seek=100000000000\fP\fP" -.IP -creates a 100GB sparse file; this requires a file system type that -supports this (ext2, ext3, reiserfs, jfs; not minix, vfat)\&. The operation of -writing 1 byte might take long (reiserfs: some minutes; ext2: "no" time), and -the resulting file can consume some disk space with just its inodes (reiserfs: -2MB; ext2: 16KB)\&. -.IP -.IP "\fB\f(CWsocat tcp-l:7777,reuseaddr,fork system:\'filan -i 0 -s >&2\',nofork\fP\fP" -.IP -listens for incoming TCP connections on port 7777\&. For each accepted -connection, invokes a shell\&. This shell has its stdin and stdout directly -connected to the TCP socket (nofork)\&. The shell starts filan and lets it print the socket addresses to -stderr (your terminal window)\&. -.IP -.IP "\fB\f(CWecho -e "\e0\e14\e0\e0\ec" |socat -u - file:/usr/bin/squid\&.exe,seek=0x00074420\fP\fP" -.IP -functions as primitive binary editor: it writes the 4 bytes 000 014 000 000 to -the executable /usr/bin/squid at offset 0x00074420 (this is a real world patch -to make the squid executable from Cygwin run under Windows, actual per May 2004)\&. -.IP -.IP "\fB\f(CWsocat - tcp:www\&.blackhat\&.org:31337,readbytes=1000\fP\fP" -.IP -connects to an unknown service and prevents being flooded\&. -.IP -.IP "\fB\f(CWsocat -U TCP:target:9999,end-close TCP-L:8888,reuseaddr,fork\fP\fP" -.IP -merges data arriving from different TCP streams on port 8888 to just one stream -to target:9999\&. The end-close option prevents the child -processes forked off by the second address from terminating the shared -connection to 9999 (close(2) just unlinks the inode which stays active as long -as the parent process lives; shutdown(2) would actively terminate the -connection)\&. -.IP -.IP "\fB\f(CWsocat - UDP4-DATAGRAM:192\&.168\&.1\&.0:123,sp=123,broadcast,range=192\&.168\&.1\&.0/24\fP\fP" -.IP -sends a broadcast to the network 192\&.168\&.1\&.0/24 and receives the replies of the -timeservers there\&. Ignores NTP packets from hosts outside this network\&. -.IP -.IP "\fB\f(CWsocat - IP4-DATAGRAM:255\&.255\&.255\&.255:44,broadcast,range=10\&.0\&.0\&.0/8\fP\fP" -.IP -sends a broadcast to the local network(s) using protocol 44\&. Accepts replies -from the private address range only\&. -.IP -.IP "\fB\f(CWsocat - UDP4-DATAGRAM:224\&.255\&.0\&.1:6666,bind=:6666,ip-add-membership=224\&.255\&.0\&.1:eth0\fP\fP" -.IP -transfers data from stdin to the specified multicast address using UDP\&. Both -local and remote ports are 6666\&. Tells the interface eth0 to also accept -multicast packets of the given group\&. Multiple hosts on the local network can -run this command, so all data sent by any of the hosts will be received -by all the other ones\&. Note that there are many possible reasons for failure, -including IP-filters, routing issues, wrong interface selection by the -operating system, bridges, or a badly configured switch\&. -.IP -.IP "\fB\f(CWsocat TCP:host2:4443 TUN:192\&.168\&.255\&.1/24,up\fP\fP" -.IP -establishes one side of a virtual (but not private!) network with host2 where a -similar process might run, with TCP-L and tun address 192\&.168\&.255\&.2\&. They -can reach each other using the addresses 192\&.168\&.255\&.1 and -192\&.168\&.255\&.2\&. Substitute the TCP link with an SSL connection protected by -client and server authentication (see OpenSSL -client and -server)\&. -.IP -.PP -.SH "DIAGNOSTICS" -.PP -\fBSocat\fP uses a logging mechanism that allows to filter messages by severity\&. The -severities provided are more or less compatible to the appropriate syslog -priority\&. With one or up to four occurrences of the -d command line option, the -lowest priority of messages that are issued can be selected\&. Each message -contains a single uppercase character specifying the messages severity (one of -F, E, W, N, I, or D) -.PP -.IP "FATAL:" -Conditions that require unconditional and immediate program termination\&. -.IP "ERROR:" -Conditions that prevent proper program processing\&. Usually the -program is terminated (see option -s)\&. -.IP "WARNING:" -Something did not function correctly or is in a state where -correct further processing cannot be guaranteed, but might be possible\&. -.IP "NOTICE:" -Interesting actions of the program, e\&.g\&. for supervising \fBsocat\fP in some kind of server mode\&. -.IP "INFO:" -Description of what the program does, and maybe why it -happens\&. Allows to monitor the lifecycles of file descriptors\&. -.IP "DEBUG:" -Description of how the program works, all system or library calls and their results\&. -.PP -Log messages can be written to stderr, to a file, or to syslog\&. -.PP -On exit, \fBsocat\fP gives status 0 if it terminated due to EOF or inactivity -timeout, with a positive value on error, and with a negative value on fatal -error\&. -.PP -.SH "FILES" -.PP -/usr/bin/socat -.br -/usr/bin/filan -.br -/usr/bin/procan -.PP -.SH "ENVIRONMENT VARIABLES" -.PP -.IP "\fBSOCAT_DEFAULT_LISTEN_IP\fP" -(Values 4 or 6) Sets the IP version to be used -for listen, recv, and recvfrom addresses if no pf -(protocol-family) option is given\&. Is overridden by socat options --4 or -6\&. -.IP -.IP "\fBSOCAT_PREFERRED_RESOLVE_IP\fP" -(Values 0, 4, or 6) Sets the IP version to -be used when resolving target host names when version is not specified by -address type, option pf (protocol-family), or -address format\&. If name resolution does not return a matching entry, the first -result (with differing IP version) is taken\&. With value 0, socat always selects -the first record and its IP version\&. -.IP -.IP "\fBSOCAT_FORK_WAIT\fP" -Specifies the time (seconds) to sleep the parent and -child processes after successful fork()\&. Useful for debugging\&. -.IP -.IP "\fBHOSTNAME\fP" -Is used to determine the hostname for logging (see --lh)\&. -.IP -.IP "\fBLOGNAME\fP" -Is used as name for the socks client user name if no -socksuser is given\&. -.br -With options su and -su-d, LOGNAME is set to the given user name\&. -.IP -.IP "\fBUSER\fP" -Is used as name for the socks client user name if no -socksuser is given and LOGNAME is empty\&. -.br -With options su and -su-d, USER is set to the given user name\&. -.IP -.IP "\fBSHELL\fP" -With options su and -su-d, SHELL is set to the login shell of the -given user\&. -.IP -.IP "\fBPATH\fP" -Can be set with option path for exec and -system addresses\&. -.IP -.IP "\fBHOME\fP" -With options su and -su-d, HOME is set to the home directory of the -given user\&. -.IP -.PP -.SH "CREDITS" -.PP -The work of the following groups and organizations was invaluable for this -project: -.PP -The \fIFSF\fP (GNU, http://www\&.fsf\&.org/ project -with their free and portable development software and -lots of other useful tools and libraries\&. -.PP -The \fILinux developers community\fP (http://www\&.linux\&.org/) for providing a free, open source operating -system\&. -.PP -The \fIOpen Group\fP (http://www\&.unix-systems\&.org/) for making their -standard specifications available on the Internet for free\&. -.PP -.SH "VERSION" -.PP -This man page describes version 1\&.6\&.0 of \fBsocat\fP\&. -.PP -.SH "BUGS" -.PP -Addresses cannot be nested, so a single socat process cannot, e\&.g\&., drive ssl -over socks\&. -.PP -Address option ftruncate without value uses default 1 instead of 0\&. -.PP -Verbose modes (-x and/or -v) display line termination characters inconsistently -when address options cr or crnl are used: They show the data \fIafter\fP -conversion in either direction\&. -.PP -The data transfer blocksize setting (-b) is ignored with address readline\&. -.PP -Send bug reports to -.PP -.SH "SEE ALSO" -.PP -nc(1), netcat6(1), sock(1), rinetd(8), cage(1), socks\&.conf(5), openssl(1), -stunnel(8), pty(1), rlwrap(1), setsid(1) -.PP -\fBSocat\fP home page http://www\&.dest-unreach\&.org/socat/ -.PP -.SH "AUTHOR" -.PP -Gerhard Rieger diff --git a/doc/socat.html b/doc/socat.html deleted file mode 100644 index 47e02fb..0000000 --- a/doc/socat.html +++ /dev/null @@ -1,2686 +0,0 @@ - - - - - - - - - - - - - - - - -socat - - - - - -
- -

socat

-

socat

-

March 2007

- - - -

- -

CONTENTS

- -NAME
-SYNOPSIS
-DESCRIPTION
-OPTIONS
-ADDRESS SPECIFICATIONS
-ADDRESS TYPES
-ADDRESS OPTIONS
-DATA VALUES
-EXAMPLES
-DIAGNOSTICS
-FILES
-ENVIRONMENT VARIABLES
-CREDITS
-VERSION
-BUGS
-SEE ALSO
-

-

NAME

- socat - Multipurpose relay (SOcket CAT) -

-

SYNOPSIS

- -socat [options] <address> <address>
-socat -V
-socat -h[h[h]] | -?[?[?]]
-filan
-procan -

-

DESCRIPTION

- -

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, 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 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, 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". -

-lf <logfile>
- Writes messages to <logfile> [filename] instead of - stderr. -

-ls
- Writes messages to stderr (this is the default). -

-lp<progname>
- Overrides the program name printed in error messages. -

-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 intervall 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. -
-

-

ADDRESS SPECIFICATIONS

- -

With the address command line arguments, the user gives socat instructions and -the necessary information for establishing the byte streams. -

An address specification usually consists of an address type -keyword, zero or more required address parameters separated by ':' from the keyword and -from each -other, and zero or more address options separated by ','. -

The keyword specifies the address type (e.g., TCP4, OPEN, EXEC). For some -keywords there exist synonyms ('-' for STDIO, TCP for TCP4). Keywords are case -insensitive. -For a few special address types, the keyword may be omitted: -Address specifications starting with a number are assumed to be FD (raw file -descriptor) addresses; -if a '/' is found before the first ':' or ',', GOPEN (generic file open) is -assumed. -

The required number and type of address parameters depend on the address -type. E.g., TCP4 requires a server specification (name or address), and a port -specification (number or service name). -

Zero or more address options may be given with each address. They influence the -address in some ways. -Options consist of an option keyword or an option keyword and a value, -separated by '='. Option keywords are case insensitive. -For filtering the options that are useful with an address -type, each option is member of one option group. For -each address type there is a set of option groups allowed. Only options -belonging to one of these address groups may be used (except with option -g). -

-Address specifications following the above schema are also called single -address specifications. -Two single addresses can be combined with "!!" to form a dual type -address for one channel. Here, the first address is used by socat for reading -data, and the -second address for writing data. There is no way to specify an option only once -for being applied to both single addresses. -

Usually, addresses are opened in read/write -mode. When an address is part of a dual address specification, or when -option -u or -U is used, an address might be -used only for reading or for writing. Considering this is important with some -address types. -

With socat version 1.5.0 and higher, the lexical analysis tries to handle -quotes and parenthesis meaningfully and allows escaping of special characters. -If one of the characters ( { [ ' is found, the corresponding closing -character - ) } ] ' - is looked for; they may also be nested. Within these -constructs, socats special characters and strings : , !! are not handled -specially. All those characters and strings can be escaped with \ or within "" -

-

ADDRESS TYPES

- -

This section describes the available address types with their keywords, -parameters, and semantics. -

-

CREATE:<filename>
- Opens <filename> with creat() and uses the file - descriptor for writing. - This address type requires write-only context, because a file opened with - creat cannot be read from. - <filename> must be a valid existing or not existing path. - If <filename> is a named pipe, creat() might block; - if <filename> refers to a socket, this is an error.
- Option groups: FD,REG,NAMED
- Useful options: - mode, - user, - group, - unlink-early, - unlink-late, - append
- See also: OPEN, GOPEN -

EXEC:<command-line>
- Forks a sub process that establishes communication with its parent process - and invokes the specified program with execvp(). - <command-line> is a simple command - with arguments separated by single spaces. If the program name - contains a '/', the part after the last '/' is taken as ARGV[0]. If the - program name is a relative - path, the execvp() semantics for finding the program via - $PATH - apply. After successful program start, socat writes data to stdin of the - process and reads from its stdout using a UNIX domain socket generated by - socketpair() per default. (example)
- Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
- Useful options: - path, - fdin, - fdout, - chroot, - su, - su-d, - nofork, - pty, - stderr, - ctty, - setsid, - pipes, - login, - sigint, - sigquit
- See also: SYSTEM -

FD:<fdnum>
- Uses the file descriptor <fdnum>. It must already exist as - valid UN*X file descriptor.
- Option groups: FD (TERMIOS,REG,SOCKET)
- See also: - STDIO, - STDIN, - STDOUT, - STDERR -

GOPEN:<filename>
- (Generic open) This address type tries to handle any file system entry - except directories usefully. <filename> may be a - relative or absolute path. If it already exists, its type is checked. - In case of a UNIX domain socket, socat connects; if connecting fails, - socat assumes a datagram socket and uses sendto() calls. - If the entry is not a socket, socat opens it applying the O_APPEND - flag. - If it does not exist, it is opened with flag - O_CREAT as a regular file (example).
- Option groups: FD,REG,SOCKET,NAMED,OPEN
- See also: - OPEN, - CREATE, - UNIX-CONNECT -

IP-SENDTO:<host>:<protocol>
- Opens a raw IP socket. Depending on host specification or option pf, IP procotol version - 4 or 6 is used. It uses <protocol> to send packets - to <host> [IP address] and receives packets from - host, ignores packets from other hosts. - Protocol 255 uses the raw socket with the IP header being part of the - data.
- Option groups: FD,SOCKET,IP4,IP6
- Useful options: - pf, - ttl - See also: - IP4-SENDTO, - IP6-SENDTO, - IP-RECVFROM, - IP-RECV, - UDP-SENDTO - UNIX-SENDTO -

IP4-SENDTO:<host>:<protocol>
- Like IP-SENDTO, but always uses IPv4.
- Option groups: FD,SOCKET,IP4
-

IP6-SENDTO:<host>:<protocol>
- Like IP-SENDTO, but always uses IPv6.
- Option groups: FD,SOCKET,IP6
-

IP-DATAGRAM:<address>:<protocol>
- Sends outgoing data to the specified address which may in particular be a - broadcast or multicast address. Packets arriving on the local socket are - checked if their source addresses match - eventual RANGE or TCPWRAP - options. This address type can for example be used for implementing - symmetric or asymmetric broadcast or multicast communications.
- Option groups: FD, SOCKET, - IP4, IP6, RANGE
- Useful options: - range, - tcpwrap, - broadcast, - ip-multicast-loop, - ip-multicast-ttl, - ip-multicast-if, - ip-add-membership, - ttl, - tos, - bind, - pf
- See also: - IP4-DATAGRAM, - IP6-DATAGRAM, - IP-SENDTO, - IP-RECVFROM, - IP-RECV, - UDP-DATAGRAM -

IP4-DATAGRAM:<host>:<protocol>
- Like IP-DATAGRAM, but always uses IPv4. - (example)
- Option groups: FD, SOCKET, - IP4, RANGE
-

IP6-DATAGRAM:<host>:<protocol>
- Like IP-DATAGRAM, but always uses IPv6. Please - note that IPv6 does not know broadcasts.
- Option groups: FD, SOCKET, - IP6, RANGE
-

IP-RECVFROM:<protocol>
- Opens a raw IP socket of <protocol>. Depending on option pf, IP procotol version - 4 or 6 is used. It receives one packet from an unspecified peer and may send one or more answer packets to that peer. - This mode is particularly useful with fork option where each arriving packet - from arbitrary peers - is handled by its own sub process. - This allows a behaviour similar to typical UDP based servers like ntpd or named. - This address works well with IP-SENDTO address peers (see above). - Protocol 255 uses the raw socket with the IP header being part of the - data.
- Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
- Useful options: - pf, - fork, - range, - ttl, - broadcast
- See also: - IP4-RECVFROM, - IP6-RECVFROM, - IP-SENDTO, - IP-RECV, - UDP-RECVFROM, - UNIX-RECVFROM -

IP4-RECVFROM:<protocol>
- Like IP-RECVFROM, but always uses IPv4.
- Option groups: FD,SOCKET,IP4,CHILD,RANGE
-

IP6-RECVFROM:<protocol>
- Like IP-RECVFROM, but always uses IPv6.
- Option groups: FD,SOCKET,IP6,CHILD,RANGE
-

IP-RECV:<protocol>
- Opens a raw IP socket of <protocol>. Depending on option pf, IP procotol version - 4 or 6 is used. It receives packets from multiple unspecified peers and merges the data. - No replies are possible. - It can be, e.g., addressed by socat IP-SENDTO address peers. - Protocol 255 uses the raw socket with the IP header being part of the - data.
- Option groups: FD,SOCKET,IP4,IP6,RANGE
- Useful options: - pf, - range
- See also: - IP4-RECV, - IP6-RECV, - IP-SENDTO, - IP-RECVFROM, - UDP-RECV, - UNIX-RECV -

IP4-RECV:<protocol>
- Like IP-RECV, but always uses IPv4.
- Option groups: FD,SOCKET,IP4,RANGE
-

IP6-RECV:<protocol>
- Like IP-RECV, but always uses IPv6.
- Option groups: FD,SOCKET,IP6,RANGE
-

OPEN:<filename>
- Opens <filename> using the open() system call - (example). - This operation fails on UNIX domain sockets.
- Note: This address type is rarly useful in bidirectional mode.
- Option groups: FD,REG,NAMED,OPEN
- Useful options: - creat, - excl, - noatime, - nofollow, - append, - rdonly, - wronly, - lock, - readbytes, - ignoreeof
- See also: - CREATE, - GOPEN, - UNIX-CONNECT -

OPENSSL:<host>:<port>
- Tries to establish a SSL connection to <port> [TCP - service] on - <host> [IP address] using TCP/IP version 4 or 6 - depending on address specification, name resolution, or option - pf.
- NOTE: The server certificate is only checked for validity against - cafile or capath, - but not for match with the server's name or its IP address!
- Option groups: FD,SOCKET,IP4,IP6,TCP,OPENSSL,RETRY
- Useful options: - cipher, - method, - verify, - cafile, - capath, - certificate, - bind, - pf, - connect-timeout, - sourceport, - retry
- See also: - OPENSSL-LISTEN, - TCP -

OPENSSL-LISTEN:<port>
- Listens on tcp <port> [TCP service]. - The IP version is 4 or the one specified with - pf. When a - connection is accepted, this address behaves as SSL server.
- Note: You probably want to use the certificate option with this address.
- NOTE: The client certificate is only checked for validity against - cafile or capath, - but not for match with the client's name or its IP address!
- Option groups: FD,SOCKET,IP4,IP6,TCP,LISTEN,OPENSSL,CHILD,RANGE,RETRY
- Useful options: - pf, - cipher, - method, - verify, - cafile, - capath, - certificate, - fork, - bind, - range, - tcpwrap, - su, - reuseaddr, - retry
- See also: - OPENSSL, - TCP -

PIPE:<filename>
- If <filename> already exists, it is opened. - If is does not exist, a named pipe is created and opened. Beginning with - socat version 1.4.3, the named pipe is removed when the address is closed - (but see option unlink-close
- Note: When a pipe is used for both reading and writing, it works - as echo service.
- Note: When a pipe is used for both reading and writing, and socat tries - to write more bytes than the pipe can buffer (Linux 2.4: 2048 bytes), socat - might block. Consider using socat option, e.g., -b 2048
- Option groups: FD,NAMED,OPEN
- Useful options: - rdonly, - nonblock, - group, - user, - mode, - unlink-early
- See also: unnamed pipe -

PIPE
- Creates an unnamed pipe and uses it for reading and writing. It works as an - echo, because everything written - to it appeares immediately as read data.
- Note: When socat tries to write more bytes than the pipe can queue (Linux - 2.4: 2048 bytes), socat might block. Consider, e.g., using - option -b 2048
- Option groups: FD
- See also: named pipe -

PROXY:<proxy>:<hostname>:<port>
- Connects to an HTTP proxy server on port 8080 using TCP/IP version 4 or 6 - depending on address specification, name resolution, or option - pf, and sends a CONNECT - request for hostname:port. If the proxy grants access and succeeds to - connect to the target, data transfer between socat and the target can - start. Note that the traffic need not be HTTP but can be an arbitrary - protocol.
- Option groups: FD,SOCKET,IP4,IP6,TCP,HTTP,RETRY
- Useful options: - proxyport, - ignorecr, - proxyauth, - resolve, - crnl, - bind, - connect-timeout, - mss, - sourceport, - retry
- See also: SOCKS, TCP -

PTY
- Generates a pseudo terminal (pty) and uses its master side. Another process - may open the pty's slave side using it like a serial line or terminal. - (example). If - both the ptmx and the openpty mechanisms are available, ptmx is used - (POSIX).
- Option groups: FD,NAMED,PTY,TERMIOS
- Useful options: - link, - openpty, - wait-slave, - mode, - user, - group
- See also: - UNIX-LISTEN, - PIPE, - EXEC, SYSTEM -

READLINE
- Uses GNU readline and history on stdio to allow editing and reusing input - lines (example). This requires the GNU readline and - history libraries. Note that stdio should be a (pseudo) terminal device, - otherwise readline does not seem to work.
- Option groups: FD,READLINE,TERMIOS
- Useful options: - history, - noecho
- See also: - STDIO -

SOCKS4:<socks-server>:<host>:<port>
- Connects via <socks-server> [IP address] - to <host> [IPv4 address] - on <port> [TCP service], - using socks version 4 protocol over IP version 4 or 6 depending on address specification, name resolution, or option - pf (example).
- Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
- Useful options: - socksuser, - socksport, - sourceport, - pf, - retry
- See also: - SOCKS4A, - PROXY, - TCP -

SOCKS4A:<socks-server>:<host>:<port>
- like SOCKS4, but uses socks protocol version 4a, thus - leaving host name resolution to the socks server.
- Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
-

STDERR
- Uses file descriptor 2.
- Option groups: FD (TERMIOS,REG,SOCKET)
- See also: FD -

STDIN
- Uses file descriptor 0.
- Option groups: FD (TERMIOS,REG,SOCKET)
- Useful options: - readbytes
- See also: FD -

STDIO
- Uses file descriptor 0 for reading, and 1 for writing.
- Option groups: FD (TERMIOS,REG,SOCKET)
- Useful options: - readbytes
- See also: FD -

STDOUT
- Uses file descriptor 1.
- Option groups: FD (TERMIOS,REG,SOCKET)
- See also: FD -

SYSTEM:<shell-command>
- Forks a sub process that establishes communication with its parent process - and invokes the specified program with system(). Please note that - <shell-command> [string] must - not contain ',' or "!!", and that shell meta characters may have to be - protected. - After successful program start, socat writes data to stdin of the - process and reads from its stdout.
- Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
- Useful options: - path, - fdin, - fdout, - chroot, - su, - su-d, - nofork, - pty, - stderr, - ctty, - setsid, - pipes, - sigint, - sigquit
- See also: EXEC -

TCP:<host>:<port>
- Connects to <port> [TCP service] on - <host> [IP address] using TCP/IP version 4 or 6 - depending on address specification, name resolution, or option - pf.
- Option groups: FD,SOCKET,IP4,IP6,TCP,RETRY
- Useful options: - crnl, - bind, - pf, - connect-timeout, - tos, - mtudiscover, - mss, - nodelay, - nonblock, - sourceport, - retry, - readbytes
- See also: - TCP4, - TCP6, - TCP-LISTEN, - UDP, - UNIX-CONNECT -

TCP4:<host>:<port>
- Like TCP, but only supports IPv4 protocol (example).
- Option groups: FD,SOCKET,IP4,TCP,RETRY
-

TCP6:<host>:<port>
- Like TCP, but only supports IPv6 protocol.
- Option groups: FD,SOCKET,IP6,TCP,RETRY
-

TCP-LISTEN:<port>
- Listens on <port> [TCP service] and accepts a - TCP/IP connection. The IP version is 4 or the one specified with - pf. - Note that opening - this address usually blocks until a client connects.
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,TCP,RETRY
- Useful options: - crnl, - fork, - bind, - range, - tcpwrap, - pf, - backlog, - mss, - su, - reuseaddr, - retry, - retry
- See also: - TCP4-LISTEN, - TCP6-LISTEN, - UDP-LISTEN, - UNIX-LISTEN, - OPENSSL-LISTEN -

TCP4-LISTEN:<port>
- Like TCP-LISTEN, but only supports IPv4 - protocol (example).
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,TCP,RETRY
-

TCP6-LISTEN:<port>
- Like TCP-LISTEN, but only supports IPv6 - protocol.
- Additional useful option: - ipv6only
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,TCP,RETRY
-

TUN:<if-addr>/<bits>
- Creates a Linux TUN/TAP device and assignes to it the address and netmask - defined by the parameters. The resulting network interface is ready for use - by other processes; socat serves its "wire side". This address requires read - and write access to the tunnel cloning device, usually /dev/net/tun. -
- Option groups: FD,NAMED,OPEN,TUN
- Useful options: - iff-up, - tun-device, - tun-name, - tun-type, - iff-no-pi
- See also: - ip-recv -

UDP:<host>:<port>
- Connects to <port> [UDP service] on - <host> [IP address] using UDP/IP version 4 or 6 - depending on address specification, name resolution, or option - pf.
- Please note that, - due to UDP protocol properties, no real connection is established; data has - to be sent for `connecting' to the server, and no end-of-file condition can - be transported.
- Option groups: FD,SOCKET,IP4,IP6
- Useful options: - ttl, - tos, - bind, - sourceport, - pf
- See also: - UDP4, - UDP6, - UDP-LISTEN, - TCP, - IP -

UDP4:<host>:<port>
- Like UDP, but only supports IPv4 protocol.
- Option groups: FD,SOCKET,IP4
-

UDP6:<host>:<port>
- Like UDP, but only supports IPv6 protocol.
- Option groups: FD,SOCKET,IP6
-

UDP-DATAGRAM:<address>:<port>
- Sends outgoing data to the specified address which may in particular be a - broadcast or multicast address. Packets arriving on the local socket are - checked for the correct remote port and if their source addresses match - eventual RANGE or TCPWRAP - options. This address type can for example be used for implementing - symmetric or asymmetric broadcast or multicast communications.
- Option groups: FD,SOCKET,IP4,IP6,RANGE
- Useful options: - range, - tcpwrap, - broadcast, - ip-multicast-loop, - ip-multicast-ttl, - ip-multicast-if, - ip-add-membership, - ttl, - tos, - bind, - sourceport, - pf
- See also: - UDP4-DATAGRAM, - UDP6-DATAGRAM, - UDP-SENDTO, - UDP-RECVFROM, - UDP-RECV, - UDP-CONNECT, - UDP-LISTEN, - IP-DATAGRAM -

UDP4-DATAGRAM:<address>:<port>
- Like UDP-DATAGRAM, but only supports IPv4 - protocol (example1, - example2).
- Option groups: FD, SOCKET, - IP4, RANGE -

UDP6-DATAGRAM:<address>:<port>
- Like UDP-DATAGRAM, but only supports IPv6 - protocol.
- Option groups: FD,SOCKET, - IP6,RANGE -

UDP-LISTEN:<port>
- Waits for a UDP/IP packet arriving on <port> - [UDP service] and `connects' back to sender. - The accepted IP version is 4 or the one specified with option - pf. - Please note that, - due to UDP protocol properties, no real connection is established; data has - to arrive from the peer first, and no end-of-file condition can be - transported. Note that opening - this address usually blocks until a client connects.
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6
- Useful options: - fork, - bind, - range, - pf
- See also: - UDP, - UDP4-LISTEN, - UDP6-LISTEN, - TCP-LISTEN -

UDP4-LISTEN:<port>
- Like UDP-LISTEN, but only support IPv4 - protocol.
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4
-

UDP6-LISTEN:<port>
- Like UDP-LISTEN, but only support IPv6 - protocol.
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6
-

UDP-SENDTO:<host>:<port>
- Communicates with the specified peer socket, defined by <port> [UDP - service] on - <host> [IP address], using UDP/IP version 4 or 6 - depending on address specification, name resolution, or option - pf. It sends packets to and receives packets - from that peer socket only. - This address effectively implements a datagram client. - It works well with socat UDP-RECVFROM and UDP-RECV address peers.
- Option groups: FD,SOCKET,IP4,IP6
- Useful options: - ttl, - tos, - bind, - sourceport, - pf
- See also: - UDP4-SENDTO, - UDP6-SENDTO, - UDP-RECVFROM, - UDP-RECV, - UDP-CONNECT, - UDP-LISTEN, - IP-SENDTO -

UDP4-SENDTO:<host>:<port>
- Like UDP-SENDTO, but only supports IPv4 - protocol.
- Option groups: FD,SOCKET,IP4 -

UDP6-SENDTO:<host>:<port>
- Like UDP-SENDTO, but only supports IPv6 - protocol.
- Option groups: FD,SOCKET,IP6 -

UDP-RECVFROM:<port>
- Creates a UDP socket on <port> [UDP service] using - UDP/IP version 4 or 6 - depending on option pf. - It receives one packet from an unspecified peer and may send one or more - answer packets to that peer. This mode is particularly useful with fork - option - where each arriving packet - from arbitrary peers - is handled by its own sub - process. This allows a behaviour similar to typical UDP based servers like ntpd - or named. This address works well with socat SENDTO address peers.
- Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
- Useful options: - fork, - ttl, - tos, - bind, - sourceport, - pf
- See also: - UDP4-RECVFROM, - UDP6-RECVFROM, - UDP-SENDTO, - UDP-RECV, - UDP-CONNECT, - UDP-LISTEN, - IP-RECVFROM, - UNIX-RECVFROM -

UDP4-RECVFROM:<port>
- Like UDP-RECVFROM, but only supports IPv4 protocol.
- Option groups: FD,SOCKET,IP4,CHILD,RANGE -

UDP6-RECVFROM:<port>
- Like UDP-RECVFROM, but only supports IPv6 protocol.
- Option groups: FD,SOCKET,IP6,CHILD,RANGE -

UDP-RECV:<port>
- Creates a UDP socket on <port> [UDP service] using UDP/IP version 4 or 6 - depending on option pf. - It receives packets from multiple unspecified peers and merges the data. - No replies are possible. It works well with, e.g., socat UDP-SENDTO address peers; it behaves similar to a syslog server.
- Option groups: FD,SOCKET,IP4,IP6,RANGE
- Useful options: - fork, - pf, - bind, - sourceport, - ttl, - tos
- See also: - UDP4-RECV, - UDP6-RECV, - UDP-SENDTO, - UDP-RECVFROM, - UDP-CONNECT, - UDP-LISTEN, - IP-RECV, - UNIX-RECV -

UDP4-RECV:<port>
- Like UDP-RECV, but only supports IPv4 protocol.
- Option groups: FD,SOCKET,IP4,RANGE -

UDP6-RECV:<port>
- Like UDP-RECV, but only supports IPv6 protocol.
- Option groups: FD,SOCKET,IP6,RANGE -

UNIX-CONNECT:<filename>
- Connects to <filename> assuming it is a UNIX domain - socket. - If <filename> does not exist, this is an error; - if <filename> is not a UNIX domain socket, this is an error; - if <filename> is a UNIX domain socket, but no process is listening, this is - an error.
- Option groups: FD,SOCKET, - NAMED,RETRY, - UNIX
) - Useful options: - bind
- See also: - UNIX-LISTEN, - UNIX-SENDTO, - TCP -

UNIX-LISTEN:<filename>
- Listens on <filename> using a UNIX domain stream - socket and accepts a connection. - If <filename> exists and is not a socket, this is an error. - If <filename> exists and is a UNIX domain socket, binding to the address - fails (use option unlink-early!). - Note that opening this address usually blocks until a client connects. - Beginning with socat version 1.4.3, the file system entry is removed when - this address is closed (but see option unlink-close) (example).
- Option groups: FD,SOCKET, - NAMED,LISTEN, - CHILD,RETRY, - UNIX
- Useful options: - fork, - umask, - mode, - user, - group, - unlink-early
- See also: - UNIX-CONNECT, - UNIX-RECVFROM, - UNIX-RECV, - TCP-LISTEN -

UNIX-SENDTO:<filename>
- Communicates with the specified peer socket, defined by [<filename>] assuming it is a UNIX domain datagram socket. - It sends packets to and receives packets from that peer socket only. - It works well with socat UNIX-RECVFROM and UNIX-RECV address peers.
- Option groups: FD,SOCKET, - NAMED,UNIX
- Useful options: - bind
- See also: - UNIX-RECVFROM, - UNIX-RECV, - UNIX-CONNECT, - UDP-SENDTO, - IP-SENDTO -

UNIX-RECVFROM:<filename>
- Creates a UNIX domain datagram socket [<filename>]. - Receives one packet and may send one or more answer packets to that peer. - This mode is particularly useful with fork option where each arriving packet - from arbitrary peers - is handled by its own sub process. - This address works well with socat UNIX-SENDTO address peers.
- Option groups: FD,SOCKET, - NAMED,CHILD, - UNIX
- Useful options: - fork
- See also: - UNIX-SENDTO, - UNIX-RECV, - UNIX-LISTEN, - UDP-RECVFROM, - IP-RECVFROM -

UNIX-RECV:<filename>
- Creates a UNIX domain datagram socket [<filename>]. - Receives packets from multiple unspecified peers and merges the data. - No replies are possible. It can be, e.g., addressed by socat UNIX-SENDTO address peers. - It behaves similar to a syslog server. - Option groups: FD,SOCKET, - NAMED,UNIX
- See also: - UNIX-SENDTO, - UNIX-RECVFROM, - UNIX-LISTEN, - UDP-RECV, - IP-RECV -

UNIX-CLIENT:<filename>
- Communicates with the specified peer socket, defined by - [<filename>] assuming it is a UNIX domain socket. - It first tries to connect and, if that fails, assumes it is a datagram - socket, thus supporting both types.
- Option groups: FD,SOCKET, - NAMED,UNIX
- Useful options: - bind
- See also: - UNIX-CONNECT, - UNIX-SENDTO, - GOPEN -

ABSTRACT-CONNECT:<string>
-

ABSTRACT-LISTEN:<string>
-

ABSTRACT-SENDTO:<string>
-

ABSTRACT-RECVFROM:<string>
-

ABSTRACT-RECV:<string>
-

ABSTRACT-CLIENT:<string>
- The ABSTRACT addresses are almost identical to the related UNIX addresses - except that they do not address file system based sockets but an alternate - UNIX domain address space. To archieve this the socket address strings are - prefixed with "\0" internally. This feature is available (only?) on Linux. - Option groups are the same as with the related UNIX addresses, except that - the ABSTRACT addresses are not member of the NAMED group. -
-

-

ADDRESS OPTIONS

- -

Address options can be applied to address specifications to influence the -process of opening the addresses and the -properties of the resulting data channels. -

For technical reasons not every option can be -applied to every address type; e.g., applying a socket option to a regular file -will fail. To catch most useless combinations as early as in the open phase, -the concept of option groups was introduced. Each option belongs to one -or more option groups. Options can be used only with address types that support -at least one of their option groups (but see option -g). -

Address options have data types that their values must conform to. -Every address option consists of just a keyword or a keyword followed by -"=value", where value must conform to the options type. - -Some address options manipulate parameters of system calls; -e.g., option sync sets the O_SYNC flag with the open() call. -Other options cause a system or library call; e.g., with option `ttl=value' -the setsockopt(fd, SOL_IP, IP_TTL, value, sizeof(int)) call is applied. -Other -options set internal socat variables that are used during data transfer; -e.g., `crnl' causes explicit character conversions. -A few options have more complex implementations; e.g., su-d -(substuser-delayed) inquires some user and group infos, stores them, and -applies them later after a possible chroot() call. -

If multiple options are given to an address, their sequence in the address specification has (almost) no -effect on the sequence of their execution/application. Instead, socat has -built in an option phase model that tries to bring the options in a useful -order. Some options exist in different forms (e.g., -unlink, unlink-early, unlink-late) to control the time of their execution. -

If the same option is specified more than once within one address -specification, with equal or different values, the effect depends on the kind of option. Options -resulting in function calls like setsockopt() cause multiple -invocations. With options that set parameters for a required call like -open() -or set internal flags, the value of the last option occurrence is effective. -

The existence or semantics of many options are system dependent. Socat -usually does NOT try to emulate missing libc or kernel features, it just -provides an -interface to the underlying system. So, if an operating system lacks a feature, -the related option is simply not available on this platform. -

The following paragraphs introduce just the more common address options. For -a more comprehensive reference and to find information about canonical option -names, alias names, option phases, and platforms see file xio.help. -

-


-

FD option group -

This option group contains options that are applied to a UN*X -style file descriptor, no matter how it was generated. -Because all current socat address types are file descriptor based, these -options may be applied to any address.
-Note: Some of these options are also member of another option group, that -provides an other, non-fd based mechanism. -For these options, it depends on the actual address type and its option groups -which mechanism is used. The second, non-fd based mechanism is prioritized. -

-

cloexec=<bool>
- Sets the FD_CLOEXEC flag with the fcntl() system call to value - <bool>. If set, - the file descriptor is closed on exec() family function calls. Socat - internally handles - this flag for the fds it controls, so in most cases there will be no need to - apply this option. -

setlk
- Tries to set a discretionary write lock to the whole file using the fcntl(fd, - F_SETLK, ...) system call. If the file is already locked, this call results - in an error. - On Linux, when the file permissions for group are "S" (g-x,g+s), and the - file system is locally mounted with the "mand" option, the lock is - mandatory, i.e. prevents other processes from opening the file. -

setlkw
- Tries to set a discretionary waiting write lock to the whole file using the - fcntl(fd, F_SETLKW, ...) system call. If the file is already locked, - this call blocks. - See option setlk for information about making this - lock mandatory. -

setlk-rd
- Tries to set a discretionary read lock to the whole file using the fcntl(fd, - F_SETLK, ...) system call. If the file is already write locked, this call - results in an error. - See option setlk for information about making this - lock mandatory. -

setlkw-rd
- Tries to set a discretionary waiting read lock to the whole file using the - fcntl(fd, F_SETLKW, ...) system call. If the file is already write - locked, this call blocks. - See option setlk for information about making this - lock mandatory. -

flock-ex
- Tries to set a blocking exclusive advisory lock to the file using the - flock(fd, LOCK_EX) system call. Socat hangs in this call if the file - is locked by another process. -

flock-ex-nb
- Tries to set a nonblocking exclusive advisory lock to the file using the - flock(fd, LOCK_EX|LOCK_NB) system call. If the file is already locked, - this option results in an error. -

flock-sh
- Tries to set a blocking shared advisory lock to the file using the - flock(fd, LOCK_SH) system call. Socat hangs in this call if the file - is locked by another process. -

flock-sh-nb
- Tries to set a nonblocking shared advisory lock to the file using the - flock(fd, LOCK_SH|LOCK_NB) system call. If the file is already locked, - this option results in an error. -

lock
- Sets a blocking lock on the file. Uses the setlk or flock mechanism - depending on availability on the particular platform. If both are available, - the POSIX variant (setlkw) is used. -

user=<user>
- Sets the <user> (owner) of the stream. - If the address is member of the NAMED option group, - socat uses the chown() system call after opening the - file or binding to the UNIX domain socket (race condition!). - Without filesystem entry, socat sets the user of the stream - using the fchown() system call. - These calls might require root privilege. -

user-late=<user>
- Sets the owner of the fd to <user> with the fchown() - system call after opening - or connecting the channel. - This is useful only on file system entries. -

group=<group>
- Sets the <group> of the stream. - If the address is member of the NAMED option group, - socat uses the chown() system call after opening the - file or binding to the UNIX domain socket (race condition!). - Without filesystem entry, socat sets the group of the stream - with the fchown() system call. - These calls might require group membership or root privilege. -

group-late=<group>
- Sets the group of the fd to <group> with the - fchown() system call after opening - or connecting the channel. - This is useful only on file system entries. -

mode=<mode>
- Sets the <mode> [mode_t] (permissions) of the stream. - If the address is member of the NAMED option group and - uses the open() or creat() call, the mode is applied with these. - If the address is member of the NAMED option group without using these - system calls, socat uses the chmod() system call after opening the - filesystem entry or binding to the UNIX domain socket (race condition!). - Otherwise, socat sets the mode of the stream - using fchmod(). - These calls might require ownership or root privilege. -

perm-late=<mode>
- Sets the permissions of the fd to value <mode> - [mode_t] using the fchmod() system call after - opening or connecting the channel. - This is useful only on file system entries. -

append=<bool>
- Always writes data to the actual end of file. - If the address is member of the OPEN option group, - socat uses the O_APPEND flag with the open() system call - (example). - Otherwise, socat applies the fcntl(fd, F_SETFL, O_APPEND) call. -

nonblock=<bool>
- Tries to open or use file in nonblocking mode. Its only effects are that the - connect() call of TCP addresses does not block, and that opening a - named pipe for reading does not block. - If the address is member of the OPEN option group, - socat uses the O_NONBLOCK flag with the open() system call. - Otherwise, socat applies the fcntl(fd, F_SETFL, O_NONBLOCK) call. - - -

binary
- Opens the file in binary mode to avoid implicit line terminator - conversions (Cygwin). -

text
- Opens the file in text mode to force implicit line terminator conversions - (Cygwin). -

noinherit
- Does not keep this file open in a spawned process (Cygwin). -

cool-write
- Takes it easy when write fails with EPIPE or ECONNRESET and logs the message - with notice level instead of error. - This prevents the log file from being filled with useless error messages - when socat is used as a high volume server or proxy where clients often - abort the connection.
- This option is experimental. -

end-close
- Changes the (address dependent) method of ending a connection to just close - the file descriptors. This is useful when the connection is to be reused by - or shared with other processes (example).
- Normally, socket connections will be ended with shutdown(2) which - terminates the socket even if it is shared by multiple processes. - close(2) "unlinks" the socket from the process but keeps it active as - long as there are still links from other processes.
- Similarly, when an address of type EXEC or SYSTEM is ended, socat usually - will explicitely kill the sub process. With this option, it will just close - the file descriptors. -
-


-

NAMED option group -

These options work on file system entries.
-See also options user, group, and -mode. -

-

user-early=<user>
- Changes the <user> (owner) of the file system entry before - accessing it, using the - chown() system call. This call might require root privilege. -

group-early=<group>
- Changes the <group> of the file system entry before - accessing it, using the - chown() system call. This call might require group membership or root - privilege. -

perm-early=<mode>
- Changes the <mode> [mode_t] of the file system entry - before accessing it, using the - chmod() system call. This call might require ownership or root - privilege. -

umask=<mode>
- Sets the umask of the process to <mode> [mode_t] before - accessing the file system entry (useful - with UNIX domain sockets!). This call might affect all further operations - of the socat process! -

unlink-early
- Unlinks (removes) the file before opening it and even before applying - user-early etc. -

unlink
- Unlinks (removes) the file before accessing it, but after user-early etc. -

unlink-late
- Unlinks (removes) the file after opening it to make it inaccessible for - other processes after a short race condition. -

unlink-close
- Removes the addresses file system entry when closing the address. - For named pipes, - listening unix domain sockets, - and the symbolic links of pty addresses, - the default is 1; for created files, - opened files, - generic opened files, and - client unix domain sockets the default is 0. -
-


-

OPEN option group -

The OPEN group options allow to set flags with the open() system call. -E.g., option `creat' sets the O_CREAT flag.
-See also options append and -nonblock. -

-

creat=<bool>
- Creates the file if it does not exist (example). -

dsync=<bool>
- Blocks write() calls until metainfo is physically written to media. -

excl=<bool>
- With option creat, if file exists this is an error. -

largefile=<bool>
- On 32 bit systems, allows a file larger than 2^31 bytes. -

noatime
- Sets the O_NOATIME options, so reads do not change the access timestamp. -

noctty=<bool>
- Does not make this file the controlling terminal. -

nofollow=<bool>
- Does not follow symbolic links. -

nshare=<bool>
- Does not allow to share this file with other processes. -

rshare=<bool>
- Does not allow other processes to open this file for writing. -

rsync=<bool>
- Blocks write() until metainfo is physically written to media. -

sync=<bool>
- Blocks write() until data is physically written to media. - - - - -

rdonly=<bool>
- Opens the file for reading only. - -

wronly=<bool>
- Opens the file for writing only. -

trunc
- Truncates the file to size 0 during opening it. -
-


-

REG and BLK option group -

These options are usually applied to a UN*X file descriptor, but their -semantics make sense only on a file supporting random access. -

-

seek=<offset>
- Applies the lseek(fd, <offset>, SEEK_SET) (or lseek64) system - call, thus positioning the file pointer absolutely to <offset> - [off_t or off64_t]. -

seek-cur=<offset>
- Applies the lseek(fd, <offset>, SEEK_CUR) (or lseek64) system - call, thus positioning the file pointer <offset> [off_t or - off64_t] bytes relatively to its current position (which - is usually 0). -

seek-end=<offset>
- Applies the lseek(fd, <offset>, SEEK_END) (or lseek64) system - call, thus positioning the file pointer <offset> [off_t or - off64_t] bytes relatively to the files current end. -

ftruncate=<offset>
- Applies the ftruncate(fd, <offset>) - (or ftruncate64 if available) system call, thus - truncating the file at the position <offset> [off_t or - off64_t]. -

secrm=<bool>
-

unrm=<bool>
-

compr=<bool>
-

ext2-sync=<bool>
-

immutable=<bool>
-

ext2-append=<bool>
-

nodump=<bool>
-

ext2-noatime=<bool>
-

journal-data=<bool>
-

notail=<bool>
-

dirsync=<bool>
- These options change non standard file attributes on operating systems and - file systems that support these features, like Linux with ext2fs, - ext3fs, or reiserfs. See man 1 chattr for information on these options. - Please note that there might be a race condition between creating the file - and applying these options. -
-


-

PROCESS option group -

Options of this group change the process properties instead of just affecting -one data channel. -For EXEC and SYSTEM addresses and for LISTEN and CONNECT type addresses with -option FORK, -these options apply to the child processes instead of the main socat process. -

-

chroot=<directory>
- Performs a chroot() operation to <directory> - after processing the address (example). This call might require root privilege. -

chroot-early=<directory>
- Performs a chroot() operation to <directory> - before opening the address. This call might require root privilege. -

setgid=<group>
- Changes the primary <group> of the process after - processing the address. This call might require root privilege. -

setgid-early=<group>
- Changes the primary <group> of the process before opening - the address. This call might require root privilege. -

setuid=<user>
- Changes the <user> (owner) of the process after processing - the address. This call might require root privilege. -

setuid-early=<user>
- Changes the <user> (owner) of the process before opening - the address. This call might require root privilege. -

su=<user>
- Changes the <user> (owner) and groups of the process after - processing the address (example). This call might require root privilege. -

su-d=<user>
- Short name for substuser-delayed. - Changes the <user> - (owner) and groups of the process after processing the address (example). - The user and his groups are retrieved before a possible - chroot(). This call might require root privilege. -

setpgid=<pid_t>
- Makes the process a member of the specified process group - <pid_t>. If no value - is given, or if the value is 0 or 1, the process becomes leader of a new - process group. -

setsid
- Makes the process the leader of a new session (example). -
-


-

READLINE option group -

These options apply to the readline address type. -

-

history=<filename>
- Reads and writes history from/to <filename> (example). -

noprompt
- Since version 1.4.0, socat per default tries to determine a prompt - - that is then passed to the readline call - by remembering the last - incomplete line of the output. With this option, socat does not pass a - prompt to readline, so it begins line editing in the first column - of the terminal. -

noecho=<pattern>
- Specifies a regular pattern for a prompt that prevents the following input - line from being displayed on the screen and from being added to the history. - The prompt is defined as the text that was output to the readline address - after the lastest newline character and before an input character was - typed. The pattern is a regular expression, e.g. - "^[Pp]assword:.*$" or "([Uu]ser:|[Pp]assword:)". See regex(7) for details. - (example) -

prompt=<string>
- Passes the string as prompt to the readline function. readline prints this - prompt when stepping through the history. If this string matches a constant - prompt issued by an interactive program on the other socat address, - consistent look and feel can be archieved. -
-


-

APPLICATION option group -

This group contains options that work at data level. -Note that these options only apply to the "raw" data transferred by socat, -but not to protocol data used by addresses like -PROXY. -

-

cr
- Converts the default line termination character NL ('\n', 0x0a) to/from CR - ('\r', 0x0d) when writing/reading on this channel. -

crnl
- Converts the default line termination character NL ('\n', 0x0a) to/from CRNL - ("\r\n", 0x0d0a) when writing/reading on this channel (example). - Note: socat simply strips all CR characters. -

ignoreeof
- When EOF occurs on this channel, socat ignores it and tries to read more - data (like "tail -f") (example). -

readbytes=<bytes>
- socat reads only so many bytes from this address (the address provides - only so many bytes for transfer and pretends to be at EOF afterwards). - Must be greater than 0. -

lockfile=<filename>
- If lockfile exists, exits with error. If lockfile does not exist, creates it - and continues, unlinks lockfile on exit. -

waitlock=<filename>
- If lockfile exists, waits until it disappears. When lockfile does not exist, - creates it and continues, unlinks lockfile on exit. -
-


-

SOCKET option group -

These options are intended for all kinds of sockets, e.g. IP or UNIX domain. Most are applied with a setsockopt() call. -

-

bind=<sockname>
- Binds the socket to the given socket address using the bind() system - call. The form of <sockname> is socket domain dependent: - IP4 and IP6 allow the form [hostname|hostaddress][:(service|port)] (example), - UNIX domain sockets require <filename>. -

connect-timeout=<seconds>
- Abort the connection attempt after <seconds> [timeval] - with error status. -

interface=<interface>
- Binds the socket to the given <interface>. - This option might require root privilege. -

broadcast
- For datagram sockets, allows sending to broadcast addresses and receiving - packets addressed to broadcast addresses. -

bsdcompat
- Emulates some (old?) bugs of the BSD socket implementation. -

debug
- Enables socket debugging. -

dontroute
- Only communicates with directly connected peers, does not use routers. -

keepalive
- Enables sending keepalives on the socket. -

linger=<seconds>
- Blocks shutdown() or close() until data transfers have finished - or the given timeout [int] expired. - -

oobinline
- Places out-of-band data in the input data stream. -

priority=<priority>
- Sets the protocol defined <priority> [<int>] for outgoing - packets. -

rcvbuf=<bytes>
- Sets the size of the receive buffer after the socket() call to - <bytes> [int]. With TCP - sockets, this value corresponds to the socket's maximal window size. -

rcvbuf-late=<bytes>
- Sets the size of the receive buffer when the socket is already - connected to <bytes> [int]. - With TCP sockets, this value corresponds to the socket's - maximal window size. -

rcvlowat=<bytes>
- Specifies the minimum number of received bytes [int] until - the socket layer will pass the buffered data to socat. -

rcvtimeo=<seconds>
- Sets the receive timeout [timeval]. -

reuseaddr
- Allows other sockets to bind to an address even if parts of it (e.g. the - local port) are already in use by socat (example). -

sndbuf=<bytes>
- Sets the size of the send buffer after the socket() call to - <bytes> [int]. -

sndbuf-late=<bytes>
- Sets the size of the send buffer when the socket is connected to - <bytes> [int]. -

sndlowat=<bytes>
- Specifies the minimum number of bytes in the send buffer until the socket - layer will send the data to <bytes> [int]. -

sndtimeo=<seconds>
- Sets the send timeout to seconds [timeval]. -

type=<type>
- Sets the type of the socket, usually as argument to the socket() or - socketpair() call, to <type> [int]. - Under Linux, 1 means stream oriented socket, 2 means datagram socket, and 3 - means raw socket. - - - - - - - - - - - - - - - - - - - - - -

pf=<string>
- Forces the use of the specified IP version. <string> can be - something like "ip4" or "ip6". -
-


-

UNIX option group -

These options apply to UNIX domain based addresses. -

-

unix-tightsocklen=[0|1]
- On socket operations, pass a socket address length that does not include the - whole struct sockaddr_un record but (besides other components) only - the relevant part of the filename or abstract string. Default is 1. -
-

-IP4 and IP6 option groups -

These options can be used with IPv4 and IPv6 based sockets. -

-

tos=<tos>
- Sets the TOS (type of service) field of outgoing packets to <tos> - [byte] (see RFC 791). -

ttl=<ttl>
- Sets the TTL (time to live) field of outgoing packets to <ttl> - [byte]. -

ipoptions=<data>
- Sets IP options like source routing. Must be given in binary form, - recommended format is a leading "x" followed by an even number of hex - digits. This option may be used multiple times, data are appended. - E.g., to connect to host 10.0.0.1 via some gateway using a loose source - route, use the gateway as address parameter and set a loose source route - using the option ipoptions=x8307040a000001.
- IP options are defined in RFC 791.
- -

mtudiscover=<0|1|2>
- Takes 0, 1, 2 to never, want, or always use path MTU discover on this - socket. - - - - - - - - - - - - -

ip-add-membership=<multicast-address:interface-address>
-

ip-add-membership=<multicast-address:interface-name>
-

ip-add-membership=<multicast-address:interface-index>
-

ip-add-membership=<multicast-address:interface-address:interface-name>
-

ip-add-membership=<multicast-address:interface-address:interface-index>
- Makes the socket member of the specified multicast group. This is currently - only implemented for IPv4. The option takes the IP address of the multicast - group and info about the desired network interface. The most common syntax - is the first one, while the others are only available on systems that - provide struct mreqn (Linux).
- The indices of active network interfaces can be shown using the utility - procan. - -dif(ip-multicast-if=<hostname>) - Specifies hostname or address of the network interface to be used for - multicast traffic. - -dif(ip-multicast-loop=<bool>) - Specifies if outgoing multicast traffic should loop back to the interface. - -dif(ip-multicast-ttl=<byte>) - Sets the TTL used for outgoing multicast traffic. Default is 1. -

res-debug
-

res-aaonly
-

res-usevc
-

res-primary
-

res-igntc
-

res-recurse
-

res-defnames
-

res-stayopen
-

res-dnsrch
- These options set the corresponding resolver (name resolution) option flags. - Append "=0" to clear a default option. See man resolver(5) for more - information on these options. Note: these options are valid only for the - address they are applied to. -

-


-

IP6 option group -

These options can only be used on IPv6 based sockets. See IP -options for options that can be applied to both IPv4 and IPv6 -sockets. -

-

ipv6only=<bool>
- Sets the IPV6_V6ONLY socket option. If 0, the TCP stack will also accept - connections using IPv4 protocol on the same port. The default is system - dependent. -
-


-

TCP option group -

These options may be applied to TCP sockets. They work by invoking setsockopt() with the appropriate parameters. -

-

cork
- Doesn't send packets smaller than MSS (maximal segment size). -

defer-accept
- While listening, accepts connections only when data from the peer arrived. -

keepcnt=<count>
- Sets the number of keepalives before shutting down the socket to - <count> [int]. -

keepidle=<seconds>
- Sets the idle time before sending the first keepalive to <seconds> - [int]. -

keepintvl=<seconds>
- Sets the intervall between two keepalives to <seconds> - [int]. -

linger2=<seconds>
- Sets the time to keep the socket in FIN-WAIT-2 state to <seconds> - [int]. -

mss=<bytes>
- Sets the MSS (maximum segment size) after the socket() call to <bytes> - [int]. This - value is then proposed to the peer with the SYN or SYN/ACK packet - (example). -

mss-late=<bytes>
- Sets the MSS of the socket after connection has been established to <bytes> - [int]. -

nodelay
- Turns off the Nagle algorithm for measuring the RTT (round trip time). -

rfc1323
- Enables RFC1323 TCP options: TCP window scale, round-trip time measurement - (RTTM), and protect against wrapped sequence numbers (PAWS) (AIX). -

stdurg
- Enables RFC1122 compliant urgent pointer handling (AIX). -

syncnt=<count>
- Sets the maximal number of SYN retransmits during connect to <count> - [int]. - - -

md5sig
- Enables generation of MD5 digests on the packets (FreeBSD). -

noopt
- Disables use of TCP options (FreeBSD, MacOSX). -

nopush
- sets the TCP_NOPUSH socket option (FreeBSD, MacOSX). -

sack-disable
- Disables use the selective acknowledge feature (OpenBSD). -

signature-enable
- Enables generation of MD5 digests on the packets (OpenBSD). -

abort-threshold=<milliseconds>
- Sets the time to wait for an answer of the peer on an established connection - (HP-UX). -

conn-abort-threshold=<milliseconds>
- Sets the time to wait for an answer of the server during the initial connect - (HP-UX). -

keepinit
- Sets the time to wait for an answer of the server during connect() before - giving up. Value in half seconds, default is 150 (75s) (Tru64). -

paws
- Enables the "protect against wrapped sequence numbers" feature (Tru64). -

sackena
- Enables selective acknowledge (Tru64). -

tsoptena
- Enables the time stamp option that allows RTT recalculation on existing - connections (Tru64). -
-


-

UDP and TCP option groups -

Here we find options that are related to the network port mechanism and that -thus can be used with UDP and TCP, client and server addresses. -

-

sourceport=<port>
- For outgoing (client) TCP and UDP connections, it sets the source - <port> using an extra bind() call. - With TCP or UDP listen addresses, socat immediately shuts down the - connection if the client does not use this sourceport (example). -

lowport
- Outgoing (client) TCP and UDP connections with this option use - an unused random source port between 640 and 1023 incl. On UNIX class operating - systems, this requires root privilege, and thus indicates that the - client process is authorized by local root. - TCP and UDP listen addresses with this option immediately shut down the - connection if the client does not use a sourceport <= 1023. - This mechanism can provide limited authorization under some circumstances. -
-


-

SOCKS option group -

When using SOCKS type addresses, some socks specific options can be set. -

-

socksport=<tcp service>
- Overrides the default "socks" service or port 1080 for the socks server - port with <TCP service>. -

socksuser=<user>
- Sends the <user> [string] in the username field to the - socks server. Default is the actual user name ($LOGNAME or $USER) (example). -
-


-

HTTP option group -

Options that can be provided with HTTP type addresses. The only HTTP address -currently implemented is proxy-connect. -

-

proxyport=<TCP service>
- Overrides the default HTTP proxy port 8080 with - <TCP service>. -

ignorecr
- The HTTP protocol requires the use of CR+NL as line terminator. When a proxy - server violates this standard, socat might not understand its answer. - This option directs socat to interprete NL as line terminator and - to ignore CR in the answer. Nevertheless, socat sends CR+NL to the proxy. -

proxyauth=<username>:<password>
- Provide "basic" authentication to the proxy server. The argument to the - option is used with a "Proxy-Authorization: Base" header in base64 encoded - form.
- Note: username and password are visible for every user on the local machine - in the process list; username and password are transferred to the proxy - server unencrypted (base64 encoded) and might be sniffed. -

resolve
- Per default, socat sends to the proxy a CONNECT request containing the - target hostname. With this option, socat resolves the hostname locally and - sends the IP address. Please note that, according to RFC 2396, only name - resolution to IPv4 addresses is implemented. -
-


-

RANGE option group -

These options check if a connecting client should be granted access. They can -be applied to listening and receiving network sockets. tcp-wrappers options -fall into this group. -

-

range=<address-range>
- After accepting a connection, tests if the peer is within range. For - IPv4 addresses, address-range takes the form address/bits, e.g. - 10.0.0.0/8, or address:mask, e.g. 10.0.0.0:255.0.0.0 (example); for IPv6, it is [ip6-address/bits], e.g. [::1/128]. - If the client address does not match, socat issues a warning and keeps - listening/receiving. -

tcpwrap[=<name>]
- Uses Wietse Venema's libwrap (tcpd) library to determine - if the client is allowed to connect. The configuration files are - /etc/hosts.allow and /etc/hosts.deny per default, see "man 5 hosts_access" - for more information. The optional <name> (type string) - is passed to the wrapper functions as daemon process name (example). - If omitted, the basename of socats invocation (argv[0]) is passed. - If both tcpwrap and range options are applied to an address, both - conditions must be fulfilled to allow the connection. -

allow-table=<filename>
- Takes the specified file instead of /etc/hosts.allow. -

deny-table=<filename>
- Takes the specified file instead of /etc/hosts.deny. -

tcpwrap-etc=<directoryname>
- Looks for hosts.allow and hosts.deny in the specified directory. Is - overridden by options hosts-allow - and hosts-deny. -
-


-

LISTEN option group -

Options specific to listening sockets. -

-

backlog=<count>
- Sets the backlog value passed with the listen() system call to <count> - [int]. Default is 5. -
-

-

CHILD option group -

Options for addresses with multiple connections via child processes. -

-

fork
- After establishing a connection, handles its channel in a child process and - keeps the parent process attempting to produce more connections, either by - listening or by connecting in a loop (example).
- SSL-CONNECT and SSL-LISTEN differ in when they actually fork off the child: -SSL-LISTEN forks before the SSL handshake, while SSL-CONNECT forks -afterwards. - RETRY and FOREVER options are not inherited by the child process.
-
-


-

EXEC option group -

Options for addresses that invoke a program. -

-

path=<string>
- Overrides the PATH environment variable for searching the program with - <string>. This - $PATH value is effective in the child process too. -

login
- Prefixes argv[0] for the execvp() call with '-', thus making a - shell behave as login shell. -
-


-

FORK option group -

EXEC or SYSTEM addresses invoke a program using a child process and transfer data between socat and the program. The interprocess communication mechanism can be influenced with the following options. Per -default, a socketpair() is created and assigned to stdin and stdout of -the child process, while stderr is inherited from the socat process, and the -child process uses file descriptors 0 and 1 for communicating with the main -socat process. -

-

nofork
- Does not fork a subprocess for executing the program, instead calls execvp() - or system() directly from the actual socat instance. This avoids the - overhead of another process between the program and its peer, - but introduces a lot of restrictions: -
-
  • this option can only be applied to the second socat address. -
  • it cannot be applied to a part of a dual address. -
  • the first socat address cannot be OPENSSL or READLINE -
  • socat options -b, -t, -D, -l, -v, -x become useless -
  • for both addresses, options ignoreeof, cr, and crnl become useless -
  • for the second address (the one with option nofork), options - append, cloexec, flock, user, group, mode, nonblock, - perm-late, setlk, and setpgid cannot be applied. Some of these could be - used on the first address though. -
    • -

    pipes
    - Creates a pair of unnamed pipes for interprocess communication instead of a - socket pair. -

    openpty
    - Establishes communication with the sub process using a pseudo terminal - created with openpty() instead of the default (socketpair or ptmx). -

    ptmx
    - Establishes communication with the sub process using a pseudo terminal - created by opening /dev/ptmx or /dev/ptc instead of the default - (socketpair). -

    pty
    - Establishes communication with the sub process using a pseudo terminal - instead of a socket pair. Creates the pty with an available mechanism. If - openpty and ptmx are both available, it uses ptmx because this is POSIX - compliant (example). -

    ctty
    - Makes the pty the controlling tty of the sub process (example). -

    stderr
    - Directs stderr of the sub process to its output channel by making stderr a - dup() of stdout (example). -

    fdin=<fdnum>
    - Assigns the sub processes input channel to its file descriptor - <fdnum> - instead of stdin (0). The program started from the subprocess has to use - this fd for reading data from socat (example). -

    fdout=<fdnum>
    - Assigns the sub processes output channel to its file descriptor - <fdnum> - instead of stdout (1). The program started from the subprocess has to use - this fd for writing data to socat (example). -

    sighup, sigint, sigquit
    - Has socat pass an eventual signal of this type to the sub process. - If no address has this option, socat terminates on these signals. -
    -


    -

    TERMIOS option group -

    For addresses that work on a tty (e.g., stdio, file:/dev/tty, exec:...,pty), the terminal parameters defined in the UN*X termios mechanism are made available as address option parameters. -Please note that changes of the parameters of your interactive terminal -remain effective after socat's termination, so you might have to enter "reset" -or "stty sane" in your shell afterwards. -For EXEC and SYSTEM addresses with option PTY, -these options apply to the pty by the child processes. -

    -

    b0
    - Disconnects the terminal. -

    b19200
    - Sets the serial line speed to 19200 baud. Some other rates are possible; use -something like socat -hh |grep ' b[1-9]' to find all speeds supported by -your implementation.
    -Note: On some operating systems, these options may not be -available. Use ispeed or ospeed -instead. -

    echo=<bool>
    - Enables or disables local echo (example). -

    icanon=<bool>
    - Sets or clears canonical mode, enabling line buffering and some special - characters. -

    raw
    - Sets raw mode, thus passing input and output almost unprocessed (example). -

    ignbrk=<bool>
    - Ignores or interpretes the BREAK character (e.g., ^C) -

    brkint=<bool>
    -

    bs0
    -

    bs1
    -

    bsdly=<0|1>
    -

    clocal=<bool>
    -

    - - - - - -

    cr0
    -cr1
    -cr2
    -cr3
    - Sets the carriage return delay to 0, 1, 2, or 3, respectively. - 0 means no delay, the other values are terminal dependent. -

    crdly=<0|1|2|3>
    -

    cread=<bool>
    -

    crtscts=<bool>
    -

    - - - - - -

    cs5
    -cs6
    -cs7
    -cs8
    - Sets the character size to 5, 6, 7, or 8 bits, respectively. -

    csize=<0|1|2|3>
    -

    cstopb=<bool>
    - Sets two stop bits, rather than one. -

    dsusp=<byte>
    - Sets the value for the VDSUSP character that suspends the current foreground - process and reactivates the shell (all except Linux). -

    echoctl=<bool>
    - Echos control characters in hat notation (e.g. ^A) -

    echoe=<bool>
    -

    echok=<bool>
    -

    echoke=<bool>
    -

    echonl=<bool>
    -

    echoprt=<bool>
    -

    eof=<byte>
    -

    eol=<byte>
    -

    eol2=<byte>
    -

    erase=<byte>
    -

    discard=<byte>
    -

    ff0
    -

    ff1
    -

    ffdly=<bool>
    -

    flusho=<bool>
    -

    hupcl=<bool>
    -

    icrnl=<bool>
    -

    iexten=<bool>
    -

    igncr=<bool>
    -

    ignpar=<bool>
    -

    imaxbel=<bool>
    -

    inlcr=<bool>
    -

    inpck=<bool>
    -

    intr=<byte>
    -

    isig=<bool>
    -

    ispeed=<unsigned-int>
    - Set the baud rate for incoming data on this line.
    - See also: ospeed, b19200 -dif(istrip=<bool>) -

    iuclc=<bool>
    -

    ixany=<bool>
    -

    ixoff=<bool>
    -

    ixon=<bool>
    -

    kill=<byte>
    -

    lnext=<byte>
    -

    min=<byte>
    -

    nl0
    - Sets the newline delay to 0. -

    nl1
    -

    nldly=<bool>
    -

    noflsh=<bool>
    -

    ocrnl=<bool>
    -

    ofdel=<bool>
    -

    ofill=<bool>
    -

    olcuc=<bool>
    -

    onlcr=<bool>
    -

    onlret=<bool>
    -

    onocr=<bool>
    -

    opost=<bool>
    - Enables or disables output processing; e.g., converts NL to CR-NL. -

    ospeed=<unsigned-int>
    - Set the baud rate for outgoing data on this line.
    - See also: ispeed, b19200 -

    parenb=<bool>
    - Enable parity generation on output and parity checking for input. -

    parmrk=<bool>
    -

    parodd=<bool>
    -

    pendin=<bool>
    -

    quit=<byte>
    -

    reprint=<byte>
    -

    sane
    - Brings the terminal to something like a useful default state. -

    start=<byte>
    -

    stop=<byte>
    -

    susp=<byte>
    -

    swtc=<byte>
    -

    tab0
    -

    tab1
    -

    tab2
    -

    tab3
    -

    tabdly=<unsigned-int>
    -

    time=<byte>
    -

    tostop=<bool>
    -

    vt0
    -

    vt1
    -

    vtdly=<bool>
    -

    werase=<byte>
    -

    xcase=<bool>
    -

    xtabs
    -
    -


    -

    PTY option group -

    These options are intended for use with the pty address -type. -

    -

    link=<filename>
    - Generates a symbolic link that points to the actual pseudo terminal - (pty). This might help - to solve the problem that ptys are generated with more or less - unpredictable names, making it difficult to directly access the socat - generated pty automatically. With this option, the user can specify a "fix" - point in the file hierarchy that helps him to access the actual pty - (example). - Beginning with socat version 1.4.3, the symbolic link is removed when - the address is closed (but see option unlink-close). -

    wait-slave
    - Blocks the open phase until a process opens the slave side of the pty. - Usually, socat continues after generating the pty with opening the next - address or with entering the transfer loop. With the wait-slave option, - socat waits until some process opens the slave side of the pty before - continuing. - This option only works if the operating system provides the poll() - system call. And it depends on an undocumented behaviour of pty's, so it - does not work on all operating systems. It has successfully been tested on - Linux, FreeBSD, NetBSD, and on Tru64 with openpty. -

    pty-intervall=<seconds>
    - When the wait-slave option is set, socat - periodically checks the HUP condition using poll() to find if the pty's - slave side has been opened. The default polling intervall is 1s. Use the - pty-intervall option [timeval] to change this value. -
    -


    -

    OPENSSL option group -

    These options apply to the openssl and -openssl-listen address types. -

    -

    cipher=<cipherlist>
    - Selects the list of ciphers that may be used for the connection. - See the man page of ciphers, section CIPHER LIST FORMAT, for - detailed information about syntax, values, and default of <cipherlist>.
    - Several cipher strings may be given, separated by ':'. - Some simple cipher strings: -
    -

    3DES
    Uses a cipher suite with triple DES. -

    MD5
    Uses a cipher suite with MD5. -

    aNULL
    Uses a cipher suite without authentication. -

    NULL
    Does not use encryption. -

    HIGH
    Uses a cipher suite with "high" encryption. -
    - Note that the peer must support the selected property, or the negotiation - will fail. -

    method=<ssl-method>
    - Sets the protocol version to be used. Valid strings (not case sensitive) - are: -
    -

    SSLv2
    Select SSL protocol version 2. -

    SSLv3
    Select SSL protocol version 3. -

    SSLv23
    Select SSL protocol version 2 or 3. This is the default when - this option is not provided. -

    TLSv1
    Select TLS protocol version 1. -
    -

    verify=<bool>
    - Controls check of the peer's certificate. Default is 1 (true). Disabling - verify might open your socket for everyone, making the encryption useless! -

    cert=<filename>
    - Specifies the file with the certificate and private key for authentication. - The certificate must be in OpenSSL format (*.pem). - With openssl-listen, use of this option is strongly - recommended. Except with cipher aNULL, "no shared ciphers" error will - occur when no certificate is given. -

    key=<filename>
    - Specifies the file with the private key. The private key may be in this - file or in the file given with the cert option. The party that has - to proof that it is the owner of a certificate needs the private key. -

    dhparams=<filename>
    - Specifies the file with the Diffie Hellman parameters. These parameters may - also be in the file given with the cert - option in which case the dhparams option is not needed. -

    cafile=<filename>
    - Specifies the file with the trusted (root) authority certificates. The file - must be in PEM format and should contain one or more certificates. The party - that checks the authentication of its peer trusts only certificates that are - in this file. -

    capath=<dirname>
    - Specifies the directory with the trusted (root) certificates. The directory - must contain certificates in PEM format and their hashes (see OpenSSL - documentation) -

    egd=<filename>
    - On some systems, openssl requires an explicit source of random data. Specify - the socket name where an entropy gathering daemon like egd provides random - data, e.g. /dev/egd-pool. -

    pseudo
    - On systems where openssl cannot find an entropy source and where no entropy - gathering daemon can be utilized, this option activates a mechanism for - providing pseudo entropy. This is archieved by taking the current time in - microseconds for feeding the libc pseudo random number generator with an - initial value. openssl is then feeded with output from random() calls.
    - NOTE:This mechanism is not sufficient for generation of secure keys! -

    fips
    - Enables FIPS mode if compiled in. For info about the FIPS encryption - implementation standard see http://oss-institute.org/fips-faq.html. - This mode might require that the involved certificates are generated with a - FIPS enabled version of openssl. Setting or clearing this option on one - socat address affects all OpenSSL addresses of this process. -
    -


    -

    RETRY option group -

    Options that control retry of some system calls, especially connection -attempts. -

    -

    retry=<num>
    - Number of retries before the connection or listen attempt is aborted. - Default is 0, which means just one attempt. -

    intervall=<timespec>
    - Time between consecutive attempts (seconds, - [timespec]). Default is 1 second. -

    forever
    - Performs an unlimited number of retry attempts. -
    -


    -

    TUN option group -

    Options that control Linux TUN/TAP interface device addresses. -

    -

    tun-device=<device-file>
    - Instructs socat to take another path for the TUN clone device. Default is - /dev/net/tun. -

    tun-name=<if-name>
    - Gives the resulting network interface a specific name instead of the system - generated (tun0, tun1, etc.) -

    tun-type=[tun|tap]
    - Sets the type of the TUN device; use this option to generate a TAP - device. See the Linux docu for the difference between these types. - When you try to establish a tunnel between two TUN devices, their types - should be the same. -

    iff-no-pi
    - Sets the IFF_NO_PI flag which controls if the device includes additional - packet information in the tunnel. - When you try to establish a tunnel between two TUN devices, these flags - should have the same values. -

    iff-up
    - Sets the TUN network interface status UP. Strongly recommended. -

    iff-broadcast
    - Sets the BROADCAST flag of the TUN network interface. -

    iff-debug
    - Sets the DEBUG flag of the TUN network interface. -

    iff-loopback
    - Sets the LOOPBACK flag of the TUN network interface. -

    iff-pointopoint
    - Sets the POINTOPOINT flag of the TUN device. -

    iff-notrailers
    - Sets the NOTRAILERS flag of the TUN device. -

    iff-running
    - Sets the RUNNING flag of the TUN device. -

    iff-noarp
    - Sets the NOARP flag of the TUN device. -

    iff-promisc
    - Sets the PROMISC flag of the TUN device. -

    iff-allmulti
    - Sets the ALLMULTI flag of the TUN device. -

    iff-master
    - Sets the MASTER flag of the TUN device. -

    iff-slave
    - Sets the SLAVE flag of the TUN device. -

    iff-multicast
    - Sets the MULTICAST flag of the TUN device. -

    iff-portsel
    - Sets the PORTSEL flag of the TUN device. -

    iff-automedia
    - Sets the AUTOMEDIA flag of the TUN device. -

    iff-dynamic
    - Sets the DYNAMIC flag of the TUN device. -
    -


    -

    -

    DATA VALUES

    - -

    This section explains the different data types that address parameters and -address options can take. -

    -

    address-range
    - Is currently only implemented for IPv4 and IPv6. See address-option - `range' -

    bool
    - "0" or "1"; if value is omitted, "1" is taken. -

    byte
    - An unsigned int number, read with strtoul(), lower or equal to - UCHAR_MAX. -

    command-line
    - A string specifying a program name and its arguments, separated by single - spaces. -

    data
    - A raw data specification following dalan syntax. The only documented - form is a string starting with 'x' followed by an even number of hex digits. -

    directory
    - A string with usual UN*X directory name semantics. -

    facility
    - The name of a syslog facility in lower case characters. -

    fdnum
    - An unsigned int type, read with strtoul(), specifying a UN*X file - descriptor. -

    filename
    - A string with usual UN*X filename semantics. -

    group
    - If the first character is a decimal digit, the value is read with - strtoul() as unsigned integer specifying a group id. Otherwise, it - must be an existing group name. -

    int
    - A number following the rules of the strtol() function with base - "0", i.e. decimal number, octal number with leading "0", or hexadecimal - number with leading "0x". The value must fit into a C int. -

    interface
    - A string specifying the device name of a network interface, e.g. "eth0". -

    IP address
    - An IPv4 address in numbers-and-dots notation, an IPv6 address in hex - notation enclosed in brackets, or a hostname that resolves to an IPv4 or an - IPv6 address.
    - Examples: 127.0.0.1, [::1], www.dest-unreach.org, dns1 -

    IPv4 address
    - An IPv4 address in numbers-and-dots notation or a hostname that resolves to - an IPv4 address.
    - Examples: 127.0.0.1, www.dest-unreach.org, dns2 -

    IPv6 address
    - An iPv6 address in hexnumbers-and-colons notation enclosed in brackets, or a - hostname that resolves to an IPv6 address.
    - Examples: [::1], [1234:5678:9abc:def0:1234:5678:9abc:def0], - ip6name.domain.org -

    long
    - A number read with strtol(). The value must fit into a C long. -

    long long
    - A number read with strtoll(). The value must fit into a C long long. -

    off_t
    - An implementation dependend signed number, usually 32 bits, read with strtol - or strtoll. -

    off64_t
    - An implementation dependend signed number, usually 64 bits, read with strtol - or strtoll. -

    mode_t
    - An unsigned integer, read with strtoul(), specifying mode (permission) - bits. -

    pid_t
    - A number, read with strtol(), specifying a process id. -

    port
    - A uint16_t (16 bit unsigned number) specifying a TCP or UDP port, read - with strtoul(). -

    protocol
    - An unsigned 8 bit number, read with strtoul(). -

    size_t
    - An unsigned number with size_t limitations, read with strtoul. -

    sockname
    - A socket address. See address-option `bind' -

    string
    - A sequence of characters, not containing '\0' and, depending on - the position within the command line, ':', ',', or "!!". Note - that you might have to escape shell meta characters in the command line. -

    TCP service
    - A service name, not starting with a digit, that is resolved by - getservbyname(), or an unsigned int 16 bit number read with - strtoul(). -

    timeval
    - A double float specifying seconds; the number is mapped into a - struct timeval, consisting of seconds and microseconds. -

    timespec
    - A double float specifying seconds; the number is mapped into a - struct timespec, consisting of seconds and nanoseconds. -

    UDP service
    - A service name, not starting with a digit, that is resolved by - getservbyname(), or an unsigned int 16 bit number read with - strtoul(). -

    unsigned int
    - A number read with strtoul(). The value must fit into a C unsigned - int. -

    user
    - If the first character is a decimal digit, the value is read with - strtoul() as unsigned integer specifying a user id. Otherwise, it must - be an existing user name. -
    -

    -

    EXAMPLES

    - -

    -

    -

    socat - TCP4:www.domain.org:80
    -

    Transfers data between STDIO (-) and a -TCP4 connection to port 80 of host -www.domain.org. This example results in an interactive connection similar to -telnet or netcat. The stdin terminal parameters are not changed, so you may -close the relay with ^D or abort it with ^C. -

    - - - - - -

    socat -d -d READLINE,history=$HOME/.http_history \
    -TCP4:www.domain.org:www,crnl
    -

    This is similar to the previous example, but you can edit the current line in a -bash like manner (READLINE) and use the -history file .http_history; socat -prints messages about progress (-d -d). The port is specified by service name -(www), and correct network line termination characters (crnl) instead of NL -are used. -

    -

    socat TCP4-LISTEN:www TCP4:www.domain.org:www
    -

    Installs a simple TCP port forwarder. With -TCP4-LISTEN it listens on local port "www" until a -connection comes in, accepts it, then connects to the remote host -(TCP4) and starts data transfer. It will not accept a -second connection. -

    - - - - - - - - -

    socat -d -d -lmlocal2 \
    -TCP4-LISTEN:80,bind=myaddr1,su=nobody,fork,range=10.0.0.0/8,reuseaddr \
    -TCP4:www.domain.org:80,bind=myaddr2
    -

    TCP port forwarder, each side bound to another local IP address -(bind). This example handles an almost -arbitrary number of parallel or consecutive connections by -fork'ing a new -process after each accept(). It provides a little security by -su'ing to user -nobody after forking; it only permits connections from the private 10 network (range); -due to reuseaddr, it allows immediate restart after master process's -termination, even if some child sockets are not completely shut down. -With -lmlocal2, socat logs to stderr until successfully -reaching the accept loop. Further logging is directed to syslog with facility -local2. -

    - - - - - - - - - -

    socat TCP4-LISTEN:5555,fork,tcpwrap=script \
    -EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr
    -

    A simple server that accepts connections -(TCP4-LISTEN) and fork's a new -child process for each connection; every child acts as single relay. -The client must match the rules for daemon process name "script" in -/etc/hosts.allow and /etc/hosts.deny, otherwise it is refused access (see "man -5 hosts_access"). -For EXEC'uting the program, the child process -chroot's -to /home/sandbox, su's to user sandbox, and then starts -the program /home/sandbox/bin/myscript. Socat and -myscript communicate via a pseudo tty (pty); myscript's -stderr is redirected to stdout, -so its error messages are transferred via socat to the connected client. -

    - - - - - - - -

    socat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \
    -TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512
    -

    mail.sh is a shell script, distributed with socat, that implements a -simple -SMTP client. It is programmed to "speak" SMTP on its FDs 3 (in) and 4 (out). -The fdin and fdout options tell socat -to use these FDs for communication with -the program. Because mail.sh inherits stdin and stdout while socat does not -use them, the script can read a -mail body from stdin. Socat makes alias1 your local source address -(bind), cares for correct network line termination -(crnl) and sends -at most 512 data bytes per packet (mss). -

    - - -

    socat - /dev/ttyS0,raw,echo=0,crnl
    -

    Opens an interactive connection via the serial line, e.g. for talking with a -modem. raw and echo set ttyS0's terminal -parameters to practicable values, crnl -converts to correct newline characters. Consider using -READLINE instead of `-'. -

    - - - - - - - -

    socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
    -SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20
    -

    With UNIX-LISTEN, socat opens a listening -UNIX domain socket /tmp/.X11-unix/X1. This path corresponds -to local XWindow display :1 on your machine, so XWindow client connections to -DISPLAY=:1 are accepted. Socat then speaks with -the SOCKS4 server host.victim.org that might permit -sourceport 20 based connections due to an FTP related -weakness in its static IP filters. Socat -pretends to be invoked by socksuser nobody, and -requests to be connected to -loopback port 6000 (only weak sockd configurations will allow this). So we get -a connection to the victims XWindow server and, if it does not require MIT -cookies or Kerberos authentication, we can start work. Please note that there -can only be one connection at a time, because TCP can establish only one -session with a given set of addresses and ports. -

    - -

    socat -u /tmp/readdata,seek-end=0,ignoreeof -
    -

    This is an example for unidirectional data transfer -(-u). Socat transfers data -from file /tmp/readdata (implicit address GOPEN), starting -at its current end (seek-end=0 lets socat start -reading at current end of file; use seek=0 or no -seek option to first read the existing data) in a "tail -f" like mode -(ignoreeof). The "file" -might also be a listening UNIX domain socket (do not use a seek option then). -

    - - - - - -

    (echo PASSWORD; sleep 5; echo ls; sleep 1) |
    -socat - EXEC:'ssh -l user server',pty,setsid,ctty
    -

    EXEC'utes an ssh session to server. Uses a pty for communication between socat and -ssh, makes it ssh's controlling tty (ctty), -and makes this pty the owner of -a new process group (setsid), so ssh accepts the password from socat. -

    - - - - - - -

    socat -u TCP4-LISTEN:3334,reuseaddr,fork \
    -OPEN:/tmp/in.log,creat,append
    -

    Implements a simple network based message collector. -For each client connecting to port 3334, a new child process is generated (option fork). -All data sent by the clients are append'ed to the file /tmp/in.log. -If the file does not exist, socat creat's it. -Option reuseaddr allows immediate restart of the server -process. -

    - -

    -

    socat READLINE,noecho='[Pp]assword:' EXEC:'ftp ftp.server.com',pty,setsid,ctty
    -

    Wraps a command line history (READLINE) around the EXEC'uted ftp client utility. -This allows editing and reuse of FTP commands for relatively comfortable -browsing through the ftp directory hierarchy. The password is echoed! - pty is required to have ftp issue a prompt. -Nevertheless, there may occur some confusion with the password and FTP -prompts. -

    - - - -(socat PTY,link=$HOME/dev/vmodem0,raw,echo=0,waitslave EXEC:'"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,raw,echo=0"') -

    Generates a pseudo terminal -device (PTY) on the client that can be reached under the -symbolic link $HOME/dev/vmodem0. -An application that expects a serial line or modem -can be configured to use $HOME/dev/vmodem0; its traffic will be directed -to a modemserver via ssh where another socat instance links it with -/dev/ttyS0. -

    - - - -

    socat TCP4-LISTEN:2022,reuseaddr,fork \
    -PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass
    -

    starts a forwarder that accepts connections on port 2022, and directs them -through the proxy daemon listening on port 3128 -(proxyport) on host proxy, using the -CONNECT method, where they are authenticated as "user" with "pass" (proxyauth). The proxy -should establish connections to host www.domain.org on port 22 then. -

    -

    socat - SSL:server:4443,cafile=server.crt,cert=client.pem
    -

    is an OpenSSL client that tries to establish a secure connection to an SSL -server. Option cafile specifies a file that -contains trust certificates: we trust the server only when it presents one of -these certificates and proofs that it owns the related private key. -Otherwise the connection is terminated. -With cert a file containing the client certificate -and the associated private key is specified. This is required in case the -server wishes a client authentication; many Internet servers do not.
    -The first address ('-') can be replaced by almost any other socat address. -

    -

    socat SSL-LISTEN:4443,reuseaddr,pf=ip4,fork,cert=server.pem,cafile=client.crt PIPE
    -

    is an OpenSSL server that accepts TCP connections, presents the certificate -from the file server.pem and forces the client to present a certificate that is -verified against cafile.crt.
    -The second address ('PIPE') can be replaced by almost any other socat -address.
    -For instructions on generating and distributing OpenSSL keys and certificates -see the additional socat docu socat-openssl.txt. -

    echo |socat -u - file:/tmp/bigfile,create,largefile,seek=100000000000
    -

    creates a 100GB sparse file; this requires a file system type that -supports this (ext2, ext3, reiserfs, jfs; not minix, vfat). The operation of -writing 1 byte might take long (reiserfs: some minutes; ext2: "no" time), and -the resulting file can consume some disk space with just its inodes (reiserfs: -2MB; ext2: 16KB). -

    socat tcp-l:7777,reuseaddr,fork system:'filan -i 0 -s >&2',nofork
    -

    listens for incoming TCP connections on port 7777. For each accepted -connection, invokes a shell. This shell has its stdin and stdout directly -connected to the TCP socket (nofork). The shell starts filan and lets it print the socket addresses to -stderr (your terminal window). -

    echo -e "\0\14\0\0\c" |socat -u - file:/usr/bin/squid.exe,seek=0x00074420
    -

    functions as primitive binary editor: it writes the 4 bytes 000 014 000 000 to -the executable /usr/bin/squid at offset 0x00074420 (this is a real world patch -to make the squid executable from Cygwin run under Windows, actual per May 2004). -

    socat - tcp:www.blackhat.org:31337,readbytes=1000
    -

    connects to an unknown service and prevents being flooded. -

    -

    socat -U TCP:target:9999,end-close TCP-L:8888,reuseaddr,fork
    -

    merges data arriving from different TCP streams on port 8888 to just one stream -to target:9999. The end-close option prevents the child -processes forked off by the second address from terminating the shared -connection to 9999 (close(2) just unlinks the inode which stays active as long -as the parent process lives; shutdown(2) would actively terminate the -connection). -

    -

    socat - UDP4-DATAGRAM:192.168.1.0:123,sp=123,broadcast,range=192.168.1.0/24
    -

    sends a broadcast to the network 192.168.1.0/24 and receives the replies of the -timeservers there. Ignores NTP packets from hosts outside this network. -

    -

    socat - IP4-DATAGRAM:255.255.255.255:44,broadcast,range=10.0.0.0/8
    -

    sends a broadcast to the local network(s) using protocol 44. Accepts replies -from the private address range only. -

    -

    socat - UDP4-DATAGRAM:224.255.0.1:6666,bind=:6666,ip-add-membership=224.255.0.1:eth0
    -

    transfers data from stdin to the specified multicast address using UDP. Both -local and remote ports are 6666. Tells the interface eth0 to also accept -multicast packets of the given group. Multiple hosts on the local network can -run this command, so all data sent by any of the hosts will be received -by all the other ones. Note that there are many possible reasons for failure, -including IP-filters, routing issues, wrong interface selection by the -operating system, bridges, or a badly configured switch. -

    -

    socat TCP:host2:4443 TUN:192.168.255.1/24,up
    -

    establishes one side of a virtual (but not private!) network with host2 where a -similar process might run, with TCP-L and tun address 192.168.255.2. They -can reach each other using the addresses 192.168.255.1 and -192.168.255.2. Substitute the TCP link with an SSL connection protected by -client and server authentication (see OpenSSL -client and -server). -

    -

    -

    DIAGNOSTICS

    - -

    Socat uses a logging mechanism that allows to filter messages by severity. The -severities provided are more or less compatible to the appropriate syslog -priority. With one or up to four occurrences of the -d command line option, the -lowest priority of messages that are issued can be selected. Each message -contains a single uppercase character specifying the messages severity (one of -F, E, W, N, I, or D) -

    -

    FATAL:
    Conditions that require unconditional and immediate program termination. -

    ERROR:
    Conditions that prevent proper program processing. Usually the -program is terminated (see option -s). -

    WARNING:
    Something did not function correctly or is in a state where -correct further processing cannot be guaranteed, but might be possible. -

    NOTICE:
    Interesting actions of the program, e.g. for supervising socat in some kind of server mode. -

    INFO:
    Description of what the program does, and maybe why it -happens. Allows to monitor the lifecycles of file descriptors. -

    DEBUG:
    Description of how the program works, all system or library calls and their results. -
    -

    Log messages can be written to stderr, to a file, or to syslog. -

    On exit, socat gives status 0 if it terminated due to EOF or inactivity -timeout, with a positive value on error, and with a negative value on fatal -error. -

    -

    FILES

    - -

    /usr/bin/socat
    -/usr/bin/filan
    -/usr/bin/procan -

    -

    ENVIRONMENT VARIABLES

    - -

    -

    SOCAT_DEFAULT_LISTEN_IP
    (Values 4 or 6) Sets the IP version to be used -for listen, recv, and recvfrom addresses if no pf -(protocol-family) option is given. Is overridden by socat options --4 or -6. -

    SOCAT_PREFERRED_RESOLVE_IP
    (Values 0, 4, or 6) Sets the IP version to -be used when resolving target host names when version is not specified by -address type, option pf (protocol-family), or -address format. If name resolution does not return a matching entry, the first -result (with differing IP version) is taken. With value 0, socat always selects -the first record and its IP version. -

    SOCAT_FORK_WAIT
    Specifies the time (seconds) to sleep the parent and -child processes after successful fork(). Useful for debugging. -

    HOSTNAME
    Is used to determine the hostname for logging (see --lh). -

    LOGNAME
    Is used as name for the socks client user name if no -socksuser is given.
    -With options su and -su-d, LOGNAME is set to the given user name. -

    USER
    Is used as name for the socks client user name if no -socksuser is given and LOGNAME is empty.
    -With options su and -su-d, USER is set to the given user name. -

    SHELL
    -With options su and -su-d, SHELL is set to the login shell of the -given user. -

    PATH
    -Can be set with option path for exec and -system addresses. -

    HOME
    -With options su and -su-d, HOME is set to the home directory of the -given user. -

    -

    -

    CREDITS

    - -

    The work of the following groups and organizations was invaluable for this -project: -

    The FSF (GNU, http://www.fsf.org/ project -with their free and portable development software and -lots of other useful tools and libraries. -

    The Linux developers community (http://www.linux.org/) for providing a free, open source operating -system. -

    The Open Group (http://www.unix-systems.org/) for making their -standard specifications available on the Internet for free. -

    -

    VERSION

    - -

    This man page describes version 1.6.0 of socat. -

    -

    BUGS

    - -

    Addresses cannot be nested, so a single socat process cannot, e.g., drive ssl -over socks. -

    Address option ftruncate without value uses default 1 instead of 0. -

    Verbose modes (-x and/or -v) display line termination characters inconsistently -when address options cr or crnl are used: They show the data after -conversion in either direction. -

    The data transfer blocksize setting (-b) is ignored with address readline. -

    Send bug reports to <socat@dest-unreach.org> -

    -

    SEE ALSO

    - -

    -nc(1), netcat6(1), sock(1), rinetd(8), cage(1), socks.conf(5), openssl(1), -stunnel(8), pty(1), rlwrap(1), setsid(1) -

    Socat home page http://www.dest-unreach.org/socat/ -

    -

    AUTHOR

    - -

    Gerhard Rieger <rieger@dest-unreach.org> - -