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.
22 Filan is a utility that prints information about its active file
24 descriptors to stdout. It has been written for debugging socat, but
25 might be useful for other purposes too. Use the -h option to find more
26 infos.
27 Procan is a utility that prints information about process parameters to
29 stdout. It has been written to better understand some UNIX process
30 properties and for debugging socat, but might be useful for other pur‐
31 poses too.
32 The life cycle of a socat instance typically consists of four phases.
34 In the init phase, the command line options are parsed and logging is
36 initialized.
37 During the open phase, socat opens the first address and afterwards the
39 second address. These steps are usually blocking; thus, especially for
40 complex address types like socks, connection requests or authentication
41 dialogs must be completed before the next step is started.
42 In the transfer phase, socat watches both streams' read and write file
44 descriptors via select() , and, when data is available on one side and
45 can be written to the other side, socat reads it, performs newline
46 character conversions if required, and writes the data to the write
47 file descriptor of the other stream, then continues waiting for more
48 data in both directions.
49 When one of the streams effectively reaches EOF, the closing phase
51 begins. Socat transfers the EOF condition to the other stream, i.e.
52 tries to shutdown only its write stream, giving it a chance to termi‐
53 nate gracefully. For a defined time socat continues to transfer data in
54 the other direction, but then closes all remaining channels and termi‐
55 nates.
56
58 Socat provides some command line options that modify the behaviour of
59 the program. They have nothing to do with so called address options
60 that are used as parts of address specifications.
61 -V Print version and available feature information to stdout, and
63 exit.
64 -h | -?
66 Print a help text to stdout describing command line options and
67 available address types, and exit.
68 -hh | -??
70 Like -h, plus a list of the short names of all available address
71 options. Some options are platform dependend, so this output is
72 helpful for checking the particular implementation.
73 -hhh | -???
75 Like -hh, plus a list of all available address option names.
76 -d Without this option, only fatal and error messages are gener‐
78 ated; applying this option also prints warning messages. See
79 DIAGNOSTICS for more information.
80 -d -d Prints fatal, error, warning, and notice messages.
82 -d -d -d
84 Prints fatal, error, warning, notice, and info messages.
85 -d -d -d -d
87 Prints fatal, error, warning, notice, info, and debug messages.
88 -D Logs information about file descriptors before starting the
90 transfer phase.
91 -ly[<facility>]
93 Writes messages to syslog instead of stderr; severity as defined
94 with -d option. With optional <facility>, the syslog type can be
95 selected, default is "daemon".
96 -lf <logfile>
98 Writes messages to <logfile> [filename] instead of stderr.
99 -ls Writes messages to stderr (this is the default).
101 -lp<progname>
103 Overrides the program name printed in error messages and used
104 for constructing environment variable names.
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 interval 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 (exam‐
157 ple).
158 -U Uses unidirectional mode in reverse direction. The first address
160 is only used for writing, and the second address is only used
161 for reading.
162 -g During address option parsing, don't check if the option is con‐
164 sidered useful in the given address environment. Use it if you
165 want to force, e.g., appliance of a socket option to a serial
166 device.
167 -L<lockfile>
169 If lockfile exists, exits with error. If lockfile does not
170 exist, creates it and continues, unlinks lockfile on exit.
171 -W<lockfile>
173 If lockfile exists, waits until it disappears. When lockfile
174 does not exist, creates it and continues, unlinks lockfile on
175 exit.
176 -4 Use IP version 4 in case that the addresses do not implicitly or
178 explicitly specify a version; this is the default.
179 -6 Use IP version 6 in case that the addresses do not implicitly or
181 explicitly specify a version.
182
185 With the address command line arguments, the user gives socat instruc‐
186 tions and the necessary information for establishing the byte streams.
187 An address specification usually consists of an address type keyword,
189 zero or more required address parameters separated by ':' from the key‐
190 word and from each other, and zero or more address options separated by
191 ','.
192 The keyword specifies the address type (e.g., TCP4, OPEN, EXEC). For
194 some keywords there exist synonyms ('-' for STDIO, TCP for TCP4). Key‐
195 words are case insensitive. For a few special address types, the key‐
196 word may be omitted: Address specifications starting with a number are
197 assumed to be FD (raw file descriptor) addresses; if a '/' is found
198 before the first ':' or ',', GOPEN (generic file open) is assumed.
199 The required number and type of address parameters depend on the
201 address type. E.g., TCP4 requires a server specification (name or
202 address), and a port specification (number or service name).
203 Zero or more address options may be given with each address. They
205 influence the address in some ways. Options consist of an option key‐
206 word or an option keyword and a value, separated by '='. Option key‐
207 words are case insensitive. For filtering the options that are useful
208 with an address type, each option is member of one option group. For
209 each address type there is a set of option groups allowed. Only options
210 belonging to one of these address groups may be used (except with
211 option -g).
212 Address specifications following the above schema are also called sin‐
214 gle address specifications. Two single addresses can be combined with
215 "!!" to form a dual type address for one channel. Here, the first
216 address is used by socat for reading data, and the second address for
217 writing data. There is no way to specify an option only once for being
218 applied to both single addresses.
219 Usually, addresses are opened in read/write mode. When an address is
221 part of a dual address specification, or when option -u or -U is used,
222 an address might be used only for reading or for writing. Considering
223 this is important with some address types.
224 With socat version 1.5.0 and higher, the lexical analysis tries to han‐
226 dle quotes and parenthesis meaningfully and allows escaping of special
227 characters. If one of the characters ( { [ ' is found, the correspond‐
228 ing closing character - ) } ] ' - is looked for; they may also be
229 nested. Within these constructs, socats special characters and strings
230 : , !! are not handled specially. All those characters and strings can
231 be escaped with \ or within ""
232
234 This section describes the available address types with their keywords,
235 parameters, and semantics.
236 CREATE:<filename>
238 Opens <filename> with creat() and uses the file descriptor for
239 writing. This address type requires write-only context, because
240 a file opened with creat cannot be read from. <filename> must
241 be a valid existing or not existing path. If <filename> is a
242 named pipe, creat() might block; if <filename> refers to a
243 socket, this is an error.
244 Option groups: FD,REG,NAMED
245 Useful options: mode, user, group, unlink-early, unlink-late,
246 append
247 See also: OPEN, GOPEN
248 EXEC:<command-line>
250 Forks a sub process that establishes communication with its par‐
251 ent process and invokes the specified program with execvp() .
252 <command-line> is a simple command with arguments separated by
253 single spaces. If the program name contains a '/', the part
254 after the last '/' is taken as ARGV[0]. If the program name is a
255 relative path, the execvp() semantics for finding the program
256 via $PATH apply. After successful program start, socat writes
257 data to stdin of the process and reads from its stdout using a
258 UNIX domain socket generated by socketpair() per default. (exam‐
259 ple)
260 Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
261 Useful options: path, fdin, fdout, chroot, su, su-d, nofork,
262 pty, stderr, ctty, setsid, pipes, login, sigint, sigquit
263 See also: SYSTEM
264 FD:<fdnum>
266 Uses the file descriptor <fdnum>. It must already exist as valid
267 UN*X file descriptor.
268 Option groups: FD (TERMIOS,REG,SOCKET)
269 See also: STDIO, STDIN, STDOUT, STDERR
270 GOPEN:<filename>
272 (Generic open) This address type tries to handle any file system
273 entry except directories usefully. <filename> may be a relative
274 or absolute path. If it already exists, its type is checked. In
275 case of a UNIX domain socket, socat connects; if connecting
276 fails, socat assumes a datagram socket and uses sendto() calls.
277 If the entry is not a socket, socat opens it applying the
278 O_APPEND flag. If it does not exist, it is opened with flag
279 O_CREAT as a regular file (example).
280 Option groups: FD,REG,SOCKET,NAMED,OPEN
281 See also: OPEN, CREATE, UNIX-CONNECT
282 IP-SENDTO:<host>:<protocol>
284 Opens a raw IP socket. Depending on host specification or option
285 pf, IP procotol version 4 or 6 is used. It uses <protocol> to
286 send packets to <host> [IP address] and receives packets from
287 host, ignores packets from other hosts. Protocol 255 uses the
288 raw socket with the IP header being part of the data.
289 Option groups: FD,SOCKET,IP4,IP6
290 Useful options: pf, ttl
291 See also: IP4-SENDTO, IP6-SENDTO, IP-RECVFROM, IP-RECV, UDP-
292 SENDTO, UNIX-SENDTO
293 INTERFACE:<interface>
295 Communicates with a network connected on an interface using raw
296 packets including link level data. <interface> is the name of
297 the network interface. Currently only available on Linux.
298 Option groups: FD,SOCKET
299 Useful options: pf, type
300 See also: ip-recv
301 IP4-SENDTO:<host>:<protocol>
303 Like IP-SENDTO, but always uses IPv4.
304 Option groups: FD,SOCKET,IP4
305 IP6-SENDTO:<host>:<protocol>
307 Like IP-SENDTO, but always uses IPv6.
308 Option groups: FD,SOCKET,IP6
309 IP-DATAGRAM:<address>:<protocol>
312 Sends outgoing data to the specified address which may in par‐
313 ticular be a broadcast or multicast address. Packets arriving on
314 the local socket are checked if their source addresses match
315 RANGE or TCPWRAP options. This address type can for example be
316 used for implementing symmetric or asymmetric broadcast or mul‐
317 ticast communications.
318 Option groups: FD, SOCKET, IP4, IP6, RANGE
319 Useful options: bind, range, tcpwrap, broadcast, ip-multicast-
320 loop, ip-multicast-ttl, ip-multicast-if, ip-add-membership, ttl,
321 tos, pf
322 See also: IP4-DATAGRAM, IP6-DATAGRAM, IP-SENDTO, IP-RECVFROM,
323 IP-RECV, UDP-DATAGRAM
324 IP4-DATAGRAM:<host>:<protocol>
326 Like IP-DATAGRAM, but always uses IPv4. (example)
327 Option groups: FD,SOCKET,IP4,RANGE
328 IP6-DATAGRAM:<host>:<protocol>
330 Like IP-DATAGRAM, but always uses IPv6. Please note that IPv6
331 does not know broadcasts.
332 Option groups: FD,SOCKET,IP6,RANGE
333 IP-RECVFROM:<protocol>
336 Opens a raw IP socket of <protocol>. Depending on option pf, IP
337 procotol version 4 or 6 is used. It receives one packet from an
338 unspecified peer and may send one or more answer packets to that
339 peer. This mode is particularly useful with fork option where
340 each arriving packet - from arbitrary peers - is handled by its
341 own sub process. This allows a behaviour similar to typical UDP
342 based servers like ntpd or named.
343 Please note that the reply packets might be fetched as incoming
344 traffic when sender and receiver IP address are identical
345 because there is no port number to distinguish the sockets.
346 This address works well with IP-SENDTO address peers (see
347 above). Protocol 255 uses the raw socket with the IP header
348 being part of the data.
349 Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
350 Useful options: pf, fork, range, ttl, broadcast
351 See also: IP4-RECVFROM, IP6-RECVFROM, IP-SENDTO, IP-RECV, UDP-
352 RECVFROM, UNIX-RECVFROM
353 IP4-RECVFROM:<protocol>
355 Like IP-RECVFROM, but always uses IPv4.
356 Option groups: FD,SOCKET,IP4,CHILD,RANGE
357 IP6-RECVFROM:<protocol>
359 Like IP-RECVFROM, but always uses IPv6.
360 Option groups: FD,SOCKET,IP6,CHILD,RANGE
361 IP-RECV:<protocol>
364 Opens a raw IP socket of <protocol>. Depending on option pf, IP
365 procotol version 4 or 6 is used. It receives packets from multi‐
366 ple unspecified peers and merges the data. No replies are pos‐
367 sible. It can be, e.g., addressed by socat IP-SENDTO address
368 peers. Protocol 255 uses the raw socket with the IP header
369 being part of the data.
370 Option groups: FD,SOCKET,IP4,IP6,RANGE
371 Useful options: pf, range
372 See also: IP4-RECV, IP6-RECV, IP-SENDTO, IP-RECVFROM, UDP-RECV,
373 UNIX-RECV
374 IP4-RECV:<protocol>
376 Like IP-RECV, but always uses IPv4.
377 Option groups: FD,SOCKET,IP4,RANGE
378 IP6-RECV:<protocol>
380 Like IP-RECV, but always uses IPv6.
381 Option groups: FD,SOCKET,IP6,RANGE
382 OPEN:<filename>
385 Opens <filename> using the open() system call (example). This
386 operation fails on UNIX domain sockets.
387 Note: This address type is rarly useful in bidirectional mode.
388 Option groups: FD,REG,NAMED,OPEN
389 Useful options: creat, excl, noatime, nofollow, append, rdonly,
390 wronly, lock, readbytes, ignoreeof
391 See also: CREATE, GOPEN, UNIX-CONNECT
392 OPENSSL:<host>:<port>
394 Tries to establish a SSL connection to <port> [TCP service] on
395 <host> [IP address] using TCP/IP version 4 or 6 depending on
396 address specification, name resolution, or option pf.
397 NOTE: The server certificate is only checked for validity
398 against cafile or capath, but not for match with the server's
399 name or its IP address!
400 Option groups: FD,SOCKET,IP4,IP6,TCP,OPENSSL,RETRY
401 Useful options: cipher, method, verify, cafile, capath, certifi‐
402 cate, key, bind, pf, connect-timeout, sourceport, retry
403 See also: OPENSSL-LISTEN, TCP
404 OPENSSL-LISTEN:<port>
406 Listens on tcp <port> [TCP service]. The IP version is 4 or the
407 one specified with pf. When a connection is accepted, this
408 address behaves as SSL server.
409 Note: You probably want to use the certificate option with this
410 address.
411 NOTE: The client certificate is only checked for validity
412 against cafile or capath, but not for match with the client's
413 name or its IP address!
414 Option groups: FD,SOCKET,IP4,IP6,TCP,LIS‐
415 TEN,OPENSSL,CHILD,RANGE,RETRY
416 Useful options: pf, cipher, method, verify, cafile, capath, cer‐
417 tificate, key, fork, bind, range, tcpwrap, su, reuseaddr, retry
418 See also: OPENSSL, TCP
419 PIPE:<filename>
421 If <filename> already exists, it is opened. If it does not
422 exist, a named pipe is created and opened. Beginning with socat
423 version 1.4.3, the named pipe is removed when the address is
424 closed (but see option unlink-close
425 Note: When a pipe is used for both reading and writing, it works
426 as echo service.
427 Note: When a pipe is used for both reading and writing, and
428 socat tries to write more bytes than the pipe can buffer (Linux
429 2.4: 2048 bytes), socat might block. Consider using socat
430 option, e.g., -b 2048
431 Option groups: FD,NAMED,OPEN
432 Useful options: rdonly, nonblock, group, user, mode, unlink-
433 early
434 See also: unnamed pipe
435 PIPE Creates an unnamed pipe and uses it for reading and writing. It
437 works as an echo, because everything written to it appeares
438 immediately as read data.
439 Note: When socat tries to write more bytes than the pipe can
440 queue (Linux 2.4: 2048 bytes), socat might block. Consider,
441 e.g., using option -b 2048
442 Option groups: FD
443 See also: named pipe
444 PROXY:<proxy>:<hostname>:<port>
446 Connects to an HTTP proxy server on port 8080 using TCP/IP ver‐
447 sion 4 or 6 depending on address specification, name resolution,
448 or option pf, and sends a CONNECT request for hostname:port. If
449 the proxy grants access and succeeds to connect to the target,
450 data transfer between socat and the target can start. Note that
451 the traffic need not be HTTP but can be an arbitrary protocol.
452 Option groups: FD,SOCKET,IP4,IP6,TCP,HTTP,RETRY
453 Useful options: proxyport, ignorecr, proxyauth, resolve, crnl,
454 bind, connect-timeout, mss, sourceport, retry
455 See also: SOCKS, TCP
456 PTY Generates a pseudo terminal (pty) and uses its master side.
458 Another process may open the pty's slave side using it like a
459 serial line or terminal. (example). If both the ptmx and the
460 openpty mechanisms are available, ptmx is used (POSIX).
461 Option groups: FD,NAMED,PTY,TERMIOS
462 Useful options: link, openpty, wait-slave, mode, user, group
463 See also: UNIX-LISTEN, PIPE, EXEC, SYSTEM
464 READLINE
466 Uses GNU readline and history on stdio to allow editing and
467 reusing input lines (example). This requires the GNU readline
468 and history libraries. Note that stdio should be a (pseudo) ter‐
469 minal device, otherwise readline does not seem to work.
470 Option groups: FD,READLINE,TERMIOS
471 Useful options: history, noecho
472 See also: STDIO
473 SCTP-CONNECT:<host>:<port>
475 Establishes an SCTP stream connection to the specified <host>
476 [IP address] and <port> [TCP service] using TCP/IP version 4 or
477 6 depending on address specification, name resolution, or option
478 pf.
479 Option groups: FD,SOCKET,IP4,IP6,SCTP,CHILD,RETRY
480 Useful options: bind, pf, connect-timeout, tos, mtudiscover,
481 sctp-maxseg, sctp-nodelay, nonblock, sourceport, retry, read‐
482 bytes
483 See also: SCTP4-CONNECT, SCTP6-CONNECT, SCTP-LISTEN, TCP-CONNECT
484 SCTP4-CONNECT:<host>:<port>
486 Like SCTP-CONNECT, but only supports IPv4 protocol.
487 Option groups: FD,SOCKET,IP4,SCTP,CHILD,RETRY
488 SCTP6-CONNECT:<host>:<port>
490 Like SCTP-CONNECT, but only supports IPv6 protocol.
491 Option groups: FD,SOCKET,IP6,SCTP,CHILD,RETRY
492 SCTP-LISTEN:<port>
494 Listens on <port> [TCP service] and accepts a TCP/IP connection.
495 The IP version is 4 or the one specified with address option pf,
496 socat option (-4, -6), or environment variable
497 SOCAT_DEFAULT_LISTEN_IP. Note that opening this address usually
498 blocks until a client connects.
499 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,SCTP,RETRY
500 Useful options: crnl, fork, bind, range, tcpwrap, pf, backlog,
501 sctp-maxseg, sctp-nodelay, su, reuseaddr, retry, cool-write
502 See also: SCTP4-LISTEN, SCTP6-LISTEN, TCP-LISTEN, SCTP-CONNECT
503 SCTP4-LISTEN:<port>
505 Like SCTP-LISTEN, but only supports IPv4 protocol.
506 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,SCTP,RETRY
507 SCTP6-LISTEN:<port>
509 Like SCTP-LISTEN, but only supports IPv6 protocol.
510 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,SCTP,RETRY
511 SOCKET-CONNECT:<domain>:<protocol>:<remote-address>
513 Creates a stream socket using the first and second given socket
514 parameters and SOCK_STREAM (see man socket\(2)) and connects to
515 the remote-address. The two socket parameters have to be speci‐
516 fied by int numbers. Consult your OS documentation and include
517 files to find the appropriate values. The remote-address must be
518 the data representation of a sockaddr structure without sa_fam‐
519 ily and (BSD) sa_len components.
520 Please note that you can - beyond the options of the specified
521 groups - also use options of higher level protocols when you
522 apply socat option -g.
523 Option groups: FD,SOCKET,CHILD,RETRY
524 Useful options: bind, setsockopt-int, setsockopt-bin, setsock‐
525 opt-string
526 See also: TCP, UDP-CONNECT, UNIX-CONNECT, SOCKET-LISTEN, SOCKET-
527 SENDTO
528 SOCKET-DATAGRAM:<domain>:<type>:<protocol>:<remote-address>
530 Creates a datagram socket using the first three given socket
531 parameters (see man socket\(2)) and sends outgoing data to the
532 remote-address. The three socket parameters have to be specified
533 by int numbers. Consult your OS documentation and include files
534 to find the appropriate values. The remote-address must be the
535 data representation of a sockaddr structure without sa_family
536 and (BSD) sa_len components.
537 Please note that you can - beyond the options of the specified
538 groups - also use options of higher level protocols when you
539 apply socat option -g.
540 Option groups: FD,SOCKET,RANGE
541 Useful options: bind, range, setsockopt-int, setsockopt-bin,
542 setsockopt-string
543 See also: UDP-DATAGRAM, IP-DATAGRAM, SOCKET-SENDTO, SOCKET-RECV,
544 SOCKET-RECVFROM
545 SOCKET-LISTEN:<domain>:<protocol>:<local-address>
547 Creates a stream socket using the first and second given socket
548 parameters and SOCK_STREAM (see man socket\(2)) and waits for
549 incoming connections on local-address. The two socket parameters
550 have to be specified by int numbers. Consult your OS documenta‐
551 tion and include files to find the appropriate values. The
552 local-address must be the data representation of a sockaddr
553 structure without sa_family and (BSD) sa_len components.
554 Please note that you can - beyond the options of the specified
555 groups - also use options of higher level protocols when you
556 apply socat option -g.
557 Option groups: FD,SOCKET,LISTEN,RANGE,CHILD,RETRY
558 Useful options: setsockopt-int, setsockopt-bin, setsockopt-
559 string
560 See also: TCP, UDP-CONNECT, UNIX-CONNECT, SOCKET-LISTEN, SOCKET-
561 SENDTO, SOCKET-SENDTO
562 SOCKET-RECV:<domain>:<type>:<protocol>:<local-address>
564 Creates a socket using the three given socket parameters (see
565 man socket\(2)) and binds it to <local-address>. Receives arriv‐
566 ing data. The three parameters have to be specified by int num‐
567 bers. Consult your OS documentation and include files to find
568 the appropriate values. The local-address must be the data rep‐
569 resentation of a sockaddr structure without sa_family and (BSD)
570 sa_len components.
571 Option groups: FD,SOCKET,RANGE
572 Useful options: range, setsockopt-int, setsockopt-bin, setsock‐
573 opt-string
574 See also: UDP-RECV, IP-RECV, UNIX-RECV, SOCKET-DATAGRAM, SOCKET-
575 SENDTO, SOCKET-RECVFROM
576 SOCKET-RECVFROM:<domain>:<type>:<protocol>:<local-address>
578 Creates a socket using the three given socket parameters (see
579 man socket\(2)) and binds it to <local-address>. Receives arriv‐
580 ing data and sends replies back to the sender. The first three
581 parameters have to be specified as int numbers. Consult your OS
582 documentation and include files to find the appropriate values.
583 The local-address must be the data representation of a sockaddr
584 structure without sa_family and (BSD) sa_len components.
585 Option groups: FD,SOCKET,CHILD,RANGE
586 Useful options: fork, range, setsockopt-int, setsockopt-bin,
587 setsockopt-string
588 See also: UDP-RECVFROM, IP-RECVFROM, UNIX-RECVFROM, SOCKET-DATA‐
589 GRAM, SOCKET-SENDTO, SOCKET-RECV
590 SOCKET-SENDTO:<domain>:<type>:<protocol>:<remote-address>
592 Creates a socket using the three given socket parameters (see
593 man socket\(2)). Sends outgoing data to the given address and
594 receives replies. The three parameters have to be specified as
595 int numbers. Consult your OS documentation and include files to
596 find the appropriate values. The remote-address must be the data
597 representation of a sockaddr structure without sa_family and
598 (BSD) sa_len components.
599 Option groups: FD,SOCKET
600 Useful options: bind, setsockopt-int, setsockopt-bin, setsock‐
601 opt-string
602 See also: UDP-SENDTO, IP-SENDTO, UNIX-SENDTO, SOCKET-DATAGRAM,
603 SOCKET-RECV SOCKET-RECVFROM
604 SOCKS4:<socks-server>:<host>:<port>
606 Connects via <socks-server> [IP address] to <host> [IPv4
607 address] on <port> [TCP service], using socks version 4 protocol
608 over IP version 4 or 6 depending on address specification, name
609 resolution, or option pf (example).
610 Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
611 Useful options: socksuser, socksport, sourceport, pf, retry
612 See also: SOCKS4A, PROXY, TCP
613 SOCKS4A:<socks-server>:<host>:<port>
615 like SOCKS4, but uses socks protocol version 4a, thus leaving
616 host name resolution to the socks server.
617 Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
618 STDERR Uses file descriptor 2.
620 Option groups: FD (TERMIOS,REG,SOCKET)
621 See also: FD
622 STDIN Uses file descriptor 0.
624 Option groups: FD (TERMIOS,REG,SOCKET)
625 Useful options: readbytes
626 See also: FD
627 STDIO Uses file descriptor 0 for reading, and 1 for writing.
629 Option groups: FD (TERMIOS,REG,SOCKET)
630 Useful options: readbytes
631 See also: FD
632 STDOUT Uses file descriptor 1.
634 Option groups: FD (TERMIOS,REG,SOCKET)
635 See also: FD
636 SYSTEM:<shell-command>
638 Forks a sub process that establishes communication with its par‐
639 ent process and invokes the specified program with system() .
640 Please note that <shell-command> [string] must not contain ','
641 or "!!", and that shell meta characters may have to be pro‐
642 tected. After successful program start, socat writes data to
643 stdin of the process and reads from its stdout.
644 Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
645 Useful options: path, fdin, fdout, chroot, su, su-d, nofork,
646 pty, stderr, ctty, setsid, pipes, sigint, sigquit
647 See also: EXEC
648 TCP:<host>:<port>
650 Connects to <port> [TCP service] on <host> [IP address] using
651 TCP/IP version 4 or 6 depending on address specification, name
652 resolution, or option pf.
653 Option groups: FD,SOCKET,IP4,IP6,TCP,RETRY
654 Useful options: crnl, bind, pf, connect-timeout, tos, mtudis‐
655 cover, mss, nodelay, nonblock, sourceport, retry, readbytes
656 See also: TCP4, TCP6, TCP-LISTEN, UDP, SCTP-CONNECT, UNIX-CON‐
657 NECT
658 TCP4:<host>:<port>
660 Like TCP, but only supports IPv4 protocol (example).
661 Option groups: FD,SOCKET,IP4,TCP,RETRY
662 TCP6:<host>:<port>
664 Like TCP, but only supports IPv6 protocol.
665 Option groups: FD,SOCKET,IP6,TCP,RETRY
666 TCP-LISTEN:<port>
668 Listens on <port> [TCP service] and accepts a TCP/IP connection.
669 The IP version is 4 or the one specified with address option pf,
670 socat option (-4, -6), or environment variable
671 SOCAT_DEFAULT_LISTEN_IP. Note that opening this address usually
672 blocks until a client connects.
673 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,TCP,RETRY
674 Useful options: crnl, fork, bind, range, tcpwrap, pf, backlog,
675 mss, su, reuseaddr, retry, cool-write
676 See also: TCP4-LISTEN, TCP6-LISTEN, UDP-LISTEN, SCTP-LISTEN,
677 UNIX-LISTEN, OPENSSL-LISTEN, TCP-CONNECT
678 TCP4-LISTEN:<port>
680 Like TCP-LISTEN, but only supports IPv4 protocol (example).
681 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,TCP,RETRY
682 TCP6-LISTEN:<port>
684 Like TCP-LISTEN, but only supports IPv6 protocol.
685 Additional useful option: ipv6only
686 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,TCP,RETRY
687 TUN:<if-addr>/<bits>
689 Creates a Linux TUN/TAP device and assignes to it the address
690 and netmask defined by the parameters. The resulting network
691 interface is ready for use by other processes; socat serves its
692 "wire side". This address requires read and write access to the
693 tunnel cloning device, usually /dev/net/tun .
694 Option groups: FD,NAMED,OPEN,TUN
695 Useful options: iff-up, tun-device, tun-name, tun-type, iff-no-
696 pi
697 See also: ip-recv
698 UDP:<host>:<port>
700 Connects to <port> [UDP service] on <host> [IP address] using
701 UDP/IP version 4 or 6 depending on address specification, name
702 resolution, or option pf.
703 Please note that, due to UDP protocol properties, no real con‐
704 nection is established; data has to be sent for `connecting' to
705 the server, and no end-of-file condition can be transported.
706 Option groups: FD,SOCKET,IP4,IP6
707 Useful options: ttl, tos, bind, sourceport, pf
708 See also: UDP4, UDP6, UDP-LISTEN, TCP, IP
709 UDP4:<host>:<port>
711 Like UDP, but only supports IPv4 protocol.
712 Option groups: FD,SOCKET,IP4
713 UDP6:<host>:<port>
715 Like UDP, but only supports IPv6 protocol.
716 Option groups: FD,SOCKET,IP6
717 UDP-DATAGRAM:<address>:<port>
719 Sends outgoing data to the specified address which may in par‐
720 ticular be a broadcast or multicast address. Packets arriving on
721 the local socket are checked for the correct remote port and if
722 their source addresses match RANGE or TCPWRAP options. This
723 address type can for example be used for implementing symmetric
724 or asymmetric broadcast or multicast communications.
725 Option groups: FD,SOCKET,IP4,IP6,RANGE
726 Useful options: bind, range, tcpwrap, broadcast, ip-multicast-
727 loop, ip-multicast-ttl, ip-multicast-if, ip-add-membership, ttl,
728 tos, sourceport, pf
729 See also: UDP4-DATAGRAM, UDP6-DATAGRAM, UDP-SENDTO, UDP-
730 RECVFROM, UDP-RECV, UDP-CONNECT, UDP-LISTEN, IP-DATAGRAM
731 UDP4-DATAGRAM:<address>:<port>
733 Like UDP-DATAGRAM, but only supports IPv4 protocol (example1,
734 example2).
735 Option groups: FD,SOCKET,IP4, RANGE
736 UDP6-DATAGRAM:<address>:<port>
738 Like UDP-DATAGRAM, but only supports IPv6 protocol.
739 Option groups: FD,SOCKET,IP6,RANGE
740 UDP-LISTEN:<port>
742 Waits for a UDP/IP packet arriving on <port> [UDP service] and
743 `connects' back to sender. The accepted IP version is 4 or the
744 one specified with option pf. Please note that, due to UDP pro‐
745 tocol properties, no real connection is established; data has to
746 arrive from the peer first, and no end-of-file condition can be
747 transported. Note that opening this address usually blocks until
748 a client connects.
749 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6
750 Useful options: fork, bind, range, pf
751 See also: UDP, UDP4-LISTEN, UDP6-LISTEN, TCP-LISTEN
752 UDP4-LISTEN:<port>
754 Like UDP-LISTEN, but only support IPv4 protocol.
755 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4
756 UDP6-LISTEN:<port>
758 Like UDP-LISTEN, but only support IPv6 protocol.
759 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6
760 UDP-SENDTO:<host>:<port>
762 Communicates with the specified peer socket, defined by <port>
763 [UDP service] on <host> [IP address], using UDP/IP version 4 or
764 6 depending on address specification, name resolution, or option
765 pf. It sends packets to and receives packets from that peer
766 socket only. This address effectively implements a datagram
767 client. It works well with socat UDP-RECVFROM and UDP-RECV
768 address peers.
769 Option groups: FD,SOCKET,IP4,IP6
770 Useful options: ttl, tos, bind, sourceport, pf
771 See also: UDP4-SENDTO, UDP6-SENDTO, UDP-RECVFROM, UDP-RECV, UDP-
772 CONNECT, UDP-LISTEN, IP-SENDTO
773 UDP4-SENDTO:<host>:<port>
775 Like UDP-SENDTO, but only supports IPv4 protocol.
776 Option groups: FD,SOCKET,IP4
777 UDP6-SENDTO:<host>:<port>
779 Like UDP-SENDTO, but only supports IPv6 protocol.
780 Option groups: FD,SOCKET,IP6
781 UDP-RECVFROM:<port>
783 Creates a UDP socket on <port> [UDP service] using UDP/IP ver‐
784 sion 4 or 6 depending on option pf. It receives one packet from
785 an unspecified peer and may send one or more answer packets to
786 that peer. This mode is particularly useful with fork option
787 where each arriving packet - from arbitrary peers - is handled
788 by its own sub process. This allows a behaviour similar to typi‐
789 cal UDP based servers like ntpd or named. This address works
790 well with socat UDP-SENDTO address peers.
791 Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
792 Useful options: fork, ttl, tos, bind, sourceport, pf
793 See also: UDP4-RECVFROM, UDP6-RECVFROM, UDP-SENDTO, UDP-RECV,
794 UDP-CONNECT, UDP-LISTEN, IP-RECVFROM, UNIX-RECVFROM
795 UDP4-RECVFROM:<port>
797 Like UDP-RECVFROM, but only supports IPv4 protocol.
798 Option groups: FD,SOCKET,IP4,CHILD,RANGE
799 UDP6-RECVFROM:<port>
801 Like UDP-RECVFROM, but only supports IPv6 protocol.
802 Option groups: FD,SOCKET,IP6,CHILD,RANGE
803 UDP-RECV:<port>
805 Creates a UDP socket on <port> [UDP service] using UDP/IP ver‐
806 sion 4 or 6 depending on option pf. It receives packets from
807 multiple unspecified peers and merges the data. No replies are
808 possible. It works well with, e.g., socat UDP-SENDTO address
809 peers; it behaves similar to a syslog server.
810 Option groups: FD,SOCKET,IP4,IP6,RANGE
811 Useful options: fork, pf, bind, sourceport, ttl, tos
812 See also: UDP4-RECV, UDP6-RECV, UDP-SENDTO, UDP-RECVFROM, UDP-
813 CONNECT, UDP-LISTEN, IP-RECV, UNIX-RECV
814 UDP4-RECV:<port>
816 Like UDP-RECV, but only supports IPv4 protocol.
817 Option groups: FD,SOCKET,IP4,RANGE
818 UDP6-RECV:<port>
820 Like UDP-RECV, but only supports IPv6 protocol.
821 Option groups: FD,SOCKET,IP6,RANGE
822 UNIX-CONNECT:<filename>
824 Connects to <filename> assuming it is a UNIX domain socket. If
825 <filename> does not exist, this is an error; if <filename> is
826 not a UNIX domain socket, this is an error; if <filename> is a
827 UNIX domain socket, but no process is listening, this is an
828 error.
829 Option groups: FD,SOCKET,NAMED,RETRY,UNIX
830 ) Useful options: bind
831 See also: UNIX-LISTEN, UNIX-SENDTO, TCP
832 UNIX-LISTEN:<filename>
834 Listens on <filename> using a UNIX domain stream socket and
835 accepts a connection. If <filename> exists and is not a socket,
836 this is an error. If <filename> exists and is a UNIX domain
837 socket, binding to the address fails (use option unlink-early!).
838 Note that opening this address usually blocks until a client
839 connects. Beginning with socat version 1.4.3, the file system
840 entry is removed when this address is closed (but see option
841 unlink-close) (example).
842 Option groups: FD,SOCKET,NAMED,LISTEN,CHILD,RETRY,UNIX
843 Useful options: fork, umask, mode, user, group, unlink-early
844 See also: UNIX-CONNECT, UNIX-RECVFROM, UNIX-RECV, TCP-LISTEN
845 UNIX-SENDTO:<filename>
847 Communicates with the specified peer socket, defined by [<file‐
848 name>] assuming it is a UNIX domain datagram socket. It sends
849 packets to and receives packets from that peer socket only.
850 Please note that it might be neccessary to bind the local socket
851 to an address (e.g. /tmp/sock1, which must not exist before).
852 This address type works well with socat UNIX-RECVFROM and UNIX-
853 RECV address peers.
854 Option groups: FD,SOCKET,NAMED,UNIX
855 Useful options: bind
856 See also: UNIX-RECVFROM, UNIX-RECV, UNIX-CONNECT, UDP-SENDTO,
857 IP-SENDTO
858 UNIX-RECVFROM:<filename>
860 Creates a UNIX domain datagram socket [<filename>]. Receives
861 one packet and may send one or more answer packets to that peer.
862 This mode is particularly useful with fork option where each
863 arriving packet - from arbitrary peers - is handled by its own
864 sub process. This address works well with socat UNIX-SENDTO
865 address peers.
866 Option groups: FD,SOCKET,NAMED,CHILD,UNIX
867 Useful options: fork
868 See also: UNIX-SENDTO, UNIX-RECV, UNIX-LISTEN, UDP-RECVFROM, IP-
869 RECVFROM
870 UNIX-RECV:<filename>
872 Creates a UNIX domain datagram socket [<filename>]. Receives
873 packets from multiple unspecified peers and merges the data. No
874 replies are possible. It can be, e.g., addressed by socat UNIX-
875 SENDTO address peers. It behaves similar to a syslog server.
876 Option groups: FD,SOCKET,NAMED,UNIX
877 See also: UNIX-SENDTO, UNIX-RECVFROM, UNIX-LISTEN, UDP-RECV, IP-
878 RECV
879 UNIX-CLIENT:<filename>
881 Communicates with the specified peer socket, defined by [<file‐
882 name>] assuming it is a UNIX domain socket. It first tries to
883 connect and, if that fails, assumes it is a datagram socket,
884 thus supporting both types.
885 Option groups: FD,SOCKET,NAMED,UNIX
886 Useful options: bind
887 See also: UNIX-CONNECT, UNIX-SENDTO, GOPEN
888 ABSTRACT-CONNECT:<string>
890 ABSTRACT-LISTEN:<string>
892 ABSTRACT-SENDTO:<string>
894 ABSTRACT-RECVFROM:<string>
896 ABSTRACT-RECV:<string>
898 ABSTRACT-CLIENT:<string>
900 The ABSTRACT addresses are almost identical to the related UNIX
901 addresses except that they do not address file system based
902 sockets but an alternate UNIX domain address space. To archieve
903 this the socket address strings are prefixed with "\0" inter‐
904 nally. This feature is available (only?) on Linux. Option
905 groups are the same as with the related UNIX addresses, except
906 that the ABSTRACT addresses are not member of the NAMED group.
907
910 Address options can be applied to address specifications to influence
911 the process of opening the addresses and the properties of the result‐
912 ing data channels.
913 For technical reasons not every option can be applied to every address
915 type; e.g., applying a socket option to a regular file will fail. To
916 catch most useless combinations as early as in the open phase, the con‐
917 cept of option groups was introduced. Each option belongs to one or
918 more option groups. Options can be used only with address types that
919 support at least one of their option groups (but see option -g).
920 Address options have data types that their values must conform to.
922 Every address option consists of just a keyword or a keyword followed
923 by "=value", where value must conform to the options type. Some
924 address options manipulate parameters of system calls; e.g., option
925 sync sets the O_SYNC flag with the open() call. Other options cause a
926 system or library call; e.g., with option `ttl=value' the setsock‐
927 opt(fd, SOL_IP, IP_TTL, value, sizeof(int)) call is applied. Other
928 options set internal socat variables that are used during data trans‐
929 fer; e.g., `crnl' causes explicit character conversions. A few options
930 have more complex implementations; e.g., su-d (substuser-delayed)
931 inquires some user and group infos, stores them, and applies them later
932 after a possible chroot() call.
933 If multiple options are given to an address, their sequence in the
935 address specification has (almost) no effect on the sequence of their
936 execution/application. Instead, socat has built in an option phase
937 model that tries to bring the options in a useful order. Some options
938 exist in different forms (e.g., unlink, unlink-early, unlink-late) to
939 control the time of their execution.
940 If the same option is specified more than once within one address spec‐
942 ification, with equal or different values, the effect depends on the
943 kind of option. Options resulting in function calls like setsockopt()
944 cause multiple invocations. With options that set parameters for a
945 required call like open() or set internal flags, the value of the last
946 option occurrence is effective.
947 The existence or semantics of many options are system dependent. Socat
949 usually does NOT try to emulate missing libc or kernel features, it
950 just provides an interface to the underlying system. So, if an operat‐
951 ing system lacks a feature, the related option is simply not available
952 on this platform.
953 The following paragraphs introduce just the more common address
955 options. For a more comprehensive reference and to find information
956 about canonical option names, alias names, option phases, and platforms
957 see file xio.help.
958 FD option group
961 This option group contains options that are applied to a UN*X style
963 file descriptor, no matter how it was generated. Because all current
964 socat address types are file descriptor based, these options may be
965 applied to any address.
966 Note: Some of these options are also member of another option group,
967 that provides an other, non-fd based mechanism. For these options, it
968 depends on the actual address type and its option groups which mecha‐
969 nism is used. The second, non-fd based mechanism is prioritized.
970 cloexec=<bool>
972 Sets the FD_CLOEXEC flag with the fcntl() system call to value
973 <bool>. If set, the file descriptor is closed on exec() family
974 function calls. Socat internally handles this flag for the fds
975 it controls, so in most cases there will be no need to apply
976 this option.
977 setlk Tries to set a discretionary write lock to the whole file using
979 the fcntl(fd, F_SETLK, ...) system call. If the file is already
980 locked, this call results in an error. On Linux, when the file
981 permissions for group are "S" (g-x,g+s), and the file system is
982 locally mounted with the "mand" option, the lock is mandatory,
983 i.e. prevents other processes from opening the file.
984 setlkw Tries to set a discretionary waiting write lock to the whole
986 file using the fcntl(fd, F_SETLKW, ...) system call. If the
987 file is already locked, this call blocks. See option setlk for
988 information about making this lock mandatory.
989 setlk-rd
991 Tries to set a discretionary read lock to the whole file using
992 the fcntl(fd, F_SETLK, ...) system call. If the file is already
993 write locked, this call results in an error. See option setlk
994 for information about making this lock mandatory.
995 setlkw-rd
997 Tries to set a discretionary waiting read lock to the whole file
998 using the fcntl(fd, F_SETLKW, ...) system call. If the file is
999 already write locked, this call blocks. See option setlk for
1000 information about making this lock mandatory.
1001 flock-ex
1003 Tries to set a blocking exclusive advisory lock to the file
1004 using the flock(fd, LOCK_EX) system call. Socat hangs in this
1005 call if the file is locked by another process.
1006 flock-ex-nb
1008 Tries to set a nonblocking exclusive advisory lock to the file
1009 using the flock(fd, LOCK_EX|LOCK_NB) system call. If the file is
1010 already locked, this option results in an error.
1011 flock-sh
1013 Tries to set a blocking shared advisory lock to the file using
1014 the flock(fd, LOCK_SH) system call. Socat hangs in this call if
1015 the file is locked by another process.
1016 flock-sh-nb
1018 Tries to set a nonblocking shared advisory lock to the file
1019 using the flock(fd, LOCK_SH|LOCK_NB) system call. If the file is
1020 already locked, this option results in an error.
1021 lock Sets a blocking lock on the file. Uses the setlk or flock mecha‐
1023 nism depending on availability on the particular platform. If
1024 both are available, the POSIX variant (setlkw) is used.
1025 user=<user>
1027 Sets the <user> (owner) of the stream. If the address is member
1028 of the NAMED option group, socat uses the chown() system call
1029 after opening the file or binding to the UNIX domain socket
1030 (race condition!). Without filesystem entry, socat sets the
1031 user of the stream using the fchown() system call. These calls
1032 might require root privilege.
1033 user-late=<user>
1035 Sets the owner of the fd to <user> with the fchown() system call
1036 after opening or connecting the channel. This is useful only on
1037 file system entries.
1038 group=<group>
1040 Sets the <group> of the stream. If the address is member of the
1041 NAMED option group, socat uses the chown() system call after
1042 opening the file or binding to the UNIX domain socket (race con‐
1043 dition!). Without filesystem entry, socat sets the group of the
1044 stream with the fchown() system call. These calls might require
1045 group membership or root privilege.
1046 group-late=<group>
1048 Sets the group of the fd to <group> with the fchown() system
1049 call after opening or connecting the channel. This is useful
1050 only on file system entries.
1051 mode=<mode>
1053 Sets the <mode> [mode_t] (permissions) of the stream. If the
1054 address is member of the NAMED option group and uses the open()
1055 or creat() call, the mode is applied with these. If the address
1056 is member of the NAMED option group without using these system
1057 calls, socat uses the chmod() system call after opening the
1058 filesystem entry or binding to the UNIX domain socket (race con‐
1059 dition!). Otherwise, socat sets the mode of the stream using
1060 fchmod() . These calls might require ownership or root privi‐
1061 lege.
1062 perm-late=<mode>
1064 Sets the permissions of the fd to value <mode> [mode_t] using
1065 the fchmod() system call after opening or connecting the chan‐
1066 nel. This is useful only on file system entries.
1067 append=<bool>
1069 Always writes data to the actual end of file. If the address is
1070 member of the OPEN option group, socat uses the O_APPEND flag
1071 with the open() system call (example). Otherwise, socat applies
1072 the fcntl(fd, F_SETFL, O_APPEND) call.
1073 nonblock=<bool>
1075 Tries to open or use file in nonblocking mode. Its only effects
1076 are that the connect() call of TCP addresses does not block, and
1077 that opening a named pipe for reading does not block. If the
1078 address is member of the OPEN option group, socat uses the
1079 O_NONBLOCK flag with the open() system call. Otherwise, socat
1080 applies the fcntl(fd, F_SETFL, O_NONBLOCK) call.
1081 binary Opens the file in binary mode to avoid implicit line terminator
1083 conversions (Cygwin).
1084 text Opens the file in text mode to force implicit line terminator
1086 conversions (Cygwin).
1087 noinherit
1089 Does not keep this file open in a spawned process (Cygwin).
1090 cool-write
1092 Takes it easy when write fails with EPIPE or ECONNRESET and logs
1093 the message with notice level instead of error. This prevents
1094 the log file from being filled with useless error messages when
1095 socat is used as a high volume server or proxy where clients
1096 often abort the connection.
1097 This option is experimental.
1098 end-close
1100 Changes the (address dependent) method of ending a connection to
1101 just close the file descriptors. This is useful when the connec‐
1102 tion is to be reused by or shared with other processes (exam‐
1103 ple).
1104 Normally, socket connections will be ended with shutdown(2)
1105 which terminates the socket even if it is shared by multiple
1106 processes. close(2) "unlinks" the socket from the process but
1107 keeps it active as long as there are still links from other pro‐
1108 cesses.
1109 Similarly, when an address of type EXEC or SYSTEM is ended,
1110 socat usually will explicitely kill the sub process. With this
1111 option, it will just close the file descriptors.
1112 shut-none
1114 Changes the (address dependent) method of shutting down the
1115 write part of a connection to not do anything.
1116 shut-down
1118 Changes the (address dependent) method of shutting down the
1119 write part of a connection to shutdown\(fd, SHUT_WR). Is only
1120 useful with sockets.
1121 shut-close
1123 Changes the (address dependent) method of shutting down the
1124 write part of a connection to close\(fd).
1125 shut-null
1127 When one address indicates EOF, socat will send a zero sized
1128 packet to the write channel of the other address to transfer the
1129 EOF condition. This is useful with UDP and other datagram proto‐
1130 cols. Has been tested against netcat and socat with option null-
1131 eof.
1132 null-eof
1134 Normally socat will ignore empty (zero size payload) packets
1135 arriving on datagram sockets, so it survives port scans. With
1136 this option socat interprets empty datagram packets as EOF indi‐
1137 cator (see shut-null).
1138 ioctl-void=<request>
1140 Calls ioctl() with the request value as second argument and NULL
1141 as third argument. This option allows to utilize ioctls that are
1142 not explicitely implemented in socat.
1143 ioctl-int=<request>:<value>
1145 Calls ioctl() with the request value as second argument and the
1146 integer value as third argument.
1147 ioctl-intp=<request>:<value>
1149 Calls ioctl() with the request value as second argument and a
1150 pointer to the integer value as third argument.
1151 ioctl-bin=<request>:<value>
1153 Calls ioctl() with the request value as second argument and a
1154 pointer to the given data value as third argument. This data
1155 must be specified in <dalan> form.
1156 ioctl-string=<request>:<value>
1158 Calls ioctl() with the request value as second argument and a
1159 pointer to the given string as third argument. <dalan> form.
1160 NAMED option group
1163 These options work on file system entries.
1165 See also options user, group, and mode.
1166 user-early=<user>
1168 Changes the <user> (owner) of the file system entry before
1169 accessing it, using the chown() system call. This call might
1170 require root privilege.
1171 group-early=<group>
1173 Changes the <group> of the file system entry before accessing
1174 it, using the chown() system call. This call might require group
1175 membership or root privilege.
1176 perm-early=<mode>
1178 Changes the <mode> [mode_t] of the file system entry before
1179 accessing it, using the chmod() system call. This call might
1180 require ownership or root privilege.
1181 umask=<mode>
1183 Sets the umask of the process to <mode> [mode_t] before access‐
1184 ing the file system entry (useful with UNIX domain sockets!).
1185 This call might affect all further operations of the socat
1186 process!
1187 unlink-early
1189 Unlinks (removes) the file before opening it and even before
1190 applying user-early etc.
1191 unlink Unlinks (removes) the file before accessing it, but after user-
1193 early etc.
1194 unlink-late
1196 Unlinks (removes) the file after opening it to make it inacces‐
1197 sible for other processes after a short race condition.
1198 unlink-close
1200 Removes the addresses file system entry when closing the
1201 address. For named pipes, listening unix domain sockets, and
1202 the symbolic links of pty addresses, the default is 1; for cre‐
1203 ated files, opened files, generic opened files, and client unix
1204 domain sockets the default is 0.
1205 OPEN option group
1208 The OPEN group options allow to set flags with the open() system call.
1210 E.g., option `creat' sets the O_CREAT flag.
1211 See also options append and nonblock.
1212 creat=<bool>
1214 Creates the file if it does not exist (example).
1215 dsync=<bool>
1217 Blocks write() calls until metainfo is physically written to
1218 media.
1219 excl=<bool>
1221 With option creat, if file exists this is an error.
1222 largefile=<bool>
1224 On 32 bit systems, allows a file larger than 2^31 bytes.
1225 noatime
1227 Sets the O_NOATIME options, so reads do not change the access
1228 timestamp.
1229 noctty=<bool>
1231 Does not make this file the controlling terminal.
1232 nofollow=<bool>
1234 Does not follow symbolic links.
1235 nshare=<bool>
1237 Does not allow to share this file with other processes.
1238 rshare=<bool>
1240 Does not allow other processes to open this file for writing.
1241 rsync=<bool>
1243 Blocks write() until metainfo is physically written to media.
1244 sync=<bool>
1246 Blocks write() until data is physically written to media.
1247 rdonly=<bool>
1249 Opens the file for reading only.
1250 wronly=<bool>
1252 Opens the file for writing only.
1253 trunc Truncates the file to size 0 during opening it.
1255 REG and BLK option group
1258 These options are usually applied to a UN*X file descriptor, but their
1260 semantics make sense only on a file supporting random access.
1261 seek=<offset>
1263 Applies the lseek(fd, <offset>, SEEK_SET) (or lseek64 ) system
1264 call, thus positioning the file pointer absolutely to <offset>
1265 [off_t or off64_t]. Please note that a missing value defaults to
1266 1, not 0.
1267 seek-cur=<offset>
1269 Applies the lseek(fd, <offset>, SEEK_CUR) (or lseek64 ) system
1270 call, thus positioning the file pointer <offset> [off_t or
1271 off64_t] bytes relatively to its current position (which is usu‐
1272 ally 0). Please note that a missing value defaults to 1, not 0.
1273 seek-end=<offset>
1275 Applies the lseek(fd, <offset>, SEEK_END) (or lseek64 ) system
1276 call, thus positioning the file pointer <offset> [off_t or
1277 off64_t] bytes relatively to the files current end. Please note
1278 that a missing value defaults to 1, not 0.
1279 ftruncate=<offset>
1281 Applies the ftruncate(fd, <offset>) (or ftruncate64 if avail‐
1282 able) system call, thus truncating the file at the position
1283 <offset> [off_t or off64_t]. Please note that a missing value
1284 defaults to 1, not 0.
1285 secrm=<bool>
1287 unrm=<bool>
1289 compr=<bool>
1291 ext2-sync=<bool>
1293 immutable=<bool>
1295 ext2-append=<bool>
1297 nodump=<bool>
1299 ext2-noatime=<bool>
1301 journal-data=<bool>
1303 notail=<bool>
1305 dirsync=<bool>
1307 These options change non standard file attributes on operating
1308 systems and file systems that support these features, like Linux
1309 with ext2fs, ext3fs, or reiserfs. See man 1 chattr for informa‐
1310 tion on these options. Please note that there might be a race
1311 condition between creating the file and applying these options.
1312 PROCESS option group
1315 Options of this group change the process properties instead of just
1317 affecting one data channel. For EXEC and SYSTEM addresses and for LIS‐
1318 TEN and CONNECT type addresses with option FORK, these options apply to
1319 the child processes instead of the main socat process.
1320 chroot=<directory>
1322 Performs a chroot() operation to <directory> after processing
1323 the address (example). This call might require root privilege.
1324 chroot-early=<directory>
1326 Performs a chroot() operation to <directory> before opening the
1327 address. This call might require root privilege.
1328 setgid=<group>
1330 Changes the primary <group> of the process after processing the
1331 address. This call might require root privilege. Please note
1332 that this option does not drop other group related privileges.
1333 setgid-early=<group>
1335 Like setgit but is performed before opening the address.
1336 setuid=<user>
1338 Changes the <user> (owner) of the process after processing the
1339 address. This call might require root privilege. Please note
1340 that this option does not drop group related privileges. Check
1341 if option su better fits your needs.
1342 setuid-early=<user>
1344 Like setuid but is performed before opening the address.
1345 su=<user>
1347 Changes the <user> (owner) and groups of the process after pro‐
1348 cessing the address (example). This call might require root
1349 privilege.
1350 su-d=<user>
1352 Short name for substuser-delayed. Changes the <user> (owner)
1353 and groups of the process after processing the address (exam‐
1354 ple). The user and his groups are retrieved before a possible
1355 chroot() . This call might require root privilege.
1356 setpgid=<pid_t>
1358 Makes the process a member of the specified process group
1359 <pid_t>. If no value is given, or if the value is 0 or 1, the
1360 process becomes leader of a new process group.
1361 setsid Makes the process the leader of a new session (example).
1363 READLINE option group
1366 These options apply to the readline address type.
1368 history=<filename>
1370 Reads and writes history from/to <filename> (example).
1371 noprompt
1373 Since version 1.4.0, socat per default tries to determine a
1374 prompt - that is then passed to the readline call - by remember‐
1375 ing the last incomplete line of the output. With this option,
1376 socat does not pass a prompt to readline, so it begins line
1377 editing in the first column of the terminal.
1378 noecho=<pattern>
1380 Specifies a regular pattern for a prompt that prevents the fol‐
1381 lowing input line from being displayed on the screen and from
1382 being added to the history. The prompt is defined as the text
1383 that was output to the readline address after the lastest new‐
1384 line character and before an input character was typed. The pat‐
1385 tern is a regular expression, e.g. "^[Pp]assword:.*$" or
1386 "([Uu]ser:|[Pp]assword:)". See regex\(7) for details. (example)
1387 prompt=<string>
1389 Passes the string as prompt to the readline function. readline
1390 prints this prompt when stepping through the history. If this
1391 string matches a constant prompt issued by an interactive pro‐
1392 gram on the other socat address, consistent look and feel can be
1393 archieved.
1394 APPLICATION option group
1397 This group contains options that work at data level. Note that these
1399 options only apply to the "raw" data transferred by socat, but not to
1400 protocol data used by addresses like PROXY.
1401 cr Converts the default line termination character NL ('\n', 0x0a)
1403 to/from CR ('\r', 0x0d) when writing/reading on this channel.
1404 crnl Converts the default line termination character NL ('\n', 0x0a)
1406 to/from CRNL ("\r\n", 0x0d0a) when writing/reading on this chan‐
1407 nel (example). Note: socat simply strips all CR characters.
1408 ignoreeof
1410 When EOF occurs on this channel, socat ignores it and tries to
1411 read more data (like "tail -f") (example).
1412 readbytes=<bytes>
1414 socat reads only so many bytes from this address (the address
1415 provides only so many bytes for transfer and pretends to be at
1416 EOF afterwards). Must be greater than 0.
1417 lockfile=<filename>
1419 If lockfile exists, exits with error. If lockfile does not
1420 exist, creates it and continues, unlinks lockfile on exit.
1421 waitlock=<filename>
1423 If lockfile exists, waits until it disappears. When lockfile
1424 does not exist, creates it and continues, unlinks lockfile on
1425 exit.
1426 escape=<int>
1428 Specifies the numeric code of a character that triggers EOF on
1429 the input stream. It is useful with a terminal in raw mode
1430 (example).
1431 SOCKET option group
1434 These options are intended for all kinds of sockets, e.g. IP or UNIX
1436 domain. Most are applied with a setsockopt() call.
1437 bind=<sockname>
1439 Binds the socket to the given socket address using the bind()
1440 system call. The form of <sockname> is socket domain dependent:
1441 IP4 and IP6 allow the form [hostname|hostaddress][:(ser‐
1442 vice|port)] (example), UNIX domain sockets require <filename>.
1443 connect-timeout=<seconds>
1445 Abort the connection attempt after <seconds> [timeval] with
1446 error status.
1447 so-bindtodevice=<interface>
1449 Binds the socket to the given <interface>. This option might
1450 require root privilege.
1451 broadcast
1453 For datagram sockets, allows sending to broadcast addresses and
1454 receiving packets addressed to broadcast addresses.
1455 debug Enables socket debugging.
1457 dontroute
1459 Only communicates with directly connected peers, does not use
1460 routers.
1461 keepalive
1463 Enables sending keepalives on the socket.
1464 linger=<seconds>
1466 Blocks shutdown() or close() until data transfers have finished
1467 or the given timeout [int] expired.
1468 oobinline
1470 Places out-of-band data in the input data stream.
1471 priority=<priority>
1473 Sets the protocol defined <priority> [<int>] for outgoing pack‐
1474 ets.
1475 rcvbuf=<bytes>
1477 Sets the size of the receive buffer after the socket() call to
1478 <bytes> [int]. With TCP sockets, this value corresponds to the
1479 socket's maximal window size.
1480 rcvbuf-late=<bytes>
1482 Sets the size of the receive buffer when the socket is already
1483 connected to <bytes> [int]. With TCP sockets, this value corre‐
1484 sponds to the socket's maximal window size.
1485 rcvlowat=<bytes>
1487 Specifies the minimum number of received bytes [int] until the
1488 socket layer will pass the buffered data to socat.
1489 rcvtimeo=<seconds>
1491 Sets the receive timeout [timeval].
1492 reuseaddr
1494 Allows other sockets to bind to an address even if parts of it
1495 (e.g. the local port) are already in use by socat (example).
1496 sndbuf=<bytes>
1498 Sets the size of the send buffer after the socket() call to
1499 <bytes> [int].
1500 sndbuf-late=<bytes>
1502 Sets the size of the send buffer when the socket is connected to
1503 <bytes> [int].
1504 sndlowat=<bytes>
1506 Specifies the minimum number of bytes in the send buffer until
1507 the socket layer will send the data to <bytes> [int].
1508 sndtimeo=<seconds>
1510 Sets the send timeout to seconds [timeval].
1511 pf=<string>
1513 Forces the use of the specified IP version or protocol. <string>
1514 can be something like "ip4" or "ip6". The resulting value is
1515 used as first argument to the socket() or socketpair() calls.
1516 This option affects address resolution and the required syntax
1517 of bind and range options.
1518 type=<type>
1520 Sets the type of the socket, specified as second argument to the
1521 socket() or socketpair() calls, to <type> [int]. Address resolu‐
1522 tion is not affected by this option. Under Linux, 1 means
1523 stream oriented socket, 2 means datagram socket, and 3 means raw
1524 socket.
1525 prototype
1527 Sets the protocol of the socket, specified as third argument to
1528 the socket() or socketpair() calls, to <prototype> [int].
1529 Address resolution is not affected by this option. 6 means TCP,
1530 17 means UDP.
1531 so-timestamp
1533 Sets the SO_TIMESTAMP socket option. This enables receiving and
1534 logging of timestamp ancillary messages.
1535 setsockopt-int=<level>:<optname>:<optval>
1537 Invokes setsockopt() for the socket with the given parameters.
1538 level [int] is used as second argument to setsockopt() and spec‐
1539 ifies the layer, e.g. SOL_TCP for TCP (6 on Linux), or
1540 SOL_SOCKET for the socket layer (1 on Linux). optname [int] is
1541 the third argument to setsockopt() and tells which socket option
1542 is to be set. For the actual numbers you might have to look up
1543 the appropriate include files of your system. The 4th setsock‐
1544 opt() parameter, value [int], is passed to the function per
1545 pointer, and for the length parameter sizeof\(int) is taken
1546 implicitely.
1547 setsockopt-bin=<level>:<optname>:<optval>
1549 Like setsockopt-int, but <optval> must be provided in dalan for‐
1550 mat and specifies an arbitrary sequence of bytes; the length
1551 parameter is automatically derived from the data.
1552 setsockopt-string=<level>:<optname>:<optval>
1554 Like setsockopt-int, but <optval> must be a string. This string
1555 is passed to the function with trailing null character, and the
1556 length parameter is automatically derived from the data.
1557 UNIX option group
1560 These options apply to UNIX domain based addresses.
1562 unix-tightsocklen=[0|1]
1564 On socket operations, pass a socket address length that does not
1565 include the whole struct sockaddr_un record but (besides other
1566 components) only the relevant part of the filename or abstract
1567 string. Default is 1.
1568 IP4 and IP6 option groups
1571 These options can be used with IPv4 and IPv6 based sockets.
1573 tos=<tos>
1575 Sets the TOS (type of service) field of outgoing packets to
1576 <tos> [byte] (see RFC 791).
1577 ttl=<ttl>
1579 Sets the TTL (time to live) field of outgoing packets to <ttl>
1580 [byte].
1581 ip-options=<data>
1583 Sets IP options like source routing. Must be given in binary
1584 form, recommended format is a leading "x" followed by an even
1585 number of hex digits. This option may be used multiple times,
1586 data are appended. E.g., to connect to host 10.0.0.1 via some
1587 gateway using a loose source route, use the gateway as address
1588 parameter and set a loose source route using the option ip-
1589 options=x8307040a000001 .
1590 IP options are defined in RFC 791.
1591 mtudiscover=<0|1|2>
1593 Takes 0, 1, 2 to never, want, or always use path MTU discover on
1594 this socket.
1595 ip-pktinfo
1597 Sets the IP_PKTINFO socket option. This enables receiving and
1598 logging of ancillary messages containing destination address and
1599 interface (Linux) (example).
1600 ip-recverr
1602 Sets the IP_RECVERR socket option. This enables receiving and
1603 logging of ancillary messages containing detailled error infor‐
1604 mation.
1605 ip-recvopts
1607 Sets the IP_RECVOPTS socket option. This enables receiving and
1608 logging of IP options ancillary messages (Linux, *BSD).
1609 ip-recvtos
1611 Sets the IP_RECVTOS socket option. This enables receiving and
1612 logging of TOS (type of service) ancillary messages (Linux).
1613 ip-recvttl
1615 Sets the IP_RECVTTL socket option. This enables receiving and
1616 logging of TTL (time to live) ancillary messages (Linux, *BSD).
1617 ip-recvdstaddr
1619 Sets the IP_RECVDSTADDR socket option. This enables receiving
1620 and logging of ancillary messages containing destination address
1621 (*BSD) (example).
1622 ip-recvif
1624 Sets the IP_RECVIF socket option. This enables receiving and
1625 logging of interface ancillary messages (*BSD) (example).
1626 ip-add-membership=<multicast-address:interface-address>
1628 ip-add-membership=<multicast-address:interface-name>
1630 ip-add-membership=<multicast-address:interface-index>
1632 ip-add-membership=<multicast-address:interface-address:interface-name>
1634 ip-add-membership=<multicast-address:interface-address:interface-index>
1636 Makes the socket member of the specified multicast group. This
1637 is currently only implemented for IPv4. The option takes the IP
1638 address of the multicast group and info about the desired net‐
1639 work interface. The most common syntax is the first one, while
1640 the others are only available on systems that provide struct
1641 mreqn (Linux).
1642 The indices of active network interfaces can be shown using the
1643 utility procan.
1644 ip-multicast-if=<hostname>
1646 Specifies hostname or address of the network interface to be
1647 used for multicast traffic.
1648 ip-multicast-loop=<bool>
1650 Specifies if outgoing multicast traffic should loop back to the
1651 interface.
1652 ip-multicast-ttl=<byte>
1654 Sets the TTL used for outgoing multicast traffic. Default is 1.
1655 res-debug
1657 res-aaonly
1659 res-usevc
1661 res-primary
1663 res-igntc
1665 res-recurse
1667 res-defnames
1669 res-stayopen
1671 res-dnsrch
1673 These options set the corresponding resolver (name resolution)
1674 option flags. Append "=0" to clear a default option. See man
1675 resolver\(5) for more information on these options. Note: these
1676 options are valid only for the address they are applied to.
1677 IP6 option group
1679 These options can only be used on IPv6 based sockets. See IP options
1681 for options that can be applied to both IPv4 and IPv6 sockets.
1682 ipv6only=<bool>
1684 Sets the IPV6_V6ONLY socket option. If 0, the TCP stack will
1685 also accept connections using IPv4 protocol on the same port.
1686 The default is system dependent.
1687 ipv6-recvdstopts
1689 Sets the IPV6_RECVDSTOPTS socket option. This enables receiving
1690 and logging of ancillary messages containing the destination
1691 options.
1692 ipv6-recvhoplimit
1694 Sets the IPV6_RECVHOPLIMIT socket option. This enables receiving
1695 and logging of ancillary messages containing the hoplimit.
1696 ipv6-recvhopopts
1698 Sets the IPV6_RECVHOPOPTS socket option. This enables receiving
1699 and logging of ancillary messages containing the hop options.
1700 ipv6-recvpktinfo
1702 Sets the IPV6_RECVPKTINFO socket option. This enables receiving
1703 and logging of ancillary messages containing destination address
1704 and interface.
1705 ipv6-unicast-hops=link(TYPE_INT)(<int>)
1707 Sets the IPV6_UNICAST_HOPS socket option. This sets the hop
1708 count limit (TTL) for outgoing unicast packets.
1709 ipv6-recvrthdr
1711 Sets the IPV6_RECVRTHDR socket option. This enables receiving
1712 and logging of ancillary messages containing routing informa‐
1713 tion.
1714 ipv6-tclass
1716 Sets the IPV6_TCLASS socket option. This sets the transfer class
1717 of outgoing packets.
1718 ipv6-recvtclass
1720 Sets the IPV6_RECVTCLASS socket option. This enables receiving
1721 and logging of ancillary messages containing the transfer class.
1722 TCP option group
1725 These options may be applied to TCP sockets. They work by invoking set‐
1727 sockopt() with the appropriate parameters.
1728 cork Doesn't send packets smaller than MSS (maximal segment size).
1730 defer-accept
1732 While listening, accepts connections only when data from the
1733 peer arrived.
1734 keepcnt=<count>
1736 Sets the number of keepalives before shutting down the socket to
1737 <count> [int].
1738 keepidle=<seconds>
1740 Sets the idle time before sending the first keepalive to <sec‐
1741 onds> [int].
1742 keepintvl=<seconds>
1744 Sets the interval between two keepalives to <seconds> [int].
1745 linger2=<seconds>
1747 Sets the time to keep the socket in FIN-WAIT-2 state to <sec‐
1748 onds> [int].
1749 mss=<bytes>
1751 Sets the MSS (maximum segment size) after the socket() call to
1752 <bytes> [int]. This value is then proposed to the peer with the
1753 SYN or SYN/ACK packet (example).
1754 mss-late=<bytes>
1756 Sets the MSS of the socket after connection has been established
1757 to <bytes> [int].
1758 nodelay
1760 Turns off the Nagle algorithm for measuring the RTT (round trip
1761 time).
1762 rfc1323
1764 Enables RFC1323 TCP options: TCP window scale, round-trip time
1765 measurement (RTTM), and protect against wrapped sequence numbers
1766 (PAWS) (AIX).
1767 stdurg Enables RFC1122 compliant urgent pointer handling (AIX).
1769 syncnt=<count>
1771 Sets the maximal number of SYN retransmits during connect to
1772 <count> [int].
1773 md5sig Enables generation of MD5 digests on the packets (FreeBSD).
1775 noopt Disables use of TCP options (FreeBSD, MacOSX).
1777 nopush sets the TCP_NOPUSH socket option (FreeBSD, MacOSX).
1779 sack-disable
1781 Disables use the selective acknowledge feature (OpenBSD).
1782 signature-enable
1784 Enables generation of MD5 digests on the packets (OpenBSD).
1785 abort-threshold=<milliseconds>
1787 Sets the time to wait for an answer of the peer on an estab‐
1788 lished connection (HP-UX).
1789 conn-abort-threshold=<milliseconds>
1791 Sets the time to wait for an answer of the server during the
1792 initial connect (HP-UX).
1793 keepinit
1795 Sets the time to wait for an answer of the server during con‐
1796 nect\() before giving up. Value in half seconds, default is 150
1797 (75s) (Tru64).
1798 paws Enables the "protect against wrapped sequence numbers" feature
1800 (Tru64).
1801 sackena
1803 Enables selective acknowledge (Tru64).
1804 tsoptena
1806 Enables the time stamp option that allows RTT recalculation on
1807 existing connections (Tru64).
1808 SCTP option group
1811 These options may be applied to SCTP stream sockets.
1813 sctp-nodelay
1815 Sets the SCTP_NODELAY socket option that disables the Nagle
1816 algorithm.
1817 sctp-maxseg=<bytes>
1819 Sets the SCTP_MAXSEG socket option to <bytes> [int]. This value
1820 is then proposed to the peer with the SYN or SYN/ACK packet.
1821 UDP, TCP, and SCTP option groups
1824 Here we find options that are related to the network port mechanism and
1826 thus can be used with UDP, TCP, and SCTP client and server addresses.
1827 sourceport=<port>
1829 For outgoing (client) TCP and UDP connections, it sets the
1830 source <port> using an extra bind() call. With TCP or UDP lis‐
1831 ten addresses, socat immediately shuts down the connection if
1832 the client does not use this sourceport (example).
1833 lowport
1835 Outgoing (client) TCP and UDP connections with this option use
1836 an unused random source port between 640 and 1023 incl. On UNIX
1837 class operating systems, this requires root privilege, and thus
1838 indicates that the client process is authorized by local root.
1839 TCP and UDP listen addresses with this option immediately shut
1840 down the connection if the client does not use a sourceport <=
1841 1023. This mechanism can provide limited authorization under
1842 some circumstances.
1843 SOCKS option group
1846 When using SOCKS type addresses, some socks specific options can be
1848 set.
1849 socksport=<tcp service>
1851 Overrides the default "socks" service or port 1080 for the socks
1852 server port with <TCP service>.
1853 socksuser=<user>
1855 Sends the <user> [string] in the username field to the socks
1856 server. Default is the actual user name ($LOGNAME or $USER)
1857 (example).
1858 HTTP option group
1861 Options that can be provided with HTTP type addresses. The only HTTP
1863 address currently implemented is proxy-connect.
1864 proxyport=<TCP service>
1866 Overrides the default HTTP proxy port 8080 with <TCP service>.
1867 ignorecr
1869 The HTTP protocol requires the use of CR+NL as line terminator.
1870 When a proxy server violates this standard, socat might not
1871 understand its answer. This option directs socat to interprete
1872 NL as line terminator and to ignore CR in the answer. Neverthe‐
1873 less, socat sends CR+NL to the proxy.
1874 proxyauth=<username>:<password>
1876 Provide "basic" authentication to the proxy server. The argument
1877 to the option is used with a "Proxy-Authorization: Base" header
1878 in base64 encoded form.
1879 Note: username and password are visible for every user on the
1880 local machine in the process list; username and password are
1881 transferred to the proxy server unencrypted (base64 encoded) and
1882 might be sniffed.
1883 resolve
1885 Per default, socat sends to the proxy a CONNECT request contain‐
1886 ing the target hostname. With this option, socat resolves the
1887 hostname locally and sends the IP address. Please note that,
1888 according to RFC 2396, only name resolution to IPv4 addresses is
1889 implemented.
1890 RANGE option group
1893 These options check if a connecting client should be granted access.
1895 They can be applied to listening and receiving network sockets. tcp-
1896 wrappers options fall into this group.
1897 range=<address-range>
1899 After accepting a connection, tests if the peer is within range.
1900 For IPv4 addresses, address-range takes the form address/bits,
1901 e.g. 10.0.0.0/8, or address:mask, e.g. 10.0.0.0:255.0.0.0
1902 (example); for IPv6, it is [ip6-address/bits], e.g. [::1/128].
1903 If the client address does not match, socat issues a warning and
1904 keeps listening/receiving.
1905 tcpwrap[=<name>]
1907 Uses Wietse Venema's libwrap (tcpd) library to determine if the
1908 client is allowed to connect. The configuration files are
1909 /etc/hosts.allow and /etc/hosts.deny per default, see "man 5
1910 hosts_access" for more information. The optional <name> (type
1911 string) is passed to the wrapper functions as daemon process
1912 name (example). If omitted, the basename of socats invocation
1913 (argv[0]) is passed. If both tcpwrap and range options are
1914 applied to an address, both conditions must be fulfilled to
1915 allow the connection.
1916 allow-table=<filename>
1918 Takes the specified file instead of /etc/hosts.allow.
1919 deny-table=<filename>
1921 Takes the specified file instead of /etc/hosts.deny.
1922 tcpwrap-etc=<directoryname>
1924 Looks for hosts.allow and hosts.deny in the specified directory.
1925 Is overridden by options hosts-allow and hosts-deny.
1926 LISTEN option group
1929 Options specific to listening sockets.
1931 backlog=<count>
1933 Sets the backlog value passed with the listen() system call to
1934 <count> [int]. Default is 5.
1935 CHILD option group
1938 Options for addresses with multiple connections via child processes.
1940 fork After establishing a connection, handles its channel in a child
1942 process and keeps the parent process attempting to produce more
1943 connections, either by listening or by connecting in a loop
1944 (example).
1945 SSL-CONNECT and SSL-LISTEN differ in when they actually fork off
1946 the child: SSL-LISTEN forks before the SSL handshake, while SSL-
1947 CONNECT forks afterwards. RETRY and FOREVER options are not
1948 inherited by the child process.
1949 EXEC option group
1952 Options for addresses that invoke a program.
1954 path=<string>
1956 Overrides the PATH environment variable for searching the pro‐
1957 gram with <string>. This $PATH value is effective in the child
1958 process too.
1959 login Prefixes argv[0] for the execvp() call with '-', thus making a
1961 shell behave as login shell.
1962 FORK option group
1965 EXEC or SYSTEM addresses invoke a program using a child process and
1967 transfer data between socat and the program. The interprocess communi‐
1968 cation mechanism can be influenced with the following options. Per
1969 default, a socketpair() is created and assigned to stdin and stdout of
1970 the child process, while stderr is inherited from the socat process,
1971 and the child process uses file descriptors 0 and 1 for communicating
1972 with the main socat process.
1973 nofork Does not fork a subprocess for executing the program, instead
1975 calls execvp\() or system\() directly from the actual socat
1976 instance. This avoids the overhead of another process between
1977 the program and its peer, but introduces a lot of restrictions:
1978 o this option can only be applied to the second socat address.
1980 o it cannot be applied to a part of a dual address.
1982 o the first socat address cannot be OPENSSL or READLINE
1984 o socat options -b, -t, -D, -l, -v, -x become useless
1986 o for both addresses, options ignoreeof, cr, and crnl become use‐
1988 less
1989 o for the second address (the one with option nofork), options
1991 append, cloexec, flock, user, group, mode, nonblock, perm-late,
1992 setlk, and setpgid cannot be applied. Some of these could be
1993 used on the first address though.
1994 pipes Creates a pair of unnamed pipes for interprocess communication
1996 instead of a socket pair.
1997 openpty
1999 Establishes communication with the sub process using a pseudo
2000 terminal created with openpty() instead of the default (socket‐
2001 pair or ptmx).
2002 ptmx Establishes communication with the sub process using a pseudo
2004 terminal created by opening /dev/ptmx or /dev/ptc instead of the
2005 default (socketpair).
2006 pty Establishes communication with the sub process using a pseudo
2008 terminal instead of a socket pair. Creates the pty with an
2009 available mechanism. If openpty and ptmx are both available, it
2010 uses ptmx because this is POSIX compliant (example).
2011 ctty Makes the pty the controlling tty of the sub process (example).
2013 stderr Directs stderr of the sub process to its output channel by mak‐
2015 ing stderr a dup() of stdout (example).
2016 fdin=<fdnum>
2018 Assigns the sub processes input channel to its file descriptor
2019 <fdnum> instead of stdin (0). The program started from the sub‐
2020 process has to use this fd for reading data from socat (exam‐
2021 ple).
2022 fdout=<fdnum>
2024 Assigns the sub processes output channel to its file descriptor
2025 <fdnum> instead of stdout (1). The program started from the sub‐
2026 process has to use this fd for writing data to socat (example).
2027 sighup, sigint, sigquit
2029 Has socat pass signals of this type to the sub process. If no
2030 address has this option, socat terminates on these signals.
2031 TERMIOS option group
2034 For addresses that work on a tty (e.g., stdio, file:/dev/tty,
2036 exec:...,pty), the terminal parameters defined in the UN*X termios
2037 mechanism are made available as address option parameters. Please note
2038 that changes of the parameters of your interactive terminal remain
2039 effective after socat's termination, so you might have to enter "reset"
2040 or "stty sane" in your shell afterwards. For EXEC and SYSTEM addresses
2041 with option PTY, these options apply to the pty by the child processes.
2042 b0 Disconnects the terminal.
2044 b19200 Sets the serial line speed to 19200 baud. Some other rates are
2046 possible; use something like socat -hh |grep ' b[1-9]' to find
2047 all speeds supported by your implementation.
2048 Note: On some operating systems, these options may not be avail‐
2049 able. Use ispeed or ospeed instead.
2050 echo=<bool>
2052 Enables or disables local echo (example).
2053 icanon=<bool>
2055 Sets or clears canonical mode, enabling line buffering and some
2056 special characters.
2057 raw Sets raw mode, thus passing input and output almost unprocessed
2059 (example).
2060 ignbrk=<bool>
2062 Ignores or interpretes the BREAK character (e.g., ^C)
2063 brkint=<bool>
2065 bs0
2067 bs1
2069 bsdly=<0|1>
2071 clocal=<bool>
2073 cr0
2076 cr1
2077 cr2
2078 cr3
2079 Sets the carriage return delay to 0, 1, 2, or 3, respectively.
2081 0 means no delay, the other values are terminal dependent.
2082 crdly=<0|1|2|3>
2084 cread=<bool>
2086 crtscts=<bool>
2088 cs5
2091 cs6
2092 cs7
2093 cs8
2094 Sets the character size to 5, 6, 7, or 8 bits, respectively.
2096 csize=<0|1|2|3>
2098 cstopb=<bool>
2100 Sets two stop bits, rather than one.
2101 dsusp=<byte>
2103 Sets the value for the VDSUSP character that suspends the cur‐
2104 rent foreground process and reactivates the shell (all except
2105 Linux).
2106 echoctl=<bool>
2108 Echos control characters in hat notation (e.g. ^A)
2109 echoe=<bool>
2111 echok=<bool>
2113 echoke=<bool>
2115 echonl=<bool>
2117 echoprt=<bool>
2119 eof=<byte>
2121 eol=<byte>
2123 eol2=<byte>
2125 erase=<byte>
2127 discard=<byte>
2129 ff0
2131 ff1
2133 ffdly=<bool>
2135 flusho=<bool>
2137 hupcl=<bool>
2139 icrnl=<bool>
2141 iexten=<bool>
2143 igncr=<bool>
2145 ignpar=<bool>
2147 imaxbel=<bool>
2149 inlcr=<bool>
2151 inpck=<bool>
2153 intr=<byte>
2155 isig=<bool>
2157 ispeed=<unsigned-int>
2159 Set the baud rate for incoming data on this line.
2160 See also: ospeed, b19200
2161 istrip=<bool>
2163 iuclc=<bool>
2165 ixany=<bool>
2167 ixoff=<bool>
2169 ixon=<bool>
2171 kill=<byte>
2173 lnext=<byte>
2175 min=<byte>
2177 nl0 Sets the newline delay to 0.
2179 nl1
2181 nldly=<bool>
2183 noflsh=<bool>
2185 ocrnl=<bool>
2187 ofdel=<bool>
2189 ofill=<bool>
2191 olcuc=<bool>
2193 onlcr=<bool>
2195 onlret=<bool>
2197 onocr=<bool>
2199 opost=<bool>
2201 Enables or disables output processing; e.g., converts NL to CR-
2202 NL.
2203 ospeed=<unsigned-int>
2205 Set the baud rate for outgoing data on this line.
2206 See also: ispeed, b19200
2207 parenb=<bool>
2209 Enable parity generation on output and parity checking for
2210 input.
2211 parmrk=<bool>
2213 parodd=<bool>
2215 pendin=<bool>
2217 quit=<byte>
2219 reprint=<byte>
2221 sane Brings the terminal to something like a useful default state.
2223 start=<byte>
2225 stop=<byte>
2227 susp=<byte>
2229 swtc=<byte>
2231 tab0
2233 tab1
2235 tab2
2237 tab3
2239 tabdly=<unsigned-int>
2241 time=<byte>
2243 tostop=<bool>
2245 vt0
2247 vt1
2249 vtdly=<bool>
2251 werase=<byte>
2253 xcase=<bool>
2255 xtabs
2257 i-pop-all
2259 With UNIX System V STREAMS, removes all drivers from the stack.
2260 i-push=<string>
2262 With UNIX System V STREAMS, pushes the driver (module) with the
2263 given name (string) onto the stack. For example, to make sure
2264 that a character device on Solaris supports termios etc, use the
2265 following options: i-pop-all,i-push=ptem,i-push=ldterm,i-
2266 push=ttcompat
2267 PTY option group
2270 These options are intended for use with the pty address type.
2272 link=<filename>
2274 Generates a symbolic link that points to the actual pseudo ter‐
2275 minal (pty). This might help to solve the problem that ptys are
2276 generated with more or less unpredictable names, making it dif‐
2277 ficult to directly access the socat generated pty automatically.
2278 With this option, the user can specify a "fix" point in the file
2279 hierarchy that helps him to access the actual pty (example).
2280 Beginning with socat version 1.4.3, the symbolic link is removed
2281 when the address is closed (but see option unlink-close).
2282 wait-slave
2284 Blocks the open phase until a process opens the slave side of
2285 the pty. Usually, socat continues after generating the pty with
2286 opening the next address or with entering the transfer loop.
2287 With the wait-slave option, socat waits until some process opens
2288 the slave side of the pty before continuing. This option only
2289 works if the operating system provides the poll() system call.
2290 And it depends on an undocumented behaviour of pty's, so it does
2291 not work on all operating systems. It has successfully been
2292 tested on Linux, FreeBSD, NetBSD, and on Tru64 with openpty.
2293 pty-interval=<seconds>
2295 When the wait-slave option is set, socat periodically checks the
2296 HUP condition using poll() to find if the pty's slave side has
2297 been opened. The default polling interval is 1s. Use the pty-
2298 interval option [timeval] to change this value.
2299 OPENSSL option group
2302 These options apply to the openssl and openssl-listen address types.
2304 cipher=<cipherlist>
2306 Selects the list of ciphers that may be used for the connection.
2307 See the man page of ciphers , section CIPHER LIST FORMAT, for
2308 detailed information about syntax, values, and default of
2309 <cipherlist>.
2310 Several cipher strings may be given, separated by ':'. Some
2311 simple cipher strings:
2312 3DES Uses a cipher suite with triple DES.
2314 MD5 Uses a cipher suite with MD5.
2316 aNULL Uses a cipher suite without authentication.
2318 NULL Does not use encryption.
2320 HIGH Uses a cipher suite with "high" encryption. Note that the peer
2322 must support the selected property, or the negotiation will
2323 fail.
2324 method=<ssl-method>
2326 Sets the protocol version to be used. Valid strings (not case
2327 sensitive) are:
2328 SSLv2 Select SSL protocol version 2.
2330 SSLv3 Select SSL protocol version 3.
2332 SSLv23 Select SSL protocol version 2 or 3. This is the default when
2334 this option is not provided.
2335 TLSv1 Select TLS protocol version 1.
2337 verify=<bool>
2339 Controls check of the peer's certificate. Default is 1 (true).
2340 Disabling verify might open your socket for everyone, making the
2341 encryption useless!
2342 cert=<filename>
2344 Specifies the file with the certificate and private key for
2345 authentication. The certificate must be in OpenSSL format
2346 (*.pem). With openssl-listen, use of this option is strongly
2347 recommended. Except with cipher aNULL, "no shared ciphers" error
2348 will occur when no certificate is given.
2349 key=<filename>
2351 Specifies the file with the private key. The private key may be
2352 in this file or in the file given with the cert option. The
2353 party that has to proof that it is the owner of a certificate
2354 needs the private key.
2355 dhparams=<filename>
2357 Specifies the file with the Diffie Hellman parameters. These
2358 parameters may also be in the file given with the cert option in
2359 which case the dhparams option is not needed.
2360 cafile=<filename>
2362 Specifies the file with the trusted (root) authority certifi‐
2363 cates. The file must be in PEM format and should contain one or
2364 more certificates. The party that checks the authentication of
2365 its peer trusts only certificates that are in this file.
2366 capath=<dirname>
2368 Specifies the directory with the trusted (root) certificates.
2369 The directory must contain certificates in PEM format and their
2370 hashes (see OpenSSL documentation)
2371 egd=<filename>
2373 On some systems, openssl requires an explicit source of random
2374 data. Specify the socket name where an entropy gathering daemon
2375 like egd provides random data, e.g. /dev/egd-pool.
2376 pseudo On systems where openssl cannot find an entropy source and where
2378 no entropy gathering daemon can be utilized, this option acti‐
2379 vates a mechanism for providing pseudo entropy. This is
2380 archieved by taking the current time in microseconds for feeding
2381 the libc pseudo random number generator with an initial value.
2382 openssl is then feeded with output from random\() calls.
2383 NOTE:This mechanism is not sufficient for generation of secure
2384 keys!
2385 fips Enables FIPS mode if compiled in. For info about the FIPS
2387 encryption implementation standard see http://oss-insti‐
2388 tute.org/fips-faq.html. This mode might require that the
2389 involved certificates are generated with a FIPS enabled version
2390 of openssl. Setting or clearing this option on one socat address
2391 affects all OpenSSL addresses of this process.
2392 RETRY option group
2395 Options that control retry of some system calls, especially connection
2397 attempts.
2398 retry=<num>
2400 Number of retries before the connection or listen attempt is
2401 aborted. Default is 0, which means just one attempt.
2402 interval=<timespec>
2404 Time between consecutive attempts (seconds, [timespec]). Default
2405 is 1 second.
2406 forever
2408 Performs an unlimited number of retry attempts.
2409 TUN option group
2412 Options that control Linux TUN/TAP interface device addresses.
2414 tun-device=<device-file>
2416 Instructs socat to take another path for the TUN clone device.
2417 Default is /dev/net/tun.
2418 tun-name=<if-name>
2420 Gives the resulting network interface a specific name instead of
2421 the system generated (tun0, tun1, etc.)
2422 tun-type=[tun|tap]
2424 Sets the type of the TUN device; use this option to generate a
2425 TAP device. See the Linux docu for the difference between these
2426 types. When you try to establish a tunnel between two TUN
2427 devices, their types should be the same.
2428 iff-no-pi
2430 Sets the IFF_NO_PI flag which controls if the device includes
2431 additional packet information in the tunnel. When you try to
2432 establish a tunnel between two TUN devices, these flags should
2433 have the same values.
2434 iff-up Sets the TUN network interface status UP. Strongly recommended.
2436 iff-broadcast
2438 Sets the BROADCAST flag of the TUN network interface.
2439 iff-debug
2441 Sets the DEBUG flag of the TUN network interface.
2442 iff-loopback
2444 Sets the LOOPBACK flag of the TUN network interface.
2445 iff-pointopoint
2447 Sets the POINTOPOINT flag of the TUN device.
2448 iff-notrailers
2450 Sets the NOTRAILERS flag of the TUN device.
2451 iff-running
2453 Sets the RUNNING flag of the TUN device.
2454 iff-noarp
2456 Sets the NOARP flag of the TUN device.
2457 iff-promisc
2459 Sets the PROMISC flag of the TUN device.
2460 iff-allmulti
2462 Sets the ALLMULTI flag of the TUN device.
2463 iff-master
2465 Sets the MASTER flag of the TUN device.
2466 iff-slave
2468 Sets the SLAVE flag of the TUN device.
2469 iff-multicast
2471 Sets the MULTICAST flag of the TUN device.
2472 iff-portsel
2474 Sets the PORTSEL flag of the TUN device.
2475 iff-automedia
2477 Sets the AUTOMEDIA flag of the TUN device.
2478 iff-dynamic
2480 Sets the DYNAMIC flag of the TUN device.
2481
2484 This section explains the different data types that address parameters
2485 and address options can take.
2486 address-range
2488 Is currently only implemented for IPv4 and IPv6. See address-
2489 option `range'
2490 bool "0" or "1"; if value is omitted, "1" is taken.
2492 byte An unsigned int number, read with strtoul() , lower or equal to
2494 UCHAR_MAX .
2495 command-line
2497 A string specifying a program name and its arguments, separated
2498 by single spaces.
2499 data A raw data specification following dalan syntax. Currently the
2501 only valid form is a string starting with 'x' followed by an
2502 even number of hex digits, specifying a sequence of bytes.
2503 directory
2505 A string with usual UN*X directory name semantics.
2506 facility
2508 The name of a syslog facility in lower case characters.
2509 fdnum An unsigned int type, read with strtoul() , specifying a UN*X
2511 file descriptor.
2512 filename
2514 A string with usual UN*X filename semantics.
2515 group If the first character is a decimal digit, the value is read
2517 with strtoul() as unsigned integer specifying a group id. Other‐
2518 wise, it must be an existing group name.
2519 int A number following the rules of the strtol() function with base
2521 "0", i.e. decimal number, octal number with leading "0", or
2522 hexadecimal number with leading "0x". The value must fit into a
2523 C int.
2524 interface
2526 A string specifying the device name of a network interface as
2527 shown by ifconfig or procan, e.g. "eth0".
2528 IP address
2530 An IPv4 address in numbers-and-dots notation, an IPv6 address in
2531 hex notation enclosed in brackets, or a hostname that resolves
2532 to an IPv4 or an IPv6 address.
2533 Examples: 127.0.0.1, [::1], www.dest-unreach.org, dns1
2534 IPv4 address
2536 An IPv4 address in numbers-and-dots notation or a hostname that
2537 resolves to an IPv4 address.
2538 Examples: 127.0.0.1, www.dest-unreach.org, dns2
2539 IPv6 address
2541 An iPv6 address in hexnumbers-and-colons notation enclosed in
2542 brackets, or a hostname that resolves to an IPv6 address.
2543 Examples: [::1], [1234:5678:9abc:def0:1234:5678:9abc:def0],
2544 ip6name.domain.org
2545 long A number read with strtol() . The value must fit into a C long.
2547 long long
2549 A number read with strtoll() . The value must fit into a C long
2550 long.
2551 off_t An implementation dependend signed number, usually 32 bits, read
2553 with strtol or strtoll.
2554 off64_t
2556 An implementation dependend signed number, usually 64 bits, read
2557 with strtol or strtoll.
2558 mode_t An unsigned integer, read with strtoul() , specifying mode (per‐
2560 mission) bits.
2561 pid_t A number, read with strtol() , specifying a process id.
2563 port A uint16_t (16 bit unsigned number) specifying a TCP or UDP
2565 port, read with strtoul() .
2566 protocol
2568 An unsigned 8 bit number, read with strtoul() .
2569 size_t An unsigned number with size_t limitations, read with strtoul .
2571 sockname
2573 A socket address. See address-option `bind'
2574 string A sequence of characters, not containing '\0' and, depending on
2576 the position within the command line, ':', ',', or "!!". Note
2577 that you might have to escape shell meta characters in the com‐
2578 mand line.
2579 TCP service
2581 A service name, not starting with a digit, that is resolved by
2582 getservbyname() , or an unsigned int 16 bit number read with
2583 strtoul() .
2584 timeval
2586 A double float specifying seconds; the number is mapped into a
2587 struct timeval, consisting of seconds and microseconds.
2588 timespec
2590 A double float specifying seconds; the number is mapped into a
2591 struct timespec, consisting of seconds and nanoseconds.
2592 UDP service
2594 A service name, not starting with a digit, that is resolved by
2595 getservbyname() , or an unsigned int 16 bit number read with
2596 strtoul() .
2597 unsigned int
2599 A number read with strtoul() . The value must fit into a C
2600 unsigned int.
2601 user If the first character is a decimal digit, the value is read
2603 with strtoul() as unsigned integer specifying a user id. Other‐
2604 wise, it must be an existing user name.
2605
2608 socat - TCP4:www.domain.org:80
2609 transfers data between STDIO (-) and a TCP4 connection to port
2612 80 of host www.domain.org. This example results in an interac‐
2613 tive connection similar to telnet or netcat. The stdin terminal
2614 parameters are not changed, so you may close the relay with ^D
2615 or abort it with ^C.
2616 socat -d -d READLINE,history=$HOME/.http_history \
2618 TCP4:www.domain.org:www,crnl
2619 this is similar to the previous example, but you can edit the
2621 current line in a bash like manner (READLINE) and use the his‐
2622 tory file .http_history; socat prints messages about progress
2623 (-d -d). The port is specified by service name (www), and cor‐
2624 rect network line termination characters (crnl) instead of NL
2625 are used.
2626 socat TCP4-LISTEN:www TCP4:www.domain.org:www
2628 installs a simple TCP port forwarder. With TCP4-LISTEN it lis‐
2631 tens on local port "www" until a connection comes in, accepts
2632 it, then connects to the remote host (TCP4) and starts data
2633 transfer. It will not accept a econd connection.
2634 socat -d -d -lmlocal2 \
2636 TCP4-LISTEN:80,bind=myaddr1,reuseaddr,fork,su=nobody,range=10.0.0.0/8 \
2637 TCP4:www.domain.org:80,bind=myaddr2
2638 TCP port forwarder, each side bound to another local IP address
2640 (bind). This example handles an almost arbitrary number of par‐
2641 allel or consecutive connections by fork'ing a new process after
2642 each accept() . It provides a little security by su'ing to user
2643 nobody after forking; it only permits connections from the pri‐
2644 vate 10 network (range); due to reuseaddr, it allows immediate
2645 restart after master process's termination, even if some child
2646 sockets are not completely shut down. With -lmlocal2, socat
2647 logs to stderr until successfully reaching the accept loop. Fur‐
2648 ther logging is directed to syslog with facility local2.
2649 socat TCP4-LISTEN:5555,fork,tcpwrap=script \
2651 EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr
2652 a simple server that accepts connections (TCP4-LISTEN) and
2654 fork's a new child process for each connection; every child acts
2655 as single relay. The client must match the rules for daemon
2656 process name "script" in /etc/hosts.allow and /etc/hosts.deny,
2657 otherwise it is refused access (see "man 5 hosts_access"). For
2658 EXEC'uting the program, the child process chroot's to
2659 /home/sandbox, su's to user sandbox, and then starts the program
2660 /home/sandbox/bin/myscript. Socat and myscript communicate via a
2661 pseudo tty (pty); myscript's stderr is redirected to stdout, so
2662 its error messages are transferred via socat to the connected
2663 client.
2664 socat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \
2666 TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512
2667 mail.sh is a shell script, distributed with socat, that imple‐
2669 ments a simple SMTP client. It is programmed to "speak" SMTP on
2670 its FDs 3 (in) and 4 (out). The fdin and fdout options tell
2671 socat to use these FDs for communication with the program.
2672 Because mail.sh inherits stdin and stdout while socat does not
2673 use them, the script can read a mail body from stdin. Socat
2674 makes alias1 your local source address (bind), cares for correct
2675 network line termination (crnl) and sends at most 512 data bytes
2676 per packet (mss).
2677 socat -,raw,echo=0,escape=0x0f /dev/ttyS0,raw,echo=0,crnl
2679 opens an interactive connection via the serial line, e.g. for
2682 talking with a modem. raw and echo set the console's and ttyS0's
2683 terminal parameters to practicable values, crnl converts to cor‐
2684 rect newline characters. escape allows to terminate the socat
2685 process with character control-O. Consider using READLINE
2686 instead of the first address.
2687 socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
2689 SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20
2690 with UNIX-LISTEN, socat opens a listening UNIX domain socket
2692 /tmp/.X11-unix/X1. This path corresponds to local XWindow dis‐
2693 play :1 on your machine, so XWindow client connections to DIS‐
2694 PLAY=:1 are accepted. Socat then speaks with the SOCKS4 server
2695 host.victim.org that might permit sourceport 20 based connec‐
2696 tions due to an FTP related weakness in its static IP filters.
2697 Socat pretends to be invoked by socksuser nobody, and requests
2698 to be connected to loopback port 6000 (only weak sockd configu‐
2699 rations will allow this). So we get a connection to the victims
2700 XWindow server and, if it does not require MIT cookies or Ker‐
2701 beros authentication, we can start work. Please note that there
2702 can only be one connection at a time, because TCP can establish
2703 only one session with a given set of addresses and ports.
2704 socat -u /tmp/readdata,seek-end=0,ignoreeof -
2706 this is an example for unidirectional data transfer (-u). Socat
2709 transfers data from file /tmp/readdata (implicit address GOPEN),
2710 starting at its current end (seek-end=0 lets socat start reading
2711 at current end of file; use seek=0 or no seek option to first
2712 read the existing data) in a "tail -f" like mode (ignoreeof).
2713 The "file" might also be a listening UNIX domain socket (do not
2714 use a seek option then).
2715 (sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |
2717 socat - EXEC:'ssh -l user server',pty,setsid,ctty
2718 EXEC'utes an ssh session to server. Uses a pty for communication
2720 between socat and ssh, makes it ssh's controlling tty (ctty),
2721 and makes this pty the owner of a new process group (setsid), so
2722 ssh accepts the password from socat.
2723 socat -u TCP4-LISTEN:3334,reuseaddr,fork \
2725 OPEN:/tmp/in.log,creat,append
2726 implements a simple network based message collector. For each
2728 client connecting to port 3334, a new child process is generated
2729 (option fork). All data sent by the clients are append'ed to
2730 the file /tmp/in.log. If the file does not exist, socat creat's
2731 it. Option reuseaddr allows immediate restart of the server
2732 process.
2733 socat READLINE,noecho='[Pp]assword:' EXEC:'ftp ftp.server.com',pty,set‐
2735 sid,ctty
2736 wraps a command line history (READLINE) around the EXEC'uted ftp
2739 client utility. This allows editing and reuse of FTP commands
2740 for relatively comfortable browsing through the ftp directory
2741 hierarchy. The password is echoed! pty is required to have ftp
2742 issue a prompt. Nevertheless, there may occur some confusion
2743 with the password and FTP prompts.
2744 (socat PTY,link=$HOME/dev/vmodem0,raw,echo=0,wait-slave
2746 EXEC:'"ssh modemserver.us.org socat - /dev/ttyS0,non‐
2747 block,raw,echo=0"')
2748 generates a pseudo terminal device (PTY) on the client that can
2750 be reached under the symbolic link $HOME/dev/vmodem0. An appli‐
2751 cation that expects a serial line or modem can be configured to
2752 use $HOME/dev/vmodem0; its traffic will be directed to a modem‐
2753 server via ssh where another socat instance links it with
2754 /dev/ttyS0.
2755 socat TCP4-LISTEN:2022,reuseaddr,fork \
2757 PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass
2758 starts a forwarder that accepts connections on port 2022, and
2760 directs them through the proxy daemon listening on port 3128
2761 (proxyport) on host proxy, using the CONNECT method, where they
2762 are authenticated as "user" with "pass" (proxyauth). The proxy
2763 should establish connections to host www.domain.org on port 22
2764 then.
2765 socat - SSL:server:4443,cafile=server.crt,cert=client.pem
2767 is an OpenSSL client that tries to establish a secure connection
2770 to an SSL server. Option cafile specifies a file that contains
2771 trust certificates: we trust the server only when it presents
2772 one of these certificates and proofs that it owns the related
2773 private key. Otherwise the connection is terminated. With cert
2774 a file containing the client certificate and the associated pri‐
2775 vate key is specified. This is required in case the server
2776 wishes a client authentication; many Internet servers do not.
2777 The first address ('-') can be replaced by almost any other
2778 socat address.
2779 socat SSL-LISTEN:4443,reuse‐
2781 addr,pf=ip4,fork,cert=server.pem,cafile=client.crt PIPE
2782 is an OpenSSL server that accepts TCP connections, presents the
2785 certificate from the file server.pem and forces the client to
2786 present a certificate that is verified against cafile.crt.
2787 The second address ('PIPE') can be replaced by almost any other
2788 socat address.
2789 For instructions on generating and distributing OpenSSL keys and
2790 certificates see the additional socat docu socat-openssl.txt.
2791 echo |socat -u - file:/tmp/bigfile,create,largefile,seek=100000000000
2793 creates a 100GB sparse file; this requires a file system type
2796 that supports this (ext2, ext3, reiserfs, jfs; not minix, vfat).
2797 The operation of writing 1 byte might take long (reiserfs: some
2798 minutes; ext2: "no" time), and the resulting file can consume
2799 some disk space with just its inodes (reiserfs: 2MB; ext2:
2800 16KB).
2801 socat tcp-l:7777,reuseaddr,fork system:'filan -i 0 -s >&2',nofork
2803 listens for incoming TCP connections on port 7777. For each
2806 accepted connection, invokes a shell. This shell has its stdin
2807 and stdout directly connected to the TCP socket (nofork). The
2808 shell starts filan and lets it print the socket addresses to
2809 stderr (your terminal window).
2810 echo -e
2812 functions as primitive binary editor: it writes the 4 bytes 000
2815 014 000 000 to the executable /usr/bin/squid at offset
2816 0x00074420 (this is a real world patch to make the squid exe‐
2817 cutable from Cygwin run under Windows, actual per May 2004).
2818 socat - tcp:www.blackhat.org:31337,readbytes=1000
2820 connects to an unknown service and prevents being flooded.
2823 socat -U TCP:target:9999,end-close TCP-L:8888,reuseaddr,fork
2825 merges data arriving from different TCP streams on port 8888 to
2828 just one stream to target:9999. The end-close option prevents
2829 the child processes forked off by the second address from termi‐
2830 nating the shared connection to 9999 (close\(2) just unlinks the
2831 inode which stays active as long as the parent process lives;
2832 shutdown\(2) would actively terminate the connection).
2833 socat - UDP4-DATAGRAM:192.168.1.0:123,sp=123,broad‐
2835 cast,range=192.168.1.0/24
2836 sends a broadcast to the network 192.168.1.0/24 and receives the
2839 replies of the timeservers there. Ignores NTP packets from hosts
2840 outside this network.
2841 socat - SOCKET-DATA‐
2843 GRAM:2:2:17:x007bxc0a80100x0000000000000000,bind=x007bx00000000x0000000000000000,set‐
2844 sockopt-
2845 int=1:6:1,range=x0000xc0a80100x0000000000000000:x0000xffffff00x0000000000000000
2846 is semantically equivalent to the previous example, but all
2849 parameters are specified in generic form. the value 6 of set‐
2850 sockopt-int is the Linux value for SO_BROADCAST.
2851 socat - IP4-DATAGRAM:255.255.255.255:44,broadcast,range=10.0.0.0/8
2853 sends a broadcast to the local network\(s) using protocol 44.
2856 Accepts replies from the private address range only.
2857 socat - UDP4-DATAGRAM:224.255.0.1:6666,bind=:6666,ip-add-member‐
2859 ship=224.255.0.1:eth0
2860 transfers data from stdin to the specified multicast address
2863 using UDP. Both local and remote ports are 6666. Tells the
2864 interface eth0 to also accept multicast packets of the given
2865 group. Multiple hosts on the local network can run this command,
2866 so all data sent by any of the hosts will be received by all the
2867 other ones. Note that there are many possible reasons for fail‐
2868 ure, including IP-filters, routing issues, wrong interface
2869 selection by the operating system, bridges, or a badly config‐
2870 ured switch.
2871 socat TCP:host2:4443 TUN:192.168.255.1/24,up
2873 establishes one side of a virtual (but not private!) network
2876 with host2 where a similar process might run, with TCP-L and tun
2877 address 192.168.255.2. They can reach each other using the
2878 addresses 192.168.255.1 and 192.168.255.2. Substitute the TCP
2879 link with an SSL connection protected by client and server
2880 authentication (see OpenSSL client and server).
2881 socat PTY,link=/var/run/ppp,raw,echo=0 INTERFACE:hdlc0
2883 circumvents the problem that pppd requires a serial device and
2886 thus might not be able to work on a synchronous line that is
2887 represented by a network device. socat creates a PTY to make
2888 pppd happy, binds to the network interface hdlc0, and can trans‐
2889 fer data between both devices. Use pppd on device /var/run/ppp
2890 then.
2891 socat -T 1 -d -d TCP-L:10081,reuseaddr,fork,crlf SYSTEM:
2893 creates a simple HTTP echo server: each HTTP client that con‐
2896 nects gets a valid HTTP reply that contains information about
2897 the client address and port as it is seen by the server host,
2898 the host address (which might vary on multihomed servers), and
2899 the original client request.
2900 socat -d -d UDP4-RECVFROM:9999,so-broadcast,so-timestamp,ip-pktinfo,ip-
2902 recverr,ip-recvopts,ip-recvtos,ip-recvttl!!- SYSTEM:'export; sleep 1'
2903 |grep SOCAT
2904 waits for an incoming UDP packet on port 9999 and prints the
2907 environment variables provided by socat. On BSD based systems
2908 you have to replace ip-pktinfo with ip-recvdstaddr,ip-recvif.
2909 Especially interesting is SOCAT_IP_DSTADDR: it contains the tar‐
2910 get address of the packet which may be a unicast, multicast, or
2911 broadcast address.
2912
2917 Socat uses a logging mechanism that allows to filter messages by sever‐
2918 ity. The severities provided are more or less compatible to the appro‐
2919 priate syslog priority. With one or up to four occurrences of the -d
2920 command line option, the lowest priority of messages that are issued
2921 can be selected. Each message contains a single uppercase character
2922 specifying the messages severity (one of F, E, W, N, I, or D)
2923 FATAL: Conditions that require unconditional and immediate program ter‐
2925 mination.
2926 ERROR: Conditions that prevent proper program processing. Usually the
2928 program is terminated (see option -s).
2929 WARNING:
2931 Something did not function correctly or is in a state where cor‐
2932 rect further processing cannot be guaranteed, but might be pos‐
2933 sible.
2934 NOTICE:
2936 Interesting actions of the program, e.g. for supervising socat
2937 in some kind of server mode.
2938 INFO: Description of what the program does, and maybe why it happens.
2940 Allows to monitor the lifecycles of file descriptors.
2941 DEBUG: Description of how the program works, all system or library
2943 calls and their results.
2944 Log messages can be written to stderr, to a file, or to syslog.
2947 On exit, socat gives status 0 if it terminated due to EOF or inactivity
2949 timeout, with a positive value on error, and with a negative value on
2950 fatal error.
2951
2953 /usr/bin/socat
2954 /usr/bin/filan
2955 /usr/bin/procan
2956
2958 Input variables carry information from the environment to socat, output
2959 variables are set by socat for use in executed scripts and programs.
2960 In the output variables beginning with "SOCAT" this prefix is actually
2962 replaced by the upper case name of the executable or the value of
2963 option -lp.
2964 SOCAT_DEFAULT_LISTEN_IP (input)
2966 (Values 4 or 6) Sets the IP version to be used for listen, recv,
2967 and recvfrom addresses if no pf (protocol-family) option is
2968 given. Is overridden by socat options -4 or -6.
2969 SOCAT_PREFERRED_RESOLVE_IP (input)
2971 (Values 0, 4, or 6) Sets the IP version to be used when resolv‐
2972 ing target host names when version is not specified by address
2973 type, option pf (protocol-family), or address format. If name
2974 resolution does not return a matching entry, the first result
2975 (with differing IP version) is taken. With value 0, socat always
2976 selects the first record and its IP version.
2977 SOCAT_FORK_WAIT (input)
2979 Specifies the time (seconds) to sleep the parent and child pro‐
2980 cesses after successful fork\(). Useful for debugging.
2981 SOCAT_VERSION (output)
2983 Socat sets this variable to its version string, e.g. "1.7.0.0"
2984 for released versions or e.g. "1.6.0.1+envvar" for temporary
2985 versions; can be used in scripts invoked by socat.
2986 SOCAT_PID (output)
2988 Socat sets this variable to its process id. In case of fork
2989 address option, SOCAT_PID gets the child processes id. Forking
2990 for exec and system does not change SOCAT_PID.
2991 SOCAT_PPID (output)
2993 Socat sets this variable to its process id. In case of fork,
2994 SOCAT_PPID keeps the pid of the master process.
2995 SOCAT_PEERADDR (output)
2997 With passive socket addresses (all LISTEN and RECVFROM
2998 addresses), this variable is set to a string describing the
2999 peers socket address. Port information is not included.
3000 SOCAT_PEERPORT (output)
3002 With appropriate passive socket addresses (TCP, UDP, and SCTP -
3003 LISTEN and RECVFROM), this variable is set to a string contain‐
3004 ing the number of the peer port.
3005 SOCAT_SOCKADDR (output)
3007 With all LISTEN addresses, this variable is set to a string
3008 describing the local socket address. Port information is not
3009 included example
3010 SOCAT_SOCKPORT (output)
3012 With TCP-LISTEN, UDP-LISTEN, and SCTP-LISTEN addresses, this
3013 variable is set to the local port.
3014 SOCAT_TIMESTAMP (output)
3016 With all RECVFROM addresses where address option so-timestamp is
3017 applied, socat sets this variable to the resulting timestamp.
3018 SOCAT_IP_OPTIONS (output)
3020 With all IPv4 based RECVFROM addresses where address option ip-
3021 recvopts is applied, socat fills this variable with the IP
3022 options of the received packet.
3023 SOCAT_IP_DSTADDR (output)
3025 With all IPv4 based RECVFROM addresses where address option ip-
3026 recvdstaddr (BSD) or ip-pktinfo (other platforms) is applied,
3027 socat sets this variable to the destination address of the
3028 received packet. This is particularly useful to identify broad‐
3029 cast and multicast addressed packets.
3030 SOCAT_IP_IF (output)
3032 With all IPv4 based RECVFROM addresses where address option ip-
3033 recvif (BSD) or ip-pktinfo (other platforms) is applied, socat
3034 sets this variable to the name of the interface where the packet
3035 was received.
3036 SOCAT_IP_LOCADDR (output)
3038 With all IPv4 based RECVFROM addresses where address option ip-
3039 pktinfo is applied, socat sets this variable to the address of
3040 the interface where the packet was received.
3041 SOCAT_IP_TOS (output)
3043 With all IPv4 based RECVFROM addresses where address option ip-
3044 recvtos is applied, socat sets this variable to the TOS (type of
3045 service) of the received packet.
3046 SOCAT_IP_TTL (output)
3048 With all IPv4 based RECVFROM addresses where address option ip-
3049 recvttl is applied, socat sets this variable to the TTL (time to
3050 live) of the received packet.
3051 SOCAT_IPV6_HOPLIMIT (output)
3053 With all IPv6 based RECVFROM addresses where address option
3054 ipv6-recvhoplimit is applied, socat sets this variable to the
3055 hoplimit value of the received packet.
3056 SOCAT_IPV6_DSTADDR (output)
3058 With all IPv6 based RECVFROM addresses where address option
3059 ipv6-recvpktinfo is applied, socat sets this variable to the
3060 destination address of the received packet.
3061 SOCAT_IPV6_TCLASS (output)
3063 With all IPv6 based RECVFROM addresses where address option
3064 ipv6-recvtclass is applied, socat sets this variable to the
3065 transfer class of the received packet.
3066 HOSTNAME (input)
3068 Is used to determine the hostname for logging (see -lh).
3069 LOGNAME (input)
3071 Is used as name for the socks client user name if no socksuser
3072 is given.
3073 With options su and su-d, LOGNAME is set to the given user name.
3074 USER (input)
3076 Is used as name for the socks client user name if no socksuser
3077 is given and LOGNAME is empty.
3078 With options su and su-d, USER is set to the given user name.
3079 SHELL (output)
3081 With options su and su-d, SHELL is set to the login shell of the
3082 given user.
3083 PATH (output)
3085 Can be set with option path for exec and system addresses.
3086 HOME (output)
3088 With options su and su-d, HOME is set to the home directory of
3089 the given user.
3090
3092 The work of the following groups and organizations was invaluable for
3093 this project:
3094 The FSF (GNU, http://www.fsf.org/ project with their free and portable
3096 development software and lots of other useful tools and libraries.
3097 The Linux developers community (http://www.linux.org/) for providing a
3099 free, open source operating system.
3100 The Open Group (http://www.unix-systems.org/) for making their standard
3102 specifications available on the Internet for free.
3103
3105 This man page describes version 1.7.1 of socat.
3106
3108 Addresses cannot be nested, so a single socat process cannot, e.g.,
3109 drive ssl over socks.
3110 Address option ftruncate without value uses default 1 instead of 0.
3112 Verbose modes (-x and/or -v) display line termination characters incon‐
3114 sistently when address options cr or crnl are used: They show the data
3115 after conversion in either direction.
3116 The data transfer blocksize setting (-b) is ignored with address read‐
3118 line.
3119 Send bug reports to <socat@dest-unreach.org>
3121
3123 nc\(1), netcat6\(1), sock\(1), rinetd\(8), cage\(1), socks.conf\(5),
3124 openssl\(1), stunnel\(8), pty\(1), rlwrap\(1), setsid\(1)
3125 Socat home page http://www.dest-unreach.org/socat/
3127
3129 Gerhard Rieger <rieger@dest-unreach.org>
3130 Jan 2010 socat(1)