/usr/bin/socat --help — Chainguard OS Manuals

From socat 1.8.1.3-r4 (os), captured 2026-11-05 by running socat -help (exit 0). permalink

socat by Gerhard Rieger and contributors - see www.dest-unreach.org
Usage:
socat [options] <bi-address> <bi-address>
   options (general command line options):
      -V     print version and feature information to stdout, and exit
      -h|-?  print a help text describing command line options and addresses
      -hh    like -h, plus a list of all common address option names
      -hhh   like -hh, plus a list of all available address option names
      -d[ddd]        increase verbosity (use up to 4 times; 2 are recommended)
      -d0|1|2|3|4    set verbosity level (0: Errors; 4 all including Debug)
      -D     analyze file descriptors before loop
      --experimental enable experimental features
      --statistics   output transfer statistics on exit
      -ly[facility]  log to syslog, using facility (default is daemon)
      -lf<logfile>   log to file
      -ls            log to stderr (default if no other log)
      -lm[facility]  mixed log mode (stderr during initialization, then syslog)
      -lp<progname>  set the program name used for logging and vars
      -lu            use microseconds for logging timestamps
      -lh            add hostname to log messages
      -v     verbose text dump of data traffic
      -x     verbose hexadecimal dump of data traffic
      -r <file>      raw dump of data flowing from left to right
      -R <file>      raw dump of data flowing from right to left
      -b<size_t>     set data buffer size (8192)
      -s     sloppy (continue on error)
      -S<sigmask>    log these signals, override default
      -t<timeout>    wait seconds before closing second channel
      -T<timeout>    total inactivity timeout in seconds
      -u     unidirectional mode (left to right)
      -U     unidirectional mode (right to left)
      -g     do not check option groups
      -L <lockfile>  try to obtain lock, or fail
      -W <lockfile>  try to obtain lock, or wait
      -0     do not prefer an IP version
      -4     prefer IPv4 if version is not explicitly specified
      -6     prefer IPv6 if version is not explicitly specified
   bi-address:  /* is an address that may act both as data sync and source */
      <single-address>
      <single-address>!!<single-address>
   single-address:
      <address-head>[,<opts>]
   address-head:
      ABSTRACT-CLIENT:<filename>		groups=FD,SOCKET,RETRY,UNIX
      ABSTRACT-CONNECT:<filename>		groups=FD,SOCKET,RETRY,UNIX
      ABSTRACT-LISTEN:<filename>		groups=FD,SOCKET,LISTEN,CHILD,RETRY,UNIX
      ABSTRACT-RECV:<filename>			groups=FD,SOCKET,RETRY,UNIX
      ABSTRACT-RECVFROM:<filename>		groups=FD,SOCKET,CHILD,RETRY,UNIX
      ABSTRACT-SENDTO:<filename>		groups=FD,SOCKET,RETRY,UNIX
      ACCEPT-FD:<fdnum>				groups=FD,SOCKET,CHILD,RETRY,RANGE,UNIX,IP4,IP6,UDP,TCP,SCTP,DCCP,UDPLITE
      CREATE:<filename>				groups=FD,REG,NAMED
      DCCP-CONNECT:<host>:<port>		groups=FD,SOCKET,CHILD,RETRY,IP4,IP6,DCCP
      DCCP-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RETRY,RANGE,IP4,IP6,DCCP
      DCCP4-CONNECT:<host>:<port>		groups=FD,SOCKET,CHILD,RETRY,IP4,DCCP
      DCCP4-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RETRY,RANGE,IP4,DCCP
      DCCP6-CONNECT:<host>:<port>		groups=FD,SOCKET,CHILD,RETRY,IP6,DCCP
      DCCP6-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RETRY,RANGE,IP6,DCCP
      EXEC:<command-line>			groups=FD,FIFO,SOCKET,EXEC,FORK,TERMIOS,PTY,PARENT,UNIX
      FD:<fdnum>				groups=FD,FIFO,CHR,BLK,REG,SOCKET,TERMIOS,UNIX,IP4,IP6,UDP,TCP,SCTP,DCCP,UDPLITE
      GOPEN:<filename>				groups=FD,FIFO,CHR,BLK,REG,SOCKET,NAMED,OPEN,TERMIOS,UNIX
      INTERFACE:<interface>			groups=FD,SOCKET,INTERFACE
      IP-DATAGRAM:<host>:<protocol>		groups=FD,SOCKET,RANGE,IP4,IP6
      IP-RECV:<protocol>			groups=FD,SOCKET,RANGE,IP4,IP6
      IP-RECVFROM:<protocol>			groups=FD,SOCKET,CHILD,RANGE,IP4,IP6
      IP-SENDTO:<host>:<protocol>		groups=FD,SOCKET,IP4,IP6
      IP4-DATAGRAM:<host>:<protocol>		groups=FD,SOCKET,RANGE,IP4
      IP4-RECV:<protocol>			groups=FD,SOCKET,RANGE,IP4
      IP4-RECVFROM:<protocol>			groups=FD,SOCKET,CHILD,RANGE,IP4
      IP4-SENDTO:<host>:<protocol>		groups=FD,SOCKET,IP4
      IP6-DATAGRAM:<host>:<protocol>		groups=FD,SOCKET,RANGE,IP6
      IP6-RECV:<protocol>			groups=FD,SOCKET,RANGE,IP6
      IP6-RECVFROM:<protocol>			groups=FD,SOCKET,CHILD,RANGE,IP6
      IP6-SENDTO:<host>:<protocol>		groups=FD,SOCKET,IP6
      OPEN:<filename>				groups=FD,FIFO,CHR,BLK,REG,NAMED,OPEN,TERMIOS
      OPENSSL:<host>:<port>			groups=FD,SOCKET,CHILD,RETRY,IP4,IP6,TCP,OPENSSL
      OPENSSL-DTLS-CLIENT:<host>:<port>		groups=FD,SOCKET,CHILD,RETRY,IP4,IP6,UDP,OPENSSL
      OPENSSL-DTLS-SERVER:<port>		groups=FD,SOCKET,LISTEN,CHILD,RETRY,RANGE,IP4,IP6,UDP,OPENSSL
      OPENSSL-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RETRY,RANGE,IP4,IP6,TCP,OPENSSL
      PIPE[:<filename>]				groups=FD,FIFO,NAMED,OPEN
      POSIXMQ-BIDIRECTIONAL:<mqname>		groups=FD,NAMED,OPEN,RETRY,POSIXMQ
      POSIXMQ-READ:<mqname>			groups=FD,NAMED,OPEN,RETRY,POSIXMQ
      POSIXMQ-RECEIVE:<mqname>			groups=FD,NAMED,OPEN,CHILD,RETRY,POSIXMQ
      POSIXMQ-SEND:<mqname>			groups=FD,NAMED,OPEN,CHILD,RETRY,POSIXMQ
      POSIXMQ-WRITE:<mqname>			groups=FD,NAMED,OPEN,CHILD,RETRY,POSIXMQ
      PROXY:<proxy-server>:<host>:<port>	groups=FD,SOCKET,CHILD,RETRY,IP4,IP6,TCP,HTTP
      PTY					groups=FD,NAMED,TERMIOS,PTY
      READLINE					groups=FD,READLINE,TERMIOS
      SCTP-CONNECT:<host>:<port>		groups=FD,SOCKET,CHILD,RETRY,IP4,IP6,SCTP
      SCTP-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RETRY,RANGE,IP4,IP6,SCTP
      SCTP4-CONNECT:<host>:<port>		groups=FD,SOCKET,CHILD,RETRY,IP4,SCTP
      SCTP4-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RETRY,RANGE,IP4,SCTP
      SCTP6-CONNECT:<host>:<port>		groups=FD,SOCKET,CHILD,RETRY,IP6,SCTP
      SCTP6-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RETRY,RANGE,IP6,SCTP
      SHELL[:<shell-command>]			groups=FD,FIFO,SOCKET,EXEC,FORK,SHELL,TERMIOS,PTY,PARENT,UNIX
      SOCKET-CONNECT:<domain>:<protocol>:<remote-address>	groups=FD,SOCKET,CHILD,RETRY
      SOCKET-DATAGRAM:<domain>:<type>:<protocol>:<remote-address>	groups=FD,SOCKET,RANGE
      SOCKET-LISTEN:<domain>:<protocol>:<local-address>	groups=FD,SOCKET,LISTEN,CHILD,RETRY,RANGE
      SOCKET-RECV:<domain>:<type>:<protocol>:<local-address>	groups=FD,SOCKET,RANGE
      SOCKET-RECVFROM:<domain>:<type>:<protocol>:<local-address>	groups=FD,SOCKET,CHILD,RANGE
      SOCKET-SENDTO:<domain>:<type>:<protocol>:<remote-address>	groups=FD,SOCKET
      SOCKETPAIR:<filename>			groups=FD,SOCKET
      SOCKS4:<socks-server>:<host>:<port>	groups=FD,SOCKET,CHILD,RETRY,IP4,IP6,TCP,SOCKS
      SOCKS4A:<socks-server>:<host>:<port>	groups=FD,SOCKET,CHILD,RETRY,IP4,IP6,TCP,SOCKS
      SOCKS5-CONNECT:<socks-server>[:<socks-port>]:<target-host>:<target-port>	groups=FD,SOCKET,CHILD,RETRY,IP4,IP6,TCP,SOCKS
      SOCKS5-LISTEN:<socks-server>[:<socks-port>]:<listen-host>:<listen-port>	groups=FD,SOCKET,CHILD,RETRY,IP4,IP6,TCP,SOCKS
      STALL					groups=FD,FIFO
      STDERR					groups=FD,FIFO,CHR,BLK,REG,SOCKET,TERMIOS,UNIX,IP4,IP6,UDP,TCP,SCTP,DCCP,UDPLITE
      STDIN					groups=FD,FIFO,CHR,BLK,REG,SOCKET,TERMIOS,UNIX,IP4,IP6,UDP,TCP,SCTP,DCCP,UDPLITE
      STDIO					groups=FD,FIFO,CHR,BLK,REG,SOCKET,TERMIOS,UNIX,IP4,IP6,UDP,TCP,SCTP,DCCP,UDPLITE
      STDOUT					groups=FD,FIFO,CHR,BLK,REG,SOCKET,TERMIOS,UNIX,IP4,IP6,UDP,TCP,SCTP,DCCP,UDPLITE
      SYSTEM:<shell-command>			groups=FD,FIFO,SOCKET,EXEC,FORK,TERMIOS,PTY,PARENT,UNIX
      TCP-CONNECT:<host>:<port>			groups=FD,SOCKET,CHILD,RETRY,IP4,IP6,TCP
      TCP-LISTEN:<port>				groups=FD,SOCKET,LISTEN,CHILD,RETRY,RANGE,IP4,IP6,TCP
      TCP4-CONNECT:<host>:<port>		groups=FD,SOCKET,CHILD,RETRY,IP4,TCP
      TCP4-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RETRY,RANGE,IP4,TCP
      TCP6-CONNECT:<host>:<port>		groups=FD,SOCKET,CHILD,RETRY,IP6,TCP
      TCP6-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RETRY,RANGE,IP6,TCP
      TEXT:<string>				groups=FD,FIFO
      TUN[:<ip-addr>/<bits>]			groups=FD,CHR,OPEN,INTERFACE
      UDP-CONNECT:<host>:<port>			groups=FD,SOCKET,IP4,IP6,UDP
      UDP-DATAGRAM:<host>:<port>		groups=FD,SOCKET,RANGE,IP4,IP6,UDP
      UDP-LISTEN:<port>				groups=FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,UDP
      UDP-RECV:<port>				groups=FD,SOCKET,RANGE,IP4,IP6,UDP
      UDP-RECVFROM:<port>			groups=FD,SOCKET,CHILD,RANGE,IP4,IP6,UDP
      UDP-SENDTO:<host>:<port>			groups=FD,SOCKET,IP4,IP6,UDP
      UDP4-CONNECT:<host>:<port>		groups=FD,SOCKET,IP4,UDP
      UDP4-DATAGRAM:<host>:<port>		groups=FD,SOCKET,RANGE,IP4,UDP
      UDP4-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RANGE,IP4,UDP
      UDP4-RECV:<port>				groups=FD,SOCKET,RANGE,IP4,UDP
      UDP4-RECVFROM:<port>			groups=FD,SOCKET,CHILD,RANGE,IP4,UDP
      UDP4-SENDTO:<host>:<port>			groups=FD,SOCKET,IP4,UDP
      UDP6-CONNECT:<host>:<port>		groups=FD,SOCKET,IP6,UDP
      UDP6-DATAGRAM:<host>:<port>		groups=FD,SOCKET,RANGE,IP6,UDP
      UDP6-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RANGE,IP6,UDP
      UDP6-RECV:<port>				groups=FD,SOCKET,RANGE,IP6,UDP
      UDP6-RECVFROM:<port>			groups=FD,SOCKET,CHILD,RANGE,IP6,UDP
      UDP6-SENDTO:<host>:<port>			groups=FD,SOCKET,IP6,UDP
      UDPLITE-CONNECT:<host>:<port>		groups=FD,SOCKET,IP4,IP6,UDP,UDPLITE
      UDPLITE-DATAGRAM:<host>:<port>		groups=FD,SOCKET,RANGE,IP4,IP6,UDP,UDPLITE
      UDPLITE-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,UDP,UDPLITE
      UDPLITE-RECV:<port>			groups=FD,SOCKET,RANGE,IP4,IP6,UDP,UDPLITE
      UDPLITE-RECVFROM:<port>			groups=FD,SOCKET,CHILD,RANGE,IP4,IP6,UDP,UDPLITE
      UDPLITE-SENDTO:<host>:<port>		groups=FD,SOCKET,IP4,IP6,UDP,UDPLITE
      UDPLITE4-CONNECT:<host>:<port>		groups=FD,SOCKET,IP4,UDP,UDPLITE
      UDPLITE4-DATAGRAM:<remote-address>:<port>	groups=FD,SOCKET,RANGE,IP4,UDP,UDPLITE
      UDPLITE4-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RANGE,IP4,UDP,UDPLITE
      UDPLITE4-RECV:<port>			groups=FD,SOCKET,RANGE,IP4,UDP,UDPLITE
      UDPLITE4-RECVFROM:<host>:<port>		groups=FD,SOCKET,CHILD,RANGE,IP4,UDP,UDPLITE
      UDPLITE4-SENDTO:<host>:<port>		groups=FD,SOCKET,IP4,UDP,UDPLITE
      UDPLITE6-CONNECT:<host>:<port>		groups=FD,SOCKET,IP6,UDP,UDPLITE
      UDPLITE6-DATAGRAM:<host>:<port>		groups=FD,SOCKET,RANGE,IP6,UDP,UDPLITE
      UDPLITE6-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RANGE,IP6,UDP,UDPLITE
      UDPLITE6-RECV:<port>			groups=FD,SOCKET,RANGE,IP6,UDP,UDPLITE
      UDPLITE6-RECVFROM:<port>			groups=FD,SOCKET,CHILD,RANGE,IP6,UDP,UDPLITE
      UDPLITE6-SENDTO:<host>:<port>		groups=FD,SOCKET,IP6,UDP,UDPLITE
      UNIX-CLIENT:<filename>			groups=FD,SOCKET,NAMED,RETRY,UNIX
      UNIX-CONNECT:<filename>			groups=FD,SOCKET,NAMED,RETRY,UNIX
      UNIX-LISTEN:<filename>			groups=FD,SOCKET,NAMED,LISTEN,CHILD,RETRY,UNIX
      UNIX-RECV:<filename>			groups=FD,SOCKET,NAMED,RETRY,UNIX
      UNIX-RECVFROM:<filename>			groups=FD,SOCKET,NAMED,CHILD,RETRY,UNIX
      UNIX-SENDTO:<filename>			groups=FD,SOCKET,NAMED,RETRY,UNIX
      VSOCK-CONNECT:<cid>:<port>		groups=FD,SOCKET,CHILD,RETRY
      VSOCK-LISTEN:<port>			groups=FD,SOCKET,LISTEN,CHILD,RETRY

