1socat(1) socat(1)
2
6 socat - Multipurpose relay (SOcket CAT)
7
9 socat [options] <address> <address>
10 socat -V
11 socat -h[h[h]] | -?[?[?]]
12 filan
13 procan
14
16 Socat is a command line based utility that establishes two bidirec‐
17 tional byte streams and transfers data between them. Because the
18 streams can be constructed from a large set of different types of data
19 sinks and sources (see address types), and because lots of address
20 options may be applied to the streams, socat can be used for many dif‐
21 ferent purposes. It might be one of the tools that one `has already
22 needed´.
23 Filan is a utility that prints information about its active file
25 descriptors to stdout. It has been written for debugging socat, but
26 might be useful for other purposes too. Use the -h option to find more
27 infos.
28 Procan is a utility that prints information about process parameters to
30 stdout. It has been written to better understand some UNIX process
31 properties and for debugging socat, but might be useful for other pur‐
32 poses too.
33 The life cycle of a socat instance typically consists of four phases.
35 In the init phase, the command line options are parsed and logging is
37 initialized.
38 During the open phase, socat opens the first address and afterwards the
40 second address. These steps are usually blocking; thus, especially for
41 complex address types like socks, connection requests or authentication
42 dialogs must be completed before the next step is started.
43 In the transfer phase, socat watches both streams´ read and write file
45 descriptors via select(), and, when data is available on one side and
46 can be written to the other side, socat reads it, performs newline
47 character conversions if required, and writes the data to the write
48 file descriptor of the other stream, then continues waiting for more
49 data in both directions.
50 When one of the streams effectively reaches EOF, the closing phase
52 begins. Socat transfers the EOF condition to the other stream, i.e.
53 tries to shutdown only its write stream, giving it a chance to termi‐
54 nate gracefully. For a defined time socat continues to transfer data in
55 the other direction, but then closes all remaining channels and termi‐
56 nates.
57
59 Socat provides some command line options that modify the behaviour of
60 the program. They have nothing to do with so called address options
61 that are used as parts of address specifications.
62 -V Print version and available feature information to stdout, and
64 exit.
65 -h | -?
67 Print a help text to stdout describing command line options and
68 available address types, and exit.
69 -hh | -??
71 Like -h, plus a list of the short names of all available address
72 options. Some options are platform dependend, so this output is
73 helpful for checking the particular implementation.
74 -hhh | -???
76 Like -hh, plus a list of all available address option names.
77 -d Without this option, only fatal and error messages are gener‐
79 ated; applying this option also prints warning messages. See
80 DIAGNOSTICS for more information.
81 -d -d Prints fatal, error, warning, and notice messages.
83 -d -d -d
85 Prints fatal, error, warning, notice, and info messages.
86 -d -d -d -d
88 Prints fatal, error, warning, notice, info, and debug messages.
89 -D Logs information about file descriptors before starting the
91 transfer phase.
92 -ly[<facility>]
94 Writes messages to syslog instead of stderr; severity as defined
95 with -d option. With optional <facility>, the syslog type can be
96 selected, default is "daemon".
97 -lf <logfile>
99 Writes messages to <logfile> [filename] instead of stderr.
100 -ls Writes messages to stderr (this is the default).
102 -lp<progname>
104 Overrides the program name printed in error messages.
105 -lu Extends the timestamp of error messages to microsecond resolu‐
107 tion. Does not work when logging to syslog.
108 -lm[<facility>]
110 Mixed log mode. During startup messages are printed to stderr;
111 when socat starts the transfer phase loop or daemon mode (i.e.
112 after opening all streams and before starting data transfer, or,
113 with listening sockets with fork option, before the first accept
114 call), it switches logging to syslog. With optional <facility>,
115 the syslog type can be selected, default is "daemon".
116 -lh Adds hostname to log messages. Uses the value from environment
118 variable HOSTNAME or the value retrieved with uname() if HOST‐
119 NAME is not set.
120 -v Writes the transferred data not only to their target streams,
122 but also to stderr. The output format is text with some conver‐
123 sions for readability, and prefixed with "> " or "< " indicating
124 flow directions.
125 -x Writes the transferred data not only to their target streams,
127 but also to stderr. The output format is hexadecimal, prefixed
128 with "> " or "< " indicating flow directions. Can be combined
129 with -v.
130 -b<size>
132 Sets the data transfer block <size> [size_t]. At most <size>
133 bytes are transferred per step. Default is 8192 bytes.
134 -s By default, socat terminates when an error occurred to prevent
136 the process from running when some option could not be applied.
137 With this option, socat is sloppy with errors and tries to con‐
138 tinue. Even with this option, socat will exit on fatals, and
139 will abort connection attempts when security checks failed.
140 -t<timeout>
142 When one channel has reached EOF, the write part of the other
143 channel is shut down. Then, socat waits <timeout> [timeval] sec‐
144 onds before terminating. Default is 0.5 seconds. This timeout
145 only applies to addresses where write and read part can be
146 closed independently. When during the timeout intervall the read
147 part gives EOF, socat terminates without awaiting the timeout.
148 -T<timeout>
150 Total inactivity timeout: when socat is already in the transfer
151 loop and nothing has happened for <timeout> [timeval] seconds
152 (no data arrived, no interrupt occurred...) then it terminates.
153 Useful with protocols like UDP that cannot transfer EOF.
154 -u Uses unidirectional mode. The first address is only used for
156 reading, and the second address is only used for writing.
157 -U Uses unidirectional mode in reverse direction. The first address
159 is only used for writing, and the second address is only used
160 for reading.
161 -g During address option parsing, don´t check if the option is con‐
163 sidered useful in the given address environment. Use it if you
164 want to force, e.g., appliance of a socket option to a serial
165 device.
166 -L<lockfile>
168 If lockfile exists, exits with error. If lockfile does not
169 exist, creates it and continues, unlinks lockfile on exit.
170 -W<lockfile>
172 If lockfile exists, waits until it disappears. When lockfile
173 does not exist, creates it and continues, unlinks lockfile on
174 exit.
175 -4 Use IP version 4 in case that the addresses do not implicitly or
177 explicitly specify a version; this is the default.
178 -6 Use IP version 6 in case that the addresses do not implicitly or
180 explicitly specify a version.
181
183 With the address command line arguments, the user gives socat instruc‐
184 tions and the necessary information for establishing the byte streams.
185 An address specification usually consists of an address type keyword,
187 zero or more required address parameters separated by ´:´ from the key‐
188 word and from each other, and zero or more address options separated by
189 ´,´.
190 The keyword specifies the address type (e.g., TCP4, OPEN, EXEC). For
192 some keywords there exist synonyms (´-´ for STDIO, TCP for TCP4). Key‐
193 words are case insensitive. For a few special address types, the key‐
194 word may be omitted: Address specifications starting with a number are
195 assumed to be FD (raw file descriptor) addresses; if a ´/´ is found
196 before the first ´:´ or ´,´, GOPEN (generic file open) is assumed.
197 The required number and type of address parameters depend on the
199 address type. E.g., TCP4 requires a server specification (name or
200 address), and a port specification (number or service name).
201 Zero or more address options may be given with each address. They
203 influence the address in some ways. Options consist of an option key‐
204 word or an option keyword and a value, separated by ´=´. Option key‐
205 words are case insensitive. For filtering the options that are useful
206 with an address type, each option is member of one option group. For
207 each address type there is a set of option groups allowed. Only options
208 belonging to one of these address groups may be used (except with
209 option -g).
210 Address specifications following the above schema are also called sin‐
212 gle address specifications. Two single addresses can be combined with
213 "!!" to form a dual type address for one channel. Here, the first
214 address is used by socat for reading data, and the second address for
215 writing data. There is no way to specify an option only once for being
216 applied to both single addresses.
217 Usually, addresses are opened in read/write mode. When an address is
219 part of a dual address specification, or when option -u or -U is used,
220 an address might be used only for reading or for writing. Considering
221 this is important with some address types.
222 With socat version 1.5.0 and higher, the lexical analysis tries to han‐
224 dle quotes and parenthesis meaningfully and allows escaping of special
225 characters. If one of the characters ( { [ ´ is found, the correspond‐
226 ing closing character - ) } ] ´ - is looked for; they may also be
227 nested. Within these constructs, socats special characters and strings
228 : , !! are not handled specially. All those characters and strings can
229 be escaped with \ or within ""
230
232 This section describes the available address types with their keywords,
233 parameters, and semantics.
234 CREATE:<filename>
236 Opens <filename> with creat() and uses the file descriptor for
237 writing. This address type requires write-only context, because
238 a file opened with creat cannot be read from. <filename> must
239 be a valid existing or not existing path. If <filename> is a
240 named pipe, creat() might block; if <filename> refers to a
241 socket, this is an error.
242 Option groups: FD,REG,NAMED
243 Useful options: mode, user, group, unlink-early, unlink-late,
244 append
245 See also: OPEN, GOPEN
246 EXEC:<command-line>
248 Forks a sub process that establishes communication with its par‐
249 ent process and invokes the specified program with execvp().
250 <command-line> is a simple command with arguments separated by
251 single spaces. If the program name contains a ´/´, the part
252 after the last ´/´ is taken as ARGV[0]. If the program name is a
253 relative path, the execvp() semantics for finding the program
254 via $PATH apply. After successful program start, socat writes
255 data to stdin of the process and reads from its stdout using a
256 UNIX domain socket generated by socketpair() per default.
257 Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
258 Useful options: path, fdin, fdout, chroot, su, su-d, nofork,
259 pty, stderr, ctty, setsid, pipes, login, sigint, sigquit
260 See also: SYSTEM
261 FD:<fdnum>
263 Uses the file descriptor <fdnum>. It must already exist as valid
264 UN*X file descriptor.
265 Option groups: FD (TERMIOS,REG,SOCKET)
266 See also: STDIO, STDIN, STDOUT, STDERR
267 GOPEN:<filename>
269 (Generic open) This address type tries to handle any file system
270 entry except directories usefully. <filename> may be a relative
271 or absolute path. If it already exists, its type is checked. In
272 case of a UNIX domain socket, socat connects; if connecting
273 fails, socat assumes a datagram socket and uses sendto() calls.
274 If the entry is not a socket, socat opens it applying the
275 O_APPEND flag. If it does not exist, it is opened with flag
276 O_CREAT as a regular file.
277 Option groups: FD,REG,SOCKET,NAMED,OPEN
278 See also: OPEN, CREATE, UNIX-CONNECT
279 IP-SENDTO:<host>:<protocol>
281 Opens a raw IP socket. Depending on host specification or option
282 pf, IP procotol version 4 or 6 is used. It uses <protocol> to
283 send packets to <host> [IP address] and receives packets from
284 host, ignores packets from other hosts. Protocol 255 uses the
285 raw socket with the IP header being part of the data.
286 Option groups: FD,SOCKET,IP4,IP6
287 Useful options: pf, ttl, broadcast
288 See also: IP4-SENDTO, IP6-SENDTO, IP-RECVFROM, IP-RECV, UDP-
289 SENDTO UNIX-SENDTO
290 IP4-SENDTO:<host>:<protocol>
292 Like IP-SENDTO, but always uses IPv4.
293 Option groups: FD,SOCKET,IP4
294 IP6-SENDTO:<host>:<protocol>
296 Like IP-SENDTO, but always uses IPv6.
297 Option groups: FD,SOCKET,IP6
298 IP-RECVFROM:<protocol>
300 Opens a raw IP socket of <protocol>. Depending on option pf, IP
301 procotol version 4 or 6 is used. It receives one packet from an
302 unspecified peer and may send one or more answer packets to that
303 peer. This mode is particularly useful with fork option where
304 each arriving packet - from arbitrary peers - is handled by its
305 own sub process. This allows a behaviour similar to typical UDP
306 based servers like ntpd or named. This address works well with
307 IP-SENDTO address peers (see above). Protocol 255 uses the raw
308 socket with the IP header being part of the data.
309 Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
310 Useful options: pf, fork, range, ttl, broadcast
311 See also: IP4-RECVFROM, IP6-RECVFROM, IP-SENDTO, IP-RECV, UDP-
312 RECVFROM, UNIX-RECVFROM
313 IP4-RECVFROM:<protocol>
315 Like IP-RECVFROM, but always uses IPv4.
316 Option groups: FD,SOCKET,IP4,CHILD,RANGE
317 IP6-RECVFROM:<protocol>
319 Like IP-RECVFROM, but always uses IPv6.
320 Option groups: FD,SOCKET,IP6,CHILD,RANGE
321 IP-RECV:<protocol>
323 Opens a raw IP socket of <protocol>. Depending on option pf, IP
324 procotol version 4 or 6 is used. It receives packets from multi‐
325 ple unspecified peers and merges the data. No replies are pos‐
326 sible. It can be, e.g., addressed by socat IP-SENDTO address
327 peers. Protocol 255 uses the raw socket with the IP header
328 being part of the data.
329 Option groups: FD,SOCKET,IP4,IP6,RANGE
330 Useful options: pf, range
331 See also: IP4-RECV, IP6-RECV, IP-SENDTO, IP-RECVFROM, UDP-RECV,
332 UNIX-RECV
333 IP4-RECV:<protocol>
335 Like IP-RECV, but always uses IPv4.
336 Option groups: FD,SOCKET,IP4,RANGE
337 IP6-RECV:<protocol>
339 Like IP-RECV, but always uses IPv6.
340 Option groups: FD,SOCKET,IP6,RANGE
341 OPEN:<filename>
343 Opens <filename> using the open() system call. This operation
344 fails on UNIX domain sockets.
345 Note: This address type is rarly useful in bidirectional mode.
346 Option groups: FD,REG,NAMED,OPEN
347 Useful options: creat, excl, noatime, nofollow, append, rdonly,
348 wronly, lock, readbytes, ignoreeof
349 See also: CREATE, GOPEN, UNIX-CONNECT
350 OPENSSL:<host>:<port>
352 Tries to establish a SSL connection to <port> [TCP service] on
353 <host> [IP address] using TCP/IP version 4 or 6 depending on
354 address specification, name resolution, or option pf.
355 NOTE: The server certificate is only checked for validity
356 against cafile or capath, but not for match with the server´s
357 name or its IP address!
358 Option groups: FD,SOCKET,IP4,IP6,TCP,OPENSSL,RETRY
359 Useful options: cipher, method, verify, cafile, capath, certifi‐
360 cate, bind, pf, connect-timeout, sourceport, retry
361 See also: OPENSSL-LISTEN, TCP
362 OPENSSL-LISTEN:<port>
364 Listens on tcp <port> [TCP service]. The IP version is 4 or the
365 one specified with pf. When a connection is accepted, this
366 address behaves as SSL server.
367 Note: You probably want to use the certificate option with this
368 address.
369 NOTE: Without verify option, the client certificate is not
370 checked. Even with verify option, the client certificate is only
371 checked for validity against cafile or capath, but not for match
372 with the client´s name or its IP address!
373 Option groups: FD,SOCKET,IP4,IP6,TCP,LIS‐
374 TEN,OPENSSL,CHILD,RANGE,RETRY
375 Useful options: pf, cipher, method, verify, cafile, capath, cer‐
376 tificate, fork, bind, range, tcpwrap, su, reuseaddr, retry
377 See also: OPENSSL, TCP
378 PIPE:<filename>
380 If <filename> already exists, it is opened. If is does not
381 exist, a named pipe is created and opened. Beginning with socat
382 version 1.4.3, the named pipe is removed when the address is
383 closed (but see option unlink-close
384 Note: When a pipe is used for both reading and writing, it works
385 as echo service.
386 Note: When a pipe is used for both reading and writing, and
387 socat tries to write more bytes than the pipe can buffer (Linux
388 2.4: 2048 bytes), socat might block. Consider using socat
389 option, e.g., -b 2048
390 Option groups: FD,NAMED,OPEN
391 Useful options: rdonly, nonblock, group, user, mode, unlink-
392 early
393 See also: unnamed pipe
394 PIPE Creates an unnamed pipe and uses it for reading and writing. It
396 works as an echo, because everything written to it appeares
397 immediately as read data.
398 Note: When socat tries to write more bytes than the pipe can
399 queue (Linux 2.4: 2048 bytes), socat might block. Consider,
400 e.g., using option -b 2048
401 Option groups: FD
402 See also: named pipe
403 PROXY:<proxy>:<hostname>:<port>
405 Connects to an HTTP proxy server on port 8080 using TCP/IP ver‐
406 sion 4 or 6 depending on address specification, name resolution,
407 or option pf, and sends a CONNECT request for hostname:port. If
408 the proxy grants access and succeeds to connect to the target,
409 data transfer between socat and the target can start. Note that
410 the traffic need not be HTTP but can be an arbitrary protocol.
411 Option groups: FD,SOCKET,IP4,IP6,TCP,HTTP,RETRY
412 Useful options: proxyport, ignorecr, proxyauth, resolve, crnl,
413 bind, connect-timeout, mss, sourceport, retry
414 See also: SOCKS, TCP
415 PTY Generates a pseudo terminal (pty) and uses its master side.
417 Another process may open the pty´s slave side using it like a
418 serial line or terminal. If both the ptmx and the openpty mecha‐
419 nisms are available, ptmx is used (POSIX).
420 Option groups: FD,NAMED,PTY,TERMIOS
421 Useful options: link, openpty, wait-slave, mode, user, group
422 See also: UNIX-LISTEN, PIPE, EXEC, SYSTEM
423 READLINE
425 Uses GNU readline and history on stdio to allow editing and
426 reusing input lines. This requires the GNU readline and history
427 libraries. Note that stdio should be a (pseudo) terminal device,
428 otherwise readline does not seem to work.
429 Option groups: FD,READLINE,TERMIOS
430 Useful options: history, noecho
431 See also: STDIO
432 SOCKS4:<socks-server>:<host>:<port>
434 Connects via <socks-server> [IP address] to <host> [IPv4
435 address] on <port> [TCP service], using socks version 4 protocol
436 over IP version 4 or 6 depending on address specification, name
437 resolution, or option pf.
438 Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
439 Useful options: socksuser, socksport, sourceport, pf, retry
440 See also: SOCKS4A, PROXY, TCP
441 SOCKS4A:<socks-server>:<host>:<port>
443 like SOCKS4, but uses socks protocol version 4a, thus leaving
444 host name resolution to the socks server.
445 Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
446 STDERR Uses file descriptor 2.
448 Option groups: FD (TERMIOS,REG,SOCKET)
449 See also: FD
450 STDIN Uses file descriptor 0.
452 Option groups: FD (TERMIOS,REG,SOCKET)
453 Useful options: readbytes
454 See also: FD
455 STDIO Uses file descriptor 0 for reading, and 1 for writing.
457 Option groups: FD (TERMIOS,REG,SOCKET)
458 Useful options: readbytes
459 See also: FD
460 STDOUT Uses file descriptor 1.
462 Option groups: FD (TERMIOS,REG,SOCKET)
463 See also: FD
464 SYSTEM:<shell-command>
466 Forks a sub process that establishes communication with its par‐
467 ent process and invokes the specified program with system().
468 Please note that <shell-command> [string] must not contain ´,´
469 or "!!", and that shell meta characters may have to be pro‐
470 tected. After successful program start, socat writes data to
471 stdin of the process and reads from its stdout.
472 Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
473 Useful options: path, fdin, fdout, chroot, su, su-d, nofork,
474 pty, stderr, ctty, setsid, pipes, sigint, sigquit
475 See also: EXEC
476 TCP:<host>:<port>
478 Connects to <port> [TCP service] on <host> [IP address] using
479 TCP/IP version 4 or 6 depending on address specification, name
480 resolution, or option pf.
481 Option groups: FD,SOCKET,IP4,IP6,TCP,RETRY
482 Useful options: crnl, bind, pf, connect-timeout, tos, mtudis‐
483 cover, mss, nodelay, nonblock, sourceport, retry, readbytes
484 See also: TCP4, TCP6, TCP-LISTEN, UDP, UNIX-CONNECT
485 TCP4:<host>:<port>
487 Like TCP, but only supports IPv4 protocol.
488 Option groups: FD,SOCKET,IP4,TCP,RETRY
489 TCP6:<host>:<port>
491 Like TCP, but only supports IPv6 protocol.
492 Option groups: FD,SOCKET,IP6,TCP,RETRY
493 TCP-LISTEN:<port>
495 Listens on <port> [TCP service] and accepts a TCP/IP connection.
496 The IP version is 4 or the one specified with pf. Note that
497 opening this address usually blocks until a client connects.
498 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,TCP,RETRY
499 Useful options: crnl, fork, bind, range, tcpwrap, pf, backlog,
500 mss, su, reuseaddr, retry, retry
501 See also: TCP4-LISTEN, TCP6-LISTEN, UDP-LISTEN, UNIX-LISTEN,
502 OPENSSL-LISTEN
503 TCP4-LISTEN:<port>
505 Like TCP-LISTEN, but only supports IPv4 protocol.
506 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,TCP,RETRY
507 TCP6-LISTEN:<port>
509 Like TCP-LISTEN, but only supports IPv6 protocol.
510 Additional useful option: ipv6only
511 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,TCP,RETRY
512 UDP:<host>:<port>
514 Connects to <port> [UDP service] on <host> [IP address] using
515 UDP/IP version 4 or 6 depending on address specification, name
516 resolution, or option pf.
517 Please note that, due to UDP protocol properties, no real con‐
518 nection is established; data has to be sent for `connecting´ to
519 the server, and no end-of-file condition can be transported.
520 Option groups: FD,SOCKET,IP4,IP6
521 Useful options: ttl, tos, bind, sourceport, pf
522 See also: UDP4, UDP6, UDP-LISTEN, TCP, IP
523 UDP4:<host>:<port>
525 Like UDP, but only supports IPv4 protocol.
526 Option groups: FD,SOCKET,IP4
527 UDP6:<host>:<port>
529 Like UDP, but only supports IPv6 protocol.
530 Option groups: FD,SOCKET,IP6
531 UDP-LISTEN:<port>
533 Waits for a UDP/IP packet arriving on <port> [UDP service] and
534 `connects´ back to sender. The accepted IP version is 4 or the
535 one specified with option pf. Please note that, due to UDP pro‐
536 tocol properties, no real connection is established; data has
537 to arrive from the peer first, and no end-of-file condition can
538 be transported. Note that opening this address usually blocks
539 until a client connects.
540 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6
541 Useful options: fork, bind, range, pf
542 See also: UDP, UDP4-LISTEN, UDP6-LISTEN, TCP-LISTEN
543 UDP4-LISTEN:<port>
545 Like UDP-LISTEN, but only support IPv4 protocol.
546 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4
547 UDP6-LISTEN:<port>
549 Like UDP-LISTEN, but only support IPv6 protocol.
550 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6
551 UDP-SENDTO:<host>:<port>
553 Communicates with the specified peer socket, defined by <port>
554 [UDP service] on <host> [IP address], using UDP/IP version 4 or
555 6 depending on address specification, name resolution, or option
556 pf. It sends packets to and receives packets from that peer
557 socket only. This is effectively a datagram client. It works
558 well with socat UDP-RECVFROM and UDP-RECV address peers.
559 Option groups: FD,SOCKET,IP4,IP6
560 Useful options: ttl, tos, bind, sourceport, pf
561 See also: UDP4-SENDTO, UDP6-SENDTO, UDP-RECVFROM, UDP-RECV, UDP-
562 CONNECT, UDP-LISTEN, IP-SENDTO
563 UDP4-SENDTO:<host>:<port>
565 Like UDP-SENDTO, but only supports IPv4 protocol.
566 Option groups: FD,SOCKET,IP4
567 UDP6-SENDTO:<host>:<port>
569 Like UDP-SENDTO, but only supports IPv6 protocol.
570 Option groups: FD,SOCKET,IP6
571 UDP-RECVFROM:<port>
573 Creates a UDP socket on <port> [UDP service] using UDP/IP ver‐
574 sion 4 or 6 depending on option pf. It receives one packet from
575 an unspecified peer and may send one or more answer packets to
576 that peer. This mode is particularly useful with fork option
577 where each arriving packet - from arbitrary peers - is handled
578 by its own sub process. This allows a behaviour similar to typi‐
579 cal UDP based servers like ntpd or named. This address works
580 well with socat SENDTO address peers.
581 Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
582 Useful options: fork, ttl, tos, bind, sourceport, pf
583 See also: UDP4-RECVFROM, UDP6-RECVFROM, UDP-SENDTO, UDP-RECV,
584 UDP-CONNECT, UDP-LISTEN, IP-RECVFROM, UNIX-RECVFROM
585 UDP4-RECVFROM:<port>
587 Like UDP-RECVFROM, but only supports IPv4 protocol.
588 Option groups: FD,SOCKET,IP4,CHILD,RANGE
589 UDP6-RECVFROM:<port>
591 Like UDP-RECVFROM, but only supports IPv6 protocol.
592 Option groups: FD,SOCKET,IP6,CHILD,RANGE
593 UDP-RECV:<port>
595 Creates a UDP socket on <port> [UDP service] using UDP/IP ver‐
596 sion 4 or 6 depending on option pf. It receives packets from
597 multiple unspecified peers and merges the data. No replies are
598 possible. It can be, e.g., addressed by socat UDP-SENDTO address
599 peers. This address works well with socat SENDTO address peers;
600 it behaves similar to a syslog server.
601 Option groups: FD,SOCKET,IP4,IP6,RANGE
602 Useful options: fork, pf, bind, sourceport, ttl, tos
603 See also: UDP4-RECV, UDP6-RECV, UDP-SENDTO, UDP-RECVFROM, UDP-
604 CONNECT, UDP-LISTEN, IP-RECV, UNIX-RECV
605 UDP4-RECV:<port>
607 Like UDP-RECV, but only supports IPv4 protocol.
608 Option groups: FD,SOCKET,IP4,RANGE
609 UDP6-RECV:<port>
611 Like UDP-RECV, but only supports IPv6 protocol.
612 Option groups: FD,SOCKET,IP6,RANGE
613 UNIX-CONNECT:<filename>
615 Connects to <filename> assuming it is a UNIX domain socket. If
616 <filename> does not exist, this is an error; if <filename> is
617 not a UNIX domain socket, this is an error; if <filename> is a
618 UNIX domain socket, but no process is listening, this is an
619 error.
620 Option groups: FD,SOCKET,NAMED,RETRY
621 ) Useful options: bind
622 See also: UNIX-LISTEN, UNIX-SENDTO, TCP
623 UNIX-LISTEN:<filename>
625 Listens on <filename> using a UNIX domain stream socket and
626 accepts a connection. If <filename> exists and is not a socket,
627 this is an error. If <filename> exists and is a UNIX domain
628 socket, binding to the address fails (use option unlink-early!).
629 Note that opening this address usually blocks until a client
630 connects. Beginning with socat version 1.4.3, the file system
631 entry is removed when this address is closed (but see option
632 unlink-close).
633 Option groups: FD,SOCKET,NAMED,LISTEN,CHILD,RETRY
634 Useful options: fork, umask, mode, user, group, unlink-early
635 See also: UNIX-CONNECT, UNIX-RECVFROM, UNIX-RECV, TCP-LISTEN
636 UNIX-SENDTO:<filename>
638 Communicates with the specified peer socket, defined by [<file‐
639 name>] assuming it is a UNIX domain datagram socket. It sends
640 packets to and receives packets from that peer socket only. It
641 works well with socat UNIX-RECVFROM and UNIX-RECV address peers.
642 Option groups: FD,SOCKET,NAMED
643 Useful options: bind
644 See also: UNIX-RECVFROM, UNIX-RECV, UNIX-CONNECT, UDP-SENDTO,
645 IP-SENDTO
646 UNIX-RECVFROM:<filename>
648 Creates a UNIX domain datagram socket [<filename>]. Receives
649 one packet and may send one or more answer packets to that peer.
650 This mode is particularly useful with fork option where each
651 arriving packet - from arbitrary peers - is handled by its own
652 sub process. This address works well with socat UNIX-SENDTO
653 address peers.
654 Option groups: FD,SOCKET,NAMED,CHILD
655 Useful options: fork
656 See also: UNIX-SENDTO, UNIX-RECV, UNIX-LISTEN, UDP-RECVFROM, IP-
657 RECVFROM
658 UNIX-RECV:<filename>
660 Creates a UNIX domain datagram socket [<filename>]. Receives
661 packets from multiple unspecified peers and merges the data. No
662 replies are possible. It can be, e.g., addressed by socat UNIX-
663 SENDTO address peers. It behaves similar to a syslog server.
664 Option groups: FD,SOCKET,NAMED
665 See also: UNIX-SENDTO, UNIX-RECVFROM, UNIX-LISTEN, UDP-RECV, IP-
666 RECV
667 UNIX:<filename>
669 Communicates with the specified peer socket, defined by [<file‐
670 name>] assuming it is a UNIX domain socket. It first tries to
671 connect and, if that fails, assumes it is a datagram socket,
672 thus supporting both types.
673 Option groups: FD,SOCKET,NAMED
674 Useful options: bind
675 See also: UNIX-CONNECT, UNIX-SENDTO, GOPEN
676
678 Address options can be applied to address specifications to influence
679 the process of opening the addresses and the properties of the result‐
680 ing data channels.
681 For technical reasons not every option can be applied to every address
683 type; e.g., applying a socket option to a regular file will fail. To
684 catch most useless combinations as early as in the open phase, the con‐
685 cept of option groups was introduced. Each option belongs to one or
686 more option groups. Options can be used only with address types that
687 support at least one of their option groups (but see option -g).
688 Address options have data types that their values must conform to.
690 Every address option consists of just a keyword or a keyword followed
691 by "=value", where value must conform to the options type. Some
692 address options manipulate parameters of system calls; e.g., option
693 sync sets the O_SYNC flag with the open() call. Other options cause a
694 system or library call; e.g., with option `ttl=value´ the setsock‐
695 opt(fd, SOL_IP, IP_TTL, value, sizeof(int)) call is applied. Other
696 options set internal socat variables that are used during data trans‐
697 fer; e.g., `crnl´ causes explicit character conversions. A few options
698 have more complex implementations; e.g., su-d (substuser-delayed)
699 inquires some user and group infos, stores them, and applies them later
700 after a possible chroot() call.
701 If multiple options are given to an address, their sequence in the
703 address specification has (almost) no effect on the sequence of their
704 execution/application. Instead, socat has built in an option phase
705 model that tries to bring the options in a useful order. Some options
706 exist in different forms (e.g., unlink, unlink-early, unlink-late) to
707 control the time of their execution.
708 If the same option is specified more than once within one address spec‐
710 ification, with equal or different values, the effect depends on the
711 kind of option. Options resulting in function calls like setsockopt()
712 cause multiple invocations. With options that set parameters for a
713 required call like open() or set internal flags, the value of the last
714 option occurrence is effective.
715 The existence or semantics of many options are system dependent. Socat
717 usually does NOT try to emulate missing libc or kernel features, it
718 just provides an interface to the underlying system. So, if an operat‐
719 ing system lacks a feature, the related option is simply not available
720 on this platform.
721 The following paragraphs introduce just the more common address
723 options. For a more comprehensive reference and to find information
724 about canonical option names, alias names, option phases, and platforms
725 see file xio.help.
726 FD option group
728 This option group contains options that are applied to a UN*X style
730 file descriptor, no matter how it was generated. Because all current
731 socat address types are file descriptor based, these options may be
732 applied to any address.
733 Note: Some of these options are also member of another option group,
734 that provides an other, non-fd based mechanism. For these options, it
735 depends on the actual address type and its option groups which mecha‐
736 nism is used. The second, non-fd based mechanism is prioritized.
737 cloexec=<bool>
739 Sets the FD_CLOEXEC flag with the fcntl() system call to value
740 <bool>. If set, the file descriptor is closed on exec() family
741 function calls. Socat internally handles this flag for the fds
742 it controls, so in most cases there will be no need to apply
743 this option.
744 setlk Tries to set a discretionary lock to the whole file using the
746 fcntl(fd, F_SETLK, ...) system call. If the file is already
747 locked, this call results in an error.
748 setlkw Tries to set a discretionary waiting lock to the whole file
750 using the fcntl(fd, F_SETLKW, ...) system call. If the file is
751 already locked, this call blocks.
752 flock-ex
754 Tries to set a blocking exclusive advisory lock to the file
755 using the flock(fd, LOCK_EX) system call. Socat hangs in this
756 call if the file is locked by another process.
757 flock-ex-nb
759 Tries to set a nonblocking exclusive advisory lock to the file
760 using the flock(fd, LOCK_EX) system call. If the file is already
761 locked, this option results in an error.
762 flock-sh
764 Tries to set a blocking shared advisory lock to the file using
765 the flock(fd, LOCK_SH) system call. Socat hangs in this call if
766 the file is locked by another process.
767 flock-sh-nb
769 Tries to set a nonblocking shared advisory lock to the file
770 using the flock(fd, LOCK_SH|LOCK_NB) system call. If the file is
771 already locked, this option results in an error.
772 lock Sets a blocking lock on the file. Uses the setlk or flock mecha‐
774 nism depending on availability on the particular platform. If
775 both are available, the POSIX variant (setlkw) is selected.
776 user=<user>
778 Sets the <user> (owner) of the stream. If the address is member
779 of the NAMED option group, socat uses the chown() system call
780 after opening the file or binding to the UNIX domain socket
781 (race condition!). Without filesystem entry, socat sets the
782 user of the stream using the fchown() system call. These calls
783 might require root privilege.
784 user-late=<user>
786 Sets the owner of the fd to <user> with the fchown() system call
787 after opening or connecting the channel. This is useful only on
788 file system entries.
789 group=<group>
791 Sets the <group> of the stream. If the address is member of the
792 NAMED option group, socat uses the chown() system call after
793 opening the file or binding to the UNIX domain socket (race con‐
794 dition!). Without filesystem entry, socat sets the group of the
795 stream with the fchown() system call. These calls might require
796 group membership or root privilege.
797 group-late=<group>
799 Sets the group of the fd to <group> with the fchown() system
800 call after opening or connecting the channel. This is useful
801 only on file system entries.
802 mode=<mode>
804 Sets the <mode> [mode_t] (permissions) of the stream. If the
805 address is member of the NAMED option group and uses the open()
806 or creat() call, the mode is applied with these. If the address
807 is member of the NAMED option group without using these system
808 calls, socat uses the chmod() system call after opening the
809 filesystem entry or binding to the UNIX domain socket (race con‐
810 dition!). Otherwise, socat sets the mode of the stream using
811 fchmod(). These calls might require ownership or root privi‐
812 lege.
813 perm-late=<mode>
815 Sets the permissions of the fd to value <mode> [mode_t] using
816 the fchmod() system call after opening or connecting the chan‐
817 nel. This is useful only on file system entries.
818 append=<bool>
820 Always writes data to the actual end of file. If the address is
821 member of the OPEN option group, socat uses the O_APPEND flag
822 with the open() system call. Otherwise, socat applies the
823 fcntl(fd, F_SETFL, O_APPEND) call.
824 nonblock=<bool>
826 Tries to open or use file in nonblocking mode. Its only effects
827 are that the connect() call of TCP addresses does not block, and
828 that opening a named pipe for reading does not block. If the
829 address is member of the OPEN option group, socat uses the
830 O_NONBLOCK flag with the open() system call. Otherwise, socat
831 applies the fcntl(fd, F_SETFL, O_NONBLOCK) call.
832 binary Opens the file in binary mode to avoid implicit line terminator
834 conversions (Cygwin).
835 text Opens the file in text mode to force implicit line terminator
837 conversions (Cygwin).
838 noinherit
840 Does not keep this file open in a spawned process (Cygwin).
841 cool-write
843 Takes it easy when write fails with EPIPE or ECONNRESET and logs
844 the message with notice level instead of error. This prevents
845 the log file from being filled with useless error messages when
846 socat is used as a high volume server or proxy where clients
847 often abort the connection.
848 This option is experimental.
849 NAMED option group
851 These options work on file system entries.
853 See also options user, group, and mode.
854 user-early=<user>
856 Changes the <user> (owner) of the file system entry before
857 accessing it, using the chown() system call. This call might
858 require root privilege.
859 group-early=<group>
861 Changes the <group> of the file system entry before accessing
862 it, using the chown() system call. This call might require group
863 membership or root privilege.
864 perm-early=<mode>
866 Changes the <mode> [mode_t] of the file system entry before
867 accessing it, using the chmod() system call. This call might
868 require ownership or root privilege.
869 umask=<mode>
871 Sets the umask of the process to <mode> [mode_t] before access‐
872 ing the file system entry (useful with UNIX domain sockets!).
873 This call might affect all further operations of the socat
874 process!
875 unlink-early
877 Unlinks (removes) the file before opening it and even before
878 applying user-early etc.
879 unlink Unlinks (removes) the file before accessing it, but after user-
881 early etc.
882 unlink-late
884 Unlinks (removes) the file after opening it to make it inacces‐
885 sible for other processes after a short race condition.
886 unlink-close
888 Removes the addresses file system entry when closing the
889 address. For named pipes, listening unix domain sockets, and
890 the symbolic links of pty addresses, the default is 1; for cre‐
891 ated files, opened files, generic opened files, and client unix
892 domain sockets the default is 0.
893 OPEN option group
895 The OPEN group options allow to set flags with the open() system call.
897 E.g., option `creat´ sets the O_CREAT flag.
898 See also options append and nonblock.
899 creat=<bool>
901 Creates the file if it does not exist.
902 dsync=<bool>
904 Blocks write() calls until metainfo is physically written to
905 media.
906 excl=<bool>
908 With option creat, if file exists this is an error.
909 largefile=<bool>
911 On 32 bit systems, allows a file larger than 2^31 bytes.
912 noatime
914 Sets the O_NOATIME options, so reads do not change the access
915 timestamp.
916 noctty=<bool>
918 Does not make this file the controlling terminal.
919 nofollow=<bool>
921 Does not follow symbolic links.
922 nshare=<bool>
924 Does not allow to share this file with other processes.
925 rshare=<bool>
927 Does not allow other processes to open this file for writing.
928 rsync=<bool>
930 Blocks write() until metainfo is physically written to media.
931 sync=<bool>
933 Blocks write() until data is physically written to media.
934 rdonly=<bool>
936 Opens the file for reading only.
937 wronly=<bool>
939 Opens the file for writing only.
940 trunc Truncates the file to size 0 during opening it.
942 REG and BLK option group
944 These options are usually applied to a UN*X file descriptor, but their
946 semantics make sense only on a file supporting random access.
947 seek=<offset>
949 Applies the lseek(fd, <offset>, SEEK_SET) (or lseek64) system
950 call, thus positioning the file pointer absolutely to <offset>
951 [off_t or off64_t].
952 seek-cur=<offset>
954 Applies the lseek(fd, <offset>, SEEK_CUR) (or lseek64) system
955 call, thus positioning the file pointer <offset> [off_t or
956 off64_t] bytes relatively to its current position (which is usu‐
957 ally 0).
958 seek-end=<offset>
960 Applies the lseek(fd, <offset>, SEEK_END) (or lseek64) system
961 call, thus positioning the file pointer <offset> [off_t or
962 off64_t] bytes relatively to the files current end.
963 ftruncate=<offset>
965 Applies the ftruncate(fd, <offset>) (or ftruncate64 if avail‐
966 able) system call, thus truncating the file at the position
967 <offset> [off_t or off64_t].
968 secrm=<bool>
970 unrm=<bool>
972 compr=<bool>
974 ext2-sync=<bool>
976 immutable=<bool>
978 ext2-append=<bool>
980 nodump=<bool>
982 ext2-noatime=<bool>
984 journal-data=<bool>
986 notail=<bool>
988 dirsync=<bool>
990 These options change non standard file attributes on operating
991 systems and file systems that support these features, like Linux
992 with ext2fs, ext3fs, or reiserfs. See man 1 chattr for informa‐
993 tion on these options. Please note that there might be a race
994 condition between creating the file and applying these options.
995 PROCESS option group
997 Options of this group change the process properties instead of just
999 affecting one data channel. For EXEC and SYSTEM addresses and for LIS‐
1000 TEN and CONNECT type addresses with option FORK, these options apply to
1001 the child processes instead of the main socat process.
1002 chroot=<directory>
1004 Performs a chroot() operation to <directory> after processing
1005 the address. This call might require root privilege.
1006 chroot-early=<directory>
1008 Performs a chroot() operation to <directory> before opening the
1009 address. This call might require root privilege.
1010 setgid=<group>
1012 Changes the primary <group> of the process after processing the
1013 address. This call might require root privilege.
1014 setgid-early=<group>
1016 Changes the primary <group> of the process before opening the
1017 address. This call might require root privilege.
1018 setuid=<user>
1020 Changes the <user> (owner) of the process after processing the
1021 address. This call might require root privilege.
1022 setuid-early=<user>
1024 Changes the <user> (owner) of the process before opening the
1025 address. This call might require root privilege.
1026 su=<user>
1028 Changes the <user> (owner) and groups of the process after pro‐
1029 cessing the address. This call might require root privilege.
1030 su-d=<user>
1032 Short name for substuser-delayed. Changes the <user> (owner)
1033 and groups of the process after processing the address. The
1034 user and his groups are retrieved before a possible chroot().
1035 This call might require root privilege.
1036 setpgid=<pid_t>
1038 Makes the process a member of the specified process group
1039 <pid_t>. If no value is given, or if the value is 0 or 1, the
1040 process becomes leader of a new process group.
1041 setsid Makes the process the leader of a new session.
1043 READLINE option group
1045 These options apply to the readline address type.
1047 history=<filename>
1049 Reads and writes history from/to <filename>.
1050 noprompt
1052 Since version 1.4.0, socat per default tries to determine a
1053 prompt - that is then passed to the readline call - by remember‐
1054 ing the last incomplete line of the output. With this option,
1055 socat does not pass a prompt to readline, so it begins line
1056 editing in the first column of the terminal.
1057 noecho=<pattern>
1059 Specifies a regular pattern for a prompt that prevents the fol‐
1060 lowing input line from being displayed on the screen and from
1061 being added to the history. The prompt is defined as the text
1062 that was output to the readline address after the lastest new‐
1063 line character and before an input character was typed. The pat‐
1064 tern is a regular expression, e.g. "^[Pp]assword:.*$" or
1065 "([Uu]ser:|[Pp]assword:)". See regex(7) for details.
1066 prompt=<string>
1068 Passes the string as prompt to the readline function. readline
1069 prints this prompt when stepping through the history. If this
1070 string matches a constant prompt issued by an interactive pro‐
1071 gram on the other socat address, consistent look and feel can be
1072 archieved.
1073 APPLICATION option group
1075 This group contains options that work at data level. Note that these
1077 options only apply to the "raw" data transferred by socat, but not to
1078 protocol data used by addresses like PROXY.
1079 cr Converts the default line termination character NL (´\n´, 0x0a)
1081 to/from CR (´\r´, 0x0d) when writing/reading on this channel.
1082 crnl Converts the default line termination character NL (´\n´, 0x0a)
1084 to/from CRNL ("\r\n", 0x0d0a) when writing/reading on this chan‐
1085 nel. Note: socat simply strips all CR characters.
1086 ignoreeof
1088 When EOF occurs on this channel, socat ignores it and tries to
1089 read more data (like "tail -f").
1090 readbytes=<bytes>
1092 socat reads only so many bytes from this address (the address
1093 provides only so many bytes for transfer and pretends to be at
1094 EOF afterwards). Must be greater than 0.
1095 lockfile=<filename>
1097 If lockfile exists, exits with error. If lockfile does not
1098 exist, creates it and continues, unlinks lockfile on exit.
1099 waitlock=<filename>
1101 If lockfile exists, waits until it disappears. When lockfile
1102 does not exist, creates it and continues, unlinks lockfile on
1103 exit.
1104 SOCKET option group
1106 These options are intended for all kinds of sockets, e.g. IP or UNIX
1108 domain. Most are applied with a setsockopt() call.
1109 bind=<sockname>
1111 Binds the socket to the given socket address using the bind()
1112 system call. The form of <sockname> is socket domain dependent:
1113 IP4 and IP6 allow the form [hostname|hostaddress][:(ser‐
1114 vice|port)], UNIX domain sockets require <filename>.
1115 connect-timeout=<seconds>
1117 Abort the connection attempt after <seconds> [timeval] with
1118 error status.
1119 interface=<interface>
1121 Binds the socket to the given <interface>. This option might
1122 require root privilege.
1123 broadcast
1125 For datagram sockets, allows sending to broadcast addresses and
1126 receiving packets addressed to broadcast addresses.
1127 bsdcompat
1129 Emulates some (old?) bugs of the BSD socket implementation.
1130 debug Enables socket debugging.
1132 dontroute
1134 Only communicates with directly connected peers, does not use
1135 routers.
1136 keepalive
1138 Enables sending keepalives on the socket.
1139 linger=<seconds>
1141 Blocks shutdown() or close() until data transfers have finished
1142 or the given timeout [int] expired.
1143 oobinline
1145 Places out-of-band data in the input data stream.
1146 priority=<priority>
1148 Sets the protocol defined <priority> [<int>] for outgoing pack‐
1149 ets.
1150 rcvbuf=<bytes>
1152 Sets the size of the receive buffer after the socket() call to
1153 <bytes> [int]. With TCP sockets, this value corresponds to the
1154 socket´s maximal window size.
1155 rcvbuf-late=<bytes>
1157 Sets the size of the receive buffer when the socket is already
1158 connected to <bytes> [int]. With TCP sockets, this value corre‐
1159 sponds to the socket´s maximal window size.
1160 rcvlowat=<bytes>
1162 Specifies the minimum number of received bytes [int] until the
1163 socket layer will pass the buffered data to socat.
1164 rcvtimeo=<seconds>
1166 Sets the receive timeout [timeval].
1167 reuseaddr
1169 Allows other sockets to bind to an address even if parts of it
1170 (e.g. the local port) are already in use by socat.
1171 sndbuf=<bytes>
1173 Sets the size of the send buffer after the socket() call to
1174 <bytes> [int].
1175 sndbuf-late=<bytes>
1177 Sets the size of the send buffer when the socket is connected to
1178 <bytes> [int].
1179 sndlowat=<bytes>
1181 Specifies the minimum number of bytes in the send buffer until
1182 the socket layer will send the data to <bytes> [int].
1183 sndtimeo=<seconds>
1185 Sets the send timeout to seconds [timeval].
1186 type=<type>
1188 Sets the type of the socket, usually as argument to the socket()
1189 or socketpair() call, to <type> [int]. Under Linux, 1 means
1190 stream oriented socket, 2 means datagram socket, and 3 means raw
1191 socket.
1192 pf=<string>
1194 Forces the use of the specified IP version. <string> can be
1195 something like "ip4" or "ip6".
1196 IP4 and IP6 option groups
1198 These options can be used with IPv4 and IPv6 based sockets.
1200 tos=<tos>
1202 Sets the TOS (type of service) field of outgoing packets to
1203 <tos> [byte] (see RFC 791).
1204 ttl=<ttl>
1206 Sets the TTL (time to live) field of outgoing packets to <ttl>
1207 [byte].
1208 ipoptions=<data>
1210 Sets IP options like source routing. Must be given in binary
1211 form, recommended format is a leading "x" followed by an even
1212 number of hex digits. This option may be used multiple times,
1213 data are appended. E.g., to connect to host 10.0.0.1 via some
1214 gateway using a loose source route, use the gateway as address
1215 parameter and set a loose source route using the option ipop‐
1216 tions=x8307040a000001.
1217 IP options are defined in RFC 791.
1218 mtudiscover=<0|1|2>
1220 Takes 0, 1, 2 to never, want, or always use path MTU discover on
1221 this socket.
1222 res-debug
1224 res-aaonly
1226 res-usevc
1228 res-primary
1230 res-igntc
1232 res-recurse
1234 res-defnames
1236 res-stayopen
1238 res-dnsrch
1240 These options set the corresponding resolver (name resolution)
1241 option flags. Append "=0" to clear a default option. See man
1242 resolver(5) for more information on these options. Note: these
1243 options are valid only for the address they are applied to.
1244 IP6 option group
1246 These options can only be used on IPv6 based sockets. See IP options
1248 for options that can be applied to both IPv4 and IPv6 sockets.
1249 ipv6only=<bool>
1251 Sets the IPV6_V6ONLY socket option. If 0, the TCP stack will
1252 also accept connections using IPv4 protocol on the same port.
1253 The default is system dependent.
1254 TCP option group
1256 These options may be applied to TCP sockets. They work by invoking set‐
1258 sockopt() with the appropriate parameters.
1259 cork Doesn´t send packets smaller than MSS (maximal segment size).
1261 defer-accept
1263 While listening, accepts connections only when data from the
1264 peer arrived.
1265 keepcnt=<count>
1267 Sets the number of keepalives before shutting down the socket to
1268 <count> [int].
1269 keepidle=<seconds>
1271 Sets the idle time before sending the first keepalive to <sec‐
1272 onds> [int].
1273 keepintvl=<seconds>
1275 Sets the intervall between two keepalives to <seconds> [int].
1276 linger2=<seconds>
1278 Sets the time to keep the socket in FIN-WAIT-2 state to <sec‐
1279 onds> [int].
1280 mss=<bytes>
1282 Sets the MSS (maximum segment size) after the socket() call to
1283 <bytes> [int]. This value is then proposed to the peer with the
1284 SYN or SYN/ACK packet.
1285 mss-late=<bytes>
1287 Sets the MSS of the socket after connection has been established
1288 to <bytes> [int].
1289 nodelay
1291 Turns off the Nagle algorithm for measuring the RTT (round trip
1292 time).
1293 rfc1323
1295 Enables RFC1323 TCP options: TCP window scale, round-trip time
1296 measurement (RTTM), and protect against wrapped sequence numbers
1297 (PAWS) (AIX).
1298 stdurg Enables RFC1122 compliant urgent pointer handling (AIX).
1300 syncnt=<count>
1302 Sets the maximal number of SYN retransmits during connect to
1303 <count> [int].
1304 md5sig Enables generation of MD5 digests on the packets (FreeBSD).
1306 noopt Disables use of TCP options (FreeBSD, MacOSX).
1308 nopush sets the TCP_NOPUSH socket option (FreeBSD, MacOSX).
1310 sack-disable
1312 Disables use the selective acknowledge feature (OpenBSD).
1313 signature-enable
1315 Enables generation of MD5 digests on the packets (OpenBSD).
1316 abort-threshold=<milliseconds>
1318 Sets the time to wait for an answer of the peer on an estab‐
1319 lished connection (HP-UX).
1320 conn-abort-threshold=<milliseconds>
1322 Sets the time to wait for an answer of the server during the
1323 initial connect (HP-UX).
1324 keepinit
1326 Sets the time to wait for an answer of the server during con‐
1327 nect() before giving up. Value in half seconds, default is 150
1328 (75s) (Tru64).
1329 paws Enables the "protect against wrapped sequence numbers" feature
1331 (Tru64).
1332 sackena
1334 Enables selective acknowledge (Tru64).
1335 tsoptena
1337 Enables the time stamp option that allows RTT recalculation on
1338 existing connections (Tru64).
1339 UDP and TCP option groups
1341 Here we find options that are related to the network port mechanism and
1343 that thus can be used with UDP and TCP, client and server addresses.
1344 sourceport=<port>
1346 For outgoing (client) TCP and UDP connections, it sets the
1347 source <port> using an extra bind() call. With TCP or UDP lis‐
1348 ten addresses, socat immediately shuts down the connection if
1349 the client does not use this sourceport.
1350 lowport
1352 Outgoing (client) TCP and UDP connections with this option use
1353 an unused random source port between 640 and 1023 incl. On UNIX
1354 class operating systems, this requires root privilege, and thus
1355 indicates that the client process is authorized by local root.
1356 TCP and UDP listen addresses with this option immediately shut
1357 down the connection if the client does not use a sourceport <=
1358 1023. This mechanism can provide limited authorization under
1359 some circumstances.
1360 SOCKS option group
1362 When using SOCKS type addresses, some socks specific options can be
1364 set.
1365 socksport=<tcp service>
1367 Overrides the default "socks" service or port 1080 for the socks
1368 server port with <TCP service>.
1369 socksuser=<user>
1371 Sends the <user> [string] in the username field to the socks
1372 server. Default is the actual user name ($LOGNAME or $USER).
1373 HTTP option group
1375 Options that can be provided with HTTP type addresses. The only HTTP
1377 address currently implemented is proxy-connect.
1378 proxyport=<TCP service>
1380 Overrides the default HTTP proxy port 8080 with <TCP service>.
1381 ignorecr
1383 The HTTP protocol requires the use of CR+NL as line terminator.
1384 When a proxy server violates this standard, socat might not
1385 understand its answer. This option directs socat to interprete
1386 NL as line terminator and to ignore CR in the answer. Neverthe‐
1387 less, socat sends CR+NL to the proxy.
1388 proxyauth=<username>:<password>
1390 Provide "basic" authentication to the proxy server. The argument
1391 to the option is used with a "Proxy-Authorization: Base" header
1392 in base64 encoded form.
1393 Note: username and password are visible for every user on the
1394 local machine in the process list; username and password are
1395 transferred to the proxy server unencrypted (base64 encoded) and
1396 might be sniffed.
1397 resolve
1399 Per default, socat sends to the proxy a CONNECT request contain‐
1400 ing the target hostname. With this option, socat resolves the
1401 hostname locally and sends the IP address.
1402 RANGE option group
1404 These options check if a connecting client is granted access. They can
1406 be applied to listening and receiving network sockets. tcp-wrappers
1407 options fall into this group.
1408 range=<address-range>
1410 After accepting a connection, tests if the peer is within range.
1411 For IPv4 addresses, address-range takes the form
1412 ww.xx.yy.zz/bits, e.g. 10.0.0.0/8; for IPv6, it is
1413 [ip6-address/bits], e.g. [::1/128]. If the client address does
1414 not match, socat issues a warning and keeps listening/receiving.
1415 tcpwrap[=<name>]
1417 Uses Wietse Venema´s libwrap (tcpd) library to determine if the
1418 client is allowed to connect. The configuration files are
1419 /etc/hosts.allow and /etc/hosts.deny per default, see "man 5
1420 hosts_access" for more information. The optional <name> (type
1421 string) is passed to the wrapper functions as daemon process
1422 name. If omitted, the basename of socats invocation (argv[0])
1423 is passed. If both tcpwrap and range options are applied to an
1424 address, both conditions must be fulfilled to allow the connec‐
1425 tion.
1426 allow-table=<filename>
1428 Takes the specified file instead of /etc/hosts.allow.
1429 deny-table=<filename>
1431 Takes the specified file instead of /etc/hosts.deny.
1432 tcpwrap-etc=<directoryname>
1434 Looks for hosts.allow and hosts.deny in the specified directory.
1435 Is overridden by options hosts-allow and hosts-deny.
1436 LISTEN option group
1438 Options specific to listening sockets.
1440 backlog=<count>
1442 Sets the backlog value passed with the listen() system call to
1443 <count> [int]. Default is 5.
1444 CHILD option group
1446 Options for addresses with multiple connections via child processes.
1448 fork After establishing a connection, handles its channel in a child
1450 process and keeps the parent process attempting to produce more
1451 connections, either by listening or by connecting in a loop.
1452 SSL-CONNECT and SSL-LISTEN differ in when they actually fork off
1453 the child: SSL-LISTEN forks before the SSL handshake, while SSL-
1454 CONNECT forks afterwards. RETRY and FOREVER options are not
1455 inherited by the child process.
1456 EXEC option group
1458 Options for addresses that invoke a program.
1460 path=<string>
1462 Overrides the PATH environment variable for searching the pro‐
1463 gram with <string>. This $PATH value is effective in the child
1464 process too.
1465 login Prefixes argv[0] for the execvp() call with ´-´, thus making a
1467 shell behave as login shell.
1468 FORK option group
1470 EXEC or SYSTEM addresses invoke a program using a child process and
1472 transfer data between socat and the program. The interprocess communi‐
1473 cation mechanism can be influenced with the following options. Per
1474 default, a socketpair() is created and assigned to stdin and stdout of
1475 the child process, while stderr is inherited from the socat process,
1476 and the child process uses file descriptors 0 and 1 for communicating
1477 with the main socat process.
1478 nofork Does not fork a subprocess for executing the program, instead
1480 calls execvp() or system() directly from the actual socat
1481 instance. This avoids the overhead of another process between
1482 the program and its peer, but introduces a lot of restrictions:
1483 o this option can only be applied to the second socat address.
1485 o it cannot be applied to a part of a dual address.
1487 o the first socat address cannot be OPENSSL or READLINE
1489 o socat options -b, -t, -D, -l, -v, -x become useless
1491 o for both addresses, options ignoreeof, cr, and crnl become use‐
1493 less
1494 o for the second address (the one with option nofork), options
1496 append, cloexec, flock, user, group, mode, nonblock, perm-late,
1497 setlk, and setpgid cannot be applied. Some of these could be
1498 used on the first address though.
1499 pipes Creates a pair of unnamed pipes for interprocess communication
1501 instead of a socket pair.
1502 openpty
1504 Establishes communication with the sub process using a pseudo
1505 terminal created with openpty() instead of the default (socket‐
1506 pair or ptmx).
1507 ptmx Establishes communication with the sub process using a pseudo
1509 terminal created by opening /dev/ptmx or /dev/ptc instead of the
1510 default (socketpair).
1511 pty Establishes communication with the sub process using a pseudo
1513 terminal instead of a socket pair. Creates the pty with an
1514 available mechanism. If openpty and ptmx are both available, it
1515 uses ptmx because this is POSIX compliant.
1516 ctty Makes the pty the controlling tty of the sub process.
1518 stderr Directs stderr of the sub process to its output channel by mak‐
1520 ing stderr a dup() of stdout.
1521 fdin=<fdnum>
1523 Assigns the sub processes input channel to its file descriptor
1524 <fdnum> instead of stdin (0). The program started from the sub‐
1525 process has to use this fd for reading data from socat.
1526 fdout=<fdnum>
1528 Assigns the sub processes output channel to its file descriptor
1529 <fdnum> instead of stdout (1). The program started from the sub‐
1530 process has to use this fd for writing data to socat.
1531 sighup, sigint, sigquit
1533 Has socat pass an eventual signal of this type to the sub
1534 process. If no address has this option, socat terminates on
1535 these signals.
1536 TERMIOS option group
1538 For addresses that work on a tty (e.g., stdio, file:/dev/tty,
1540 exec:...,pty), the terminal parameters defined in the UN*X termios
1541 mechanism are made available as address option parameters. Please note
1542 that changes of the parameters of your interactive terminal remain
1543 effective after socat´s termination, so you might have to enter "reset"
1544 or "stty sane" in your shell afterwards. For EXEC and SYSTEM addresses
1545 with option PTY, these options apply to the pty by the child processes.
1546 b0 Disconnects the terminal.
1548 b19200 Sets the serial line speed to 19200 baud. Some other rates are
1550 possible; use something like socat -hh |grep ´ b[1-9]´ to find
1551 all speeds supported by your implementation.
1552 Note: On some operating systems, these options may not be avail‐
1553 able. Use ispeed or ospeed instead.
1554 echo=<bool>
1556 Enables or disables local echo.
1557 icanon=<bool>
1559 Sets or clears canonical mode, enabling line buffering and some
1560 special characters.
1561 raw Sets raw mode, thus passing input and output almost unprocessed.
1563 ignbrk=<bool>
1565 Ignores or interpretes the BREAK character (e.g., ^C)
1566 brkint=<bool>
1568 bs0
1570 bs1
1572 bsdly=<0|1>
1574 clocal=<bool>
1576 cr0
1578 cr1
1579 cr2
1580 cr3
1581 Sets the carriage return delay to 0, 1, 2, or 3, respectively.
1583 0 means no delay, the other values are terminal dependent.
1584 crdly=<0|1|2|3>
1586 cread=<bool>
1588 crtscts=<bool>
1590 cs5
1592 cs6
1593 cs7
1594 cs8
1595 Sets the character size to 5, 6, 7, or 8 bits, respectively.
1597 csize=<0|1|2|3>
1599 cstopb=<bool>
1601 Sets two stop bits, rather than one.
1602 dsusp=<byte>
1604 Sets the value for the VDSUSP character that suspends the cur‐
1605 rent foreground process and reactivates the shell (all except
1606 Linux).
1607 echoctl=<bool>
1609 Echos control characters in hat notation (e.g. ^A)
1610 echoe=<bool>
1612 echok=<bool>
1614 echoke=<bool>
1616 echonl=<bool>
1618 echoprt=<bool>
1620 eof=<byte>
1622 eol=<byte>
1624 eol2=<byte>
1626 erase=<byte>
1628 discard=<byte>
1630 ff0
1632 ff1
1634 ffdly=<bool>
1636 flusho=<bool>
1638 hupcl=<bool>
1640 icrnl=<bool>
1642 iexten=<bool>
1644 igncr=<bool>
1646 ignpar=<bool>
1648 imaxbel=<bool>
1650 inlcr=<bool>
1652 inpck=<bool>
1654 intr=<byte>
1656 isig=<bool>
1658 ispeed=<unsigned-int>
1660 Set the baud rate for incoming data on this line.
1661 See also: ospeed, b19200 dif(istrip=<bool>)
1662 iuclc=<bool>
1664 ixany=<bool>
1666 ixoff=<bool>
1668 ixon=<bool>
1670 kill=<byte>
1672 lnext=<byte>
1674 min=<byte>
1676 nl0 Sets the newline delay to 0.
1678 nl1
1680 nldly=<bool>
1682 noflsh=<bool>
1684 ocrnl=<bool>
1686 ofdel=<bool>
1688 ofill=<bool>
1690 olcuc=<bool>
1692 onlcr=<bool>
1694 onlret=<bool>
1696 onocr=<bool>
1698 opost=<bool>
1700 Enables or disables output processing; e.g., converts NL to CR-
1701 NL.
1702 ospeed=<unsigned-int>
1704 Set the baud rate for outgoing data on this line.
1705 See also: ispeed, b19200
1706 parenb=<bool>
1708 Enable parity generation on output and parity checking for
1709 input.
1710 parmrk=<bool>
1712 parodd=<bool>
1714 pendin=<bool>
1716 quit=<byte>
1718 reprint=<byte>
1720 sane Brings the terminal to something like a useful default state.
1722 start=<byte>
1724 stop=<byte>
1726 susp=<byte>
1728 swtc=<byte>
1730 tab0
1732 tab1
1734 tab2
1736 tab3
1738 tabdly=<unsigned-int>
1740 time=<byte>
1742 tostop=<bool>
1744 vt0
1746 vt1
1748 vtdly=<bool>
1750 werase=<byte>
1752 xcase=<bool>
1754 xtabs
1756 PTY option group
1758 These options are intended for use with the pty address type.
1760 link=<filename>
1762 Generates a symbolic link that points to the actual pseudo ter‐
1763 minal (pty). This might help to solve the problem that ptys are
1764 generated with more or less unpredictable names, making it dif‐
1765 ficult to directly access the socat generated pty automatically.
1766 With this option, the user can specify a "fix" point in the file
1767 hierarchy that helps him to access the actual pty. Beginning
1768 with socat version 1.4.3, the symbolic link is removed when the
1769 address is closed (but see option unlink-close).
1770 wait-slave
1772 Blocks the open phase until a process opens the slave side of
1773 the pty. Usually, socat continues after generating the pty with
1774 opening the next address or with entering the transfer loop.
1775 With the wait-slave option, socat waits until some process opens
1776 the slave side of the pty before continuing. This option only
1777 works if the operating system provides the poll() system call.
1778 And it depends on an undocumented behaviour of pty´s, so it does
1779 not work on all operating systems. It has successfully been
1780 tested on Linux, FreeBSD, NetBSD, and on Tru64 with openpty.
1781 pty-intervall=<seconds>
1783 When the wait-slave option is set, socat periodically checks the
1784 HUP condition using poll() to find if the pty´s slave side has
1785 been opened. The default polling intervall is 1s. Use the pty-
1786 intervall option [timeval] to change this value.
1787 OPENSSL option group
1789 These options apply to the openssl and openssl-listen address types.
1791 cipher=<cipherlist>
1793 Selects the list of ciphers that may be used for the connection.
1794 See the man page of ciphers, section CIPHER LIST FORMAT, for
1795 detailed information about syntax, values, and default of
1796 <cipherlist>.
1797 Several cipher strings may be given, separated by ´:´. Some
1798 simple cipher strings:
1799 3DES Uses a cipher suite with triple DES.
1801 MD5 Uses a cipher suite with MD5.
1803 aNULL Uses a cipher suite without authentication.
1805 NULL Does not use encryption.
1807 HIGH Uses a cipher suite with "high" encryption. Note that the peer
1809 must support the selected property, or the negotiation will
1810 fail.
1811 method=<ssl-method>
1813 Sets the protocol version to be used. Valid strings (not case
1814 sensitive) are:
1815 SSLv2 Select SSL protocol version 2.
1817 SSLv3 Select SSL protocol version 3.
1819 SSLv23 Select SSL protocol version 2 or 3. This is the default when
1821 this option is not provided.
1822 TLSv1 Select TLS protocol version 1.
1824 verify=<bool>
1826 Controls check of the peer´s certificate. Default is 1 (true)
1827 for client and 0 (false) for server addresses. Disabling verify
1828 might open your socket for everyone!
1829 cert=<filename>
1831 Specifies the file with the certificate and private key for
1832 authentication. The certificate must be in OpenSSL format
1833 (*.pem). With openssl-listen, use of this option is strongly
1834 recommended. Except with cipher aNULL, "no shared ciphers" error
1835 will occur when no certificate is given.
1836 key=<filename>
1838 Specifies the file with the private key. The private key may be
1839 in this file or in the file given with the cert option. The
1840 party that has to proof that it is the owner of a certificate
1841 needs the private key.
1842 dhparams=<filename>
1844 Specifies the file with the Diffie Hellman parameters. These
1845 parameters may also be in the file given with the cert option in
1846 which case the dhparams option is not needed.
1847 cafile=<filename>
1849 Specifies the file with the trusted (root) authority certifi‐
1850 cates. The file must be in PEM format and should contain one or
1851 more certificates. The party that checks the authentication of
1852 its peer trusts only certificates that are in this file.
1853 capath=<dirname>
1855 Specifies the directory with the trusted (root) certificates.
1856 The directory must contain certificates in PEM format and their
1857 hashes (see OpenSSL documentation)
1858 egd=<filename>
1860 On some systems, openssl requires an explicit source of random
1861 data. Specify the socket name where an entropy gathering daemon
1862 like egd provides random data, e.g. /dev/egd-pool.
1863 pseudo On systems where openssl cannot find an entropy source and where
1865 no entropy gathering daemon can be utilized, this option acti‐
1866 vates a mechanism for providing pseudo entropy. This is
1867 archieved by taking the current time in microseconds for feeding
1868 the libc pseudo random number generator with an initial value.
1869 openssl is then feeded with output from random() calls.
1870 NOTE:This mechanism is not sufficient for generation of secure
1871 keys!
1872 fips Enables FIPS mode if compiled in. For info about the FIPS
1874 encryption implementation standard see http://oss-insti‐
1875 tute.org/fips-faq.html. This mode might require that the
1876 involved certificates are generated with a FIPS enabled version
1877 of openssl. Setting or clearing this option on one socat address
1878 affects all OpenSSL addresses of this process.
1879 RETRY option group
1881 Options that control retry of some system calls, especially connection
1883 attempts.
1884 retry=<num>
1886 Number of retries before the connection or listen attempt is
1887 aborted. Default is 0, which means just one attempt.
1888 intervall=<timespec>
1890 Time between consecutive attempts (seconds, [timespec]). Default
1891 is 1 second.
1892 forever
1894 Performs an unlimited number of retry attempts.
1895
1897 This section explains the different data types that address parameters
1898 and address options can take.
1899 address-range
1901 Is currently only implemented for IPv4 and IPv6. See address-
1902 option `range´
1903 bool "0" or "1"; if value is omitted, "1" is taken.
1905 byte An unsigned int number, read with strtoul(), lower or equal to
1907 UCHAR_MAX.
1908 command-line
1910 A string specifying a program name and its arguments, separated
1911 by single spaces.
1912 data A raw data specification following dalan syntax. The only docu‐
1914 mented form is a string starting with ´x´ followed by an even
1915 number of hex digits.
1916 directory
1918 A string with usual UN*X directory name semantics.
1919 facility
1921 The name of a syslog facility in lower case characters.
1922 fdnum An unsigned int type, read with strtoul(), specifying a UN*X
1924 file descriptor.
1925 filename
1927 A string with usual UN*X filename semantics.
1928 group If the first character is a decimal digit, the value is read
1930 with strtoul() as unsigned integer specifying a group id. Other‐
1931 wise, it must be an existing group name.
1932 int A number following the rules of the strtol() function with base
1934 "0", i.e. decimal number, octal number with leading "0", or
1935 hexadecimal number with leading "0x". The value must fit into a
1936 C int.
1937 interface
1939 A string specifying the device name of a network interface, e.g.
1940 "eth0".
1941 IP address
1943 An IPv4 address in numbers-and-dots notation, an IPv6 address in
1944 hex notation enclosed in brackets, or a hostname that resolves
1945 to an IPv4 or an IPv6 address.
1946 Examples: 127.0.0.1, [::1], www.dest-unreach.org, dns1
1947 IPv4 address
1949 An IPv4 address in numbers-and-dots notation or a hostname that
1950 resolves to an IPv4 address.
1951 Examples: 127.0.0.1, www.dest-unreach.org, dns2
1952 IPv6 address
1954 An iPv6 address in hexnumbers-and-colons notation enclosed in
1955 brackets, or a hostname that resolves to an IPv6 address.
1956 Examples: [::1], [1234:5678:9abc:def0:1234:5678:9abc:def0],
1957 ip6name.domain.org
1958 long A number read with strtol(). The value must fit into a C long.
1960 long long
1962 A number read with strtoll(). The value must fit into a C long
1963 long.
1964 off_t An implementation dependend signed number, usually 32 bits, read
1966 with strtol or strtoll.
1967 off64_t
1969 An implementation dependend signed number, usually 64 bits, read
1970 with strtol or strtoll.
1971 mode_t An unsigned integer, read with strtoul(), specifying mode (per‐
1973 mission) bits.
1974 pid_t A number, read with strtol(), specifying a process id.
1976 port A uint16_t (16 bit unsigned number) specifying a TCP or UDP
1978 port, read with strtoul().
1979 protocol
1981 An unsigned 8 bit number, read with strtoul().
1982 size_t An unsigned number with size_t limitations, read with strtoul.
1984 sockname
1986 A socket address. See address-option `bind´
1987 string A sequence of characters, not containing ´\0´ and, depending on
1989 the position within the command line, ´:´, ´,´, or "!!". Note
1990 that you might have to escape shell meta characters in the com‐
1991 mand line.
1992 TCP service
1994 A service name, not starting with a digit, that is resolved by
1995 getservbyname(), or an unsigned int 16 bit number read with str‐
1996 toul().
1997 timeval
1999 A double float specifying seconds; the number is mapped into a
2000 struct timeval, consisting of seconds and microseconds.
2001 timespec
2003 A double float specifying seconds; the number is mapped into a
2004 struct timespec, consisting of seconds and nanoseconds.
2005 UDP service
2007 A service name, not starting with a digit, that is resolved by
2008 getservbyname(), or an unsigned int 16 bit number read with str‐
2009 toul().
2010 unsigned int
2012 A number read with strtoul(). The value must fit into a C
2013 unsigned int.
2014 user If the first character is a decimal digit, the value is read
2016 with strtoul() as unsigned integer specifying a user id. Other‐
2017 wise, it must be an existing user name.
2018
2020 socat - TCP4:www.domain.org:80
2021 Transfers data between STDIO (-) and a TCP4 connection to port
2023 80 of host www.domain.org. This example results in an interac‐
2024 tive connection similar to telnet or netcat. The stdin terminal
2025 parameters are not changed, so you may close the relay with ^D
2026 or abort it with ^C.
2027 socat -d -d READLINE,history=$HOME/.http_history \
2029 TCP4:www.domain.org:www,crnl
2030 This is similar to the previous example, but you can edit the
2032 current line in a bash like manner (READLINE) and use the his‐
2033 tory file .http_history; socat prints messages about progress
2034 (-d -d). The port is specified by service name (www), and cor‐
2035 rect network line termination characters (crnl) instead of NL
2036 are used.
2037 socat TCP4-LISTEN:www TCP4:www.domain.org:www
2039 Installs a simple TCP port forwarder. With TCP4-LISTEN it lis‐
2041 tens on local port "www" until a connection comes in, accepts
2042 it, then connects to the remote host (TCP4) and starts data
2043 transfer. It will not accept a second connection.
2044 socat -d -d -lmlocal2 \
2046 TCP4-LISTEN:80,bind=myaddr1,su=nobody,fork,range=10.0.0.0/8,reuseaddr \
2047 TCP4:www.domain.org:80,bind=myaddr2
2048 TCP port forwarder, each side bound to another local IP address
2050 (bind). This example handles an almost arbitrary number of par‐
2051 allel or consecutive connections by fork´ing a new process after
2052 each accept(). It provides a little security by su´ing to user
2053 nobody after forking; it only permits connections from the pri‐
2054 vate 10 network (range); due to reuseaddr, it allows immediate
2055 restart after master process´s termination, even if some child
2056 sockets are not completely shut down. With -lmlocal2, socat
2057 logs to stderr until successfully reaching the accept loop. Fur‐
2058 ther logging is directed to syslog with facility local2.
2059 socat TCP4-LISTEN:5555,fork,tcpwrap=script \
2061 EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr
2062 A simple server that accepts connections (TCP4-LISTEN) and
2064 fork´s a new child process for each connection; every child acts
2065 as single relay. The client must match the rules for daemon
2066 process name "script" in /etc/hosts.allow and /etc/hosts.deny,
2067 otherwise it is refused access (see "man 5 hosts_access"). For
2068 EXEC´uting the program, the child process chroot´s to
2069 /home/sandbox, su´s to user sandbox, and then starts the program
2070 /home/sandbox/bin/myscript. Socat and myscript communicate via a
2071 pseudo tty (pty); myscript´s stderr is redirected to stdout, so
2072 its error messages are transferred via socat to the connected
2073 client.
2074 socat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \
2076 TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512
2077 mail.sh is a shell script, distributed with socat, that imple‐
2079 ments a simple SMTP client. It is programmed to "speak" SMTP on
2080 its FDs 3 (in) and 4 (out). The fdin and fdout options tell
2081 socat to use these FDs for communication with the program.
2082 Because mail.sh inherits stdin and stdout while socat does not
2083 use them, the script can read a mail body from stdin. Socat
2084 makes alias1 your local source address (bind), cares for correct
2085 network line termination (crnl) and sends at most 512 data bytes
2086 per packet (mss).
2087 socat - /dev/ttyS0,raw,echo=0,crnl
2089 Opens an interactive connection via the serial line, e.g. for
2091 talking with a modem. raw and echo set ttyS0´s terminal parame‐
2092 ters to practicable values, crnl converts to correct newline
2093 characters. Consider using READLINE instead of `-´.
2094 socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
2096 SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20
2097 With UNIX-LISTEN, socat opens a listening UNIX domain socket
2099 /tmp/.X11-unix/X1. This path corresponds to local XWindow dis‐
2100 play :1 on your machine, so XWindow client connections to DIS‐
2101 PLAY=:1 are accepted. Socat then speaks with the SOCKS4 server
2102 host.victim.org that might permit sourceport 20 based connec‐
2103 tions due to an FTP related weakness in its static IP filters.
2104 Socat pretends to be invoked by socksuser nobody, and requests
2105 to be connected to loopback port 6000 (only weak sockd configu‐
2106 rations will allow this). So we get a connection to the victims
2107 XWindow server and, if it does not require MIT cookies or Ker‐
2108 beros authentication, we can start work. Please note that there
2109 can only be one connection at a time, because TCP can establish
2110 only one session with a given set of addresses and ports.
2111 socat -u /tmp/readdata,seek-end=0,ignoreeof -
2113 This is an example for unidirectional data transfer (-u). Socat
2115 transfers data from file /tmp/readdata (implicit address GOPEN),
2116 starting at its current end (seek-end=0 lets socat start reading
2117 at current end of file; use seek=0 or no seek option to first
2118 read the existing data) in a "tail -f" like mode (ignoreeof).
2119 The "file" might also be a listening UNIX domain socket (do not
2120 use a seek option then).
2121 (sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |
2123 socat - EXEC:'ssh -l user server',pty,setsid,ctty
2124 EXEC´utes an ssh session to server. Uses a pty for communication
2126 between socat and ssh, makes it ssh´s controlling tty (ctty),
2127 and makes this pty the owner of a new process group (setsid), so
2128 ssh accepts the password from socat.
2129 socat -u TCP4-LISTEN:3334,reuseaddr,fork \
2131 OPEN:/tmp/in.log,creat,append
2132 Implements a simple network based message collector. For each
2134 client connecting to port 3334, a new child process is generated
2135 (option fork). All data sent by the clients are append´ed to
2136 the file /tmp/in.log. If the file does not exist, socat creat´s
2137 it. Option reuseaddr allows immediate restart of the server
2138 process.
2139 socat READLINE,noecho=´[Pp]assword:´ EXEC:´ftp ftp.server.com´,pty,set‐
2141 sid,ctty
2142 Wraps a command line history (READLINE) around the EXEC´uted ftp
2144 client utility. This allows editing and reuse of FTP commands
2145 for relatively comfortable browsing through the ftp directory
2146 hierarchy. The password is echoed! pty is required to have ftp
2147 issue a prompt. Nevertheless, there may occur some confusion
2148 with the password and FTP prompts.
2149 socat PTY,link=$HOME/dev/vmodem0,raw,echo=0,waitslave exec:´
2151 Generates a pseudo terminal device (PTY) on the client that can
2153 be reached under the symbolic link $HOME/dev/vmodem0. An appli‐
2154 cation that expects a serial line or modem can be configured to
2155 use $HOME/dev/vmodem0; its traffic will be directed to a modem‐
2156 server via ssh where another socat instance links it with
2157 /dev/ttyS0.
2158 socat TCP4-LISTEN:2022,reuseaddr,fork \
2160 PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass
2161 starts a forwarder that accepts connections on port 2022, and
2163 directs them through the proxy daemon listening on port 3128
2164 (proxyport) on host proxy, using the CONNECT method, where they
2165 are authenticated as "user" with "pass" (proxyauth). The proxy
2166 should establish connections to host www.domain.org on port 22
2167 then.
2168 echo |socat -u - file:/tmp/bigfile,create,largefile,seek=100000000000
2170 creates a 100GB sparse file; this requires a file system type
2172 that supports this (ext2, ext3, reiserfs, jfs; not minix, vfat).
2173 The operation of writing 1 byte might take long (reiserfs: some
2174 minutes; ext2: "no" time), and the resulting file can consume
2175 some disk space with just its inodes (reiserfs: 2MB; ext2:
2176 16KB).
2177 socat tcp-l:7777,reuseaddr,fork system:´filan -i 0 -s >&2´,nofork
2179 listens for incoming TCP connections on port 7777. For each
2181 accepted connection, invokes a shell. This shell has its stdin
2182 and stdout directly connected to the TCP socket (nofork). The
2183 shell starts filan and lets it print the socket addresses to
2184 stderr (your terminal window).
2185 echo -e
2187 functions as primitive binary editor: it writes the 4 bytes 000
2189 014 000 000 to the executable /usr/bin/squid at offset
2190 0x00074420 (this is a real world patch to make the squid exe‐
2191 cutable from Cygwin run under Windows, actual per May 2004).
2192 socat - tcp:www.blackhat.org:31337,readbytes=1000
2194 connect to an unknown service and prevent being flooded.
2196
2198 Socat uses a logging mechanism that allows to filter messages by sever‐
2199 ity. The severities provided are more or less compatible to the appro‐
2200 priate syslog priority. With one or up to four occurrences of the -d
2201 command line option, the lowest priority of messages that are issued
2202 can be selected. Each message contains a single uppercase character
2203 specifying the messages severity (one of F, E, W, N, I, or D)
2204 FATAL: Conditions that require unconditional and immediate program ter‐
2206 mination.
2207 ERROR: Conditions that prevent proper program processing. Usually the
2209 program is terminated (see option -s).
2210 WARNING:
2212 Something did not function correctly or is in a state where cor‐
2213 rect further processing cannot be guaranteed, but might be pos‐
2214 sible.
2215 NOTICE:
2217 Interesting actions of the program, e.g. for supervising socat
2218 in some kind of server mode.
2219 INFO: Description of what the program does, and maybe why it happens.
2221 Allows to monitor the lifecycles of file descriptors.
2222 DEBUG: Description of how the program works, all system or library
2224 calls and their results.
2225 Log messages can be written to stderr, to a file, or to syslog.
2227 On exit, socat gives status 0 if it terminated due to EOF or inactivity
2229 timeout, with a positive value on error, and with a negative value on
2230 fatal error.
2231
2233 /usr/bin/socat
2234 /usr/bin/filan
2235 /usr/bin/procan
2236
2238 SOCAT_DEFAULT_LISTEN_IP
2239 (Values 4 or 6) Sets the IP version to be used for listen, recv,
2240 and recvfrom addresses if no pf (protocol-family) option is
2241 given. Is overridden by socat options -4 or -6.
2242 SOCAT_PREFERRED_RESOLVE_IP
2244 (Values 0, 4, or 6) Sets the IP version to be used when resolv‐
2245 ing target host names when version is not specified by address
2246 type, option pf (protocol-family), or address format. If name
2247 resolution does not return a matching entry, the first result
2248 (with differing IP version) is taken. With value 0, socat always
2249 selects the first record and its IP version.
2250 SOCAT_FORK_WAIT
2252 Specifies the time (seconds) to sleep the parent and child pro‐
2253 cesses after successful fork(). Useful for debugging.
2254 HOSTNAME
2256 Is used to determine the hostname for logging (see -lh).
2257 LOGNAME
2259 Is used as name for the socks client user name if no socksuser
2260 is given.
2261 With options su and su-d, LOGNAME is set to the given user name.
2262 USER Is used as name for the socks client user name if no socksuser
2264 is given and LOGNAME is empty.
2265 With options su and su-d, USER is set to the given user name.
2266 SHELL With options su and su-d, SHELL is set to the login shell of the
2268 given user.
2269 PATH Can be set with option path for exec and system addresses.
2271 HOME With options su and su-d, HOME is set to the home directory of
2273 the given user.
2274
2276 The work of the following groups and organizations was invaluable for
2277 this project:
2278 The FSF (GNU, http://www.fsf.org/ project with their free and portable
2280 development software and lots of other useful tools and libraries.
2281 The Linux developers community (http://www.linux.org/) for providing a
2283 free, open source operating system.
2284 Sourceforge (http://www.sourceforge.net/) for providing a compile farm
2286 with Solaris, FreeBSD, and MacOS X machines, making these ports possi‐
2287 ble.
2288 The Open Group (http://www.unix-systems.org/) for making their standard
2290 specifications available on the Internet for free.
2291
2293 This man page describes version 1.5.0 of socat.
2294
2296 Addresses cannot be nested, so a single socat process cannot, e.g.,
2297 drive ssl over socks.
2298 Address option ftruncate without value uses default 1 instead of 0.
2300 Verbose modes (-x and/or -v) display line termination characters incon‐
2302 sistently when address options cr or crnl are used: They show the data
2303 after conversion in either direction.
2304 The data transfer blocksize setting (-b) is ignored with address read‐
2306 line.
2307 Send bug reports to <socat@dest-unreach.org>
2309
2311 nc(1), netcat6(1), sock(1), rinetd(8), cage(1), socks.conf(5),
2312 openssl(1), stunnel(8), pty(1), rlwrap(1), setsid(1)
2313 Socat home page http://www.dest-unreach.org/socat/
2315
2317 Gerhard Rieger <rieger@dest-unreach.org>
2318socat July 2006 socat(1)