4960 lines
115 KiB
Plaintext
4960 lines
115 KiB
Plaintext
# $Id: xio.help,v 1.115 2007/03/06 20:57:34 gerhard Exp $
|
||
# Copyright Gerhard Rieger 2001-2007
|
||
|
||
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 fchown()
|
||
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 chown() 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-intervall
|
||
|
||
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 intervall is 1s. Use the pty-intervall 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(). Intervall 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.
|
||
|
||
|
||
===============================================================================
|
||
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: intervall=<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
|