man socat Command

Man page for apt-get socat Command

Man Page for socat in Linux

Ubuntu Man Command : man socat

Man Socat  Command

This tutorial shows the man page for man socat in linux.

Open terminal with 'su' access and type the command as shown below:
man socat

Result of the Command Execution shown below:

socat(1)                                                              socat(1)



NAME
socat Multipurpose relay (SOcket CAT)

SYNOPSIS
socat [options]

socat V
socat h[h[h]] | ?[?[?]]
filan
procan

DESCRIPTION
Socat is a command line based utility that establishes two bidirec
tional 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 dif
ferent 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 pur
poses 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 termi
nate gracefully. For a defined time socat continues to transfer data in
the other direction, but then closes all remaining channels and termi
nates.

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 gener
ated; 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[]
Writes messages to syslog instead of stderr; severity as defined
with d option. With optional , the syslog type can be
selected, default is "daemon".

lf
Writes messages to [filename] instead of stderr.

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

lp
Overrides the program name printed in error messages and used
for constructing environment variable names.

lu Extends the timestamp of error messages to microsecond resolu
tion. Does not work when logging to syslog.

lm[]
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 ,
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 HOST
NAME 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 conver
sions 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
Sets the data transfer block [size_t]. At most
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 con
tinue. Even with this option, socat will exit on fatals, and
will abort connection attempts when security checks failed.

t
When one channel has reached EOF, the write part of the other
channel is shut down. Then, socat waits [timeval] sec
onds 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
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.

u Uses unidirectional mode. The first address is only used for
reading, and the second address is only used for writing (exam
ple).

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 con
sidered 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
If lockfile exists, exits with error. If lockfile does not
exist, creates it and continues, unlinks lockfile on exit.

W
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 instruc
tions 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 key
word 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). Key
words are case insensitive. For a few special address types, the key
word 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 key
word or an option keyword and a value, separated by '='. Option key
words 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 sin
gle 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 han
dle quotes and parenthesis meaningfully and allows escaping of special
characters. If one of the characters ( { [ ' is found, the correspond
ing 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:
Opens 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. must
be a valid existing or not existing path. If is a
named pipe, creat() might block; if 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:
Forks a sub process that establishes communication with its par
ent process and invokes the specified program with execvp() .
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. (exam
ple)
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:
Uses the file descriptor . It must already exist as valid
UN*X file descriptor.
Option groups: FD (TERMIOS,REG,SOCKET)
See also: STDIO, STDIN, STDOUT, STDERR

GOPEN:
(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, 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::
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.
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:
Communicates with a network connected on an interface using raw
packets including link level data. is the name of
the network interface. Currently only available on Linux.
Option groups: FD,SOCKET
Useful options: pf, type
See also: ip recv

IP4 SENDTO::
Like IP SENDTO, but always uses IPv4.
Option groups: FD,SOCKET,IP4

IP6 SENDTO::
Like IP SENDTO, but always uses IPv6.
Option groups: FD,SOCKET,IP6


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

IP4 DATAGRAM::
Like IP DATAGRAM, but always uses IPv4. (example)
Option groups: FD,SOCKET,IP4,RANGE

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


IP RECVFROM:
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.
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

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

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


IP RECV:
Opens a raw IP socket of . Depending on option pf, IP
procotol version 4 or 6 is used. It receives packets from multi
ple unspecified peers and merges the data. No replies are pos
sible. 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:
Like IP RECV, but always uses IPv4.
Option groups: FD,SOCKET,IP4,RANGE

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


OPEN:
Opens 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::
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.
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, certifi
cate, key, bind, pf, connect timeout, sourceport, retry
See also: OPENSSL LISTEN, TCP

OPENSSL LISTEN:
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.
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,LIS
TEN,OPENSSL,CHILD,RANGE,RETRY
Useful options: pf, cipher, method, verify, cafile, capath, cer
tificate, key, fork, bind, range, tcpwrap, su, reuseaddr, retry
See also: OPENSSL, TCP

PIPE:
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
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:::
Connects to an HTTP proxy server on port 8080 using TCP/IP ver
sion 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) ter
minal device, otherwise readline does not seem to work.
Option groups: FD,READLINE,TERMIOS
Useful options: history, noecho
See also: STDIO

SCTP CONNECT::
Establishes an SCTP stream connection to the specified
[IP address] and [TCP service] using TCP/IP version 4 or
6 depending on address specification, name resolution, or option
pf.
Option groups: FD,SOCKET,IP4,IP6,SCTP,CHILD,RETRY
Useful options: bind, pf, connect timeout, tos, mtudiscover,
sctp maxseg, sctp nodelay, nonblock, sourceport, retry, read
bytes
See also: SCTP4 CONNECT, SCTP6 CONNECT, SCTP LISTEN, TCP CONNECT

SCTP4 CONNECT::
Like SCTP CONNECT, but only supports IPv4 protocol.
Option groups: FD,SOCKET,IP4,SCTP,CHILD,RETRY

SCTP6 CONNECT::
Like SCTP CONNECT, but only supports IPv6 protocol.
Option groups: FD,SOCKET,IP6,SCTP,CHILD,RETRY

SCTP LISTEN:
Listens on [TCP service] and accepts a TCP/IP connection.
The IP version is 4 or the one specified with address option pf,
socat option ( 4, 6), or environment variable
SOCAT_DEFAULT_LISTEN_IP. Note that opening this address usually
blocks until a client connects.
Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,SCTP,RETRY
Useful options: crnl, fork, bind, range, tcpwrap, pf, backlog,
sctp maxseg, sctp nodelay, su, reuseaddr, retry, cool write
See also: SCTP4 LISTEN, SCTP6 LISTEN, TCP LISTEN, SCTP CONNECT

SCTP4 LISTEN:
Like SCTP LISTEN, but only supports IPv4 protocol.
Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,SCTP,RETRY

SCTP6 LISTEN:
Like SCTP LISTEN, but only supports IPv6 protocol.
Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,SCTP,RETRY

SOCKET CONNECT:::
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 speci
fied 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_fam
ily 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, setsock
opt string
See also: TCP, UDP CONNECT, UNIX CONNECT, SOCKET LISTEN, SOCKET
SENDTO

SOCKET DATAGRAM::::
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:::
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 documenta
tion 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

SOCKET RECV::::
Creates a socket using the three given socket parameters (see
man socket\(2)) and binds it to . Receives arriv
ing data. The three parameters have to be specified by int num
bers. Consult your OS documentation and include files to find
the appropriate values. The local address must be the data rep
resentation of a sockaddr structure without sa_family and (BSD)
sa_len components.
Option groups: FD,SOCKET,RANGE
Useful options: range, setsockopt int, setsockopt bin, setsock
opt string
See also: UDP RECV, IP RECV, UNIX RECV, SOCKET DATAGRAM, SOCKET
SENDTO, SOCKET RECVFROM

SOCKET RECVFROM::::
Creates a socket using the three given socket parameters (see
man socket\(2)) and binds it to . Receives arriv
ing 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 DATA
GRAM, SOCKET SENDTO, SOCKET RECV

SOCKET SENDTO::::
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, setsock
opt string
See also: UDP SENDTO, IP SENDTO, UNIX SENDTO, SOCKET DATAGRAM,
SOCKET RECV SOCKET RECVFROM

SOCKS4:::
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).
Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
Useful options: socksuser, socksport, sourceport, pf, retry
See also: SOCKS4A, PROXY, TCP

SOCKS4A:::
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 des


Related Topics

Apt Get Commands