Socat is a command line based utility that establishes two bidirectional byte
streams and transfers data between them. Because the streams can be constructed
from a large set of different types of data sinks and sources
(see address types), and because lots of
address options may be applied to the streams, socat can
be used for many different purposes.
Filan is a utility that prints information about its active file
descriptors to stdout. It has been written for debugging socat, but might be
useful for other purposes too. Use the -h option to find more infos.
Procan is a utility that prints information about process parameters to
stdout. It has been written to better understand
some UNIX process properties and for debugging socat, but might be
useful for other purposes too.
The life cycle of a socat instance typically consists of four phases.
In the init phase, the command line options are parsed and logging is
initialized.
During the open phase, socat opens the first address and afterwards the
second address. These steps are usually blocking; thus, especially for complex address types like socks,
connection requests or authentication dialogs must be completed before the next
step is started.
In the transfer phase, socat watches both streams' read and write file
descriptors via
select()
, and, when data is available on one side 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 and used for
constructing environment variable names.
-lu
Extends the timestamp of error messages to microsecond resolution. Does not
work when logging to syslog.
-lm[<facility>]
Mixed log mode. During startup messages are printed to stderr; when socat
starts the transfer phase loop or daemon mode (i.e. after opening all
streams and before starting data transfer, or, with listening sockets with
fork option, before the first accept call), it switches logging to syslog.
With optional <facility>, the syslog type can be
selected, default is "daemon".
-lh
Adds hostname to log messages. Uses the value from environment variable
HOSTNAME or the value retrieved with uname() if HOSTNAME is not set.
-v
Writes the transferred data not only to their target streams, but also to
stderr. The output format is text with some conversions for readability, and
prefixed with "> " or "< " indicating flow directions.
-x
Writes the transferred data not only to their target streams, but also to
stderr. The output format is hexadecimal, prefixed with "> " or "< "
indicating flow directions. Can be combined with
-v
.
-b<size>
Sets the data transfer block <size> [size_t].
At most <size> bytes are transferred per step. Default is 8192 bytes.
-s
By default, socat terminates when an error occurred to prevent the process
from running when some option could not be applied. With this
option, socat is sloppy with errors and tries to continue. Even with this
option, socat will exit on fatals, and will abort connection attempts when
security checks failed.
-t<timeout>
When one channel has reached EOF, the write part of the other channel is shut
down. Then, socat waits <timeout> [timeval] seconds
before terminating. Default is 0.5 seconds. This timeout only applies to
addresses where write and read part can be closed independently. When during
the timeout interval the read part gives EOF, socat terminates without
awaiting the timeout.
-T<timeout>
Total inactivity timeout: when socat is already in the transfer loop and
nothing has happened for <timeout> [timeval] seconds
(no data arrived, no interrupt occurred...) then it terminates.
Useful with protocols like UDP that cannot transfer EOF.
-u
Uses unidirectional mode. The first address is only used for reading, and the
second address is only used for writing (example).
-U
Uses unidirectional mode in reverse direction. The first address is only
used for writing, and the second address is only used for reading.
-g
During address option parsing, don't check if the option is considered
useful in the given address environment. Use it if you want to force, e.g.,
appliance of a socket option to a serial device.
-L<lockfile>
If lockfile exists, exits with error. If lockfile does not exist, creates it
and continues, unlinks lockfile on exit.
-W<lockfile>
If lockfile exists, waits until it disappears. When lockfile does not exist,
creates it and continues, unlinks lockfile on exit.
-4
Use IP version 4 in case that the addresses do not implicitly or explicitly
specify a version; this is the default.
-6
Use IP version 6 in case that the addresses do not implicitly or explicitly
specify a version.
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
(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
INTERFACE:<interface>
Communicates with a network connected on an interface using raw packets
including link level data. <interface> is the name of
the network interface. Currently only available on Linux.
Option groups: FD,SOCKET
Useful options:
pf,
type
See also: ip-recv
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.
Please note that the reply packets might be fetched as incoming traffic when
sender and receiver IP address are identical because there is no port number
to distinguish the sockets.
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
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
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
Creates a stream socket using the first and second given socket parameters
and SOCK_STREAM (see man socket\(2)) and connects to the remote-address.
The two socket parameters have to be specified by int
numbers. Consult your OS documentation and include files to find the
appropriate values. The remote-address must be the data
representation of a sockaddr structure without sa_family and (BSD) sa_len
components.
Please note that you can - beyond the options of the specified groups - also
use options of higher level protocols when you apply socat option
-g.
Option groups: FD,SOCKET,CHILD,RETRY
Useful options:
bind,
setsockopt-int,
setsockopt-bin,
setsockopt-string
See also:
TCP,
UDP-CONNECT,
UNIX-CONNECT,
SOCKET-LISTEN,
SOCKET-SENDTO
Creates a datagram socket using the first three given socket parameters (see
man socket\(2)) and sends outgoing data to the remote-address. The three
socket parameters have to be specified by int
numbers. Consult your OS documentation and include files to find the
appropriate values. The remote-address must be the data
representation of a sockaddr structure without sa_family and (BSD) sa_len
components.
Please note that you can - beyond the options of the specified groups - also
use options of higher level protocols when you apply socat option
-g.
Option groups: FD,SOCKET,RANGE
Useful options:
bind,
range,
setsockopt-int,
setsockopt-bin,
setsockopt-string
See also:
UDP-DATAGRAM,
IP-DATAGRAM,
SOCKET-SENDTO,
SOCKET-RECV,
SOCKET-RECVFROM
SOCKET-LISTEN:<domain>:<protocol>:<local-address>
Creates a stream socket using the first and second given socket parameters
and SOCK_STREAM (see man socket\(2)) and waits for incoming connections
on local-address. The two socket parameters have to be specified by
int numbers. Consult your OS documentation and include files
to find the appropriate values. The local-address must be the
data representation of a sockaddr structure without
sa_family and (BSD) sa_len components.
Please note that you can - beyond the options of the specified groups - also
use options of higher level protocols when you apply socat option
-g.
Option groups: FD,SOCKET,LISTEN,RANGE,CHILD,RETRY
Useful options:
setsockopt-int,
setsockopt-bin,
setsockopt-string
See also:
TCP,
UDP-CONNECT,
UNIX-CONNECT,
SOCKET-LISTEN,
SOCKET-SENDTO,
SOCKET-SENDTO
Creates a socket using the three given socket parameters (see man socket\(2))
and binds it to <local-address>. Receives arriving data. The three
parameters have to be specified by int numbers. Consult your
OS documentation and include files to find the appropriate values. The
local-address must be the data representation of a sockaddr
structure without sa_family and (BSD) sa_len components.
Option groups: FD,SOCKET,RANGE
Useful options:
range,
setsockopt-int,
setsockopt-bin,
setsockopt-string
See also:
UDP-RECV,
IP-RECV,
UNIX-RECV,
SOCKET-DATAGRAM,
SOCKET-SENDTO,
SOCKET-RECVFROM
Creates a socket using the three given socket parameters (see man socket\(2))
and binds it to <local-address>. Receives arriving data and sends replies
back to the sender. The first three parameters have to be specified as
int numbers. Consult your OS documentation and include files
to find the appropriate values. The local-address must be the
data representation of a sockaddr structure without
sa_family and (BSD) sa_len components.
Option groups: FD,SOCKET,CHILD,RANGE
Useful options:
fork,
range,
setsockopt-int,
setsockopt-bin,
setsockopt-string
See also:
UDP-RECVFROM,
IP-RECVFROM,
UNIX-RECVFROM,
SOCKET-DATAGRAM,
SOCKET-SENDTO,
SOCKET-RECV
Creates a socket using the three given socket parameters (see man
socket\(2)). Sends outgoing data to the given address and receives replies.
The three parameters have to be specified as int
numbers. Consult your OS documentation and include files to find the
appropriate values. The remote-address must be the data
representation of a sockaddr structure without sa_family and (BSD) sa_len
components.
Option groups: FD,SOCKET
Useful options:
bind,
setsockopt-int,
setsockopt-bin,
setsockopt-string
See also:
UDP-SENDTO,
IP-SENDTO,
UNIX-SENDTO,
SOCKET-DATAGRAM,
SOCKET-RECVSOCKET-RECVFROM
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
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
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
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
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
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 UDP-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
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.
Please note that it might be neccessary to bind the
local socket to an address (e.g. /tmp/sock1, which must not exist
before).
This address type 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.
shut-none
Changes the (address dependent) method of shutting down the write part of a
connection to not do anything.
shut-down
Changes the (address dependent) method of shutting down the write part of a
connection to shutdown\(fd, SHUT_WR). Is only useful with sockets.
shut-close
Changes the (address dependent) method of shutting down the write part of a
connection to close\(fd).
shut-null
When one address indicates EOF, socat will send a zero sized packet to the
write channel of the other address to transfer the EOF condition. This is
useful with UDP and other datagram protocols. Has been tested against
netcat and socat with option null-eof.
null-eof
Normally socat will ignore empty (zero size payload) packets arriving on
datagram sockets, so it survives port scans. With this option socat
interprets empty datagram packets as EOF indicator (see
shut-null.
ioctl-void=<request>
Calls ioctl() with the request value as second argument and NULL as
third argument. This option allows to utilize ioctls that are not
explicitely implemented in socat.
ioctl-int=<reqeust>:<value>
Calls ioctl() with the request value as second argument and the integer
value as third argument.
ioctl-intp=<reqeust>:<value>
Calls ioctl() with the request value as second argument and a pointer to
the integer value as third argument.
ioctl-bin=<reqeust>:<value>
Calls ioctl() with the request value as second argument and a pointer to
the given data value as third argument. This data must be specified in
<dalan> form.
ioctl-string=<reqeust>:<value>
Calls ioctl() with the request value as second argument and a pointer to
the given string as third argument.
<dalan> form.
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.
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.
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]. Please note that a
missing value defaults to 1, not 0.
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). Please note that a missing value defaults to 1, not 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. Please
note that a missing value defaults to 1, not 0.
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]. Please note that a missing value defaults to 1,
not 0.
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. Please note
that this option does not drop other group related privileges.
setgid-early=<group>
Like setgit but is performed before opening the address.
setuid=<user>
Changes the <user> (owner) of the process after processing
the address. This call might require root privilege. Please note that this
option does not drop group related privileges. Check if option
su better fits your needs.
setuid-early=<user>
Like setuid but is performed before opening the
address.
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).
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.
escape=<int>
Specifies the numeric code of a character that triggers EOF on the input
stream. It is useful with a terminal in raw mode
(example).
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.
so-bindtodevice=<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.
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.
Forces the use of the specified IP version or protocol. <string> can be
something like "ip4" or "ip6". The resulting value is
used as first argument to the
socket()
or
socketpair()
calls.
This option affects address resolution and the required syntax of bind and
range options.
type=<type>
Sets the type of the socket, specified as second argument to the
socket()
or
socketpair()
calls, to <type>
[int]. Address resolution is not affected by this option.
Under Linux, 1 means stream oriented socket, 2 means datagram socket, and 3
means raw socket.
prototype
Sets the protocol of the socket, specified as third argument to the
socket()
or
socketpair()
calls, to <prototype>
[int]. Address resolution is not affected by this option.
6 means TCP, 17 means UDP.
so-timestamp
Sets the SO_TIMESTAMP socket option. This enables receiving and logging of
timestamp ancillary messages.