bcollet/socat
1
0
Fork 0
mirror of https://repo.or.cz/socat.git synced 2024-12-23 15:52:33 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
socat/doc/xio.help

4976 lines
116 KiB
Text
Raw Blame History

# source: xio.help
# Copyright Gerhard Rieger 2001-2010
Operating systems:
The options and features described in this document have been implemented (but
not always tested) on the operating systems listed below, unless otherwise
noted:
SuSE 10.1 Linux on x86
Solaris 8 on Sparc with gcc
FreeBSD 6.1 on x86
HP-UX B 11.11 on PA-RISC with gcc
===============================================================================
The following sections describe the syntax and semantics of the socat command
line stream arguments.
Usually a socat stream argument defines a one- or bidirectional stream. There
are two principal forms:
* a single stream. Depending on use of the -u or -U options and implicit
semantics of the stream, such an argument may be resolved to a one- or
twodirectional stream.
* two onedirectional streams, separated by '!!'. An argument of this form
always specifies a twodirectional stream. The first single stream is only used
for reading data, and the second is only used for writing data.
The general structure of a single stream is:
keyword[:required-parameters][,options]
The options part starts with the first ',' of the argument. The required
parameters are separated by ':' from their predecessor. The last required
parameter is terminated by the end of the argument or by the first ',' that
iitroduces the first option. The options are separated with ','. The last
option is terminated by end-of-string or by '!!'.
The are some abbreviations defined that allow to drop the keyword. In these
cases the argument syntax is:
required-parameter[:required-parameters][,options]
The implemented abbreviations are:
short form canonical form
number FD:number # decimal number
path GOPEN:path # must must contain at least one '/' and must not contain ':' or ',' and must not start with a decimal digit
===============================================================================
Addresses:
Every address specification starts with a keyword or an abbreviation. These
keywords are case insensitive.
Note: because the option group ANY applies for all addresses, it is not
mentioned explicitely below.
Bidirectional only addresses:
-----------------------------
PIPE
FIFO
ECHO
Opens an unnamed pipe (fifo) where outbound traffic is sent to and inbound
traffic is read from. The special semantics of pipes results in an echo like
behaviour.
Option groups: FD, FIFO (no specific FIFO options are defined yet)
Onedirectional only addresses:
------------------------------
Currently all addresses may be used bidirectional.
Note: for regular files, behaviour when being used bidirectionally is
undefined.
One- and bidirectional addresses:
---------------------------------
STDIO
- ("minus")
Uses stdin (FD 0) for inbound traffic and/or stdout (FD 1) for outbound traffic
on this address.
Option groups: FD; others dependent on actual types of stdin and stdout (FIFO,
CHR, BLK, REG, and/or SOCKET).
STDIN
Uses stdin for traffic. This might fail for outbound traffic.
Option groups: FD; dependent on actual type of stdin (FIFO, CHR, BLK, REG, or
SOCKET).
STDOUT
Uses stdout for traffic. This might fail for inbound traffic.
Option groups: FD; dependent on actual type of stdout (FIFO, CHR, BLK, REG, or
SOCKET).
STDERR
Uses stdout for traffic. This might fail for inbound traffic.
Option group: FD; dependent on actual types of sterr (FIFO, CHR, BLK, REG, or
SOCKET).
FD:num
num
Uses the already existing file descriptor <num> for traffic.
Option groups: FD; dependent on actual types of file descriptor (FIFO, CHR,
BLK, REG, or SOCKET).
READLINE
Uses the GNU readline function and history capabilies (best known from bash).
It always works on stdin and stdout; if stdio is not a tty, readline does not
seem to work correctly.
Because readline is blocking during line editing, it does not fit well into
socats I/O philosophy.
socat integrates readline by waiting in the select call as usual; when stdin
reports available data, socat invokes readline(). readline blocks until the
user presses ENTER or EOF. Data on socats other stream is not handling in this
time.
socat controls the ECHO flag of the stdin tty (off during select(), on for
readline()).
When using socat with readline as front end to a service like telnet, POP3 or
an other authenticated service, please note that the password is entered as
ordinary data, thus appears on the screen!
Option groups: FD, READLINE, TERMIOS
Useful options: history-file
OPEN:path
Applies an open() system call to the given path. If the path does not exist a
file is created only if the option create is used; if a file, pipe, or device
with this name already exists it is opened. Open for reading and/or writing
depends on the rw parameter of the xioopen call, or on usage in a socat
argument. If no perm option is used, xioopen uses 600 (which might be modified
by umask then).
Applying this function to files conforms to the semantics as described by the
open(2) man page.
Opening device files, like /dev/ttyS*, might block until the device gets active
(until some peer is connected)
With existing named pipes (fifos) please note the usual semantics:
Opening the pipe in read/write mode results in an echo service;
Opening the pipe in read mode blocks until a writer opens the pipe (close
by writer gives EOF for the reader); with option nonblock the open call does
not block.
Opening the pipe in write mode blocks until a reader opens the pipe (close
by reader gives "broken pipe" error on next write); with option nonblock the
open call terminates with error "no such device or address" in absence of a
reader.
Opening a named UNIX stream socket with or without a listening peer might
succeed depending on the operating system, but
the resulting file descriptor erronously reports available data immediately,
and the following read() or write() call always fails with "invalid
argument". Even worse, while such a filesystem entry is identified as socket by
"file" command and by fstat(), getsockopt() after open() gives error "Socket operation on non-socket".
Use GOPEN for reasonable behaviour!
Option groups: FD, OPEN, NAMED, and specific for data object type (FILE, FIFO,
CHRDEV+TERMIOS, BLKDEV, or SOCKET).
GOPEN:path
path
"Generic open". Tries to open the given path in a smarter way. If the path
exists and is a socket, it is connected to; if connecting fails,
socat assumes a datagram socket and later uses sendto() calls for data
transfer.
If the path exists and is not a socket, it is opened:
in RDONLY environment for reading from position 0,
in WRONLY environment for appending (O_APPEND),
in RDWR env. for reading and/or writing starting from position 0.
If the path does not exist:
in RDONLY environment this is an error
in WRONLY environment the file is created (O_CREAT)
in RDWR env. for reading and/or writing starting from position 0.
However, these flags may be overriden by user supplied options
(e.g., "append=0")
Option groups: FD, NAMED, and specific for data object type (FILE, FIFO,
CHRDEV+TERMIOS, BLKDEV, or SOCKET).
CREATE:path
CREAT:path
Opens the named file with creat(). With UNIX semantics, this address is just a
variation of the OPEN address, see there for more details.
Note: The creat() system call does not create a completely new file, but
inherits some properties of the old file if it exists, e.g. permissions. Use
option "unlink-early" to remove the old entry before.
Option groups: FD, NAMED, FILE
Useful options: unlink-late
PIPE:path
FIFO:path
Creates and opens a pipe if path does not exist; opens path if it already
exists.
Option groups: FD, NAMED, FIFO
Note: this address uses the mknod(2) system call to create the named pipe. On
FreeBSD, this call requires root privilege
EXEC:cmdline
Forks off a child process after establishing a bidirectional communication
channel (with socketpair, pipes, or pty). The child then starts "cmdline" with
execvp().
Note: spaces and shell meta characters in cmdline must be quoted if socat is
invoked from the command line.
Option groups: FD, FORK, EXEC, SOCKET, SOCK_UNIX, FIFO, TERMIOS
Useful options: path, fdin, fdout, chroot, su, pty, stderr
Note: on AIX, search permissions on /dev/pts/ are required to use option pty.
SYSTEM:cmdline
Forks off a child process after establishing a bidirectional communication
channel (with socketpair, pipes, or pty). The child then starts "cmdline" with
system().
Note: spaces and shell meta characters in cmdline must be quoted if socat is
invoked from the command line.
Option groups: FD, FORK, EXEC, SOCKET, SOCK_UNIX, FIFO, TERMIOS
Useful options: path, fdin, fdout, chroot, su, pty, stderr
Note: there are slightly different semantics with options pty or pipes, because
they do not communicate an EOF condition to the shell process. Therefore, the
shell process and its child do not terminate due to EOF, but are explicitly
killed during close of the socat file handle. Consider using
exec:'/bin/sh -c command',pty...
UNIX:path
LOCAL:path
Connects to a UNIX domain socket.
Option groups: FD, SOCKET, SOCK_UNIX
NOTE: you need rw permissions to connect to a local socket. My Linux answers
with "connection refused" to insufficient permissions, not existing
socket, not a socket, or just a socket entry without a listening process.
NOTE: this address does not implement option group NAMED because its connect
call succeeds only if there is already someone listening, but at this point the
NAMED group actions no longer affect this socket, only the fs entry.
UNIX-listen:path
UNIX-l:path
Create a listening UNIX domain socket. With the fork option, for each accepted
connection a new process is forked off, and more connections are accepted on
the parent socket. Without fork, only the first connection is accepted.
Option groups: FD, NAMED, SOCKET, SOCK_UNIX, LISTEN, CHILD
IP:host:protocol
IP4:host:protocol
Open a raw socket with IP4 protocol. This mode sends packets to and accepts
them only from host. protocol is a number from 0 to 255, with 1 meaning ICMP,
6..TCP, 17..UDP, 255..raw IP; 0 might be unsupported by the local IP stack,
resulting in an error.
Requires root privilege.
Note: my Linux 2.4.10 kernel seems to drop payloads smaller than 8
bytes on their way from the network to the application.
Option groups: FD, SOCKET, SOCK_IP
TCP:host:port
TCP4:host:port
INET:host:port
Create a TCP/IP4 client socket and connect to the given host/port combination.
Option groups: FD, SOCKET, SOCK_IP, IPAPP, IP_TCP
Useful options: crlf, bind, tos, mtudiscover, mss, nodelay,
TCP-l:port
TCP-listen:port
TCP4-l:port
TCP4-listen:port
INET-l:port
INET-listen:port
Create a TCP/IP4 server socket and wait for an incoming connection. With the
fork option, for each accepted connection a new process is forked off, and more
connections are accepted on the parent socket. Without fork, only the first
connection is accepted.
Option groups: FD, SOCKET, SOCK_IP, IPAPP, IP_TCP, LISTEN, RANGE, CHILD
Useful options: fork, crlf, bind, backlog, mtu, tcpwrap
UDP:host:port
UDP-CONNECT:host:port
Connects to port on host 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, SOCK_IP4, SOCK_IP6, IP_UDP
Useful options: ttl
UDP4:host:port
UDP4-CONNECT:host:port
Like UDP-CONNECT, but only supports IPv4 protocol.
Option groups: FD, SOCKET, SOCK_IP, IPAPP, IP_UDP
UDP-listen:port
UDP-l:port
Emulates a UDP server in the same way as netcat: Create a UDP/IP4 socket and
bind to the given port. Then wait for the first packet, get its sender address
(without consuming its data), connect() to this address, and leave xioopen().
Afterwards, our socket only communicates with this peer.
Option groups: FD, SOCKET, SOCK_IP, IPAPP, IP_UDP, RANGE
Note: with fork option, child processes might hang forever because UDP cannot
transport EOF conditions.
#UDP-dgram:port
#UDP-d:port
#
#Create and use a pure datagram oriented UDP socket.
#The following restrictions apply:
#* range option does not work
#* de facto this is a read-only endpoint: sending data to 0.0.0.0 might fail.
TCP6:host:port
INET6:host:port
Create a TCP/IP6 client socket and connect to the given host/port combination.
Option groups: FD, SOCKET, SOCK_IP, IPAPP, IP_TCP
Note: Address syntax parsing is awkward, since the IPv6 address word separator
is ':' which is used as port separator too.
An FTP listen entry looks in netstat ":::21"!
TCP6-l:port
TCP6-listen:port
INET6-l:port
INET6-listen:port
Create a TCP server socket and wait for an incoming connection. With the fork
option, for each accepted connection a new process is forked off, and more
connections are accepted on the parent socket. Without fork, only the first
connection is accepted.
Option groups: FD, SOCKET, SOCK_IP, IPAPP, IP_TCP, LISTEN, RANGE, CHILD
SOCKS4:sockd:host:port
SOCKS:sockd:host:port
Use a socks server, socks protocol version 4, to build a TCP (IPv4) connection.
Sockd is the name or address of the socks server, host and port specify the
destination address. Use option socksport if the socks server does not listen
on port 1080.
Option groups: FD, SOCKET, SOCK_IP, IPAPP, IP_TCP, IP_SOCKS
Useful options: sp, socksport, socksuser
Note: If you do not specify option socksuser, xioopen tries to derive it from
environment: LOGNAME or USER, and might therefore undisclose your identity.
SOCKS4a:sockd:host:port
Like SOCKS4, but use the socks version 4a extension for destination name
resolution on the socks server.
Option groups: FD, SOCKET, SOCK_IP, IPAPP, IP_TCP, IP_SOCKS
PTY
Creates a pseudo terminal (pty) and uses its master side. Another process may
open the pty<74>s slave side using it like a serial line or terminal.
Option groups: FD,NAMED,PTY,TERMIOS
Useful options: link, openpty, mode, user, group
OPENSSL-CONNECT:host:port
OPENSSL:host:port
Tries to establish a SSL connection to port on host using TCP/IPv4.
Note: this is currently only an experimental integration of openssl!
(it does not provide any trust between the peers because is does not check
certificates!)
Option groups: FD,SOCKET,SOCK_IP4,IP_TCP,OPENSSL,RETRY
Useful options: cipher, method, verify, cafile, capath, certificate, bind, sourceport, retry
OPENSSL-LISTEN:port
Listens on tcp4 port. When a connection is accepted, this address behaves as
SSL server.
Option groups: FD,SOCKET,SOCK_IP4,TCP,LISTEN,CHILD,RANGE,OPENSSL,RETRY
Usefule options: cipher, method, verify, cafile, capath, certificate, retry
PROXY:proxy:host:port
PROXY-CONNECT:proxy:host:port
Connects to an HTTP proxy server on port 8080 using TCP/IPv4, and sends a
CONNECT request for host: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,TCP,HTTP
Useful options: proxyport, ignorecr, proxyauth, crnl, bind, mss, sourceport
===============================================================================
Option Groups:
Each option is member of one option group. Address definitions specify which
option groups they support. This allows to reject unapplyable options in an
early stage of address processing.
Address groups are identified by single bit positions. Option definitions
specify to which group the option belongs (some options are member or more than
one group). Addresses use a bit pattern to specify which option groups they
support.
Currently the following option groups are defined:
GROUP_FD: All addresses that result in one or more file descriptors. These
options are typically applied with fcntl() or some special calls like fchown()
or fchmod(). There is no documented restriction to apply these functions to any
file descriptor; but they are not always meaningful, and sometimes lead to OS
exceptions.
GROUP_APPL: All addresses. The options do not need file descriptors, because
they manipulate the data streams at application level (ignoreeof, line
terminator conversion).
GROUP_PROCESS: For options that change process related attributes, like user id
(setuid).
GROUP_FIFO: Options for pipes. Currently not used.
GROUP_CHR: Options for character devices. Currently not used.
GROUP_BLK: Options for block devices. Currently not used.
GROUP_REG, GROUP_FILE: Options for regular files. Currently not used.
GROUP_SOCKET: Options for arbitrary type sockets, e.g. so-sndbuf, so-linger.
GROUP_NAMED: Options for file system entries, e.g. user-early, unlink.
GROUP_OPEN: Options that are applied with the open() system call.
GROUP_EXEC: Options for program or script execution, e.g. path.
GROUP_FORK: Options for communication with children processes, e.g. fdin, pty.
GROUP_LISTEN: Options for listening sockets. Only backlog.
GROUP_DEVICE: not used
GROUP_CHILD: Options for addresses that may fork off independent child
processes. Currently only option fork.
GROUP_RETRY: Options for failure handling. Currently not used.
GROUP_TERMIOS: Options for terminal settings, e.g. echo, b38400, raw.
GROUP_READLINE: Options for readline (GNU line editing and history).
GROUP_RANGE: Options for checking peer address. Currently only range.
GROUP_SOCK_UNIX: Options for UNIX domain sockets. Currently not used.
GROUP_SOCK_IP4: Options for IP4 sockets. Currently not used.
GROUP_SOCK_IP6: Options for IP6 sockets. Currently not used.
GROUP_SOCK_IP: Options for IP sockets, e.g. mtu, ip-options, ttl.
GROUP_IP_UDP: Options for UDP sockets. Currently not used.
GROUP_IP_TCP: Options for TCP sockets, e.g. maxseg, nodelay.
GROUP_IPAPP: Options for UDP and TCP sockets. Currently only sourceport.
GROUP_IP_SOCKS4: Options for SOCKS client connections, e.g. socksuser.
GROUP_PROCESS: Options for process wide attributes, e.g. su, chroot.
GROUP_APPL: Options handled by application. Currently not used.
GROUP_PTY: Options for pseudo terminals. Used with addresses PTY, EXEC, and
SYSTEM.
GROUP_OPENSSL: Options for the OPENSSL address.
There are "combined" group definitions too:
#define GROUP_ANY (GROUP_PROCESS|GROUP_APPL)
#define GROUP_ALL 0xffffffff
===============================================================================
Address Options
Address options are identified by a case insensitive keyword. If the options
needs a parameter value, the option syntax is always:
OPTION=VALUE
Currently there do not exist options that take more than one argument;
sometimes, two values are combined to form one argument value, e.g. IP4 address
and port:
192.168.0.1:80
Note:
"Type" describes the type of data that may or must be given to the option and
that is passed to the system. There are some options with boolean semantics
(on/off or yes/no), but their values are passed to the system with an int
parameter. This situation is indicated as "Logical type: bool" and "Physical
type: int". In this case xioopen passes the physical value to the system,
giving the user one more hacking playground.
Option: append
Type: BOOL
Option group: FD
Phase: LATE
Platforms: all (UNIX98)
Sets the O_APPEND flag via a fcntl() call and F_SETFL; with OPEN type
addresses, this flag is applied with the open() call. All data written is
appended to the actual file end, even if other processes have written to or
truncated the file in the meantime.
Option: async
Type: BOOL
Option group: FD
Phase: LATE
Platforms: FreeBSD, Linux, SunOS
Sets the O_ASYNC (or FASYNC) flag via a fcntl() call and F_SETFL; with FILE
addresses, this flag is applied with the open() call. Consult your kernel
documentation for effects of this flag.
NOTE: socat does not handle the SIGIO signal.
Option: cloexec
Type: BOOL
Option group: FD
Phase: LATE
Platforms: all
Sets the FD_CLOEXEC (close-on-exec) flag on the file descriptor via a
fcntl()call with F_SETFD. Use with caution, because xioopen() makes use of this
flag to archieve what we consider the most reasonable behaviour; using this
option overrides xioopen's setting!
Option: flock-ex
Aliases: flock, lock
Type: BOOL
Option group: FD
Phase: FD
Platforms: FreeBSD, Linux
Applies the flock(fd, LOCK_EX) call to the file descriptor(s). This locks a file
exclusively (but only for processes also using flock() on this file - otherwise, they seem to have unrestricted access).
If the file is already locked with flock, our flock call blocks until the other
processes lock is released.
Note: the "lock" option name alias applies to this option only
if the fcntl locking mechanism is not available on a platform.
Option: flock-ex-nb
Aliases: flock-nb
Type: BOOL
Option group: FD
Phase: FD
Platforms: FreeBSD, Linux
Applies the flock(fd, LOCK_EX|LOCK_NB) call to the file descriptor(s). This locks a file
exclusively (but only for processes also using flock() on this file -
otherwise, they seem to have unrestricted access).
If the file is already locked with flock, our flock call returns the error
"Resource temporarily unavailable".
Option: flock-sh
Type: BOOL
Option group: FD
Phase: FD
Platforms: FreeBSD, Linux
Applies a shared advisory lock to the file using the flock(fd, LOCK_SH) call.
This prevents processes from locking the file exclusively.
If the file has already an exclusive lock, our flock call blocks until the
other processes lock is released.
Option: flock-sh-nb
Type: BOOL
Option group: FD
Phase: FD
Platforms: FreeBSD, Linux
Applies a shared advisory lock to the file using the flock(fd, LOCK_SH|LOCK_NB) call.
This prevents processes from locking the file exclusively.
If the file has already an exclusive lock, our flock call returns with error
"Resource temporarily unavailable".
Option: f-setlk-rd
Aliases: setlk-rd
Type: BOOL
Option group: FD
Phase: FD
Platforms: all
Locks the complete file with fcntl(fd, F_SETLK, {F_RDLCK}) (complete means from its
start to its maximal length). This locks the file exclusively (but only if the
other processes accessing this file also use f-setlk or f-setlkw - otherwise,
they seem to have unrestricted access). If the file is already locked with
f-setlk or f-setlkw, the fcntl call blocks until release by the other process.
Option: f-setlk-wr
Aliases: f-setlk, setlk-wr, setlk
Type: BOOL
Option group: FD
Phase: FD
Platforms: all
Locks the complete file with fcntl(fd, F_SETLK, {F_WRLCK}) (complete means from its
start to its maximal length). This locks the file exclusively (but only if the
other processes accessing this file also use f-setlk or f-setlkw - otherwise,
they seem to have unrestricted access). If the file is already locked with
f-setlk or f-setlkw, the fcntl call blocks until release by the other process.
Option: f-setlkw-rd
Aliases: setlkw-rd
Type: BOOL
Option group: FD
Phase: FD
Platforms: all
Locks the complete file with fcntl(fd, F_SETLKW, {F_RDLCK}) (complete means from its
start to its maximal length). This locks the file exclusively (but only if the
other processes accessing this file also use f-setlk or f-setlkw - otherwise,
they seem to have unrestricted access). If the file is already locked with
f-setlk or f-setlkw, fcntl returns with EAGAIN.
Option: f-setlkw-wr
Aliases: setlkw-wr, f-setlkw, setlkw, lockw, lock
Type: BOOL
Option group: FD
Phase: FD
Platforms: all
Locks the complete file with fcntl(fd, F_SETLKW, {F_WRLCK}) (complete means from its
start to its maximal length). This locks the file exclusively (but only if the
other processes accessing this file also use f-setlk or f-setlkw - otherwise,
they seem to have unrestricted access). If the file is already locked with
f-setlk or f-setlkw, fcntl returns with EAGAIN.
Option: fork
Type: BOOL
Option group: CHILD
Phase: PASTACCEPT
Platforms: all
Without fork (or fork=0), the listening process accepts exactly one
connections, and terminates afterwards. With fork set, it forks off a new socat
child process for each incoming connection.
It is very important to understand what socat does with this fork option:
The parent process remains in a loop of accept() and fork() calls until
terminated from outside. The child process leaves this loop and goes on with
the socat processing. If the fork occurs in the first address argument, the
child process continues with parsing and activating the second address
argument. This will in most cases be what you want or expect.
If the fork call occurs in socats second address argument, all children will
inherit and share the already activated first address.
Option: group=value
Aliases: gid=value
Type: GIDT or unsigned int
Option group: NAMED
Type: GIDT
Platforms: all
Takes one argument, a UNIX group name or a numeric group id. The first
character of value is a digit for group ids.
With NAMED addresses this option is applied via a chown() call, with a
fchown() call otherwise.
If groupname is a name it must be a valid groupname from /etc/group and is
converted to a group id with a getgrnam(3) call.
On most modern operating systems, the owner of the process must be member of
the group being set; only root may set any group, even numbers without group
name.
A Linux 2.2.10 kernel SIGSEGVs the process in the fchown() call when this
option is used with a socket or pipe. Is fixed with Linux 2.4.
LINUXBUG TESTCASE:
SH1: socat -D - unix-l:/tmp/socket,unlink-early
SH2: socat -d -d -d -d -D gopen:/tmp/socket,group=floppy -
Option: group-late=value
Type: GIDT or string
Option group: FD
Type: GIDT
Platforms: all
Takes one argument, a UNIX group name or a numeric group id. The first
character of value is a digit for group ids.
This option is applied via a fchown(2) call.
If groupname is a name it must be a valid groupname from /etc/group and is
converted to a group id with a getgrnam(3) call.
On most modern operating systems, the owner of the process must be member of
the group being set; only root may set any group, even numberic group ids
without group name.
Option: o-nonblock
Aliases: nonblock
Type: BOOL
Option group: FD
Phase: FD
Platforms: all (UNIX98)
Sets the O_NONBLOCK flag of a file descriptor via a fcntl(2) call and F_SETFL;
with OPEN type addresses, this flag is applied with the open() call.
It does not change the behaviour of socat's data transfer loop because socat
uses select() which blocks nevertheless.
Currently is has only two documented uses:
1) With address TCP, the connect() call
does not block; instead, it continues through the open step. The channel is
passed to the select() call. If something is written to the channel before it
is connected, this is an error. If connection fails, a read condition occurs
and read() returns the error.
2) Opening a named pipe does not block with this option.
Option: o-ndelay
Aliases: ndelay
Type: BOOL
Option group: FD
Phase: LATE
Platforms: HP-UX, SunOS (UNIX98)
Under Solaris it sets the O_NDELAY of the file descriptor via a fcntl(2) call
and F_SETFL; with OPEN type addresses, this flag is applied with the open()
call.
With all other operating systems, this is just another name for the nonblock option.
Option: o-noatime
Aliases: noatime
Type: BOOL
Option group: FD
Phase: FD
Platforms: Linux
Sets the O_NOATIME flag of a file descriptor via a fcntl(2) call and F_SETFL;
with OPEN type addresses, this flag is applied with the open() call.
It prevents the access time from being updated during read operations.
Option: perm=value
Aliases: mode=value
Type: MODET (mode_t)
Option group: NAMED
Phase: FD
Platforms: all
This option changes the mode (permissions) of an addresses inode. xioopen
tries to apply this option already during open phase. If the address does not
have a open phase or if the option cannot be applied there, the value is
applied directly on the file descriptor afterwards.
It is up to you to (1) have the permission to change the permissions, and (2)
not to set permissions that prevent you from performing your transactions :-)
NOTE: At least with some Linux 2.2, setting permissions on an existing file or
device with fchmod() does not change the permissions of its inode on disk. See
perm-early which uses chmod() instead.
NOTE: At least with some Linux 2.2, restricting mode on file descriptors does
not restrict this file descriptors data transfer capabilities.
Option: perm-late=value
Type: MODET (mode_t)
Option group: FD
Phase: LATE
Platforms: all
This option changes the mode (permissions) of a file descriptor with fchmod()
in the last phase of address processing.
Option: seek-set=offset
Aliases: lseek=offset, seek=offset
Type: OFF32 or OFF64
Option group: BLK
Phase: LATE
Platforms: HP-UX, Linux, SunOS
Positions the file at the given absolute offset, using lseek() (or lseek64() if
available) with SEEK_SET.
Option: seek-cur=offset
Type: OFF32 or OFF64
Option group: BLK
Phase: LATE
Platforms: HP-UX, Linux, SunOS
Positions the file at the given offset from the current position,
using lseek() (or lseek64() if available) with SEEK_SET.
Option: seek-end=offset
Type: OFF32 or OFF64
Option group: BLK
Phase: LATE
Platforms: HP-UX, Linux, SunOS
Positions the file at the given offset from the file end,
using lseek() (or lseek64() if available) with SEEK_END.
Option: lseek32-set=offset
Aliases: lseek32=offset
Type: OFF32
Option group: BLK
Phase: LATE
Platforms: HP-UX, Linux, SunOS
Positions the file at the given absolute offset using lseek() with SEEK_SET.
This call might fail for non
random access data objects like character devices or sockets.
NOTE: this option seems to be useless on files with O_APPEND set.
Option: lseek32-cur=offset
Type: OFF32 (instead of off_t)
Option group: BLK
Phase: LATE
Platforms: HP-UX, Linux, SunOS
Positions the file at the given offset from the current position using lseek()
with SEEK_CUR. This call
might fail for non random access data objects like character devices.
On Linux, the seek() call fails on pipes, sockets and ttys but works on files
and /dev/null
NOTE: this option seems to be useless on files with O_APPEND set.
Option: lseek32-end=offset
Type: OFF32
Option group: BLK
Phase: LATE
Platforms: HP-UX, Linux, SunOS
Positions the file at the given offset from the file end using lseek() with
SEEK_END. This call might fail
for non random access data objects like character devices.
NOTE: this option seems to be useless on files with O_APPEND set.
Option: lseek64-set=offset
Aliases: lseek64=offset
Type: OFF64
Option group: BLK
Phase: LATE
Platforms: all
Positions the file at the given absolute offset using lseek64() with SEEK_SET.
This call might fail for non
random access data objects like character devices or sockets.
NOTE: this option seems to be useless on files with O_APPEND set.
Option: lseek64-cur=offset
Type: OFF64
Option group: BLK
Phase: LATE
Platforms: all
Positions the file at the given offset from the current position using
lseek64() with SEEK_CUR. This call
might fail for non random access data objects like character devices.
NOTE: this option seems to be useless on files with O_APPEND set.
Option: lseek64-end=offset
Type: OFF64
Option group: BLK
Phase: LATE
Platforms: all
Positions the file at the given offset from the file end using lseek64() with
SEEK_END. This call might fail
for non random access data objects like character devices.
NOTE: this option seems to be useless on files with O_APPEND set.
Option: chroot=path
Type: STRING
Option group: PROCESS
Phase: LATE
Platforms: all
Invokes the chroot() system call with the given path after the address
resolution, so the path names of the address must be specified with absolute
pathes.
Note: when you combine chroot with substuser, with substuser applied within the
chroot environment, usually the etc/passwd and etc/group files in the chroot
environment are used for group set etc.
See appendix "generating a sandbox"
Option: chroot-early=path
Type: STRING
Option group: PROCESS
Phase: EARLY
Platforms: all
Invokes the chroot() system call with the given path before the address is
resolved, this means before file opening in OPEN, GOPEN and before program
execution in EXEC and SYSTEM, so their pathes must be specified related to
their chroot directory.
See appendix "generating a sandbox"
Option: setgid=group
Type: GIDT (gid_t or string)
Option group: PROCESS
Phase: LATE2
Platforms: all
Invokes setgid() with the group id. For EXEC and SYSTEM this call is performed
for the child process after the fork and therefore does not affect the socat
process directly. For LISTEN group addresses with fork option, this call is
performed only on the child processes. For all other addresses, it is performed
in the late phase of address processing, so it does not affect the address
where it is used, but for the next address (if any), and for the data loop.
Note: setgid() does not remove any groups from the current process group set.
Option: setuid=user
Type: UIDT (uid_t or string)
Option group: PROCESS
Phase: LATE2
Platforms: all
Invokes setuid() with the user id. For EXEC and SYSTEM this call is performed
for the child process after the fork and therefore does not affect the socat
process directly. For LISTEN group addresses with fork option, this call is
performed only on the child processes. For all other addresses, it is performed
in the late phase of address processing, so it does not affect the address
where it is used, but the next address (if any), and the data loop.
Note: setuid() is invoked AFTER setgid(), if both are applied.
Note: setuid() does not influence the processes group set; in most cases, you
want to prefer substuser option.
Option: substuser=user
Aliases: su=user
Type: UIDT (uid_t or string)
Option group: PROCESS
Phase: LATE2
Platforms: all
Tries to switch the process to the given user and its group set.
To make sure that the groups are set correctly for the new process owner, the
system calls initgroups(), setgid(), and setuid() are invoked with the
appropriate arguments.
On sane operating system, this option requires root privileges.
Note: this option sets the user and group ids of the process, but does not
change the environment; therefore, all variables including $USER, $HOME,
$LOGNAME, $SHELL etc. are inherited from the old users environment.
Note: starting a SETUID program after applying substuser or setuid gives the
process the SETUID owner, which might give root privileges again.
Option: substuser-delayed=user
Aliases: su-d=user
Type: UIDT (unsigned int or string)
Option group: PROCESS
Phase: INIT
Platforms: all
Like substuser, but reads the user and group information in an early phase of
address processing, but applies the appropriate system calls in a late
phase. This allows to use user information from the host in a chroot
environment, without exposing this data within the sandbox.
Option: o-trunc
Aliases: trunc
Type: BOOL
Option group: OPEN
Phase: LATE
Platforms: all
Sets the O_TRUNC flag of the open() call, thus truncating the file to zero
length.
#! block devices?
Option: ftruncate=value
Aliases: truncate=value
Type: OFF32 or OFF64
Option group: REG
Phase: LATE
Platforms: HP-UX, Linux, SunOS
Invokes the ftruncate() (or ftruncate64() if available) call for the file descriptor with the given value,
thus reducing the length of the file to the given length.
On Linux, ftruncate() fails on sockets and devices but works on regular files
and pipes.
#! block devices?
Note: AIX docu says: for regular files only
Option: ftruncate32=value
Type: OFF32
Option group: REG
Phase: LATE
Platforms: HP-UX, Linux, SunOS
Invokes the ftruncate() call (even if ftruncate64() is available) call for the file descriptor with the given value,
thus reducing the length of the file to the given length.
Option: ftruncate64=value
Type: OFF64
Option group: REG
Phase: LATE
Platforms: all
Invokes the ftruncate64() call if available, for the file descriptor with the given value,
thus reducing the length of the file to the given length.
Option: o-binary
Aliases: binary, bin
Type: BOOL
Option group: FD
Phase: OPEN
Platforms: none; Cygwin
Sets the O_BINARY flag with open() or fcntl() to avoid implicit line terminator conversions.
Option: o-text
Aliases: text
Type: BOOL
Option group: FD
Phase: OPEN
Platforms: none; Cygwin
Sets the O_TEXT flag with open() or fcntl() to force implicit line terminator conversions.
Option: o-noinherit
Aliases: noinherit
Type: BOOL
Option group: FD
Phase: OPEN
Platforms: none; Cygwin
Sets the O_NOINHERIT flag with open() or fcntl() to not keep this file open in a spawned process.
Option: cool-write
Aliases: coolwrite
Type: BOOL
Option group: FD
Phase: INIT
Platforms: all
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.
Option: end-close
Aliases: close
Type: CONST
Option group: FD
Phase: INIT
Platforms: all
Changes the (address dependent) method to close a connection to just close
the file descriptors. This is useful when the connection is to be reused by
or shared with other processes.
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.
Option: user=value
Aliases: owner=value, uid=value
Type: UIDT (unsigned int or string)
Option group: NAMED
Phase: FD
Platforms: all
Takes one argument, a UNIX user name or a numeric user id. The first
character of value is a digit for user ids.
For NAMED addresses, if the file already exists, this option is applied via a
chown() call, with fchown() for all other cases.
If username is a name it must be a valid username from /etc/passwd and is
converted to a user id with a getpwnam() call.
On sane operating systems, the owner of the process must be root to change
the owner of a file descriptor; root may even apply undefined (unnamed) user
ids.
My Linux 2.2 kernel SIGSEGVs the process in the fchown() call when this
option is used with a (UNIX, unconnected or connected) socket or pipe. Linux
2.4.0 handles this call correctly.
TESTCASE: ./socat -d -d -d -d - tcp:loopback:21,user=root
Option: user-late=value
Aliases: uid-l=value
Type: UIDT (unsigned int or string)
Option group: FD
Phase: LATE
Platforms: all
Takes one argument, a UNIX user name or a numeric user id. The first
character of value is a digit for user ids.
This option is applied via a fchown() call just before xioopen_single()
terminates.
If username is a name it must be a valid username from /etc/passwd and is
converted to a user id with a getpwnam() call.
On sane operating systems, the owner of the process must be root to change
the owner of a file descriptor; root may even apply undefined (unnamed) user
ids.
My Linux 2.2 kernel SIGSEGVs the process in the fchown() call when this
option is used with a socket or pipe.
===============================================================================
OPEN group options
Options of this group may be used with all addresses that support OPEN group
options.
Option: o-rdonly
Aliases: rdonly
Type: BOOL (inherent - no value)
Option group: OPEN
Phase: OPEN
Platforms: all
Use O_RDONLY with the open() call instead of the position dependend default.
Take care not to block later write operations.
Option: o-wronly
Aliases: wronly
Type: BOOL (inherent - no value)
Option group: OPEN
Phase: OPEN
Platforms: all
Use O_WRONLY with the open() call instead of the position dependend default.
Take care not to block later write operations.
Option: o-rdwr
Aliases: rdwr
Type: BOOL (inherent - no value)
Option group: OPEN
Phase: OPEN
Platforms: all
Use O_RDWR with the open() call instead of the position dependend default.
Option: o-create
Aliases: create, creat
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: all
Sets the O_CREAT flag of the open() call. This means that it is not an error if
the file does not exist.
Option: o-defer
Aliases: defer
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: none
Sets the O_DEFER flag of the open() call. This means that write data is stored
in paging space until an fsync() call.
Option: o-delay
Aliases: delay
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: none
Sets the O_DELAY flag of the open() call. This lets open block until the share
conditions are fulfilled (see nshare, rshare)
Option: o-direct
Aliases: direct
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: FreeBSD, HP-UX, Linux
Sets the O_DIRECT flag of the open() call.
Option: o-directory
Aliases: directory
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: Linux
Sets the O_DIRECTORY flag of the open() call. This lets open fail if the given
path is not a directory. This does not seem to be useful with socat.
Option: o-dsync
Aliases: dsync
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: HP-UX, Linux, SunOS (UNIX98)
Sets the O_DSYNC flag with the open() call. This lets write() calls wait until
modification metainfo is physically written to media.
Option: o-excl
Aliases: excl
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: all
Sets the O_EXCL flag of the open() call.
Option: o-largefile
Aliases: largefile
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: HP-UX, Linux, SunOS
Sets the O_LARGEFILE flag of the open() flag.
Option: o-noctty
Aliases: noctty
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: all
Sets the O_NOCTTY flag of the open() call, so the opened device does not become
the controlling tty of the process.
Option: o-nofollow
Aliases: nofollow
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: FreeBSD, Linux
Sets the O_NOFOLLOW flag of the open() call. This means that the last component
of the open path must no be a symlink.
Option: o-sync
Aliases: sync
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: all (UNIX98)
Sets the O_SYNC flag with the open() call. This lets write() calls wait until
data is physically written to media.
Option: o-rshare
Aliases: rshare
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: none
Sets the O_RSHARE flag of the open() call. This means that the file must not be
opened for writing by other processes ("read sharing").
Option: o-nshare
Aliases: nshare
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: none
Sets the O_NSHARE flag of the open() call. This means that the file must not be
shared with other processes ("no sharing").
Option: o-rsync
Aliases: rsync
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: HP-UX, Linux, SunOS (UNIX98)
Sets the O_RSYNC flag with the open() call. This lets write() calls wait until
read metainfo is physically written to media.
Option: o-priv
Aliases: priv
Type: BOOL
Option group: OPEN
Phase: OPEN
Platforms: none (Solaris)
Sets the O_PRIV flag with the open() call.
===============================================================================
NAMED group options
This group is valid for all addresses that refer to a file system entry like
file, device, named pipe, or named UNIX domain socket.
Option: unlink-early
Aliases: new
Type: BOOL
Option group: NAMED
Phase: EARLY
Platforms: all
This options tries to remove the filesystem entry given in the address before
starting any other processing (even before user-early, perm-early, or
group-early). unlink() is called; note that this call, in contrast to rm(1),
removes entries regardless of their permissions. Instead, ownership or root
privileges and write permissions in the directory are required and sufficient.
Option: unlink
Type: BOOL
Option group: NAMED
Phase: PREOPEN
Platforms: all
This options tries to remove the filesystem entry given in the address before
it is tried to open, but past user-early, perm-early, or group-early).
unlink() is called; note that this call, in contrast to rm(1), removes entries
regardless of their permissions. Instead, ownership or root privileges and
write permissions in the directory are required and sufficient.
Option: unlink-late
Type: BOOL
Option group: NAMED
Phase: PASTOPEN
Platforms: all
This option tries to remove the filesystem entry after it has been opened.
Options can still be applied to the file descriptor, and
the node or files data can be used, but it can no longer be accessed by other
processes (except by tricks?), and after closing the stream the data or node is
completely removed.
unlink() is called; note that this call, in contrast to rm(1), removes entries
regardless of their permissions. Instead, ownership or root privileges and
write permissions in the directory are required and sufficient.
Option: perm-early=value
Type: MODET (mode_t)
Option group: NAMED
Phase: PREOPEN
Platforms: all
This option changes the mode (permissions) of an already existing filesystem
entry with chmod() before the file is opened or after the UNIX domain socket is
bound, but before it listens/connects.
Option: user-early=value
Aliases: uid-e=value
Type: UIDT (unsigned int or string)
Option group: NAMED
Phase: PREOPEN
Platforms: all
Takes one argument, a UNIX user name or a numeric user id. The first
character of value is a digit for user ids.
This option is applied via a chown() call before the file system entry is
opened or after the UNIX domain socket is bound, but before it starts to
listen/connect.
If username is a name it must be a valid username from /etc/passwd and is
converted to a user id with a getpwnam() call.
On sane operating systems, the owner of the process must be root to change
the owner of a file descriptor; root may even apply undefined (unnamed) user
ids.
Option: group-early=value
Aliases: gid-e=value
Type: GIDT (unsigned int or string)
Option group: NAMED
Phase: PREOPEN
Platforms: all
Takes one argument, a UNIX group name or a numeric group id. The first
character of value is a digit for group ids.
This option is applied via a chown() call before the file system entry is
opened or after the UNIX domain socket is bound, but before it
listens/connects.
If groupname is a name it must be a valid groupname from /etc/group and is
converted to a group id with a getgrnam() call.
On most modern operating systems, the owner of the process must be member of
the group being set; only root may set any group, even numbers without group
name.
Option: umask=value
Type: MODET
Option group: NAMED
Phase: EARLY
Platforms: all
Sets the umask before opening a file or creating a UNIX domain socket. This is
especially useful for these sockets, because there interface does not provide a
mode argument.
Option: unlink-close
Type: BOOL
Option group: NAMED
Phase: LATE
Platforms: all
Remove 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.
===============================================================================
FORK and EXEC options
Option: path=string
Type: STRING
Option group: EXEC
Phase: PREEXEC
Platforms: all
Changes the PATH environment variable in the child process before the exec() or
system() call.
Option: nofork
Type: BOOL
Option group: FORK
Phase: BIGEN
Platforms: all
Does not fork a subprocess for executing the program, instead calls execvp()
directly from the actual socat instance. This avoids the overhead of another process
between the program and the communication peer, but introduces lots of
restrictions:
* this option can only be applied to the second socat() address.
* the first socat address cannot be OPENSSL or READLINE
* socat options -b, -t, -D, -l, -v, -x, -t become useless
* for both addresses, options ignoreeof, cr and crnl become useless
* for the second address (the one with option nofork), options
append, async, cloexec, flock, user, group, mode, nonblock,
perm-late, setlk, and setpgid cannot be applied, and should be used on the
first address instead.
Option: pipes
Type: BOOL
Option group: FORK
Phase: BIGEN
Platforms: all
For communication between the exec() or system() subprocess with socat, use two
unnamed pipes instead of creating a socket pair.
Option: pty
Type: BOOL
Option group: FORK
Phase: BIGEN
Platforms: all
For communication between the exec() or system() subprocess with socat, use a
pseudo terminal instead of a socket pair. The executed program gets the slave
side, and socat the controlling side of the pseudo terminal.
This is especially useful if you want to use, e.g., chat with socat (see
EXAMPLES). Plus, ptys do not buffer I/O.
Note: implementation of pseudo terminals are differing between platforms, so
extra porting struggles might be required for porting this feature.
Option: fdin=num
Type: USHORT
Option group: FORK
Phase: PASTBIGEN
Platforms: all
After forking the child process, assign the stream where the child
receives data from socat, to file descriptor num instead of stdin.
Option: fdout=num
Type: USHORT
Option group: FORK
Phase: PASTBIGEN
Platforms: all
After forking the child process, assign the stream where the child
writes data to socat, to file descriptor num instead of stdout.
Option: stderr
Type: BOOL
Option group: FORK
Phase: PASTFORK
Platforms: all
Normally, the stderr filedescriptor of the forked program is a clone of socat's
stderr fd. If this option is used, the programs stderr filedescriptor is a copy
of the "normal" data output of the program, i.e. of its stdout or fdout.
Option: setsid
Aliases: sid
Type: BOOL
Option group: PROCESS
Phase: LATE
Platforms: all
Invokes setsid() to make the forked off subprocess the leader of a new
session. This also generates a new process group with this process as leader.
This is useful, e.g., when exec'ing ssh to get the password prompt into the I/O
channel (see EXAMPLES)
Option: setpgid
Aliases: pgid
Type: INT
Option group: FORK
Phase: LATE
Platforms: all
Invokes setpgid(0, val) from the child process.
Option: tiocsctty
Aliases: ctty
Type: BOOL
Option group: TERMIOS
Phase: LATE2
Platforms: all
Applies only in combination with the pty option or its variants. Tries to make
the pty the controlling terminal. May require option setsid to work correctly.
Option: dash
Aliases: login
Type: BOOL
Option group: EXEC
Phase: PREEXEC
Platforms: all
Prefixes argv[0] for the execvp() call with '-', thus making a shell behave as
login shell.
Option: sighup
Type: CONST
Option group: PARENT
Phase: LATE
Platforms: all
Has socat pass an eventual SIGHUP signal to the sub process.
If no address has this option, socat terminates on SIGHUP.
Option: sigint
Type: CONST
Option group: PARENT
Phase: LATE
Platforms: all
Has socat pass an eventual SIGINT signal to the sub process.
If no address has this option, socat terminates on SIGINT.
Option: sigquit
Type: CONST
Option group: PARENT
Phase: LATE
Platforms: all
Has socat pass an eventual SIGQUIT signal to the sub process.
If no address has this option, socat dumps core and terminates on SIGQUIT.
===============================================================================
PTY options
These options may be used with addresses that create a pseudo terminal (pty).
In particular, these are addresses EXEC, SYSTEM, and PTY.
Option: openpty
Type: BOOL
Option group: PTY
Phase: BIGEN
Platforms: FreeBSD, Linux
Like pty, but only use the openpty mechanism, not any other way for pty
generation.
Option: ptmx
Type: BOOL
Option group: PTY
Phase: BIGEN
Platforms: HP-UX, Linux, SunOS
Like pty, but only use the /dev/ptmx (/dev/ptc on AIX) mechanism, not any other
way for pty generation.
Option: symbolic-link=filename
Type: FILENAME
Option group: PTY
Phase: LATE
Platforms: all
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.
Option: pty-wait-slave
Aliases: wait-slave, waitslave
Type: BOOL
Option group: PTY
Phase: EARLY
Platforms: all
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 engine. 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 tt(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.
Option: pty-interval
Type: TIMESPEC
Option group: PTY
Phase: EARLY
Platforms: all
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 interval is 1s. Use the pty-interval option to change this value.
===============================================================================
SOCKET options
These are options that may be applied to all socket type addresses: UNIX
(LOCAL) domain sockets (even with EXEC type addresses if not pipes), IP, and
IPv6.
Option: so-debug
Aliases: debug
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Sets the SO_DEBUG socket option. Requires root.
Option: so-acceptconn
Aliases: acceptconn
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Tries to set the SO_ACCEPTCONN socket option. Read-only!
Option: so-broadcast
Aliases: broadcast
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Sets the SO_BROADCAST socket option.
Option: so-reuseaddr
Aliases: reuseaddr
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Sets the SO_REUSEADDR socket option. Allows to bind to a port even if this
port is already used for a connection.
Option: so-keepalive
Aliases: keepalive
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: FD
Platforms: all (UNIX98)
Sets the SO_KEEPALIVE socket option.
Option: so-linger=value
Aliases: linger=value
Type: LINGER
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Activates the SO_LINGER option and sets a value (seconds) for it.
This lets shutdown() or close() block until data transfers have finished or the
given value timed out.
Note: on some systems, the type for setsockopt() is struct { int; int; }
In this case, xioopen() sets {1,value}.
Option: so-oobinline
Aliases: oobinline
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Sets the SO_OOBINLINE socket option.
Option: so-sndbuf=value
Aliases: sndbuf=value
Type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Sets the SO_SNDBUF option of the socket to the given value. This option is
applied after the socket() (or socketpair()) call.
NOTE: The kernel might change the effective value:
My Linux 2.2 with TCP doubles the value, but uses at least 2048.
Option: so-sndbuf-late=value
Aliases: sndbuf-late=value
Type: INT
Option group: SOCKET
Phase: LATE
Platforms: all (UNIX98)
Sets the SO_SNDBUF option of the socket to the given value. This option is
applied after the connect() or accept() (or socketpair) call.
NOTE: The kernel might change the effective value:
My Linux 2.2 with TCP doubles the value, but uses at least 2048, and a
maximum of 131070 (system limit?).
Option: so-rcvbuf=value
Aliases: rcvbuf=value
Type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Sets the SO_RCVBUF option of the socket to the given value. This option is
applied after the socket() call.
NOTE: The kernel might change the effective value:
My Linux 2.2 with TCP connect doubles the value, but uses at least 256 and
at most 131070.
My Linux 2.2 with TCP listen doubles the value but uses at least 11772.
NOTE: For applying the SO_RCVBUF options after the connect() or accept() calls
see rcvbuf-late.
Option: so-rcvbuf-late=value
Aliases: rcvbuf-late=value
Type: INT
Option group: SOCKET
Phase: LATE
Platforms: all (UNIX98)
Sets the SO_RCVBUF option of the socket to the given value. This option is
applied after the connect() or listen() call.
NOTE: The kernel might change the effective value:
My Linux 2.2 with TCP doubles the value, but uses at least 256 and maximal
131070.
NOTE: sequence of this call may be relevant for the effecting value (AIX
4.3.3). For applying the SO_RCVBUF option immediately after the socket() call
see rcvbuf.
Option: so-error
Aliases: error
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Tries to set the SO_ERROR socket option which is a read-only option.
On my Linux 2.2 it gives "protocol not available".
Option: so-type=value
Aliases: type=value
Type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all
Set the sockettype argument of the socket() or socketpair() call. This
overrides the per
protocol default (e.g., TCP: SOCK_STREAM). Most values might
not be supported by a given protocol.
The following combinations are known to work at least under one OS:
TCP SOCK_STREAM (system default)
UDP SOCK_DGRAM (system default)
IP SOCK_RAW (socat default)
UNIX SOCK_STREAM (system default)
UNIX SOCK_DGRAM
Option: so-dontroute
Aliases: dontroute
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Sets the SO_DONTROUTE socket option.
Option: so-rcvlowat=value
Aliases: rcvlowat=value
Type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Sets the SO_RCVLOWAT socket option. Cannot be changed in Linux (always
gives "protocol not available").
Option: so-rcvtimeo=value
Aliases: rcvtimeo=value
Provided type: double
Physical type: TIMEVAL (long[2])
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Sets the SO_RCVTIMOE socket option. Cannot be changed in Linux (always
gives "protocol not available").
Option: so-sndlowat=value
Aliases: sndlowat=value
Type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Sets the SO_SNDLOWAT socket option. Cannot be changed in Linux (always
gives "protocol not available").
Option: so-sndtimeo=value
Aliases: sndtimeo=value
Provided type: double
Physical type: TIMEVAL (long[2])
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all (UNIX98)
Sets the SO_SNDTIMEO socket option. Cannot be changed in Linux (always
gives "protocol not available").
Option: so-audit
Aliases: audit
Type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: none
Sets the SO_AUDIT socket option.
Option: so-attach-filter
Aliases: attach-filter, attachfilter
Type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: Linux
Linux docu recommends to use libpcap for this feature.
"protocol not available", need kernel CONFIG_FILTER!
Option: so-detach-filter
Aliases: detach-filter, detachfilter
Type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: Linux
See Linux "man 7 socket".
"protocol not available", need kernel CONFIG_FILTER!
Option: so-bindtodevice=string
Aliases: bindtodevice, interface, if
Type: NAME
Option group: SOCKET
Phase: PASTSOCKET
Platforms: Linux
Binds the socket to a net interface, e.g. lo0 or eth0 (interface names depend
on operating system). Might require root privilege.
Option: so-bsdcompat
Aliases: bsdcompat
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: none
Sets the SO_BSDCOMPAT socket option. See Linux "man 7 socket".
Option: so-cksumrecv
Aliases: cksumrecv
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: none
Sets the SO_CKSUMRECV socket option.
Option: so-kernaccept
Aliases: kernaccept
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: none
Sets the SO_KERNACCEPT socket option.
Option: so-no-check
Aliases: no-check, nocheck
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: Linux
Sets the SO_NO_CHECK socket option." Intentionally undocumented" under
Linux (see "man 7 socket"), don't know what it does....
Option: so-noreuseaddr
Aliases: noreuseaddr
Type: INT?
Option group: SOCKET
Phase: PASTSOCKET
Platforms: none
Sets the SO_NOREUSEADDR socket option.
Option: passcred
Aliases: so-passcred
Type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: Linux
Sets the SO_PASSCRED option of a socket.
Option: so-peercred
Aliases: peercred
Type: INT3 or int[3]?
Option group: SOCKET
Phase: PASTSOCKET
Platforms: Linux
Enables receiving of credentials. Read only.
Not really implemented yet.
Nevertheless, Gives "Protocol not available".
Option: so-priority=value
Aliases: priority=value
Type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: Linux
Sets the protocol defined priority for all packets to be sent on this socket.
Docu says it requires root privileges. Normal user may set 0..6 for UNIX domain
and TCP client sockets on Linux 2.2. root may send any int value.
Option: so-reuseport
Aliases: reuseport
Type: INT?
Option group: SOCKET
Phase: PASTSOCKET
Platforms: FreeBSD, HP-UX
Sets the SO_REUSEPORT socket option.
Option: so-security-authentication
Aliases: security-authentication, securityauthentication
Type: INT?
Option group: SOCKET
Phase: PASTSOCKET
Platforms: Linux
Sets the SO_SECURITY_AUTHENTICATION socket option. Gives "protocol not
available" error.
In Linux 2.2.16 source, only exists in asm-*/socket.h
Option: so-security-encryption-network
Aliases: security-encryption-network, securityencryptionnetwork
Type: INT?
Option group: SOCKET
Phase: PASTSOCKET
Platforms: Linux
Sets the SO_SECURITY_ENCRYPTION_NETWORK option of the socket. Gives "protocol
not available" error.
In Linux 2.2.16 source, only exists in asm-*/socket.h
Option: so-security-encryption-transport
Aliases: security-encryption-transport, securityencryptiontransport
Type: INT?
Option group: SOCKET
Phase: PASTSOCKET
Platforms: Linux
Sets the SO_SECURITY_ENCRYPTION_TRANSPORT option of the socket. Gives "protocol
not available" error.
In Linux 2.2.16 source, only exists in asm-*/socket.h
Option: so-use-ifbufs
Aliases: use-ifbufs, useifbufs
Type: INT?
Option group: SOCKET
Phase: PASTSOCKET
Platforms: none
Sets the SO_USE_IFBUFS socket option.
Option: so-useloopback
Aliases: useloopback
Type: INT?
Option group: SOCKET
Phase: PASTSOCKET
Platforms: FreeBSD, HP-UX, SunOS
Sets the SO_USELOOPBACK socket option.
Option: so-dgram-errind
Aliases: dgram-errind, dgramerrind
Logical type: bool?
Physical type: INT?
Option group: SOCKET
Phase: PASTSOCKET
Platforms: SunOS
Sets the SO_DGRAM_ERRIND flag.
Option: so-dontlinger
Aliases: dontlinger
Type: INT?
Option group: SOCKET
Phase: PASTSOCKET
Platforms: SunOS
Sets the SO_DONTLINGER socket option.
Option: so-prototype
Aliases: prototype
Type: INT?
Option group: SOCKET
Phase: PASTSOCKET
Platforms: HP-UX, SunOS
Sets the SO_PROTOTYPE socket option.
Option: type
Type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all
Sets the type of the socket, usually as argument to the socket() or
socketpair() call, to <type>. Under Linux, 1 means stream oriented socket, 2
means datagram socket, and 3 means raw socket.
Option: protocol-family
Aliases: pf
Type: STRING
Option group: SOCKET
Phase: PRESOCKET
Platforms: all
Forces the use of the specified IP version. <string> can be something like
"ip4" or "ip6".
Option: fiosetown
Logical type: bool
Physical type: INT
Option group: SOCKET
Phase: PASTSOCKET
Platforms: FreeBSD, Linux
Sets the FIOSETOWN ioctl (in "man 7 socket" called FIOCSETOWN).
#Option: ciocspgrp
#
#Allowed in addresses: SOCKET
#Logical type: bool
#Physical type: int
#
#Sets the CIOCSPGRP ioctl.
#Option: addr=value
#
#Allowed in addresses: SOCKET
#Type: socket-address
#
#For client socket, sets the local (bind) address. Not yet implemented.
Option: bind=socketaddress
Type: STRING
Option group: SOCKET
Phase: BIND
Platforms: all
Gives the address to be used in the bind(2) system call. The format of the
socketaddress depends on the socket type (see below). For "client" sockets this
option inserts a bind(2) call between socket(2) and connect(2) calls. For
"server" sockets this option is ignored! For datagram sockets behaviour of this
option is currently unspecified.
Note: for client sockets in the UNIX domain this option is not useful: with the
same address as connect it will conflict with the bind call of the server
socket; another address for bind is ignored (with Linux 2.2).
For TCP sockets these formats are currently implemented:
HOSTNAME
HOSTNAME:PORT
IPADDR
IPADDR:PORT
:PORT
.PORT
Option: connect-timeout=seconds
Type: TIMEVAL
Option group: SOCKET
Phase: PASTSOCKET
Platforms: all
Abort the connection attempt after the given time with error status.
#
Option: backlog=value
Type: INT
Option group: LISTEN
Phase: LISTEN
Platforms: all
Sets the value to be used with the listen(2) system call. The default is 5.
It does not seem to work for Linux 2.2; Linux seems to allow much more
established connections, but then they stay even after server process
shutdown...
Option: range=address:mask, range=address/bits
Type: STRING
Option group: RANGE
Phase: ACCEPT
Platforms: all
Implementation status: only for INET (IP4) addresses
Defines a subnet where clients may connect from. If other clients connect the
accepted connection is shut down immediately after examination of the client
address. If this option is not used, the default is 0.0.0.0:0.0.0.0, allowing
arbitrary client addresses. bits is the number of high order bits that must
match between the range value and the clients address.
Option: tcpwrap, tcpwrap=name
Type: STRING_NULL
Option group: RANGE
Phase: ACCEPT
Platforms: (depends on libwrap installation)
Uses the rules introduced by Wietse Venema's libwrap (tcpd) library to check
if the client is allowed to connect. The configuration files are
/etc/hosts.allow and /etc/hosts.deny. See "man 5 hosts_access" for
more information. <name> is passed to the wrapper functions as daemon
process name. If omitted, the basename of socats invokation (argv[0]) is
passed.
If both tcpwrap and and range options are applied to an address, both
conditions must be fulfilled to allow the connection.
Option: hosts-allow, tcpwrap-hosts-allow-table
Type: FILENAME
Option group: RANGE
Phase: ACCEPT
Platforms: (depends on libwrap installation)
Takes the specified file instead of /etc/hosts.allow.
Option: hosts-deny, tcpwrap-hosts-deny-table
Type: FILENAME
Option group: RANGE
Phase: ACCEPT
Platforms: (depends on libwrap installation)
Takes the specified file instead of /etc/hosts.deny.
Option: tcpwrap-etc, tcpwrap-dir
Type: FILENAME
Option group: RANGE
Phase: ACCEPT
Platforms: (depends on libwrap installation)
Looks for hosts.allow and hosts.deny in the specified directory. Is
overriden by options hosts-allow and hosts-deny.
-------------------------------------------------------------------------------
IP options
Option: ip-options=values
Aliases: ipoptions
Type: BIN
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: all
Sets the IP_OPTIONS values of the IP socket. For example, to send packets to
destination D.D.D.D via a router G.G.G.G you have to specify G.G.G.G as the
"normal" destination, and D.D.D.D in the source route:
TCP:G.G.G.G:25,ip-options=x890704dddddddd
Note that the destination will see G.G.G.G as sender of the packets, and
therefore might not return the answers correctly.
See RFC791 for detailed specification of IP option fields.
Examples:
x01 ... nop
x8307040a000001 ... loose source route
x890b040a000001c0c1c2c3 ... strict source route
Note: with source routes, you should not specifiy destination address and
hops as defined in RFC791 (first hop as IP header destination address,
further hops and final destination in source route) because the (Linux?) kernel changes
them to a more intuitive form (final destination as destination in IP header,
gateways in source route). So, in destination address give the final
destination, and in the source route the gateways!
Note: this option may be mulitply applied per socket but the (Linux?) kernel
pads each setting with 0' to align the options end to 4 octets. So you should
better pad the options data with nops (01) yourself.
Option: ip-pktinfo
Aliases: ippktinfo, pktinfo
Type: INT (should be struct in_pktinfo)
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: Linux
Status: Not completely implemented (ancillary messages are not supported by
socat/xio)
Pass an IP_PKTINFO ancillary message.
Option: ip-recvtos
Aliases: iprecvtos, recvtos
Logical type: bool
Physical type: INT
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: Linux
Status: Not completely implemented (ancillary messages are not supported by
socat/xio)
Set the IP_RECVTOS socket option which enables IP_TOS ancillary message
passing.
Option: ip-recvttl
Aliases: iprecvttl, recvttl
Logical type: bool
Physical type: INT
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: all
Implementation status: No results.
Set the IP_RECVTTL socket option.
Option: ip-recvopts
Aliases: iprecvopts, recvopts
Logical type: bool
Physical type: INT
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: all
Implementation status: No results.
Set the IP_RECVOPTS socket option.
Option: ip-retopts
Aliases: ipretopts, retopts
Logical type: bool
Physical type: INT
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: all
Implementation status: No results.
Set the IP_RETOPTS socket option.
Option: ip-tos=value
Aliases: iptos=value, tos=value
Logical type: byte
Physical type: INT
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: all
Sets the TOS (type of service) flags for the outgoing IP headers of the
socket. My Linux 2.2 does not allow to set values other than 0 (probably
needs some optional kernel features).
Option: ip-ttl=value
Aliases: ipttl=value, ttl=value
Logical type: byte
Physical type: INT
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: all
Sets the TTL (time to live) field for the outgoing IP headers of the socket.
0 does not seem to be useful and gives "invalid argument" error in Linux.
This option can be used to implement a "poor mans traceroute" in conjunction
with tcpdump.
Option: ip-hdrincl
Aliases: iphdrincl, hdrincl
Logical type: bool
Physical type: INT
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: all
Set the IP_HDRINCL socket option. User will supply IP header before user
data. For raw IP sockets only. Not tested.
Option: ip-recverr
Aliases: iprecverr, recverr
Type: INT
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: Linux
Set the IP_RECVERR socket option.
Implementation status: No results.
Option: ip-mtu-discover=value
Aliases: ipmtudiscover=value, mtudiscover=value
Type: INT (0..2)
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: Linux
Sets the IP_MTU_DISCOVER flag of the IP socket. In Linux there are three values
defined: 0..dont(never), 1..want(per route), 2..do(always)
Option: ip-mtu
Aliases: ipmtu, mtu
Type: INT
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: none
Sets the MTU (maximal transfer unit) of the socket. In Linux this is a
read-only parameter and results in a "protocol not available" error.
Option: ip-freebind
Aliases: ipfreebind, freebind
Logical type: bool
Physical type: INT
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: none
Allows the socket to locally bind to any address, even those that are
not covered by an interface address, alias address or a local subnet. Even
broadcast and multicast addresses are possible.
Note: this option has been found on Linux 2.4 in <linux/in.h>. This file might
not be included per default, because it creates errors.
To make this option available, "make" socat with the CCOPT environment
variable set to "-DIP_FREEBIND=15"
Option: ip-router-alert=value
Aliases: iprouteralert, routeralert
Type: INT
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: Linux
Sets the IP_ROUTER_ALERT socket option. Only works with raw sockets.
"Invalid argument"
Option: 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
Aliases: add-membership
ip-membership
Type: IP_MREQN
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: all
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 tt(struct mreqn) (Linux).nl()
The indices of active network interfaces can be shown using the utility
procan().
Option: ip-drop-membership
Not implemented.
#! Option: ipv6-join-group
Option: ip-multicast-ttl=byte
Aliases: ipmulticastttl, multicastttl
Type: BYTE
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: all
Sets the TTL used for outgoing multicast traffic. Default is 1.
Option: ip-multicast-loop
Aliases: ipmulticastloop, multicastloop
Logical type: bool
Physical type: INT
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: all
Specifies if outgoing multicast traffic should loop back to the interface.
Option: ip-multicast-if=hostname
Aliases: multicast-if
Type: IP4NAME
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: all
Specifies hostname or address of the network interface to be used for
multicast traffic.
Option: ip-pktoptions
Aliases: ippktoptions, pktoptions, pktopts
Type: INT?
Option group: SOCK_IP
Phase: PASTSOCKET
Platforms: Linux
Set the IP_PKTOPTIONS socket option. No docu found.
Implementation status: "Protocol not available".
Option: res-debug
Type: BOOL
Option group: SOCK_IP
Phase: INIT
Platforms: all
Apply the debug resolver option to all queries of this XIO address.
Option: res-aaonly
Aliases: aaonly
Type: BOOL
Option group: SOCK_IP
Phase: INIT
Platforms: all
Apply the aaonly resolver option to all queries of this XIO address.
Option: res-usevc
Aliases: usevc
Type: BOOL
Option group: SOCK_IP
Phase: INIT
Platforms: all
Apply the usevc resolver option to all queries of this XIO address.
Option: res-primary
Aliases: primary
Type: BOOL
Option group: SOCK_IP
Phase: INIT
Platforms: all
Apply the primary resolver option to all queries of this XIO address.
Option: res-igntc
Aliases: igntc
Type: BOOL
Option group: SOCK_IP
Phase: INIT
Platforms: all
Apply the igntc resolver option to all queries of this XIO address.
Option: res-recurse
Aliases: recurse
Type: BOOL
Option group: SOCK_IP
Phase: INIT
Platforms: all
Apply the recurse resolver option to all queries of this XIO address.
Option: res-defnames
Aliases: defnames
Type: BOOL
Option group: SOCK_IP
Phase: INIT
Platforms: all
Apply the defnames resolver option to all queries of this XIO address.
Option: res-stayopen
Aliases: stayopen
Type: BOOL
Option group: SOCK_IP
Phase: INIT
Platforms: all
Apply the stayopen resolver option to all queries of this XIO address.
Option: res-dnsrch
Aliases: dnsrch
Type: BOOL
Option group: SOCK_IP
Phase: INIT
Platforms: all
Apply the dnsrch resolver option to all queries of this XIO address.
-------------------------------------------------------------------------------
IP6 options
Option: ipv6-v6only=value
Alias: ipv6only, v6only
Type: BOOL
Option group: SOCK_IP6
Phase: PASTSOCKET
Platforms: FreeBSD, Linux
Apply the IPV6_V6ONLY socket option to the file descriptor. This controls if
the socket listens only on the IPv6 protocol or also on IPv4.
-------------------------------------------------------------------------------
IPAPP (TCP and UDP) options
Option: sourceport=value
Alias: sp=value
Type: 2BYTE
Option group: IPAPP (IP_TCP and IP_UDP)
Phase: LATE
Platforms: all
For outgoing (client) TCP and UDP connections, it sets the source port (local port, client side port) of
the socket connection. For server type addresses, requires the client to use
this sourceport, otherwise socat immediately shuts down the connection.
On UNIX class operating systems root privilege are required to set a source
port between 1 and 1023 incl. 0 gives a "random" port number >= 1024, which is
the default.
Option: lowport
Type: BOOL
Option group: IPAPP (IP_TCP and IP_UDP)
Phase: LATE
Platforms: all
For outgoing (client) TCP and UDP connections, it sets the source
to an unused random port between 640 and 1023 incl. On UN*X type operating
systems, this requires root privilege, and thus guaranties the peer to be
root authorized.
With TCP or UDP listen addresses, socat immediately shuts down the
connection if the client does not use a sourceport <= 1023.
This mechanism can provide limited authorization under some circumstances.
-------------------------------------------------------------------------------
TCP options
Option: tcp-nodelay
Aliases: nodelay
Logical type: bool
Physical type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: all
Sets the TCP_NODELAY flag of the TCP socket. This turns off Nagles algorithm.
Option: tcp-maxseg
Aliases: maxseg, mss
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: all
Limits the MAXSEG (MSS) value of the TCP socket. This option is applied before
the connect or listen call, so it is transferred in the SYN packet to the peer
socket.
Linux client: 0 gives "invalid argument", higher values are used in SYN
negotiation, but effective MSS is n-12, at least 8.
On AIX, this is a read-only option.
Option: tcp-maxseg-late
Aliases: maxseg-late, mss-late
Type: INT
Option group: IP_TCP
Phase: CONNECTED
Platforms: all
Limits the MAXSEG (MSS) value of the TCP socket. This option is applied past
the connect or accept call, so it is not transferred as MSS to the peer socket.
Observation with Linux 2.2: does not influence the size of packets generated
by the local socket.
Option: tcp-cork
Aliases: cork
Logical type: bool
Physical type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: Linux
Sets the TCP_CORK option.
Option: tcp-stdurg
Aliases: stdurg
Logical type: bool
Physical type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: none
Applies the TCP_STDURG option with setsockopt. This enables RFC 1122 compliant
urgent point handling.
Option: tcp-rfc1323
Aliases: rfc1323
Logical type: bool
Physical type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: none
Applies the TCP_RFC1323 option with setsockopt. This enables RFC1323 TCP
enhancements (window scale, timestamp).
Option: tcp-keepidle
Aliases: keepidle
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: Linux
Sets the TCP_KEEPIDLE value of the socket with setsockopt(). Starts keepalive
after this period (in seconds?)
Option: tcp-keepintvl
Aliases: keepintvl
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: Linux
Sets the TCP_KEEPINTVL value of the socket with setsockopt(). Interval between
keepalives (in seconds?)
Option: tcp-keepcnt
Aliases: keepcnt
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: Linux
Sets the TCP_KEEPCNT value of the socket with setsockopt(). Number of
keepalives before death.
Option: tcp-syncnt
Aliases: syncnt
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: Linux
Sets the TCP_SYNCNT value of the socket with setsockopt(). Number of SYN
retransmits.
Option: tcp-linger2
Aliases: linger2
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: Linux
Sets the TCP_LINGER2 value of the socket with setsockopt(). Life time of
orphaned FIN-WAIT-2 state.
Option: tcp-defer-accept
Aliases: defer-accept
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: Linux
Sets the TCP_DEFER_ACCEPT value of the socket with setsockopt(). accept() of
the listener will only return when data arrived at the new connection. The
value is converted to seconds by some algorithm.
Option: tcp-window-clamp
Aliases: window-clamp
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: Linux
Sets the TCP_WINDOW_CLAMP value of the socket with setsockopt(). "Bound advertised
window".
Option: tcp-info
Aliases: info
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: FreeBSD, Linux
Sets the TCP_INFO value of the socket with setsockopt(). Is a read only option,
so it always generates an error.
Option: tcp-quickack
Aliases: quickack
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: Linux
Sets the TCP_QUICKACK option with setsockopt().
Option: tcp-md5sig
Aliases: md5sig
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: none
Enables generation of MD5 digests on the packets.
Option: tcp-noopt
Aliases: noopt
Type: INT
Option: group: IP_TCP
Phase: PASTSOCKET
Platforms: FreeBSD
Disables use of TCP options.
Option: tcp-nopush
Aliases: nopush
Type: INT
Option: group: IP_TCP
Phase: PASTSOCKET
Platforms: FreeBSD
Sets the TCP_NOPUSH option.
Option: tcp-sack-disable
Aliases: sack-disable
Type: INT
Option: group: IP_TCP
Phase: PASTSOCKET
Platforms: none
Disables use the selective acknowledge feature.
Option: tcp-signature-enable
Aliases: signature-enable
Type: INT
Option: group: IP_TCP
Phase: PASTSOCKET
Platforms: none
Enables generation of MD5 digests on the packets.
Option: tcp-abort-threshold
Aliases: abort-threshold
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: HP-UX, SunOS
Sets the time to wait for an answer of the peer on an established connection.
Option: tcp-conn-abort-threshold
Aliases: conn-abort-threshold
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: HP-UX, SunOS
Sets the time to wait for an answer of the server during the initial connect.
Option: tcp-keepinit
Aliases: keepinit
Type: INT
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: none
Sets the time to wait for an answer of the server during connect() before
giving up. Value in half seconds, default is 150 (75s).
Option: tcp-paws
Aliases: paws
Type: BOOL
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: none
Enables the "protect against wrapped sequence numbers" feature.
Option: tcp-sackena
Aliases: sackena
Type: BOOL
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: none
Enables selective acknowledge.
Option: tcp-tsoptena
Aliases: tsoptena
Type: BOOL
Option group: IP_TCP
Phase: PASTSOCKET
Platforms: none
Enables the time stamp option that allows RTT recalculation on existing
connections.
===============================================================================
SOCKS options
Option: socksport
Type: STRING
Option group: IP_SOCKS4
Phase: LATE
Platforms: all
Overrides the default socks server port 1080
Option: socksuser
Type: NAME
Option group: IP_SOCKS4
Phase: LATE
Platforms: all
Overrides the system derived socks user name ($USER or $LOGNAME or "anonymous")
===============================================================================
HTTP options
Option: proxyport
Type: STRING
Option group: HTTP
Phase: LATE
Platforms: all
Overrides the default HTTP proxy port 8080.
Option: ignorecr
Type: BOOL
Option group: HTTP
Phase: LATE
Platforms: all
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.
Option: proxyauth
Type: STRING
Option group: HTTP
Phase: LATE
Platforms: all
Provide "basic" authentication to the proxy server. The argument to the option
must be the username followed by ':' followed by the password. This string is
used with a "Proxy-Authorize: Base" header in base64 encoded form.
Option: resolve
Type: BOOL
Option group: HTTP
Phase: LATE
Platforms: all
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.
===============================================================================
TERMIOS options
These options are applied with tcsetattr calls with a struct termios.
Attention: Applying these options to stdin/stdout when they refer to your
terminal might directly effect your terminal!
See Linux:"man 3 termios" and Linux:"man 2 stty"
-------------------------------------------------------------------------------
TERMIOS combined modes
Option: raw
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: all
Is equivalent to
ignbrk=0,brkint=0,ignpar=0,parmrk=0,inpck=0,istrip=0,inlcr=0,igncr=0,icrnl=0,ixon=0,ixoff=0,iuclc=0,ixany=0,imaxbel=0,opost=0,isig=0,icanon=0,xcase=0,vmin=1,vtime=0
Option: sane
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: all
Is equivalent to
cread,ignbrk=0,brkint,inlcr=0,igncr=0,icrnl,ixoff=0,iuclc=0,-ixany=0,imaxbel,opost,olcuc=0,ocrnl=0,onlcr,onocr=0,onlret=0,ofill=0,ofdel=0,nl0,cr0,tab0,bs0,vt0,ff0,isig,icanon,iexten,echo,echoe,echok,echonl=0,noflsh=0,xcase=0,tostop=0,echoprt=0,echoctl,echoke
-------------------------------------------------------------------------------
TERMIOS input mode flags
Option: ignbrk
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the IGNBRK flag of the terminal driver.
Option: brkint
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the BRKINT flag of the terminal driver.
Option: ignpar
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the IGNPAR flag of the terminal driver.
Option: parmrk
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the PARMRK flag of the terminal driver.
Option: inpck
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the INPCK flag of the terminal driver. Enables input parity checking.
Option: istrip
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ISTRIP flag of the terminal driver. Strips off the eighth bit.
Option: inlcr
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the INLCR flag of the terminal driver. Translates NL to CR on input.
Option: igncr
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the IGNCR flag of the terminal driver. Ignores CR character on input.
Option: icrnl
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ICRNL flag of the terminal driver. Translates CR to NL on input. This
option is ignored when IGNCR is set.
Option: iuclc
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the IUCLC flag of the terminal driver. Changes characters in input from
uppercase to lowercase.
Option: ixon
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the IXON flag of the terminal driver. Enables XON/XOFF flow control on
output (?).
Option: ixany
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the IXANY flag of the terminal driver. Enables any character to restart
output.
Option: ixoff
Aliases: tandem
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the IXOFF flag of the terminal driver. Enables XON/XOFF flow control on
input.
Option: imaxbel
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the IMAXBEL flag of the terminal driver. Rings the bell when the input
queue is full.
-------------------------------------------------------------------------------
TERMIOS output mode flags
Option: opost
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the OPOST flag of the terminal driver.
Option: olcuc
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the OLCUC flag of the terminal driver.
Option: onlcr
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ONLCR flag of the terminal driver.
Option: ocrnl
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the OCRNL flag of the terminal driver.
Option: onocr
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ONOCR flag of the terminal driver.
Option: onlret
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ONLRET flag of the terminal driver.
Option: ofill
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the OFILL flag of the terminal driver.
Option: ofdel
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the OFDEL flag of the terminal driver.
Option: nldly
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the NLDLY flag of the terminal driver. 0 sets the value to NL0, and 1 to
NL1. See nl0, nl1.
Option: nl0
Type: CONST (const bool, always sets 0)
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the field NLDLY to the value NL0.
Option: nl1
Type: CONST (const bool, always sets 1)
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the field NLDLY to the value NL1.
Option: crdly=value
Type: UINT (0..3)
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the field CRDLY to the given value.
See cr0, cr1, cr2, cr3.
Option: cr0
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the CRDLY field to the value CR0.
See crdly.
Option: cr1
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the CRDLY field to the value CR1.
See crdly.
Option: cr2
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the CRDLY field to the value CR2.
See crdly.
Option: cr3
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the CRDLY field to the value CR3.
See crdly.
Option: tab0
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the horizontal tab delay mask to TAB0.
See tabdly.
Option: tab1
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the horizontal tab delay mask to TAB1.
See tabdly.
Option: tab2
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the horizontal tab delay mask to TAB2.
See tabdly.
Option: tab3
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the horizontal tab delay mask to TAB3.
See tabdly.
Option: tabdly=value
Type: UINT (0..3)
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the field TABDLY to the given value.
See tab0, tab1, tab2, and tab3.
Option: xtabs
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the horizontal tab delay mask to XTABS.
Option: bs0
Type: CONST (0)
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the field BSDLY to the value BS0
Option: bs1
Type: CONST (1)
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the field BSDLY to the value BS1
Option: bsdly
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the BSDLY flag of the terminal driver. 0 sets the value to BS0, and 1 to
BS1. See bs0, bs1.
Option: vt0
Type: CONST (0)
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the field VTDLY to the value VT0
Option: vt1
Type: CONST (1)
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the field VTDLY to the value VT1
Option: vtdly
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the VTDLY flag of the terminal driver. 0 sets the value to VT0, and 1 to
VT1. See vt0, vt1.
Option: ff0
Type: CONST (0)
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the field FFDLY to the value FF0
See ffdly.
Option: ff1
Type: CONST (1)
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the field FFDLY to the value FF1
See ffdly.
Option: ffdly
Type: BOOL (0..1)
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the FFDLY flag of the terminal driver. 0 sets the value to FF0, and 1 to
FF1. See ff0, ff1.
-------------------------------------------------------------------------------
TERMIOS control mode flags
Option: cs5
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the field CSIZE to the value CS5
Option: cs6
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the field CSIZE to the value CS6
Option: cs7
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the field CSIZE to the value CS7
Option: cs8
Type: CONST
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the field CSIZE to the value CS8
Option: csize
Type: UINT (0..3)
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the field CSIZE. 0..CS5, 1..CS6, 2..CS7, 3..CS8
Option: cstopb
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the flag CSTOPB.
Option: cread
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the value of the CREAD flag.
Option: parenb
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the PARENB flag of the terminal driver.
Option: parodd
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the PARODD flag of the terminal driver.
Option: hupcl
Aliases: hup
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the HUPCL flag of the terminal driver.
Option: clocal
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the CLOCAL flag of the terminal driver.
Option: crtscts
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: FreeBSD, Linux, SunOS
Sets the CRTSCTS flag of the terminal driver.
Option: b0 (HP-UX, Linux, SunOS)
Option: b50 (HP-UX, Linux, SunOS)
Option: b75 (HP-UX, Linux, SunOS)
Option: b110 (HP-UX, Linux, SunOS)
Option: b134 (HP-UX, Linux, SunOS)
Option: b150 (HP-UX, Linux, SunOS)
Option: b200 (HP-UX, Linux, SunOS)
Option: b300 (HP-UX, Linux, SunOS)
Option: b600 (HP-UX, Linux, SunOS)
Option: b900 (HP-UX)
Option: b1200 (HP-UX, Linux, SunOS)
Option: b1800 (HP-UX, Linux, SunOS)
Option: b2400 (HP-UX, Linux, SunOS)
Option: b3600 (HP-UX)
Option: b4800 (HP-UX, Linux, SunOS)
Option: b7200 (HP-UX)
Option: b9600 (HP-UX, Linux, SunOS)
Option: b19200 (HP-UX, Linux, SunOS)
Option: b38400 (HP-UX, Linux, SunOS)
Option: b57600 (HP-UX, Linux, SunOS)
Option: b115200 (HP-UX, Linux, SunOS)
Option: b230400 (HP-UX, Linux, SunOS)
Option: b460800 (HP-UX, Linux, SunOS)
Option: b500000 (Linux)
Option: b576000 (Linux)
Option: b921600 (Linux)
Option: b1000000 (Linux)
Option: b1152000 (Linux)
Option: b1500000 (Linux)
Option: b2000000 (Linux)
Option: b2500000 (Linux)
Option: b3000000 (Linux)
Option: b3500000 (Linux)
Option: b4000000 (Linux)
Type: CONST
Option group: TERMIOS
Phase: FD
Sets the baud rate to the implied value. b0 "hangs up" the connection.
Option: ispeed
Type: UINT
Option group: TERMIOS
Phase: FD
Platforms: FreeBSD, Linux
Sets the input baud rate to the specified value. This works on systems where
struct termios has a special c_ispeed field.
Option: ospeed
Type: UINT
Option group: TERMIOS
Phase: FD
Platforms: FreeBSD, Linux
Sets the input baud rate to the specified value. This works on systems where
struct termios has a special c_ospeed field.
-------------------------------------------------------------------------------
TERMIOS local mode flags
Option: isig
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ISIG flag of the terminal driver.
Option: icanon
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ICANON flag of the terminal driver.
Option: xcase
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: HP-UX, Linux, SunOS
Sets the XCASE flag of the terminal driver.
Option: echo
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ECHO flag of the terminal driver.
Option: echoe
Aliases: crterase
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ECHOE flag of the terminal driver.
Option: echok
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ECHOK flag of the terminal driver.
Option: echonl
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ECHONL flag of the terminal driver.
Option: echoctl
Aliases: ctlecho
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ECHOCTL flag of the terminal driver.
Option: echoprt
Aliases: prterase
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ECHOPRT flag of the terminal driver.
Option: echoke
Aliases: crtkill
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the ECHOKE flag of the terminal driver.
Option: flusho
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the FLUSHO flag of the terminal driver.
Option: noflsh
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the NOFLSH flag of the terminal driver.
Option: tostop
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the TOSTOP flag of the terminal driver.
Option: pendin
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the PENDIN flag of the terminal driver.
Option: iexten
Type: BOOL
Option group: TERMIOS
Phase: FD
Platforms: all
Sets the IEXTEN flag of the terminal driver.
-------------------------------------------------------------------------------
TERMIOS options for functional characters
Option: vintr=value
Aliases: intr=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: tested
Sets the value for the VINTR character that interrupts the current process.
On UNIX systems the preset value usually is 3 (^C).
Option: vquit=value
Aliases: quit=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: tested
Sets the value for the VQUIT character that quits the current process.
On my Linux 2.2 system the preset value is 0x1c (^\).
Option: verase=value
Aliases: erase=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: tested
Sets the value for the VERASE character that erases the last character.
On many UNIX systems the preset value is 0x7f.
Option: vkill=value
Aliases: kill=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: tested
Sets the value for the VKILL character that kills (erases) the current line.
On my Linux 2.2 system systems the preset value is 0x15 (^U).
Option: veof=value
Aliases: eof=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: tested
Sets the value for the VEOF character that kills indicate end of file.
On most UNIX systems the preset value is 0x04 (^D).
Option: vtime=value
Aliases: time=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: not tested
Sets the value of VTIME. See "man 1 stty" / time.
On my Linux 2.2 system the preset value is 0.
Option: vmin=value
Aliases: min=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: not tested
Sets the value of VMIN. See "man 1 stty" / time.
On my Linux 2.2 system the preset value is 1.
Option: vswtc=value
Aliases: swtc=value, swtch=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: Linux
Status: not tested
Sets the value of VSWTC. "Switches to a different shell layer".
On my Linux 2.2 system the preset value is 0.
Option: vstart=value
Aliases: start=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: tested
Sets the value for the VSTART character that resumes data flow after a stop.
Usually the preset value is 0x11 (^Q).
Option: vstop=value
Aliases: stop=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: tested
Sets the value for the VSTOP character that stops output.
Usually the preset value is 0x13 (^S)
Option: vsusp=value
Aliases: susp=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: tested
Sets the value for the VSUSP character that suspends the current foreground
process and reactivates the shell.
Usually the preset value is 0x1a (^Z)
Option: vdsusp=value
Aliases: dsusp=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: FreeBSD, HP-UX, SunOS
Status: tested
Sets the value for the VDSUSP character that suspends the current foreground
process and reactivates the shell.
Option: veol=value
Aliases: eol=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: tested with awkward results
Sets the value for the VEOL character that should indicate end of line.
Not clear what differentiates it from the return key; xterm window put "xterm"
into the input buffer.
On my Linux 2.2 system the preset value is 0 (disabled)
Option: vreprint=value
Aliases: reprint=value, rprnt=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: FreeBSD, Linux, SunOS
Status: not tested
Sets the value for the VREPRINT character that should reprint the current line.
On my Linux 2.2 system the preset value is 0x12 (^R). Nevertheless, bash
enters backward search mode.
Option: vdiscard=value
Aliases: discard=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: FreeBSD, Linux, SunOS
Status: not tested
Sets the value for the VDISCARD character.
On my Linux 2.2 system the preset value is 0x0f (^O)
Option: vwerase=value
Aliases: werase=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: tested
Sets the value for the VWERASE character that erases the last word.
On my Linux 2.2 system the preset value is 0x17 (^W)
Option: vlnext=value
Aliases: lnext=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: tested
Sets the value for the VLNEXT character that lets the next input character raw
(not interpreted).
On my Linux 2.2 system the preset value is 0x16 (^V)
Option: veol2=value
Aliases: eol2=value
Type: BYTE
Option group: TERMIOS
Phase: FD
Platforms: all
Status: not tested
Sets the value for the VEOL2 character.
On my Linux 2.2 system the preset value is 0 (disabled).
===============================================================================
READLINE options
Option: history-file=filename
Aliases: history=filename
Type: STRING
Option group: READLINE
Phase: LATE
Platforms: (depends on libreadline installation)
Without this option, the readline address uses only a per process history
list. With this option, socat tries to read history lines during initialization
from the given file, and on termination writes the old and new lines to the
file.
NOTE: currently, no mechanism is implemented for limiting the length of the
history file.
NOTE: filename must be a valid relativ or absolute path; "~" is not supported!
Option: noprompt
Type: BOOL
Option group: READLINE
Phase: LATE
Platforms: all
Since version 1.3.3, 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 the readline call, so it might set the cursor to the first column
of the terminal.
Option: noecho
Type: STRING
Option group: READLINE
Phase: LATE
Platforms: all
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.
Option: prompt
Type: STRING
Option group: READLINE
Phase: LATE
Platforms: all
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.
===============================================================================
OPENSSL options
Option: openssl-cipherlist=string
Aliases: cipherlist=string, ciphers=string, cipher=string
Type: STRING
Option group: OPENSSL
Phase: SPEC
Platforms: (depends on openssl installation)
Selects the list of ciphers that may be used for the connection.
See the man page ciphers(1), section CIPHER LIST FORMAT, for
detailed information about syntax, values, and default of the cipherlist
string.
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.
Option: openssl-method=string
Aliases: method=string
Type: STRING
Option group: OPENSSL
Phase: SPEC
Platforms: (depends on openssl installation)
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.
Option: openssl-verify=bool
Aliases: verify=bool
Type: BOOL
Option group: OPENSSL
Phase: SPEC
Platforms: (depends on openssl installation)
Controls check of the peer's certificate. Default is 1 (true). Disabling
verify might open your socket for everyone!
Option: openssl-certificate=file
Aliases: cert=file
Type: FILENAME
Option group: OPENSSL
Phase: SPEC
Platforms: (depends on openssl installation)
Specifies the file with the certificate. The certificate must be
in OpenSSL format (*.pem). With openssl-listen, this option is strongly
recommended: except with cipher aNULL, "no shared ciphers" error might
occur when no certificate is given.
Option: openssl-key=file
Aliases: key
Type: FILENAME
Option group: OPENSSL
Phase: SPEC
Platforms: (depends on openssl installation)
Specifies the file with the private key. The private key may be in this
file or in the file given with the ref(cert) option. The party that has
to proof that it is the owner of a certificate needs the private key.
Option: openssl-cafile=file
Aliases: cafile
Type: FILENAME
Option group: OPENSSL
Phase: SPEC
Platforms: (depends on openssl installation)
Specifies the file with the trusted (root) authority certificates. The file
must be in PEM format and should contain one or more certificates.
Option: openssl-capath=directory
Aliases: capath
Type: FILENAME
Option group: OPENSSL
Phase: SPEC
Platforms: (depends on openssl installation)
Specify the directory with the trusted (root) certificates. The directory
must contain certificates in PEM format and their hashes (see OpenSSL
documentation)
Option: openssl-egd=file
Aliases: egd
Type: FILENAME
Option group: OPENSSL
Phase: SPEC
Platforms: (depends on openssl installation)
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.
Option: openssl-pseudo
Aliases: pseudo
Type: BOOL
Option group: OPENSSL
Phase: SPEC
Platforms: (depends on openssl installation)
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!
Option: openssl-fips
Aliases: fips
Type: BOOL
Option group: BOOL
Phase: SPEC
Platforms: (depends on OpenSSL installation and FIPS implementation)
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.
Option: openssl-compress
Aliases: compress
Type: STRING
Option group: OPENSSL
Phase: SPEC
Platforms: (depends on openssl installation)
Enable or disable the use of compression for a connection. Setting this to
"none" disables compression, setting it to "auto" lets OpenSSL choose the best
available algorithm supported by both parties. The default is to not touch any
compression-related settings.
NOTE: Requires OpenSSL 0.9.8 or higher.
NOTE: Disabling compression with OpenSSL 0.9.8 affects all new connections in
the same process.
===============================================================================
Application specific address options
Option: ignoreeof
Aliases: ignoreof
Type: BOOL
Option group: APPL
Phase: LATE
Platforms: all
This option has to be supported by the application. For socat it means that an
EOF condition on this data source does not trigger termination procedures, but
instead the read/write loop waits for one second and then tries to read more
input data. This behaviour emulates "tail -f" and might not be useful for all
kinds of input devices, but regular files and /dev/null are good candidates.
Termination of socat then can only occur by EOF condition of the other input
device, an error, or by external events.
Option: cr
Type: CONST
Option group: APPL
Phase: LATE
Platforms: all
The appropriate data endpoint uses CR ('\r', 0x0d) as line terminator
character. Convert data to and from this stream appropriately.
This is useful for, e.g., modems.
Option: crnl
Aliases: crlf
Type: CONST
Option group: APPL
Phase: LATE
Platforms: all
The appropriate data endpoint uses CR+LF ("\r\n", 0x0d0a ) as line terminator
string. Convert data to and from this stream appropriately.
This is useful for, e.g., TCP protocols like SMTP and FTP.
Option: readbytes=num
Aliases: bytes
Type: SIZE_T
Option group: APPL
Phase: LATE
Platforms: all
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).
Option: lockfile=filename
Type: FILENAME
Option group: APPL
Phase: INIT
Platforms: all
If lockfile exists, exits with error. If lockfile does not exist, creates it
and continues; removes lockfile on exit.
Option: waitlock=filename
Type: FILENAME
Option group: APPL
Phase: INIT
Platforms: all
If lockfile exists, waits until it disappears. When lockfile does not exist,
creates it and continues; removes lockfile on exit.
===============================================================================
RETRY options
Option: retry=<num>
Type: UINT
Option group: RETRY
Phase: INIT
Platforms: all
Number of retries before the connection or listen attempt is aborted.
Default is 0, which means just one attempt.
Option: interval=<double>
Type: TIMESPEC
Option group: RETRY
Phase: INIT
Platforms: all
Time between consecutive attempts (seconds). Default is 1 second.
Option: forever
Type: BOOL
Option group: RETRY
Phase: INIT
Platforms: all
Performs an unlimited number of retry attempts.
===============================================================================
EXT2 options
Option: ext2-secrm=<bool>
Aliases: secrm=<bool>
Type: BOOL
Option group: REG
Phase: FD
Platforms: Linux
Sets the secrm file attribute on the file.
Option: ext2-unrm=<bool>
Aliases: unrm=<bool>
Type: BOOL
Option group: REG
Phase: FD
Platforms: Linux
Sets the unrm file attribute on the file.
Option: ext2-compr=<bool>
Aliases: compr=<bool>
Type: BOOL
Option group: REG
Phase: FD
Platforms: Linux
Sets the compr file attribute on the file.
Option: ext2-sync=<bool>
Type: BOOL
Option group: REG
Phase: FD
Platforms: all
Sets the sync file attribute on the file.
Option: ext2-immutable=<bool>
Aliases: immutable=<bool>
Type: BOOL
Option group: REG
Phase: FD
Platforms: Linux
Sets the immutable file attribute on the file.
Option: ext2-append=<bool>
Type: BOOL
Option group: REG
Phase: FD
Platforms: all
Sets the append file attribute on the file.
Option: ext2-nodump=<bool>
Aliases: nodump=<bool>
Type: BOOL
Option group: REG
Phase: FD
Platforms: Linux
Sets the nodump file attribute on the file.
Option: ext2-noatime=<bool>
Type: BOOL
Option group: REG
Phase: FD
Platforms: Linux
Sets the noatime file attribute on the file.
Option: ext2-journal-data=<bool>
Aliases: journal-data=<bool>
Type: BOOL
Option group: REG
Phase: FD
Platforms: Linux
Sets the journal-data file attribute on the file.
Option: ext2-notail=<bool>
Aliases: notail=<bool>
Type: BOOL
Option group: REG
Phase: FD
Platforms: none
Sets the notail file attribute on the file.
Option: ext2-dirsync=<bool>
Aliases: dirsync=<bool>
Type: BOOL
Option group: REG
Phase: FD
Platforms: Linux
Sets the dirsync file attribute on the file.
Option: ext2-topdir=<bool>
Aliases: topdir=<bool>
Type: BOOL
Option group: REG
Phase: FD
Platforms: Linux
Sets the topdir file attribute on the file.
===============================================================================
Appendix: generating a sandbox (chroot environment)
While it is possible to generate a sandbox almost anywhere in the file system,
I recommend to use a file system that has been mounted with restrictions,
especially nosuid and maybe nodev, or even ro.
You may mount a dedicated file system for the sandbox, so it gets a little
harder for the guests to determine for sure if they are within a sandbox when
using "ls -id /"
The following desribes typical steps for generating a sandbox. Depending on
your operating system, application, and security requirements, your mileage may
vary. With the below steps, you will be able to run some check programs to play
around with the sandbox.
I Installation
1) Create a sandbox group - but give it and all following "sandbox" ids a more
cryptic name!
2) Create a sandbox user, only in sandbox group. If this user must never login,
give it a useless shell like /bin/false
3) Check the sandbox home directory (e.g. /home/sandbox) and save and remove
all .profile, public_html/ etc.
4) Optionally mount a new file system over the new home directory
5) Generate subdirectories bin, lib, etc, usr, usr/bin, usr/lib.
Set their permissions and ownership equal to the original directories (or use
only root.root)
6) Generate subdirectory home/sandbox (or similarly; like sandbox home)
7) Generate etc/passwd with users sandbox and root, but do not store original
password hashes there!
8) Generate etc/group with only groups sandbox and root (or system on AIX)
9) Copy test programs and utilities to bin, e.g. su, id, ls, mount, strace (but
without SUID/SGID)
10) Copy the required shared libraries and the shared library loader to their
directories.
On Linux, e.g. /lib/ld-linux.so.2, /lib/libnss_compat.so.2
Note: it is often difficult to find out what shared libraries are (still) not
installed in the sandbox. The programs invoked in the sandbox typically do not
give useful error messages. If chroot's exec call gives an error like "no such
file or directory", and you do not know if it even found the program itself,
then remove the test programs execute permission; the error message should
change to "execute permission denied" or so. Redo the execute permissions and
look for the shared libraries...
List required libraries of a program:
Linux: ldd <program>
AIX: xdb <program>
map
11) For testing purposes, install id, ls, su, mount, strace, and maybe sh in
the sandbox. Test it.
II Customization
12) Copy your applications, configuration files, and data to the appropriate
directories within the sandbox.
Test function of the application in the sandbox, and add missing files and
libraries. If an application program gets killed immediately after start, it
might miss a shared library.
III Cleanup, check
13) Implement your own tricks how to improve security of the sandbox
14) Remove test programs like bin/sh, id, ls, mount, strace
===============================================================================
socket types, modes and their security features:
IP.v4.TCP.connect
IP.v4.TCP.listen range tcpwrap srcport lowport
IP.v4.UDP.connect
IP.v4.UDP.listen range tcpwrap srcport lowport
IP.v4.UDP.sendto
IP.v4.UDP.recvfrom range tcpwrap srcport lowport
IP.v4.UDP.recv range tcpwrap srcport lowport
IP.v4.raw.sendto
IP.v4.raw.recvfrom range tcpwrap
IP.v4.raw.recv range tcpwrap
IP.v6.TCP.connect
IP.v6.TCP.listen range tcpwrap srcport lowport
IP.v6.UDP.connect
IP.v6.UDP.listen range tcpwrap srcport lowport
IP.v6.UDP.sendto
IP.v6.UDP.recvfrom range tcpwrap srcport lowport
IP.v6.UDP.recv range tcpwrap srcport lowport
IP.v6.raw.sendto
IP.v6.raw.recvfrom range tcpwrap
IP.v6.raw.recv srcport lowport
UNIX.stream.connect
UNIX.stream.listen
UNIX.dgram.sendto
UNIX.dgram.recvfrom
UNIX.dgram.recv
OPENSSL.connect
OPENSSL.TCP4.listen range tcpwrap srcport lowport
OPENSSL.TCP6.listen range tcpwrap srcport lowport
===============================================================================
Missing features and Caveats:
. no support for SIGIO mechanism
. no support for socket ancillary messages
. Probably many ioctls not implemented due to missing documentation
. only limited implementation of raw sockets and interfaces,
. no support for high level sockets beyond UNIX, INET, and INET6 domains
Reference in a new issue View git blame Copy permalink