PageRenderTime 38ms CodeModel.GetById 5ms app.highlight 13ms RepoModel.GetById 1ms app.codeStats 1ms

/doc/socat.1

https://github.com/xscc/socat
Unknown | 3701 lines | 3603 code | 98 blank | 0 comment | 0 complexity | a6a25a53ff0478c3b71c8e48f00ec892 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

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

Large files files are truncated, but you can click here to view the full file