1COMMENT(source: socat.yo) 2mailto(socat@dest-unreach.org) 3 4def(unix)(0)(UN*X) 5def(unixdomain)(0)(UNIX domain) 6def(socat)(0)(bf(socat)) 7def(Socat)(0)(bf(Socat)) 8def(filan)(0)(bf(filan)) 9def(Filan)(0)(bf(Filan)) 10def(procan)(0)(bf(procan)) 11def(Procan)(0)(bf(Procan)) 12 13manpage(socat)(1)()()() 14 15whenhtml( 16label(CONTENTS) 17manpagesection(CONTENTS) 18link(NAME)(NAME)nl() 19link(SYNOPSIS)(SYNOPSIS)nl() 20link(DESCRIPTION)(DESCRIPTION)nl() 21link(OPTIONS)(OPTIONS)nl() 22link(ADDRESS SPECIFICATIONS)(ADDRESS_SPECIFICATIONS)nl() 23link(ADDRESS TYPES)(ADDRESS_TYPES)nl() 24link(ADDRESS OPTIONS)(ADDRESS_OPTIONS)nl() 25link(DATA VALUES)(VALUES)nl() 26link(EXAMPLES)(EXAMPLES)nl() 27link(DIAGNOSTICS)(DIAGNOSTICS)nl() 28link(FILES)(FILES)nl() 29link(ENVIRONMENT VARIABLES)(ENVIRONMENT_VARIABLES)nl() 30link(CREDITS)(CREDITS)nl() 31link(VERSION)(VERSION)nl() 32link(BUGS)(BUGS)nl() 33link(SEE ALSO)(SEEALSO)nl() 34) 35 36label(NAME) 37manpagename(socat) (Multipurpose relay (SOcket CAT)) 38 39label(SYNOPSIS) 40manpagesynopsis() 41tt(socat [options] <address> <address>)nl() 42tt(socat -V)nl() 43tt(socat -h[h[h]] | -?[?[?]])nl() 44tt(filan)nl() 45tt(procan) 46 47label(DESCRIPTION) 48manpagedescription() 49 50Socat() is a command line based utility that establishes two bidirectional byte 51streams and transfers data between them. Because the streams can be constructed 52from a large set of different types of data sinks and sources 53(see link(address types)(ADDRESS_TYPES)), and because lots of 54link(address options)(ADDRESS_OPTIONS) may be applied to the streams, socat can 55be used for many different purposes. 56 57Filan() is a utility that prints information about its active file 58descriptors to stdout. It has been written for debugging socat(), but might be 59useful for other purposes too. Use the -h option to find more infos. 60 61Procan() is a utility that prints information about process parameters to 62stdout. It has been written to better understand 63some UNIX process properties and for debugging socat(), but might be 64useful for other purposes too. 65 66The life cycle of a socat() instance typically consists of four phases. 67 68In the em(init) phase, the command line options are parsed and logging is 69initialized. 70 71During the em(open) phase, socat() opens the first address and afterwards the 72second address. These steps are usually blocking; thus, especially for complex address types like socks, 73connection requests or authentication dialogs must be completed before the next 74step is started. 75 76In the em(transfer) phase, socat() watches both streams' read and write file 77descriptors via code(select()), and, when data is available on one side em(and) 78can be written to the other side, socat reads it, performs newline 79character conversions if required, and writes the data to the write file 80descriptor of the other stream, then continues waiting for more data in both 81directions. 82 83When one of the streams effectively reaches EOF, the em(closing) phase 84begins. Socat() transfers the EOF condition to the other stream, 85i.e. tries to shutdown only its write stream, giving it a chance to 86terminate gracefully. For a defined time socat() continues to transfer data in 87the other direction, but then closes all remaining channels and terminates. 88 89 90label(OPTIONS) 91manpageoptions() 92 93Socat() provides some command line options that modify the behaviour of the 94program. They have nothing to do with so called 95link(address options)(ADDRESS_OPTIONS) that are used as parts of link(address specifications)(ADDRESS_SPECIFICATIONS). 96 97startdit() 98dit(bf(tt(-V))) 99 Print version and available feature information to stdout, and exit. 100dit(bf(tt(-h | -?))) 101 Print a help text to stdout describing command line options and available address 102 types, and exit. 103dit(bf(tt(-hh | -??))) 104 Like -h, plus a list of the short names of all available address options. Some options are 105 platform dependend, so this output is helpful for checking the particular 106 implementation. 107dit(bf(tt(-hhh | -???))) 108 Like -hh, plus a list of all available address option names. 109label(option_d)dit(bf(tt(-d))) 110 Without this option, only fatal and error messages are generated; applying 111 this option also prints warning messages. See link(DIAGNOSTICS)(DIAGNOSTICS) 112 for more information. 113label(option_d_d)dit(bf(tt(-d -d))) Prints fatal, error, warning, and notice messages. 114dit(bf(tt(-d -d -d))) Prints fatal, error, warning, notice, and info messages. 115dit(bf(tt(-d -d -d -d))) Prints fatal, error, warning, notice, info, and debug 116 messages. 117dit(bf(tt(-D))) 118 Logs information about file descriptors before starting the transfer phase. 119dit(bf(tt(-ly[<facility>]))) 120 Writes messages to syslog instead of stderr; severity as defined with -d 121 option. With optional link(<facility>)(TYPE_FACILITY), the syslog type can 122 be selected, default is "daemon". Third party libraries might not obey this 123 option. 124dit(bf(tt(-lf))tt( <logfile>)) 125 Writes messages to <logfile> [link(filename)(TYPE_FILENAME)] instead of 126 stderr. Some third party libraries, in particular libwrap, might not obey 127 this option. 128dit(bf(tt(-ls))) 129 Writes messages to stderr (this is the default). Some third party libraries 130 might not obey this option, in particular libwrap appears to only log to 131 syslog. 132label(option_lp)dit(bf(tt(-lp))tt(<progname>)) 133 Overrides the program name printed in error messages and used for 134 constructing environment variable names. 135dit(bf(tt(-lu))) 136 Extends the timestamp of error messages to microsecond resolution. Does not 137 work when logging to syslog. 138label(option_lm)dit(bf(tt(-lm[<facility>]))) 139 Mixed log mode. During startup messages are printed to stderr; when socat() 140 starts the transfer phase loop or daemon mode (i.e. after opening all 141 streams and before starting data transfer, or, with listening sockets with 142 fork option, before the first accept call), it switches logging to syslog. 143 With optional link(<facility>)(TYPE_FACILITY), the syslog type can be 144 selected, default is "daemon". 145label(option_lh)dit(bf(tt(-lh))) 146 Adds hostname to log messages. Uses the value from environment variable 147 HOSTNAME or the value retrieved with tt(uname()) if HOSTNAME is not set. 148dit(bf(tt(-v))) 149 Writes the transferred data not only to their target streams, but also to 150 stderr. The output format is text with some conversions for readability, and 151 prefixed with "> " or "< " indicating flow directions. 152dit(bf(tt(-x))) 153 Writes the transferred data not only to their target streams, but also to 154 stderr. The output format is hexadecimal, prefixed with "> " or "< " 155 indicating flow directions. Can be combined with code(-v). 156dit(bf(tt(-r <file>))) 157 Dumps the raw (binary) data flowing from left to right address to the given 158 file. 159dit(bf(tt(-R <file>))) 160 Dumps the raw (binary) data flowing from right to left address to the given 161 file. 162label(option_b)dit(bf(tt(-b))tt(<size>)) 163 Sets the data transfer block <size> [link(size_t)(TYPE_SIZE_T)]. 164 At most <size> bytes are transferred per step. Default is 8192 bytes. 165label(option_s)dit(bf(tt(-s))) 166 By default, socat() terminates when an error occurred to prevent the process 167 from running when some option could not be applied. With this 168 option, socat() is sloppy with errors and tries to continue. Even with this 169 option, socat will exit on fatals, and will abort connection attempts when 170 security checks failed. 171label(option_t)dit(bf(tt(-t))tt(<timeout>)) 172 When one channel has reached EOF, the write part of the other channel is shut 173 down. Then, socat() waits <timeout> [link(timeval)(TYPE_TIMEVAL)] seconds 174 before terminating. Default is 0.5 seconds. This timeout only applies to 175 addresses where write and read part can be closed independently. When during 176 the timeout interval the read part gives EOF, socat terminates without 177 awaiting the timeout. 178label(option_T)dit(bf(tt(-T))tt(<timeout>)) 179 Total inactivity timeout: when socat is already in the transfer loop and 180 nothing has happened for <timeout> [link(timeval)(TYPE_TIMEVAL)] seconds 181 (no data arrived, no interrupt occurred...) then it terminates. 182 Useful with protocols like UDP that cannot transfer EOF. 183label(option_u)dit(bf(tt(-u))) 184 Uses unidirectional mode. The first address is only used for reading, and the 185 second address is only used for writing (link(example)(EXAMPLE_option_u)). 186label(option_U)dit(bf(tt(-U))) 187 Uses unidirectional mode in reverse direction. The first address is only 188 used for writing, and the second address is only used for reading. 189label(option_g)dit(bf(tt(-g))) 190 During address option parsing, don't check if the option is considered 191 useful in the given address environment. Use it if you want to force, e.g., 192 appliance of a socket option to a serial device. 193label(option_L)dit(bf(tt(-L))tt(<lockfile>)) 194 If lockfile exists, exits with error. If lockfile does not exist, creates it 195 and continues, unlinks lockfile on exit. 196label(option_W)dit(bf(tt(-W))tt(<lockfile>)) 197 If lockfile exists, waits until it disappears. When lockfile does not exist, 198 creates it and continues, unlinks lockfile on exit. 199label(option_4)dit(bf(tt(-4))) 200 Use IP version 4 in case that the addresses do not implicitly or explicitly 201 specify a version; this is the default. 202label(option_6)dit(bf(tt(-6))) 203 Use IP version 6 in case that the addresses do not implicitly or explicitly 204 specify a version. 205enddit() 206 207 208label(ADDRESS_SPECIFICATIONS) 209manpagesection(ADDRESS SPECIFICATIONS) 210 211With the address command line arguments, the user gives socat() instructions and 212the necessary information for establishing the byte streams. 213 214An address specification usually consists of an address type 215keyword, zero or more required address parameters separated by ':' from the keyword and 216from each 217other, and zero or more address options separated by ','. 218 219The keyword specifies the address type (e.g., TCP4, OPEN, EXEC). For some 220keywords there exist synonyms ('-' for STDIO, TCP for TCP4). Keywords are case 221insensitive. 222For a few special address types, the keyword may be omitted: 223Address specifications starting with a number are assumed to be FD (raw file 224descriptor) addresses; 225if a '/' is found before the first ':' or ',', GOPEN (generic file open) is 226assumed. 227 228The required number and type of address parameters depend on the address 229type. E.g., TCP4 requires a server specification (name or address), and a port 230specification (number or service name). 231 232Zero or more address options may be given with each address. They influence the 233address in some ways. 234Options consist of an option keyword or an option keyword and a value, 235separated by '='. Option keywords are case insensitive. 236For filtering the options that are useful with an address 237type, each option is member of one option group. For 238each address type there is a set of option groups allowed. Only options 239belonging to one of these address groups may be used (except with link(option -g)(option_g)). 240 241label(ADDRESS_DUAL) 242Address specifications following the above schema are also called em(single) 243address specifications. 244Two single addresses can be combined with "!!" to form a em(dual) type 245address for one channel. Here, the first address is used by socat() for reading 246data, and the 247second address for writing data. There is no way to specify an option only once 248for being applied to both single addresses. 249 250Usually, addresses are opened in read/write 251mode. When an address is part of a dual address specification, or when 252link(option -u)(option_u) or link(-U)(option_U) is used, an address might be 253used only for reading or for writing. Considering this is important with some 254address types. 255 256With socat version 1.5.0 and higher, the lexical analysis tries to handle 257quotes and parenthesis meaningfully and allows escaping of special characters. 258If one of the characters ( { [ ' is found, the corresponding closing 259character - ) } ] ' - is looked for; they may also be nested. Within these 260constructs, socats special characters and strings : , !! are not handled 261specially. All those characters and strings can be escaped with \ or within "" 262 263label(ADDRESS_TYPES) 264manpagesection(ADDRESS TYPES) 265 266This section describes the available address types with their keywords, 267parameters, and semantics. 268 269startdit() 270label(ADDRESS_CREAT)dit(bf(tt(CREATE:<filename>))) 271 Opens link(<filename>)(TYPE_FILENAME) with code(creat()) and uses the file 272 descriptor for writing. 273 This address type requires write-only context, because a file opened with 274 code(creat) cannot be read from. nl() 275 Flags like O_LARGEFILE cannot be applied. If you need them use 276 link(OPEN)(ADDRESS_OPEN) with options 277 link(create)(OPTION_O_CREAT),link(create)(OPTION_O_TRUNC). nl() 278 <filename> must be a valid existing or not existing path. 279 If <filename> is a named pipe, code(creat()) might block; 280 if <filename> refers to a socket, this is an error.nl() 281 Option groups: link(FD)(GROUP_FD),link(REG)(GROUP_REG),link(NAMED)(GROUP_NAMED) nl() 282 Useful options: 283 link(mode)(OPTION_MODE), 284 link(user)(OPTION_USER), 285 link(group)(OPTION_GROUP), 286 link(unlink-early)(OPTION_UNLINK_EARLY), 287 link(unlink-late)(OPTION_UNLINK_LATE), 288 link(append)(OPTION_APPEND)nl() 289 See also: link(OPEN)(ADDRESS_OPEN), link(GOPEN)(ADDRESS_GOPEN) 290label(ADDRESS_EXEC)dit(bf(tt(EXEC:<command-line>))) 291 Forks a sub process that establishes communication with its parent process 292 and invokes the specified program with code(execvp()). 293 link(<command-line>)(TYPE_COMMAND_LINE) is a simple command 294 with arguments separated by single spaces. If the program name 295 contains a '/', the part after the last '/' is taken as ARGV[0]. If the 296 program name is a relative 297 path, the code(execvp()) semantics for finding the program via 298 code($PATH) 299 apply. After successful program start, socat() writes data to stdin of the 300 process and reads from its stdout using a unixdomain() socket generated by 301 code(socketpair()) per default. (link(example)(EXAMPLE_ADDRESS_EXEC)) nl() 302 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(EXEC)(GROUP_EXEC),link(FORK)(GROUP_FORK),link(TERMIOS)(GROUP_TERMIOS) nl() 303 Useful options: 304 link(path)(OPTION_PATH), 305 link(fdin)(OPTION_FDIN), 306 link(fdout)(OPTION_FDOUT), 307 link(chroot)(OPTION_CHROOT), 308 link(su)(OPTION_SUBSTUSER), 309 link(su-d)(OPTION_SUBSTUSER_DELAYED), 310 link(nofork)(OPTION_NOFORK), 311 link(pty)(OPTION_PTY), 312 link(stderr)(OPTION_STDERR), 313 link(ctty)(OPTION_CTTY), 314 link(setsid)(OPTION_SETSID), 315 link(pipes)(OPTION_PIPES), 316 link(login)(OPTION_LOGIN), 317 link(sigint)(OPTION_SIGINT), 318 link(sigquit)(OPTION_SIGQUIT)nl() 319 See also: link(SYSTEM)(ADDRESS_SYSTEM) 320label(ADDRESS_FD)dit(bf(tt(FD:<fdnum>))) 321 Uses the file descriptor link(<fdnum>)(TYPE_FDNUM). It must already exist as 322 valid unix() file descriptor.nl() 323 Option groups: link(FD)(GROUP_FD) (link(TERMIOS)(GROUP_TERMIOS),link(REG)(GROUP_REG),link(SOCKET)(GROUP_SOCKET)) nl() 324 See also: 325 link(STDIO)(ADDRESS_STDIO), 326 link(STDIN)(ADDRESS_STDIN), 327 link(STDOUT)(ADDRESS_STDOUT), 328 link(STDERR)(ADDRESS_STDERR) 329label(ADDRESS_GOPEN)dit(bf(tt(GOPEN:<filename>))) 330 (Generic open) This address type tries to handle any file system entry 331 except directories usefully. link(<filename>)(TYPE_FILENAME) may be a 332 relative or absolute path. If it already exists, its type is checked. 333 In case of a unixdomain() socket, socat() connects; if connecting fails, 334 socat() assumes a datagram socket and uses code(sendto()) calls. 335 If the entry is not a socket, socat() opens it applying the code(O_APPEND) 336 flag. 337 If it does not exist, it is opened with flag 338 code(O_CREAT) as a regular file (link(example)(EXAMPLE_ADDRESS_GOPEN)).nl() 339 Option groups: link(FD)(GROUP_FD),link(REG)(GROUP_REG),link(SOCKET)(GROUP_SOCKET),link(NAMED)(GROUP_NAMED),link(OPEN)(GROUP_OPEN) nl() 340 See also: 341 link(OPEN)(ADDRESS_OPEN), 342 link(CREATE)(ADDRESS_CREAT), 343 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT) 344 345label(ADDRESS_IP_SENDTO)dit(bf(tt(IP-SENDTO:<host>:<protocol>))) 346 Opens a raw IP socket. Depending on host specification or option link(pf)(OPTION_PROTOCOL_FAMILY), IP protocol version 347 4 or 6 is used. It uses link(<protocol>)(TYPE_PROTOCOL) to send packets 348 to <host> [link(IP address)(TYPE_IP_ADDRESS)] and receives packets from 349 host, ignores packets from other hosts. 350 Protocol 255 uses the raw socket with the IP header being part of the 351 data.nl() 352 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6) nl() 353 Useful options: 354 link(pf)(OPTION_PROTOCOL_FAMILY), 355 link(ttl)(OPTION_TTL) nl() 356 See also: 357 link(IP4-SENDTO)(ADDRESS_IP4_SENDTO), 358 link(IP6-SENDTO)(ADDRESS_IP6_SENDTO), 359 link(IP-RECVFROM)(ADDRESS_IP_RECVFROM), 360 link(IP-RECV)(ADDRESS_IP_RECV), 361 link(UDP-SENDTO)(ADDRESS_UDP_SENDTO), 362 link(UNIX-SENDTO)(ADDRESS_UNIX_SENDTO) 363label(ADDRESS_INTERFACE)dit(bf(tt(INTERFACE:<interface>))) 364 Communicates with a network connected on an interface using raw packets 365 including link level data. link(<interface>)(TYPE_INTERFACE) is the name of 366 the network interface. Currently only available on Linux. 367 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET) nl() 368 Useful options: 369 link(pf)(OPTION_PROTOCOL_FAMILY), 370 link(type)(OPTION_SO_TYPE)nl() 371 See also: link(ip-recv)(ADDRESS_IP_RECV) 372label(ADDRESS_IP4_SENDTO)dit(bf(tt(IP4-SENDTO:<host>:<protocol>))) 373 Like link(IP-SENDTO)(ADDRESS_IP_SENDTO), but always uses IPv4.nl() 374 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4) nl() 375label(ADDRESS_IP6_SENDTO)dit(bf(tt(IP6-SENDTO:<host>:<protocol>))) 376 Like link(IP-SENDTO)(ADDRESS_IP_SENDTO), but always uses IPv6.nl() 377 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6) nl() 378 379label(ADDRESS_IP_DATAGRAM)dit(bf(tt(IP-DATAGRAM:<address>:<protocol>))) 380 Sends outgoing data to the specified address which may in particular be a 381 broadcast or multicast address. Packets arriving on the local socket are 382 checked if their source addresses match 383 link(RANGE)(OPTION_RANGE) or link(TCPWRAP)(OPTION_TCPWRAPPERS) 384 options. This address type can for example be used for implementing 385 symmetric or asymmetric broadcast or multicast communications.nl() 386 Option groups: link(FD)(GROUP_FD), link(SOCKET)(GROUP_SOCKET), 387 link(IP4)(GROUP_IP4), link(IP6)(GROUP_IP6), link(RANGE)(GROUP_RANGE) nl() 388 Useful options: 389 link(bind)(OPTION_BIND), 390 link(range)(OPTION_RANGE), 391 link(tcpwrap)(OPTION_TCPWRAPPERS), 392 link(broadcast)(OPTION_SO_BROADCAST), 393 link(ip-multicast-loop)(OPTION_IP_MULTICAST_LOOP), 394 link(ip-multicast-ttl)(OPTION_IP_MULTICAST_TTL), 395 link(ip-multicast-if)(OPTION_IP_MULTICAST_IF), 396 link(ip-add-membership)(OPTION_IP_ADD_MEMBERSHIP), 397 link(ip-add-source-membership)(OPTION_IP_ADD_SOURCE_MEMBERSHIP), 398 link(ttl)(OPTION_TTL), 399 link(tos)(OPTION_TOS), 400 link(pf)(OPTION_PROTOCOL_FAMILY)nl() 401 See also: 402 link(IP4-DATAGRAM)(ADDRESS_IP4_DATAGRAM), 403 link(IP6-DATAGRAM)(ADDRESS_IP6_DATAGRAM), 404 link(IP-SENDTO)(ADDRESS_IP_SENDTO), 405 link(IP-RECVFROM)(ADDRESS_IP_RECVFROM), 406 link(IP-RECV)(ADDRESS_IP_RECV), 407 link(UDP-DATAGRAM)(ADDRESS_UDP_DATAGRAM) 408label(ADDRESS_IP4_DATAGRAM)dit(bf(tt(IP4-DATAGRAM:<host>:<protocol>))) 409 Like link(IP-DATAGRAM)(ADDRESS_IP_DATAGRAM), but always uses IPv4. 410 (link(example)(EXAMPLE_ADDRESS_IP4_BROADCAST_CLIENT))nl() 411 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(RANGE)(GROUP_RANGE) nl() 412label(ADDRESS_IP6_DATAGRAM)dit(bf(tt(IP6-DATAGRAM:<host>:<protocol>))) 413 Like link(IP-DATAGRAM)(ADDRESS_IP_DATAGRAM), but always uses IPv6. Please 414 note that IPv6 does not know broadcasts.nl() 415 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE) nl() 416 417label(ADDRESS_IP_RECVFROM)dit(bf(tt(IP-RECVFROM:<protocol>))) 418 Opens a raw IP socket of link(<protocol>)(TYPE_PROTOCOL). Depending on option link(pf)(OPTION_PROTOCOL_FAMILY), IP protocol version 419 4 or 6 is used. It receives one packet from an unspecified peer and may send one or more answer packets to that peer. 420 This mode is particularly useful with fork option where each arriving packet - from arbitrary peers - is handled by its own sub process. 421 This allows a behaviour similar to typical UDP based servers like ntpd or 422 named.nl() 423 Please note that the reply packets might be fetched as incoming traffic when 424 sender and receiver IP address are identical because there is no port number 425 to distinguish the sockets.nl() 426 This address works well with IP-SENDTO address peers (see above). 427 Protocol 255 uses the raw socket with the IP header being part of the 428 data.nl() 429 See the link(note about RECVFROM addresses)(NOTE_RECVFROM).nl() 430 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE) nl() 431 Useful options: 432 link(pf)(OPTION_PROTOCOL_FAMILY), 433 link(fork)(OPTION_FORK), 434 link(range)(OPTION_RANGE), 435 link(ttl)(OPTION_TTL), 436 link(broadcast)(OPTION_SO_BROADCAST)nl() 437 See also: 438 link(IP4-RECVFROM)(ADDRESS_IP4_RECVFROM), 439 link(IP6-RECVFROM)(ADDRESS_IP6_RECVFROM), 440 link(IP-SENDTO)(ADDRESS_IP_SENDTO), 441 link(IP-RECV)(ADDRESS_IP_RECV), 442 link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM), 443 link(UNIX-RECVFROM)(ADDRESS_UNIX_RECVFROM) 444label(ADDRESS_IP4_RECVFROM)dit(bf(tt(IP4-RECVFROM:<protocol>))) 445 Like link(IP-RECVFROM)(ADDRESS_IP_RECVFROM), but always uses IPv4.nl() 446 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE) nl() 447label(ADDRESS_IP6_RECVFROM)dit(bf(tt(IP6-RECVFROM:<protocol>))) 448 Like link(IP-RECVFROM)(ADDRESS_IP_RECVFROM), but always uses IPv6.nl() 449 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE) nl() 450 451label(ADDRESS_IP_RECV)dit(bf(tt(IP-RECV:<protocol>))) 452 Opens a raw IP socket of link(<protocol>)(TYPE_PROTOCOL). Depending on option link(pf)(OPTION_PROTOCOL_FAMILY), IP protocol version 453 4 or 6 is used. It receives packets from multiple unspecified peers and merges the data. 454 No replies are possible. 455 It can be, e.g., addressed by socat IP-SENDTO address peers. 456 Protocol 255 uses the raw socket with the IP header being part of the 457 data.nl() 458 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE) nl() 459 Useful options: 460 link(pf)(OPTION_PROTOCOL_FAMILY), 461 link(range)(OPTION_RANGE)nl() 462 See also: 463 link(IP4-RECV)(ADDRESS_IP4_RECV), 464 link(IP6-RECV)(ADDRESS_IP6_RECV), 465 link(IP-SENDTO)(ADDRESS_IP_SENDTO), 466 link(IP-RECVFROM)(ADDRESS_IP_RECVFROM), 467 link(UDP-RECV)(ADDRESS_UDP_RECV), 468 link(UNIX-RECV)(ADDRESS_UNIX_RECV) 469label(ADDRESS_IP4_RECV)dit(bf(tt(IP4-RECV:<protocol>))) 470 Like link(IP-RECV)(ADDRESS_IP_RECV), but always uses IPv4.nl() 471 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(RANGE)(GROUP_RANGE) nl() 472label(ADDRESS_IP6_RECV)dit(bf(tt(IP6-RECV:<protocol>))) 473 Like link(IP-RECV)(ADDRESS_IP_RECV), but always uses IPv6.nl() 474 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE) nl() 475 476label(ADDRESS_OPEN)dit(bf(tt(OPEN:<filename>))) 477 Opens link(<filename>)(TYPE_FILENAME) using the code(open()) system call 478 (link(example)(EXAMPLE_ADDRESS_OPEN)). 479 This operation fails on unixdomain() sockets. nl() 480 Note: This address type is rarely useful in bidirectional mode.nl() 481 Option groups: link(FD)(GROUP_FD),link(REG)(GROUP_REG),link(NAMED)(GROUP_NAMED),link(OPEN)(GROUP_OPEN) nl() 482 Useful options: 483 link(creat)(OPTION_O_CREAT), 484 link(excl)(OPTION_EXCL), 485 link(noatime)(OPTION_O_NOATIME), 486 link(nofollow)(OPTION_NOFOLLOW), 487 link(append)(OPTION_APPEND), 488 link(rdonly)(OPTION_RDONLY), 489 link(wronly)(OPTION_WRONLY), 490 link(lock)(OPTION_LOCK), 491 link(readbytes)(OPTION_READBYTES), 492 link(ignoreeof)(OPTION_IGNOREEOF)nl() 493 See also: 494 link(CREATE)(ADDRESS_CREAT), 495 link(GOPEN)(ADDRESS_GOPEN), 496 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT) 497 498label(ADDRESS_OPENSSL_CONNECT)dit(bf(tt(OPENSSL:<host>:<port>))) 499 Tries to establish a SSL connection to <port> [link(TCP 500 service)(TYPE_TCP_SERVICE)] on 501 <host> [link(IP address)(TYPE_IP_ADDRESS)] using TCP/IP version 4 or 6 502 depending on address specification, name resolution, or option 503 link(pf)(OPTION_PROTOCOL_FAMILY).nl() 504 NOTE: Up to version 1.7.2.4 505 the server certificate was only checked for validity against the system 506 certificate store or link(cafile)(OPTION_OPENSSL_CAFILE) or 507 link(capath)(OPTION_OPENSSL_CAPATH), 508 but not for match with the server's name or its IP address. 509 Since version 1.7.3.0 socat checks the peer certificate for match with the 510 <host> parameter or the value of the 511 link(openssl-commonname)(OPTION_OPENSSL_COMMONNAME) option. 512 Socat tries to match it against the certificates subject commonName, 513 and the certificates extension subjectAltName DNS names. Wildcards in the 514 certificate are supported.nl() 515 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(OPENSSL)(GROUP_OPENSSL),link(RETRY)(GROUP_RETRY) nl() 516 Useful options: 517 link(min-proto-version)(OPTION_OPENSSL_MIN_PROTO_VERSION), 518 link(cipher)(OPTION_OPENSSL_CIPHERLIST), 519 link(verify)(OPTION_OPENSSL_VERIFY), 520 link(commonname)(OPTION_OPENSSL_COMMONNAME), 521 link(cafile)(OPTION_OPENSSL_CAFILE), 522 link(capath)(OPTION_OPENSSL_CAPATH), 523 link(certificate)(OPTION_OPENSSL_CERTIFICATE), 524 link(key)(OPTION_OPENSSL_KEY), 525 link(compress)(OPTION_OPENSSL_COMPRESS), 526 link(bind)(OPTION_BIND), 527 link(pf)(OPTION_PROTOCOL_FAMILY), 528 link(connect-timeout)(OPTION_CONNECT_TIMEOUT), 529 link(sourceport)(OPTION_SOURCEPORT), 530 link(retry)(OPTION_RETRY)nl() 531 See also: 532 link(OPENSSL-LISTEN)(ADDRESS_OPENSSL_LISTEN), 533 link(TCP)(ADDRESS_TCP_CONNECT) 534 535label(ADDRESS_OPENSSL_LISTEN)dit(bf(tt(OPENSSL-LISTEN:<port>))) 536 Listens on tcp <port> [link(TCP service)(TYPE_TCP_SERVICE)]. 537 The IP version is 4 or the one specified with 538 link(pf)(OPTION_PROTOCOL_FAMILY). When a 539 connection is accepted, this address behaves as SSL server.nl() 540 Note: You probably want to use the link(certificate)(OPTION_OPENSSL_CERTIFICATE) option with this address.nl() 541 NOTE: The client certificate is only checked for validity against 542 link(cafile)(OPTION_OPENSSL_CAFILE) or link(capath)(OPTION_OPENSSL_CAPATH), 543 but not for match with the client's name or its IP address!nl() 544 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(LISTEN)(GROUP_LISTEN),link(OPENSSL)(GROUP_OPENSSL),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(RETRY)(GROUP_RETRY) nl() 545 Useful options: 546 link(pf)(OPTION_PROTOCOL_FAMILY), 547 link(min-proto-version)(OPTION_OPENSSL_MIN_PROTO_VERSION), 548 link(cipher)(OPTION_OPENSSL_CIPHERLIST), 549 link(verify)(OPTION_OPENSSL_VERIFY), 550 link(commonname)(OPTION_OPENSSL_COMMONNAME), 551 link(cafile)(OPTION_OPENSSL_CAFILE), 552 link(capath)(OPTION_OPENSSL_CAPATH), 553 link(certificate)(OPTION_OPENSSL_CERTIFICATE), 554 link(key)(OPTION_OPENSSL_KEY), 555 link(compress)(OPTION_OPENSSL_COMPRESS), 556 link(fork)(OPTION_FORK), 557 link(bind)(OPTION_BIND), 558 link(range)(OPTION_RANGE), 559 link(tcpwrap)(OPTION_TCPWRAPPERS), 560 link(su)(OPTION_SUBSTUSER), 561 link(reuseaddr)(OPTION_REUSEADDR), 562 link(retry)(OPTION_RETRY)nl() 563 See also: 564 link(OPENSSL)(ADDRESS_OPENSSL_CONNECT), 565 link(TCP-LISTEN)(ADDRESS_TCP_LISTEN) 566 567label(ADDRESS_OPENSSL_DTLS_CLIENT)dit(bf(tt(OPENSSL-DTLS-CLIENT:<host>:<port>))) 568 Tries to establish a DTLS connection to <port> [link(UDP 569 service)(TYPE_UDP_SERVICE)] on 570 <host> [link(IP address)(TYPE_IP_ADDRESS)] using UDP/IP version 4 or 6 571 depending on address specification, name resolution, or option 572 link(pf)(OPTION_PROTOCOL_FAMILY).nl() 573 Socat() checks the peer certificates subjectAltName or commonName against the addresses 574 option link(openssl-commonname)(OPTION_OPENSSL_COMMONNAME) or the host name. 575 Wildcards in the certificate are supported.nl() 576 Use socat() option link(-b)(option_b) to make datagrams small enough to fit with overhead 577 on the network. Use option link(-T)(option_T) to prevent indefinite hanging when peer went down quietly.nl() 578 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),COMMENT(link(UDP)(GROUP_UDP),)link(OPENSSL)(GROUP_OPENSSL),link(RETRY)(GROUP_RETRY) nl() 579 Useful options: 580 link(min-proto-version)(OPTION_OPENSSL_MIN_PROTO_VERSION), 581 link(cipher)(OPTION_OPENSSL_CIPHERLIST), 582 link(verify)(OPTION_OPENSSL_VERIFY), 583 link(commonname)(OPTION_OPENSSL_COMMONNAME), 584 link(cafile)(OPTION_OPENSSL_CAFILE), 585 link(capath)(OPTION_OPENSSL_CAPATH), 586 link(certificate)(OPTION_OPENSSL_CERTIFICATE), 587 link(key)(OPTION_OPENSSL_KEY), 588 link(compress)(OPTION_OPENSSL_COMPRESS), 589 link(bind)(OPTION_BIND), 590 link(pf)(OPTION_PROTOCOL_FAMILY), 591 link(sourceport)(OPTION_SOURCEPORT), 592 link(retry)(OPTION_RETRY)nl() 593 See also: 594 link(OPENSSL-DTLS-SERVER)(ADDRESS_OPENSSL_DTLS_SERVER), 595 link(OPENSSL-CONNECT)(ADDRESS_OPENSSL_CONNECT), 596 link(UDP-CONNECT)(ADDRESS_UDP_CONNECT) 597 598label(ADDRESS_OPENSSL_DTLS_SERVER)dit(bf(tt(OPENSSL-DTLS-SERVER:<port>))) 599 Listens on UDP <port> [link(UDP service)(TYPE_UDP_SERVICE)]. 600 The IP version is 4 or the one specified with 601 link(pf)(OPTION_PROTOCOL_FAMILY). When a 602 connection is accepted, this address behaves as DTLS server.nl() 603 Note: You probably want to use the link(certificate)(OPTION_OPENSSL_CERTIFICATE) option with this address.nl() 604 NOTE: The client certificate is only checked for validity against 605 link(cafile)(OPTION_OPENSSL_CAFILE) or link(capath)(OPTION_OPENSSL_CAPATH), 606 but not for match with the client's name or its IP address! 607 Use socat() option link(-b)(option_b) to make datagrams small enough to fit with overhead on the network. 608 Use option link(-T)(option_T) to prevent indefinite hanging when peer went down quietly.nl() 609 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),COMMENT(link(UDP)(GROUP_UDP),)link(LISTEN)(GROUP_LISTEN),link(OPENSSL)(GROUP_OPENSSL),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(RETRY)(GROUP_RETRY) nl() 610 Useful options: 611 link(pf)(OPTION_PROTOCOL_FAMILY), 612 link(min-proto-version)(OPTION_OPENSSL_MIN_PROTO_VERSION), 613 link(cipher)(OPTION_OPENSSL_CIPHERLIST), 614 link(verify)(OPTION_OPENSSL_VERIFY), 615 link(commonname)(OPTION_OPENSSL_COMMONNAME), 616 link(cafile)(OPTION_OPENSSL_CAFILE), 617 link(capath)(OPTION_OPENSSL_CAPATH), 618 link(certificate)(OPTION_OPENSSL_CERTIFICATE), 619 link(key)(OPTION_OPENSSL_KEY), 620 link(compress)(OPTION_OPENSSL_COMPRESS), 621 link(fork)(OPTION_FORK), 622 link(bind)(OPTION_BIND), 623 link(range)(OPTION_RANGE), 624 link(tcpwrap)(OPTION_TCPWRAPPERS), 625 link(su)(OPTION_SUBSTUSER), 626 link(reuseaddr)(OPTION_REUSEADDR), 627 link(retry)(OPTION_RETRY)nl() 628 See also: 629 link(OPENSSL-DTLS-CLIENT)(ADDRESS_OPENSSL_DTLS_CLIENT), 630 link(OPENSSL-LISTEN)(ADDRESS_OPENSSL_LISTEN), 631 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN) 632 633label(ADDRESS_NAMED_PIPE)dit(bf(tt(PIPE:<filename>))) 634 If link(<filename>)(TYPE_FILENAME) already exists, it is opened. 635 If it does not exist, a named pipe is created and opened. Beginning with 636 socat version 1.4.3, the named pipe is removed when the address is closed 637 (but see option link(unlink-close)(OPTION_UNLINK_CLOSE)nl() 638 Note: When a pipe is used for both reading and writing, it works 639 as echo service.nl() 640 Note: When a pipe is used for both reading and writing, and socat tries 641 to write more bytes than the pipe can buffer (Linux 2.4: 2048 bytes), socat 642 might block. Consider using socat option, e.g., code(-b 2048) nl() 643 Option groups: link(FD)(GROUP_FD),link(NAMED)(GROUP_NAMED),link(OPEN)(GROUP_OPEN) nl() 644 Useful options: 645 link(rdonly)(OPTION_RDONLY), 646 link(nonblock)(OPTION_NONBLOCK), 647 link(group)(OPTION_GROUP), 648 link(user)(OPTION_USER), 649 link(mode)(OPTION_MODE), 650 link(unlink-early)(OPTION_UNLINK_EARLY)nl() 651 See also: link(unnamed pipe)(ADDRESS_UNNAMED_PIPE) 652label(ADDRESS_UNNAMED_PIPE)dit(bf(tt(PIPE))) 653 Creates an unnamed pipe and uses it for reading and writing. It works as an 654 echo, because everything written 655 to it appeares immediately as read data.nl() 656 Note: When socat tries to write more bytes than the pipe can queue (Linux 657 2.4: 2048 bytes), socat might block. Consider, e.g., using 658 option code(-b 2048) nl() 659 Option groups: link(FD)(GROUP_FD) nl() 660 See also: link(named pipe)(ADDRESS_NAMED_PIPE) 661label(ADDRESS_PROXY_CONNECT)dit(bf(tt(PROXY:<proxy>:<hostname>:<port>))) 662 Connects to an HTTP proxy server on port 8080 using TCP/IP version 4 or 6 663 depending on address specification, name resolution, or option 664 link(pf)(OPTION_PROTOCOL_FAMILY), and sends a CONNECT 665 request for hostname:port. If the proxy grants access and succeeds to 666 connect to the target, data transfer between socat and the target can 667 start. Note that the traffic need not be HTTP but can be an arbitrary 668 protocol. nl() 669 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(HTTP)(GROUP_HTTP),link(RETRY)(GROUP_RETRY) nl() 670 Useful options: 671 link(proxyport)(OPTION_PROXYPORT), 672 link(ignorecr)(OPTION_IGNORECR), 673 link(proxyauth)(OPTION_PROXY_AUTHORIZATION), 674 link(resolve)(OPTION_PROXY_RESOLVE), 675 link(crnl)(OPTION_CRNL), 676 link(bind)(OPTION_BIND), 677 link(connect-timeout)(OPTION_CONNECT_TIMEOUT), 678 link(mss)(OPTION_MSS), 679 link(sourceport)(OPTION_SOURCEPORT), 680 link(retry)(OPTION_RETRY) nl() 681 See also: link(SOCKS)(ADDRESS_SOCKS4), link(TCP)(ADDRESS_TCP_CONNECT) 682label(ADDRESS_PTY)dit(bf(tt(PTY))) 683 Generates a pseudo terminal (pty) and uses its master side. Another process 684 may open the pty's slave side using it like a serial line or terminal. 685 (link(example)(EXAMPLE_ADDRESS_PTY)). If 686 both the ptmx and the openpty mechanisms are available, ptmx is used 687 (POSIX).nl() 688 Option groups: link(FD)(GROUP_FD),link(NAMED)(GROUP_NAMED),link(PTY)(GROUP_PTY),link(TERMIOS)(GROUP_TERMIOS) nl() 689 Useful options: 690 link(link)(OPTION_SYMBOLIC_LINK), 691 link(openpty)(OPTION_OPENPTY), 692 link(wait-slave)(OPTION_PTY_WAIT_SLAVE), 693 link(mode)(OPTION_MODE), 694 link(user)(OPTION_USER), 695 link(group)(OPTION_GROUP)nl() 696 See also: 697 link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN), 698 link(PIPE)(ADDRESS_NAMED_PIPE), 699 link(EXEC)(ADDRESS_EXEC), link(SYSTEM)(ADDRESS_SYSTEM) 700label(ADDRESS_READLINE)dit(bf(tt(READLINE))) 701 Uses GNU readline and history on stdio to allow editing and reusing input 702 lines (link(example)(EXAMPLE_ADDRESS_READLINE)). This requires the GNU readline and 703 history libraries. Note that stdio should be a (pseudo) terminal device, 704 otherwise readline does not seem to work.nl() 705 Option groups: link(FD)(GROUP_FD),link(READLINE)(GROUP_READLINE),link(TERMIOS)(GROUP_TERMIOS) nl() 706 Useful options: 707 link(history)(OPTION_HISTORY), 708 link(noecho)(OPTION_NOECHO)nl() 709 See also: 710 link(STDIO)(ADDRESS_STDIO) 711label(ADDRESS_SCTP_CONNECT)dit(bf(tt(SCTP-CONNECT:<host>:<port>))) 712 Establishes an SCTP stream connection to the specified <host> [link(IP 713 address)(TYPE_IP_ADDRESS)] and <port> [link(TCP service)(TYPE_TCP_SERVICE)] 714 using IP version 4 or 6 depending on address specification, name 715 resolution, or option link(pf)(OPTION_PROTOCOL_FAMILY).nl() 716 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(SCTP)(GROUP_SCTP),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY) nl() 717 Useful options: 718 link(bind)(OPTION_BIND), 719 link(pf)(OPTION_PROTOCOL_FAMILY), 720 link(connect-timeout)(OPTION_CONNECT_TIMEOUT), 721 link(tos)(OPTION_TOS), 722 link(mtudiscover)(OPTION_MTUDISCOVER), 723 link(sctp-maxseg)(OPTION_SCTP_MAXSEG), 724 link(sctp-nodelay)(OPTION_SCTP_NODELAY), 725 link(nonblock)(OPTION_NONBLOCK), 726 link(sourceport)(OPTION_SOURCEPORT), 727 link(retry)(OPTION_RETRY), 728 link(readbytes)(OPTION_READBYTES)nl() 729 See also: 730 link(SCTP4-CONNECT)(ADDRESS_SCTP4_CONNECT), 731 link(SCTP6-CONNECT)(ADDRESS_SCTP6_CONNECT), 732 link(SCTP-LISTEN)(ADDRESS_SCTP_LISTEN), 733 link(TCP-CONNECT)(ADDRESS_TCP_CONNECT) 734label(ADDRESS_SCTP4_CONNECT)dit(bf(tt(SCTP4-CONNECT:<host>:<port>))) 735 Like link(SCTP-CONNECT)(ADDRESS_SCTP_CONNECT), but only supports IPv4 protocol.nl() 736 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(SCTP)(GROUP_SCTP),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY) nl() 737label(ADDRESS_SCTP6_CONNECT)dit(bf(tt(SCTP6-CONNECT:<host>:<port>))) 738 Like link(SCTP-CONNECT)(ADDRESS_SCTP_CONNECT), but only supports IPv6 protocol.nl() 739 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(SCTP)(GROUP_SCTP),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY) nl() 740label(ADDRESS_SCTP_LISTEN)dit(bf(tt(SCTP-LISTEN:<port>))) 741 Listens on <port> [link(TCP service)(TYPE_TCP_SERVICE)] and accepts an 742 SCTP connection. The IP version is 4 or the one specified with 743 address option link(pf)(OPTION_PROTOCOL_FAMILY), socat option 744 (link(-4)(option_4), link(-6)(option_6)), or environment variable link(SOCAT_DEFAULT_LISTEN_IP)(ENV_SOCAT_DEFAULT_LISTEN_IP). 745 Note that opening 746 this address usually blocks until a client connects.nl() 747 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(SCTP)(GROUP_SCTP),link(RETRY)(GROUP_RETRY) nl() 748 Useful options: 749 link(crnl)(OPTION_CRNL), 750 link(fork)(OPTION_FORK), 751 link(bind)(OPTION_BIND), 752 link(range)(OPTION_RANGE), 753 link(tcpwrap)(OPTION_TCPWRAPPERS), 754 link(pf)(OPTION_PROTOCOL_FAMILY), 755 link(max-children)(OPTION_MAX_CHILDREN), 756 link(backlog)(OPTION_BACKLOG), 757 link(accept-timeout)(OPTION_ACCEPT_TIMEOUT), 758 link(sctp-maxseg)(OPTION_SCTP_MAXSEG), 759 link(sctp-nodelay)(OPTION_SCTP_NODELAY), 760 link(su)(OPTION_SUBSTUSER), 761 link(reuseaddr)(OPTION_REUSEADDR), 762 link(retry)(OPTION_RETRY), 763 link(cool-write)(OPTION_COOL_WRITE)nl() 764 See also: 765 link(SCTP4-LISTEN)(ADDRESS_SCTP4_LISTEN), 766 link(SCTP6-LISTEN)(ADDRESS_SCTP6_LISTEN), 767 link(TCP-LISTEN)(ADDRESS_TCP_LISTEN), 768 link(SCTP-CONNECT)(ADDRESS_SCTP_CONNECT) 769label(ADDRESS_SCTP4_LISTEN)dit(bf(tt(SCTP4-LISTEN:<port>))) 770 Like link(SCTP-LISTEN)(ADDRESS_SCTP_LISTEN), but only supports IPv4 771 protocol.nl() 772 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP4)(GROUP_IP4),link(SCTP)(GROUP_SCTP),link(RETRY)(GROUP_RETRY) nl() 773label(ADDRESS_SCTP6_LISTEN)dit(bf(tt(SCTP6-LISTEN:<port>))) 774 Like link(SCTP-LISTEN)(ADDRESS_SCTP_LISTEN), but only supports IPv6 775 protocol.nl() 776 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP6)(GROUP_IP6),link(SCTP)(GROUP_SCTP),link(RETRY)(GROUP_RETRY) nl() 777label(ADDRESS_SOCKET_CONNECT)dit(bf(tt(SOCKET-CONNECT:<domain>:<protocol>:<remote-address>))) 778 Creates a stream socket using the first and second given socket parameters 779 and tt(SOCK_STREAM) (see man NOEXPAND(socket(2))) and connects to the remote-address. 780 The two socket parameters have to be specified by link(int)(TYPE_INT) 781 numbers. Consult your OS documentation and include files to find the 782 appropriate values. The remote-address must be the link(data)(TYPE_DATA) 783 representation of a sockaddr structure without sa_family and (BSD) sa_len 784 components.nl() 785 Please note that you can - beyond the options of the specified groups - also 786 use options of higher level protocols when you apply socat option 787 link(-g)(option_g).nl() 788 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY)nl() 789 Useful options: 790 link(bind)(OPTION_BIND), 791 link(setsockopt)(OPTION_SETSOCKOPT), 792 nl() 793 See also: 794 link(TCP)(ADDRESS_TCP_CONNECT), 795 link(UDP-CONNECT)(ADDRESS_UDP_CONNECT), 796 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT), 797 link(SOCKET-LISTEN)(ADDRESS_SOCKET_LISTEN), 798 link(SOCKET-SENDTO)(ADDRESS_SOCKET_SENDTO) 799label(ADDRESS_SOCKET_DATAGRAM)dit(bf(tt(SOCKET-DATAGRAM:<domain>:<type>:<protocol>:<remote-address>))) 800 Creates a datagram socket using the first three given socket parameters (see 801 man NOEXPAND(socket(2))) and sends outgoing data to the remote-address. The three 802 socket parameters have to be specified by link(int)(TYPE_INT) 803 numbers. Consult your OS documentation and include files to find the 804 appropriate values. The remote-address must be the link(data)(TYPE_DATA) 805 representation of a sockaddr structure without sa_family and (BSD) sa_len 806 components.nl() 807 Please note that you can - beyond the options of the specified groups - also 808 use options of higher level protocols when you apply socat option 809 link(-g)(option_g).nl() 810 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(RANGE)(GROUP_RANGE)nl() 811 Useful options: 812 link(bind)(OPTION_BIND), 813 link(range)(OPTION_RANGE), 814 link(setsockopt)(OPTION_SETSOCKOPT), 815 nl() 816 See also: 817 link(UDP-DATAGRAM)(ADDRESS_UDP_DATAGRAM), 818 link(IP-DATAGRAM)(ADDRESS_IP_DATAGRAM), 819 link(SOCKET-SENDTO)(ADDRESS_SOCKET_SENDTO), 820 link(SOCKET-RECV)(ADDRESS_SOCKET_RECV), 821 link(SOCKET-RECVFROM)(ADDRESS_SOCKET_RECVFROM) 822label(ADDRESS_SOCKET_LISTEN)dit(bf(tt(SOCKET-LISTEN:<domain>:<protocol>:<local-address>))) 823 Creates a stream socket using the first and second given socket parameters 824 and tt(SOCK_STREAM) (see man NOEXPAND(socket(2))) and waits for incoming connections 825 on local-address. The two socket parameters have to be specified by 826 link(int)(TYPE_INT) numbers. Consult your OS documentation and include files 827 to find the appropriate values. The local-address must be the 828 link(data)(TYPE_DATA) representation of a sockaddr structure without 829 sa_family and (BSD) sa_len components.nl() 830 Please note that you can - beyond the options of the specified groups - also 831 use options of higher level protocols when you apply socat option 832 link(-g)(option_g).nl() 833 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(RANGE)(GROUP_RANGE),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY)nl() 834 Useful options: 835 link(setsockopt)(OPTION_SETSOCKOPT), 836 link(setsockopt-listen)(OPTION_SETSOCKOPT_LISTEN), 837 nl() 838 See also: 839 link(TCP)(ADDRESS_TCP_LISTEN), 840 link(UDP-CONNECT)(ADDRESS_UDP_LISTEN), 841 link(UNIX-CONNECT)(ADDRESS_UNIX_LISTEN), 842 link(SOCKET-LISTEN)(ADDRESS_SOCKET_CONNECT), 843 link(SOCKET-SENDTO)(ADDRESS_SOCKET_RECVFROM), 844 link(SOCKET-SENDTO)(ADDRESS_SOCKET_RECV) 845label(ADDRESS_SOCKET_RECV)dit(bf(tt(SOCKET-RECV:<domain>:<type>:<protocol>:<local-address>))) 846 Creates a socket using the three given socket parameters (see man NOEXPAND(socket(2))) 847 and binds it to <local-address>. Receives arriving data. The three 848 parameters have to be specified by link(int)(TYPE_INT) numbers. Consult your 849 OS documentation and include files to find the appropriate values. The 850 local-address must be the link(data)(TYPE_DATA) representation of a sockaddr 851 structure without sa_family and (BSD) sa_len components.nl() 852 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(RANGE)(GROUP_RANGE)nl() 853 Useful options: 854 link(range)(OPTION_RANGE), 855 link(setsockopt)(OPTION_SETSOCKOPT), 856 link(setsockopt-listen)(OPTION_SETSOCKOPT_LISTEN) 857 nl() 858 See also: 859 link(UDP-RECV)(ADDRESS_UDP_RECV), 860 link(IP-RECV)(ADDRESS_IP_RECV), 861 link(UNIX-RECV)(ADDRESS_UNIX_RECV), 862 link(SOCKET-DATAGRAM)(ADDRESS_SOCKET_DATAGRAM), 863 link(SOCKET-SENDTO)(ADDRESS_SOCKET_SENDTO), 864 link(SOCKET-RECVFROM)(ADDRESS_SOCKET_RECVFROM) 865label(ADDRESS_SOCKET_RECVFROM)dit(bf(tt(SOCKET-RECVFROM:<domain>:<type>:<protocol>:<local-address>))) 866 Creates a socket using the three given socket parameters (see man NOEXPAND(socket(2))) 867 and binds it to <local-address>. Receives arriving data and sends replies 868 back to the sender. The first three parameters have to be specified as 869 link(int)(TYPE_INT) numbers. Consult your OS documentation and include files 870 to find the appropriate values. The local-address must be the 871 link(data)(TYPE_DATA) representation of a sockaddr structure without 872 sa_family and (BSD) sa_len components.nl() 873 See the link(note about RECVFROM addresses)(NOTE_RECVFROM).nl() 874 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE)nl() 875 Useful options: 876 link(fork)(OPTION_FORK), 877 link(range)(OPTION_RANGE), 878 link(setsockopt)(OPTION_SETSOCKOPT), 879 link(setsockopt-listen)(OPTION_SETSOCKOPT_LISTEN) 880 nl() 881 See also: 882 link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM), 883 link(IP-RECVFROM)(ADDRESS_IP_RECVFROM), 884 link(UNIX-RECVFROM)(ADDRESS_UNIX_RECVFROM), 885 link(SOCKET-DATAGRAM)(ADDRESS_SOCKET_DATAGRAM), 886 link(SOCKET-SENDTO)(ADDRESS_SOCKET_SENDTO), 887 link(SOCKET-RECV)(ADDRESS_SOCKET_RECV) 888label(ADDRESS_SOCKET_SENDTO)dit(bf(tt(SOCKET-SENDTO:<domain>:<type>:<protocol>:<remote-address>))) 889 Creates a socket using the three given socket parameters (see man 890 NOEXPAND(socket(2))). Sends outgoing data to the given address and receives replies. 891 The three parameters have to be specified as link(int)(TYPE_INT) 892 numbers. Consult your OS documentation and include files to find the 893 appropriate values. The remote-address must be the link(data)(TYPE_DATA) 894 representation of a sockaddr structure without sa_family and (BSD) sa_len 895 components.nl() 896 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET)nl() 897 Useful options: 898 link(bind)(OPTION_BIND), 899 link(setsockopt)(OPTION_SETSOCKOPT), 900 link(setsockopt-listen)(OPTION_SETSOCKOPT_LISTEN) 901 nl() 902 See also: 903 link(UDP-SENDTO)(ADDRESS_UDP_SENDTO), 904 link(IP-SENDTO)(ADDRESS_IP_SENDTO), 905 link(UNIX-SENDTO)(ADDRESS_UNIX_SENDTO), 906 link(SOCKET-DATAGRAM)(ADDRESS_SOCKET_DATAGRAM), 907 link(SOCKET-RECV)(ADDRESS_SOCKET_RECV) 908 link(SOCKET-RECVFROM)(ADDRESS_SOCKET_RECVFROM) 909label(ADDRESS_SOCKS4)dit(bf(tt(SOCKS4:<socks-server>:<host>:<port>))) 910 Connects via <socks-server> [link(IP address)(TYPE_IP_ADDRESS)] 911 to <host> [link(IPv4 address)(TYPE_IPV4_ADDRESS)] 912 on <port> [link(TCP service)(TYPE_TCP_SERVICE)], 913 using socks version 4 protocol over IP version 4 or 6 depending on address specification, name resolution, or option 914 link(pf)(OPTION_PROTOCOL_FAMILY) (link(example)(EXAMPLE_ADDRESS_SOCKS4)).nl() 915 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(SOCKS4)(GROUP_SOCKS),link(RETRY)(GROUP_RETRY) nl() 916 Useful options: 917 link(socksuser)(OPTION_SOCKSUSER), 918 link(socksport)(OPTION_SOCKSPORT), 919 link(sourceport)(OPTION_SOURCEPORT), 920 link(pf)(OPTION_PROTOCOL_FAMILY), 921 link(retry)(OPTION_RETRY)nl() 922 See also: 923 link(SOCKS4A)(ADDRESS_SOCKS4A), 924 link(PROXY)(ADDRESS_PROXY_CONNECT), 925 link(TCP)(ADDRESS_TCP_CONNECT) 926label(ADDRESS_SOCKS4A)dit(bf(tt(SOCKS4A:<socks-server>:<host>:<port>))) 927 like link(SOCKS4)(ADDRESS_SOCKS4), but uses socks protocol version 4a, thus 928 leaving host name resolution to the socks server.nl() 929 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(SOCKS4)(GROUP_SOCKS),link(RETRY)(GROUP_RETRY) nl() 930label(ADDRESS_STDERR)dit(bf(tt(STDERR))) 931 Uses file descriptor 2.nl() 932 Option groups: link(FD)(GROUP_FD) (link(TERMIOS)(GROUP_TERMIOS),link(REG)(GROUP_REG),link(SOCKET)(GROUP_SOCKET)) nl() 933 See also: link(FD)(ADDRESS_FD) 934label(ADDRESS_STDIN)dit(bf(tt(STDIN))) 935 Uses file descriptor 0.nl() 936 Option groups: link(FD)(GROUP_FD) (link(TERMIOS)(GROUP_TERMIOS),link(REG)(GROUP_REG),link(SOCKET)(GROUP_SOCKET)) nl() 937 Useful options: 938 link(readbytes)(OPTION_READBYTES)nl() 939 See also: link(FD)(ADDRESS_FD) 940label(ADDRESS_STDIO)dit(bf(tt(STDIO))) 941 Uses file descriptor 0 for reading, and 1 for writing.nl() 942 Option groups: link(FD)(GROUP_FD) (link(TERMIOS)(GROUP_TERMIOS),link(REG)(GROUP_REG),link(SOCKET)(GROUP_SOCKET)) nl() 943 Useful options: 944 link(readbytes)(OPTION_READBYTES)nl() 945 See also: link(FD)(ADDRESS_FD) 946label(ADDRESS_STDOUT)dit(bf(tt(STDOUT))) 947 Uses file descriptor 1.nl() 948 Option groups: link(FD)(GROUP_FD) (link(TERMIOS)(GROUP_TERMIOS),link(REG)(GROUP_REG),link(SOCKET)(GROUP_SOCKET)) nl() 949 See also: link(FD)(ADDRESS_FD) 950label(ADDRESS_SYSTEM)dit(bf(tt(SYSTEM:<shell-command>))) 951 Forks a sub process that establishes communication with its parent process 952 and invokes the specified program with code(system()). Please note that 953 <shell-command> [link(string)(TYPE_STRING)] must 954 not contain ',' or "!!", and that shell meta characters may have to be 955 protected. 956 After successful program start, socat() writes data to stdin of the 957 process and reads from its stdout.nl() 958 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(EXEC)(GROUP_EXEC),link(FORK)(GROUP_FORK),link(TERMIOS)(GROUP_TERMIOS) nl() 959 Useful options: 960 link(path)(OPTION_PATH), 961 link(fdin)(OPTION_FDIN), 962 link(fdout)(OPTION_FDOUT), 963 link(chroot)(OPTION_CHROOT), 964 link(su)(OPTION_SUBSTUSER), 965 link(su-d)(OPTION_SUBSTUSER_DELAYED), 966 link(nofork)(OPTION_NOFORK), 967 link(pty)(OPTION_PTY), 968 link(stderr)(OPTION_STDERR), 969 link(ctty)(OPTION_CTTY), 970 link(setsid)(OPTION_SETSID), 971 link(pipes)(OPTION_PIPES), 972 link(sigint)(OPTION_SIGINT), 973 link(sigquit)(OPTION_SIGQUIT)nl() 974 See also: link(EXEC)(ADDRESS_EXEC) 975label(ADDRESS_TCP_CONNECT)dit(bf(tt(TCP:<host>:<port>))) 976 Connects to <port> [link(TCP service)(TYPE_TCP_SERVICE)] on 977 <host> [link(IP address)(TYPE_IP_ADDRESS)] using TCP/IP version 4 or 6 978 depending on address specification, name resolution, or option 979 link(pf)(OPTION_PROTOCOL_FAMILY).nl() 980 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(RETRY)(GROUP_RETRY) nl() 981 Useful options: 982 link(crnl)(OPTION_CRNL), 983 link(bind)(OPTION_BIND), 984 link(pf)(OPTION_PROTOCOL_FAMILY), 985 link(connect-timeout)(OPTION_CONNECT_TIMEOUT), 986 link(tos)(OPTION_TOS), 987 link(mtudiscover)(OPTION_MTUDISCOVER), 988 link(mss)(OPTION_MSS), 989 link(nodelay)(OPTION_TCP_NODELAY), 990 link(nonblock)(OPTION_NONBLOCK), 991 link(sourceport)(OPTION_SOURCEPORT), 992 link(retry)(OPTION_RETRY), 993 link(readbytes)(OPTION_READBYTES)nl() 994 See also: 995 link(TCP4)(ADDRESS_TCP4_CONNECT), 996 link(TCP6)(ADDRESS_TCP6_CONNECT), 997 link(TCP-LISTEN)(ADDRESS_TCP_LISTEN), 998 link(UDP)(ADDRESS_UDP_CONNECT), 999 link(SCTP-CONNECT)(ADDRESS_SCTP_CONNECT), 1000 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT) 1001label(ADDRESS_TCP4_CONNECT)dit(bf(tt(TCP4:<host>:<port>))) 1002 Like link(TCP)(ADDRESS_TCP_CONNECT), but only supports IPv4 protocol (link(example)(EXAMPLE_ADDRESS_TCP4_CONNECT)).nl() 1003 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(TCP)(GROUP_TCP),link(RETRY)(GROUP_RETRY) nl() 1004label(ADDRESS_TCP6_CONNECT)dit(bf(tt(TCP6:<host>:<port>))) 1005 Like link(TCP)(ADDRESS_TCP_CONNECT), but only supports IPv6 protocol.nl() 1006 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(RETRY)(GROUP_RETRY) nl() 1007label(ADDRESS_TCP_LISTEN)dit(bf(tt(TCP-LISTEN:<port>))) 1008 Listens on <port> [link(TCP service)(TYPE_TCP_SERVICE)] and accepts a 1009 TCP/IP connection. The IP version is 4 or the one specified with 1010 address option link(pf)(OPTION_PROTOCOL_FAMILY), socat option 1011 (link(-4)(option_4), link(-6)(option_6)), or environment variable link(SOCAT_DEFAULT_LISTEN_IP)(ENV_SOCAT_DEFAULT_LISTEN_IP). 1012 Note that opening 1013 this address usually blocks until a client connects.nl() 1014 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(RETRY)(GROUP_RETRY) nl() 1015 Useful options: 1016 link(crnl)(OPTION_CRNL), 1017 link(fork)(OPTION_FORK), 1018 link(bind)(OPTION_BIND), 1019 link(range)(OPTION_RANGE), 1020 link(tcpwrap)(OPTION_TCPWRAPPERS), 1021 link(pf)(OPTION_PROTOCOL_FAMILY), 1022 link(max-children)(OPTION_MAX_CHILDREN), 1023 link(backlog)(OPTION_BACKLOG), 1024 link(accept-timeout)(OPTION_ACCEPT_TIMEOUT), 1025 link(mss)(OPTION_MSS), 1026 link(su)(OPTION_SUBSTUSER), 1027 link(reuseaddr)(OPTION_REUSEADDR), 1028 link(retry)(OPTION_RETRY), 1029 link(cool-write)(OPTION_COOL_WRITE)nl() 1030 See also: 1031 link(TCP4-LISTEN)(ADDRESS_TCP4_LISTEN), 1032 link(TCP6-LISTEN)(ADDRESS_TCP6_LISTEN), 1033 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN), 1034 link(SCTP-LISTEN)(ADDRESS_SCTP_LISTEN), 1035 link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN), 1036 link(OPENSSL-LISTEN)(ADDRESS_OPENSSL_LISTEN), 1037 link(TCP-CONNECT)(ADDRESS_TCP_CONNECT) 1038label(ADDRESS_TCP4_LISTEN)dit(bf(tt(TCP4-LISTEN:<port>))) 1039 Like link(TCP-LISTEN)(ADDRESS_TCP_LISTEN), but only supports IPv4 1040 protocol (link(example)(EXAMPLE_ADDRESS_TCP4_LISTEN)).nl() 1041 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP4)(GROUP_IP4),link(TCP)(GROUP_TCP),link(RETRY)(GROUP_RETRY) nl() 1042label(ADDRESS_TCP6_LISTEN)dit(bf(tt(TCP6-LISTEN:<port>))) 1043 Like link(TCP-LISTEN)(ADDRESS_TCP_LISTEN), but only supports IPv6 1044 protocol.nl() 1045 Additional useful option: 1046 link(ipv6only)(OPTION_IPV6_V6ONLY)nl() 1047 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP6)(GROUP_IP6),link(TCP)(GROUP_TCP),link(RETRY)(GROUP_RETRY) nl() 1048label(ADDRESS_TUN)dit(bf(tt(TUN[:<if-addr>/<bits>]))) 1049 Creates a Linux TUN/TAP device and optionally assignes it the address and 1050 netmask given by the parameters. The resulting network interface is almost 1051 ready for use by other processes; socat serves its "wire side". This address 1052 requires read and write access to the tunnel cloning device, usually 1053 code(/dev/net/tun), as well as permission to set some tt(ioctl()s). 1054 bf(Option iff-up is required to immediately activate the interface!)nl() 1055 Note: If you intend to transfer packets between two Socat "wire sides" you 1056 need a protocol that keeps packet boundaries, e.g.UDP; TCP might work with 1057 option link(nodelay)(OPTION_TCP_NODELAY).nl() 1058 Option groups: link(FD)(GROUP_FD),link(NAMED)(GROUP_NAMED),link(OPEN)(GROUP_OPEN),link(TUN)(GROUP_TUN) nl() 1059 Useful options: 1060 link(iff-up)(OPTION_IFF_UP), 1061 link(tun-device)(OPTION_TUN_DEVICE), 1062 link(tun-name)(OPTION_TUN_NAME), 1063 link(tun-type)(OPTION_TUN_TYPE), 1064 link(iff-no-pi)(OPTION_IFF_NO_PI) nl() 1065 See also: 1066 link(ip-recv)(ADDRESS_IP_RECV) 1067label(ADDRESS_UDP_CONNECT)dit(bf(tt(UDP:<host>:<port>))) 1068 Connects to <port> [link(UDP service)(TYPE_UDP_SERVICE)] on 1069 <host> [link(IP address)(TYPE_IP_ADDRESS)] using UDP/IP version 4 or 6 1070 depending on address specification, name resolution, or option 1071 link(pf)(OPTION_PROTOCOL_FAMILY).nl() 1072 Please note that, 1073 due to UDP protocol properties, no real connection is established; data has 1074 to be sent for `connecting' to the server, and no end-of-file condition can 1075 be transported.nl() 1076 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6) nl() 1077 Useful options: 1078 link(ttl)(OPTION_TTL), 1079 link(tos)(OPTION_TOS), 1080 link(bind)(OPTION_BIND), 1081 link(sourceport)(OPTION_SOURCEPORT), 1082 link(pf)(OPTION_PROTOCOL_FAMILY)nl() 1083 See also: 1084 link(UDP4)(ADDRESS_UDP4_CONNECT), 1085 link(UDP6)(ADDRESS_UDP6_CONNECT), 1086 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN), 1087 link(TCP)(ADDRESS_TCP_CONNECT), 1088 link(IP)(ADDRESS_IP_SENDTO) 1089label(ADDRESS_UDP4_CONNECT)dit(bf(tt(UDP4:<host>:<port>))) 1090 Like link(UDP)(ADDRESS_UDP_CONNECT), but only supports IPv4 protocol.nl() 1091 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4) nl() 1092label(ADDRESS_UDP6_CONNECT)dit(bf(tt(UDP6:<host>:<port>))) 1093 Like link(UDP)(ADDRESS_UDP_CONNECT), but only supports IPv6 protocol.nl() 1094 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6) nl() 1095label(ADDRESS_UDP_DATAGRAM)dit(bf(tt(UDP-DATAGRAM:<address>:<port>))) 1096 Sends outgoing data to the specified address which may in particular be a 1097 broadcast or multicast address. Packets arriving on the local socket are 1098 checked for the correct remote port only when option link(sourceport)(OPTION_SOURCEPORT) is used (this is a change with Socat() version 1.7.4.0) and if their source addresses match 1099 link(RANGE)(OPTION_RANGE) or link(TCPWRAP)(OPTION_TCPWRAPPERS) 1100 options. This address type can for example be used for implementing 1101 symmetric or asymmetric broadcast or multicast communications.nl() 1102 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE) nl() 1103 Useful options: 1104 link(bind)(OPTION_BIND), 1105 link(range)(OPTION_RANGE), 1106 link(tcpwrap)(OPTION_TCPWRAPPERS), 1107 link(broadcast)(OPTION_SO_BROADCAST), 1108 link(ip-multicast-loop)(OPTION_IP_MULTICAST_LOOP), 1109 link(ip-multicast-ttl)(OPTION_IP_MULTICAST_TTL), 1110 link(ip-multicast-if)(OPTION_IP_MULTICAST_IF), 1111 link(ip-add-membership)(OPTION_IP_ADD_MEMBERSHIP), 1112 link(ip-add-source-membership)(OPTION_IP_ADD_SOURCE_MEMBERSHIP), 1113 link(ttl)(OPTION_TTL), 1114 link(tos)(OPTION_TOS), 1115 link(sourceport)(OPTION_SOURCEPORT), 1116 link(pf)(OPTION_PROTOCOL_FAMILY)nl() 1117 See also: 1118 link(UDP4-DATAGRAM)(ADDRESS_UDP4_DATAGRAM), 1119 link(UDP6-DATAGRAM)(ADDRESS_UDP6_DATAGRAM), 1120 link(UDP-SENDTO)(ADDRESS_UDP_SENDTO), 1121 link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM), 1122 link(UDP-RECV)(ADDRESS_UDP_RECV), 1123 link(UDP-CONNECT)(ADDRESS_UDP_CONNECT), 1124 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN), 1125 link(IP-DATAGRAM)(ADDRESS_IP_DATAGRAM) 1126label(ADDRESS_UDP4_DATAGRAM)dit(bf(tt(UDP4-DATAGRAM:<address>:<port>))) 1127 Like link(UDP-DATAGRAM)(ADDRESS_UDP_DATAGRAM), but only supports IPv4 1128 protocol (link(example1)(EXAMPLE_ADDRESS_UDP4_BROADCAST_CLIENT), 1129 link(example2)(EXAMPLE_ADDRESS_UDP4_MULTICAST)).nl() 1130 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4), link(RANGE)(GROUP_RANGE) 1131label(ADDRESS_UDP6_DATAGRAM)dit(bf(tt(UDP6-DATAGRAM:<address>:<port>))) 1132 Like link(UDP-DATAGRAM)(ADDRESS_UDP_DATAGRAM), but only supports IPv6 1133 protocol.nl() 1134 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE) 1135label(ADDRESS_UDP_LISTEN)dit(bf(tt(UDP-LISTEN:<port>))) 1136 Waits for a UDP/IP packet arriving on <port> 1137 [link(UDP service)(TYPE_UDP_SERVICE)] and `connects' back to sender. 1138 The accepted IP version is 4 or the one specified with option 1139 link(pf)(OPTION_PROTOCOL_FAMILY). 1140 Please note that, 1141 due to UDP protocol properties, no real connection is established; data has 1142 to arrive from the peer first, and no end-of-file condition can be 1143 transported. Note that opening 1144 this address usually blocks until a client connects.nl() 1145 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6) nl() 1146 Useful options: 1147 link(fork)(OPTION_FORK), 1148 link(bind)(OPTION_BIND), 1149 link(range)(OPTION_RANGE), 1150 link(pf)(OPTION_PROTOCOL_FAMILY) nl() 1151 See also: 1152 link(UDP)(ADDRESS_UDP_CONNECT), 1153 link(UDP4-LISTEN)(ADDRESS_UDP4_LISTEN), 1154 link(UDP6-LISTEN)(ADDRESS_UDP6_LISTEN), 1155 link(TCP-LISTEN)(ADDRESS_TCP_LISTEN) 1156label(ADDRESS_UDP4_LISTEN)dit(bf(tt(UDP4-LISTEN:<port>))) 1157 Like link(UDP-LISTEN)(ADDRESS_UDP_LISTEN), but only support IPv4 1158 protocol.nl() 1159 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP4)(GROUP_IP4) nl() 1160label(ADDRESS_UDP6_LISTEN)dit(bf(tt(UDP6-LISTEN:<port>))) 1161 Like link(UDP-LISTEN)(ADDRESS_UDP_LISTEN), but only support IPv6 1162 protocol.nl() 1163 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE),link(IP6)(GROUP_IP6) nl() 1164label(ADDRESS_UDP_SENDTO)dit(bf(tt(UDP-SENDTO:<host>:<port>))) 1165 Communicates with the specified peer socket, defined by <port> [link(UDP 1166 service)(TYPE_UDP_SERVICE)] on 1167 <host> [link(IP address)(TYPE_IP_ADDRESS)], using UDP/IP version 4 or 6 1168 depending on address specification, name resolution, or option 1169 link(pf)(OPTION_PROTOCOL_FAMILY). It sends packets to and receives packets 1170 from that peer socket only. 1171 This address effectively implements a datagram client. 1172 It works well with socat UDP-RECVFROM and UDP-RECV address peers.nl() 1173 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6) nl() 1174 Useful options: 1175 link(ttl)(OPTION_TTL), 1176 link(tos)(OPTION_TOS), 1177 link(bind)(OPTION_BIND), 1178 link(sourceport)(OPTION_SOURCEPORT), 1179 link(pf)(OPTION_PROTOCOL_FAMILY)nl() 1180 See also: 1181 link(UDP4-SENDTO)(ADDRESS_UDP4_SENDTO), 1182 link(UDP6-SENDTO)(ADDRESS_UDP6_SENDTO), 1183 link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM), 1184 link(UDP-RECV)(ADDRESS_UDP_RECV), 1185 link(UDP-CONNECT)(ADDRESS_UDP_CONNECT), 1186 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN), 1187 link(IP-SENDTO)(ADDRESS_IP_SENDTO) 1188label(ADDRESS_UDP4_SENDTO)dit(bf(tt(UDP4-SENDTO:<host>:<port>))) 1189 Like link(UDP-SENDTO)(ADDRESS_UDP_SENDTO), but only supports IPv4 1190 protocol.nl() 1191 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4) 1192label(ADDRESS_UDP6_SENDTO)dit(bf(tt(UDP6-SENDTO:<host>:<port>))) 1193 Like link(UDP-SENDTO)(ADDRESS_UDP_SENDTO), but only supports IPv6 1194 protocol.nl() 1195 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6) 1196 1197label(ADDRESS_UDP_RECVFROM)dit(bf(tt(UDP-RECVFROM:<port>))) 1198 Creates a UDP socket on <port> [link(UDP service)(TYPE_UDP_SERVICE)] using 1199 UDP/IP version 4 or 6 1200 depending on option link(pf)(OPTION_PROTOCOL_FAMILY). 1201 It receives one packet from an unspecified peer and may send one or more 1202 answer packets to that peer. This mode is particularly useful with 1203 link(fork)(OPTION_FORK) option 1204 where each arriving packet - from arbitrary peers - is handled by its own sub 1205 process. This allows a behaviour similar to typical UDP based servers like ntpd 1206 or named. This address works well with socat UDP-SENDTO address peers.nl() 1207 label(NOTE_RECVFROM)Note: When the second address fails before entering the transfer loop the 1208 packet is dropped. Use option link(retry)(OPTION_RETRY) or 1209 link(forever)(OPTION_FOREVER) on the second address to avoid data loss. 1210 nl() 1211 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE) nl() 1212 Useful options: 1213 link(fork)(OPTION_FORK), 1214 link(ttl)(OPTION_TTL), 1215 link(tos)(OPTION_TOS), 1216 link(bind)(OPTION_BIND), 1217 link(sourceport)(OPTION_SOURCEPORT), 1218 link(pf)(OPTION_PROTOCOL_FAMILY)nl() 1219 See also: 1220 link(UDP4-RECVFROM)(ADDRESS_UDP4_RECVFROM), 1221 link(UDP6-RECVFROM)(ADDRESS_UDP6_RECVFROM), 1222 link(UDP-SENDTO)(ADDRESS_UDP_SENDTO), 1223 link(UDP-RECV)(ADDRESS_UDP_RECV), 1224 link(UDP-CONNECT)(ADDRESS_UDP_CONNECT), 1225 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN), 1226 link(IP-RECVFROM)(ADDRESS_IP_RECVFROM), 1227 link(UNIX-RECVFROM)(ADDRESS_UNIX_RECVFROM) 1228label(ADDRESS_UDP4_RECVFROM)dit(bf(tt(UDP4-RECVFROM:<port>))) 1229 Like link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM), but only supports IPv4 protocol.nl() 1230 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE) 1231label(ADDRESS_UDP6_RECVFROM)dit(bf(tt(UDP6-RECVFROM:<port>))) 1232 Like link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM), but only supports IPv6 protocol.nl() 1233 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE) 1234 1235label(ADDRESS_UDP_RECV)dit(bf(tt(UDP-RECV:<port>))) 1236 Creates a UDP socket on <port> [link(UDP service)(TYPE_UDP_SERVICE)] using UDP/IP version 4 or 6 1237 depending on option link(pf)(OPTION_PROTOCOL_FAMILY). 1238 It receives packets from multiple unspecified peers and merges the data. 1239 No replies are possible. It works well with, e.g., socat link(UDP-SENDTO)(ADDRESS_UDP_SENDTO) address peers; it behaves similar to a syslog server.nl() 1240 Note: if you need the link(fork)(OPTION_FORK) option, use link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM) in unidirectional mode (with link(option -u)(option_u)) instead.nl() 1241 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE) nl() 1242 Useful options: 1243 link(pf)(OPTION_PROTOCOL_FAMILY), 1244 link(bind)(OPTION_BIND), 1245 link(sourceport)(OPTION_SOURCEPORT), 1246 link(ttl)(OPTION_TTL), 1247 link(tos)(OPTION_TOS)nl() 1248 See also: 1249 link(UDP4-RECV)(ADDRESS_UDP4_RECV), 1250 link(UDP6-RECV)(ADDRESS_UDP6_RECV), 1251 link(UDP-SENDTO)(ADDRESS_UDP_SENDTO), 1252 link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM), 1253 link(UDP-CONNECT)(ADDRESS_UDP_CONNECT), 1254 link(UDP-LISTEN)(ADDRESS_UDP_LISTEN), 1255 link(IP-RECV)(ADDRESS_IP_RECV), 1256 link(UNIX-RECV)(ADDRESS_UNIX_RECV) 1257label(ADDRESS_UDP4_RECV)dit(bf(tt(UDP4-RECV:<port>))) 1258 Like link(UDP-RECV)(ADDRESS_UDP_RECV), but only supports IPv4 protocol.nl() 1259 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(RANGE)(GROUP_RANGE) 1260label(ADDRESS_UDP6_RECV)dit(bf(tt(UDP6-RECV:<port>))) 1261 Like link(UDP-RECV)(ADDRESS_UDP_RECV), but only supports IPv6 protocol.nl() 1262 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP6)(GROUP_IP6),link(RANGE)(GROUP_RANGE) 1263 1264label(ADDRESS_UNIX_CONNECT)dit(bf(tt(UNIX-CONNECT:<filename>))) 1265 Connects to link(<filename>)(TYPE_FILENAME) assuming it is a unixdomain() 1266 socket. 1267 If <filename> does not exist, this is an error; 1268 if <filename> is not a unixdomain() socket, this is an error; 1269 if <filename> is a unixdomain() socket, but no process is listening, this is 1270 an error.nl() 1271 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(NAMED)(GROUP_NAMED),link(RETRY)(GROUP_RETRY),link(UNIX)(GROUP_SOCK_UNIX) nl()) 1272 Useful options: 1273 link(bind)(OPTION_BIND)nl() 1274 See also: 1275 link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN), 1276 link(UNIX-SENDTO)(ADDRESS_UNIX_SENDTO), 1277 link(TCP)(ADDRESS_TCP_CONNECT) 1278 1279label(ADDRESS_UNIX_LISTEN)dit(bf(tt(UNIX-LISTEN:<filename>))) 1280 Listens on link(<filename>)(TYPE_FILENAME) using a unixdomain() stream 1281 socket and accepts a connection. 1282 If <filename> exists and is not a socket, this is an error. 1283 If <filename> exists and is a unixdomain() socket, binding to the address 1284 fails (use option link(unlink-early)(OPTION_UNLINK_EARLY)!). 1285 Note that opening this address usually blocks until a client connects. 1286 Beginning with socat version 1.4.3, the file system entry is removed when 1287 this address is closed (but see option link(unlink-close)(OPTION_UNLINK_CLOSE)) (link(example)(EXAMPLE_ADDRESS_UNIX_LISTEN)).nl() 1288 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(NAMED)(GROUP_NAMED),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY),link(UNIX)(GROUP_SOCK_UNIX) nl() 1289 Useful options: 1290 link(fork)(OPTION_FORK), 1291 link(umask)(OPTION_UMASK), 1292 link(mode)(OPTION_MODE), 1293 link(user)(OPTION_USER), 1294 link(group)(OPTION_GROUP), 1295 link(unlink-early)(OPTION_UNLINK_EARLY)nl() 1296 See also: 1297 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT), 1298 link(UNIX-RECVFROM)(ADDRESS_UNIX_RECVFROM), 1299 link(UNIX-RECV)(ADDRESS_UNIX_RECV), 1300 link(TCP-LISTEN)(ADDRESS_TCP4_LISTEN) 1301 1302label(ADDRESS_UNIX_SENDTO)dit(bf(tt(UNIX-SENDTO:<filename>))) 1303 Communicates with the specified peer socket, defined by [link(<filename>)(TYPE_FILENAME)] assuming it is a unixdomain() datagram socket. 1304 It sends packets to and receives packets from that peer socket only. 1305 Please note that it might be necessary to link(bind)(OPTION_BIND) the 1306 local socket to an address (e.g. tt(/tmp/sock1), which must not exist 1307 before). 1308 This address type works well with socat UNIX-RECVFROM and UNIX-RECV address 1309 peers.nl() 1310 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(NAMED)(GROUP_NAMED),link(UNIX)(GROUP_SOCK_UNIX)nl() 1311 Useful options: 1312 link(bind)(OPTION_BIND)nl() 1313 See also: 1314 link(UNIX-RECVFROM)(ADDRESS_UNIX_RECVFROM), 1315 link(UNIX-RECV)(ADDRESS_UNIX_RECV), 1316 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT), 1317 link(UDP-SENDTO)(ADDRESS_UDP_SENDTO), 1318 link(IP-SENDTO)(ADDRESS_IP_SENDTO) 1319 1320label(ADDRESS_UNIX_RECVFROM)dit(bf(tt(UNIX-RECVFROM:<filename>))) 1321 Creates a unixdomain() datagram socket [link(<filename>)(TYPE_FILENAME)]. 1322 Receives one packet and may send one or more answer packets to that peer. 1323 This mode is particularly useful with fork option where each arriving packet - from arbitrary peers - is handled by its own sub process. 1324 This address works well with socat UNIX-SENDTO address peers.nl() 1325 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(NAMED)(GROUP_NAMED),link(CHILD)(GROUP_CHILD),link(UNIX)(GROUP_SOCK_UNIX) nl() 1326 See the link(note about RECVFROM addresses)(NOTE_RECVFROM).nl() 1327 Useful options: 1328 link(fork)(OPTION_FORK)nl() 1329 See also: 1330 link(UNIX-SENDTO)(ADDRESS_UNIX_SENDTO), 1331 link(UNIX-RECV)(ADDRESS_UNIX_RECV), 1332 link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN), 1333 link(UDP-RECVFROM)(ADDRESS_UDP_RECVFROM), 1334 link(IP-RECVFROM)(ADDRESS_IP_RECVFROM) 1335 1336label(ADDRESS_UNIX_RECV)dit(bf(tt(UNIX-RECV:<filename>))) 1337 Creates a unixdomain() datagram socket [link(<filename>)(TYPE_FILENAME)]. 1338 Receives packets from multiple unspecified peers and merges the data. 1339 No replies are possible. It can be, e.g., addressed by socat UNIX-SENDTO address peers. 1340 It behaves similar to a syslog server.nl() 1341 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(NAMED)(GROUP_NAMED),link(UNIX)(GROUP_SOCK_UNIX) nl() 1342 See also: 1343 link(UNIX-SENDTO)(ADDRESS_UNIX_SENDTO), 1344 link(UNIX-RECVFROM)(ADDRESS_UNIX_RECVFROM), 1345 link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN), 1346 link(UDP-RECV)(ADDRESS_UDP_RECV), 1347 link(IP-RECV)(ADDRESS_IP_RECV) 1348 1349label(ADDRESS_UNIX_CLIENT)dit(bf(tt(UNIX-CLIENT:<filename>))) 1350 Communicates with the specified peer socket, defined by 1351 [link(<filename>)(TYPE_FILENAME)] assuming it is a unixdomain() socket. 1352 It first tries to connect and, if that fails, assumes it is a datagram 1353 socket, thus supporting both types.nl() 1354 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(NAMED)(GROUP_NAMED),link(UNIX)(GROUP_SOCK_UNIX) nl() 1355 Useful options: 1356 link(bind)(OPTION_BIND)nl() 1357 See also: 1358 link(UNIX-CONNECT)(ADDRESS_UNIX_CONNECT), 1359 link(UNIX-SENDTO)(ADDRESS_UNIX_SENDTO), 1360 link(GOPEN)(ADDRESS_GOPEN) 1361 1362label(ADDRESS_VSOCK_CONNECT)dit(bf(tt(VSOCK-CONNECT:<cid>:<port>))) 1363 Establishes a VSOCK stream connection to the specified <cid> [link(VSOCK 1364 cid)(TYPE_VSOCK_ADDRESS)] and <port> [link(VSOCK port)(TYPE_VSOCK_PORT)].nl() 1365 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY) nl() 1366 Useful options: 1367 link(bind)(OPTION_BIND), 1368 link(pf)(OPTION_PROTOCOL_FAMILY), 1369 link(connect-timeout)(OPTION_CONNECT_TIMEOUT), 1370 link(retry)(OPTION_RETRY), 1371 link(readbytes)(OPTION_READBYTES)nl() 1372 See also: 1373 link(VSOCK-LISTEN)(ADDRESS_VSOCK_LISTEN), 1374 1375label(ADDRESS_VSOCK_LISTEN)dit(bf(tt(VSOCK-LISTEN:<port>))) 1376 Listens on <port> [link(VSOCK port)(TYPE_VSOCK_PORT)] and accepts a 1377 VSOCK connection. 1378 Note that opening this address usually blocks until a client connects.nl() 1379 Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY) nl() 1380 Useful options: 1381 link(fork)(OPTION_FORK), 1382 link(bind)(OPTION_BIND), 1383 link(pf)(OPTION_PROTOCOL_FAMILY), 1384 link(max-children)(OPTION_MAX_CHILDREN), 1385 link(backlog)(OPTION_BACKLOG), 1386 link(su)(OPTION_SUBSTUSER), 1387 link(reuseaddr)(OPTION_REUSEADDR), 1388 link(retry)(OPTION_RETRY), 1389 link(cool-write)(OPTION_COOL_WRITE)nl() 1390 See also: 1391 link(VSOCK-CONNECT)(ADDRESS_VSOCK_CONNECT) 1392 1393dit(bf(tt(ABSTRACT-CONNECT:<string>))) 1394dit(bf(tt(ABSTRACT-LISTEN:<string>))) 1395dit(bf(tt(ABSTRACT-SENDTO:<string>))) 1396dit(bf(tt(ABSTRACT-RECVFROM:<string>))) 1397dit(bf(tt(ABSTRACT-RECV:<string>))) 1398dit(bf(tt(ABSTRACT-CLIENT:<string>))) 1399 The ABSTRACT addresses are almost identical to the related UNIX addresses 1400 except that they do not address file system based sockets but an alternate 1401 unixdomain() address space. To achieve this the socket address strings are 1402 prefixed with "\0" internally. This feature is available (only?) on Linux. 1403 Option groups are the same as with the related UNIX addresses, except that 1404 the ABSTRACT addresses are not member of the NAMED group. 1405enddit() 1406 1407 1408label(ADDRESS_OPTIONS) 1409manpagesection(ADDRESS OPTIONS) 1410 1411Address options can be applied to address specifications to influence the 1412process of opening the addresses and the 1413properties of the resulting data channels. 1414 1415For technical reasons not every option can be 1416applied to every address type; e.g., applying a socket option to a regular file 1417will fail. To catch most useless combinations as early as in the open phase, 1418the concept of em(option groups) was introduced. Each option belongs to one 1419or more option groups. Options can be used only with address types that support 1420at least one of their option groups (but see link(option -g)(option_g)). 1421 1422Address options have data types that their values must conform to. 1423Every address option consists of just a keyword or a keyword followed by 1424"=value", where value must conform to the options type. 1425COMMENT(Options that trigger a call with 1426trivial parameters are described with type BOOL which might be misleading.) 1427Some address options manipulate parameters of system calls; 1428e.g., option sync sets the code(O_SYNC) flag with the code(open()) call. 1429Other options cause a system or library call; e.g., with option `ttl=value' 1430the code(setsockopt(fd, SOL_IP, IP_TTL, value, sizeof(int))) call is applied. 1431Other 1432options set internal socat() variables that are used during data transfer; 1433e.g., `crnl' causes explicit character conversions. 1434A few options have more complex implementations; e.g., su-d 1435(substuser-delayed) inquires some user and group infos, stores them, and 1436applies them later after a possible code(chroot()) call. 1437 1438If multiple options are given to an address, their sequence in the address specification has (almost) no 1439effect on the sequence of their execution/application. Instead, socat() has 1440built in an em(option phase) model that tries to bring the options in a useful 1441order. Some options exist in different forms (e.g., 1442unlink, unlink-early, unlink-late) to control the time of their execution. 1443 1444If the same option is specified more than once within one address 1445specification, with equal or different values, the effect depends on the kind of option. Options 1446resulting in function calls like code(setsockopt()) cause multiple 1447invocations. With options that set parameters for a required call like 1448code(open()) 1449or set internal flags, the value of the last option occurrence is effective. 1450 1451The existence or semantics of many options are system dependent. Socat() 1452usually does NOT try to emulate missing libc or kernel features, it just 1453provides an 1454interface to the underlying system. So, if an operating system lacks a feature, 1455the related option is simply not available on this platform. 1456 1457The following paragraphs introduce just the more common address options. For 1458a more comprehensive reference and to find information about canonical option 1459names, alias names, option phases, and platforms see file file(xio.help). 1460nl() nl() 1461 1462startdit()enddit()nl() 1463 1464 1465label(GROUP_FD)em(bf(FD option group)) 1466 1467This option group contains options that are applied to a unix() 1468style file descriptor, no matter how it was generated. 1469Because all current socat() address types are file descriptor based, these 1470options may be applied to any address. nl() 1471Note: Some of these options are also member of another option group, that 1472provides another, non-fd based mechanism. 1473For these options, it depends on the actual address type and its option groups 1474which mechanism is used. The second, non-fd based mechanism is prioritized. 1475startdit() 1476label(OPTION_CLOEXEC)dit(bf(tt(cloexec=<bool>))) 1477 Sets the code(FD_CLOEXEC) flag with the code(fcntl()) system call to value 1478 link(<bool>)(TYPE_BOOL). If set, 1479 the file descriptor is closed on code(exec()) family function calls. Socat() 1480 internally handles 1481 this flag for the fds it controls, so in most cases there will be no need to 1482 apply this option. 1483label(OPTION_SETLK_WR)dit(bf(tt(setlk))) 1484 Tries to set a discretionary write lock to the whole file using the code(fcntl(fd, 1485 F_SETLK, ...)) system call. If the file is already locked, this call results 1486 in an error. 1487 On Linux, when the file permissions for group are "S" (g-x,g+s), and the 1488 file system is locally mounted with the "mand" option, the lock is 1489 mandatory, i.e. prevents other processes from opening the file. 1490label(OPTION_SETLKW_WR)dit(bf(tt(setlkw))) 1491 Tries to set a discretionary waiting write lock to the whole file using the 1492 code(fcntl(fd, F_SETLKW, ...)) system call. If the file is already locked, 1493 this call blocks. 1494 See option link(setlk)(OPTION_SETLK_WR) for information about making this 1495 lock mandatory. 1496label(OPTION_SETLK_RD)dit(bf(tt(setlk-rd))) 1497 Tries to set a discretionary read lock to the whole file using the code(fcntl(fd, 1498 F_SETLK, ...)) system call. If the file is already write locked, this call 1499 results in an error. 1500 See option link(setlk)(OPTION_SETLK_WR) for information about making this 1501 lock mandatory. 1502label(OPTION_SETLKW_RD)dit(bf(tt(setlkw-rd))) 1503 Tries to set a discretionary waiting read lock to the whole file using the 1504 code(fcntl(fd, F_SETLKW, ...)) system call. If the file is already write 1505 locked, this call blocks. 1506 See option link(setlk)(OPTION_SETLK_WR) for information about making this 1507 lock mandatory. 1508label(OPTION_FLOCK_EX)dit(bf(tt(flock-ex))) 1509 Tries to set a blocking exclusive advisory lock to the file using the 1510 code(flock(fd, LOCK_EX)) system call. Socat() hangs in this call if the file 1511 is locked by another process. 1512label(OPTION_FLOCK_EX_NB)dit(bf(tt(flock-ex-nb))) 1513 Tries to set a nonblocking exclusive advisory lock to the file using the 1514 code(flock(fd, LOCK_EX|LOCK_NB)) system call. If the file is already locked, 1515 this option results in an error. 1516label(OPTION_FLOCK_SH)dit(bf(tt(flock-sh))) 1517 Tries to set a blocking shared advisory lock to the file using the 1518 code(flock(fd, LOCK_SH)) system call. Socat() hangs in this call if the file 1519 is locked by another process. 1520label(OPTION_FLOCK_SH_NB)dit(bf(tt(flock-sh-nb))) 1521 Tries to set a nonblocking shared advisory lock to the file using the 1522 code(flock(fd, LOCK_SH|LOCK_NB)) system call. If the file is already locked, 1523 this option results in an error. 1524label(OPTION_LOCK)dit(bf(tt(lock))) 1525 Sets a blocking lock on the file. Uses the setlk or flock mechanism 1526 depending on availability on the particular platform. If both are available, 1527 the POSIX variant (setlkw) is used. 1528label(OPTION_USER)dit(bf(tt(user=<user>))) 1529 Sets the link(<user>)(TYPE_USER) (owner) of the stream. 1530 If the address is member of the NAMED option group, 1531 socat() uses the code(chown()) system call after opening the 1532 file or binding to the unixdomain() socket (race condition!). 1533 Without filesystem entry, socat() sets the user of the stream 1534 using the code(fchown()) system call. 1535 These calls might require root privilege. 1536label(OPTION_USER_LATE)dit(bf(tt(user-late=<user>))) 1537 Sets the owner of the fd to link(<user>)(TYPE_USER) with the code(fchown()) 1538 system call after opening 1539 or connecting the channel. 1540 This is useful only on file system entries. 1541label(OPTION_GROUP)dit(bf(tt(group=<group>))) 1542 Sets the link(<group>)(TYPE_GROUP) of the stream. 1543 If the address is member of the NAMED option group, 1544 socat() uses the code(chown()) system call after opening the 1545 file or binding to the unixdomain() socket (race condition!). 1546 Without filesystem entry, socat() sets the group of the stream 1547 with the code(fchown()) system call. 1548 These calls might require group membership or root privilege. 1549label(OPTION_GROUP_LATE)dit(bf(tt(group-late=<group>))) 1550 Sets the group of the fd to link(<group>)(TYPE_GROUP) with the 1551 code(fchown()) system call after opening 1552 or connecting the channel. 1553 This is useful only on file system entries. 1554label(OPTION_MODE)dit(bf(tt(mode=<mode>))) 1555 Sets the <mode> [link(mode_t)(TYPE_MODE_T)] (permissions) of the stream. 1556 If the address is member of the NAMED option group and 1557 uses the code(open()) or code(creat()) call, the mode is applied with these. 1558 If the address is member of the NAMED option group without using these 1559 system calls, socat() uses the code(chmod()) system call after opening the 1560 filesystem entry or binding to the unixdomain() socket (race condition!). 1561 Otherwise, socat() sets the mode of the stream 1562 using code(fchmod()). 1563 These calls might require ownership or root privilege. 1564label(OPTION_PERM_LATE)dit(bf(tt(perm-late=<mode>))) 1565 Sets the permissions of the fd to value <mode> 1566 [link(mode_t)(TYPE_MODE_T)] using the code(fchmod()) system call after 1567 opening or connecting the channel. 1568 This is useful only on file system entries. 1569label(OPTION_APPEND)dit(bf(tt(append=<bool>))) 1570 Always writes data to the actual end of file. 1571 If the address is member of the OPEN option group, 1572 socat() uses the code(O_APPEND) flag with the code(open()) system call 1573 (link(example)(EXAMPLE_OPTION_APPEND)). 1574 Otherwise, socat() applies the code(fcntl(fd, F_SETFL, O_APPEND)) call. 1575label(OPTION_NONBLOCK)dit(bf(tt(nonblock=<bool>))) 1576 Tries to open or use file in nonblocking mode. Its only effects are that the 1577 code(connect()) call of TCP addresses does not block, and that opening a 1578 named pipe for reading does not block. 1579 If the address is member of the OPEN option group, 1580 socat() uses the code(O_NONBLOCK) flag with the code(open()) system call. 1581 Otherwise, socat() applies the code(fcntl(fd, F_SETFL, O_NONBLOCK)) call. 1582COMMENT(label(OPTION_NDELAY)dit(bf(tt(ndelay=<bool>))) 1583 Tries to open or use file in nonblocking mode. Has no effect because socat() 1584 works with code(select()).) 1585COMMENT(label(OPTION_ASYNC)dit(bf(tt(async=<bool>))) 1586 Enables SIGIO for this fd. Has no effect, because socat() ignores SIGIO.) 1587label(OPTION_O_BINARY)dit(bf(tt(binary))) 1588 Opens the file in binary mode to avoid implicit line terminator 1589 conversions (Cygwin). 1590label(OPTION_O_TEXT)dit(bf(tt(text))) 1591 Opens the file in text mode to force implicit line terminator conversions 1592 (Cygwin). 1593label(OPTION_O_NOINHERIT)dit(bf(tt(noinherit))) 1594 Does not keep this file open in a spawned process (Cygwin). 1595label(OPTION_COOL_WRITE)dit(bf(tt(cool-write))) 1596 Takes it easy when write fails with EPIPE or ECONNRESET and logs the message 1597 with em(notice) level instead of em(error). 1598 This prevents the log file from being filled with useless error messages 1599 when socat is used as a high volume server or proxy where clients often 1600 abort the connection.nl() 1601 This option is experimental. 1602label(OPTION_END_CLOSE)dit(bf(tt(end-close))) 1603 Changes the (address dependent) method of ending a connection to just close 1604 the file descriptors. This is useful when the connection is to be reused by 1605 or shared with other processes (link(example)(EXAMPLE_END_CLOSE)).nl() 1606 Normally, socket connections will be ended with tt(shutdown(2)) which 1607 terminates the socket even if it is shared by multiple processes. 1608 tt(close(2)) "unlinks" the socket from the process but keeps it active as 1609 long as there are still links from other processes.nl() 1610 Similarly, when an address of type EXEC or SYSTEM is ended, socat usually 1611 will explicitly kill the sub process. With this option, it will just close 1612 the file descriptors. 1613label(OPTION_SHUT_NONE)dit(bf(tt(shut-none))) 1614 Changes the (address dependent) method of shutting down the write part of a 1615 connection to not do anything. 1616label(OPTION_SHUT_DOWN)dit(bf(tt(shut-down))) 1617 Changes the (address dependent) method of shutting down the write part of a 1618 connection to NOEXPAND(shutdown(fd, SHUT_WR)). Is only useful with sockets. 1619label(OPTION_SHUT_CLOSE)dit(bf(tt(shut-close))) 1620 Changes the (address dependent) method of shutting down the write part of a 1621 connection to NOEXPAND(close(fd)). 1622label(OPTION_SHUT_NULL)dit(bf(tt(shut-null))) 1623 When one address indicates EOF, socat() will send a zero sized packet to the 1624 write channel of the other address to transfer the EOF condition. This is 1625 useful with UDP and other datagram protocols. Has been tested against 1626 netcat and socat with option link(null-eof)(OPTION_NULL_EOF). 1627label(OPTION_NULL_EOF)dit(bf(tt(null-eof))) 1628 Normally socat() will ignore empty (zero size payload) packets arriving on 1629 datagram sockets, so it survives port scans. With this option socat() 1630 interprets empty datagram packets as EOF indicator (see 1631 link(shut-null)(OPTION_SHUT_NULL)). 1632label(OPTION_IOCTL_VOID)dit(bf(tt(ioctl-void=<request>))) 1633 Calls tt(ioctl()) with the request value as second argument and NULL as 1634 third argument. This option allows utilizing ioctls that are not 1635 explicitly implemented in socat. 1636label(OPTION_IOCTL_INT)dit(bf(tt(ioctl-int=<request>:<value>))) 1637 Calls tt(ioctl()) with the request value as second argument and the integer 1638 value as third argument. 1639label(OPTION_IOCTL_INTP)dit(bf(tt(ioctl-intp=<request>:<value>))) 1640 Calls tt(ioctl()) with the request value as second argument and a pointer to 1641 the integer value as third argument. 1642label(OPTION_IOCTL_BIN)dit(bf(tt(ioctl-bin=<request>:<value>))) 1643 Calls tt(ioctl()) with the request value as second argument and a pointer to 1644 the given data value as third argument. This data must be specified in 1645 link(<dalan>)(TYPE_DATA) form. 1646label(OPTION_IOCTL_STRING)dit(bf(tt(ioctl-string=<request>:<value>))) 1647 Calls tt(ioctl()) with the request value as second argument and a pointer to 1648 the given string as third argument. 1649 link(<dalan>)(TYPE_DATA) form. 1650enddit() 1651 1652startdit()enddit()nl() 1653 1654 1655label(GROUP_NAMED)em(bf(NAMED option group)) 1656 1657These options work on file system entries.nl() 1658Please note that, with UNIX domain client addresses, this means the bind entry, 1659not the target/peer entry.nl() 1660See also options link(user)(OPTION_USER), link(group)(OPTION_GROUP), and 1661link(mode)(OPTION_MODE). 1662 1663startdit() 1664label(OPTION_USER_EARLY)dit(bf(tt(user-early=<user>))) 1665 Changes the link(<user>)(TYPE_USER) (owner) of the file system entry before 1666 accessing it, using the 1667 code(chown()) system call. This call might require root privilege. 1668label(OPTION_GROUP_EARLY)dit(bf(tt(group-early=<group>))) 1669 Changes the link(<group>)(TYPE_GROUP) of the file system entry before 1670 accessing it, using the 1671 code(chown()) system call. This call might require group membership or root 1672 privilege. 1673label(OPTION_PERM_EARLY)dit(bf(tt(perm-early=<mode>))) 1674 Changes the <mode> [link(mode_t)(TYPE_MODE_T)] of the file system entry 1675 before accessing it, using the 1676 code(chmod()) system call. This call might require ownership or root 1677 privilege. 1678label(OPTION_UMASK)dit(bf(tt(umask=<mode>))) 1679 Sets the umask of the process to <mode> [link(mode_t)(TYPE_MODE_T)] before 1680 accessing the file system entry (useful 1681 with unixdomain() sockets!). This call might affect all further operations 1682 of the socat() process! 1683label(OPTION_UNLINK_EARLY)dit(bf(tt(unlink-early))) 1684 Unlinks (removes) the file before opening it and even before applying 1685 user-early etc. 1686label(OPTION_UNLINK)dit(bf(tt(unlink))) 1687 Unlinks (removes) the file before accessing it, but after user-early etc. 1688label(OPTION_UNLINK_LATE)dit(bf(tt(unlink-late))) 1689 Unlinks (removes) the file after opening it to make it inaccessible for 1690 other processes after a short race condition. 1691label(OPTION_UNLINK_CLOSE)dit(bf(tt(unlink-close))) 1692 Removes the addresses file system entry when closing the address. 1693 For link(named pipes)(ADDRESS_NAMED_PIPE), 1694 link(UNIX domain sockets)(ADDRESS_UNIX_LISTEN), 1695 and the link(symbolic links)(OPTION_SYMBOLIC_LINK) of link(pty addresses)(ADDRESS_PTY), 1696 the default is 1; for link(created files)(ADDRESS_CREAT), 1697 link(opened files)(ADDRESS_OPEN), and 1698 link(generic opened files)(ADDRESS_GOPEN) the default is 0. 1699enddit() 1700 1701startdit()enddit()nl() 1702 1703 1704label(GROUP_OPEN)em(bf(OPEN option group)) 1705 1706The OPEN group options allow setting flags with the code(open()) system call. 1707E.g., option `creat' sets the code(O_CREAT) flag.nl() 1708See also options link(append)(OPTION_APPEND) and 1709link(nonblock)(OPTION_NONBLOCK). 1710startdit() 1711label(OPTION_O_CREAT)dit(bf(tt(creat=<bool>))) 1712 Creates the file if it does not exist (link(example)(EXAMPLE_OPTION_CREAT)). 1713label(OPTION_DSYNC)dit(bf(tt(dsync=<bool>))) 1714 Blocks code(write()) calls until metainfo is physically written to media. 1715label(OPTION_EXCL)dit(bf(tt(excl=<bool>))) 1716 With option creat, if file exists this is an error. 1717label(OPTION_LARGEFILE)dit(bf(tt(largefile=<bool>))) 1718 On 32 bit systems, allows a file larger than 2^31 bytes. 1719label(OPTION_O_NOATIME)dit(bf(tt(noatime))) 1720 Sets the O_NOATIME options, so reads do not change the access timestamp. 1721label(OPTION_NOCTTY)dit(bf(tt(noctty=<bool>))) 1722 Does not make this file the controlling terminal. 1723label(OPTION_NOFOLLOW)dit(bf(tt(nofollow=<bool>))) 1724 Does not follow symbolic links. 1725label(OPTION_NSHARE)dit(bf(tt(nshare=<bool>))) 1726 Does not allow sharing this file with other processes. 1727label(OPTION_RSHARE)dit(bf(tt(rshare=<bool>))) 1728 Does not allow other processes to open this file for writing. 1729label(OPTION_RSYNC)dit(bf(tt(rsync=<bool>))) 1730 Blocks code(write()) until metainfo is physically written to media. 1731label(OPTION_SYNC)dit(bf(tt(sync=<bool>))) 1732 Blocks code(write()) until data is physically written to media. 1733COMMENT(label(OPTION_DEFER)dit(bf(tt(defer=<bool>))) 1734 Temporarily stores write data in paging space.) 1735COMMENT(label(OPTION_DELAY)dit(bf(tt(delay=<bool>))) 1736 Blocks code(open()) until share conditions are fulfilled.) 1737COMMENT(label(OPTION_DIRECT)dit(bf(tt(direct=<bool>)))) 1738COMMENT(label(OPTION_DIRECTORY)dit(bf(tt(directory=<bool>))) 1739 Fails if file is not a directory. Not useful with socat().) 1740label(OPTION_RDONLY)dit(bf(tt(rdonly=<bool>))) 1741 Opens the file for reading only. 1742COMMENT(label(OPTION_RDWR)dit(bf(tt(rdwr=<bool>))) 1743 Opens the file for reading and writing.) 1744label(OPTION_WRONLY)dit(bf(tt(wronly=<bool>))) 1745 Opens the file for writing only. 1746label(OPTION_O_TRUNC)dit(bf(tt(trunc))) 1747 Truncates the file to size 0 during opening it. 1748enddit() 1749 1750 1751startdit()enddit()nl() 1752 1753 1754label(GROUP_REG)em(bf(REG and BLK option group)) 1755 1756These options are usually applied to a unix() file descriptor, but their 1757semantics make sense only on a file supporting random access. 1758startdit() 1759label(OPTION_SEEK)dit(bf(tt(seek=<offset>))) 1760 Applies the code(lseek(fd, <offset>, SEEK_SET)) (or code(lseek64)) system 1761 call, thus positioning the file pointer absolutely to <offset> 1762 [link(off_t)(TYPE_OFF) or link(off64_t)(TYPE_OFF64)]. Please note that a 1763 missing value defaults to 1, not 0. 1764label(OPTION_SEEK_CUR)dit(bf(tt(seek-cur=<offset>))) 1765 Applies the code(lseek(fd, <offset>, SEEK_CUR)) (or code(lseek64)) system 1766 call, thus positioning the file pointer <offset> [link(off_t)(TYPE_OFF) or 1767 link(off64_t)(TYPE_OFF64)] bytes relatively to its current position (which 1768 is usually 0). Please note that a missing value defaults to 1, not 0. 1769label(OPTION_SEEK_END)dit(bf(tt(seek-end=<offset>))) 1770 Applies the code(lseek(fd, <offset>, SEEK_END)) (or code(lseek64)) system 1771 call, thus positioning the file pointer <offset> [link(off_t)(TYPE_OFF) or 1772 link(off64_t)(TYPE_OFF64)] bytes relatively to the files current end. Please 1773 note that a missing value defaults to 1, not 0. 1774label(OPTION_FTRUNCATE)dit(bf(tt(ftruncate=<offset>))) 1775 Applies the code(ftruncate(fd, <offset>)) 1776 (or code(ftruncate64) if available) system call, thus 1777 truncating the file at the position <offset> [link(off_t)(TYPE_OFF) or 1778 link(off64_t)(TYPE_OFF64)]. Please note that a missing value defaults to 1, 1779 not 0. 1780 1781label(OPTION_FS_SECRM_FL)dit(bf(tt(secrm=<bool>))) 1782label(OPTION_FS_UNRM)dit(bf(tt(unrm=<bool>))) 1783label(OPTION_FS_COMPR)dit(bf(tt(compr=<bool>))) 1784label(OPTION_FS_SYNC)dit(bf(tt(fs-sync=<bool>))) 1785label(OPTION_FS_IMMUTABLE)dit(bf(tt(immutable=<bool>))) 1786label(OPTION_FS_APPEND)dit(bf(tt(fs-append=<bool>))) 1787label(OPTION_FS_NODUMP)dit(bf(tt(nodump=<bool>))) 1788label(OPTION_FS_NOATIME)dit(bf(tt(fs-noatime=<bool>))) 1789label(OPTION_FS_JOURNAL_DATA)dit(bf(tt(journal-data=<bool>))) 1790label(OPTION_FS_NOTAIL)dit(bf(tt(notail=<bool>))) 1791label(OPTION_FS_DIRSYNC)dit(bf(tt(dirsync=<bool>))) 1792 These options change non standard file attributes on operating systems and 1793 file systems that support these features, like Linux with ext2fs and 1794 successors, xfs, or reiserfs. See man 1 chattr for information on these 1795 options. Please note that there might be a race condition between creating 1796 the file and applying these options. 1797enddit() 1798 1799startdit()enddit()nl() 1800 1801 1802label(GROUP_PROCESS)em(bf(PROCESS option group)) 1803 1804Options of this group change the process properties instead of just affecting 1805one data channel. 1806For EXEC and SYSTEM addresses and for LISTEN and CONNECT type addresses with 1807option FORK, 1808these options apply to the child processes instead of the main socat process. 1809startdit() 1810label(OPTION_CHROOT)dit(bf(tt(chroot=<directory>))) 1811 Performs a code(chroot()) operation to link(<directory>)(TYPE_DIRECTORY) 1812 after processing the address (link(example)(EXAMPLE_OPTION_CHROOT)). This call might require root privilege. 1813label(OPTION_CHROOT_EARLY)dit(bf(tt(chroot-early=<directory>))) 1814 Performs a code(chroot()) operation to link(<directory>)(TYPE_DIRECTORY) 1815 before opening the address. This call might require root privilege. 1816label(OPTION_SETGID)dit(bf(tt(setgid=<group>))) 1817 Changes the primary link(<group>)(TYPE_GROUP) of the process after 1818 processing the address. This call might require root privilege. Please note 1819 that this option does not drop other group related privileges. 1820label(OPTION_SETGID_EARLY)dit(bf(tt(setgid-early=<group>))) 1821 Like link(setgit)(OPTION_SETGID) but is performed before opening the address. 1822label(OPTION_SETUID)dit(bf(tt(setuid=<user>))) 1823 Changes the link(<user>)(TYPE_USER) (owner) of the process after processing 1824 the address. This call might require root privilege. Please note that this 1825 option does not drop group related privileges. Check if option 1826 link(su)(OPTION_SUBSTUSER) better fits your needs. 1827label(OPTION_SETUID_EARLY)dit(bf(tt(setuid-early=<user>))) 1828 Like link(setuid)(OPTION_SETUID) but is performed before opening the 1829 address. 1830label(OPTION_SUBSTUSER)dit(bf(tt(su=<user>))) 1831 Changes the link(<user>)(TYPE_USER) (owner) and groups of the process after 1832 processing the address (link(example)(EXAMPLE_OPTION_SUBSTUSER)). This call might require root privilege. 1833label(OPTION_SUBSTUSER_DELAYED)dit(bf(tt(su-d=<user>))) 1834 Short name for tt(substuser-delayed). 1835 COMMENT(Short name for bf(tt(substuser-delayed) ).) 1836 Changes the link(<user>)(TYPE_USER) 1837 (owner) and groups of the process after processing the address (link(example)(EXAMPLE_OPTION_SUBSTUSER_DELAYED)). 1838 The user and his groups are retrieved em(before) a possible 1839 code(chroot()). This call might require root privilege. 1840label(OPTION_SETPGID)dit(bf(tt(setpgid=<pid_t>))) 1841 Makes the process a member of the specified process group 1842 link(<pid_t>)(TYPE_PID_T). If no value 1843 is given, or if the value is 0 or 1, the process becomes leader of a new 1844 process group. 1845label(OPTION_SETSID)dit(bf(tt(setsid))) 1846 Makes the process the leader of a new session (link(example)(EXAMPLE_OPTION_SETSID)). 1847enddit() 1848 1849startdit()enddit()nl() 1850 1851 1852label(GROUP_READLINE)em(bf(READLINE option group)) 1853 1854These options apply to the readline address type. 1855startdit() 1856label(OPTION_HISTORY)dit(bf(tt(history=<filename>))) 1857 Reads and writes history from/to link(<filename>)(TYPE_FILENAME) (link(example)(EXAMPLE_OPTION_HISTORY)). 1858label(OPTION_NOPROMPT)dit(bf(tt(noprompt))) 1859 Since version 1.4.0, socat per default tries to determine a prompt - 1860 that is then passed to the readline call - by remembering the last 1861 incomplete line of the output. With this option, socat does not pass a 1862 prompt to readline, so it begins line editing in the first column 1863 of the terminal. 1864label(OPTION_NOECHO)dit(bf(tt(noecho=<pattern>))) 1865 Specifies a regular pattern for a prompt that prevents the following input 1866 line from being displayed on the screen and from being added to the history. 1867 The prompt is defined as the text that was output to the readline address 1868 after the lastest newline character and before an input character was 1869 typed. The pattern is a regular expression, e.g. 1870 "^[Pp]assword:.*$" or "([Uu]ser:|[Pp]assword:)". See NOEXPAND(regex(7)) for details. 1871 (link(example)(EXAMPLE_OPTION_NOECHO)) 1872label(OPTION_PROMPT)dit(bf(tt(prompt=<string>))) 1873 Passes the string as prompt to the readline function. readline prints this 1874 prompt when stepping through the history. If this string matches a constant 1875 prompt issued by an interactive program on the other socat address, 1876 consistent look and feel can be achieved. 1877enddit() 1878 1879startdit()enddit()nl() 1880 1881 1882label(GROUP_APPLICATION)em(bf(APPLICATION option group)) 1883 1884This group contains options that work at data level. 1885Note that these options only apply to the "raw" data transferred by socat, 1886but not to protocol data used by addresses like 1887link(PROXY)(ADDRESS_PROXY_CONNECT). 1888startdit() 1889label(OPTION_CR)dit(bf(tt(cr))) 1890 Converts the default line termination character NL ('\n', 0x0a) to/from CR 1891 ('\r', 0x0d) when writing/reading on this channel. 1892label(OPTION_CRNL)dit(bf(tt(crnl))) 1893 Converts the default line termination character NL ('\n', 0x0a) to/from CRNL 1894 ("\r\n", 0x0d0a) when writing/reading on this channel (link(example)(EXAMPLE_OPTION_CRNL)). 1895 Note: socat simply strips all CR characters. 1896label(OPTION_IGNOREEOF)dit(bf(tt(ignoreeof))) 1897 When EOF occurs on this channel, socat() ignores it and tries to read more 1898 data (like "tail -f") (link(example)(EXAMPLE_OPTION_IGNOREEOF)). 1899label(OPTION_READBYTES)dit(bf(tt(readbytes=<bytes>))) 1900 socat() reads only so many bytes from this address (the address provides 1901 only so many bytes for transfer and pretends to be at EOF afterwards). 1902 Must be greater than 0. 1903label(OPTION_LOCKFILE)dit(bf(tt(lockfile=<filename>))) 1904 If lockfile exists, exits with error. If lockfile does not exist, creates it 1905 and continues, unlinks lockfile on exit. 1906label(OPTION_WAITLOCK)dit(bf(tt(waitlock=<filename>))) 1907 If lockfile exists, waits until it disappears. When lockfile does not exist, 1908 creates it and continues, unlinks lockfile on exit. 1909label(OPTION_ESCAPE)dit(bf(tt(escape=<int>))) 1910 Specifies the numeric code of a character that triggers EOF on the input 1911 stream. It is useful with a terminal in raw mode 1912 (link(example)(EXAMPLE_OPTION_ESCAPE)). 1913enddit() 1914 1915startdit()enddit()nl() 1916 1917 1918label(GROUP_SOCKET)em(bf(SOCKET option group)) 1919 1920These options are intended for all kinds of sockets, e.g. IP or unixdomain(). Most are applied with a code(setsockopt()) call. 1921startdit() 1922label(OPTION_BIND)dit(bf(tt(bind=<sockname>))) 1923 Binds the socket to the given socket address using the code(bind()) system 1924 call. The form of <sockname> is socket domain dependent: 1925 IP4 and IP6 allow the form [hostname|hostaddress][:(service|port)] (link(example)(EXAMPLE_OPTION_BIND_TCP4)), 1926 unixdomain() sockets require link(<filename>)(TYPE_FILENAME), 1927 VSOCK allow the form [cid][:(port)]. 1928label(OPTION_CONNECT_TIMEOUT)dit(bf(tt(connect-timeout=<seconds>))) 1929 Abort the connection attempt after <seconds> [link(timeval)(TYPE_TIMEVAL)] 1930 with error status. 1931label(OPTION_SO_BINDTODEVICE)dit(bf(tt(so-bindtodevice=<interface>))) 1932 Binds the socket to the given link(<interface>)(TYPE_INTERFACE). 1933 This option might require root privilege. 1934label(OPTION_SO_BROADCAST)dit(bf(tt(broadcast))) 1935 For datagram sockets, allows sending to broadcast addresses and receiving 1936 packets addressed to broadcast addresses. 1937COMMENT(label(OPTION_BSDCOMPAT)dit(bf(tt(bsdcompat))) 1938 Emulates some (old?) bugs of the BSD socket implementation.) 1939label(OPTION_DEBUG)dit(bf(tt(debug))) 1940 Enables socket debugging. 1941label(OPTION_DONTROUTE)dit(bf(tt(dontroute))) 1942 Only communicates with directly connected peers, does not use routers. 1943label(OPTION_KEEPALIVE)dit(bf(tt(keepalive))) 1944 Enables sending keepalives on the socket. 1945label(OPTION_LINGER)dit(bf(tt(linger=<seconds>))) 1946 Blocks code(shutdown()) or code(close()) until data transfers have finished 1947 or the given timeout [link(int)(TYPE_INT)] expired. 1948COMMENT(label(OPTION_NOREUSEADDR)dit(bf(tt(noreuseaddr))) 1949 Set the code(SO_NOREUSEADDR) socket option.) 1950label(OPTION_OOBINLINE)dit(bf(tt(oobinline))) 1951 Places out-of-band data in the input data stream. 1952label(OPTION_PRIORITY)dit(bf(tt(priority=<priority>))) 1953 Sets the protocol defined <priority> [link(<int>)(TYPE_INT)] for outgoing 1954 packets. 1955label(OPTION_RCVBUF)dit(bf(tt(rcvbuf=<bytes>))) 1956 Sets the size of the receive buffer after the code(socket()) call to 1957 <bytes> [link(int)(TYPE_INT)]. With TCP 1958 sockets, this value corresponds to the socket's maximal window size. 1959label(OPTION_RCVBUF_LATE)dit(bf(tt(rcvbuf-late=<bytes>))) 1960 Sets the size of the receive buffer when the socket is already 1961 connected to <bytes> [link(int)(TYPE_INT)]. 1962 With TCP sockets, this value corresponds to the socket's 1963 maximal window size. 1964label(OPTION_RCVLOWAT)dit(bf(tt(rcvlowat=<bytes>))) 1965 Specifies the minimum number of received bytes [link(int)(TYPE_INT)] until 1966 the socket layer will pass the buffered data to socat(). 1967label(OPTION_REUSEADDR)dit(bf(tt(reuseaddr))) 1968 Allows other sockets to bind to an address even if parts of it (e.g. the 1969 local port) are already in use by socat() (link(example)(EXAMPLE_OPTION_REUSEADDR)). 1970label(OPTION_SNDBUF)dit(bf(tt(sndbuf=<bytes>))) 1971 Sets the size of the send buffer after the code(socket()) call to 1972 <bytes> [link(int)(TYPE_INT)]. 1973label(OPTION_SNDBUF_LATE)dit(bf(tt(sndbuf-late=<bytes>))) 1974 Sets the size of the send buffer when the socket is connected to 1975 <bytes> [link(int)(TYPE_INT)]. 1976label(OPTION_SNDLOWAT)dit(bf(tt(sndlowat=<bytes>))) 1977 Specifies the minimum number of bytes in the send buffer until the socket 1978 layer will send the data to <bytes> [link(int)(TYPE_INT)]. 1979label(OPTION_PROTOCOL_FAMILY)dit(bf(tt(pf=<string>))) 1980 Forces the use of the specified IP version or protocol. <string> can be 1981 something like "ip4" or "ip6". The resulting value is 1982 used as first argument to the code(socket()) or code(socketpair()) calls. 1983 This option affects address resolution and the required syntax of bind and 1984 range options. 1985label(OPTION_SO_TYPE)dit(bf(tt(type=<type>))) 1986 Sets the type of the socket, specified as second argument to the 1987 code(socket()) or code(socketpair()) calls, to <type> 1988 [link(int)(TYPE_INT)]. Address resolution is not affected by this option. 1989 Under Linux, 1 means stream oriented socket, 2 means datagram socket, and 3 1990 means raw socket. 1991label(OPTION_SO_PROTOCOL)dit(bf(tt(protocol))) 1992 Sets the protocol of the socket, specified as third argument to the 1993 code(socket()) or code(socketpair()) calls, to <protocol> 1994 [link(int)(TYPE_INT)]. Address resolution is not affected by this option. 1995 6 means TCP, 17 means UDP. 1996COMMENT(label(OPTION_USELOOPBACK)dit(bf(tt(useloopback))) 1997 Sets the code(SO_USELOOPBACK) socket option.) 1998COMMENT(label(OPTION_ACCEPTCONN)dit(bf(tt(acceptconn))) 1999 Tries to set the code(SO_ACCEPTCONN) socket option.) 2000COMMENT(label(OPTION_ATTACHFILTER)dit(bf(tt(attachfilter))) 2001 Tries to set the code(SO_ATTACH_FILTER) socket option.) 2002COMMENT(label(OPTION_AUDIT)dit(bf(tt(audit))) 2003 Sets the code(SO_AUDIT) socket option.) 2004COMMENT(label(OPTION_CHSUMRECV)dit(bf(tt(cksumrecv))) 2005 Sets the code(SO_CKSUMRECV) socket option.) 2006COMMENT(label(OPTION_DETACHFILTER)dit(bf(tt(detachfilter))) 2007 Tries to set the code(SO_DETACH_FILTER) socket option.) 2008COMMENT(label(OPTION_DGRAMERRIND)dit(bf(tt(dgramerrind))) 2009 Sets the code(SO_DGRAM_ERRIND) socket option.) 2010COMMENT(label(OPTION_DONTLINGER)dit(bf(tt(dontlinger))) 2011 Sets the code(SO_DONTLINGER) socket option.) 2012COMMENT(label(OPTION_ERROR)dit(bf(tt(error))) 2013 Tries to set this read only socket option.) 2014COMMENT(label(OPTION_FIOSETOWN)dit(bf(tt(fiosetown=<pid_t>))) 2015 Sets the receiver of SIGIO.) 2016COMMENT(label(OPTION_KERNACCEPT)dit(bf(tt(kernaccept))) 2017 Sets the code(SO_KERNACCEPT) socket option.) 2018COMMENT(label(OPTION_NOCHECK)dit(bf(tt(nocheck))) 2019 Sets the code(SO_NO_CHECK) socket option. Undocumented...) 2020COMMENT(label(OPTION_PASSCRED)dit(bf(tt(passcred))) 2021 Set the code(SO_PASSCRED) socket option.) 2022COMMENT(label(OPTION_PEERCRED)dit(bf(tt(peercred))) 2023 This is a read-only socket option.) 2024label(OPTION_REUSEPORT)dit(bf(tt(reuseport))) 2025 Set the code(SO_REUSEPORT) socket option. 2026COMMENT(label(OPTION_SECURITYAUTHENTICATION)dit(bf(tt(securityauthentication))) 2027 Set the code(SO_SECURITY_AUTHENTICATION) socket option.) 2028COMMENT(label(OPTION_SECURITYENCRYPTIONNETWORK)dit(bf(tt(securityencryptionnetwork))) 2029 Set the code(SO_SECURITY_ENCRYPTION_NETWORK) socket option.) 2030COMMENT(label(OPTION_SECURITYENCRYPTIONTRANSPORT)dit(bf(tt(securityencryptiontransport))) 2031 Set the code(SO_SECURITY_ENCRYPTION_TRANSPORT) socket option.) 2032COMMENT(label(OPTION_SIOCSPGRP)dit(bf(tt(siocspgrp=<pid_t>))) 2033 Set the SIOCSPGRP with code(ioclt()) to enable SIGIO.) 2034COMMENT(label(OPTION_USEIFBUFS)dit(bf(tt(useifbufs))) 2035 Set the code(SO_USE_IFBUFS) socket option.) 2036label(OPTION_SO_TIMESTAMP)dit(bf(tt(so-timestamp))) 2037 Sets the SO_TIMESTAMP socket option. This enables receiving and logging of 2038 timestamp ancillary messages. 2039label(OPTION_SETSOCKOPT)dit(bf(tt(setsockopt=<level>:<optname>:<optval>))) 2040 Invokes tt(setsockopt()) for the socket with the given parameters. tt(level) 2041 [link(int)(TYPE_INT)] is used as second argument to tt(setsockopt()) and 2042 specifies the layer, e.g. SOL_TCP for TCP (6 on Linux), or SOL_SOCKET for 2043 the socket layer (1 on Linux). tt(optname) [link(int)(TYPE_INT)] is the 2044 third argument to tt(setsockopt()) and tells which socket option is to be 2045 set. For the actual numbers you might have to look up the appropriate include 2046 files of your system. For the 4th and 5th tt(setsockopt()) parameters, 2047 tt(value) [link(dalan)(TYPE_DATA)] specifies an arbitrary sequence of bytes 2048 that are passed to the function per pointer, with the automatically derived 2049 length parameter. 2050label(OPTION_SETSOCKOPT_INT)dit(bf(tt(setsockopt-int=<level>:<optname>:<optval>))) 2051 Like tt(setsockopt), but <optval> is a pointer to int [link(int)(TYPE_INT)] 2052label(OPTION_SETSOCKOPT_LISTEN)dit(bf(tt(setsockopt-listen=<level>:<optname>:<optval>))) 2053 Like tt(setsockopt), but for listen type addresses it is applied to the 2054 listening socket instead of the connected socket. 2055label(OPTION_SETSOCKOPT_STRING)dit(bf(tt(setsockopt-string=<level>:<optname>:<optval>))) 2056 Like tt(setsockopt), but <optval> is a link(string)(TYPE_STRING). 2057 This string is passed to the function with trailing null character, and the 2058 length parameter is automatically derived from the data. 2059enddit() 2060 2061startdit()enddit()nl() 2062 2063 2064label(GROUP_SOCK_UNIX)em(bf(UNIX option group)) 2065 2066These options apply to UNIX domain based addresses. 2067startdit() 2068label(OPTION_UNIX_TIGHTSOCKLEN)dit(bf(tt(unix-tightsocklen=[0|1]))) 2069 On socket operations, pass a socket address length that does not include the 2070 whole code(struct sockaddr_un) record but (besides other components) only 2071 the relevant part of the filename or abstract string. Default is 1. 2072enddit() 2073 2074label(GROUP_IP4) 2075label(GROUP_IP)em(bf(IP4 and IP6 option groups)) 2076 2077These options can be used with IPv4 and IPv6 based sockets. 2078startdit() 2079label(OPTION_TOS)dit(bf(tt(tos=<tos>))) 2080 Sets the TOS (type of service) field of outgoing packets to <tos> 2081 [link(byte)(TYPE_BYTE)] (see RFC 791). 2082label(OPTION_TTL)dit(bf(tt(ttl=<ttl>))) 2083 Sets the TTL (time to live) field of outgoing packets to <ttl> 2084 [link(byte)(TYPE_BYTE)]. 2085label(OPTION_IPOPTIONS)dit(bf(tt(ip-options=<data>))) 2086 Sets IP options like source routing. Must be given in binary form, 2087 recommended format is a leading "x" followed by an even number of hex 2088 digits. This option may be used multiple times, data are appended. 2089 E.g., to connect to host 10.0.0.1 via some gateway using a loose source 2090 route, use the gateway as address parameter and set a loose source route 2091 using the option code(ip-options=x8307040a000001).nl() 2092 IP options are defined in RFC 791. COMMENT(, RFC 2113)nl() 2093COMMENT( x00 end of option list 2094 x01 no operation (nop) 2095 x0211 security 2096 x03 loose source route 2097 x09 strict source route 2098 x07 record route 2099 x0804 stream ID 2100 x44 internet timestamp) 2101label(OPTION_MTUDISCOVER)dit(bf(tt(mtudiscover=<0|1|2>))) 2102 Takes 0, 1, 2 to never, want, or always use path MTU discover on this 2103 socket. 2104COMMENT(label(OPTION_HRDINCL)dit(bf(tt(ip-hdrincl))) 2105 Tell the raw socket that the application data includes the IP header.) 2106COMMENT(label(OPTION_IP_MULTICAST_LOOP)dit(bf(tt(ip-multicastloop))) 2107 Allow looping back outgoing multicast to the local interface.) 2108COMMENT(label(OPTION_IP_MULTICAST_TTL)dit(bf(tt(ip-multicastttl))) 2109 Set the TTL for outgoing multicast packets.) 2110label(OPTION_IP_PKTINFO)dit(bf(tt(ip-pktinfo))) 2111 Sets the IP_PKTINFO socket option. This enables receiving and logging of 2112 ancillary messages containing destination address and interface (Linux) 2113 (link(example)(EXAMPLE_ANCILLARY)). 2114COMMENT(label(OPTION_PKTOPTS)dit(bf(tt(ip-pktopts))) 2115 Set the IP_PKTOPTIONS socket option.) 2116label(OPTION_IP_RECVERR)dit(bf(tt(ip-recverr))) 2117 Sets the IP_RECVERR socket option. This enables receiving and logging of 2118 ancillary messages containing detailed error information. 2119label(OPTION_IP_RECVOPTS)dit(bf(tt(ip-recvopts))) 2120 Sets the IP_RECVOPTS socket option. This enables receiving and logging of IP 2121 options ancillary messages (Linux, *BSD). 2122label(OPTION_IP_RECVTOS)dit(bf(tt(ip-recvtos))) 2123 Sets the IP_RECVTOS socket option. This enables receiving and logging of TOS 2124 (type of service) ancillary messages (Linux). 2125label(OPTION_IP_RECVTTL)dit(bf(tt(ip-recvttl))) 2126 Sets the IP_RECVTTL socket option. This enables receiving and logging of TTL 2127 (time to live) ancillary messages (Linux, *BSD). 2128COMMENT(label(OPTION_RETOPTS)dit(bf(tt(ip-retopts))) 2129 Set the IP_RETOPTS socket option.) 2130label(OPTION_IP_RECVDSTADDR)dit(bf(tt(ip-recvdstaddr))) 2131 Sets the IP_RECVDSTADDR socket option. This enables receiving and logging of 2132 ancillary messages containing destination address (*BSD) 2133 (link(example)(EXAMPLE_ANCILLARY)). 2134label(OPTION_IP_RECVIF)dit(bf(tt(ip-recvif))) 2135 Sets the IP_RECVIF socket option. This enables receiving and logging of 2136 interface ancillary messages (*BSD) (link(example)(EXAMPLE_ANCILLARY)). 2137COMMENT(label(OPTION_ROUTERALERT)dit(bf(tt(routeralert))) 2138 Set the IP_ROUTER_ALERT socket option.) 2139label(OPTION_IP_ADD_MEMBERSHIP) 2140dit(bf(tt(ip-add-membership=<multicast-address:interface-address>))) 2141dit(bf(tt(ip-add-membership=<multicast-address:interface-name>))) 2142dit(bf(tt(ip-add-membership=<multicast-address:interface-index>))) 2143dit(bf(tt(ip-add-membership=<multicast-address:interface-address:interface-name>))) 2144dit(bf(tt(ip-add-membership=<multicast-address:interface-address:interface-index>))) 2145 Makes the socket member of the specified multicast group. This is currently 2146 only implemented for IPv4. The option takes the IP address of the multicast 2147 group and info about the desired network interface. The most common syntax 2148 is the first one, while the others are only available on systems that 2149 provide tt(struct mreqn) (Linux).nl() 2150 The indices of active network interfaces can be shown using the utility 2151 procan(). 2152label(OPTION_IP_ADD_SOURCE_MEMBERSHIP) 2153dit(bf(tt(ip-add-source-membership=<multicast-address:interface-address:source-address>))) 2154 Makes the socket member of the specified multicast group for the specified 2155 source, i.e. only multicast traffic from this address is to be delivered. 2156 This is currently only implemented for IPv4.nl() 2157label(OPTION_IP_MULTICAST_IF) 2158dit(bf(tt(ip-multicast-if=<hostname>))) 2159 Specifies hostname or address of the network interface to be used for 2160 multicast traffic. 2161label(OPTION_IP_MULTICAST_LOOP) 2162dit(bf(tt(ip-multicast-loop=<bool>))) 2163 Specifies if outgoing multicast traffic should loop back to the interface. 2164label(OPTION_IP_MULTICAST_TTL) 2165dit(bf(tt(ip-multicast-ttl=<byte>))) 2166 Sets the TTL used for outgoing multicast traffic. Default is 1. 2167label(OPTOIN_IP_TRANSPARENT) 2168dit(bf(tt(ip-transparent))) 2169 Sets the IP_TRANSPARENT socket option. 2170 This option might require root privilege. 2171label(OPTION_RES_DEBUG)dit(bf(tt(res-debug))) 2172label(OPTION_RES_AAONLY)dit(bf(tt(res-aaonly))) 2173label(OPTION_RES_USEVC)dit(bf(tt(res-usevc))) 2174label(OPTION_RES_PRIMARY)dit(bf(tt(res-primary))) 2175label(OPTION_RES_IGNTC)dit(bf(tt(res-igntc))) 2176label(OPTION_RES_RECURSE)dit(bf(tt(res-recurse))) 2177label(OPTION_RES_DEFNAMES)dit(bf(tt(res-defnames))) 2178label(OPTION_RES_STAYOPEN)dit(bf(tt(res-stayopen))) 2179label(OPTION_RES_DNSRCH)dit(bf(tt(res-dnsrch))) 2180 These options set the corresponding resolver (name resolution) option flags. 2181 Append "=0" to clear a default option. See man NOEXPAND(resolver(5)) for more 2182 information on these options. Note: these options are valid only for the 2183 address they are applied to. 2184 2185enddit() 2186 2187startdit()enddit()nl() 2188 2189 2190label(GROUP_IP6)em(bf(IP6 option group)) 2191 2192These options can only be used on IPv6 based sockets. See link(IP 2193options)(GROUP_IP) for options that can be applied to both IPv4 and IPv6 2194sockets. 2195startdit() 2196label(OPTION_IPV6_V6ONLY)dit(bf(tt(ipv6only=<bool>))) 2197 Sets the IPV6_V6ONLY socket option. If 0, the TCP stack will also accept 2198 connections using IPv4 protocol on the same port. The default is system 2199 dependent. 2200label(OPTION_IPV6_RECVDSTOPTS)dit(bf(tt(ipv6-recvdstopts))) 2201 Sets the IPV6_RECVDSTOPTS socket option. This enables receiving and logging 2202 of ancillary messages containing the destination options. 2203label(OPTION_IPV6_RECVHOPLIMIT)dit(bf(tt(ipv6-recvhoplimit))) 2204 Sets the IPV6_RECVHOPLIMIT socket option. This enables receiving and logging 2205 of ancillary messages containing the hoplimit. 2206label(OPTION_IPV6_RECVHOPOPTS)dit(bf(tt(ipv6-recvhopopts))) 2207 Sets the IPV6_RECVHOPOPTS socket option. This enables receiving and logging 2208 of ancillary messages containing the hop options. 2209label(OPTION_IPV6_RECVPKTINFO)dit(bf(tt(ipv6-recvpktinfo))) 2210 Sets the IPV6_RECVPKTINFO socket option. This enables receiving and logging 2211 of ancillary messages containing destination address and interface. 2212label(OPTION_IPV6_UNICAST_HOPS)dit(bf(tt(ipv6-unicast-hops=link(TYPE_INT)(<int>)))) 2213 Sets the IPV6_UNICAST_HOPS socket option. This sets the hop count limit 2214 (TTL) for outgoing unicast packets. 2215label(OPTION_IPV6_RECVRTHDR)dit(bf(tt(ipv6-recvrthdr))) 2216 Sets the IPV6_RECVRTHDR socket option. This enables receiving and logging 2217 of ancillary messages containing routing information. 2218label(OPTION_IPV6_TCLASS)dit(bf(tt(ipv6-tclass))) 2219 Sets the IPV6_TCLASS socket option. This sets the transfer class of outgoing 2220 packets. 2221label(OPTION_IPV6_RECVTCLASS)dit(bf(tt(ipv6-recvtclass))) 2222 Sets the IPV6_RECVTCLASS socket option. This enables receiving and logging 2223 of ancillary messages containing the transfer class. 2224enddit() 2225 2226startdit()enddit()nl() 2227 2228 2229label(GROUP_TCP)em(bf(TCP option group)) 2230 2231These options may be applied to TCP sockets. They work by invoking code(setsockopt()) with the appropriate parameters. 2232startdit() 2233label(OPTION_TCP_CORK)dit(bf(tt(cork))) 2234 Doesn't send packets smaller than MSS (maximal segment size). 2235label(OPTION_DEFER-ACCEPT)dit(bf(tt(defer-accept))) 2236 While listening, accepts connections only when data from the peer arrived. 2237label(OPTION_KEEPCNT)dit(bf(tt(keepcnt=<count>))) 2238 Sets the number of keepalives before shutting down the socket to 2239 <count> [link(int)(TYPE_INT)]. 2240label(OPTION_KEEPIDLE)dit(bf(tt(keepidle=<seconds>))) 2241 Sets the idle time before sending the first keepalive to <seconds> 2242 [link(int)(TYPE_INT)]. 2243label(OPTION_KEEPINTVL)dit(bf(tt(keepintvl=<seconds>))) 2244 Sets the interval between two keepalives to <seconds> 2245 [link(int)(TYPE_INT)]. 2246label(OPTION_LINGER2)dit(bf(tt(linger2=<seconds>))) 2247 Sets the time to keep the socket in FIN-WAIT-2 state to <seconds> 2248 [link(int)(TYPE_INT)]. 2249label(OPTION_MSS)dit(bf(tt(mss=<bytes>))) 2250 Sets the MSS (maximum segment size) after the code(socket()) call to <bytes> 2251 [link(int)(TYPE_INT)]. This 2252 value is then proposed to the peer with the SYN or SYN/ACK packet 2253 (link(example)(EXAMPLE_OPTION_MSS)). 2254label(OPTION_MSS_LATE)dit(bf(tt(mss-late=<bytes>))) 2255 Sets the MSS of the socket after connection has been established to <bytes> 2256 [link(int)(TYPE_INT)]. 2257label(OPTION_TCP_NODELAY)dit(bf(tt(nodelay))) 2258 Turns off the Nagle algorithm for measuring the RTT (round trip time). 2259label(OPTION_RFC1323)dit(bf(tt(rfc1323))) 2260 Enables RFC1323 TCP options: TCP window scale, round-trip time measurement 2261 (RTTM), and protect against wrapped sequence numbers (PAWS) (AIX). 2262label(OPTION_STDURG)dit(bf(tt(stdurg))) 2263 Enables RFC1122 compliant urgent pointer handling (AIX). 2264label(OPTION_SYNCNT)dit(bf(tt(syncnt=<count>))) 2265 Sets the maximal number of SYN retransmits during connect to <count> 2266 [link(int)(TYPE_INT)]. 2267COMMENT(label(OPTION_INFO)dit(bf(tt(info))) 2268 Tries to set the read-only TCP_INFO socket option.) 2269COMMENT(label(OPTION_WINDOW_CLAMP)dit(bf(tt(window-clamp))) 2270 Sets the TCP_WINDOW_CLAMP socket option.) 2271label(OPTION_TCP_MD5SIG)dit(bf(tt(md5sig))) 2272 Enables generation of MD5 digests on the packets (FreeBSD). 2273label(OPTION_TCP_NOOPT)dit(bf(tt(noopt))) 2274 Disables use of TCP options (FreeBSD, MacOSX). 2275label(OPTION_TCP_NOPUSH)dit(bf(tt(nopush))) 2276 sets the TCP_NOPUSH socket option (FreeBSD, MacOSX). 2277label(OPTION_TCP_SACK_DISABLE)dit(bf(tt(sack-disable))) 2278 Disables use the selective acknowledge feature (OpenBSD). 2279label(OPTION_TCP_SIGNATURE_ENABLE)dit(bf(tt(signature-enable))) 2280 Enables generation of MD5 digests on the packets (OpenBSD). 2281label(OPTION_TCP_ABORT_THRESHOLD)dit(bf(tt(abort-threshold=<milliseconds>))) 2282 Sets the time to wait for an answer of the peer on an established connection 2283 (HP-UX). 2284label(OPTION_TCP_CONN_ABORT_THRESHOLD)dit(bf(tt(conn-abort-threshold=<milliseconds>))) 2285 Sets the time to wait for an answer of the server during the initial connect 2286 (HP-UX). 2287label(OPTION_TCP_KEEPINIT)dit(bf(tt(keepinit))) 2288 Sets the time to wait for an answer of the server during NOEXPAND(connect()) before 2289 giving up. Value in half seconds, default is 150 (75s) (Tru64). 2290label(OPTION_TCP_PAWS)dit(bf(tt(paws))) 2291 Enables the "protect against wrapped sequence numbers" feature (Tru64). 2292label(OPTION_TCP_SACKENA)dit(bf(tt(sackena))) 2293 Enables selective acknowledge (Tru64). 2294label(OPTION_TCP_TSOPTENA)dit(bf(tt(tsoptena))) 2295 Enables the time stamp option that allows RTT recalculation on existing 2296 connections (Tru64). 2297enddit() 2298 2299startdit()enddit()nl() 2300 2301 2302label(GROUP_UDP)em(bf(UDP option group)) 2303 2304This option may be applied to UDP datagram sockets. 2305 2306startdit() 2307label(OPTION_UDP_IGNORE_PEERPORT)dit(bf(tt(udp-ignore-peerport>))) 2308 Address UDP-DATAGRAM expects incoming responses to come from the port 2309 specified in its second parameter. With this option, it accepts packets 2310 coming from any port. 2311enddit() 2312 2313startdit()enddit()nl() 2314 2315 2316label(GROUP_SCTP)em(bf(SCTP option group)) 2317 2318These options may be applied to SCTP stream sockets. 2319startdit() 2320label(OPTION_SCTP_NODELAY)dit(bf(tt(sctp-nodelay))) 2321 Sets the SCTP_NODELAY socket option that disables the Nagle algorithm. 2322label(OPTION_SCTP_MAXSEG)dit(bf(tt(sctp-maxseg=<bytes>))) 2323 Sets the SCTP_MAXSEG socket option to <bytes> [link(int)(TYPE_INT)]. This 2324 value is then proposed to the peer with the SYN or SYN/ACK packet. 2325enddit() 2326 2327startdit()enddit()nl() 2328 2329 2330em(bf(UDP, TCP, and SCTP option group)) 2331 2332Here we find options that are related to the network port mechanism and thus 2333can be used with UDP, TCP, and SCTP client and server addresses. 2334startdit() 2335label(OPTION_SOURCEPORT)dit(bf(tt(sourceport=<port>))) 2336 For outgoing (client) TCP and UDP connections, it sets the source 2337 link(<port>)(TYPE_PORT) using an extra code(bind()) call. 2338 With TCP or UDP listen addresses, socat immediately shuts down the 2339 connection if the client does not use this sourceport. UDP-RECV, 2340 UDP-RECVFROM, UDP-SENDTO, and UDP-DATAGRAM addresses ignore the packet when 2341 it does not match. 2342 (link(example)(EXAMPLE_OPTION_SOURCEPORT)). 2343label(OPTION_LOWPORT)dit(bf(tt(lowport))) 2344 Outgoing (client) TCP and UDP connections with this option use 2345 an unused random source port between 640 and 1023 incl. On UNIX class operating 2346 systems, this requires root privilege, and thus indicates that the 2347 client process is authorized by local root. 2348 TCP and UDP listen addresses with this option immediately shut down the 2349 connection if the client does not use a sourceport <= 1023. 2350 This mechanism can provide limited authorization under some circumstances. 2351enddit() 2352 2353startdit()enddit()nl() 2354 2355 2356label(GROUP_SOCKS)em(bf(SOCKS option group)) 2357 2358When using SOCKS type addresses, some socks specific options can be set. 2359startdit() 2360label(OPTION_SOCKSPORT)dit(bf(tt(socksport=<tcp service>))) 2361 Overrides the default "socks" service or port 1080 for the socks server 2362 port with link(<TCP service>)(TYPE_TCP_SERVICE). 2363label(OPTION_SOCKSUSER)dit(bf(tt(socksuser=<user>))) 2364 Sends the <user> [link(string)(TYPE_STRING)] in the username field to the 2365 socks server. Default is the actual user name ($LOGNAME or $USER) (link(example)(EXAMPLE_OPTION_SOCKSUSER)). 2366enddit() 2367 2368startdit()enddit()nl() 2369 2370 2371label(GROUP_HTTP)em(bf(HTTP option group)) 2372 2373Options that can be provided with HTTP type addresses. The only HTTP address 2374currently implemented is link(proxy-connect)(ADDRESS_PROXY_CONNECT). 2375 2376startdit() 2377label(OPTION_PROXYPORT)dit(bf(tt(proxyport=<TCP service>))) 2378 Overrides the default HTTP proxy port 8080 with 2379 link(<TCP service>)(TYPE_TCP_SERVICE). 2380label(OPTION_IGNORECR)dit(bf(tt(ignorecr))) 2381 The HTTP protocol requires the use of CR+NL as line terminator. When a proxy 2382 server violates this standard, socat might not understand its answer. 2383 This option directs socat to interprete NL as line terminator and 2384 to ignore CR in the answer. Nevertheless, socat sends CR+NL to the proxy. 2385label(OPTION_PROXY_AUTHORIZATION)dit(bf(tt(proxy-authorization=<username>:<password>))) 2386 Provide "basic" authentication to the proxy server. The argument to the 2387 option is used with a "Proxy-Authorization: Basic" header in base64 encoded 2388 form.nl() 2389 Note: username and password are visible for every user on the local machine 2390 in the process list; username and password are transferred to the proxy 2391 server unencrypted (base64 encoded) and might be sniffed. 2392label(OPTION_PROXY_AUTHORIZATION_FILE)dit(bf(tt(proxy-authorization-file=<filename>))) 2393 Like option link(proxy-authorization)(OPTION_PROXY_AUTHORIZATION), but the 2394 credentials are read from the file and therefore not visible in the process 2395 list.nl() 2396label(OPTION_PROXY_RESOLVE)dit(bf(tt(resolve))) 2397 Per default, socat sends to the proxy a CONNECT request containing the 2398 target hostname. With this option, socat resolves the hostname locally and 2399 sends the IP address. Please note that, according to RFC 2396, only name 2400 resolution to IPv4 addresses is implemented. 2401enddit() 2402 2403startdit()enddit()nl() 2404 2405 2406label(GROUP_RANGE)em(bf(RANGE option group)) 2407 2408These options check if a connecting client should be granted access. They can 2409be applied to listening and receiving network sockets. tcp-wrappers options 2410fall into this group. 2411startdit() 2412label(OPTION_RANGE)dit(bf(tt(range=<address-range>))) 2413 After accepting a connection, tests if the peer is within em(range). For 2414 IPv4 addresses, address-range takes the form address/bits, e.g. 2415 10.0.0.0/8, or address:mask, e.g. 10.0.0.0:255.0.0.0 (link(example)(EXAMPLE_OPTION_RANGE)); for IPv6, it is [ip6-address]/bits, e.g. [::1]/128. 2416 If the client address does not match, socat() refuses the connection attempt, issues a warning, and keeps 2417 listening/receiving. 2418label(OPTION_TCPWRAPPERS)dit(bf(tt(tcpwrap[=<name>]))) 2419 Uses Wietse Venema's libwrap (tcpd) library to determine 2420 if the client is allowed to connect. The configuration files are 2421 /etc/hosts.allow and /etc/hosts.deny per default, see "man 5 hosts_access" 2422 for more information. The optional <name> (type link(string)(TYPE_STRING)) 2423 is passed to the wrapper functions as daemon process name (link(example)(EXAMPLE_OPTION_TCPWRAPPERS)). 2424 If omitted, the basename of socats invocation (argv[0]) is passed. 2425 If both tcpwrap and range options are applied to an address, both 2426 conditions must be fulfilled to allow the connection. 2427label(OPTION_TCPWRAP_HOSTS_ALLOW_TABLE)dit(bf(tt(allow-table=<filename>))) 2428 Takes the specified file instead of /etc/hosts.allow. 2429label(OPTION_TCPWRAP_HOSTS_DENY_TABLE)dit(bf(tt(deny-table=<filename>))) 2430 Takes the specified file instead of /etc/hosts.deny. 2431label(OPTION_TCPWRAP_ETC)dit(bf(tt(tcpwrap-etc=<directoryname>))) 2432 Looks for hosts.allow and hosts.deny in the specified directory. Is 2433 overridden by options link(hosts-allow)(OPTION_TCPWRAP_HOSTS_ALLOW_TABLE) 2434 and link(hosts-deny)(OPTION_TCPWRAP_HOSTS_DENY_TABLE). 2435enddit() 2436 2437startdit()enddit()nl() 2438 2439 2440label(GROUP_LISTEN)em(bf(LISTEN option group)) 2441 2442Options specific to listening sockets. 2443startdit() 2444label(OPTION_BACKLOG)dit(bf(tt(backlog=<count>))) 2445 Sets the backlog value passed with the code(listen()) system call to <count> 2446 [link(int)(TYPE_INT)]. Default is 5. 2447label(OPTION_ACCEPT_TIMEOUT)dit(bf(tt(accept-timeout=<seconds>))) 2448 End waiting for a connection after <seconds> [link(timeval)(TYPE_TIMEVAL)] 2449 with error status. 2450label(OPTION_MAX_CHILDREN)dit(bf(tt(max-children=<count>))) 2451 Limits the number of concurrent child processes [link(int)(TYPE_INT)]. 2452 Default is no limit. 2453enddit() 2454startdit()enddit()nl() 2455 2456 2457label(GROUP_CHILD)em(bf(CHILD option group)) 2458 2459Options for addresses with multiple connections via child processes. 2460startdit() 2461label(OPTION_FORK)dit(bf(tt(fork))) 2462 After establishing a connection, handles its channel in a child process and 2463 keeps the parent process attempting to produce more connections, either by 2464 listening or by connecting in a loop (link(example)(EXAMPLE_OPTION_FORK)).nl() 2465 OPENSSL-CONNECT and OPENSSL-LISTEN differ in when they actually fork off the 2466 child: 2467 OPENSSL-LISTEN forks em(before) the SSL handshake, while OPENSSL-CONNECT 2468 forks em(afterwards). 2469 link(retry)(OPTION_RETRY) and link(forever)(OPTION_FOREVER) options are not 2470 inherited by the child process.nl() 2471 On some operating systems (e.g. FreeBSD) this option does not work for 2472 UDP-LISTEN addresses.nl() 2473enddit() 2474 2475startdit()enddit()nl() 2476 2477 2478label(GROUP_EXEC)em(bf(EXEC option group)) 2479 2480Options for addresses that invoke a program. 2481startdit() 2482label(OPTION_PATH)dit(bf(tt(path=<string>))) 2483 Overrides the PATH environment variable for searching the program with 2484 link(<string>)(TYPE_STRING). This 2485 code($PATH) value is effective in the child process too. 2486label(OPTION_LOGIN)dit(bf(tt(login))) 2487 Prefixes code(argv[0]) for the code(execvp()) call with '-', thus making a 2488 shell behave as login shell. 2489enddit() 2490 2491startdit()enddit()nl() 2492 2493 2494label(GROUP_FORK)em(bf(FORK option group)) 2495 2496EXEC or SYSTEM addresses invoke a program using a child process and transfer data between socat() and the program. The interprocess communication mechanism can be influenced with the following options. Per 2497default, a code(socketpair()) is created and assigned to stdin and stdout of 2498the child process, while stderr is inherited from the socat() process, and the 2499child process uses file descriptors 0 and 1 for communicating with the main 2500socat process. 2501startdit() 2502label(OPTION_NOFORK)dit(bf(tt(nofork))) 2503 Does not fork a subprocess for executing the program, instead calls NOEXPAND(execvp()) 2504 or NOEXPAND(system()) directly from the actual socat instance. This avoids the 2505 overhead of another process between the program and its peer, 2506 but introduces a lot of restrictions: 2507 startit() 2508 it() this option can only be applied to the second socat() address. 2509 it() it cannot be applied to a part of a link(dual)(ADDRESS_DUAL) address. 2510 it() the first socat address cannot be OPENSSL or READLINE 2511 it() socat options -b, -t, -D, -l, -v, -x become useless 2512 it() for both addresses, options ignoreeof, cr, and crnl become useless 2513 it() for the second address (the one with option nofork), options 2514 append, metaCOMMENT(async,) cloexec, flock, user, group, mode, nonblock, 2515 perm-late, setlk, and setpgid cannot be applied. Some of these could be 2516 used on the first address though. 2517 endit() 2518label(OPTION_PIPES)dit(bf(tt(pipes))) 2519 Creates a pair of unnamed pipes for interprocess communication instead of a 2520 socket pair. 2521label(OPTION_OPENPTY)dit(bf(tt(openpty))) 2522 Establishes communication with the sub process using a pseudo terminal 2523 created with code(openpty()) instead of the default (socketpair or ptmx). 2524label(OPTION_PTMX)dit(bf(tt(ptmx))) 2525 Establishes communication with the sub process using a pseudo terminal 2526 created by opening file(/dev/ptmx) or file(/dev/ptc) instead of the default 2527 (socketpair). 2528label(OPTION_PTY)dit(bf(tt(pty))) 2529 Establishes communication with the sub process using a pseudo terminal 2530 instead of a socket pair. Creates the pty with an available mechanism. If 2531 openpty and ptmx are both available, it uses ptmx because this is POSIX 2532 compliant (link(example)(EXAMPLE_OPTION_PTY)). 2533label(OPTION_CTTY)dit(bf(tt(ctty))) 2534 Makes the pty the controlling tty of the sub process (link(example)(EXAMPLE_OPTION_CTTY)). 2535label(OPTION_STDERR)dit(bf(tt(stderr))) 2536 Directs stderr of the sub process to its output channel by making stderr a 2537 code(dup()) of stdout (link(example)(EXAMPLE_OPTION_STDERR)). 2538label(OPTION_FDIN)dit(bf(tt(fdin=<fdnum>))) 2539 Assigns the sub processes input channel to its file descriptor 2540 link(<fdnum>)(TYPE_FDNUM) 2541 instead of stdin (0). The program started from the subprocess has to use 2542 this fd for reading data from socat() (link(example)(EXAMPLE_OPTION_FDIN)). 2543label(OPTION_FDOUT)dit(bf(tt(fdout=<fdnum>))) 2544 Assigns the sub processes output channel to its file descriptor 2545 link(<fdnum>)(TYPE_FDNUM) 2546 instead of stdout (1). The program started from the subprocess has to use 2547 this fd for writing data to socat() (link(example)(EXAMPLE_OPTION_FDOUT)). 2548label(OPTION_SIGHUP)label(OPTION_SIGINT)label(OPTION_SIGQUIT)dit(bf(tt(sighup)), bf(tt(sigint)), bf(tt(sigquit))) 2549 Has socat() pass signals of this type to the sub process. 2550 If no address has this option, socat terminates on these signals. 2551enddit() 2552 2553startdit()enddit()nl() 2554 2555 2556label(GROUP_TERMIOS)em(bf(TERMIOS option group)) 2557 2558For addresses that work on a tty (e.g., stdio, file:/dev/tty, exec:...,pty), the terminal parameters defined in the unix() termios mechanism are made available as address option parameters. 2559Please note that changes of the parameters of your interactive terminal 2560remain effective after socat()'s termination, so you might have to enter "reset" 2561or "stty sane" in your shell afterwards. 2562For EXEC and SYSTEM addresses with option PTY, 2563these options apply to the pty by the child processes. 2564 2565startdit() 2566label(OPTION_B0)dit(bf(tt(b0))) 2567 Disconnects the terminal. 2568label(OPTION_B19200)dit(bf(tt(b19200))) 2569 Sets the serial line speed to 19200 baud. Some other rates are possible; use 2570something like tt(socat -hh |grep ' b[1-9]') to find all speeds supported by 2571your implementation.nl() 2572Note: On some operating systems, these options may not be 2573available. Use link(ispeed)(OPTION_ISPEED) or link(ospeed)(OPTION_OSPEED) 2574instead. 2575label(OPTION_ECHO)dit(bf(tt(echo=<bool>))) 2576 Enables or disables local echo. 2577label(OPTION_ICANON)dit(bf(tt(icanon=<bool>))) 2578 Sets or clears canonical mode, enabling line buffering and some special 2579 characters. 2580label(OPTION_RAW)dit(bf(tt(raw))) 2581 Sets raw mode, thus passing input and output almost unprocessed. This option is obsolete, use option link(rawer)(OPTION_TERMIOS_RAWER) or link(cfmakeraw)(OPTION_TERMIOS_CFMAKERAW) instead. 2582label(OPTION_TERMIOS_RAWER)dit(bf(tt(rawer))) 2583 Makes terminal rawer than link(raw)(OPTION_RAW) option. This option implicitly turns off echo. (link(example)(EXAMPLE_OPTION_TERMIOS_RAWER)). 2584label(OPTION_TERMIOS_CFMAKERAW)dit(bf(tt(cfmakeraw))) 2585 Sets raw mode by invoking tt(cfmakeraw()) or by simulating this call. This option implicitly turns off echo. 2586label(OPTION_IGNBRK)dit(bf(tt(ignbrk=<bool>))) 2587 Ignores or interpretes the BREAK character (e.g., ^C) 2588label(OPTION_BRKINT)dit(bf(tt(brkint=<bool>))) 2589label(OPTION_BS0)dit(bf(tt(bs0))) 2590label(OPTION_BS1)dit(bf(tt(bs1))) 2591label(OPTION_BSDLY)dit(bf(tt(bsdly=<0|1>))) 2592label(OPTION_CLOCAL)dit(bf(tt(clocal=<bool>))) 2593 2594label(OPTION_CR0)label(OPTION_CR1)label(OPTION_CR2)label(OPTION_CR3) 2595mancommand(\.LP) 2596mancommand(\.nf) 2597mancommand(\fBcr0 2598cr1 2599cr2 2600cr3\fP) 2601mancommand(\.fi) 2602mancommand(\.IP) 2603htmlcommand(<dt><code><strong>cr0</strong><br> 2604<strong>cr1</strong><br> 2605<strong>cr2</strong><br> 2606<strong>cr3</strong></code><dd>) 2607 Sets the carriage return delay to 0, 1, 2, or 3, respectively. 2608 0 means no delay, the other values are terminal dependent. 2609 2610label(OPTION_CRDLY)dit(bf(tt(crdly=<0|1|2|3>))) 2611label(OPTION_CREAD)dit(bf(tt(cread=<bool>))) 2612label(OPTION_CRTSCTS)dit(bf(tt(crtscts=<bool>))) 2613 2614label(OPTION_CS5)label(OPTION_CS6)label(OPTION_CS7)label(OPTION_CS8) 2615mancommand(\.LP) 2616mancommand(\.nf) 2617mancommand(\fBcs5 2618cs6 2619cs7 2620cs8\fP) 2621mancommand(\.fi) 2622mancommand(\.IP) 2623htmlcommand(<dt><code><strong>cs5</strong><br> 2624<strong>cs6</strong><br> 2625<strong>cs7</strong><br> 2626<strong>cs8</strong></code><dd>) 2627 Sets the character size to 5, 6, 7, or 8 bits, respectively. 2628 2629label(OPTION_CSIZE)dit(bf(tt(csize=<0|1|2|3>))) 2630label(OPTION_CSTOPB)dit(bf(tt(cstopb=<bool>))) 2631 Sets two stop bits, rather than one. 2632label(OPTION_VDSUSP)dit(bf(tt(dsusp=<byte>))) 2633 Sets the value for the VDSUSP character that suspends the current foreground 2634 process and reactivates the shell (all except Linux). 2635label(OPTION_ECHOCTL)dit(bf(tt(echoctl=<bool>))) 2636 Echos control characters in hat notation (e.g. ^A) 2637label(OPTION_ECHOE)dit(bf(tt(echoe=<bool>))) 2638label(OPTION_ECHOK)dit(bf(tt(echok=<bool>))) 2639label(OPTION_ECHOKE)dit(bf(tt(echoke=<bool>))) 2640label(OPTION_ECHONL)dit(bf(tt(echonl=<bool>))) 2641label(OPTION_ECHOPRT)dit(bf(tt(echoprt=<bool>))) 2642label(OPTION_EOF)dit(bf(tt(eof=<byte>))) 2643label(OPTION_EOL)dit(bf(tt(eol=<byte>))) 2644label(OPTION_EOL2)dit(bf(tt(eol2=<byte>))) 2645label(OPTION_ERASE)dit(bf(tt(erase=<byte>))) 2646label(OPTION_DISCARD)dit(bf(tt(discard=<byte>))) 2647label(OPTION_FF0)dit(bf(tt(ff0))) 2648label(OPTION_FF1)dit(bf(tt(ff1))) 2649label(OPTION_FFDLY)dit(bf(tt(ffdly=<bool>))) 2650label(OPTION_FLUSHO)dit(bf(tt(flusho=<bool>))) 2651label(OPTION_HUPCL)dit(bf(tt(hupcl=<bool>))) 2652label(OPTION_ICRNL)dit(bf(tt(icrnl=<bool>))) 2653label(OPTION_IEXTEN)dit(bf(tt(iexten=<bool>))) 2654label(OPTION_IGNCR)dit(bf(tt(igncr=<bool>))) 2655label(OPTION_IGNPAR)dit(bf(tt(ignpar=<bool>))) 2656label(OPTION_IMAXBEL)dit(bf(tt(imaxbel=<bool>))) 2657label(OPTION_INLCR)dit(bf(tt(inlcr=<bool>))) 2658label(OPTION_INPCK)dit(bf(tt(inpck=<bool>))) 2659label(OPTION_INTR)dit(bf(tt(intr=<byte>))) 2660label(OPTION_ISIG)dit(bf(tt(isig=<bool>))) 2661label(OPTION_ISPEED)dit(bf(tt(ispeed=<unsigned-int>))) 2662 Set the baud rate for incoming data on this line.nl() 2663 See also: link(ospeed)(OPTION_OSPEED), link(b19200)(OPTION_B19200) 2664label(OPTION_ISTRIP)dit(bf(tt(istrip=<bool>))) 2665label(OPTION_IUCLC)dit(bf(tt(iuclc=<bool>))) 2666label(OPTION_IXANY)dit(bf(tt(ixany=<bool>))) 2667label(OPTION_IXOFF)dit(bf(tt(ixoff=<bool>))) 2668label(OPTION_IXON)dit(bf(tt(ixon=<bool>))) 2669label(OPTION_KILL)dit(bf(tt(kill=<byte>))) 2670label(OPTION_LNEXT)dit(bf(tt(lnext=<byte>))) 2671label(OPTION_MIN)dit(bf(tt(min=<byte>))) 2672label(OPTION_NL0)dit(bf(tt(nl0))) 2673 Sets the newline delay to 0. 2674label(OPTION_NL1)dit(bf(tt(nl1))) 2675label(OPTION_NLDLY)dit(bf(tt(nldly=<bool>))) 2676label(OPTION_NOFLSH)dit(bf(tt(noflsh=<bool>))) 2677label(OPTION_OCRNL)dit(bf(tt(ocrnl=<bool>))) 2678label(OPTION_OFDEL)dit(bf(tt(ofdel=<bool>))) 2679label(OPTION_OFILL)dit(bf(tt(ofill=<bool>))) 2680label(OPTION_OLCUC)dit(bf(tt(olcuc=<bool>))) 2681label(OPTION_ONLCR)dit(bf(tt(onlcr=<bool>))) 2682label(OPTION_ONLRET)dit(bf(tt(onlret=<bool>))) 2683label(OPTION_ONOCR)dit(bf(tt(onocr=<bool>))) 2684label(OPTION_OPOST)dit(bf(tt(opost=<bool>))) 2685 Enables or disables output processing; e.g., converts NL to CR-NL. 2686label(OPTION_OSPEED)dit(bf(tt(ospeed=<unsigned-int>))) 2687 Set the baud rate for outgoing data on this line.nl() 2688 See also: link(ispeed)(OPTION_ISPEED), link(b19200)(OPTION_B19200) 2689label(OPTION_PARENB)dit(bf(tt(parenb=<bool>))) 2690 Enable parity generation on output and parity checking for input. 2691label(OPTION_PARMRK)dit(bf(tt(parmrk=<bool>))) 2692label(OPTION_PARODD)dit(bf(tt(parodd=<bool>))) 2693label(OPTION_PENDIN)dit(bf(tt(pendin=<bool>))) 2694label(OPTION_QUIT)dit(bf(tt(quit=<byte>))) 2695label(OPTION_REPRINT)dit(bf(tt(reprint=<byte>))) 2696label(OPTION_SANE)dit(bf(tt(sane))) 2697 Brings the terminal to something like a useful default state. 2698label(OPTION_START)dit(bf(tt(start=<byte>))) 2699label(OPTION_STOP)dit(bf(tt(stop=<byte>))) 2700label(OPTION_SUSP)dit(bf(tt(susp=<byte>))) 2701label(OPTION_SWTC)dit(bf(tt(swtc=<byte>))) 2702label(OPTION_TAB0)dit(bf(tt(tab0))) 2703label(OPTION_TAB1)dit(bf(tt(tab1))) 2704label(OPTION_TAB2)dit(bf(tt(tab2))) 2705label(OPTION_TAB3)dit(bf(tt(tab3))) 2706label(OPTION_TABDLY)dit(bf(tt(tabdly=<unsigned-int>))) 2707label(OPTION_TIME)dit(bf(tt(time=<byte>))) 2708label(OPTION_TOSTOP)dit(bf(tt(tostop=<bool>))) 2709label(OPTION_VT0)dit(bf(tt(vt0))) 2710label(OPTION_VT1)dit(bf(tt(vt1))) 2711label(OPTION_VTDLY)dit(bf(tt(vtdly=<bool>))) 2712label(OPTION_WERASE)dit(bf(tt(werase=<byte>))) 2713label(OPTION_XCASE)dit(bf(tt(xcase=<bool>))) 2714label(OPTION_XTABS)dit(bf(tt(xtabs))) 2715label(OPTION_I_POP_ALL)dit(bf(tt(i-pop-all))) 2716 With UNIX System V STREAMS, removes all drivers from the stack. 2717label(OPTION_I_PUSH)dit(bf(tt(i-push=<string>))) 2718 With UNIX System V STREAMS, pushes the driver (module) with the given name 2719 (link(string)(TYPE_STRING)) onto the stack. For example, to make sure that a 2720 character device on Solaris supports termios etc, use the following options: 2721 tt(i-pop-all,i-push=ptem,i-push=ldterm,i-push=ttcompat) 2722enddit() 2723 2724startdit()enddit()nl() 2725 2726 2727label(GROUP_PTY)em(bf(PTY option group)) 2728 2729These options are intended for use with the link(pty)(ADDRESS_PTY) address 2730type. 2731 2732startdit() 2733label(OPTION_SYMBOLIC_LINK)dit(bf(tt(link=<filename>))) 2734 Generates a symbolic link that points to the actual pseudo terminal 2735 (pty). This might help 2736 to solve the problem that ptys are generated with more or less 2737 unpredictable names, making it difficult to directly access the socat 2738 generated pty automatically. With this option, the user can specify a "fix" 2739 point in the file hierarchy that helps him to access the actual pty 2740 (link(example)(EXAMPLE_OPTION_SYMBOLIC_LINK)). 2741 Beginning with socat() version 1.4.3, the symbolic link is removed when 2742 the address is closed (but see option link(unlink-close)(OPTION_UNLINK_CLOSE)). 2743label(OPTION_PTY_WAIT_SLAVE)dit(bf(tt(wait-slave))) 2744 Blocks the open phase until a process opens the slave side of the pty. 2745 Usually, socat continues after generating the pty with opening the next 2746 address or with entering the transfer loop. With the wait-slave option, 2747 socat waits until some process opens the slave side of the pty before 2748 continuing. 2749 This option only works if the operating system provides the tt(poll()) 2750 system call. And it depends on an undocumented behaviour of pty's, so it 2751 does not work on all operating systems. It has successfully been tested on 2752 Linux, FreeBSD, NetBSD, and on Tru64 with openpty. 2753label(OPTION_PTY_INTERVAL)dit(bf(tt(pty-interval=<seconds>))) 2754 When the link(wait-slave)(OPTION_PTY_WAIT_SLAVE) option is set, socat 2755 periodically checks the HUP condition using tt(poll()) to find if the pty's 2756 slave side has been opened. The default polling interval is 1s. Use the 2757 pty-interval option [link(timeval)(TYPE_TIMEVAL)] to change this value. 2758enddit() 2759 2760 2761startdit()enddit()nl() 2762 2763 2764label(GROUP_OPENSSL)em(bf(OPENSSL option group)) 2765 2766These options apply to the link(openssl)(ADDRESS_OPENSSL_CONNECT) and 2767link(openssl-listen)(ADDRESS_OPENSSL_LISTEN) address types. 2768 2769startdit() 2770label(OPTION_OPENSSL_CIPHERLIST)dit(bf(tt(cipher=<cipherlist>))) 2771 Specifies the list of ciphers that may be used for the connection. 2772 See the man page of code(ciphers), section bf(CIPHER LIST FORMAT), for 2773 detailed information about syntax, values, and default of <cipherlist>.nl() 2774 Several cipher strings may be given, separated by ':'. 2775 Some simple cipher strings: 2776 startdit() 2777 dit(3DES) Uses a cipher suite with triple DES. 2778 dit(MD5) Uses a cipher suite with MD5. 2779 dit(aNULL) Uses a cipher suite without authentication. 2780 dit(NULL) Does not use encryption. 2781 dit(HIGH) Uses a cipher suite with "high" encryption. 2782 enddit() 2783 Note that the peer must support the selected property, or the negotiation 2784 will fail. 2785label(OPTION_OPENSSL_METHOD)dit(bf(tt(method=<ssl-method>))) 2786 This option is based on deprecated functions and is only available when 2787 socat() was build with option tt(--with-openssl-method). 2788 Use option link(min-proto-version)(OPTION_OPENSSL_MIN_PROTO_VERSION) 2789 and maybe link(max-proto-version)(OPTION_OPENSSL_MAX_PROTO_VERSION) 2790 instead. 2791 Sets the protocol version to be used. Valid strings (not case sensitive) 2792 are: 2793 startdit() 2794 dit(tt(SSL2)) Select SSL protocol version 2. 2795 dit(tt(SSL3)) Select SSL protocol version 3. 2796 dit(tt(SSL23)) Select the best available SSL or TLS protocol. 2797 dit(tt(TLS1)) Select TLS protocol version 1. 2798 dit(tt(TLS1.1)) Select TLS protocol version 1.1. 2799 dit(tt(TLS1.2)) Select TLS protocol version 1.2. 2800 When this option is not provided OpenSSL negotiates the mothod with its 2801 peer. 2802 enddit() 2803label(OPTION_OPENSSL_MIN_PROTO_VERSION)dit(bf(tt(min-proto-version))) 2804 This option tells OpenSSL to use this or a later SSL/TLS protocol version 2805 and refuses to accept a lower/older protocol. Valid syntax is: 2806 startdit() 2807 dit(tt(SSL2)) Select SSL protocol version 2. 2808 dit(tt(SSL3)) Select SSL protocol version 3. 2809 dit(tt(TLS1)) dit(tt(TLS1.0)) Select TLS protocol version 1. 2810 dit(tt(TLS1.1)) Select TLS protocol version 1.1. 2811 dit(tt(TLS1.2)) Select TLS protocol version 1.2. 2812 dit(tt(TLS1.3)) Select TLS protocol version 1.3. 2813 enddit() 2814label(OPTION_OPENSSL_MAX_PROTO_VERSION)dit(bf(tt(openssl-max-proto-version))) 2815 This option is similar to link(min-proto-version)(OPTION_OPENSSL_MIN_PROTO_VERSION), 2816 however, it disallows use of a higher protocol version. Useful for testing 2817 the peer. 2818label(OPTION_OPENSSL_VERIFY)dit(bf(tt(verify=<bool>))) 2819 Controls check of the peer's certificate. Default is 1 (true). Disabling 2820 verify might open your socket for everyone, making the encryption useless! 2821label(OPTION_OPENSSL_CERTIFICATE)dit(bf(tt(cert=<filename>))) 2822 Specifies the file with the certificate and private key for authentication. 2823 The certificate must be in OpenSSL format (*.pem). 2824 With openssl-listen, use of this option is strongly 2825 recommended. Except with cipher aNULL, "no shared ciphers" error will 2826 occur when no certificate is given. 2827label(OPTION_OPENSSL_KEY)dit(bf(tt(key=<filename>))) 2828 Specifies the file with the private key. The private key may be in this 2829 file or in the file given with the link(cert)(OPTION_OPENSSL_CERTIFICATE) option. The party that has 2830 to proof that it is the owner of a certificate needs the private key. 2831label(OPTION_OPENSSL_DHPARAMS)dit(bf(tt(dhparams=<filename>))) 2832 Specifies the file with the Diffie Hellman parameters. These parameters may 2833 also be in the file given with the link(cert)(OPTION_OPENSSL_CERTIFICATE) 2834 option in which case the dhparams option is not needed. 2835label(OPTION_OPENSSL_CAFILE)dit(bf(tt(cafile=<filename>))) 2836 Specifies the file with the trusted (root) authority certificates. The file 2837 must be in PEM format and should contain one or more certificates. The party 2838 that checks the authentication of its peer trusts only certificates that are 2839 in this file. 2840label(OPTION_OPENSSL_CAPATH)dit(bf(tt(capath=<dirname>))) 2841 Specifies the directory with the trusted (root) certificates. The directory 2842 must contain certificates in PEM format and their hashes (see OpenSSL 2843 documentation) 2844label(OPTION_OPENSSL_EGD)dit(bf(tt(egd=<filename>))) 2845 On some systems, openssl requires an explicit source of random data. Specify 2846 the socket name where an entropy gathering daemon like egd provides random 2847 data, e.g. /dev/egd-pool. 2848label(OPTION_OPENSSL_PSEUDO)dit(bf(tt(pseudo))) 2849 On systems where openssl cannot find an entropy source and where no entropy 2850 gathering daemon can be utilized, this option activates a mechanism for 2851 providing pseudo entropy. This is achieved by taking the current time in 2852 microseconds for feeding the libc pseudo random number generator with an 2853 initial value. openssl is then feeded with output from NOEXPAND(random()) calls.nl() 2854 NOTE:This mechanism is not sufficient for generation of secure keys! 2855label(OPTION_OPENSSL_COMPRESS)dit(bf(tt(compress))) 2856 Enable or disable the use of compression for a connection. Setting this to 2857 "none" disables compression, setting it to "auto" lets OpenSSL choose the best 2858 available algorithm supported by both parties. The default is to not touch any 2859 compression-related settings. 2860 NOTE: Requires OpenSSL 0.9.8 or higher and disabling compression with 2861 OpenSSL 0.9.8 affects all new connections in the process. 2862label(OPTION_OPENSSL_COMMONNAME)dit(bf(tt(commonname=<string>))) 2863 Specify the commonname that the peer certificate must match. With 2864 link(OPENSSL-CONNECT)(ADDRESS_OPENSSL_CONNECT) address this overrides the 2865 given hostname or IP target address; with 2866 link(OPENSSL-LISTEN)(ADDRESS_OPENSSL_LISTEN) this turns on check of peer 2867 certificates commonname. This option has only meaning when option 2868 link(verify)(OPTION_OPENSSL_VERIFY) is not disabled and the chosen cipher 2869 provides a peer certificate. 2870label(OPTION_OPENSSL_NO_SNI)dit(bf(tt(no-sni=<bool>))) 2871 Do not use the client side Server Name Indication (SNI) feature that selects 2872 the desired server certificate.nl() 2873 Note: SNI is automatically used since socat() version 1.7.4.0 and uses 2874 link(commonname)(OPTION_OPENSSL_COMMONNAME) or the given host name. 2875label(OPTION_OPENSSL_SNIHOST)dit(bf(tt(snihost=<string>))) 2876 Set the client side Server Name Indication (SNI) host name different from 2877 the addressed server name or common name. This might be useful when the 2878 server certificate has multiple host names or wildcard names because the 2879 SNI host name is passed in cleartext to the server and might be eavesdropped; 2880 with this option a mock name of the desired certificate may be transferred. 2881label(OPTION_OPENSSL_FIPS)dit(bf(tt(fips))) 2882 Enables FIPS mode if compiled in. For info about the FIPS encryption 2883 implementation standard see lurl(http://oss-institute.org/fips-faq.html). 2884 This mode might require that the involved certificates are generated with a 2885 FIPS enabled version of openssl. Setting or clearing this option on one 2886 socat address affects all OpenSSL addresses of this process. 2887enddit() 2888 2889startdit()enddit()nl() 2890 2891 2892label(GROUP_RETRY)em(bf(RETRY option group)) 2893 2894Options that control retry of some system calls, especially connection 2895attempts. 2896 2897startdit() 2898label(OPTION_RETRY)dit(bf(tt(retry=<num>))) 2899 Number of retries before the connection or listen attempt is aborted. 2900 Default is 0, which means just one attempt. 2901label(OPTION_INTERVAL)dit(bf(tt(interval=<timespec>))) 2902 Time between consecutive attempts (seconds, 2903 [link(timespec)(TYPE_TIMESPEC)]). Default is 1 second. 2904label(OPTION_FOREVER)dit(bf(tt(forever))) 2905 Performs an unlimited number of retry attempts. 2906enddit() 2907 2908startdit()enddit()nl() 2909 2910 2911label(GROUP_TUN)em(bf(TUN option group)) 2912 2913Options that control Linux TUN/TAP interface device addresses. 2914 2915startdit() 2916label(OPTION_TUN_DEVICE)dit(bf(tt(tun-device=<device-file>))) 2917 Instructs socat to take another path for the TUN clone device. Default is 2918 tt(/dev/net/tun). 2919label(OPTION_TUN_NAME)dit(bf(tt(tun-name=<if-name>))) 2920 Gives the resulting network interface a specific name instead of the system 2921 generated (tun0, tun1, etc.) 2922label(OPTION_TUN_TYPE)dit(bf(tt(tun-type=[tun|tap]))) 2923 Sets the type of the TUN device; use this option to generate a TAP 2924 device. See the Linux docu for the difference between these types. 2925 When you try to establish a tunnel between two TUN devices, their types 2926 should be the same. 2927label(OPTION_IFF_NO_PI)dit(bf(tt(iff-no-pi))) 2928 Sets the IFF_NO_PI flag which controls if the device includes additional 2929 packet information in the tunnel. 2930 When you try to establish a tunnel between two TUN devices, these flags 2931 should have the same values. 2932label(OPTION_IFF_UP)dit(bf(tt(iff-up))) 2933 Sets the TUN network interface status UP. Strongly recommended. 2934label(OPTION_IFF_BROADCAST)dit(bf(tt(iff-broadcast))) 2935 Sets the BROADCAST flag of the TUN network interface. 2936label(OPTION_IFF_DEBUG)dit(bf(tt(iff-debug))) 2937 Sets the DEBUG flag of the TUN network interface. 2938label(OPTION_IFF_LOOPBACK)dit(bf(tt(iff-loopback))) 2939 Sets the LOOPBACK flag of the TUN network interface. 2940label(OPTION_IFF_POINTOPOINT)dit(bf(tt(iff-pointopoint))) 2941 Sets the POINTOPOINT flag of the TUN device. 2942label(OPTION_IFF_NOTRAILERS)dit(bf(tt(iff-notrailers))) 2943 Sets the NOTRAILERS flag of the TUN device. 2944label(OPTION_IFF_RUNNING)dit(bf(tt(iff-running))) 2945 Sets the RUNNING flag of the TUN device. 2946label(OPTION_IFF_NOARP)dit(bf(tt(iff-noarp))) 2947 Sets the NOARP flag of the TUN device. 2948label(OPTION_IFF_PROMISC)dit(bf(tt(iff-promisc))) 2949 Sets the PROMISC flag of the TUN device. 2950label(OPTION_IFF_ALLMULTI)dit(bf(tt(iff-allmulti))) 2951 Sets the ALLMULTI flag of the TUN device. 2952label(OPTION_IFF_MASTER)dit(bf(tt(iff-master))) 2953 Sets the MASTER flag of the TUN device. 2954label(OPTION_IFF_SLAVE)dit(bf(tt(iff-slave))) 2955 Sets the SLAVE flag of the TUN device. 2956label(OPTION_IFF_MULTICAST)dit(bf(tt(iff-multicast))) 2957 Sets the MULTICAST flag of the TUN device. 2958label(OPTION_IFFPORTSEL_)dit(bf(tt(iff-portsel))) 2959 Sets the PORTSEL flag of the TUN device. 2960label(OPTION_IFF_AUTOMEDIA)dit(bf(tt(iff-automedia))) 2961 Sets the AUTOMEDIA flag of the TUN device. 2962label(OPTION_IFF_DYNAMIC)dit(bf(tt(iff-dynamic))) 2963 Sets the DYNAMIC flag of the TUN device. 2964enddit() 2965 2966startdit()enddit()nl() 2967 2968 2969label(VALUES) 2970manpagesection(DATA VALUES) 2971 2972This section explains the different data types that address parameters and 2973address options can take. 2974 2975startdit() 2976label(TYPE_ADDRESS_RANGE)dit(address-range) 2977 Is currently only implemented for IPv4 and IPv6. See address-option 2978 link(`range')(OPTION_RANGE) 2979label(TYPE_BOOL)dit(bool) 2980 "0" or "1"; if value is omitted, "1" is taken. 2981label(TYPE_BYTE)dit(byte) 2982 An unsigned int number, read with code(strtoul()), lower or equal to 2983 code(UCHAR_MAX). 2984label(TYPE_COMMAND_LINE)dit(command-line) 2985 A string specifying a program name and its arguments, separated by single 2986 spaces. 2987label(TYPE_DATA)dit(data) 2988 This is a more general data specification. The given text string contains 2989 information about the target data type and value. Generally a leading 2990 character specifies the type of the following data item. In its specific 2991 context a default data type may exist.nl() 2992 Currently only the following specifications are implemented:nl() 2993 description( 2994 dit(i) A signed integer number, stored in host byte order.nl() 2995 Example: bf(i-1000) (Integer number -1000) 2996 dit(I) An unsigned integer number, stored in host byte order.nl() 2997 dit(l) A signed long integer number, stored in host byte order.nl() 2998 dit(L) An unsigned long integer number, stored in host byte order.nl() 2999 dit(s) A signed short integer number, stored in host byte order.nl() 3000 dit(S) An unsigned short integer number, stored in host byte order.nl() 3001 dit(b) A signed byte (signed char).nl() 3002 dit(B) An unsigned byte (unsigned char).nl() 3003 dit(x) Following is an even number of hex digits, stored as sequence of 3004 bytes.nl() 3005 Example: bf(x7f000001) (IP address 127.0.0.1) 3006 dit(") Following is a string that is used with the common conversions 3007 \n \r \t \f \b \a \e \0; the string must be closed with '"'. Please note 3008 that the quotes and backslashes need to be escaped from shell and socat() 3009 conversion.nl() 3010 Example: bf("Hello world!\n") 3011 dit(') A single char, with the usual conversions. Please note that the 3012 quotes and backslashes need to be escaped from shell and socat() conversion. 3013 nl() 3014 Example: bf('a') 3015 ) 3016 Data items may be separated with white space without need to repeat the type 3017 specifier again. 3018label(TYPE_DIRECTORY)dit(directory) 3019 A string with usual unix() directory name semantics. 3020label(TYPE_FACILITY)dit(facility) 3021 The name of a syslog facility in lower case characters. 3022label(TYPE_FDNUM)dit(fdnum) 3023 An unsigned int type, read with code(strtoul()), specifying a unix() file 3024 descriptor. 3025label(TYPE_FILENAME)dit(filename) 3026 A string with usual unix() filename semantics. 3027label(TYPE_GROUP)dit(group) 3028 If the first character is a decimal digit, the value is read with 3029 code(strtoul()) as unsigned integer specifying a group id. Otherwise, it 3030 must be an existing group name. 3031label(TYPE_INT)dit(int) 3032 A number following the rules of the code(strtol()) function with base 3033 "0", i.e. decimal number, octal number with leading "0", or hexadecimal 3034 number with leading "0x". The value must fit into a C int. 3035label(TYPE_INTERFACE)dit(interface) 3036 A string specifying the device name of a network interface 3037 as shown by ifconfig or procan, e.g. "eth0". 3038label(TYPE_IP_ADDRESS)dit(IP address) 3039 An IPv4 address in numbers-and-dots notation, an IPv6 address in hex 3040 notation enclosed in brackets, or a hostname that resolves to an IPv4 or an 3041 IPv6 address.nl() 3042 Examples: 127.0.0.1, [::1], www.dest-unreach.org, dns1 3043label(TYPE_IPV4_ADDRESS)dit(IPv4 address) 3044 An IPv4 address in numbers-and-dots notation or a hostname that resolves to 3045 an IPv4 address.nl() 3046 Examples: 127.0.0.1, www.dest-unreach.org, dns2 3047label(TYPE_IPV6_ADDRESS)dit(IPv6 address) 3048 An IPv6 address in hexnumbers-and-colons notation enclosed in brackets, or a 3049 hostname that resolves to an IPv6 address.nl() 3050 Examples: [::1], [1234:5678:9abc:def0:1234:5678:9abc:def0], 3051 ip6name.domain.org 3052label(TYPE_LONG)dit(long) 3053 A number read with code(strtol()). The value must fit into a C long. 3054label(TYPE_LONGLONG)dit(long long) 3055 A number read with code(strtoll()). The value must fit into a C long long. 3056label(TYPE_OFF)dit(off_t) 3057 An implementation dependend signed number, usually 32 bits, read with strtol 3058 or strtoll. 3059label(TYPE_OFF64)dit(off64_t) 3060 An implementation dependend signed number, usually 64 bits, read with strtol 3061 or strtoll. 3062label(TYPE_MODE_T)dit(mode_t) 3063 An unsigned integer, read with code(strtoul()), specifying mode (permission) 3064 bits. 3065label(TYPE_PID_T)dit(pid_t) 3066 A number, read with code(strtol()), specifying a process id. 3067label(TYPE_PORT)dit(port) 3068 A uint16_t (16 bit unsigned number) specifying a TCP or UDP port, read 3069 with code(strtoul()). 3070label(TYPE_PROTOCOL)dit(protocol) 3071 An unsigned 8 bit number, read with code(strtoul()). 3072label(TYPE_SIZE_T)dit(size_t) 3073 An unsigned number with size_t limitations, read with code(strtoul). 3074label(TYPE_SOCKNAME)dit(sockname) 3075 A socket address. See address-option link(`bind')(OPTION_BIND) 3076label(TYPE_STRING)dit(string) 3077 A sequence of characters, not containing '\0' and, depending on 3078 the position within the command line, ':', ',', or "!!". Note 3079 that you might have to escape shell meta characters in the command line. 3080label(TYPE_TCP_SERVICE)dit(TCP service) 3081 A service name, not starting with a digit, that is resolved by 3082 code(getservbyname()), or an unsigned int 16 bit number read with 3083 code(strtoul()). 3084label(TYPE_TIMEVAL)dit(timeval) 3085 A double float specifying seconds; the number is mapped into a 3086 struct timeval, consisting of seconds and microseconds. 3087label(TYPE_TIMESPEC)dit(timespec) 3088 A double float specifying seconds; the number is mapped into a 3089 struct timespec, consisting of seconds and nanoseconds. 3090label(TYPE_UDP_SERVICE)dit(UDP service) 3091 A service name, not starting with a digit, that is resolved by 3092 code(getservbyname()), or an unsigned int 16 bit number read with 3093 code(strtoul()). 3094label(TYPE_UNSIGNED_INT)dit(unsigned int) 3095 A number read with code(strtoul()). The value must fit into a C unsigned 3096 int. 3097label(TYPE_USER)dit(user) 3098 If the first character is a decimal digit, the value is read with 3099 code(strtoul()) as unsigned integer specifying a user id. Otherwise, it must 3100 be an existing user name. 3101label(TYPE_VSOCK_ADDRESS)dit(VSOCK cid) 3102 A uint32_t (32 bit unsigned number) specifying a VSOCK Context Identifier 3103 (CID), read with code(strtoul()). 3104 There are several special addresses: VMADDR_CID_ANY (-1U) means any address 3105 for binding; VMADDR_CID_HOST (2) is the well-known address of the host. 3106label(TYPE_VSOCK_PORT)dit(VSOCK port) 3107 A uint32_t (32 bit unsigned number) specifying a VSOCK port, read 3108 with code(strtoul()). 3109enddit() 3110 3111 3112label(EXAMPLES) 3113manpagesection(EXAMPLES) 3114 3115 3116startdit() 3117 3118label(EXAMPLE_ADDRESS_TCP4_CONNECT) 3119dit(bf(tt(socat - TCP4:www.domain.org:80))) 3120 3121transfers data between link(STDIO)(ADDRESS_STDIO) (-) and a 3122link(TCP4)(ADDRESS_TCP4_CONNECT) connection to port 80 of host 3123www.domain.org. This example results in an interactive connection similar to 3124telnet or netcat. The stdin terminal parameters are not changed, so you may 3125close the relay with ^D or abort it with ^C. 3126 3127label(EXAMPLE_ADDRESS_READLINE) 3128label(EXAMPLE_OPTION_HISTORY) 3129mancommand(\.LP) 3130mancommand(\.nf) 3131mancommand(\fBsocat -d -d READLINE,history=$HOME/.http_history \\ 3132TCP4:www.domain.org:www,crnl\fP) 3133mancommand(\.fi) 3134 3135htmlcommand(<dt><code><strong>socat -d -d READLINE,history=$HOME/.http_history \</strong><br> 3136<strong>TCP4:www.domain.org:www,crnl</strong></code><dd>) 3137 3138this is similar to the previous example, but you can edit the current line in a 3139bash like manner (link(READLINE)(ADDRESS_READLINE)) and use the 3140link(history)(OPTION_HISTORY) file .http_history; socat() prints messages about 3141progress (link(-d -d)(option_d_d)). The port is specified by service name 3142(www), and correct network line termination characters 3143(link(crnl)(OPTION_CRNL)) instead of NL are used. 3144 3145 3146label(EXAMPLE_ADDRESS_TCP4_LISTEN) 3147dit(bf(tt(socat TCP4-LISTEN:www TCP4:www.domain.org:www))) 3148 3149installs a simple TCP port forwarder. With 3150link(TCP4-LISTEN)(ADDRESS_TCP4_LISTEN) it listens on local port "www" until a 3151connection comes in, accepts it, then connects to the remote host 3152(link(TCP4)(ADDRESS_TCP4_CONNECT)) and starts data transfer. It will not accept 3153a second connection. 3154 3155label(EXAMPLE_OPTION_BIND_TCP4) 3156label(EXAMPLE_OPTION_REUSEADDR) 3157label(EXAMPLE_OPTION_FORK) 3158label(EXAMPLE_OPTION_SUBSTUSER) 3159label(EXAMPLE_OPTION_RANGE) 3160mancommand(\.LP) 3161mancommand(\.nf) 3162mancommand(\fBsocat -d -d -lmlocal2 \\ 3163TCP4-LISTEN:80,bind=myaddr1,reuseaddr,fork,su=nobody,range=10.0.0.0/8 \\ 3164TCP4:www.domain.org:80,bind=myaddr2\fP) 3165mancommand(\.fi) 3166 3167htmlcommand(<dt><code><strong>socat -d -d -lmlocal2 \</strong><br> 3168<strong>TCP4-LISTEN:80,bind=myaddr1,su=nobody,fork,range=10.0.0.0/8,reuseaddr \</strong><br> 3169<strong>TCP4:www.domain.org:80,bind=myaddr2</strong></code><dd>) 3170 3171TCP port forwarder, each side bound to another local IP address 3172(link(bind)(OPTION_BIND)). This example handles an almost 3173arbitrary number of parallel or consecutive connections by 3174link(fork)(OPTION_FORK)'ing a new 3175process after each code(accept()). It provides a little security by 3176link(su)(OPTION_SUBSTUSER)'ing to user 3177nobody after forking; it only permits connections from the private 10 network 3178(link(range)(OPTION_RANGE)); due to link(reuseaddr)(OPTION_REUSEADDR), it 3179allows immediate restart after master process's termination, even if some child 3180sockets are not completely shut down. 3181With link(-lmlocal2)(option_lm), socat logs to stderr until successfully 3182reaching the accept loop. Further logging is directed to syslog with facility 3183local2. 3184 3185label(EXAMPLE_ADDRESS_EXEC) 3186label(EXAMPLE_OPTION_TCPWRAPPERS) 3187label(EXAMPLE_OPTION_CHROOT) 3188label(EXAMPLE_OPTION_SUBSTUSER_DELAYED) 3189label(EXAMPLE_OPTION_PTY) 3190label(EXAMPLE_OPTION_STDERR) 3191mancommand(\.LP) 3192mancommand(\.nf) 3193mancommand(\fBsocat TCP4-LISTEN:5555,fork,tcpwrap=script \\ 3194EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr\fP) 3195mancommand(\.fi) 3196 3197htmlcommand(<dt><code><strong>socat TCP4-LISTEN:5555,fork,tcpwrap=script \</strong><br> 3198<strong>EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr</strong></code><dd>) 3199 3200a simple server that accepts connections 3201(link(TCP4-LISTEN)(ADDRESS_TCP4_LISTEN)) and link(fork)(OPTION_FORK)'s a new 3202child process for each connection; every child acts as single relay. 3203The client must match the rules for daemon process name "script" in 3204/etc/hosts.allow and /etc/hosts.deny, otherwise it is refused access (see "man 32055 hosts_access"). 3206For link(EXEC)(ADDRESS_EXEC)'uting the program, the child process 3207link(chroot)(OPTION_CHROOT)'s 3208to file(/home/sandbox), link(su)(OPTION_SUBSTUSER)'s to user sandbox, and then starts 3209the program file(/home/sandbox/bin/myscript). Socat() and 3210myscript communicate via a pseudo tty (link(pty)(OPTION_PTY)); myscript's 3211link(stderr)(OPTION_STDERR) is redirected to stdout, 3212so its error messages are transferred via socat() to the connected client. 3213 3214label(EXAMPLE_OPTION_FDIN) 3215label(EXAMPLE_OPTION_FDOUT) 3216label(EXAMPLE_OPTION_CRNL) 3217label(EXAMPLE_OPTION_MSS) 3218mancommand(\.LP) 3219mancommand(\.nf) 3220mancommand(\fBsocat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \\ 3221TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512\fP) 3222mancommand(\.fi) 3223 3224htmlcommand(<dt><code><strong>socat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \</strong><br> 3225<strong>TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512</strong></code><dd>) 3226 3227file(mail.sh) is a shell script, distributed with socat(), that implements a 3228simple 3229SMTP client. It is programmed to "speak" SMTP on its FDs 3 (in) and 4 (out). 3230The link(fdin)(OPTION_FDIN) and link(fdout)(OPTION_FDOUT) options tell socat() 3231to use these FDs for communication with 3232the program. Because mail.sh inherits stdin and stdout while socat() does not 3233use them, the script can read a 3234mail body from stdin. Socat() makes alias1 your local source address 3235(link(bind)(OPTION_BIND)), cares for correct network line termination 3236(link(crnl)(OPTION_CRNL)) and sends 3237at most 512 data bytes per packet (link(mss)(OPTION_MSS)). 3238 3239 3240label(EXAMPLE_ADDRESS_GOPEN) 3241label(EXAMPLE_OPTION_TERMIOS_RAWER) 3242label(EXAMPLE_OPTION_ESCAPE) 3243dit(bf(tt(socat -,escape=0x0f /dev/ttyS0,rawer,crnl))) 3244 3245opens an interactive connection via the serial line, e.g. for talking with a 3246modem. link(rawer)(OPTION_TERMIOS_RAWER) sets the console's and 3247ttyS0's terminal parameters to practicable values, link(crnl)(OPTION_CRNL) 3248converts to correct newline characters. link(escape)(OPTION_ESCAPE) allows 3249terminating the socat process with character control-O. 3250Consider using link(READLINE)(ADDRESS_READLINE) instead of the first address. 3251 3252 3253label(EXAMPLE_ADDRESS_UNIX_LISTEN) 3254label(EXAMPLE_ADDRESS_SOCKS4) 3255label(EXAMPLE_OPTION_SOCKSUSER) 3256label(EXAMPLE_OPTION_SOURCEPORT) 3257mancommand(\.LP) 3258mancommand(\.nf) 3259mancommand(\fBsocat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \\ 3260SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20\fP) 3261mancommand(\.fi) 3262 3263htmlcommand(<dt><code><strong>socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \</strong><br> 3264<strong>SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20</strong></code><dd>) 3265 3266with link(UNIX-LISTEN)(ADDRESS_UNIX_LISTEN), socat() opens a listening 3267unixdomain() socket file(/tmp/.X11-unix/X1). This path corresponds 3268to local XWindow display :1 on your machine, so XWindow client connections to 3269DISPLAY=:1 are accepted. Socat() then speaks with 3270the link(SOCKS4)(ADDRESS_SOCKS4) server host.victim.org that might permit 3271link(sourceport)(OPTION_SOURCEPORT) 20 based connections due to an FTP related 3272weakness in its static IP filters. Socat() 3273pretends to be invoked by link(socksuser)(OPTION_SOCKSUSER) nobody, and 3274requests to be connected to 3275loopback port 6000 (only weak sockd configurations will allow this). So we get 3276a connection to the victims XWindow server and, if it does not require MIT 3277cookies or Kerberos authentication, we can start work. Please note that there 3278can only be one connection at a time, because TCP can establish only one 3279session with a given set of addresses and ports. 3280 3281 3282label(EXAMPLE_option_u) 3283label(EXAMPLE_OPTION_IGNOREEOF) 3284dit(bf(tt(socat -u /tmp/readdata,seek-end=0,ignoreeof -))) 3285 3286this is an example for unidirectional data transfer 3287(link(-u)(option_u)). Socat() transfers data 3288from file /tmp/readdata (implicit address link(GOPEN)(ADDRESS_GOPEN)), starting 3289at its current end (link(seek-end)(OPTION_SEEK_END)=0 lets socat() start 3290reading at current end of file; use link(seek)(OPTION_SEEK)=0 or no 3291seek option to first read the existing data) in a "tail -f" like mode 3292(link(ignoreeof)(OPTION_IGNOREEOF)). The "file" 3293might also be a listening unixdomain() socket (do not use a seek option then). 3294 3295 3296label(EXAMPLE_OPTION_SETSID) 3297label(EXAMPLE_OPTION_CTTY) 3298mancommand(\.LP) 3299mancommand(\.nf) 3300mancommand(\fB(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) | 3301socat - EXEC:'ssh -l user server',pty,setsid,ctty\fP) 3302mancommand(\.fi) 3303 3304htmlcommand(<dt><code><strong>(sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |</strong><br> 3305<strong>socat - EXEC:'ssh -l user server',pty,setsid,ctty</strong></code><dd>) 3306 3307link(EXEC)(ADDRESS_EXEC)'utes an ssh session to server. Uses a link(pty)(OPTION_PTY) for communication between socat() and 3308ssh, makes it ssh's controlling tty (link(ctty)(OPTION_CTTY)), 3309and makes this pty the owner of 3310a new process group (link(setsid)(OPTION_SETSID)), so ssh accepts the password from socat(). 3311 3312 3313label(EXAMPLE_ADDRESS_OPEN) 3314label(EXAMPLE_OPTION_CREAT) 3315label(EXAMPLE_OPTION_APPEND) 3316mancommand(\.LP) 3317mancommand(\.nf) 3318mancommand(\fBsocat -u TCP4-LISTEN:3334,reuseaddr,fork \\ 3319OPEN:/tmp/in.log,creat,append\fP) 3320mancommand(\.fi) 3321 3322htmlcommand(<dt><code><strong>socat -u TCP4-LISTEN:3334,reuseaddr,fork \</strong><br> 3323<strong>OPEN:/tmp/in.log,creat,append</strong></code><dd>) 3324 3325implements a simple network based message collector. 3326For each client connecting to port 3334, a new child process is generated (option link(fork)(OPTION_FORK)). 3327All data sent by the clients are link(append)(OPTION_APPEND)'ed to the file /tmp/in.log. 3328If the file does not exist, socat link(creat)(OPTION_O_CREAT)'s it. 3329Option link(reuseaddr)(OPTION_REUSEADDR) allows immediate restart of the server 3330process. 3331 3332COMMENT( 3333dit(bf(tt(socat TCP4-LISTEN:3335,reuseaddr,fork OPEN:/tmp/motd,rdonly))) 3334 3335implements a simple network based motd server. 3336For each client connecting to port 3335, a new child process is generated 3337(option link(fork)(OPTION_FORK)). 3338The contents of the file /tmp/motd is sent to each client. 3339Messages sent by clients result in an error due to option link(rdonly)(OPTION_RDONLY). 3340Option link(reuseaddr)(OPTION_REUSEADDR) allows immediate restart of the server 3341process. 3342) 3343COMMENT( 3344dit(bf(tt(socat - TCP4-LISTEN:8080,mtudiscover=0,rcvbuf=2048))) 3345 3346changes some socket parameters to confuse active OS fingerprinting methods. 3347link(mtudiscover)(OPTION_MTUDISCOVER)=0 sets the DF (don'ft fragment flag) in 3348the IP packets to 0 and link(rcvbuf)(OPTION_RCVBUF) changes the initial TCP 3349window size. 3350) 3351 3352label(EXAMPLE_OPTION_NOECHO) 3353dit(bf(tt(socat READLINE,noecho='[Pp]assword:' EXEC:'ftp ftp.server.com',pty,setsid,ctty))) 3354 3355wraps a command line history (link(READLINE)(ADDRESS_READLINE)) around the link(EXEC)(ADDRESS_EXEC)'uted ftp client utility. 3356This allows editing and reuse of FTP commands for relatively comfortable 3357browsing through the ftp directory hierarchy. The password is echoed! 3358 link(pty)(OPTION_PTY) is required to have ftp issue a prompt. 3359Nevertheless, there may occur some confusion with the password and FTP 3360prompts. 3361 3362 3363label(EXAMPLE_ADDRESS_PTY) 3364label(EXAMPLE_OPTION_SYMBOLIC_LINK) 3365label(EXAMPLE_OPTION_WAIT_SLAVE) 3366label(EXAMPLE_OPTION_NONBLOCK) 3367mancommand(\.LP) 3368mancommand(\.nf) 3369mancommand(\fBsocat PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \\\bf) 3370mancommand(\fBEXEC:"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"\fP) 3371mancommand(\.fi) 3372 3373htmlcommand(<dt><code><strong>socat PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \</strong><br> 3374<strong>EXEC:'"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"'</strong></code><dd>) 3375 3376generates a pseudo terminal 3377device (link(PTY)(ADDRESS_PTY)) on the client that can be reached under the 3378symbolic link(link)(OPTION_SYMBOLIC_LINK) file($HOME/dev/vmodem0). 3379An application that expects a serial line or modem 3380can be configured to use file($HOME/dev/vmodem0); its traffic will be directed 3381to a modemserver via ssh where another socat instance links it to 3382file(/dev/ttyS0). 3383 3384 3385mancommand(\.LP) 3386mancommand(\.nf) 3387mancommand(\fBsocat TCP4-LISTEN:2022,reuseaddr,fork \\ 3388PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass\fP) 3389mancommand(\.fi) 3390 3391htmlcommand(<dt><code><strong>socat TCP4-LISTEN:2022,reuseaddr,fork \</strong><br> 3392<strong>PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass</strong></code><dd>) 3393 3394starts a forwarder that accepts connections on port 2022, and directs them 3395through the link(proxy)(ADDRESS_PROXY_CONNECT) daemon listening on port 3128 3396(link(proxyport)(OPTION_PROXYPORT)) on host proxy, using the 3397CONNECT method, where they are authenticated as "user" with "pass" (link(proxyauth)(OPTION_PROXY_AUTHORIZATION)). The proxy 3398should establish connections to host www.domain.org on port 22 then. 3399 3400 3401label(EXAMPLE_ADDRESS_OPENSSL_CONNECT) 3402dit(bf(tt(socat - SSL:server:4443,cafile=server.crt,cert=client.pem))) 3403 3404is an OpenSSL client that tries to establish a secure connection to an SSL 3405server. Option link(cafile)(OPTION_OPENSSL_CAFILE) specifies a file that 3406contains trust certificates: we trust the server only when it presents one of 3407these certificates and proofs that it owns the related private key. 3408Otherwise the connection is terminated. 3409With link(cert)(OPTION_OPENSSL_CERTIFICATE) a file containing the client certificate 3410and the associated private key is specified. This is required in case the 3411server wishes a client authentication; many Internet servers do not.nl() 3412The first address ('-') can be replaced by almost any other socat address. 3413 3414 3415label(EXAMPLE_ADDRESS_OPENSSL_LISTEN) 3416dit(bf(tt(socat OPENSSL-LISTEN:4443,reuseaddr,pf=ip4,fork,cert=server.pem,cafile=client.crt PIPE))) 3417 3418is an OpenSSL server that accepts TCP connections, presents the certificate 3419from the file server.pem and forces the client to present a certificate that is 3420verified against cafile.crt.nl() 3421The second address ('PIPE') can be replaced by almost any other socat 3422address.nl() 3423For instructions on generating and distributing OpenSSL keys and certificates 3424see the additional socat docu tt(socat-openssl.txt). 3425 3426 3427dit(bf(tt(echo |socat -u - file:/tmp/bigfile,create,largefile,seek=100000000000))) 3428 3429creates a 100GB sparse file; this requires a file system type that 3430supports this (ext2, ext3, reiserfs, jfs; not minix, vfat). The operation of 3431writing 1 byte might take long (reiserfs: some minutes; ext2: "no" time), and 3432the resulting file can consume some disk space with just its inodes (reiserfs: 34332MB; ext2: 16KB). 3434 3435 3436dit(bf(tt(socat tcp-l:7777,reuseaddr,fork system:'filan -i 0 -s >&2',nofork))) 3437 3438listens for incoming TCP connections on port 7777. For each accepted 3439connection, invokes a shell. This shell has its stdin and stdout directly 3440connected to the TCP socket (link(nofork)(OPTION_NOFORK)). The shell starts filan and lets it print the socket addresses to 3441stderr (your terminal window). 3442 3443 3444dit(bf(tt(echo -e "\0\14\0\0\c" |socat -u - file:/usr/bin/squid.exe,seek=0x00074420))) 3445 3446functions as primitive binary editor: it writes the 4 bytes 000 014 000 000 to 3447the executable /usr/bin/squid at offset 0x00074420 (this is a real world patch 3448to make the squid executable from Cygwin run under Windows, actual per May 2004). 3449 3450 3451dit(bf(tt(socat - tcp:www.blackhat.org:31337,readbytes=1000))) 3452 3453connects to an unknown service and prevents being flooded. 3454 3455 3456label(EXAMPLE_END_CLOSE) 3457dit(bf(tt(socat -U TCP:target:9999,end-close TCP-L:8888,reuseaddr,fork))) 3458 3459merges data arriving from different TCP streams on port 8888 to just one stream 3460to target:9999. The link(end-close)(OPTION_END_CLOSE) option prevents the child 3461processes forked off by the second address from terminating the shared 3462connection to 9999 (NOEXPAND(close(2)) just unlinks the inode which stays active as long 3463as the parent process lives; NOEXPAND(shutdown(2)) would actively terminate the 3464connection). 3465 3466 3467label(EXAMPLE_ADDRESS_UDP4_BROADCAST_CLIENT) 3468dit(bf(tt(socat - UDP4-DATAGRAM:192.168.1.0:123,sp=123,broadcast,range=192.168.1.0/24))) 3469 3470sends a broadcast to the network 192.168.1.0/24 and receives the replies of the 3471timeservers there. Ignores NTP packets from hosts outside this network. 3472 3473 3474label(EXAMPLE_ADDRESS_GENERIC_CLIENT) 3475dit(bf(tt(socat - SOCKET-DATAGRAM:2:2:17:x007bxc0a80100x0000000000000000,bind=x007bx00000000x0000000000000000,setsockopt-int=1:6:1,range=x0000xc0a80100x0000000000000000:x0000xffffff00x0000000000000000))) 3476 3477is semantically equivalent to the link(previous 3478example)(EXAMPLE_ADDRESS_UDP4_BROADCAST_CLIENT), but all parameters are 3479specified in generic form. the value 6 of setsockopt-int is the Linux value for 3480tt(SO_BROADCAST). 3481 3482 3483label(EXAMPLE_ADDRESS_IP4_BROADCAST_CLIENT) 3484dit(bf(tt(socat - IP4-DATAGRAM:255.255.255.255:44,broadcast,range=10.0.0.0/8))) 3485 3486sends a broadcast to the local NOEXPAND(network(s)) using protocol 44. Accepts replies 3487from the private address range only. 3488 3489 3490label(EXAMPLE_ADDRESS_UDP4_MULTICAST) 3491dit(bf(tt(socat - UDP4-DATAGRAM:224.255.0.1:6666,bind=:6666,ip-add-membership=224.255.0.1:eth0))) 3492 3493transfers data from stdin to the specified multicast address using UDP. Both 3494local and remote ports are 6666. Tells the interface eth0 to also accept 3495multicast packets of the given group. Multiple hosts on the local network can 3496run this command, so all data sent by any of the hosts will be received 3497by all the other ones. Note that there are many possible reasons for failure, 3498including IP-filters, routing issues, wrong interface selection by the 3499operating system, bridges, or a badly configured switch. 3500 3501 3502label(EXAMPLE_ADDRESS_TUN) 3503dit(bf(tt(socat UDP:host2:4443 TUN:192.168.255.1/24,up))) 3504 3505establishes one side of a virtual (but not private!) network with host2 where a 3506similar process might run, with UDP-L and tun address 192.168.255.2. They can 3507reach each other using the addresses 192.168.255.1 and 192.168.255.2. Note that 3508streaming eg.via TCP or SSL does not guarantee to retain packet boundaries and 3509might thus cause packet loss. 3510 3511 3512label(EXAMPLE_ADDRESS_VSOCK) 3513dit(bf(tt(socat - VSOCK-CONNECT:2:1234))) 3514 3515establishes a VSOCK connection with the host (host is always reachable with 3516the well-know CID=2) on 1234 port. 3517 3518 3519dit(bf(tt(socat - VSOCK-LISTEN:1234))) 3520 3521listens for a VSOCK connection on 1234 port. 3522 3523 3524dit(bf(tt(socat - VSOCK-CONNECT:31:4321,bind:5555))) 3525 3526establishes a VSOCK connection with the guest that have CID=31 on 1234 port, 3527binding the local socket to the 5555 port. 3528 3529 3530dit(bf(tt(socat VSOCK-LISTEN:3333,reuseaddr,fork VSOCK-CONNECT:42,3333))) 3531 3532starts a forwarder that accepts VSOCK connections on port 3333, and directs 3533them to the guest with CID=42 on the same port. 3534 3535 3536dit(bf(tt(socat VSOCK-LISTEN:22,reuseaddr,fork TCP:localhost:22))) 3537 3538forwards VSOCK connections from 22 port to the local SSH server. 3539Running this in a VM allows you to connect via SSH from the host using VSOCK, 3540as in the example below. 3541 3542 3543dit(bf(tt(socat TCP4-LISTEN:22222,reuseaddr,fork VSOCK-CONNECT:33:22))) 3544 3545forwards TCP connections from 22222 port to the guest with CID=33 listening on 3546VSOCK port 22. 3547Running this in the host, allows you to connect via SSH running 3548"ssh -p 22222 user@localhost", if the guest runs the example above. 3549 3550 3551label(EXAMPLE_INTERFACE) 3552dit(bf(tt(socat PTY,link=/var/run/ppp,rawer INTERFACE:hdlc0))) 3553 3554circumvents the problem that pppd requires a serial device and thus might not 3555be able to work on a synchronous line that is represented by a network device. 3556socat creates a PTY to make pppd happy, binds to the network 3557link(interface)(ADDRESS_INTERFACE) tt(hdlc0), and can transfer data between 3558both devices. Use pppd on device tt(/var/run/ppp) then. 3559 3560 3561label(EXAMPLE_HTTPECHO) 3562dit(bf(tt(socat -T 1 -d -d TCP-L:10081,reuseaddr,fork,crlf SYSTEM:"echo -e \"\\\"HTTP/1.0 200 OK\\\nDocumentType: text/plain\\\n\\\ndate: \$\(date\)\\\nserver:\$SOCAT_SOCKADDR:\$SOCAT_SOCKPORT\\\nclient: \$SOCAT_PEERADDR:\$SOCAT_PEERPORT\\\n\\\"\"; cat; echo -e \"\\\"\\\n\\\"\""))) 3563 3564creates a simple HTTP echo server: each HTTP client that connects gets a valid 3565HTTP reply that contains information about the client address and port as it is 3566seen by the server host, the host address (which might vary on multihomed 3567servers), and the original client request. 3568 3569 3570label(EXAMPLE_ANCILLARY) 3571dit(bf(tt(socat -d -d UDP4-RECVFROM:9999,so-broadcast,so-timestamp,ip-pktinfo,ip-recverr,ip-recvopts,ip-recvtos,ip-recvttl!!- SYSTEM:'export; sleep 1' |grep SOCAT))) 3572 3573waits for an incoming UDP packet on port 9999 and prints the environment 3574variables provided by socat. On BSD based systems you have to replace 3575link(tt(ip-pktinfo))(OPTION_IP_PKTINFO) with link(tt(ip-recvdstaddr))(OPTION_IP_RECVDSTADDR),link(tt(ip-recvif))(OPTION_IP_RECVIF). Especially interesting is 3576SOCAT_IP_DSTADDR: it contains the target address of the packet which may be a 3577unicast, multicast, or broadcast address. 3578 3579 3580label(EXAMPLE_SSD) 3581dit(bf(tt(echo -e "M-SEARCH * HTTP/1.1\nHOST: 239.255.255.250:1900\nMAN: \"ssdp:discover\"\nMX: 4\nST: \"ssdp:all\"\n" |./socat - UDP-DATAGRAM:239.255.255.250:1900,crlf))) 3582 3583sends an SSDP (Simple Service Discovery Protocol) query to the local network 3584and collects and outputs the answers received. 3585 3586dit(bf(tt())) 3587 3588 3589 3590enddit() 3591 3592 3593label(DIAGNOSTICS) 3594manpagediagnostics() 3595 3596Socat() uses a logging mechanism that allows filtering messages by severity. The 3597severities provided are more or less compatible to the appropriate syslog 3598priority. With one or up to four occurrences of the -d command line option, the 3599lowest priority of messages that are issued can be selected. Each message 3600contains a single uppercase character specifying the messages severity (one of 3601F, E, W, N, I, or D) 3602 3603description( 3604dit(FATAL:) Conditions that require unconditional and immediate program termination. 3605dit(ERROR:) Conditions that prevent proper program processing. Usually the 3606program is terminated (see link(option -s)(option_s)). 3607dit(WARNING:) Something did not function correctly or is in a state where 3608correct further processing cannot be guaranteed, but might be possible. 3609dit(NOTICE:) Interesting actions of the program, e.g. for supervising socat() in some kind of server mode. 3610dit(INFO:) Description of what the program does, and maybe why it 3611happens. Allows monitoring the lifecycles of file descriptors. 3612dit(DEBUG:) Description of how the program works, all system or library calls and their results. 3613) 3614 3615Log messages can be written to stderr, to a file, or to syslog. 3616 3617On exit, socat() gives status 0 if it terminated due to EOF or inactivity 3618timeout, with a positive value on error, and with a negative value on fatal 3619error. 3620 3621 3622label(FILES) 3623manpagefiles() 3624 3625/usr/bin/socat nl() 3626/usr/bin/filan nl() 3627/usr/bin/procan 3628 3629 3630label(ENVIRONMENT_VARIABLES) 3631manpagesection(ENVIRONMENT VARIABLES) 3632 3633Input variables carry information from the environment to socat, output 3634variables are set by socat for use in executed scripts and programs. 3635 3636In the output variables beginning with "SOCAT" this prefix is actually replaced 3637by the upper case name of the executable or the value of option 3638link(-lp)(option_lp). 3639 3640startdit() 3641label(ENV_SOCAT_DEFAULT_LISTEN_IP) 3642dit(bf(SOCAT_DEFAULT_LISTEN_IP) (input)) (Values 4 or 6) Sets the IP version to 3643be used for listen, recv, and recvfrom addresses if no 3644link(pf)(OPTION_PROTOCOL_FAMILY) (protocol-family) option is given. Is 3645overridden by socat options link(-4)(option_4) or link(-6)(option_6). 3646 3647dit(bf(SOCAT_PREFERRED_RESOLVE_IP) (input)) (Values 0, 4, or 6) Sets the IP 3648version to 3649be used when resolving target host names when version is not specified by 3650address type, option link(pf)(OPTION_PROTOCOL_FAMILY) (protocol-family), or 3651address format. If name resolution does not return a matching entry, the first 3652result (with differing IP version) is taken. With value 0, socat always selects 3653the first record and its IP version. 3654 3655dit(bf(SOCAT_FORK_WAIT) (input)) Specifies the time (seconds) to sleep the 3656parent and child processes after successful NOEXPAND(fork()). Useful for debugging. 3657 3658dit(bf(SOCAT_VERSION) (output)) Socat sets this variable to its version string, 3659e.g. tt("1.7.0.0") for released versions or e.g. tt("1.6.0.1+envvar") for 3660temporary versions; can be used in scripts invoked by socat. 3661 3662dit(bf(SOCAT_PID) (output)) Socat sets this variable to its process id. In case 3663of link(fork)(OPTION_FORK) address option, SOCAT_PID gets the child processes 3664id. Forking for link(exec)(ADDRESS_EXEC) and link(system)(ADDRESS_SYSTEM) does 3665not change SOCAT_PID. 3666 3667dit(bf(SOCAT_PPID) (output)) Socat sets this variable to its process id. In 3668case of link(fork)(OPTION_FORK), SOCAT_PPID keeps the pid of the master process. 3669 3670dit(bf(SOCAT_PEERADDR) (output)) With passive socket addresses (all LISTEN and 3671RECVFROM addresses), this variable is set to a string describing the peers 3672socket address. Port information is not included. 3673 3674dit(bf(SOCAT_PEERPORT) (output)) With appropriate passive socket addresses 3675(TCP, UDP, and SCTP - LISTEN and RECVFROM), this variable is set to a string containing the 3676number of the peer port. 3677 3678dit(bf(SOCAT_SOCKADDR) (output)) With all LISTEN addresses, this variable is 3679set to a string describing the local socket address. Port information is not 3680included link(example)(EXAMPLE_HTTPECHO) 3681 3682dit(bf(SOCAT_SOCKPORT) (output)) With link(TCP-LISTEN)(ADDRESS_TCP_LISTEN), 3683link(UDP-LISTEN)(ADDRESS_UDP_LISTEN), and 3684link(SCTP-LISTEN)(ADDRESS_SCTP_LISTEN) addresses, this variable is set to the 3685local port. 3686 3687dit(bf(SOCAT_TIMESTAMP) (output)) With all RECVFROM addresses where address 3688option link(so-timestamp)(OPTION_SO_TIMESTAMP) is applied, socat sets this 3689variable to the resulting timestamp. 3690 3691dit(bf(SOCAT_IP_OPTIONS) (output)) With all IPv4 based RECVFROM addresses where 3692address option link(ip-recvopts)(OPTION_IP_RECVOPTS) is applied, socat fills 3693this variable with the IP options of the received packet. 3694 3695dit(bf(SOCAT_IP_DSTADDR) (output)) With all IPv4 based RECVFROM addresses where 3696address option link(ip-recvdstaddr)(OPTION_IP_RECVDSTADDR) (BSD) or 3697link(ip-pktinfo)(OPTION_IP_PKTINFO) (other platforms) is applied, socat sets 3698this variable to the destination address of the received packet. This is 3699particularly useful to identify broadcast and multicast addressed packets. 3700 3701dit(bf(SOCAT_IP_IF) (output)) With all IPv4 based RECVFROM addresses where 3702address option link(ip-recvif)(OPTION_IP_RECVIF) (BSD) or 3703link(ip-pktinfo)(OPTION_IP_PKTINFO) (other platforms) is applied, socat sets 3704this variable to the name of the interface where the packet was received. 3705 3706dit(bf(SOCAT_IP_LOCADDR) (output)) With all IPv4 based RECVFROM 3707addresses where address option link(ip-pktinfo)(OPTION_IP_PKTINFO) is applied, 3708socat sets this variable to the address of the interface where the packet was 3709received. 3710 3711dit(bf(SOCAT_IP_TOS) (output)) With all IPv4 based RECVFROM addresses where 3712address option link(ip-recvtos)(OPTION_IP_RECVTOS) is applied, socat sets this 3713variable to the TOS (type of service) of the received packet. 3714 3715dit(bf(SOCAT_IP_TTL) (output)) With all IPv4 based RECVFROM addresses where 3716address option link(ip-recvttl)(OPTION_IP_RECVTTL) is applied, socat sets this 3717variable to the TTL (time to live) of the received packet. 3718 3719dit(bf(SOCAT_IPV6_HOPLIMIT) (output)) With all IPv6 based RECVFROM addresses 3720where address option link(ipv6-recvhoplimit)(OPTION_IPV6_RECVHOPLIMIT) is 3721applied, socat sets this variable to the hoplimit value of the received packet. 3722 3723dit(bf(SOCAT_IPV6_DSTADDR) (output)) With all IPv6 based RECVFROM 3724addresses where address option link(ipv6-recvpktinfo)(OPTION_IPV6_RECVPKTINFO) 3725is applied, socat sets this variable to the destination address of the received 3726packet. 3727 3728dit(bf(SOCAT_IPV6_TCLASS) (output)) With all IPv6 based RECVFROM addresses 3729where address option link(ipv6-recvtclass)(OPTION_IPV6_RECVTCLASS) is applied, 3730socat() sets this variable to the transfer class of the received packet. 3731 3732dit(bf(SOCAT_OPENSSL_X509_ISSUER) (output)) Issuer field from peer certificate 3733 3734dit(bf(SOCAT_OPENSSL_X509_SUBJECT) (output)) Subject field from peer certificate 3735 3736dit(bf(SOCAT_OPENSSL_X509_COMMONNAME) (output)) commonName entries from peer certificates subject. Multiple values are separated by " // ". 3737 3738dit(bf(SOCAT_OPENSSL_X509_*) (output)) all other entries from peer certificates subject 3739 3740dit(bf(SOCAT_OPENSSL_X509V3_DNS) (output)) DNS entries from peer certificates extensions - subjectAltName field. Multiple values are separated by " // ". 3741 3742dit(bf(HOSTNAME) (input)) Is used to determine the hostname for logging (see 3743link(-lh)(option_lh)). 3744 3745dit(bf(LOGNAME) (input)) Is used as name for the socks client user name if no 3746link(socksuser)(OPTION_SOCKSUSER) is given.nl() 3747With options link(su)(OPTION_SUBSTUSER) and 3748link(su-d)(OPTION_SUBSTUSER_DELAYED), LOGNAME is set to the given user name. 3749 3750dit(bf(USER) (input)) Is used as name for the socks client user name if no 3751link(socksuser)(OPTION_SOCKSUSER) is given and LOGNAME is empty.nl() 3752With options link(su)(OPTION_SUBSTUSER) and 3753link(su-d)(OPTION_SUBSTUSER_DELAYED), USER is set to the given user name. 3754 3755dit(bf(SHELL) (output)) 3756With options link(su)(OPTION_SUBSTUSER) and 3757link(su-d)(OPTION_SUBSTUSER_DELAYED), SHELL is set to the login shell of the 3758given user. 3759 3760dit(bf(PATH) (output)) 3761Can be set with option link(path)(OPTION_PATH) for link(exec)(ADDRESS_EXEC) and 3762link(system)(ADDRESS_SYSTEM) addresses. 3763 3764dit(bf(HOME) (output)) 3765With options link(su)(OPTION_SUBSTUSER) and 3766link(su-d)(OPTION_SUBSTUSER_DELAYED), HOME is set to the home directory of the 3767given user. 3768 3769enddit() 3770 3771label(CREDITS) 3772manpagesection(CREDITS) 3773 3774The work of the following groups and organizations was invaluable for this 3775project: 3776 3777The em(FSF) (GNU, lurl(http://www.fsf.org/)) project 3778with their free and portable development software and 3779lots of other useful tools and libraries. 3780 3781The em(Linux developers community) (lurl(http://www.linux.org/)) for providing a free, open source operating 3782system. 3783 3784The em(Open Group) (lurl(http://www.unix-systems.org/)) for making their 3785standard specifications available on the Internet for free. 3786 3787 3788label(VERSION) 3789manpagesection(VERSION) 3790 3791This man page describes version 1.7.4 of socat(). 3792 3793 3794label(BUGS) 3795manpagebugs() 3796 3797Addresses cannot be nested, so a single socat process cannot, e.g., drive ssl 3798over socks. 3799 3800Address option ftruncate without value uses default 1 instead of 0. 3801 3802Verbose modes (-x and/or -v) display line termination characters inconsistently 3803when address options cr or crnl are used: They show the data em(after) 3804conversion in either direction. 3805 3806The data transfer blocksize setting (-b) is ignored with address readline. 3807 3808Send bug reports to <socat@dest-unreach.org> 3809 3810 3811label(SEEALSO) 3812manpageseealso() 3813 3814COMMENT(NOEXPAND(procan(1)), NOEXPAND(filan(1)), ) 3815NOEXPAND(nc(1)), NOEXPAND(rinetd(8)), NOEXPAND(openssl(1)), 3816NOEXPAND(stunnel(8)), NOEXPAND(rlwrap(1)), NOEXPAND(setsid(1)) 3817 3818Socat() home page lurl(http://www.dest-unreach.org/socat/) 3819 3820label(AUTHOR) 3821manpageauthor() 3822 3823Gerhard Rieger <rieger@dest-unreach.org> and contributors 3824