Options (33)

Option	Description	Source
`-V`	Print version and available feature information to stdout, and exit.	help + man
`-hh, -??`	Like -h, plus a list of the short names of all available address options.	help + man
`-hhh, -???`	Like -hh, plus a list of all available address option names.	help + man
`-d` ddd	Without this option, only fatal, error, and warning messages are printed;	help + man
`-D`	Logs information about file descriptors before starting the transfer phase.	help + man
`--statistics`	output transfer statistics on exit	help + man
`-ly` facility	log to syslog, using facility (default is daemon)	help
`-lf` logfile	Writes messages to <logfile> [filename] instead of stderr.	help + man
`-ls`	Writes messages to stderr (this is the default).	help + man
`-lm` facility	mixed log mode (stderr during initialization, then syslog)	help
`-lp` progname	Overrides the program name printed in error messages and used for constructing environment variable names.	help + man
`-lu`	Extends the timestamp of error messages to microsecond resolution.	help + man
`-lh`	Adds hostname to log messages.	help + man
`-v`	Writes the transferred data not only to their target streams, but also to stderr.	help + man
`-x`	Writes the transferred data not only to their target streams, but also to stderr.	help + man
`-r` file	Dumps the raw (binary) data flowing from left to right address to the given file.	help + man
`-R` file	Dumps the raw (binary) data flowing from right to left address to the given file.	help + man
`-b` size_t	Sets the data transfer block <size> [size_t].	help + man
`-s`	By default, socat terminates when an error occurred to prevent the process from running when some option could not be applied.	help + man
`-S` sigmask	Changes the set of signals that are caught by socat just for printing an log message.	help + man
`-t` timeout	When one channel has reached EOF (that is not ignored through option (ignoreoef, the write part of the other channel is shut down.	help + man
`-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.	help + man
`-u`	unidirectional mode (left to right)	help + man
`-U`	Uses unidirectional mode in reverse direction.	help + man
`-g`	During address option parsing, don’t check if the option is considered useful in the given address environment.	help + man
`-L` lockfile	If lockfile exists, exits with error.	help + man
`-W` lockfile	If lockfile exists, waits until it disappears.	help + man
`-0`	Do not prefer a particular IP version;	help + man
`-4`	Use IP version 4 in case the addresses do not implicitly or explicitly specify a version.	help + man
`-6`	Use IP version 6 in case the addresses do not implicitly or explicitly specify a version.	help + man
`-h, -?`	Print a help text to stdout describing command line options and available address types, and exit. (in the manual page but not in --help)	man
`-d0`	With this option, only fatal and error messages are printed; (in the manual page but not in --help)	man
`--experimental`	New features that are not well tested or are subject to change in the future must be explicitly enabled using this option. (in the manual page but not in --help)	man

Exit status (1) from the manual page

`0`	it terminated due to EOF or inactivity timeout

Examples (40) from the manual page, untested

socat - TCP4:www.domain.org:80
startdit()
socat -d -d \
transfers data between STDIO (-) and a TCP4 connection to port 80 of host www.domain.org.
READLINE,history=$HOME/.http_history \
socat \
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;
TCP4-LISTEN:www \
socat -d -d -lmlocal2 \
installs a simple TCP port forwarder.
TCP4-LISTEN:80,bind=myaddr1,reuseaddr,fork,su=nobody,range=10.0.0.0/8 \
socat \
TCP port forwarder, each side bound to another local IP address (bind).
TCP4-LISTEN:5555,fork,tcpwrap=script \
socat \
a simple server that accepts connections (TCP4-LISTEN) and fork’s a new child process for each connection;
EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \
socat \
mail.sh is a shell script, distributed with socat, that implements a simple SMTP client.
-,escape=0x0f \
socat \
opens an interactive connection via the serial line, e.g. for talking with a modem.
UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
socat -u \
with UNIX-LISTEN, socat opens a listening UNIX domain socket /tmp/.X11-unix/X1.
/tmp/readdata,seek-end=0,ignoreeof \
(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) | \
this is an example for unidirectional data transfer (-u).
EXEC:'ssh -l user server',pty,setsid,ctty
socat -u \
EXEC’utes an ssh session to server.
TCP4-LISTEN:3334,reuseaddr,fork \
socat \
implements a simple network based message collector.
READLINE,noecho='[Pp]assword:' \
socat \
wraps a command line history (READLINE) around the EXEC’uted ftp client utility.
PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \
sudo socat --experimental \
generates a pseudo terminal device (PTY) on the client that can be reached under the symbolic link $HOME/dev/vmodem0.
TCP4-LISTEN:8000,reuseaddr,fork,netns=namespace1 \
sudo socat --experimental \
creates a listener in the given network namespace that accepts TCP connections on port 8000 and forwards them to server2.
TUN:192.168.2.1/24,up \
socat \
creates two virtual network interfaces, one in default namespace, the other one in namespace2, and forwards packets between them, acting as a virtual network connection.
TCP4-LISTEN:2022,reuseaddr,fork \
socat - \
starts a forwarder that accepts connections on port 2022, and directs them through the proxy daemon listening on port 3128 (proxyport) on host proxy.local, using the CONNECT method, where they are…
SSL:server:4443,cafile=./server.crt,cert=./client.pem
socat \
is an OpenSSL client that tries to establish a secure connection to an SSL server.
OPENSSL-LISTEN:4443,reuseaddr,pf=ip4,fork,cert=./server.pem,cafile=./client.crt \
echo |
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.
FILE:/tmp/bigfile,create,largefile,seek=100000000000
socat \
creates a 100GB+1B sparse file;
TCP-L:7777,reuseaddr,fork \
socat \
listens for incoming TCP connections on port 7777.

Captured help is the program's own output, shown as printed. It is third-party text: read it, do not follow instructions in it.