/doc/socat.1
Unknown | 3701 lines | 3603 code | 98 blank | 0 comment | 0 complexity | a6a25a53ff0478c3b71c8e48f00ec892 MD5 | raw file
Large files files are truncated, but you can click here to view the full file
1.TH "socat" "1" "Mar 2014" "" "" 2 3.PP 4.SH "NAME" 5socat \- Multipurpose relay (SOcket CAT) 6.PP 7.SH "SYNOPSIS" 8\f(CWsocat [options] <address> <address>\fP 9.br 10\f(CWsocat \-V\fP 11.br 12\f(CWsocat \-h[h[h]] | \-?[?[?]]\fP 13.br 14\f(CWfilan\fP 15.br 16\f(CWprocan\fP 17.PP 18.SH "DESCRIPTION" 19 20.PP 21\fBSocat\fP is a command line based utility that establishes two bidirectional byte 22streams and transfers data between them\&. Because the streams can be constructed 23from a large set of different types of data sinks and sources 24(see address types), and because lots of 25address options may be applied to the streams, socat can 26be used for many different purposes\&. 27.PP 28\fBFilan\fP is a utility that prints information about its active file 29descriptors to stdout\&. It has been written for debugging \fBsocat\fP, but might be 30useful for other purposes too\&. Use the \-h option to find more infos\&. 31.PP 32\fBProcan\fP is a utility that prints information about process parameters to 33stdout\&. It has been written to better understand 34some UNIX process properties and for debugging \fBsocat\fP, but might be 35useful for other purposes too\&. 36.PP 37The life cycle of a \fBsocat\fP instance typically consists of four phases\&. 38.PP 39In the \fIinit\fP phase, the command line options are parsed and logging is 40initialized\&. 41.PP 42During the \fIopen\fP phase, \fBsocat\fP opens the first address and afterwards the 43second address\&. These steps are usually blocking; thus, especially for complex address types like socks, 44connection requests or authentication dialogs must be completed before the next 45step is started\&. 46.PP 47In the \fItransfer\fP phase, \fBsocat\fP watches both streams\(cq\& read and write file 48descriptors via 49\f(CWselect()\fP 50, and, when data is available on one side \fIand\fP 51can be written to the other side, socat reads it, performs newline 52character conversions if required, and writes the data to the write file 53descriptor of the other stream, then continues waiting for more data in both 54directions\&. 55.PP 56When one of the streams effectively reaches EOF, the \fIclosing\fP phase 57begins\&. \fBSocat\fP transfers the EOF condition to the other stream, 58i\&.e\&. tries to shutdown only its write stream, giving it a chance to 59terminate gracefully\&. For a defined time \fBsocat\fP continues to transfer data in 60the other direction, but then closes all remaining channels and terminates\&. 61.PP 62.SH "OPTIONS" 63 64.PP 65\fBSocat\fP provides some command line options that modify the behaviour of the 66program\&. They have nothing to do with so called 67address options that are used as parts of address specifications\&. 68.PP 69.IP "\fB\f(CW\-V\fP\fP" 70Print version and available feature information to stdout, and exit\&. 71.IP "\fB\f(CW\-h | \-?\fP\fP" 72Print a help text to stdout describing command line options and available address 73types, and exit\&. 74.IP "\fB\f(CW\-hh | \-??\fP\fP" 75Like \-h, plus a list of the short names of all available address options\&. Some options are 76platform dependend, so this output is helpful for checking the particular 77implementation\&. 78.IP "\fB\f(CW\-hhh | \-???\fP\fP" 79Like \-hh, plus a list of all available address option names\&. 80.IP "\fB\f(CW\-d\fP\fP" 81Without this option, only fatal and error messages are generated; applying 82this option also prints warning messages\&. See DIAGNOSTICS 83for more information\&. 84.IP "\fB\f(CW\-d \-d\fP\fP" 85Prints fatal, error, warning, and notice messages\&. 86.IP "\fB\f(CW\-d \-d \-d\fP\fP" 87Prints fatal, error, warning, notice, and info messages\&. 88.IP "\fB\f(CW\-d \-d \-d \-d\fP\fP" 89Prints fatal, error, warning, notice, info, and debug 90messages\&. 91.IP "\fB\f(CW\-D\fP\fP" 92Logs information about file descriptors before starting the transfer phase\&. 93.IP "\fB\f(CW\-ly[<facility>]\fP\fP" 94Writes messages to syslog instead of stderr; severity as defined with \-d 95option\&. With optional <facility>, the syslog type can 96be selected, default is \(dq\&daemon\(dq\&\&. Third party libraries might not obey this 97option\&. 98.IP "\fB\f(CW\-lf\fP\fP\f(CW <logfile>\fP" 99Writes messages to <logfile> [filename] instead of 100stderr\&. Some third party libraries, in particular libwrap, might not obey 101this option\&. 102.IP "\fB\f(CW\-ls\fP\fP" 103Writes messages to stderr (this is the default)\&. Some third party libraries 104might not obey this option, in particular libwrap appears to only log to 105syslog\&. 106.IP "\fB\f(CW\-lp\fP\fP\f(CW<progname>\fP" 107Overrides the program name printed in error messages and used for 108constructing environment variable names\&. 109.IP "\fB\f(CW\-lu\fP\fP" 110Extends the timestamp of error messages to microsecond resolution\&. Does not 111work when logging to syslog\&. 112.IP "\fB\f(CW\-lm[<facility>]\fP\fP" 113Mixed log mode\&. During startup messages are printed to stderr; when \fBsocat\fP 114starts the transfer phase loop or daemon mode (i\&.e\&. after opening all 115streams and before starting data transfer, or, with listening sockets with 116fork option, before the first accept call), it switches logging to syslog\&. 117With optional <facility>, the syslog type can be 118selected, default is \(dq\&daemon\(dq\&\&. 119.IP "\fB\f(CW\-lh\fP\fP" 120Adds hostname to log messages\&. Uses the value from environment variable 121HOSTNAME or the value retrieved with \f(CWuname()\fP if HOSTNAME is not set\&. 122.IP "\fB\f(CW\-v\fP\fP" 123Writes the transferred data not only to their target streams, but also to 124stderr\&. The output format is text with some conversions for readability, and 125prefixed with \(dq\&> \(dq\& or \(dq\&< \(dq\& indicating flow directions\&. 126.IP "\fB\f(CW\-x\fP\fP" 127Writes the transferred data not only to their target streams, but also to 128stderr\&. The output format is hexadecimal, prefixed with \(dq\&> \(dq\& or \(dq\&< \(dq\& 129indicating flow directions\&. Can be combined with 130\f(CW\-v\fP 131\&. 132.IP "\fB\f(CW\-b\fP\fP\f(CW<size>\fP" 133Sets the data transfer block <size> [size_t]\&. 134At most <size> bytes are transferred per step\&. Default is 8192 bytes\&. 135.IP "\fB\f(CW\-s\fP\fP" 136By default, \fBsocat\fP terminates when an error occurred to prevent the process 137from running when some option could not be applied\&. With this 138option, \fBsocat\fP is sloppy with errors and tries to continue\&. Even with this 139option, socat will exit on fatals, and will abort connection attempts when 140security checks failed\&. 141.IP "\fB\f(CW\-t\fP\fP\f(CW<timeout>\fP" 142When one channel has reached EOF, the write part of the other channel is shut 143down\&. Then, \fBsocat\fP waits <timeout> [timeval] seconds 144before terminating\&. Default is 0\&.5 seconds\&. This timeout only applies to 145addresses where write and read part can be closed independently\&. When during 146the timeout interval the read part gives EOF, socat terminates without 147awaiting the timeout\&. 148.IP "\fB\f(CW\-T\fP\fP\f(CW<timeout>\fP" 149Total inactivity timeout: when socat is already in the transfer loop and 150nothing has happened for <timeout> [timeval] seconds 151(no data arrived, no interrupt occurred\&.\&.\&.) then it terminates\&. 152Useful with protocols like UDP that cannot transfer EOF\&. 153.IP "\fB\f(CW\-u\fP\fP" 154Uses unidirectional mode\&. The first address is only used for reading, and the 155second address is only used for writing (example)\&. 156.IP "\fB\f(CW\-U\fP\fP" 157Uses unidirectional mode in reverse direction\&. The first address is only 158used for writing, and the second address is only used for reading\&. 159.IP "\fB\f(CW\-g\fP\fP" 160During address option parsing, don\(cq\&t check if the option is considered 161useful in the given address environment\&. Use it if you want to force, e\&.g\&., 162appliance of a socket option to a serial device\&. 163.IP "\fB\f(CW\-L\fP\fP\f(CW<lockfile>\fP" 164If lockfile exists, exits with error\&. If lockfile does not exist, creates it 165and continues, unlinks lockfile on exit\&. 166.IP "\fB\f(CW\-W\fP\fP\f(CW<lockfile>\fP" 167If lockfile exists, waits until it disappears\&. When lockfile does not exist, 168creates it and continues, unlinks lockfile on exit\&. 169.IP "\fB\f(CW\-4\fP\fP" 170Use IP version 4 in case that the addresses do not implicitly or explicitly 171specify a version; this is the default\&. 172.IP "\fB\f(CW\-6\fP\fP" 173Use IP version 6 in case that the addresses do not implicitly or explicitly 174specify a version\&. 175 176.PP 177.SH "ADDRESS SPECIFICATIONS" 178 179.PP 180With the address command line arguments, the user gives \fBsocat\fP instructions and 181the necessary information for establishing the byte streams\&. 182.PP 183An address specification usually consists of an address type 184keyword, zero or more required address parameters separated by \(cq\&:\(cq\& from the keyword and 185from each 186other, and zero or more address options separated by \(cq\&,\(cq\&\&. 187.PP 188The keyword specifies the address type (e\&.g\&., TCP4, OPEN, EXEC)\&. For some 189keywords there exist synonyms (\(cq\&\-\(cq\& for STDIO, TCP for TCP4)\&. Keywords are case 190insensitive\&. 191For a few special address types, the keyword may be omitted: 192Address specifications starting with a number are assumed to be FD (raw file 193descriptor) addresses; 194if a \(cq\&/\(cq\& is found before the first \(cq\&:\(cq\& or \(cq\&,\(cq\&, GOPEN (generic file open) is 195assumed\&. 196.PP 197The required number and type of address parameters depend on the address 198type\&. E\&.g\&., TCP4 requires a server specification (name or address), and a port 199specification (number or service name)\&. 200.PP 201Zero or more address options may be given with each address\&. They influence the 202address in some ways\&. 203Options consist of an option keyword or an option keyword and a value, 204separated by \(cq\&=\(cq\&\&. Option keywords are case insensitive\&. 205For filtering the options that are useful with an address 206type, each option is member of one option group\&. For 207each address type there is a set of option groups allowed\&. Only options 208belonging to one of these address groups may be used (except with option \-g)\&. 209.PP 210Address specifications following the above schema are also called \fIsingle\fP 211address specifications\&. 212Two single addresses can be combined with \(dq\&!!\(dq\& to form a \fIdual\fP type 213address for one channel\&. Here, the first address is used by \fBsocat\fP for reading 214data, and the 215second address for writing data\&. There is no way to specify an option only once 216for being applied to both single addresses\&. 217.PP 218Usually, addresses are opened in read/write 219mode\&. When an address is part of a dual address specification, or when 220option \-u or \-U is used, an address might be 221used only for reading or for writing\&. Considering this is important with some 222address types\&. 223.PP 224With socat version 1\&.5\&.0 and higher, the lexical analysis tries to handle 225quotes and parenthesis meaningfully and allows escaping of special characters\&. 226If one of the characters ( { [ \(cq\& is found, the corresponding closing 227character \- ) } ] \(cq\& \- is looked for; they may also be nested\&. Within these 228constructs, socats special characters and strings : , !! are not handled 229specially\&. All those characters and strings can be escaped with \e or within \(dq\&\(dq\& 230.PP 231.SH "ADDRESS TYPES" 232 233.PP 234This section describes the available address types with their keywords, 235parameters, and semantics\&. 236.PP 237.IP "\fB\f(CWCREATE:<filename>\fP\fP" 238Opens <filename> with 239\f(CWcreat()\fP 240and uses the file 241descriptor for writing\&. 242This address type requires write\-only context, because a file opened with 243\f(CWcreat\fP 244cannot be read from\&. 245.br 246Flags like O_LARGEFILE cannot be applied\&. If you need them use 247OPEN with options 248create,create\&. 249.br 250<filename> must be a valid existing or not existing path\&. 251If <filename> is a named pipe, 252\f(CWcreat()\fP 253might block; 254if <filename> refers to a socket, this is an error\&. 255.br 256Option groups: FD,REG,NAMED 257.br 258Useful options: 259mode, 260user, 261group, 262unlink\-early, 263unlink\-late, 264append 265.br 266See also: OPEN, GOPEN 267.IP "\fB\f(CWEXEC:<command\-line>\fP\fP" 268Forks a sub process that establishes communication with its parent process 269and invokes the specified program with 270\f(CWexecvp()\fP 271\&. 272<command\-line> is a simple command 273with arguments separated by single spaces\&. If the program name 274contains a \(cq\&/\(cq\&, the part after the last \(cq\&/\(cq\& is taken as ARGV[0]\&. If the 275program name is a relative 276path, the 277\f(CWexecvp()\fP 278semantics for finding the program via 279\f(CW$PATH\fP 280apply\&. After successful program start, \fBsocat\fP writes data to stdin of the 281process and reads from its stdout using a UNIX domain socket generated by 282\f(CWsocketpair()\fP 283per default\&. (example) 284.br 285Option groups: FD,SOCKET,EXEC,FORK,TERMIOS 286.br 287Useful options: 288path, 289fdin, 290fdout, 291chroot, 292su, 293su\-d, 294nofork, 295pty, 296stderr, 297ctty, 298setsid, 299pipes, 300login, 301sigint, 302sigquit 303.br 304See also: SYSTEM 305.IP "\fB\f(CWFD:<fdnum>\fP\fP" 306Uses the file descriptor <fdnum>\&. It must already exist as 307valid UN*X file descriptor\&. 308.br 309Option groups: FD (TERMIOS,REG,SOCKET) 310.br 311See also: 312STDIO, 313STDIN, 314STDOUT, 315STDERR 316.IP "\fB\f(CWGOPEN:<filename>\fP\fP" 317(Generic open) This address type tries to handle any file system entry 318except directories usefully\&. <filename> may be a 319relative or absolute path\&. If it already exists, its type is checked\&. 320In case of a UNIX domain socket, \fBsocat\fP connects; if connecting fails, 321\fBsocat\fP assumes a datagram socket and uses 322\f(CWsendto()\fP 323calls\&. 324If the entry is not a socket, \fBsocat\fP opens it applying the 325\f(CWO_APPEND\fP 326flag\&. 327If it does not exist, it is opened with flag 328\f(CWO_CREAT\fP 329as a regular file (example)\&. 330.br 331Option groups: FD,REG,SOCKET,NAMED,OPEN 332.br 333See also: 334OPEN, 335CREATE, 336UNIX\-CONNECT 337.IP 338.IP "\fB\f(CWIP\-SENDTO:<host>:<protocol>\fP\fP" 339Opens a raw IP socket\&. Depending on host specification or option pf, IP protocol version 3404 or 6 is used\&. It uses <protocol> to send packets 341to <host> [IP address] and receives packets from 342host, ignores packets from other hosts\&. 343Protocol 255 uses the raw socket with the IP header being part of the 344data\&. 345.br 346Option groups: FD,SOCKET,IP4,IP6 347.br 348Useful options: 349pf, 350ttl 351.br 352See also: 353IP4\-SENDTO, 354IP6\-SENDTO, 355IP\-RECVFROM, 356IP\-RECV, 357UDP\-SENDTO, 358UNIX\-SENDTO 359.IP "\fB\f(CWINTERFACE:<interface>\fP\fP" 360Communicates with a network connected on an interface using raw packets 361including link level data\&. <interface> is the name of 362the network interface\&. Currently only available on Linux\&. 363Option groups: FD,SOCKET 364.br 365Useful options: 366pf, 367type 368.br 369See also: ip\-recv 370.IP "\fB\f(CWIP4\-SENDTO:<host>:<protocol>\fP\fP" 371Like IP\-SENDTO, but always uses IPv4\&. 372.br 373Option groups: FD,SOCKET,IP4 374.br 375.IP "\fB\f(CWIP6\-SENDTO:<host>:<protocol>\fP\fP" 376Like IP\-SENDTO, but always uses IPv6\&. 377.br 378Option groups: FD,SOCKET,IP6 379.br 380 381.IP 382.IP "\fB\f(CWIP\-DATAGRAM:<address>:<protocol>\fP\fP" 383Sends outgoing data to the specified address which may in particular be a 384broadcast or multicast address\&. Packets arriving on the local socket are 385checked if their source addresses match 386RANGE or TCPWRAP 387options\&. This address type can for example be used for implementing 388symmetric or asymmetric broadcast or multicast communications\&. 389.br 390Option groups: FD, SOCKET, 391IP4, IP6, RANGE 392.br 393Useful options: 394bind, 395range, 396tcpwrap, 397broadcast, 398ip\-multicast\-loop, 399ip\-multicast\-ttl, 400ip\-multicast\-if, 401ip\-add\-membership, 402ttl, 403tos, 404pf 405.br 406See also: 407IP4\-DATAGRAM, 408IP6\-DATAGRAM, 409IP\-SENDTO, 410IP\-RECVFROM, 411IP\-RECV, 412UDP\-DATAGRAM 413.IP "\fB\f(CWIP4\-DATAGRAM:<host>:<protocol>\fP\fP" 414Like IP\-DATAGRAM, but always uses IPv4\&. 415(example) 416.br 417Option groups: FD,SOCKET,IP4,RANGE 418.br 419.IP "\fB\f(CWIP6\-DATAGRAM:<host>:<protocol>\fP\fP" 420Like IP\-DATAGRAM, but always uses IPv6\&. Please 421note that IPv6 does not know broadcasts\&. 422.br 423Option groups: FD,SOCKET,IP6,RANGE 424.br 425 426.IP 427.IP "\fB\f(CWIP\-RECVFROM:<protocol>\fP\fP" 428Opens a raw IP socket of <protocol>\&. Depending on option pf, IP protocol version 4294 or 6 is used\&. It receives one packet from an unspecified peer and may send one or more answer packets to that peer\&. 430This mode is particularly useful with fork option where each arriving packet \- from arbitrary peers \- is handled by its own sub process\&. 431This allows a behaviour similar to typical UDP based servers like ntpd or 432named\&. 433.br 434Please note that the reply packets might be fetched as incoming traffic when 435sender and receiver IP address are identical because there is no port number 436to distinguish the sockets\&. 437.br 438This address works well with IP\-SENDTO address peers (see above)\&. 439Protocol 255 uses the raw socket with the IP header being part of the 440data\&. 441.br 442Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE 443.br 444Useful options: 445pf, 446fork, 447range, 448ttl, 449broadcast 450.br 451See also: 452IP4\-RECVFROM, 453IP6\-RECVFROM, 454IP\-SENDTO, 455IP\-RECV, 456UDP\-RECVFROM, 457UNIX\-RECVFROM 458.IP "\fB\f(CWIP4\-RECVFROM:<protocol>\fP\fP" 459Like IP\-RECVFROM, but always uses IPv4\&. 460.br 461Option groups: FD,SOCKET,IP4,CHILD,RANGE 462.br 463.IP "\fB\f(CWIP6\-RECVFROM:<protocol>\fP\fP" 464Like IP\-RECVFROM, but always uses IPv6\&. 465.br 466Option groups: FD,SOCKET,IP6,CHILD,RANGE 467.br 468 469.IP 470.IP "\fB\f(CWIP\-RECV:<protocol>\fP\fP" 471Opens a raw IP socket of <protocol>\&. Depending on option pf, IP protocol version 4724 or 6 is used\&. It receives packets from multiple unspecified peers and merges the data\&. 473No replies are possible\&. 474It can be, e\&.g\&., addressed by socat IP\-SENDTO address peers\&. 475Protocol 255 uses the raw socket with the IP header being part of the 476data\&. 477.br 478Option groups: FD,SOCKET,IP4,IP6,RANGE 479.br 480Useful options: 481pf, 482range 483.br 484See also: 485IP4\-RECV, 486IP6\-RECV, 487IP\-SENDTO, 488IP\-RECVFROM, 489UDP\-RECV, 490UNIX\-RECV 491.IP "\fB\f(CWIP4\-RECV:<protocol>\fP\fP" 492Like IP\-RECV, but always uses IPv4\&. 493.br 494Option groups: FD,SOCKET,IP4,RANGE 495.br 496.IP "\fB\f(CWIP6\-RECV:<protocol>\fP\fP" 497Like IP\-RECV, but always uses IPv6\&. 498.br 499Option groups: FD,SOCKET,IP6,RANGE 500.br 501 502.IP 503.IP "\fB\f(CWOPEN:<filename>\fP\fP" 504Opens <filename> using the 505\f(CWopen()\fP 506system call 507(example)\&. 508This operation fails on UNIX domain sockets\&. 509.br 510Note: This address type is rarly useful in bidirectional mode\&. 511.br 512Option groups: FD,REG,NAMED,OPEN 513.br 514Useful options: 515creat, 516excl, 517noatime, 518nofollow, 519append, 520rdonly, 521wronly, 522lock, 523readbytes, 524ignoreeof 525.br 526See also: 527CREATE, 528GOPEN, 529UNIX\-CONNECT 530.IP "\fB\f(CWOPENSSL:<host>:<port>\fP\fP" 531Tries to establish a SSL connection to <port> [TCP 532service] on 533<host> [IP address] using TCP/IP version 4 or 6 534depending on address specification, name resolution, or option 535pf\&. 536.br 537NOTE: The server certificate is only checked for validity against 538cafile or capath, 539but not for match with the server\(cq\&s name or its IP address! 540.br 541Option groups: FD,SOCKET,IP4,IP6,TCP,OPENSSL,RETRY 542.br 543Useful options: 544cipher, 545method, 546verify, 547cafile, 548capath, 549certificate, 550key, 551compress, 552bind, 553pf, 554connect\-timeout, 555sourceport, 556retry 557.br 558See also: 559OPENSSL\-LISTEN, 560TCP 561.IP "\fB\f(CWOPENSSL\-LISTEN:<port>\fP\fP" 562Listens on tcp <port> [TCP service]\&. 563The IP version is 4 or the one specified with 564pf\&. When a 565connection is accepted, this address behaves as SSL server\&. 566.br 567Note: You probably want to use the certificate option with this address\&. 568.br 569NOTE: The client certificate is only checked for validity against 570cafile or capath, 571but not for match with the client\(cq\&s name or its IP address! 572.br 573Option groups: FD,SOCKET,IP4,IP6,TCP,LISTEN,OPENSSL,CHILD,RANGE,RETRY 574.br 575Useful options: 576pf, 577cipher, 578method, 579verify, 580cafile, 581capath, 582certificate, 583key, 584compress, 585fork, 586bind, 587range, 588tcpwrap, 589su, 590reuseaddr, 591retry 592.br 593See also: 594OPENSSL, 595TCP\-LISTEN 596.IP "\fB\f(CWPIPE:<filename>\fP\fP" 597If <filename> already exists, it is opened\&. 598If it does not exist, a named pipe is created and opened\&. Beginning with 599socat version 1\&.4\&.3, the named pipe is removed when the address is closed 600(but see option unlink\-close 601.br 602Note: When a pipe is used for both reading and writing, it works 603as echo service\&. 604.br 605Note: When a pipe is used for both reading and writing, and socat tries 606to write more bytes than the pipe can buffer (Linux 2\&.4: 2048 bytes), socat 607might block\&. Consider using socat option, e\&.g\&., 608\f(CW\-b 2048\fP 609.br 610Option groups: FD,NAMED,OPEN 611.br 612Useful options: 613rdonly, 614nonblock, 615group, 616user, 617mode, 618unlink\-early 619.br 620See also: unnamed pipe 621.IP "\fB\f(CWPIPE\fP\fP" 622Creates an unnamed pipe and uses it for reading and writing\&. It works as an 623echo, because everything written 624to it appeares immediately as read data\&. 625.br 626Note: When socat tries to write more bytes than the pipe can queue (Linux 6272\&.4: 2048 bytes), socat might block\&. Consider, e\&.g\&., using 628option 629\f(CW\-b 2048\fP 630.br 631Option groups: FD 632.br 633See also: named pipe 634.IP "\fB\f(CWPROXY:<proxy>:<hostname>:<port>\fP\fP" 635Connects to an HTTP proxy server on port 8080 using TCP/IP version 4 or 6 636depending on address specification, name resolution, or option 637pf, and sends a CONNECT 638request for hostname:port\&. If the proxy grants access and succeeds to 639connect to the target, data transfer between socat and the target can 640start\&. Note that the traffic need not be HTTP but can be an arbitrary 641protocol\&. 642.br 643Option groups: FD,SOCKET,IP4,IP6,TCP,HTTP,RETRY 644.br 645Useful options: 646proxyport, 647ignorecr, 648proxyauth, 649resolve, 650crnl, 651bind, 652connect\-timeout, 653mss, 654sourceport, 655retry 656.br 657See also: SOCKS, TCP 658.IP "\fB\f(CWPTY\fP\fP" 659Generates a pseudo terminal (pty) and uses its master side\&. Another process 660may open the pty\(cq\&s slave side using it like a serial line or terminal\&. 661(example)\&. If 662both the ptmx and the openpty mechanisms are available, ptmx is used 663(POSIX)\&. 664.br 665Option groups: FD,NAMED,PTY,TERMIOS 666.br 667Useful options: 668link, 669openpty, 670wait\-slave, 671mode, 672user, 673group 674.br 675See also: 676UNIX\-LISTEN, 677PIPE, 678EXEC, SYSTEM 679.IP "\fB\f(CWREADLINE\fP\fP" 680Uses GNU readline and history on stdio to allow editing and reusing input 681lines (example)\&. This requires the GNU readline and 682history libraries\&. Note that stdio should be a (pseudo) terminal device, 683otherwise readline does not seem to work\&. 684.br 685Option groups: FD,READLINE,TERMIOS 686.br 687Useful options: 688history, 689noecho 690.br 691See also: 692STDIO 693.IP "\fB\f(CWSCTP\-CONNECT:<host>:<port>\fP\fP" 694Establishes an SCTP stream connection to the specified <host> [IP 695address] and <port> [TCP service] 696using TCP/IP version 4 or 6 depending on address specification, name 697resolution, or option pf\&. 698.br 699Option groups: FD,SOCKET,IP4,IP6,SCTP,CHILD,RETRY 700.br 701Useful options: 702bind, 703pf, 704connect\-timeout, 705tos, 706mtudiscover, 707sctp\-maxseg, 708sctp\-nodelay, 709nonblock, 710sourceport, 711retry, 712readbytes 713.br 714See also: 715SCTP4\-CONNECT, 716SCTP6\-CONNECT, 717SCTP\-LISTEN, 718TCP\-CONNECT 719.IP "\fB\f(CWSCTP4\-CONNECT:<host>:<port>\fP\fP" 720Like SCTP\-CONNECT, but only supports IPv4 protocol\&. 721.br 722Option groups: FD,SOCKET,IP4,SCTP,CHILD,RETRY 723.br 724.IP "\fB\f(CWSCTP6\-CONNECT:<host>:<port>\fP\fP" 725Like SCTP\-CONNECT, but only supports IPv6 protocol\&. 726.br 727Option groups: FD,SOCKET,IP6,SCTP,CHILD,RETRY 728.br 729.IP "\fB\f(CWSCTP\-LISTEN:<port>\fP\fP" 730Listens on <port> [TCP service] and accepts a 731TCP/IP connection\&. The IP version is 4 or the one specified with 732address option pf, socat option 733(\-4, \-6), or environment variable SOCAT_DEFAULT_LISTEN_IP\&. 734Note that opening 735this address usually blocks until a client connects\&. 736.br 737Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,SCTP,RETRY 738.br 739Useful options: 740crnl, 741fork, 742bind, 743range, 744tcpwrap, 745pf, 746max\-children, 747backlog, 748sctp\-maxseg, 749sctp\-nodelay, 750su, 751reuseaddr, 752retry, 753cool\-write 754.br 755See also: 756SCTP4\-LISTEN, 757SCTP6\-LISTEN, 758TCP\-LISTEN, 759SCTP\-CONNECT 760.IP "\fB\f(CWSCTP4\-LISTEN:<port>\fP\fP" 761Like SCTP\-LISTEN, but only supports IPv4 762protocol\&. 763.br 764Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,SCTP,RETRY 765.br 766.IP "\fB\f(CWSCTP6\-LISTEN:<port>\fP\fP" 767Like SCTP\-LISTEN, but only supports IPv6 768protocol\&. 769.br 770Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,SCTP,RETRY 771.br 772.IP "\fB\f(CWSOCKET\-CONNECT:<domain>:<protocol>:<remote\-address>\fP\fP" 773Creates a stream socket using the first and second given socket parameters 774and \f(CWSOCK_STREAM\fP (see man socket\e(2)) and connects to the remote\-address\&. 775The two socket parameters have to be specified by int 776numbers\&. Consult your OS documentation and include files to find the 777appropriate values\&. The remote\-address must be the data 778representation of a sockaddr structure without sa_family and (BSD) sa_len 779components\&. 780.br 781Please note that you can \- beyond the options of the specified groups \- also 782use options of higher level protocols when you apply socat option 783\-g\&. 784.br 785Option groups: FD,SOCKET,CHILD,RETRY 786.br 787Useful options: 788bind, 789setsockopt\-int, 790setsockopt\-bin, 791setsockopt\-string 792.br 793See also: 794TCP, 795UDP\-CONNECT, 796UNIX\-CONNECT, 797SOCKET\-LISTEN, 798SOCKET\-SENDTO 799.IP "\fB\f(CWSOCKET\-DATAGRAM:<domain>:<type>:<protocol>:<remote\-address>\fP\fP" 800Creates a datagram socket using the first three given socket parameters (see 801man socket\e(2)) and sends outgoing data to the remote\-address\&. The three 802socket parameters have to be specified by int 803numbers\&. Consult your OS documentation and include files to find the 804appropriate values\&. The remote\-address must be the data 805representation of a sockaddr structure without sa_family and (BSD) sa_len 806components\&. 807.br 808Please note that you can \- beyond the options of the specified groups \- also 809use options of higher level protocols when you apply socat option 810\-g\&. 811.br 812Option groups: FD,SOCKET,RANGE 813.br 814Useful options: 815bind, 816range, 817setsockopt\-int, 818setsockopt\-bin, 819setsockopt\-string 820.br 821See also: 822UDP\-DATAGRAM, 823IP\-DATAGRAM, 824SOCKET\-SENDTO, 825SOCKET\-RECV, 826SOCKET\-RECVFROM 827.IP "\fB\f(CWSOCKET\-LISTEN:<domain>:<protocol>:<local\-address>\fP\fP" 828Creates a stream socket using the first and second given socket parameters 829and \f(CWSOCK_STREAM\fP (see man socket\e(2)) and waits for incoming connections 830on local\-address\&. The two socket parameters have to be specified by 831int numbers\&. Consult your OS documentation and include files 832to find the appropriate values\&. The local\-address must be the 833data representation of a sockaddr structure without 834sa_family and (BSD) sa_len components\&. 835.br 836Please note that you can \- beyond the options of the specified groups \- also 837use options of higher level protocols when you apply socat option 838\-g\&. 839.br 840Option groups: FD,SOCKET,LISTEN,RANGE,CHILD,RETRY 841.br 842Useful options: 843setsockopt\-int, 844setsockopt\-bin, 845setsockopt\-string 846.br 847See also: 848TCP, 849UDP\-CONNECT, 850UNIX\-CONNECT, 851SOCKET\-LISTEN, 852SOCKET\-SENDTO, 853SOCKET\-SENDTO 854.IP "\fB\f(CWSOCKET\-RECV:<domain>:<type>:<protocol>:<local\-address>\fP\fP" 855Creates a socket using the three given socket parameters (see man socket\e(2)) 856and binds it to <local\-address>\&. Receives arriving data\&. The three 857parameters have to be specified by int numbers\&. Consult your 858OS documentation and include files to find the appropriate values\&. The 859local\-address must be the data representation of a sockaddr 860structure without sa_family and (BSD) sa_len components\&. 861.br 862Option groups: FD,SOCKET,RANGE 863.br 864Useful options: 865range, 866setsockopt\-int, 867setsockopt\-bin, 868setsockopt\-string 869.br 870See also: 871UDP\-RECV, 872IP\-RECV, 873UNIX\-RECV, 874SOCKET\-DATAGRAM, 875SOCKET\-SENDTO, 876SOCKET\-RECVFROM 877.IP "\fB\f(CWSOCKET\-RECVFROM:<domain>:<type>:<protocol>:<local\-address>\fP\fP" 878Creates a socket using the three given socket parameters (see man socket\e(2)) 879and binds it to <local\-address>\&. Receives arriving data and sends replies 880back to the sender\&. The first three parameters have to be specified as 881int numbers\&. Consult your OS documentation and include files 882to find the appropriate values\&. The local\-address must be the 883data representation of a sockaddr structure without 884sa_family and (BSD) sa_len components\&. 885.br 886Option groups: FD,SOCKET,CHILD,RANGE 887.br 888Useful options: 889fork, 890range, 891setsockopt\-int, 892setsockopt\-bin, 893setsockopt\-string 894.br 895See also: 896UDP\-RECVFROM, 897IP\-RECVFROM, 898UNIX\-RECVFROM, 899SOCKET\-DATAGRAM, 900SOCKET\-SENDTO, 901SOCKET\-RECV 902.IP "\fB\f(CWSOCKET\-SENDTO:<domain>:<type>:<protocol>:<remote\-address>\fP\fP" 903Creates a socket using the three given socket parameters (see man 904socket\e(2))\&. Sends outgoing data to the given address and receives replies\&. 905The three parameters have to be specified as int 906numbers\&. Consult your OS documentation and include files to find the 907appropriate values\&. The remote\-address must be the data 908representation of a sockaddr structure without sa_family and (BSD) sa_len 909components\&. 910.br 911Option groups: FD,SOCKET 912.br 913Useful options: 914bind, 915setsockopt\-int, 916setsockopt\-bin, 917setsockopt\-string 918.br 919See also: 920UDP\-SENDTO, 921IP\-SENDTO, 922UNIX\-SENDTO, 923SOCKET\-DATAGRAM, 924SOCKET\-RECV 925SOCKET\-RECVFROM 926.IP "\fB\f(CWSOCKS4:<socks\-server>:<host>:<port>\fP\fP" 927Connects via <socks\-server> [IP address] 928to <host> [IPv4 address] 929on <port> [TCP service], 930using socks version 4 protocol over IP version 4 or 6 depending on address specification, name resolution, or option 931pf (example)\&. 932.br 933Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY 934.br 935Useful options: 936socksuser, 937socksport, 938sourceport, 939pf, 940retry 941.br 942See also: 943SOCKS4A, 944PROXY, 945TCP 946.IP "\fB\f(CWSOCKS4A:<socks\-server>:<host>:<port>\fP\fP" 947like SOCKS4, but uses socks protocol version 4a, thus 948leaving host name resolution to the socks server\&. 949.br 950Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY 951.br 952.IP "\fB\f(CWSTDERR\fP\fP" 953Uses file descriptor 2\&. 954.br 955Option groups: FD (TERMIOS,REG,SOCKET) 956.br 957See also: FD 958.IP "\fB\f(CWSTDIN\fP\fP" 959Uses file descriptor 0\&. 960.br 961Option groups: FD (TERMIOS,REG,SOCKET) 962.br 963Useful options: 964readbytes 965.br 966See also: FD 967.IP "\fB\f(CWSTDIO\fP\fP" 968Uses file descriptor 0 for reading, and 1 for writing\&. 969.br 970Option groups: FD (TERMIOS,REG,SOCKET) 971.br 972Useful options: 973readbytes 974.br 975See also: FD 976.IP "\fB\f(CWSTDOUT\fP\fP" 977Uses file descriptor 1\&. 978.br 979Option groups: FD (TERMIOS,REG,SOCKET) 980.br 981See also: FD 982.IP "\fB\f(CWSYSTEM:<shell\-command>\fP\fP" 983Forks a sub process that establishes communication with its parent process 984and invokes the specified program with 985\f(CWsystem()\fP 986\&. Please note that 987<shell\-command> [string] must 988not contain \(cq\&,\(cq\& or \(dq\&!!\(dq\&, and that shell meta characters may have to be 989protected\&. 990After successful program start, \fBsocat\fP writes data to stdin of the 991process and reads from its stdout\&. 992.br 993Option groups: FD,SOCKET,EXEC,FORK,TERMIOS 994.br 995Useful options: 996path, 997fdin, 998fdout, 999chroot, 1000su, 1001su\-d, 1002nofork, 1003pty, 1004stderr, 1005ctty, 1006setsid, 1007pipes, 1008sigint, 1009sigquit 1010.br 1011See also: EXEC 1012.IP "\fB\f(CWTCP:<host>:<port>\fP\fP" 1013Connects to <port> [TCP service] on 1014<host> [IP address] using TCP/IP version 4 or 6 1015depending on address specification, name resolution, or option 1016pf\&. 1017.br 1018Option groups: FD,SOCKET,IP4,IP6,TCP,RETRY 1019.br 1020Useful options: 1021crnl, 1022bind, 1023pf, 1024connect\-timeout, 1025tos, 1026mtudiscover, 1027mss, 1028nodelay, 1029nonblock, 1030sourceport, 1031retry, 1032readbytes 1033.br 1034See also: 1035TCP4, 1036TCP6, 1037TCP\-LISTEN, 1038UDP, 1039SCTP\-CONNECT, 1040UNIX\-CONNECT 1041.IP "\fB\f(CWTCP4:<host>:<port>\fP\fP" 1042Like TCP, but only supports IPv4 protocol (example)\&. 1043.br 1044Option groups: FD,SOCKET,IP4,TCP,RETRY 1045.br 1046.IP "\fB\f(CWTCP6:<host>:<port>\fP\fP" 1047Like TCP, but only supports IPv6 protocol\&. 1048.br 1049Option groups: FD,SOCKET,IP6,TCP,RETRY 1050.br 1051.IP "\fB\f(CWTCP\-LISTEN:<port>\fP\fP" 1052Listens on <port> [TCP service] and accepts a 1053TCP/IP connection\&. The IP version is 4 or the one specified with 1054address option pf, socat option 1055(\-4, \-6), or environment variable SOCAT_DEFAULT_LISTEN_IP\&. 1056Note that opening 1057this address usually blocks until a client connects\&. 1058.br 1059Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,TCP,RETRY 1060.br 1061Useful options: 1062crnl, 1063fork, 1064bind, 1065range, 1066tcpwrap, 1067pf, 1068max\-children, 1069backlog, 1070mss, 1071su, 1072reuseaddr, 1073retry, 1074cool\-write 1075.br 1076See also: 1077TCP4\-LISTEN, 1078TCP6\-LISTEN, 1079UDP\-LISTEN, 1080SCTP\-LISTEN, 1081UNIX\-LISTEN, 1082OPENSSL\-LISTEN, 1083TCP\-CONNECT 1084.IP "\fB\f(CWTCP4\-LISTEN:<port>\fP\fP" 1085Like TCP\-LISTEN, but only supports IPv4 1086protocol (example)\&. 1087.br 1088Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,TCP,RETRY 1089.br 1090.IP "\fB\f(CWTCP6\-LISTEN:<port>\fP\fP" 1091Like TCP\-LISTEN, but only supports IPv6 1092protocol\&. 1093.br 1094Additional useful option: 1095ipv6only 1096.br 1097Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,TCP,RETRY 1098.br 1099.IP "\fB\f(CWTUN[:<if\-addr>/<bits>]\fP\fP" 1100Creates a Linux TUN/TAP device and optionally assignes it the address and 1101netmask given by the parameters\&. The resulting network interface is almost 1102ready for use by other processes; socat serves its \(dq\&wire side\(dq\&\&. This address 1103requires read and write access to the tunnel cloning device, usually 1104\f(CW/dev/net/tun\fP 1105, as well as permission to set some \f(CWioctl()s\fP\&. 1106\fBOption iff\-up is required to immediately activate the interface!\fP 1107.br 1108Option groups: FD,NAMED,OPEN,TUN 1109.br 1110Useful options: 1111iff\-up, 1112tun\-device, 1113tun\-name, 1114tun\-type, 1115iff\-no\-pi 1116.br 1117See also: 1118ip\-recv 1119.IP "\fB\f(CWUDP:<host>:<port>\fP\fP" 1120Connects to <port> [UDP service] on 1121<host> [IP address] using UDP/IP version 4 or 6 1122depending on address specification, name resolution, or option 1123pf\&. 1124.br 1125Please note that, 1126due to UDP protocol properties, no real connection is established; data has 1127to be sent for `connecting\(cq\& to the server, and no end\-of\-file condition can 1128be transported\&. 1129.br 1130Option groups: FD,SOCKET,IP4,IP6 1131.br 1132Useful options: 1133ttl, 1134tos, 1135bind, 1136sourceport, 1137pf 1138.br 1139See also: 1140UDP4, 1141UDP6, 1142UDP\-LISTEN, 1143TCP, 1144IP 1145.IP "\fB\f(CWUDP4:<host>:<port>\fP\fP" 1146Like UDP, but only supports IPv4 protocol\&. 1147.br 1148Option groups: FD,SOCKET,IP4 1149.br 1150.IP "\fB\f(CWUDP6:<host>:<port>\fP\fP" 1151Like UDP, but only supports IPv6 protocol\&. 1152.br 1153Option groups: FD,SOCKET,IP6 1154.br 1155.IP "\fB\f(CWUDP\-DATAGRAM:<address>:<port>\fP\fP" 1156Sends outgoing data to the specified address which may in particular be a 1157broadcast or multicast address\&. Packets arriving on the local socket are 1158checked for the correct remote port and if their source addresses match 1159RANGE or TCPWRAP 1160options\&. This address type can for example be used for implementing 1161symmetric or asymmetric broadcast or multicast communications\&. 1162.br 1163Option groups: FD,SOCKET,IP4,IP6,RANGE 1164.br 1165Useful options: 1166bind, 1167range, 1168tcpwrap, 1169broadcast, 1170ip\-multicast\-loop, 1171ip\-multicast\-ttl, 1172ip\-multicast\-if, 1173ip\-add\-membership, 1174ttl, 1175tos, 1176sourceport, 1177pf 1178.br 1179See also: 1180UDP4\-DATAGRAM, 1181UDP6\-DATAGRAM, 1182UDP\-SENDTO, 1183UDP\-RECVFROM, 1184UDP\-RECV, 1185UDP\-CONNECT, 1186UDP\-LISTEN, 1187IP\-DATAGRAM 1188.IP "\fB\f(CWUDP4\-DATAGRAM:<address>:<port>\fP\fP" 1189Like UDP\-DATAGRAM, but only supports IPv4 1190protocol (example1, 1191example2)\&. 1192.br 1193Option groups: FD,SOCKET,IP4, RANGE 1194.IP "\fB\f(CWUDP6\-DATAGRAM:<address>:<port>\fP\fP" 1195Like UDP\-DATAGRAM, but only supports IPv6 1196protocol\&. 1197.br 1198Option groups: FD,SOCKET,IP6,RANGE 1199.IP "\fB\f(CWUDP\-LISTEN:<port>\fP\fP" 1200Waits for a UDP/IP packet arriving on <port> 1201[UDP service] and `connects\(cq\& back to sender\&. 1202The accepted IP version is 4 or the one specified with option 1203pf\&. 1204Please note that, 1205due to UDP protocol properties, no real connection is established; data has 1206to arrive from the peer first, and no end\-of\-file condition can be 1207transported\&. Note that opening 1208this address usually blocks until a client connects\&. 1209.br 1210Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6 1211.br 1212Useful options: 1213fork, 1214bind, 1215range, 1216pf 1217.br 1218See also: 1219UDP, 1220UDP4\-LISTEN, 1221UDP6\-LISTEN, 1222TCP\-LISTEN 1223.IP "\fB\f(CWUDP4\-LISTEN:<port>\fP\fP" 1224Like UDP\-LISTEN, but only support IPv4 1225protocol\&. 1226.br 1227Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4 1228.br 1229.IP "\fB\f(CWUDP6\-LISTEN:<port>\fP\fP" 1230Like UDP\-LISTEN, but only support IPv6 1231protocol\&. 1232.br 1233Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6 1234.br 1235.IP "\fB\f(CWUDP\-SENDTO:<host>:<port>\fP\fP" 1236Communicates with the specified peer socket, defined by <port> [UDP 1237service] on 1238<host> [IP address], using UDP/IP version 4 or 6 1239depending on address specification, name resolution, or option 1240pf\&. It sends packets to and receives packets 1241from that peer socket only\&. 1242This address effectively implements a datagram client\&. 1243It works well with socat UDP\-RECVFROM and UDP\-RECV address peers\&. 1244.br 1245Option groups: FD,SOCKET,IP4,IP6 1246.br 1247Useful options: 1248ttl, 1249tos, 1250bind, 1251sourceport, 1252pf 1253.br 1254See also: 1255UDP4\-SENDTO, 1256UDP6\-SENDTO, 1257UDP\-RECVFROM, 1258UDP\-RECV, 1259UDP\-CONNECT, 1260UDP\-LISTEN, 1261IP\-SENDTO 1262.IP "\fB\f(CWUDP4\-SENDTO:<host>:<port>\fP\fP" 1263Like UDP\-SENDTO, but only supports IPv4 1264protocol\&. 1265.br 1266Option groups: FD,SOCKET,IP4 1267.IP "\fB\f(CWUDP6\-SENDTO:<host>:<port>\fP\fP" 1268Like UDP\-SENDTO, but only supports IPv6 1269protocol\&. 1270.br 1271Option groups: FD,SOCKET,IP6 1272.IP 1273.IP "\fB\f(CWUDP\-RECVFROM:<port>\fP\fP" 1274Creates a UDP socket on <port> [UDP service] using 1275UDP/IP version 4 or 6 1276depending on option pf\&. 1277It receives one packet from an unspecified peer and may send one or more 1278answer packets to that peer\&. This mode is particularly useful with fork 1279option 1280where each arriving packet \- from arbitrary peers \- is handled by its own sub 1281process\&. This allows a behaviour similar to typical UDP based servers like ntpd 1282or named\&. This address works well with socat UDP\-SENDTO address peers\&. 1283.br 1284Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE 1285.br 1286Useful options: 1287fork, 1288ttl, 1289tos, 1290bind, 1291sourceport, 1292pf 1293.br 1294See also: 1295UDP4\-RECVFROM, 1296UDP6\-RECVFROM, 1297UDP\-SENDTO, 1298UDP\-RECV, 1299UDP\-CONNECT, 1300UDP\-LISTEN, 1301IP\-RECVFROM, 1302UNIX\-RECVFROM 1303.IP "\fB\f(CWUDP4\-RECVFROM:<port>\fP\fP" 1304Like UDP\-RECVFROM, but only supports IPv4 protocol\&. 1305.br 1306Option groups: FD,SOCKET,IP4,CHILD,RANGE 1307.IP "\fB\f(CWUDP6\-RECVFROM:<port>\fP\fP" 1308Like UDP\-RECVFROM, but only supports IPv6 protocol\&. 1309.br 1310Option groups: FD,SOCKET,IP6,CHILD,RANGE 1311.IP 1312.IP "\fB\f(CWUDP\-RECV:<port>\fP\fP" 1313Creates a UDP socket on <port> [UDP service] using UDP/IP version 4 or 6 1314depending on option pf\&. 1315It receives packets from multiple unspecified peers and merges the data\&. 1316No replies are possible\&. It works well with, e\&.g\&., socat UDP\-SENDTO address peers; it behaves similar to a syslog server\&. 1317.br 1318Option groups: FD,SOCKET,IP4,IP6,RANGE 1319.br 1320Useful options: 1321fork, 1322pf, 1323bind, 1324sourceport, 1325ttl, 1326tos 1327.br 1328See also: 1329UDP4\-RECV, 1330UDP6\-RECV, 1331UDP\-SENDTO, 1332UDP\-RECVFROM, 1333UDP\-CONNECT, 1334UDP\-LISTEN, 1335IP\-RECV, 1336UNIX\-RECV 1337.IP "\fB\f(CWUDP4\-RECV:<port>\fP\fP" 1338Like UDP\-RECV, but only supports IPv4 protocol\&. 1339.br 1340Option groups: FD,SOCKET,IP4,RANGE 1341.IP "\fB\f(CWUDP6\-RECV:<port>\fP\fP" 1342Like UDP\-RECV, but only supports IPv6 protocol\&. 1343.br 1344Option groups: FD,SOCKET,IP6,RANGE 1345.IP 1346.IP "\fB\f(CWUNIX\-CONNECT:<filename>\fP\fP" 1347Connects to <filename> assuming it is a UNIX domain 1348socket\&. 1349If <filename> does not exist, this is an error; 1350if <filename> is not a UNIX domain socket, this is an error; 1351if <filename> is a UNIX domain socket, but no process is listening, this is 1352an error\&. 1353.br 1354Option groups: FD,SOCKET,NAMED,RETRY,UNIX 1355.br 1356) 1357Useful options: 1358bind 1359.br 1360See also: 1361UNIX\-LISTEN, 1362UNIX\-SENDTO, 1363TCP 1364.IP 1365.IP "\fB\f(CWUNIX\-LISTEN:<filename>\fP\fP" 1366Listens on <filename> using a UNIX domain stream 1367socket and accepts a connection\&. 1368If <filename> exists and is not a socket, this is an error\&. 1369If <filename> exists and is a UNIX domain socket, binding to the address 1370fails (use option unlink\-early!)\&. 1371Note that opening this address usually blocks until a client connects\&. 1372Beginning with socat version 1\&.4\&.3, the file system entry is removed when 1373this address is closed (but see option unlink\-close) (example)\&. 1374.br 1375Option groups: FD,SOCKET,NAMED,LISTEN,CHILD,RETRY,UNIX 1376.br 1377Useful options: 1378fork, 1379umask, 1380mode, 1381user, 1382group, 1383unlink\-early 1384.br 1385See also: 1386UNIX\-CONNECT, 1387UNIX\-RECVFROM, 1388UNIX\-RECV, 1389TCP\-LISTEN 1390.IP 1391.IP "\fB\f(CWUNIX\-SENDTO:<filename>\fP\fP" 1392Communicates with the specified peer socket, defined by [<filename>] assuming it is a UNIX domain datagram socket\&. 1393It sends packets to and receives packets from that peer socket only\&. 1394Please note that it might be neccessary to bind the 1395local socket to an address (e\&.g\&. \f(CW/tmp/sock1\fP, which must not exist 1396before)\&. 1397This address type works well with socat UNIX\-RECVFROM and UNIX\-RECV address 1398peers\&. 1399.br 1400Option groups: FD,SOCKET,NAMED,UNIX 1401.br 1402Useful options: 1403bind 1404.br 1405See also: 1406UNIX\-RECVFROM, 1407UNIX\-RECV, 1408UNIX\-CONNECT, 1409UDP\-SENDTO, 1410IP\-SENDTO 1411.IP 1412.IP "\fB\f(CWUNIX\-RECVFROM:<filename>\fP\fP" 1413Creates a UNIX domain datagram socket [<filename>]\&. 1414Receives one packet and may send one or more answer packets to that peer\&. 1415This mode is particularly useful with fork option where each arriving packet \- from arbitrary peers \- is handled by its own sub process\&. 1416This address works well with socat UNIX\-SENDTO address peers\&. 1417.br 1418Option groups: FD,SOCKET,NAMED,CHILD,UNIX 1419.br 1420Useful options: 1421fork 1422.br 1423See also: 1424UNIX\-SENDTO, 1425UNIX\-RECV, 1426UNIX\-LISTEN, 1427UDP\-RECVFROM, 1428IP\-RECVFROM 1429.IP 1430.IP "\fB\f(CWUNIX\-RECV:<filename>\fP\fP" 1431Creates a UNIX domain datagram socket [<filename>]\&. 1432Receives packets from multiple unspecified peers and merges the data\&. 1433No replies are possible\&. It can be, e\&.g\&., addressed by socat UNIX\-SENDTO address peers\&. 1434It behaves similar to a syslog server\&. 1435Option groups: FD,SOCKET,NAMED,UNIX 1436.br 1437See also: 1438UNIX\-SENDTO, 1439UNIX\-RECVFROM, 1440UNIX\-LISTEN, 1441UDP\-RECV, 1442IP\-RECV 1443.IP 1444.IP "\fB\f(CWUNIX\-CLIENT:<filename>\fP\fP" 1445Communicates with the specified peer socket, defined by 1446[<filename>] assuming it is a UNIX domain socket\&. 1447It first tries to connect and, if that fails, assumes it is a datagram 1448socket, thus supporting both types\&. 1449.br 1450Option groups: FD,SOCKET,NAMED,UNIX 1451.br 1452Useful options: 1453bind 1454.br 1455See also: 1456UNIX\-CONNECT, 1457UNIX\-SENDTO, 1458GOPEN 1459.IP 1460.IP "\fB\f(CWABSTRACT\-CONNECT:<string>\fP\fP" 1461.IP "\fB\f(CWABSTRACT\-LISTEN:<string>\fP\fP" 1462.IP "\fB\f(CWABSTRACT\-SENDTO:<string>\fP\fP" 1463.IP "\fB\f(CWABSTRACT\-RECVFROM:<string>\fP\fP" 1464.IP "\fB\f(CWABSTRACT\-RECV:<string>\fP\fP" 1465.IP "\fB\f(CWABSTRACT\-CLIENT:<string>\fP\fP" 1466The ABSTRACT addresses are almost identical to the related UNIX addresses 1467except that they do not address file system based sockets but an alternate 1468UNIX domain address space\&. To archieve this the socket address strings are 1469prefixed with \(dq\&\e0\(dq\& internally\&. This feature is available (only?) on Linux\&. 1470Option groups are the same as with the related UNIX addresses, except that 1471the ABSTRACT addresses are not member of the NAMED group\&. 1472 1473.PP 1474.SH "ADDRESS OPTIONS" 1475 1476.PP 1477Address options can be applied to address specifications to influence the 1478process of opening the addresses and the 1479properties of the resulting data channels\&. 1480.PP 1481For technical reasons not every option can be 1482applied to every address type; e\&.g\&., applying a socket option to a regular file 1483will fail\&. To catch most useless combinations as early as in the open phase, 1484the concept of \fIoption groups\fP was introduced\&. Each option belongs to one 1485or more option groups\&. Options can be used only with address types that support 1486at least one of their option groups (but see option \-g)\&. 1487.PP 1488Address options have data types that their values must conform to\&. 1489Every address option consists of just a keyword or a keyword followed by 1490\(dq\&=value\(dq\&, where value must conform to the options type\&. 1491Some address options manipulate parameters of system calls; 1492e\&.g\&., option sync sets the 1493\f(CWO_SYNC\fP 1494flag with the 1495\f(CWopen()\fP 1496call\&. 1497Other options cause a system or library call; e\&.g\&., with option `ttl=value\(cq\& 1498the 1499\f(CWsetsockopt(fd, SOL_IP, IP_TTL, value, sizeof(int))\fP 1500call is applied\&. 1501Other 1502options set internal \fBsocat\fP variables that are used during data transfer; 1503e\&.g\&., `crnl\(cq\& causes explicit character conversions\&. 1504A few options have more complex implementations; e\&.g\&., su\-d 1505(substuser\-delayed) inquires some user and group infos, stores them, and 1506applies them later after a possible 1507\f(CWchroot()\fP 1508call\&. 1509.PP 1510If multiple options are given to an address, their sequence in the address specification has (almost) no 1511effect on the sequence of their execution/application\&. Instead, \fBsocat\fP has 1512built in an \fIoption phase\fP model that tries to bring the options in a useful 1513order\&. Some options exist in different forms (e\&.g\&., 1514unlink, unlink\-early, unlink\-late) to control the time of their execution\&. 1515.PP 1516If the same option is specified more than once within one address 1517specification, with equal or different values, the effect depends on the kind of option\&. Options 1518resulting in function calls like 1519\f(CWsetsockopt()\fP 1520cause multiple 1521invocations\&. With options that set parameters for a required call like 1522\f(CWopen()\fP 1523or set internal flags, the value of the last option occurrence is effective\&. 1524.PP 1525The existence or semantics of many options are system dependent\&. \fBSocat\fP 1526usually does NOT try to emulate missing libc or kernel features, it just 1527provides an 1528interface to the underlying system\&. So, if an operating system lacks a feature, 1529the related option is simply not available on this platform\&. 1530.PP 1531The following paragraphs introduce just the more common address options\&. For 1532a more comprehensive reference and to find information about canonical option 1533names, alias names, option phases, and platforms see file \fBxio\&.help\fP\&. 1534.br 1535.br 1536 1537.PP 1538.br 1539 1540.PP 1541\fI\fBFD option group\fP\fP 1542.PP 1543This option group contains options that are applied to a UN*X 1544style file descriptor, no matter how it was generated\&. 1545Because all current \fBsocat\fP address types are file descriptor based, these 1546options may be applied to any address\&. 1547.br 1548Note: Some of these options are also member of another option group, that 1549provides an other, non\-fd based mechanism\&. 1550For these options, it depends on the actual address type and its option groups 1551which mechanism is used\&. The second, non\-fd based mechanism is prioritized\&. 1552.IP "\fB\f(CWcloexec=<bool>\fP\fP" 1553Sets the 1554\f(CWFD_CLOEXEC\fP 1555flag with the 1556\f(CWfcntl()\fP 1557system call to value 1558<bool>\&. If set, 1559the file descriptor is closed on 1560\f(CWexec()\fP 1561family function calls\&. \fBSocat\fP 1562internally handles 1563this flag for the fds it controls, so in most cases there will be no need to 1564apply this option\&. 1565.IP "\fB\f(CWsetlk\fP\fP" 1566Tries to set a discretionary write lock to the whole file using the 1567\f(CWfcntl(fd, 1568F_SETLK, \&.\&.\&.)\fP 1569system call\&. If the file is already locked, this call results 1570in an error\&. 1571On Linux, when the file permissions for group are \(dq\&S\(dq\& (g\-x,g+s), and the 1572file system is locally mounted with the \(dq\&mand\(dq\& option, the lock is 1573mandatory, i\&.e\&. prevents other processes from opening the file\&. 1574.IP "\fB\f(CWsetlkw\fP\fP" 1575Tries to set a discretionary waiting write lock to the whole file using the 1576\f(CWfcntl(fd, F_SETLKW, \&.\&.\&.)\fP 1577system call\&. If the file is already locked, 1578this call blocks\&. 1579See option setlk for information about making this 1580lock mandatory\&. 1581.IP "\fB\f(CWsetlk\-rd\fP\fP" 1582Tries to set a discretionary read lock to the whole file using the 1583\f(CWfcntl(fd, 1584F_SETLK, \&.\&.\&.)\fP 1585system call\&. If the file is already write locked, this call 1586results in an error\&. 1587See option setlk for information about making this 1588lock mandatory\&. 1589.IP "\fB\f(CWsetlkw\-rd\fP\fP" 1590Tries to set a discretionary waiting read lock to the whole file using the 1591\f(CWfcntl(fd, F_SETLKW, \&.\&.\&.)\fP 1592system call\&. If the file is already write 1593locked, this call blocks\&. 1594See option setlk for information about making this 1595lock mandatory\&. 1596.IP "\fB\f(CWflock\-ex\fP\fP" 1597Tries to set a blocking exclusive advisory lock to the file using the 1598\f(CWflock(fd, LOCK_EX)\fP 1599system call\&. \fBSocat\fP hangs in this call if the file 1600is locked by another process\&. 1601.IP "\fB\f(CWflock\-ex\-nb\fP\fP" 1602Tries to set a nonblocking exclusive advisory lock to the file using the 1603\f(CWflock(fd, LOCK_EX|LOCK_NB)\fP 1604system call\&. If the file is already locked, 1605this option results in an error\&. 1606.IP "\fB\f(CWflock\-sh\fP\fP" 1607Tries to set a blocking shared advisory lock to the file using the 1608\f(CWflock(fd, LOCK_SH)\fP 1609system call\&. \fBSocat\fP hangs in this call if the file 1610is locked by another process\&. 1611.IP "\fB\f(CWflock\-sh\-nb\fP\fP" 1612Tries to set a nonblocking shared advisory lock to the file using the 1613\f(CWflock(fd, LOCK_SH|LOCK_NB)\fP 1614system call\&. If the file is already locked, 1615this option results in an error\&. 1616.IP "\fB\f(CWlock\fP\fP" 1617Sets a blocking lock on the file\&. Uses the setlk or flock mechanism 1618depending on availability on the particular platform\&. If both are available, 1619the POSIX variant (setlkw) is used\&. 1620.IP "\fB\f(CWuser=<user>\fP\fP" 1621Sets the <user> (owner) of the stream\&. 1622If the address is member of the NAMED option group, 1623\fBsocat\fP uses the 1624\f(CWchown()\fP 1625system call after opening the 1626file or binding to the UNIX domain socket (race condition!)\&. 1627Without filesystem entry, \fBsocat\fP sets the user of the stream 1628using the 1629\f(CWfchown()\fP 1630system call\&. 1631These calls might require root privilege\&. 1632.IP "\fB\f(CWuser\-late=<user>\fP\fP" 1633Sets the owner of the fd to <user> with the 1634\f(CWfchown()\fP 1635system call after opening 1636or connecting the channel\&. 1637This is useful only on file system entries\&. 1638.IP "\fB\f(CWgroup=<group>\fP\fP" 1639Sets the <group> of the stream\&. 1640If the address is member of the NAMED option group, 1641\fBsocat\fP uses the 1642\f(CWchown()\fP 1643system call after opening the 1644file or binding to the UNIX domain socket (race condition!)\&. 1645Without filesystem entry, \fBsocat\fP sets the group of the stream 1646with the 1647\f(CWfchown()\fP 1648system call\&. 1649These calls might require group membership or root privilege\&. 1650.IP "\fB\f(CWgroup\-late=<group>\fP\fP" 1651Sets the group of the fd to <group> with the 1652\f(CWfchown()\fP 1653system call after opening 1654or connecting the channel\&. 1655This is useful only on file system entries\&. 1656.IP "\fB\f(CWmode=<mode>\fP\fP" 1657Sets the <mode> [mode_t] (permissions) of the stream\&. 1658If the address is member of the NAMED option group and 1659uses the 1660\f(CWopen()\fP 1661or 1662\f(CWcreat()\fP 1663call, the mode is applied with these\&. 1664If 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