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