/doc/socat.1
Unknown | 3701 lines | 3603 code | 98 blank | 0 comment | 0 complexity | a6a25a53ff0478c3b71c8e48f00ec892 MD5 | raw file
Possible License(s): GPL-2.0
Large files files are truncated, but you can click here to view the full file
- .TH "socat" "1" "Mar 2014" "" ""
- .PP
- .SH "NAME"
- socat \- Multipurpose relay (SOcket CAT)
- .PP
- .SH "SYNOPSIS"
- \f(CWsocat [options] <address> <address>\fP
- .br
- \f(CWsocat \-V\fP
- .br
- \f(CWsocat \-h[h[h]] | \-?[?[?]]\fP
- .br
- \f(CWfilan\fP
- .br
- \f(CWprocan\fP
- .PP
- .SH "DESCRIPTION"
- .PP
- \fBSocat\fP is a command line based utility that establishes two bidirectional byte
- streams and transfers data between them\&. Because the streams can be constructed
- from a large set of different types of data sinks and sources
- (see address types), and because lots of
- address options may be applied to the streams, socat can
- be used for many different purposes\&.
- .PP
- \fBFilan\fP is a utility that prints information about its active file
- descriptors to stdout\&. It has been written for debugging \fBsocat\fP, but might be
- useful for other purposes too\&. Use the \-h option to find more infos\&.
- .PP
- \fBProcan\fP is a utility that prints information about process parameters to
- stdout\&. It has been written to better understand
- some UNIX process properties and for debugging \fBsocat\fP, but might be
- useful for other purposes too\&.
- .PP
- The life cycle of a \fBsocat\fP instance typically consists of four phases\&.
- .PP
- In the \fIinit\fP phase, the command line options are parsed and logging is
- initialized\&.
- .PP
- During the \fIopen\fP phase, \fBsocat\fP opens the first address and afterwards the
- second address\&. These steps are usually blocking; thus, especially for complex address types like socks,
- connection requests or authentication dialogs must be completed before the next
- step is started\&.
- .PP
- In the \fItransfer\fP phase, \fBsocat\fP watches both streams\(cq\& read and write file
- descriptors via
- \f(CWselect()\fP
- , and, when data is available on one side \fIand\fP
- can be written to the other side, socat reads it, performs newline
- character conversions if required, and writes the data to the write file
- descriptor of the other stream, then continues waiting for more data in both
- directions\&.
- .PP
- When one of the streams effectively reaches EOF, the \fIclosing\fP phase
- begins\&. \fBSocat\fP transfers the EOF condition to the other stream,
- i\&.e\&. tries to shutdown only its write stream, giving it a chance to
- terminate gracefully\&. For a defined time \fBsocat\fP continues to transfer data in
- the other direction, but then closes all remaining channels and terminates\&.
- .PP
- .SH "OPTIONS"
- .PP
- \fBSocat\fP provides some command line options that modify the behaviour of the
- program\&. They have nothing to do with so called
- address options that are used as parts of address specifications\&.
- .PP
- .IP "\fB\f(CW\-V\fP\fP"
- Print version and available feature information to stdout, and exit\&.
- .IP "\fB\f(CW\-h | \-?\fP\fP"
- Print a help text to stdout describing command line options and available address
- types, and exit\&.
- .IP "\fB\f(CW\-hh | \-??\fP\fP"
- Like \-h, plus a list of the short names of all available address options\&. Some options are
- platform dependend, so this output is helpful for checking the particular
- implementation\&.
- .IP "\fB\f(CW\-hhh | \-???\fP\fP"
- Like \-hh, plus a list of all available address option names\&.
- .IP "\fB\f(CW\-d\fP\fP"
- Without this option, only fatal and error messages are generated; applying
- this option also prints warning messages\&. See DIAGNOSTICS
- for more information\&.
- .IP "\fB\f(CW\-d \-d\fP\fP"
- Prints fatal, error, warning, and notice messages\&.
- .IP "\fB\f(CW\-d \-d \-d\fP\fP"
- Prints fatal, error, warning, notice, and info messages\&.
- .IP "\fB\f(CW\-d \-d \-d \-d\fP\fP"
- Prints fatal, error, warning, notice, info, and debug
- messages\&.
- .IP "\fB\f(CW\-D\fP\fP"
- Logs information about file descriptors before starting the transfer phase\&.
- .IP "\fB\f(CW\-ly[<facility>]\fP\fP"
- Writes messages to syslog instead of stderr; severity as defined with \-d
- option\&. With optional <facility>, the syslog type can
- be selected, default is \(dq\&daemon\(dq\&\&. Third party libraries might not obey this
- option\&.
- .IP "\fB\f(CW\-lf\fP\fP\f(CW <logfile>\fP"
- Writes messages to <logfile> [filename] instead of
- stderr\&. Some third party libraries, in particular libwrap, might not obey
- this option\&.
- .IP "\fB\f(CW\-ls\fP\fP"
- Writes messages to stderr (this is the default)\&. Some third party libraries
- might not obey this option, in particular libwrap appears to only log to
- syslog\&.
- .IP "\fB\f(CW\-lp\fP\fP\f(CW<progname>\fP"
- Overrides the program name printed in error messages and used for
- constructing environment variable names\&.
- .IP "\fB\f(CW\-lu\fP\fP"
- Extends the timestamp of error messages to microsecond resolution\&. Does not
- work when logging to syslog\&.
- .IP "\fB\f(CW\-lm[<facility>]\fP\fP"
- Mixed log mode\&. During startup messages are printed to stderr; when \fBsocat\fP
- starts the transfer phase loop or daemon mode (i\&.e\&. after opening all
- streams and before starting data transfer, or, with listening sockets with
- fork option, before the first accept call), it switches logging to syslog\&.
- With optional <facility>, the syslog type can be
- selected, default is \(dq\&daemon\(dq\&\&.
- .IP "\fB\f(CW\-lh\fP\fP"
- Adds hostname to log messages\&. Uses the value from environment variable
- HOSTNAME or the value retrieved with \f(CWuname()\fP if HOSTNAME is not set\&.
- .IP "\fB\f(CW\-v\fP\fP"
- Writes the transferred data not only to their target streams, but also to
- stderr\&. The output format is text with some conversions for readability, and
- prefixed with \(dq\&> \(dq\& or \(dq\&< \(dq\& indicating flow directions\&.
- .IP "\fB\f(CW\-x\fP\fP"
- Writes the transferred data not only to their target streams, but also to
- stderr\&. The output format is hexadecimal, prefixed with \(dq\&> \(dq\& or \(dq\&< \(dq\&
- indicating flow directions\&. Can be combined with
- \f(CW\-v\fP
- \&.
- .IP "\fB\f(CW\-b\fP\fP\f(CW<size>\fP"
- Sets the data transfer block <size> [size_t]\&.
- At most <size> bytes are transferred per step\&. Default is 8192 bytes\&.
- .IP "\fB\f(CW\-s\fP\fP"
- By default, \fBsocat\fP terminates when an error occurred to prevent the process
- from running when some option could not be applied\&. With this
- option, \fBsocat\fP is sloppy with errors and tries to continue\&. Even with this
- option, socat will exit on fatals, and will abort connection attempts when
- security checks failed\&.
- .IP "\fB\f(CW\-t\fP\fP\f(CW<timeout>\fP"
- When one channel has reached EOF, the write part of the other channel is shut
- down\&. Then, \fBsocat\fP waits <timeout> [timeval] seconds
- before terminating\&. Default is 0\&.5 seconds\&. This timeout only applies to
- addresses where write and read part can be closed independently\&. When during
- the timeout interval the read part gives EOF, socat terminates without
- awaiting the timeout\&.
- .IP "\fB\f(CW\-T\fP\fP\f(CW<timeout>\fP"
- Total inactivity timeout: when socat is already in the transfer loop and
- nothing has happened for <timeout> [timeval] seconds
- (no data arrived, no interrupt occurred\&.\&.\&.) then it terminates\&.
- Useful with protocols like UDP that cannot transfer EOF\&.
- .IP "\fB\f(CW\-u\fP\fP"
- Uses unidirectional mode\&. The first address is only used for reading, and the
- second address is only used for writing (example)\&.
- .IP "\fB\f(CW\-U\fP\fP"
- Uses unidirectional mode in reverse direction\&. The first address is only
- used for writing, and the second address is only used for reading\&.
- .IP "\fB\f(CW\-g\fP\fP"
- During address option parsing, don\(cq\&t check if the option is considered
- useful in the given address environment\&. Use it if you want to force, e\&.g\&.,
- appliance of a socket option to a serial device\&.
- .IP "\fB\f(CW\-L\fP\fP\f(CW<lockfile>\fP"
- If lockfile exists, exits with error\&. If lockfile does not exist, creates it
- and continues, unlinks lockfile on exit\&.
- .IP "\fB\f(CW\-W\fP\fP\f(CW<lockfile>\fP"
- If lockfile exists, waits until it disappears\&. When lockfile does not exist,
- creates it and continues, unlinks lockfile on exit\&.
- .IP "\fB\f(CW\-4\fP\fP"
- Use IP version 4 in case that the addresses do not implicitly or explicitly
- specify a version; this is the default\&.
- .IP "\fB\f(CW\-6\fP\fP"
- Use IP version 6 in case that the addresses do not implicitly or explicitly
- specify a version\&.
- .PP
- .SH "ADDRESS SPECIFICATIONS"
- .PP
- With the address command line arguments, the user gives \fBsocat\fP instructions and
- the necessary information for establishing the byte streams\&.
- .PP
- An address specification usually consists of an address type
- keyword, zero or more required address parameters separated by \(cq\&:\(cq\& from the keyword and
- from each
- other, and zero or more address options separated by \(cq\&,\(cq\&\&.
- .PP
- The keyword specifies the address type (e\&.g\&., TCP4, OPEN, EXEC)\&. For some
- keywords there exist synonyms (\(cq\&\-\(cq\& for STDIO, TCP for TCP4)\&. Keywords are case
- insensitive\&.
- For a few special address types, the keyword may be omitted:
- Address specifications starting with a number are assumed to be FD (raw file
- descriptor) addresses;
- if a \(cq\&/\(cq\& is found before the first \(cq\&:\(cq\& or \(cq\&,\(cq\&, GOPEN (generic file open) is
- assumed\&.
- .PP
- The required number and type of address parameters depend on the address
- type\&. E\&.g\&., TCP4 requires a server specification (name or address), and a port
- specification (number or service name)\&.
- .PP
- Zero or more address options may be given with each address\&. They influence the
- address in some ways\&.
- Options consist of an option keyword or an option keyword and a value,
- separated by \(cq\&=\(cq\&\&. Option keywords are case insensitive\&.
- For filtering the options that are useful with an address
- type, each option is member of one option group\&. For
- each address type there is a set of option groups allowed\&. Only options
- belonging to one of these address groups may be used (except with option \-g)\&.
- .PP
- Address specifications following the above schema are also called \fIsingle\fP
- address specifications\&.
- Two single addresses can be combined with \(dq\&!!\(dq\& to form a \fIdual\fP type
- address for one channel\&. Here, the first address is used by \fBsocat\fP for reading
- data, and the
- second address for writing data\&. There is no way to specify an option only once
- for being applied to both single addresses\&.
- .PP
- Usually, addresses are opened in read/write
- mode\&. When an address is part of a dual address specification, or when
- option \-u or \-U is used, an address might be
- used only for reading or for writing\&. Considering this is important with some
- address types\&.
- .PP
- With socat version 1\&.5\&.0 and higher, the lexical analysis tries to handle
- quotes and parenthesis meaningfully and allows escaping of special characters\&.
- If one of the characters ( { [ \(cq\& is found, the corresponding closing
- character \- ) } ] \(cq\& \- is looked for; they may also be nested\&. Within these
- constructs, socats special characters and strings : , !! are not handled
- specially\&. All those characters and strings can be escaped with \e or within \(dq\&\(dq\&
- .PP
- .SH "ADDRESS TYPES"
- .PP
- This section describes the available address types with their keywords,
- parameters, and semantics\&.
- .PP
- .IP "\fB\f(CWCREATE:<filename>\fP\fP"
- Opens <filename> with
- \f(CWcreat()\fP
- and uses the file
- descriptor for writing\&.
- This address type requires write\-only context, because a file opened with
- \f(CWcreat\fP
- cannot be read from\&.
- .br
- Flags like O_LARGEFILE cannot be applied\&. If you need them use
- OPEN with options
- create,create\&.
- .br
- <filename> must be a valid existing or not existing path\&.
- If <filename> is a named pipe,
- \f(CWcreat()\fP
- might block;
- if <filename> refers to a socket, this is an error\&.
- .br
- Option groups: FD,REG,NAMED
- .br
- Useful options:
- mode,
- user,
- group,
- unlink\-early,
- unlink\-late,
- append
- .br
- See also: OPEN, GOPEN
- .IP "\fB\f(CWEXEC:<command\-line>\fP\fP"
- Forks a sub process that establishes communication with its parent process
- and invokes the specified program with
- \f(CWexecvp()\fP
- \&.
- <command\-line> is a simple command
- with arguments separated by single spaces\&. If the program name
- contains a \(cq\&/\(cq\&, the part after the last \(cq\&/\(cq\& is taken as ARGV[0]\&. If the
- program name is a relative
- path, the
- \f(CWexecvp()\fP
- semantics for finding the program via
- \f(CW$PATH\fP
- apply\&. After successful program start, \fBsocat\fP writes data to stdin of the
- process and reads from its stdout using a UNIX domain socket generated by
- \f(CWsocketpair()\fP
- per default\&. (example)
- .br
- Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
- .br
- Useful options:
- path,
- fdin,
- fdout,
- chroot,
- su,
- su\-d,
- nofork,
- pty,
- stderr,
- ctty,
- setsid,
- pipes,
- login,
- sigint,
- sigquit
- .br
- See also: SYSTEM
- .IP "\fB\f(CWFD:<fdnum>\fP\fP"
- Uses the file descriptor <fdnum>\&. It must already exist as
- valid UN*X file descriptor\&.
- .br
- Option groups: FD (TERMIOS,REG,SOCKET)
- .br
- See also:
- STDIO,
- STDIN,
- STDOUT,
- STDERR
- .IP "\fB\f(CWGOPEN:<filename>\fP\fP"
- (Generic open) This address type tries to handle any file system entry
- except directories usefully\&. <filename> may be a
- relative or absolute path\&. If it already exists, its type is checked\&.
- In case of a UNIX domain socket, \fBsocat\fP connects; if connecting fails,
- \fBsocat\fP assumes a datagram socket and uses
- \f(CWsendto()\fP
- calls\&.
- If the entry is not a socket, \fBsocat\fP opens it applying the
- \f(CWO_APPEND\fP
- flag\&.
- If it does not exist, it is opened with flag
- \f(CWO_CREAT\fP
- as a regular file (example)\&.
- .br
- Option groups: FD,REG,SOCKET,NAMED,OPEN
- .br
- See also:
- OPEN,
- CREATE,
- UNIX\-CONNECT
- .IP
- .IP "\fB\f(CWIP\-SENDTO:<host>:<protocol>\fP\fP"
- Opens a raw IP socket\&. Depending on host specification or option pf, IP protocol version
- 4 or 6 is used\&. It uses <protocol> to send packets
- to <host> [IP address] and receives packets from
- host, ignores packets from other hosts\&.
- Protocol 255 uses the raw socket with the IP header being part of the
- data\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6
- .br
- Useful options:
- pf,
- ttl
- .br
- See also:
- IP4\-SENDTO,
- IP6\-SENDTO,
- IP\-RECVFROM,
- IP\-RECV,
- UDP\-SENDTO,
- UNIX\-SENDTO
- .IP "\fB\f(CWINTERFACE:<interface>\fP\fP"
- Communicates with a network connected on an interface using raw packets
- including link level data\&. <interface> is the name of
- the network interface\&. Currently only available on Linux\&.
- Option groups: FD,SOCKET
- .br
- Useful options:
- pf,
- type
- .br
- See also: ip\-recv
- .IP "\fB\f(CWIP4\-SENDTO:<host>:<protocol>\fP\fP"
- Like IP\-SENDTO, but always uses IPv4\&.
- .br
- Option groups: FD,SOCKET,IP4
- .br
- .IP "\fB\f(CWIP6\-SENDTO:<host>:<protocol>\fP\fP"
- Like IP\-SENDTO, but always uses IPv6\&.
- .br
- Option groups: FD,SOCKET,IP6
- .br
- .IP
- .IP "\fB\f(CWIP\-DATAGRAM:<address>:<protocol>\fP\fP"
- Sends outgoing data to the specified address which may in particular be a
- broadcast or multicast address\&. Packets arriving on the local socket are
- checked if their source addresses match
- RANGE or TCPWRAP
- options\&. This address type can for example be used for implementing
- symmetric or asymmetric broadcast or multicast communications\&.
- .br
- Option groups: FD, SOCKET,
- IP4, IP6, RANGE
- .br
- Useful options:
- bind,
- range,
- tcpwrap,
- broadcast,
- ip\-multicast\-loop,
- ip\-multicast\-ttl,
- ip\-multicast\-if,
- ip\-add\-membership,
- ttl,
- tos,
- pf
- .br
- See also:
- IP4\-DATAGRAM,
- IP6\-DATAGRAM,
- IP\-SENDTO,
- IP\-RECVFROM,
- IP\-RECV,
- UDP\-DATAGRAM
- .IP "\fB\f(CWIP4\-DATAGRAM:<host>:<protocol>\fP\fP"
- Like IP\-DATAGRAM, but always uses IPv4\&.
- (example)
- .br
- Option groups: FD,SOCKET,IP4,RANGE
- .br
- .IP "\fB\f(CWIP6\-DATAGRAM:<host>:<protocol>\fP\fP"
- Like IP\-DATAGRAM, but always uses IPv6\&. Please
- note that IPv6 does not know broadcasts\&.
- .br
- Option groups: FD,SOCKET,IP6,RANGE
- .br
- .IP
- .IP "\fB\f(CWIP\-RECVFROM:<protocol>\fP\fP"
- Opens a raw IP socket of <protocol>\&. Depending on option pf, IP protocol version
- 4 or 6 is used\&. It receives one packet from an unspecified peer and may send one or more answer packets to that peer\&.
- This mode is particularly useful with fork option where each arriving packet \- from arbitrary peers \- is handled by its own sub process\&.
- This allows a behaviour similar to typical UDP based servers like ntpd or
- named\&.
- .br
- Please note that the reply packets might be fetched as incoming traffic when
- sender and receiver IP address are identical because there is no port number
- to distinguish the sockets\&.
- .br
- This address works well with IP\-SENDTO address peers (see above)\&.
- Protocol 255 uses the raw socket with the IP header being part of the
- data\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
- .br
- Useful options:
- pf,
- fork,
- range,
- ttl,
- broadcast
- .br
- See also:
- IP4\-RECVFROM,
- IP6\-RECVFROM,
- IP\-SENDTO,
- IP\-RECV,
- UDP\-RECVFROM,
- UNIX\-RECVFROM
- .IP "\fB\f(CWIP4\-RECVFROM:<protocol>\fP\fP"
- Like IP\-RECVFROM, but always uses IPv4\&.
- .br
- Option groups: FD,SOCKET,IP4,CHILD,RANGE
- .br
- .IP "\fB\f(CWIP6\-RECVFROM:<protocol>\fP\fP"
- Like IP\-RECVFROM, but always uses IPv6\&.
- .br
- Option groups: FD,SOCKET,IP6,CHILD,RANGE
- .br
- .IP
- .IP "\fB\f(CWIP\-RECV:<protocol>\fP\fP"
- Opens a raw IP socket of <protocol>\&. Depending on option pf, IP protocol version
- 4 or 6 is used\&. It receives packets from multiple unspecified peers and merges the data\&.
- No replies are possible\&.
- It can be, e\&.g\&., addressed by socat IP\-SENDTO address peers\&.
- Protocol 255 uses the raw socket with the IP header being part of the
- data\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6,RANGE
- .br
- Useful options:
- pf,
- range
- .br
- See also:
- IP4\-RECV,
- IP6\-RECV,
- IP\-SENDTO,
- IP\-RECVFROM,
- UDP\-RECV,
- UNIX\-RECV
- .IP "\fB\f(CWIP4\-RECV:<protocol>\fP\fP"
- Like IP\-RECV, but always uses IPv4\&.
- .br
- Option groups: FD,SOCKET,IP4,RANGE
- .br
- .IP "\fB\f(CWIP6\-RECV:<protocol>\fP\fP"
- Like IP\-RECV, but always uses IPv6\&.
- .br
- Option groups: FD,SOCKET,IP6,RANGE
- .br
- .IP
- .IP "\fB\f(CWOPEN:<filename>\fP\fP"
- Opens <filename> using the
- \f(CWopen()\fP
- system call
- (example)\&.
- This operation fails on UNIX domain sockets\&.
- .br
- Note: This address type is rarly useful in bidirectional mode\&.
- .br
- Option groups: FD,REG,NAMED,OPEN
- .br
- Useful options:
- creat,
- excl,
- noatime,
- nofollow,
- append,
- rdonly,
- wronly,
- lock,
- readbytes,
- ignoreeof
- .br
- See also:
- CREATE,
- GOPEN,
- UNIX\-CONNECT
- .IP "\fB\f(CWOPENSSL:<host>:<port>\fP\fP"
- Tries to establish a SSL connection to <port> [TCP
- service] on
- <host> [IP address] using TCP/IP version 4 or 6
- depending on address specification, name resolution, or option
- pf\&.
- .br
- NOTE: The server certificate is only checked for validity against
- cafile or capath,
- but not for match with the server\(cq\&s name or its IP address!
- .br
- Option groups: FD,SOCKET,IP4,IP6,TCP,OPENSSL,RETRY
- .br
- Useful options:
- cipher,
- method,
- verify,
- cafile,
- capath,
- certificate,
- key,
- compress,
- bind,
- pf,
- connect\-timeout,
- sourceport,
- retry
- .br
- See also:
- OPENSSL\-LISTEN,
- TCP
- .IP "\fB\f(CWOPENSSL\-LISTEN:<port>\fP\fP"
- Listens on tcp <port> [TCP service]\&.
- The IP version is 4 or the one specified with
- pf\&. When a
- connection is accepted, this address behaves as SSL server\&.
- .br
- Note: You probably want to use the certificate option with this address\&.
- .br
- NOTE: The client certificate is only checked for validity against
- cafile or capath,
- but not for match with the client\(cq\&s name or its IP address!
- .br
- Option groups: FD,SOCKET,IP4,IP6,TCP,LISTEN,OPENSSL,CHILD,RANGE,RETRY
- .br
- Useful options:
- pf,
- cipher,
- method,
- verify,
- cafile,
- capath,
- certificate,
- key,
- compress,
- fork,
- bind,
- range,
- tcpwrap,
- su,
- reuseaddr,
- retry
- .br
- See also:
- OPENSSL,
- TCP\-LISTEN
- .IP "\fB\f(CWPIPE:<filename>\fP\fP"
- If <filename> already exists, it is opened\&.
- If it does not exist, a named pipe is created and opened\&. Beginning with
- socat version 1\&.4\&.3, the named pipe is removed when the address is closed
- (but see option unlink\-close
- .br
- Note: When a pipe is used for both reading and writing, it works
- as echo service\&.
- .br
- Note: When a pipe is used for both reading and writing, and socat tries
- to write more bytes than the pipe can buffer (Linux 2\&.4: 2048 bytes), socat
- might block\&. Consider using socat option, e\&.g\&.,
- \f(CW\-b 2048\fP
- .br
- Option groups: FD,NAMED,OPEN
- .br
- Useful options:
- rdonly,
- nonblock,
- group,
- user,
- mode,
- unlink\-early
- .br
- See also: unnamed pipe
- .IP "\fB\f(CWPIPE\fP\fP"
- Creates an unnamed pipe and uses it for reading and writing\&. It works as an
- echo, because everything written
- to it appeares immediately as read data\&.
- .br
- Note: When socat tries to write more bytes than the pipe can queue (Linux
- 2\&.4: 2048 bytes), socat might block\&. Consider, e\&.g\&., using
- option
- \f(CW\-b 2048\fP
- .br
- Option groups: FD
- .br
- See also: named pipe
- .IP "\fB\f(CWPROXY:<proxy>:<hostname>:<port>\fP\fP"
- Connects to an HTTP proxy server on port 8080 using TCP/IP version 4 or 6
- depending on address specification, name resolution, or option
- pf, and sends a CONNECT
- request for hostname:port\&. If the proxy grants access and succeeds to
- connect to the target, data transfer between socat and the target can
- start\&. Note that the traffic need not be HTTP but can be an arbitrary
- protocol\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6,TCP,HTTP,RETRY
- .br
- Useful options:
- proxyport,
- ignorecr,
- proxyauth,
- resolve,
- crnl,
- bind,
- connect\-timeout,
- mss,
- sourceport,
- retry
- .br
- See also: SOCKS, TCP
- .IP "\fB\f(CWPTY\fP\fP"
- Generates a pseudo terminal (pty) and uses its master side\&. Another process
- may open the pty\(cq\&s slave side using it like a serial line or terminal\&.
- (example)\&. If
- both the ptmx and the openpty mechanisms are available, ptmx is used
- (POSIX)\&.
- .br
- Option groups: FD,NAMED,PTY,TERMIOS
- .br
- Useful options:
- link,
- openpty,
- wait\-slave,
- mode,
- user,
- group
- .br
- See also:
- UNIX\-LISTEN,
- PIPE,
- EXEC, SYSTEM
- .IP "\fB\f(CWREADLINE\fP\fP"
- Uses GNU readline and history on stdio to allow editing and reusing input
- lines (example)\&. This requires the GNU readline and
- history libraries\&. Note that stdio should be a (pseudo) terminal device,
- otherwise readline does not seem to work\&.
- .br
- Option groups: FD,READLINE,TERMIOS
- .br
- Useful options:
- history,
- noecho
- .br
- See also:
- STDIO
- .IP "\fB\f(CWSCTP\-CONNECT:<host>:<port>\fP\fP"
- Establishes an SCTP stream connection to the specified <host> [IP
- address] and <port> [TCP service]
- using TCP/IP version 4 or 6 depending on address specification, name
- resolution, or option pf\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6,SCTP,CHILD,RETRY
- .br
- Useful options:
- bind,
- pf,
- connect\-timeout,
- tos,
- mtudiscover,
- sctp\-maxseg,
- sctp\-nodelay,
- nonblock,
- sourceport,
- retry,
- readbytes
- .br
- See also:
- SCTP4\-CONNECT,
- SCTP6\-CONNECT,
- SCTP\-LISTEN,
- TCP\-CONNECT
- .IP "\fB\f(CWSCTP4\-CONNECT:<host>:<port>\fP\fP"
- Like SCTP\-CONNECT, but only supports IPv4 protocol\&.
- .br
- Option groups: FD,SOCKET,IP4,SCTP,CHILD,RETRY
- .br
- .IP "\fB\f(CWSCTP6\-CONNECT:<host>:<port>\fP\fP"
- Like SCTP\-CONNECT, but only supports IPv6 protocol\&.
- .br
- Option groups: FD,SOCKET,IP6,SCTP,CHILD,RETRY
- .br
- .IP "\fB\f(CWSCTP\-LISTEN:<port>\fP\fP"
- Listens on <port> [TCP service] and accepts a
- TCP/IP connection\&. The IP version is 4 or the one specified with
- address option pf, socat option
- (\-4, \-6), or environment variable SOCAT_DEFAULT_LISTEN_IP\&.
- Note that opening
- this address usually blocks until a client connects\&.
- .br
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,SCTP,RETRY
- .br
- Useful options:
- crnl,
- fork,
- bind,
- range,
- tcpwrap,
- pf,
- max\-children,
- backlog,
- sctp\-maxseg,
- sctp\-nodelay,
- su,
- reuseaddr,
- retry,
- cool\-write
- .br
- See also:
- SCTP4\-LISTEN,
- SCTP6\-LISTEN,
- TCP\-LISTEN,
- SCTP\-CONNECT
- .IP "\fB\f(CWSCTP4\-LISTEN:<port>\fP\fP"
- Like SCTP\-LISTEN, but only supports IPv4
- protocol\&.
- .br
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,SCTP,RETRY
- .br
- .IP "\fB\f(CWSCTP6\-LISTEN:<port>\fP\fP"
- Like SCTP\-LISTEN, but only supports IPv6
- protocol\&.
- .br
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,SCTP,RETRY
- .br
- .IP "\fB\f(CWSOCKET\-CONNECT:<domain>:<protocol>:<remote\-address>\fP\fP"
- Creates a stream socket using the first and second given socket parameters
- and \f(CWSOCK_STREAM\fP (see man socket\e(2)) and connects to the remote\-address\&.
- The two socket parameters have to be specified by int
- numbers\&. Consult your OS documentation and include files to find the
- appropriate values\&. The remote\-address must be the data
- representation of a sockaddr structure without sa_family and (BSD) sa_len
- components\&.
- .br
- Please note that you can \- beyond the options of the specified groups \- also
- use options of higher level protocols when you apply socat option
- \-g\&.
- .br
- Option groups: FD,SOCKET,CHILD,RETRY
- .br
- Useful options:
- bind,
- setsockopt\-int,
- setsockopt\-bin,
- setsockopt\-string
- .br
- See also:
- TCP,
- UDP\-CONNECT,
- UNIX\-CONNECT,
- SOCKET\-LISTEN,
- SOCKET\-SENDTO
- .IP "\fB\f(CWSOCKET\-DATAGRAM:<domain>:<type>:<protocol>:<remote\-address>\fP\fP"
- Creates a datagram socket using the first three given socket parameters (see
- man socket\e(2)) and sends outgoing data to the remote\-address\&. The three
- socket parameters have to be specified by int
- numbers\&. Consult your OS documentation and include files to find the
- appropriate values\&. The remote\-address must be the data
- representation of a sockaddr structure without sa_family and (BSD) sa_len
- components\&.
- .br
- Please note that you can \- beyond the options of the specified groups \- also
- use options of higher level protocols when you apply socat option
- \-g\&.
- .br
- Option groups: FD,SOCKET,RANGE
- .br
- Useful options:
- bind,
- range,
- setsockopt\-int,
- setsockopt\-bin,
- setsockopt\-string
- .br
- See also:
- UDP\-DATAGRAM,
- IP\-DATAGRAM,
- SOCKET\-SENDTO,
- SOCKET\-RECV,
- SOCKET\-RECVFROM
- .IP "\fB\f(CWSOCKET\-LISTEN:<domain>:<protocol>:<local\-address>\fP\fP"
- Creates a stream socket using the first and second given socket parameters
- and \f(CWSOCK_STREAM\fP (see man socket\e(2)) and waits for incoming connections
- on local\-address\&. The two socket parameters have to be specified by
- int numbers\&. Consult your OS documentation and include files
- to find the appropriate values\&. The local\-address must be the
- data representation of a sockaddr structure without
- sa_family and (BSD) sa_len components\&.
- .br
- Please note that you can \- beyond the options of the specified groups \- also
- use options of higher level protocols when you apply socat option
- \-g\&.
- .br
- Option groups: FD,SOCKET,LISTEN,RANGE,CHILD,RETRY
- .br
- Useful options:
- setsockopt\-int,
- setsockopt\-bin,
- setsockopt\-string
- .br
- See also:
- TCP,
- UDP\-CONNECT,
- UNIX\-CONNECT,
- SOCKET\-LISTEN,
- SOCKET\-SENDTO,
- SOCKET\-SENDTO
- .IP "\fB\f(CWSOCKET\-RECV:<domain>:<type>:<protocol>:<local\-address>\fP\fP"
- Creates a socket using the three given socket parameters (see man socket\e(2))
- and binds it to <local\-address>\&. Receives arriving data\&. The three
- parameters have to be specified by int numbers\&. Consult your
- OS documentation and include files to find the appropriate values\&. The
- local\-address must be the data representation of a sockaddr
- structure without sa_family and (BSD) sa_len components\&.
- .br
- Option groups: FD,SOCKET,RANGE
- .br
- Useful options:
- range,
- setsockopt\-int,
- setsockopt\-bin,
- setsockopt\-string
- .br
- See also:
- UDP\-RECV,
- IP\-RECV,
- UNIX\-RECV,
- SOCKET\-DATAGRAM,
- SOCKET\-SENDTO,
- SOCKET\-RECVFROM
- .IP "\fB\f(CWSOCKET\-RECVFROM:<domain>:<type>:<protocol>:<local\-address>\fP\fP"
- Creates a socket using the three given socket parameters (see man socket\e(2))
- and binds it to <local\-address>\&. Receives arriving data and sends replies
- back to the sender\&. The first three parameters have to be specified as
- int numbers\&. Consult your OS documentation and include files
- to find the appropriate values\&. The local\-address must be the
- data representation of a sockaddr structure without
- sa_family and (BSD) sa_len components\&.
- .br
- Option groups: FD,SOCKET,CHILD,RANGE
- .br
- Useful options:
- fork,
- range,
- setsockopt\-int,
- setsockopt\-bin,
- setsockopt\-string
- .br
- See also:
- UDP\-RECVFROM,
- IP\-RECVFROM,
- UNIX\-RECVFROM,
- SOCKET\-DATAGRAM,
- SOCKET\-SENDTO,
- SOCKET\-RECV
- .IP "\fB\f(CWSOCKET\-SENDTO:<domain>:<type>:<protocol>:<remote\-address>\fP\fP"
- Creates a socket using the three given socket parameters (see man
- socket\e(2))\&. Sends outgoing data to the given address and receives replies\&.
- The three parameters have to be specified as int
- numbers\&. Consult your OS documentation and include files to find the
- appropriate values\&. The remote\-address must be the data
- representation of a sockaddr structure without sa_family and (BSD) sa_len
- components\&.
- .br
- Option groups: FD,SOCKET
- .br
- Useful options:
- bind,
- setsockopt\-int,
- setsockopt\-bin,
- setsockopt\-string
- .br
- See also:
- UDP\-SENDTO,
- IP\-SENDTO,
- UNIX\-SENDTO,
- SOCKET\-DATAGRAM,
- SOCKET\-RECV
- SOCKET\-RECVFROM
- .IP "\fB\f(CWSOCKS4:<socks\-server>:<host>:<port>\fP\fP"
- Connects via <socks\-server> [IP address]
- to <host> [IPv4 address]
- on <port> [TCP service],
- using socks version 4 protocol over IP version 4 or 6 depending on address specification, name resolution, or option
- pf (example)\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
- .br
- Useful options:
- socksuser,
- socksport,
- sourceport,
- pf,
- retry
- .br
- See also:
- SOCKS4A,
- PROXY,
- TCP
- .IP "\fB\f(CWSOCKS4A:<socks\-server>:<host>:<port>\fP\fP"
- like SOCKS4, but uses socks protocol version 4a, thus
- leaving host name resolution to the socks server\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
- .br
- .IP "\fB\f(CWSTDERR\fP\fP"
- Uses file descriptor 2\&.
- .br
- Option groups: FD (TERMIOS,REG,SOCKET)
- .br
- See also: FD
- .IP "\fB\f(CWSTDIN\fP\fP"
- Uses file descriptor 0\&.
- .br
- Option groups: FD (TERMIOS,REG,SOCKET)
- .br
- Useful options:
- readbytes
- .br
- See also: FD
- .IP "\fB\f(CWSTDIO\fP\fP"
- Uses file descriptor 0 for reading, and 1 for writing\&.
- .br
- Option groups: FD (TERMIOS,REG,SOCKET)
- .br
- Useful options:
- readbytes
- .br
- See also: FD
- .IP "\fB\f(CWSTDOUT\fP\fP"
- Uses file descriptor 1\&.
- .br
- Option groups: FD (TERMIOS,REG,SOCKET)
- .br
- See also: FD
- .IP "\fB\f(CWSYSTEM:<shell\-command>\fP\fP"
- Forks a sub process that establishes communication with its parent process
- and invokes the specified program with
- \f(CWsystem()\fP
- \&. Please note that
- <shell\-command> [string] must
- not contain \(cq\&,\(cq\& or \(dq\&!!\(dq\&, and that shell meta characters may have to be
- protected\&.
- After successful program start, \fBsocat\fP writes data to stdin of the
- process and reads from its stdout\&.
- .br
- Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
- .br
- Useful options:
- path,
- fdin,
- fdout,
- chroot,
- su,
- su\-d,
- nofork,
- pty,
- stderr,
- ctty,
- setsid,
- pipes,
- sigint,
- sigquit
- .br
- See also: EXEC
- .IP "\fB\f(CWTCP:<host>:<port>\fP\fP"
- Connects to <port> [TCP service] on
- <host> [IP address] using TCP/IP version 4 or 6
- depending on address specification, name resolution, or option
- pf\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6,TCP,RETRY
- .br
- Useful options:
- crnl,
- bind,
- pf,
- connect\-timeout,
- tos,
- mtudiscover,
- mss,
- nodelay,
- nonblock,
- sourceport,
- retry,
- readbytes
- .br
- See also:
- TCP4,
- TCP6,
- TCP\-LISTEN,
- UDP,
- SCTP\-CONNECT,
- UNIX\-CONNECT
- .IP "\fB\f(CWTCP4:<host>:<port>\fP\fP"
- Like TCP, but only supports IPv4 protocol (example)\&.
- .br
- Option groups: FD,SOCKET,IP4,TCP,RETRY
- .br
- .IP "\fB\f(CWTCP6:<host>:<port>\fP\fP"
- Like TCP, but only supports IPv6 protocol\&.
- .br
- Option groups: FD,SOCKET,IP6,TCP,RETRY
- .br
- .IP "\fB\f(CWTCP\-LISTEN:<port>\fP\fP"
- Listens on <port> [TCP service] and accepts a
- TCP/IP connection\&. The IP version is 4 or the one specified with
- address option pf, socat option
- (\-4, \-6), or environment variable SOCAT_DEFAULT_LISTEN_IP\&.
- Note that opening
- this address usually blocks until a client connects\&.
- .br
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,TCP,RETRY
- .br
- Useful options:
- crnl,
- fork,
- bind,
- range,
- tcpwrap,
- pf,
- max\-children,
- backlog,
- mss,
- su,
- reuseaddr,
- retry,
- cool\-write
- .br
- See also:
- TCP4\-LISTEN,
- TCP6\-LISTEN,
- UDP\-LISTEN,
- SCTP\-LISTEN,
- UNIX\-LISTEN,
- OPENSSL\-LISTEN,
- TCP\-CONNECT
- .IP "\fB\f(CWTCP4\-LISTEN:<port>\fP\fP"
- Like TCP\-LISTEN, but only supports IPv4
- protocol (example)\&.
- .br
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,TCP,RETRY
- .br
- .IP "\fB\f(CWTCP6\-LISTEN:<port>\fP\fP"
- Like TCP\-LISTEN, but only supports IPv6
- protocol\&.
- .br
- Additional useful option:
- ipv6only
- .br
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,TCP,RETRY
- .br
- .IP "\fB\f(CWTUN[:<if\-addr>/<bits>]\fP\fP"
- Creates a Linux TUN/TAP device and optionally assignes it the address and
- netmask given by the parameters\&. The resulting network interface is almost
- ready for use by other processes; socat serves its \(dq\&wire side\(dq\&\&. This address
- requires read and write access to the tunnel cloning device, usually
- \f(CW/dev/net/tun\fP
- , as well as permission to set some \f(CWioctl()s\fP\&.
- \fBOption iff\-up is required to immediately activate the interface!\fP
- .br
- Option groups: FD,NAMED,OPEN,TUN
- .br
- Useful options:
- iff\-up,
- tun\-device,
- tun\-name,
- tun\-type,
- iff\-no\-pi
- .br
- See also:
- ip\-recv
- .IP "\fB\f(CWUDP:<host>:<port>\fP\fP"
- Connects to <port> [UDP service] on
- <host> [IP address] using UDP/IP version 4 or 6
- depending on address specification, name resolution, or option
- pf\&.
- .br
- Please note that,
- due to UDP protocol properties, no real connection is established; data has
- to be sent for `connecting\(cq\& to the server, and no end\-of\-file condition can
- be transported\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6
- .br
- Useful options:
- ttl,
- tos,
- bind,
- sourceport,
- pf
- .br
- See also:
- UDP4,
- UDP6,
- UDP\-LISTEN,
- TCP,
- IP
- .IP "\fB\f(CWUDP4:<host>:<port>\fP\fP"
- Like UDP, but only supports IPv4 protocol\&.
- .br
- Option groups: FD,SOCKET,IP4
- .br
- .IP "\fB\f(CWUDP6:<host>:<port>\fP\fP"
- Like UDP, but only supports IPv6 protocol\&.
- .br
- Option groups: FD,SOCKET,IP6
- .br
- .IP "\fB\f(CWUDP\-DATAGRAM:<address>:<port>\fP\fP"
- Sends outgoing data to the specified address which may in particular be a
- broadcast or multicast address\&. Packets arriving on the local socket are
- checked for the correct remote port and if their source addresses match
- RANGE or TCPWRAP
- options\&. This address type can for example be used for implementing
- symmetric or asymmetric broadcast or multicast communications\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6,RANGE
- .br
- Useful options:
- bind,
- range,
- tcpwrap,
- broadcast,
- ip\-multicast\-loop,
- ip\-multicast\-ttl,
- ip\-multicast\-if,
- ip\-add\-membership,
- ttl,
- tos,
- sourceport,
- pf
- .br
- See also:
- UDP4\-DATAGRAM,
- UDP6\-DATAGRAM,
- UDP\-SENDTO,
- UDP\-RECVFROM,
- UDP\-RECV,
- UDP\-CONNECT,
- UDP\-LISTEN,
- IP\-DATAGRAM
- .IP "\fB\f(CWUDP4\-DATAGRAM:<address>:<port>\fP\fP"
- Like UDP\-DATAGRAM, but only supports IPv4
- protocol (example1,
- example2)\&.
- .br
- Option groups: FD,SOCKET,IP4, RANGE
- .IP "\fB\f(CWUDP6\-DATAGRAM:<address>:<port>\fP\fP"
- Like UDP\-DATAGRAM, but only supports IPv6
- protocol\&.
- .br
- Option groups: FD,SOCKET,IP6,RANGE
- .IP "\fB\f(CWUDP\-LISTEN:<port>\fP\fP"
- Waits for a UDP/IP packet arriving on <port>
- [UDP service] and `connects\(cq\& back to sender\&.
- The accepted IP version is 4 or the one specified with option
- pf\&.
- Please note that,
- due to UDP protocol properties, no real connection is established; data has
- to arrive from the peer first, and no end\-of\-file condition can be
- transported\&. Note that opening
- this address usually blocks until a client connects\&.
- .br
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6
- .br
- Useful options:
- fork,
- bind,
- range,
- pf
- .br
- See also:
- UDP,
- UDP4\-LISTEN,
- UDP6\-LISTEN,
- TCP\-LISTEN
- .IP "\fB\f(CWUDP4\-LISTEN:<port>\fP\fP"
- Like UDP\-LISTEN, but only support IPv4
- protocol\&.
- .br
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4
- .br
- .IP "\fB\f(CWUDP6\-LISTEN:<port>\fP\fP"
- Like UDP\-LISTEN, but only support IPv6
- protocol\&.
- .br
- Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6
- .br
- .IP "\fB\f(CWUDP\-SENDTO:<host>:<port>\fP\fP"
- Communicates with the specified peer socket, defined by <port> [UDP
- service] on
- <host> [IP address], using UDP/IP version 4 or 6
- depending on address specification, name resolution, or option
- pf\&. It sends packets to and receives packets
- from that peer socket only\&.
- This address effectively implements a datagram client\&.
- It works well with socat UDP\-RECVFROM and UDP\-RECV address peers\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6
- .br
- Useful options:
- ttl,
- tos,
- bind,
- sourceport,
- pf
- .br
- See also:
- UDP4\-SENDTO,
- UDP6\-SENDTO,
- UDP\-RECVFROM,
- UDP\-RECV,
- UDP\-CONNECT,
- UDP\-LISTEN,
- IP\-SENDTO
- .IP "\fB\f(CWUDP4\-SENDTO:<host>:<port>\fP\fP"
- Like UDP\-SENDTO, but only supports IPv4
- protocol\&.
- .br
- Option groups: FD,SOCKET,IP4
- .IP "\fB\f(CWUDP6\-SENDTO:<host>:<port>\fP\fP"
- Like UDP\-SENDTO, but only supports IPv6
- protocol\&.
- .br
- Option groups: FD,SOCKET,IP6
- .IP
- .IP "\fB\f(CWUDP\-RECVFROM:<port>\fP\fP"
- Creates a UDP socket on <port> [UDP service] using
- UDP/IP version 4 or 6
- depending on option pf\&.
- It receives one packet from an unspecified peer and may send one or more
- answer packets to that peer\&. This mode is particularly useful with fork
- option
- where each arriving packet \- from arbitrary peers \- is handled by its own sub
- process\&. This allows a behaviour similar to typical UDP based servers like ntpd
- or named\&. This address works well with socat UDP\-SENDTO address peers\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
- .br
- Useful options:
- fork,
- ttl,
- tos,
- bind,
- sourceport,
- pf
- .br
- See also:
- UDP4\-RECVFROM,
- UDP6\-RECVFROM,
- UDP\-SENDTO,
- UDP\-RECV,
- UDP\-CONNECT,
- UDP\-LISTEN,
- IP\-RECVFROM,
- UNIX\-RECVFROM
- .IP "\fB\f(CWUDP4\-RECVFROM:<port>\fP\fP"
- Like UDP\-RECVFROM, but only supports IPv4 protocol\&.
- .br
- Option groups: FD,SOCKET,IP4,CHILD,RANGE
- .IP "\fB\f(CWUDP6\-RECVFROM:<port>\fP\fP"
- Like UDP\-RECVFROM, but only supports IPv6 protocol\&.
- .br
- Option groups: FD,SOCKET,IP6,CHILD,RANGE
- .IP
- .IP "\fB\f(CWUDP\-RECV:<port>\fP\fP"
- Creates a UDP socket on <port> [UDP service] using UDP/IP version 4 or 6
- depending on option pf\&.
- It receives packets from multiple unspecified peers and merges the data\&.
- No replies are possible\&. It works well with, e\&.g\&., socat UDP\-SENDTO address peers; it behaves similar to a syslog server\&.
- .br
- Option groups: FD,SOCKET,IP4,IP6,RANGE
- .br
- Useful options:
- fork,
- pf,
- bind,
- sourceport,
- ttl,
- tos
- .br
- See also:
- UDP4\-RECV,
- UDP6\-RECV,
- UDP\-SENDTO,
- UDP\-RECVFROM,
- UDP\-CONNECT,
- UDP\-LISTEN,
- IP\-RECV,
- UNIX\-RECV
- .IP "\fB\f(CWUDP4\-RECV:<port>\fP\fP"
- Like UDP\-RECV, but only supports IPv4 protocol\&.
- .br
- Option groups: FD,SOCKET,IP4,RANGE
- .IP "\fB\f(CWUDP6\-RECV:<port>\fP\fP"
- Like UDP\-RECV, but only supports IPv6 protocol\&.
- .br
- Option groups: FD,SOCKET,IP6,RANGE
- .IP
- .IP "\fB\f(CWUNIX\-CONNECT:<filename>\fP\fP"
- Connects to <filename> assuming it is a UNIX domain
- socket\&.
- If <filename> does not exist, this is an error;
- if <filename> is not a UNIX domain socket, this is an error;
- if <filename> is a UNIX domain socket, but no process is listening, this is
- an error\&.
- .br
- Option groups: FD,SOCKET,NAMED,RETRY,UNIX
- .br
- )
- Useful options:
- bind
- .br
- See also:
- UNIX\-LISTEN,
- UNIX\-SENDTO,
- TCP
- .IP
- .IP "\fB\f(CWUNIX\-LISTEN:<filename>\fP\fP"
- Listens on <filename> using a UNIX domain stream
- socket and accepts a connection\&.
- If <filename> exists and is not a socket, this is an error\&.
- If <filename> exists and is a UNIX domain socket, binding to the address
- fails (use option unlink\-early!)\&.
- Note that opening this address usually blocks until a client connects\&.
- Beginning with socat version 1\&.4\&.3, the file system entry is removed when
- this address is closed (but see option unlink\-close) (example)\&.
- .br
- Option groups: FD,SOCKET,NAMED,LISTEN,CHILD,RETRY,UNIX
- .br
- Useful options:
- fork,
- umask,
- mode,
- user,
- group,
- unlink\-early
- .br
- See also:
- UNIX\-CONNECT,
- UNIX\-RECVFROM,
- UNIX\-RECV,
- TCP\-LISTEN
- .IP
- .IP "\fB\f(CWUNIX\-SENDTO:<filename>\fP\fP"
- Communicates with the specified peer socket, defined by [<filename>] assuming it is a UNIX domain datagram socket\&.
- It sends packets to and receives packets from that peer socket only\&.
- Please note that it might be neccessary to bind the
- local socket to an address (e\&.g\&. \f(CW/tmp/sock1\fP, which must not exist
- before)\&.
- This address type works well with socat UNIX\-RECVFROM and UNIX\-RECV address
- peers\&.
- .br
- Option groups: FD,SOCKET,NAMED,UNIX
- .br
- Useful options:
- bind
- .br
- See also:
- UNIX\-RECVFROM,
- UNIX\-RECV,
- UNIX\-CONNECT,
- UDP\-SENDTO,
- IP\-SENDTO
- .IP
- .IP "\fB\f(CWUNIX\-RECVFROM:<filename>\fP\fP"
- Creates a UNIX domain datagram socket [<filename>]\&.
- Receives one packet and may send one or more answer packets to that peer\&.
- This mode is particularly useful with fork option where each arriving packet \- from arbitrary peers \- is handled by its own sub process\&.
- This address works well with socat UNIX\-SENDTO address peers\&.
- .br
- Option groups: FD,SOCKET,NAMED,CHILD,UNIX
- .br
- Useful options:
- fork
- .br
- See also:
- UNIX\-SENDTO,
- UNIX\-RECV,
- UNIX\-LISTEN,
- UDP\-RECVFROM,
- IP\-RECVFROM
- .IP
- .IP "\fB\f(CWUNIX\-RECV:<filename>\fP\fP"
- Creates a UNIX domain datagram socket [<filename>]\&.
- Receives packets from multiple unspecified peers and merges the data\&.
- No replies are possible\&. It can be, e\&.g\&., addressed by socat UNIX\-SENDTO address peers\&.
- It behaves similar to a syslog server\&.
- Option groups: FD,SOCKET,NAMED,UNIX
- .br
- See also:
- UNIX\-SENDTO,
- UNIX\-RECVFROM,
- UNIX\-LISTEN,
- UDP\-RECV,
- IP\-RECV
- .IP
- .IP "\fB\f(CWUNIX\-CLIENT:<filename>\fP\fP"
- Communicates with the specified peer socket, defined by
- [<filename>] assuming it is a UNIX domain socket\&.
- It first tries to connect and, if that fails, assumes it is a datagram
- socket, thus supporting both types\&.
- .br
- Option groups: FD,SOCKET,NAMED,UNIX
- .br
- Useful options:
- bind
- .br
- See also:
- UNIX\-CONNECT,
- UNIX\-SENDTO,
- GOPEN
- .IP
- .IP "\fB\f(CWABSTRACT\-CONNECT:<string>\fP\fP"
- .IP "\fB\f(CWABSTRACT\-LISTEN:<string>\fP\fP"
- .IP "\fB\f(CWABSTRACT\-SENDTO:<string>\fP\fP"
- .IP "\fB\f(CWABSTRACT\-RECVFROM:<string>\fP\fP"
- .IP "\fB\f(CWABSTRACT\-RECV:<string>\fP\fP"
- .IP "\fB\f(CWABSTRACT\-CLIENT:<string>\fP\fP"
- The ABSTRACT addresses are almost identical to the related UNIX addresses
- except that they do not address file system based sockets but an alternate
- UNIX domain address space\&. To archieve this the socket address strings are
- prefixed with \(dq\&\e0\(dq\& internally\&. This feature is available (only?) on Linux\&.
- Option groups are the same as with the related UNIX addresses, except that
- the ABSTRACT addresses are not member of the NAMED group\&.
- .PP
- .SH "ADDRESS OPTIONS"
- .PP
- Address options can be applied to address specifications to influence the
- process of opening the addresses and the
- properties of the resulting data channels\&.
- .PP
- For technical reasons not every option can be
- applied to every address type; e\&.g\&., applying a socket option to a regular file
- will fail\&. To catch most useless combinations as early as in the open phase,
- the concept of \fIoption groups\fP was introduced\&. Each option belongs to one
- or more option groups\&. Options can be used only with address types that support
- at least one of their option groups (but see option \-g)\&.
- .PP
- Address options have data types that their values must conform to\&.
- Every address option consists of just a keyword or a keyword followed by
- \(dq\&=value\(dq\&, where value must conform to the options type\&.
- Some address options manipulate parameters of system calls;
- e\&.g\&., option sync sets the
- \f(CWO_SYNC\fP
- flag with the
- \f(CWopen()\fP
- call\&.
- Other options cause a system or library call; e\&.g\&., with option `ttl=value\(cq\&
- the
- \f(CWsetsockopt(fd, SOL_IP, IP_TTL, value, sizeof(int))\fP
- call is applied\&.
- Other
- options set internal \fBsocat\fP variables that are used during data transfer;
- e\&.g\&., `crnl\(cq\& causes explicit character conversions\&.
- A few options have more complex implementations; e\&.g\&., su\-d
- (substuser\-delayed) inquires some user and group infos, stores them, and
- applies them later after a possible
- \f(CWchroot()\fP
- call\&.
- .PP
- If multiple options are given to an address, their sequence in the address specification has (almost) no
- effect on the sequence of their execution/application\&. Instead, \fBsocat\fP has
- built in an \fIoption phase\fP model that tries to bring the options in a useful
- order\&. Some options exist in different forms (e\&.g\&.,
- unlink, unlink\-early, unlink\-late) to control the time of their execution\&.
- .PP
- If the same option is specified more than once within one address
- specification, with equal or different values, the effect depends on the kind of option\&. Options
- resulting in function calls like
- \f(CWsetsockopt()\fP
- cause multiple
- invocations\&. With options that set parameters for a required call like
- \f(CWopen()\fP
- or set internal flags, the value of the last option occurrence is effective\&.
- .PP
- The existence or semantics of many options are system dependent\&. \fBSocat\fP
- usually does NOT try to emulate missing libc or kernel features, it just
- provides an
- interface to the underlying system\&. So, if an operating system lacks a feature,
- the related option is simply not available on this platform\&.
- .PP
- The following paragraphs introduce just the more common address options\&. For
- a more comprehensive reference and to find information about canonical option
- names, alias names, option phases, and platforms see file \fBxio\&.help\fP\&.
- .br
- .br
- .PP
- .br
- .PP
- \fI\fBFD option group\fP\fP
- .PP
- This option group contains options that are applied to a UN*X
- style file descriptor, no matter how it was generated\&.
- Because all current \fBsocat\fP address types are file descriptor based, these
- options may be applied to any address\&.
- .br
- Note: Some of these options are also member of another option group, that
- provides an other, non\-fd based mechanism\&.
- For these options, it depends on the actual address type and its option groups
- which mechanism is used\&. The second, non\-fd based mechanism is prioritized\&.
- .IP "\fB\f(CWcloexec=<bool>\fP\fP"
- Sets the
- \f(CWFD_CLOEXEC\fP
- flag with the
- \f(CWfcntl()\fP
- system call to value
- <bool>\&. If set,
- the file descriptor is closed on
- \f(CWexec()\fP
- family function calls\&. \fBSocat\fP
- internally handles
- this flag for the fds it controls, so in most cases there will be no need to
- apply this option\&.
- .IP "\fB\f(CWsetlk\fP\fP"
- Tries to set a discretionary write lock to the whole file using the
- \f(CWfcntl(fd,
- F_SETLK, \&.\&.\&.)\fP
- system call\&. If the file is already locked, this call results
- in an error\&.
- On Linux, when the file permissions for group are \(dq\&S\(dq\& (g\-x,g+s), and the
- file system is locally mounted with the \(dq\&mand\(dq\& option, the lock is
- mandatory, i\&.e\&. prevents other processes from opening the file\&.
- .IP "\fB\f(CWsetlkw\fP\fP"
- Tries to set a discretionary waiting write lock to the whole file using the
- \f(CWfcntl(fd, F_SETLKW, \&.\&.\&.)\fP
- system call\&. If the file is already locked,
- this call blocks\&.
- See option setlk for information about making this
- lock mandatory\&.
- .IP "\fB\f(CWsetlk\-rd\fP\fP"
- Tries to set a discretionary read lock to the whole file using the
- \f(CWfcntl(fd,
- F_SETLK, \&.\&.\&.)\fP
- system call\&. If the file is already write locked, this call
- results in an error\&.
- See option setlk for information about making this
- lock mandatory\&.
- .IP "\fB\f(CWsetlkw\-rd\fP\fP"
- Tries to set a discretionary waiting read lock to the whole file using the
- \f(CWfcntl(fd, F_SETLKW, \&.\&.\&.)\fP
- system call\&. If the file is already write
- locked, this call blocks\&.
- See option setlk for information about making this
- lock mandatory\&.
- .IP "\fB\f(CWflock\-ex\fP\fP"
- Tries to set a blocking exclusive advisory lock to the file using the
- \f(CWflock(fd, LOCK_EX)\fP
- system call\&. \fBSocat\fP hangs in this call if the file
- is locked by another process\&.
- .IP "\fB\f(CWflock\-ex\-nb\fP\fP"
- Tries to set a nonblocking exclusive advisory lock to the file using the
- \f(CWflock(fd, LOCK_EX|LOCK_NB)\fP
- system call\&. If the file is already locked,
- this option results in an error\&.
- .IP "\fB\f(CWflock\-sh\fP\fP"
- Tries to set a blocking shared advisory lock to the file using the
- \f(CWflock(fd, LOCK_SH)\fP
- system call\&. \fBSocat\fP hangs in this call if the file
- is locked by another process\&.
- .IP "\fB\f(CWflock\-sh\-nb\fP\fP"
- Tries to set a nonblocking shared advisory lock to the file using the
- \f(CWflock(fd, LOCK_SH|LOCK_NB)\fP
- system call\&. If the file is already locked,
- this option results in an error\&.
- .IP "\fB\f(CWlock\fP\fP"
- Sets a blocking lock on the file\&. Uses the setlk or flock mechanism
- depending on availability on the particular platform\&. If both are available,
- the POSIX variant (setlkw) is used\&.
- .IP "\fB\f(CWuser=<user>\fP\fP"
- Sets the <user> (owner) of the stream\&.
- If the address is member of the NAMED option group,
- \fBsocat\fP uses the
- \f(CWchown()\fP
- system call after opening the
- file or binding to the UNIX domain socket (race condition!)\&.
- Without filesystem entry, \fBsocat\fP sets the user of the stream
- using the
- \f(CWfchown()\fP
- system call\&.
- These calls might require root privilege\&.
- .IP "\fB\f(CWuser\-late=<user>\fP\fP"
- Sets the owner of the fd to <user> with the
- \f(CWfchown()\fP
- system call after opening
- or connecting the channel\&.
- This is useful only on file system entries\&.
- .IP "\fB\f(CWgroup=<group>\fP\fP"
- Sets the <group> of the stream\&.
- If the address is member of the NAMED option group,
- \fBsocat\fP uses the
- \f(CWchown()\fP
- system call after opening the
- file or binding to the UNIX domain socket (race condition!)\&.
- Without filesystem entry, \fBsocat\fP sets the group of the stream
- with the
- \f(CWfchown()\fP
- system call\&.
- These calls might require group membership or root privilege\&.
- .IP "\fB\f(CWgroup\-late=<group>\fP\fP"
- Sets the group of the fd to <group> with the
- \f(CWfchown()\fP
- system call after opening
- or connecting the channel\&.
- This is useful only on file system entries\&.
- .IP "\fB\f(CWmode=<mode>\fP\fP"
- Sets the <mode> [mode_t] (permissions) of the stream\&.
- If the address is member of the NAMED option group and
- uses the
- \f(CWopen()\fP
- or
- \f(CWcreat()\fP
- call, the mode is applied with these\&.
- If the address is member of the NAMED option group with…
Large files files are truncated, but you can click here to view the full file