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