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 op‐
20 tions may be applied to the streams, socat can be used for many differ‐
21 ent purposes.
22 Filan is a utility that prints information about its active file de‐
24 scriptors to stdout. It has been written for debugging socat, but might
25 be useful for other purposes too. Use the -h option to find more infos.
26 Procan is a utility that prints information about process parameters to
28 stdout. It has been written to better understand some UNIX process
29 properties and for debugging socat, but might be useful for other pur‐
30 poses too.
31 The life cycle of a socat instance typically consists of four phases.
33 In the init phase, the command line options are parsed and logging is
35 initialized.
36 During the open phase, socat opens the first address and afterwards the
38 second address. These steps are usually blocking; thus, especially for
39 complex address types like socks, connection requests or authentication
40 dialogs must be completed before the next step is started.
41 In the transfer phase, socat watches both streams’ read and write file
43 descriptors via select() , and, when data is available on one side and
44 can be written to the other side, socat reads it, performs newline
45 character conversions if required, and writes the data to the write
46 file descriptor of the other stream, then continues waiting for more
47 data in both directions.
48 When one of the streams effectively reaches EOF, the closing phase be‐
50 gins. Socat transfers the EOF condition to the other stream, i.e. tries
51 to shutdown only its write stream, giving it a chance to terminate
52 gracefully. For a defined time socat continues to transfer data in the
53 other direction, but then closes all remaining channels and terminates.
54
56 Socat provides some command line options that modify the behaviour of
57 the program. They have nothing to do with so called address options
58 that are used as parts of address specifications.
59 -V Print version and available feature information to stdout, and
61 exit.
62 -h | -?
64 Print a help text to stdout describing command line options and
65 available address types, and exit.
66 -hh | -??
68 Like -h, plus a list of the short names of all available address
69 options. Some options are platform dependend, so this output is
70 helpful for checking the particular implementation.
71 -hhh | -???
73 Like -hh, plus a list of all available address option names.
74 -d Without this option, only fatal and error messages are gener‐
76 ated; applying this option also prints warning messages. See DI‐
77 AGNOSTICS for more information.
78 -d -d Prints fatal, error, warning, and notice messages.
80 -d -d -d
82 Prints fatal, error, warning, notice, and info messages.
83 -d -d -d -d
85 Prints fatal, error, warning, notice, info, and debug messages.
86 -D Logs information about file descriptors before starting the
88 transfer phase.
89 -ly[<facility>]
91 Writes messages to syslog instead of stderr; severity as defined
92 with -d option. With optional <facility>, the syslog type can be
93 selected, default is "daemon". Third party libraries might not
94 obey this option.
95 -lf <logfile>
97 Writes messages to <logfile> [filename] instead of stderr. Some
98 third party libraries, in particular libwrap, might not obey
99 this option.
100 -ls Writes messages to stderr (this is the default). Some third
102 party libraries might not obey this option, in particular lib‐
103 wrap appears to only log to syslog.
104 -lp<progname>
106 Overrides the program name printed in error messages and used
107 for constructing environment variable names.
108 -lu Extends the timestamp of error messages to microsecond resolu‐
110 tion. Does not work when logging to syslog.
111 -lm[<facility>]
113 Mixed log mode. During startup messages are printed to stderr;
114 when socat starts the transfer phase loop or daemon mode (i.e.
115 after opening all streams and before starting data transfer, or,
116 with listening sockets with fork option, before the first accept
117 call), it switches logging to syslog. With optional <facility>,
118 the syslog type can be selected, default is "daemon".
119 -lh Adds hostname to log messages. Uses the value from environment
121 variable HOSTNAME or the value retrieved with uname() if HOST‐
122 NAME is not set.
123 -v Writes the transferred data not only to their target streams,
125 but also to stderr. The output format is text with some conver‐
126 sions for readability, and prefixed with "> " or "< " indicating
127 flow directions.
128 -x Writes the transferred data not only to their target streams,
130 but also to stderr. The output format is hexadecimal, prefixed
131 with "> " or "< " indicating flow directions. Can be combined
132 with -v .
133 -r <file>
135 Dumps the raw (binary) data flowing from left to right address
136 to the given file.
137 -R <file>
139 Dumps the raw (binary) data flowing from right to left address
140 to the given file.
141 -b<size>
143 Sets the data transfer block <size> [size_t]. At most <size>
144 bytes are transferred per step. Default is 8192 bytes.
145 -s By default, socat terminates when an error occurred to prevent
147 the process from running when some option could not be applied.
148 With this option, socat is sloppy with errors and tries to con‐
149 tinue. Even with this option, socat will exit on fatals, and
150 will abort connection attempts when security checks failed.
151 -t<timeout>
153 When one channel has reached EOF, the write part of the other
154 channel is shut down. Then, socat waits <timeout> [timeval] sec‐
155 onds before terminating. Default is 0.5 seconds. This timeout
156 only applies to addresses where write and read part can be
157 closed independently. When during the timeout interval the read
158 part gives EOF, socat terminates without awaiting the timeout.
159 -T<timeout>
161 Total inactivity timeout: when socat is already in the transfer
162 loop and nothing has happened for <timeout> [timeval] seconds
163 (no data arrived, no interrupt occurred...) then it terminates.
164 Useful with protocols like UDP that cannot transfer EOF.
165 -u Uses unidirectional mode. The first address is only used for
167 reading, and the second address is only used for writing (exam‐
168 ple).
169 -U Uses unidirectional mode in reverse direction. The first address
171 is only used for writing, and the second address is only used
172 for reading.
173 -g During address option parsing, don’t check if the option is con‐
175 sidered useful in the given address environment. Use it if you
176 want to force, e.g., appliance of a socket option to a serial
177 device.
178 -L<lockfile>
180 If lockfile exists, exits with error. If lockfile does not ex‐
181 ist, creates it and continues, unlinks lockfile on exit.
182 -W<lockfile>
184 If lockfile exists, waits until it disappears. When lockfile
185 does not exist, creates it and continues, unlinks lockfile on
186 exit.
187 -4 Use IP version 4 in case that the addresses do not implicitly or
189 explicitly specify a version; this is the default.
190 -6 Use IP version 6 in case that the addresses do not implicitly or
192 explicitly specify a version.
193
196 With the address command line arguments, the user gives socat instruc‐
197 tions and the necessary information for establishing the byte streams.
198 An address specification usually consists of an address type keyword,
200 zero or more required address parameters separated by ’:’ from the key‐
201 word and from each other, and zero or more address options separated by
202 ’,’.
203 The keyword specifies the address type (e.g., TCP4, OPEN, EXEC). For
205 some keywords there exist synonyms (’-’ for STDIO, TCP for TCP4). Key‐
206 words are case insensitive. For a few special address types, the key‐
207 word may be omitted: Address specifications starting with a number are
208 assumed to be FD (raw file descriptor) addresses; if a ’/’ is found be‐
209 fore the first ’:’ or ’,’, GOPEN (generic file open) is assumed.
210 The required number and type of address parameters depend on the ad‐
212 dress type. E.g., TCP4 requires a server specification (name or ad‐
213 dress), and a port specification (number or service name).
214 Zero or more address options may be given with each address. They in‐
216 fluence the address in some ways. Options consist of an option keyword
217 or an option keyword and a value, separated by ’=’. Option keywords are
218 case insensitive. For filtering the options that are useful with an
219 address type, each option is member of one option group. For each ad‐
220 dress type there is a set of option groups allowed. Only options be‐
221 longing to one of these address groups may be used (except with option
222 -g).
223 Address specifications following the above schema are also called sin‐
225 gle address specifications. Two single addresses can be combined with
226 "!!" to form a dual type address for one channel. Here, the first ad‐
227 dress is used by socat for reading data, and the second address for
228 writing data. There is no way to specify an option only once for being
229 applied to both single addresses.
230 Usually, addresses are opened in read/write mode. When an address is
232 part of a dual address specification, or when option -u or -U is used,
233 an address might be used only for reading or for writing. Considering
234 this is important with some address types.
235 With socat version 1.5.0 and higher, the lexical analysis tries to han‐
237 dle quotes and parenthesis meaningfully and allows escaping of special
238 characters. If one of the characters ( { [ ’ is found, the correspond‐
239 ing closing character - ) } ] ’ - is looked for; they may also be
240 nested. Within these constructs, socats special characters and strings
241 : , !! are not handled specially. All those characters and strings can
242 be escaped with \ or within ""
243
245 This section describes the available address types with their keywords,
246 parameters, and semantics.
247 CREATE:<filename>
249 Opens <filename> with creat() and uses the file descriptor for
250 writing. This address type requires write-only context, because
251 a file opened with creat cannot be read from.
252 Flags like O_LARGEFILE cannot be applied. If you need them use
253 OPEN with options create,create.
254 <filename> must be a valid existing or not existing path. If
255 <filename> is a named pipe, creat() might block; if <filename>
256 refers to a socket, this is an error.
257 Option groups: FD,REG,NAMED
258 Useful options: mode, user, group, unlink-early, unlink-late,
259 append
260 See also: OPEN, GOPEN
261 EXEC:<command-line>
263 Forks a sub process that establishes communication with its par‐
264 ent process and invokes the specified program with execvp() .
265 <command-line> is a simple command with arguments separated by
266 single spaces. If the program name contains a ’/’, the part af‐
267 ter the last ’/’ is taken as ARGV[0]. If the program name is a
268 relative path, the execvp() semantics for finding the program
269 via $PATH apply. After successful program start, socat writes
270 data to stdin of the process and reads from its stdout using a
271 UNIX domain socket generated by socketpair() per default. (exam‐
272 ple)
273 Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
274 Useful options: path, fdin, fdout, chroot, su, su-d, nofork,
275 pty, stderr, ctty, setsid, pipes, login, sigint, sigquit
276 See also: SYSTEM
277 FD:<fdnum>
279 Uses the file descriptor <fdnum>. It must already exist as valid
280 UN*X file descriptor.
281 Option groups: FD (TERMIOS,REG,SOCKET)
282 See also: STDIO, STDIN, STDOUT, STDERR
283 GOPEN:<filename>
285 (Generic open) This address type tries to handle any file system
286 entry except directories usefully. <filename> may be a relative
287 or absolute path. If it already exists, its type is checked. In
288 case of a UNIX domain socket, socat connects; if connecting
289 fails, socat assumes a datagram socket and uses sendto() calls.
290 If the entry is not a socket, socat opens it applying the O_AP‐
291 PEND flag. If it does not exist, it is opened with flag O_CREAT
292 as a regular file (example).
293 Option groups: FD,REG,SOCKET,NAMED,OPEN
294 See also: OPEN, CREATE, UNIX-CONNECT
295 IP-SENDTO:<host>:<protocol>
297 Opens a raw IP socket. Depending on host specification or option
298 pf, IP protocol version 4 or 6 is used. It uses <protocol> to
299 send packets to <host> [IP address] and receives packets from
300 host, ignores packets from other hosts. Protocol 255 uses the
301 raw socket with the IP header being part of the data.
302 Option groups: FD,SOCKET,IP4,IP6
303 Useful options: pf, ttl
304 See also: IP4-SENDTO, IP6-SENDTO, IP-RECVFROM, IP-RECV,
305 UDP-SENDTO, UNIX-SENDTO
306 INTERFACE:<interface>
308 Communicates with a network connected on an interface using raw
309 packets including link level data. <interface> is the name of
310 the network interface. Currently only available on Linux. Op‐
311 tion groups: FD,SOCKET
312 Useful options: pf, type
313 See also: ip-recv
314 IP4-SENDTO:<host>:<protocol>
316 Like IP-SENDTO, but always uses IPv4.
317 Option groups: FD,SOCKET,IP4
318 IP6-SENDTO:<host>:<protocol>
320 Like IP-SENDTO, but always uses IPv6.
321 Option groups: FD,SOCKET,IP6
322 IP-DATAGRAM:<address>:<protocol>
325 Sends outgoing data to the specified address which may in par‐
326 ticular be a broadcast or multicast address. Packets arriving on
327 the local socket are checked if their source addresses match
328 RANGE or TCPWRAP options. This address type can for example be
329 used for implementing symmetric or asymmetric broadcast or mul‐
330 ticast communications.
331 Option groups: FD, SOCKET, IP4, IP6, RANGE
332 Useful options: bind, range, tcpwrap, broadcast, ip-multi‐
333 cast-loop, ip-multicast-ttl, ip-multicast-if, ip-add-membership,
334 ip-add-source-membership, ttl, tos, pf
335 See also: IP4-DATAGRAM, IP6-DATAGRAM, IP-SENDTO, IP-RECVFROM,
336 IP-RECV, UDP-DATAGRAM
337 IP4-DATAGRAM:<host>:<protocol>
339 Like IP-DATAGRAM, but always uses IPv4. (example)
340 Option groups: FD,SOCKET,IP4,RANGE
341 IP6-DATAGRAM:<host>:<protocol>
343 Like IP-DATAGRAM, but always uses IPv6. Please note that IPv6
344 does not know broadcasts.
345 Option groups: FD,SOCKET,IP6,RANGE
346 IP-RECVFROM:<protocol>
349 Opens a raw IP socket of <protocol>. Depending on option pf, IP
350 protocol version 4 or 6 is used. It receives one packet from an
351 unspecified peer and may send one or more answer packets to that
352 peer. This mode is particularly useful with fork option where
353 each arriving packet - from arbitrary peers - is handled by its
354 own sub process. This allows a behaviour similar to typical UDP
355 based servers like ntpd or named.
356 Please note that the reply packets might be fetched as incoming
357 traffic when sender and receiver IP address are identical be‐
358 cause there is no port number to distinguish the sockets.
359 This address works well with IP-SENDTO address peers (see
360 above). Protocol 255 uses the raw socket with the IP header be‐
361 ing part of the data.
362 See the note about RECVFROM addresses.
363 Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
364 Useful options: pf, fork, range, ttl, broadcast
365 See also: IP4-RECVFROM, IP6-RECVFROM, IP-SENDTO, IP-RECV,
366 UDP-RECVFROM, UNIX-RECVFROM
367 IP4-RECVFROM:<protocol>
369 Like IP-RECVFROM, but always uses IPv4.
370 Option groups: FD,SOCKET,IP4,CHILD,RANGE
371 IP6-RECVFROM:<protocol>
373 Like IP-RECVFROM, but always uses IPv6.
374 Option groups: FD,SOCKET,IP6,CHILD,RANGE
375 IP-RECV:<protocol>
378 Opens a raw IP socket of <protocol>. Depending on option pf, IP
379 protocol version 4 or 6 is used. It receives packets from multi‐
380 ple unspecified peers and merges the data. No replies are pos‐
381 sible. It can be, e.g., addressed by socat IP-SENDTO address
382 peers. Protocol 255 uses the raw socket with the IP header be‐
383 ing part of the data.
384 Option groups: FD,SOCKET,IP4,IP6,RANGE
385 Useful options: pf, range
386 See also: IP4-RECV, IP6-RECV, IP-SENDTO, IP-RECVFROM, UDP-RECV,
387 UNIX-RECV
388 IP4-RECV:<protocol>
390 Like IP-RECV, but always uses IPv4.
391 Option groups: FD,SOCKET,IP4,RANGE
392 IP6-RECV:<protocol>
394 Like IP-RECV, but always uses IPv6.
395 Option groups: FD,SOCKET,IP6,RANGE
396 OPEN:<filename>
399 Opens <filename> using the open() system call (example). This
400 operation fails on UNIX domain sockets.
401 Note: This address type is rarely useful in bidirectional mode.
402 Option groups: FD,REG,NAMED,OPEN
403 Useful options: creat, excl, noatime, nofollow, append, rdonly,
404 wronly, lock, readbytes, ignoreeof
405 See also: CREATE, GOPEN, UNIX-CONNECT
406 OPENSSL:<host>:<port>
408 Tries to establish a SSL connection to <port> [TCP service] on
409 <host> [IP address] using TCP/IP version 4 or 6 depending on ad‐
410 dress specification, name resolution, or option pf.
411 NOTE: Up to version 1.7.2.4 the server certificate was only
412 checked for validity against the system certificate store or
413 cafile or capath, but not for match with the server’s name or
414 its IP address. Since version 1.7.3.0 socat checks the peer
415 certificate for match with the <host> parameter or the value of
416 the openssl-commonname option. Socat tries to match it against
417 the certificates subject commonName, and the certificates exten‐
418 sion subjectAltName DNS names. Wildcards in the certificate are
419 supported.
420 Option groups: FD,SOCKET,IP4,IP6,TCP,OPENSSL,RETRY
421 Useful options: min-proto-version, cipher, verify, commonname,
422 cafile, capath, certificate, key, compress, bind, pf, con‐
423 nect-timeout, sourceport, retry
424 See also: OPENSSL-LISTEN, TCP
425 OPENSSL-LISTEN:<port>
427 Listens on tcp <port> [TCP service]. The IP version is 4 or the
428 one specified with pf. When a connection is accepted, this ad‐
429 dress behaves as SSL server.
430 Note: You probably want to use the certificate option with this
431 address.
432 NOTE: The client certificate is only checked for validity
433 against cafile or capath, but not for match with the client’s
434 name or its IP address!
435 Option groups: FD,SOCKET,IP4,IP6,TCP,LIS‐
436 TEN,OPENSSL,CHILD,RANGE,RETRY
437 Useful options: pf, min-proto-version, cipher, verify, common‐
438 name, cafile, capath, certificate, key, compress, fork, bind,
439 range, tcpwrap, su, reuseaddr, retry
440 See also: OPENSSL, TCP-LISTEN
441 OPENSSL-DTLS-CLIENT:<host>:<port>
443 Tries to establish a DTLS connection to <port> [UDP service] on
444 <host> [IP address] using UDP/IP version 4 or 6 depending on ad‐
445 dress specification, name resolution, or option pf.
446 Socat checks the peer certificates subjectAltName or commonName
447 against the addresses option openssl-commonname or the host
448 name. Wildcards in the certificate are supported.
449 Use socat option -b to make datagrams small enough to fit with
450 overhead on the network. Use option -T to prevent indefinite
451 hanging when peer went down quietly.
452 Option groups: FD,SOCKET,IP4,IP6,OPENSSL,RETRY
453 Useful options: min-proto-version, cipher, verify, commonname,
454 cafile, capath, certificate, key, compress, bind, pf, source‐
455 port, retry
456 See also: OPENSSL-DTLS-SERVER, OPENSSL-CONNECT, UDP-CONNECT
457 OPENSSL-DTLS-SERVER:<port>
459 Listens on UDP <port> [UDP service]. The IP version is 4 or the
460 one specified with pf. When a connection is accepted, this ad‐
461 dress behaves as DTLS server.
462 Note: You probably want to use the certificate option with this
463 address.
464 NOTE: The client certificate is only checked for validity
465 against cafile or capath, but not for match with the client’s
466 name or its IP address! Use socat option -b to make datagrams
467 small enough to fit with overhead on the network. Use option -T
468 to prevent indefinite hanging when peer went down quietly.
469 Option groups: FD,SOCKET,IP4,IP6,LIS‐
470 TEN,OPENSSL,CHILD,RANGE,RETRY
471 Useful options: pf, min-proto-version, cipher, verify, common‐
472 name, cafile, capath, certificate, key, compress, fork, bind,
473 range, tcpwrap, su, reuseaddr, retry
474 See also: OPENSSL-DTLS-CLIENT, OPENSSL-LISTEN, UDP-LISTEN
475 PIPE:<filename>
477 If <filename> already exists, it is opened. If it does not ex‐
478 ist, a named pipe is created and opened. Beginning with socat
479 version 1.4.3, the named pipe is removed when the address is
480 closed (but see option unlink-close
481 Note: When a pipe is used for both reading and writing, it works
482 as echo service.
483 Note: When a pipe is used for both reading and writing, and so‐
484 cat tries to write more bytes than the pipe can buffer (Linux
485 2.4: 2048 bytes), socat might block. Consider using socat op‐
486 tion, e.g., -b 2048
487 Option groups: FD,NAMED,OPEN
488 Useful options: rdonly, nonblock, group, user, mode, un‐
489 link-early
490 See also: unnamed pipe
491 PIPE Creates an unnamed pipe and uses it for reading and writing. It
493 works as an echo, because everything written to it appeares im‐
494 mediately as read data.
495 Note: When socat tries to write more bytes than the pipe can
496 queue (Linux 2.4: 2048 bytes), socat might block. Consider,
497 e.g., using option -b 2048
498 Option groups: FD
499 See also: named pipe
500 PROXY:<proxy>:<hostname>:<port>
502 Connects to an HTTP proxy server on port 8080 using TCP/IP ver‐
503 sion 4 or 6 depending on address specification, name resolution,
504 or option pf, and sends a CONNECT request for hostname:port. If
505 the proxy grants access and succeeds to connect to the target,
506 data transfer between socat and the target can start. Note that
507 the traffic need not be HTTP but can be an arbitrary protocol.
508 Option groups: FD,SOCKET,IP4,IP6,TCP,HTTP,RETRY
509 Useful options: proxyport, ignorecr, proxyauth, resolve, crnl,
510 bind, connect-timeout, mss, sourceport, retry
511 See also: SOCKS, TCP
512 PTY Generates a pseudo terminal (pty) and uses its master side. An‐
514 other process may open the pty’s slave side using it like a se‐
515 rial line or terminal. (example). If both the ptmx and the
516 openpty mechanisms are available, ptmx is used (POSIX).
517 Option groups: FD,NAMED,PTY,TERMIOS
518 Useful options: link, openpty, wait-slave, mode, user, group
519 See also: UNIX-LISTEN, PIPE, EXEC, SYSTEM
520 READLINE
522 Uses GNU readline and history on stdio to allow editing and
523 reusing input lines (example). This requires the GNU readline
524 and history libraries. Note that stdio should be a (pseudo) ter‐
525 minal device, otherwise readline does not seem to work.
526 Option groups: FD,READLINE,TERMIOS
527 Useful options: history, noecho
528 See also: STDIO
529 SCTP-CONNECT:<host>:<port>
531 Establishes an SCTP stream connection to the specified <host>
532 [IP address] and <port> [TCP service] using IP version 4 or 6
533 depending on address specification, name resolution, or option
534 pf.
535 Option groups: FD,SOCKET,IP4,IP6,SCTP,CHILD,RETRY
536 Useful options: bind, pf, connect-timeout, tos, mtudiscover,
537 sctp-maxseg, sctp-nodelay, nonblock, sourceport, retry, read‐
538 bytes
539 See also: SCTP4-CONNECT, SCTP6-CONNECT, SCTP-LISTEN, TCP-CONNECT
540 SCTP4-CONNECT:<host>:<port>
542 Like SCTP-CONNECT, but only supports IPv4 protocol.
543 Option groups: FD,SOCKET,IP4,SCTP,CHILD,RETRY
544 SCTP6-CONNECT:<host>:<port>
546 Like SCTP-CONNECT, but only supports IPv6 protocol.
547 Option groups: FD,SOCKET,IP6,SCTP,CHILD,RETRY
548 SCTP-LISTEN:<port>
550 Listens on <port> [TCP service] and accepts an SCTP connection.
551 The IP version is 4 or the one specified with address option pf,
552 socat option (-4, -6), or environment variable SOCAT_DE‐
553 FAULT_LISTEN_IP. Note that opening this address usually blocks
554 until a client connects.
555 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,SCTP,RETRY
556 Useful options: crnl, fork, bind, range, tcpwrap, pf, max-chil‐
557 dren, backlog, accept-timeout, sctp-maxseg, sctp-nodelay, su,
558 reuseaddr, retry, cool-write
559 See also: SCTP4-LISTEN, SCTP6-LISTEN, TCP-LISTEN, SCTP-CONNECT
560 SCTP4-LISTEN:<port>
562 Like SCTP-LISTEN, but only supports IPv4 protocol.
563 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,SCTP,RETRY
564 SCTP6-LISTEN:<port>
566 Like SCTP-LISTEN, but only supports IPv6 protocol.
567 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,SCTP,RETRY
568 SOCKET-CONNECT:<domain>:<protocol>:<remote-address>
570 Creates a stream socket using the first and second given socket
571 parameters and SOCK_STREAM (see man socket(2)) and connects to
572 the remote-address. The two socket parameters have to be speci‐
573 fied by int numbers. Consult your OS documentation and include
574 files to find the appropriate values. The remote-address must be
575 the data representation of a sockaddr structure without sa_fam‐
576 ily and (BSD) sa_len components.
577 Please note that you can - beyond the options of the specified
578 groups - also use options of higher level protocols when you ap‐
579 ply socat option -g.
580 Option groups: FD,SOCKET,CHILD,RETRY
581 Useful options: bind, setsockopt,
582 See also: TCP, UDP-CONNECT, UNIX-CONNECT, SOCKET-LISTEN,
583 SOCKET-SENDTO
584 SOCKET-DATAGRAM:<domain>:<type>:<protocol>:<remote-address>
586 Creates a datagram socket using the first three given socket pa‐
587 rameters (see man socket(2)) and sends outgoing data to the re‐
588 mote-address. The three socket parameters have to be specified
589 by int numbers. Consult your OS documentation and include files
590 to find the appropriate values. The remote-address must be the
591 data representation of a sockaddr structure without sa_family
592 and (BSD) sa_len components.
593 Please note that you can - beyond the options of the specified
594 groups - also use options of higher level protocols when you ap‐
595 ply socat option -g.
596 Option groups: FD,SOCKET,RANGE
597 Useful options: bind, range, setsockopt,
598 See also: UDP-DATAGRAM, IP-DATAGRAM, SOCKET-SENDTO, SOCKET-RECV,
599 SOCKET-RECVFROM
600 SOCKET-LISTEN:<domain>:<protocol>:<local-address>
602 Creates a stream socket using the first and second given socket
603 parameters and SOCK_STREAM (see man socket(2)) and waits for in‐
604 coming connections on local-address. The two socket parameters
605 have to be specified by int numbers. Consult your OS documenta‐
606 tion and include files to find the appropriate values. The lo‐
607 cal-address must be the data representation of a sockaddr struc‐
608 ture without sa_family and (BSD) sa_len components.
609 Please note that you can - beyond the options of the specified
610 groups - also use options of higher level protocols when you ap‐
611 ply socat option -g.
612 Option groups: FD,SOCKET,LISTEN,RANGE,CHILD,RETRY
613 Useful options: setsockopt, setsockopt-listen,
614 See also: TCP, UDP-CONNECT, UNIX-CONNECT, SOCKET-LISTEN,
615 SOCKET-SENDTO, SOCKET-SENDTO
616 SOCKET-RECV:<domain>:<type>:<protocol>:<local-address>
618 Creates a socket using the three given socket parameters (see
619 man socket(2)) and binds it to <local-address>. Receives arriv‐
620 ing data. The three parameters have to be specified by int num‐
621 bers. Consult your OS documentation and include files to find
622 the appropriate values. The local-address must be the data rep‐
623 resentation of a sockaddr structure without sa_family and (BSD)
624 sa_len components.
625 Option groups: FD,SOCKET,RANGE
626 Useful options: range, setsockopt, setsockopt-listen
627 See also: UDP-RECV, IP-RECV, UNIX-RECV, SOCKET-DATAGRAM,
628 SOCKET-SENDTO, SOCKET-RECVFROM
629 SOCKET-RECVFROM:<domain>:<type>:<protocol>:<local-address>
631 Creates a socket using the three given socket parameters (see
632 man socket(2)) and binds it to <local-address>. Receives arriv‐
633 ing data and sends replies back to the sender. The first three
634 parameters have to be specified as int numbers. Consult your OS
635 documentation and include files to find the appropriate values.
636 The local-address must be the data representation of a sockaddr
637 structure without sa_family and (BSD) sa_len components.
638 See the note about RECVFROM addresses.
639 Option groups: FD,SOCKET,CHILD,RANGE
640 Useful options: fork, range, setsockopt, setsockopt-listen
641 See also: UDP-RECVFROM, IP-RECVFROM, UNIX-RECVFROM, SOCKET-DATA‐
642 GRAM, SOCKET-SENDTO, SOCKET-RECV
643 SOCKET-SENDTO:<domain>:<type>:<protocol>:<remote-address>
645 Creates a socket using the three given socket parameters (see
646 man socket(2)). Sends outgoing data to the given address and re‐
647 ceives replies. The three parameters have to be specified as
648 int numbers. Consult your OS documentation and include files to
649 find the appropriate values. The remote-address must be the data
650 representation of a sockaddr structure without sa_family and
651 (BSD) sa_len components.
652 Option groups: FD,SOCKET
653 Useful options: bind, setsockopt, setsockopt-listen
654 See also: UDP-SENDTO, IP-SENDTO, UNIX-SENDTO, SOCKET-DATAGRAM,
655 SOCKET-RECV SOCKET-RECVFROM
656 SOCKS4:<socks-server>:<host>:<port>
658 Connects via <socks-server> [IP address] to <host> [IPv4 ad‐
659 dress] on <port> [TCP service], using socks version 4 protocol
660 over IP version 4 or 6 depending on address specification, name
661 resolution, or option pf (example).
662 Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
663 Useful options: socksuser, socksport, sourceport, pf, retry
664 See also: SOCKS4A, PROXY, TCP
665 SOCKS4A:<socks-server>:<host>:<port>
667 like SOCKS4, but uses socks protocol version 4a, thus leaving
668 host name resolution to the socks server.
669 Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
670 STDERR Uses file descriptor 2.
672 Option groups: FD (TERMIOS,REG,SOCKET)
673 See also: FD
674 STDIN Uses file descriptor 0.
676 Option groups: FD (TERMIOS,REG,SOCKET)
677 Useful options: readbytes
678 See also: FD
679 STDIO Uses file descriptor 0 for reading, and 1 for writing.
681 Option groups: FD (TERMIOS,REG,SOCKET)
682 Useful options: readbytes
683 See also: FD
684 STDOUT Uses file descriptor 1.
686 Option groups: FD (TERMIOS,REG,SOCKET)
687 See also: FD
688 SYSTEM:<shell-command>
690 Forks a sub process that establishes communication with its par‐
691 ent process and invokes the specified program with system() .
692 Please note that <shell-command> [string] must not contain ’,’
693 or "!!", and that shell meta characters may have to be pro‐
694 tected. After successful program start, socat writes data to
695 stdin of the process and reads from its stdout.
696 Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
697 Useful options: path, fdin, fdout, chroot, su, su-d, nofork,
698 pty, stderr, ctty, setsid, pipes, sigint, sigquit
699 See also: EXEC
700 TCP:<host>:<port>
702 Connects to <port> [TCP service] on <host> [IP address] using
703 TCP/IP version 4 or 6 depending on address specification, name
704 resolution, or option pf.
705 Option groups: FD,SOCKET,IP4,IP6,TCP,RETRY
706 Useful options: crnl, bind, pf, connect-timeout, tos, mtudis‐
707 cover, mss, nodelay, nonblock, sourceport, retry, readbytes
708 See also: TCP4, TCP6, TCP-LISTEN, UDP, SCTP-CONNECT, UNIX-CON‐
709 NECT
710 TCP4:<host>:<port>
712 Like TCP, but only supports IPv4 protocol (example).
713 Option groups: FD,SOCKET,IP4,TCP,RETRY
714 TCP6:<host>:<port>
716 Like TCP, but only supports IPv6 protocol.
717 Option groups: FD,SOCKET,IP6,TCP,RETRY
718 TCP-LISTEN:<port>
720 Listens on <port> [TCP service] and accepts a TCP/IP connection.
721 The IP version is 4 or the one specified with address option pf,
722 socat option (-4, -6), or environment variable SOCAT_DE‐
723 FAULT_LISTEN_IP. Note that opening this address usually blocks
724 until a client connects.
725 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,TCP,RETRY
726 Useful options: crnl, fork, bind, range, tcpwrap, pf, max-chil‐
727 dren, backlog, accept-timeout, mss, su, reuseaddr, retry,
728 cool-write
729 See also: TCP4-LISTEN, TCP6-LISTEN, UDP-LISTEN, SCTP-LISTEN,
730 UNIX-LISTEN, OPENSSL-LISTEN, TCP-CONNECT
731 TCP4-LISTEN:<port>
733 Like TCP-LISTEN, but only supports IPv4 protocol (example).
734 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,TCP,RETRY
735 TCP6-LISTEN:<port>
737 Like TCP-LISTEN, but only supports IPv6 protocol.
738 Additional useful option: ipv6only
739 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,TCP,RETRY
740 TUN[:<if-addr>/<bits>]
742 Creates a Linux TUN/TAP device and optionally assignes it the
743 address and netmask given by the parameters. The resulting net‐
744 work interface is almost ready for use by other processes; socat
745 serves its "wire side". This address requires read and write ac‐
746 cess to the tunnel cloning device, usually /dev/net/tun , as
747 well as permission to set some ioctl()s. Option iff-up is re‐
748 quired to immediately activate the interface!
749 Note: If you intend to transfer packets between two Socat "wire
750 sides" you need a protocol that keeps packet boundaries,
751 e.g.UDP; TCP might work with option nodelay.
752 Option groups: FD,NAMED,OPEN,TUN
753 Useful options: iff-up, tun-device, tun-name, tun-type,
754 iff-no-pi
755 See also: ip-recv
756 UDP:<host>:<port>
758 Connects to <port> [UDP service] on <host> [IP address] using
759 UDP/IP version 4 or 6 depending on address specification, name
760 resolution, or option pf.
761 Please note that, due to UDP protocol properties, no real con‐
762 nection is established; data has to be sent for `connecting’ to
763 the server, and no end-of-file condition can be transported.
764 Option groups: FD,SOCKET,IP4,IP6
765 Useful options: ttl, tos, bind, sourceport, pf
766 See also: UDP4, UDP6, UDP-LISTEN, TCP, IP
767 UDP4:<host>:<port>
769 Like UDP, but only supports IPv4 protocol.
770 Option groups: FD,SOCKET,IP4
771 UDP6:<host>:<port>
773 Like UDP, but only supports IPv6 protocol.
774 Option groups: FD,SOCKET,IP6
775 UDP-DATAGRAM:<address>:<port>
777 Sends outgoing data to the specified address which may in par‐
778 ticular be a broadcast or multicast address. Packets arriving on
779 the local socket are checked for the correct remote port only
780 when option sourceport is used (this is a change with Socat ver‐
781 sion 1.7.4.0) and if their source addresses match RANGE or TCP‐
782 WRAP options. This address type can for example be used for im‐
783 plementing symmetric or asymmetric broadcast or multicast commu‐
784 nications.
785 Option groups: FD,SOCKET,IP4,IP6,RANGE
786 Useful options: bind, range, tcpwrap, broadcast, ip-multi‐
787 cast-loop, ip-multicast-ttl, ip-multicast-if, ip-add-membership,
788 ip-add-source-membership, ttl, tos, sourceport, pf
789 See also: UDP4-DATAGRAM, UDP6-DATAGRAM, UDP-SENDTO,
790 UDP-RECVFROM, UDP-RECV, UDP-CONNECT, UDP-LISTEN, IP-DATAGRAM
791 UDP4-DATAGRAM:<address>:<port>
793 Like UDP-DATAGRAM, but only supports IPv4 protocol (example1,
794 example2).
795 Option groups: FD,SOCKET,IP4, RANGE
796 UDP6-DATAGRAM:<address>:<port>
798 Like UDP-DATAGRAM, but only supports IPv6 protocol.
799 Option groups: FD,SOCKET,IP6,RANGE
800 UDP-LISTEN:<port>
802 Waits for a UDP/IP packet arriving on <port> [UDP service] and
803 `connects’ back to sender. The accepted IP version is 4 or the
804 one specified with option pf. Please note that, due to UDP pro‐
805 tocol properties, no real connection is established; data has to
806 arrive from the peer first, and no end-of-file condition can be
807 transported. Note that opening this address usually blocks until
808 a client connects.
809 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6
810 Useful options: fork, bind, range, pf
811 See also: UDP, UDP4-LISTEN, UDP6-LISTEN, TCP-LISTEN
812 UDP4-LISTEN:<port>
814 Like UDP-LISTEN, but only support IPv4 protocol.
815 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4
816 UDP6-LISTEN:<port>
818 Like UDP-LISTEN, but only support IPv6 protocol.
819 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6
820 UDP-SENDTO:<host>:<port>
822 Communicates with the specified peer socket, defined by <port>
823 [UDP service] on <host> [IP address], using UDP/IP version 4 or
824 6 depending on address specification, name resolution, or option
825 pf. It sends packets to and receives packets from that peer
826 socket only. This address effectively implements a datagram
827 client. It works well with socat UDP-RECVFROM and UDP-RECV ad‐
828 dress peers.
829 Option groups: FD,SOCKET,IP4,IP6
830 Useful options: ttl, tos, bind, sourceport, pf
831 See also: UDP4-SENDTO, UDP6-SENDTO, UDP-RECVFROM, UDP-RECV,
832 UDP-CONNECT, UDP-LISTEN, IP-SENDTO
833 UDP4-SENDTO:<host>:<port>
835 Like UDP-SENDTO, but only supports IPv4 protocol.
836 Option groups: FD,SOCKET,IP4
837 UDP6-SENDTO:<host>:<port>
839 Like UDP-SENDTO, but only supports IPv6 protocol.
840 Option groups: FD,SOCKET,IP6
841 UDP-RECVFROM:<port>
843 Creates a UDP socket on <port> [UDP service] using UDP/IP ver‐
844 sion 4 or 6 depending on option pf. It receives one packet from
845 an unspecified peer and may send one or more answer packets to
846 that peer. This mode is particularly useful with fork option
847 where each arriving packet - from arbitrary peers - is handled
848 by its own sub process. This allows a behaviour similar to typi‐
849 cal UDP based servers like ntpd or named. This address works
850 well with socat UDP-SENDTO address peers.
851 Note: When the second address fails before entering the transfer
852 loop the packet is dropped. Use option retry or forever on the
853 second address to avoid data loss.
854 Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
855 Useful options: fork, ttl, tos, bind, sourceport, pf
856 See also: UDP4-RECVFROM, UDP6-RECVFROM, UDP-SENDTO, UDP-RECV,
857 UDP-CONNECT, UDP-LISTEN, IP-RECVFROM, UNIX-RECVFROM
858 UDP4-RECVFROM:<port>
860 Like UDP-RECVFROM, but only supports IPv4 protocol.
861 Option groups: FD,SOCKET,IP4,CHILD,RANGE
862 UDP6-RECVFROM:<port>
864 Like UDP-RECVFROM, but only supports IPv6 protocol.
865 Option groups: FD,SOCKET,IP6,CHILD,RANGE
866 UDP-RECV:<port>
868 Creates a UDP socket on <port> [UDP service] using UDP/IP ver‐
869 sion 4 or 6 depending on option pf. It receives packets from
870 multiple unspecified peers and merges the data. No replies are
871 possible. It works well with, e.g., socat UDP-SENDTO address
872 peers; it behaves similar to a syslog server.
873 Note: if you need the fork option, use UDP-RECVFROM in unidirec‐
874 tional mode (with option -u) instead.
875 Option groups: FD,SOCKET,IP4,IP6,RANGE
876 Useful options: pf, bind, sourceport, ttl, tos
877 See also: UDP4-RECV, UDP6-RECV, UDP-SENDTO, UDP-RECVFROM,
878 UDP-CONNECT, UDP-LISTEN, IP-RECV, UNIX-RECV
879 UDP4-RECV:<port>
881 Like UDP-RECV, but only supports IPv4 protocol.
882 Option groups: FD,SOCKET,IP4,RANGE
883 UDP6-RECV:<port>
885 Like UDP-RECV, but only supports IPv6 protocol.
886 Option groups: FD,SOCKET,IP6,RANGE
887 UNIX-CONNECT:<filename>
889 Connects to <filename> assuming it is a UNIX domain socket. If
890 <filename> does not exist, this is an error; if <filename> is
891 not a UNIX domain socket, this is an error; if <filename> is a
892 UNIX domain socket, but no process is listening, this is an er‐
893 ror.
894 Option groups: FD,SOCKET,NAMED,RETRY,UNIX
895 ) Useful options: bind
896 See also: UNIX-LISTEN, UNIX-SENDTO, TCP
897 UNIX-LISTEN:<filename>
899 Listens on <filename> using a UNIX domain stream socket and ac‐
900 cepts a connection. If <filename> exists and is not a socket,
901 this is an error. If <filename> exists and is a UNIX domain
902 socket, binding to the address fails (use option unlink-early!).
903 Note that opening this address usually blocks until a client
904 connects. Beginning with socat version 1.4.3, the file system
905 entry is removed when this address is closed (but see option un‐
906 link-close) (example).
907 Option groups: FD,SOCKET,NAMED,LISTEN,CHILD,RETRY,UNIX
908 Useful options: fork, umask, mode, user, group, unlink-early
909 See also: UNIX-CONNECT, UNIX-RECVFROM, UNIX-RECV, TCP-LISTEN
910 UNIX-SENDTO:<filename>
912 Communicates with the specified peer socket, defined by [<file‐
913 name>] assuming it is a UNIX domain datagram socket. It sends
914 packets to and receives packets from that peer socket only.
915 Please note that it might be necessary to bind the local socket
916 to an address (e.g. /tmp/sock1, which must not exist before).
917 This address type works well with socat UNIX-RECVFROM and
918 UNIX-RECV address peers.
919 Option groups: FD,SOCKET,NAMED,UNIX
920 Useful options: bind
921 See also: UNIX-RECVFROM, UNIX-RECV, UNIX-CONNECT, UDP-SENDTO,
922 IP-SENDTO
923 UNIX-RECVFROM:<filename>
925 Creates a UNIX domain datagram socket [<filename>]. Receives
926 one packet and may send one or more answer packets to that peer.
927 This mode is particularly useful with fork option where each ar‐
928 riving packet - from arbitrary peers - is handled by its own sub
929 process. This address works well with socat UNIX-SENDTO address
930 peers.
931 Option groups: FD,SOCKET,NAMED,CHILD,UNIX
932 See the note about RECVFROM addresses.
933 Useful options: fork
934 See also: UNIX-SENDTO, UNIX-RECV, UNIX-LISTEN, UDP-RECVFROM,
935 IP-RECVFROM
936 UNIX-RECV:<filename>
938 Creates a UNIX domain datagram socket [<filename>]. Receives
939 packets from multiple unspecified peers and merges the data. No
940 replies are possible. It can be, e.g., addressed by socat
941 UNIX-SENDTO address peers. It behaves similar to a syslog
942 server.
943 Option groups: FD,SOCKET,NAMED,UNIX
944 See also: UNIX-SENDTO, UNIX-RECVFROM, UNIX-LISTEN, UDP-RECV,
945 IP-RECV
946 UNIX-CLIENT:<filename>
948 Communicates with the specified peer socket, defined by [<file‐
949 name>] assuming it is a UNIX domain socket. It first tries to
950 connect and, if that fails, assumes it is a datagram socket,
951 thus supporting both types.
952 Option groups: FD,SOCKET,NAMED,UNIX
953 Useful options: bind
954 See also: UNIX-CONNECT, UNIX-SENDTO, GOPEN
955 VSOCK-CONNECT:<cid>:<port>
957 Establishes a VSOCK stream connection to the specified <cid>
958 [VSOCK cid] and <port> [VSOCK port].
959 Option groups: FD,SOCKET,CHILD,RETRY
960 Useful options: bind, pf, connect-timeout, retry, readbytes
961 See also: VSOCK-LISTEN,
962 VSOCK-LISTEN:<port>
964 Listens on <port> [VSOCK port] and accepts a VSOCK connection.
965 Note that opening this address usually blocks until a client
966 connects.
967 Option groups: FD,SOCKET,LISTEN,CHILD,RETRY
968 Useful options: fork, bind, pf, max-children, backlog, su,
969 reuseaddr, retry, cool-write
970 See also: VSOCK-CONNECT
971 ABSTRACT-CONNECT:<string>
973 ABSTRACT-LISTEN:<string>
975 ABSTRACT-SENDTO:<string>
977 ABSTRACT-RECVFROM:<string>
979 ABSTRACT-RECV:<string>
981 ABSTRACT-CLIENT:<string>
983 The ABSTRACT addresses are almost identical to the related UNIX
984 addresses except that they do not address file system based
985 sockets but an alternate UNIX domain address space. To achieve
986 this the socket address strings are prefixed with "\0" inter‐
987 nally. This feature is available (only?) on Linux. Option
988 groups are the same as with the related UNIX addresses, except
989 that the ABSTRACT addresses are not member of the NAMED group.
990
993 Address options can be applied to address specifications to influence
994 the process of opening the addresses and the properties of the result‐
995 ing data channels.
996 For technical reasons not every option can be applied to every address
998 type; e.g., applying a socket option to a regular file will fail. To
999 catch most useless combinations as early as in the open phase, the con‐
1000 cept of option groups was introduced. Each option belongs to one or
1001 more option groups. Options can be used only with address types that
1002 support at least one of their option groups (but see option -g).
1003 Address options have data types that their values must conform to. Ev‐
1005 ery address option consists of just a keyword or a keyword followed by
1006 "=value", where value must conform to the options type. Some address
1007 options manipulate parameters of system calls; e.g., option sync sets
1008 the O_SYNC flag with the open() call. Other options cause a system or
1009 library call; e.g., with option `ttl=value’ the setsockopt(fd, SOL_IP,
1010 IP_TTL, value, sizeof(int)) call is applied. Other options set inter‐
1011 nal socat variables that are used during data transfer; e.g., `crnl’
1012 causes explicit character conversions. A few options have more complex
1013 implementations; e.g., su-d (substuser-delayed) inquires some user and
1014 group infos, stores them, and applies them later after a possible ch‐
1015 root() call.
1016 If multiple options are given to an address, their sequence in the ad‐
1018 dress specification has (almost) no effect on the sequence of their ex‐
1019 ecution/application. Instead, socat has built in an option phase model
1020 that tries to bring the options in a useful order. Some options exist
1021 in different forms (e.g., unlink, unlink-early, unlink-late) to control
1022 the time of their execution.
1023 If the same option is specified more than once within one address spec‐
1025 ification, with equal or different values, the effect depends on the
1026 kind of option. Options resulting in function calls like setsockopt()
1027 cause multiple invocations. With options that set parameters for a re‐
1028 quired call like open() or set internal flags, the value of the last
1029 option occurrence is effective.
1030 The existence or semantics of many options are system dependent. Socat
1032 usually does NOT try to emulate missing libc or kernel features, it
1033 just provides an interface to the underlying system. So, if an operat‐
1034 ing system lacks a feature, the related option is simply not available
1035 on this platform.
1036 The following paragraphs introduce just the more common address op‐
1038 tions. For a more comprehensive reference and to find information about
1039 canonical option names, alias names, option phases, and platforms see
1040 file xio.help.
1041 FD option group
1044 This option group contains options that are applied to a UN*X style
1046 file descriptor, no matter how it was generated. Because all current
1047 socat address types are file descriptor based, these options may be ap‐
1048 plied to any address.
1049 Note: Some of these options are also member of another option group,
1050 that provides another, non-fd based mechanism. For these options, it
1051 depends on the actual address type and its option groups which mecha‐
1052 nism is used. The second, non-fd based mechanism is prioritized.
1053 cloexec=<bool>
1055 Sets the FD_CLOEXEC flag with the fcntl() system call to value
1056 <bool>. If set, the file descriptor is closed on exec() family
1057 function calls. Socat internally handles this flag for the fds
1058 it controls, so in most cases there will be no need to apply
1059 this option.
1060 setlk Tries to set a discretionary write lock to the whole file using
1062 the fcntl(fd, F_SETLK, ...) system call. If the file is already
1063 locked, this call results in an error. On Linux, when the file
1064 permissions for group are "S" (g-x,g+s), and the file system is
1065 locally mounted with the "mand" option, the lock is mandatory,
1066 i.e. prevents other processes from opening the file.
1067 setlkw Tries to set a discretionary waiting write lock to the whole
1069 file using the fcntl(fd, F_SETLKW, ...) system call. If the
1070 file is already locked, this call blocks. See option setlk for
1071 information about making this lock mandatory.
1072 setlk-rd
1074 Tries to set a discretionary read lock to the whole file using
1075 the fcntl(fd, F_SETLK, ...) system call. If the file is already
1076 write locked, this call results in an error. See option setlk
1077 for information about making this lock mandatory.
1078 setlkw-rd
1080 Tries to set a discretionary waiting read lock to the whole file
1081 using the fcntl(fd, F_SETLKW, ...) system call. If the file is
1082 already write locked, this call blocks. See option setlk for
1083 information about making this lock mandatory.
1084 flock-ex
1086 Tries to set a blocking exclusive advisory lock to the file us‐
1087 ing the flock(fd, LOCK_EX) system call. Socat hangs in this call
1088 if the file is locked by another process.
1089 flock-ex-nb
1091 Tries to set a nonblocking exclusive advisory lock to the file
1092 using the flock(fd, LOCK_EX|LOCK_NB) system call. If the file is
1093 already locked, this option results in an error.
1094 flock-sh
1096 Tries to set a blocking shared advisory lock to the file using
1097 the flock(fd, LOCK_SH) system call. Socat hangs in this call if
1098 the file is locked by another process.
1099 flock-sh-nb
1101 Tries to set a nonblocking shared advisory lock to the file us‐
1102 ing the flock(fd, LOCK_SH|LOCK_NB) system call. If the file is
1103 already locked, this option results in an error.
1104 lock Sets a blocking lock on the file. Uses the setlk or flock mecha‐
1106 nism depending on availability on the particular platform. If
1107 both are available, the POSIX variant (setlkw) is used.
1108 user=<user>
1110 Sets the <user> (owner) of the stream. If the address is member
1111 of the NAMED option group, socat uses the chown() system call
1112 after opening the file or binding to the UNIX domain socket
1113 (race condition!). Without filesystem entry, socat sets the
1114 user of the stream using the fchown() system call. These calls
1115 might require root privilege.
1116 user-late=<user>
1118 Sets the owner of the fd to <user> with the fchown() system call
1119 after opening or connecting the channel. This is useful only on
1120 file system entries.
1121 group=<group>
1123 Sets the <group> of the stream. If the address is member of the
1124 NAMED option group, socat uses the chown() system call after
1125 opening the file or binding to the UNIX domain socket (race con‐
1126 dition!). Without filesystem entry, socat sets the group of the
1127 stream with the fchown() system call. These calls might require
1128 group membership or root privilege.
1129 group-late=<group>
1131 Sets the group of the fd to <group> with the fchown() system
1132 call after opening or connecting the channel. This is useful
1133 only on file system entries.
1134 mode=<mode>
1136 Sets the <mode> [mode_t] (permissions) of the stream. If the
1137 address is member of the NAMED option group and uses the open()
1138 or creat() call, the mode is applied with these. If the address
1139 is member of the NAMED option group without using these system
1140 calls, socat uses the chmod() system call after opening the
1141 filesystem entry or binding to the UNIX domain socket (race con‐
1142 dition!). Otherwise, socat sets the mode of the stream using
1143 fchmod() . These calls might require ownership or root privi‐
1144 lege.
1145 perm-late=<mode>
1147 Sets the permissions of the fd to value <mode> [mode_t] using
1148 the fchmod() system call after opening or connecting the chan‐
1149 nel. This is useful only on file system entries.
1150 append=<bool>
1152 Always writes data to the actual end of file. If the address is
1153 member of the OPEN option group, socat uses the O_APPEND flag
1154 with the open() system call (example). Otherwise, socat applies
1155 the fcntl(fd, F_SETFL, O_APPEND) call.
1156 nonblock=<bool>
1158 Tries to open or use file in nonblocking mode. Its only effects
1159 are that the connect() call of TCP addresses does not block, and
1160 that opening a named pipe for reading does not block. If the
1161 address is member of the OPEN option group, socat uses the
1162 O_NONBLOCK flag with the open() system call. Otherwise, socat
1163 applies the fcntl(fd, F_SETFL, O_NONBLOCK) call.
1164 binary Opens the file in binary mode to avoid implicit line terminator
1166 conversions (Cygwin).
1167 text Opens the file in text mode to force implicit line terminator
1169 conversions (Cygwin).
1170 noinherit
1172 Does not keep this file open in a spawned process (Cygwin).
1173 cool-write
1175 Takes it easy when write fails with EPIPE or ECONNRESET and logs
1176 the message with notice level instead of error. This prevents
1177 the log file from being filled with useless error messages when
1178 socat is used as a high volume server or proxy where clients of‐
1179 ten abort the connection.
1180 This option is experimental.
1181 end-close
1183 Changes the (address dependent) method of ending a connection to
1184 just close the file descriptors. This is useful when the connec‐
1185 tion is to be reused by or shared with other processes (exam‐
1186 ple).
1187 Normally, socket connections will be ended with shutdown(2)
1188 which terminates the socket even if it is shared by multiple
1189 processes. close(2) "unlinks" the socket from the process but
1190 keeps it active as long as there are still links from other pro‐
1191 cesses.
1192 Similarly, when an address of type EXEC or SYSTEM is ended, so‐
1193 cat usually will explicitly kill the sub process. With this op‐
1194 tion, it will just close the file descriptors.
1195 shut-none
1197 Changes the (address dependent) method of shutting down the
1198 write part of a connection to not do anything.
1199 shut-down
1201 Changes the (address dependent) method of shutting down the
1202 write part of a connection to shutdown(fd, SHUT_WR). Is only
1203 useful with sockets.
1204 shut-close
1206 Changes the (address dependent) method of shutting down the
1207 write part of a connection to close(fd).
1208 shut-null
1210 When one address indicates EOF, socat will send a zero sized
1211 packet to the write channel of the other address to transfer the
1212 EOF condition. This is useful with UDP and other datagram proto‐
1213 cols. Has been tested against netcat and socat with option
1214 null-eof.
1215 null-eof
1217 Normally socat will ignore empty (zero size payload) packets ar‐
1218 riving on datagram sockets, so it survives port scans. With this
1219 option socat interprets empty datagram packets as EOF indicator
1220 (see shut-null).
1221 ioctl-void=<request>
1223 Calls ioctl() with the request value as second argument and NULL
1224 as third argument. This option allows utilizing ioctls that are
1225 not explicitly implemented in socat.
1226 ioctl-int=<request>:<value>
1228 Calls ioctl() with the request value as second argument and the
1229 integer value as third argument.
1230 ioctl-intp=<request>:<value>
1232 Calls ioctl() with the request value as second argument and a
1233 pointer to the integer value as third argument.
1234 ioctl-bin=<request>:<value>
1236 Calls ioctl() with the request value as second argument and a
1237 pointer to the given data value as third argument. This data
1238 must be specified in <dalan> form.
1239 ioctl-string=<request>:<value>
1241 Calls ioctl() with the request value as second argument and a
1242 pointer to the given string as third argument. <dalan> form.
1243 NAMED option group
1246 These options work on file system entries.
1248 Please note that, with UNIX domain client addresses, this means the
1249 bind entry, not the target/peer entry.
1250 See also options user, group, and mode.
1251 user-early=<user>
1253 Changes the <user> (owner) of the file system entry before ac‐
1254 cessing it, using the chown() system call. This call might re‐
1255 quire root privilege.
1256 group-early=<group>
1258 Changes the <group> of the file system entry before accessing
1259 it, using the chown() system call. This call might require group
1260 membership or root privilege.
1261 perm-early=<mode>
1263 Changes the <mode> [mode_t] of the file system entry before ac‐
1264 cessing it, using the chmod() system call. This call might re‐
1265 quire ownership or root privilege.
1266 umask=<mode>
1268 Sets the umask of the process to <mode> [mode_t] before access‐
1269 ing the file system entry (useful with UNIX domain sockets!).
1270 This call might affect all further operations of the socat
1271 process!
1272 unlink-early
1274 Unlinks (removes) the file before opening it and even before ap‐
1275 plying user-early etc.
1276 unlink Unlinks (removes) the file before accessing it, but after
1278 user-early etc.
1279 unlink-late
1281 Unlinks (removes) the file after opening it to make it inacces‐
1282 sible for other processes after a short race condition.
1283 unlink-close
1285 Removes the addresses file system entry when closing the ad‐
1286 dress. For named pipes, UNIX domain sockets, and the symbolic
1287 links of pty addresses, the default is 1; for created files,
1288 opened files, and generic opened files the default is 0.
1289 OPEN option group
1292 The OPEN group options allow setting flags with the open() system call.
1294 E.g., option `creat’ sets the O_CREAT flag.
1295 See also options append and nonblock.
1296 creat=<bool>
1298 Creates the file if it does not exist (example).
1299 dsync=<bool>
1301 Blocks write() calls until metainfo is physically written to me‐
1302 dia.
1303 excl=<bool>
1305 With option creat, if file exists this is an error.
1306 largefile=<bool>
1308 On 32 bit systems, allows a file larger than 2^31 bytes.
1309 noatime
1311 Sets the O_NOATIME options, so reads do not change the access
1312 timestamp.
1313 noctty=<bool>
1315 Does not make this file the controlling terminal.
1316 nofollow=<bool>
1318 Does not follow symbolic links.
1319 nshare=<bool>
1321 Does not allow sharing this file with other processes.
1322 rshare=<bool>
1324 Does not allow other processes to open this file for writing.
1325 rsync=<bool>
1327 Blocks write() until metainfo is physically written to media.
1328 sync=<bool>
1330 Blocks write() until data is physically written to media.
1331 rdonly=<bool>
1333 Opens the file for reading only.
1334 wronly=<bool>
1336 Opens the file for writing only.
1337 trunc Truncates the file to size 0 during opening it.
1339 REG and BLK option group
1342 These options are usually applied to a UN*X file descriptor, but their
1344 semantics make sense only on a file supporting random access.
1345 seek=<offset>
1347 Applies the lseek(fd, <offset>, SEEK_SET) (or lseek64 ) system
1348 call, thus positioning the file pointer absolutely to <offset>
1349 [off_t or off64_t]. Please note that a missing value defaults to
1350 1, not 0.
1351 seek-cur=<offset>
1353 Applies the lseek(fd, <offset>, SEEK_CUR) (or lseek64 ) system
1354 call, thus positioning the file pointer <offset> [off_t or
1355 off64_t] bytes relatively to its current position (which is usu‐
1356 ally 0). Please note that a missing value defaults to 1, not 0.
1357 seek-end=<offset>
1359 Applies the lseek(fd, <offset>, SEEK_END) (or lseek64 ) system
1360 call, thus positioning the file pointer <offset> [off_t or
1361 off64_t] bytes relatively to the files current end. Please note
1362 that a missing value defaults to 1, not 0.
1363 ftruncate=<offset>
1365 Applies the ftruncate(fd, <offset>) (or ftruncate64 if avail‐
1366 able) system call, thus truncating the file at the position
1367 <offset> [off_t or off64_t]. Please note that a missing value
1368 defaults to 1, not 0.
1369 secrm=<bool>
1371 unrm=<bool>
1373 compr=<bool>
1375 fs-sync=<bool>
1377 immutable=<bool>
1379 fs-append=<bool>
1381 nodump=<bool>
1383 fs-noatime=<bool>
1385 journal-data=<bool>
1387 notail=<bool>
1389 dirsync=<bool>
1391 These options change non standard file attributes on operating
1392 systems and file systems that support these features, like Linux
1393 with ext2fs and successors, xfs, or reiserfs. See man 1 chattr
1394 for information on these options. Please note that there might
1395 be a race condition between creating the file and applying these
1396 options.
1397 PROCESS option group
1400 Options of this group change the process properties instead of just af‐
1402 fecting one data channel. For EXEC and SYSTEM addresses and for LISTEN
1403 and CONNECT type addresses with option FORK, these options apply to the
1404 child processes instead of the main socat process.
1405 chroot=<directory>
1407 Performs a chroot() operation to <directory> after processing
1408 the address (example). This call might require root privilege.
1409 chroot-early=<directory>
1411 Performs a chroot() operation to <directory> before opening the
1412 address. This call might require root privilege.
1413 setgid=<group>
1415 Changes the primary <group> of the process after processing the
1416 address. This call might require root privilege. Please note
1417 that this option does not drop other group related privileges.
1418 setgid-early=<group>
1420 Like setgit but is performed before opening the address.
1421 setuid=<user>
1423 Changes the <user> (owner) of the process after processing the
1424 address. This call might require root privilege. Please note
1425 that this option does not drop group related privileges. Check
1426 if option su better fits your needs.
1427 setuid-early=<user>
1429 Like setuid but is performed before opening the address.
1430 su=<user>
1432 Changes the <user> (owner) and groups of the process after pro‐
1433 cessing the address (example). This call might require root
1434 privilege.
1435 su-d=<user>
1437 Short name for substuser-delayed. Changes the <user> (owner)
1438 and groups of the process after processing the address (exam‐
1439 ple). The user and his groups are retrieved before a possible
1440 chroot() . This call might require root privilege.
1441 setpgid=<pid_t>
1443 Makes the process a member of the specified process group
1444 <pid_t>. If no value is given, or if the value is 0 or 1, the
1445 process becomes leader of a new process group.
1446 setsid Makes the process the leader of a new session (example).
1448 READLINE option group
1451 These options apply to the readline address type.
1453 history=<filename>
1455 Reads and writes history from/to <filename> (example).
1456 noprompt
1458 Since version 1.4.0, socat per default tries to determine a
1459 prompt - that is then passed to the readline call - by remember‐
1460 ing the last incomplete line of the output. With this option,
1461 socat does not pass a prompt to readline, so it begins line
1462 editing in the first column of the terminal.
1463 noecho=<pattern>
1465 Specifies a regular pattern for a prompt that prevents the fol‐
1466 lowing input line from being displayed on the screen and from
1467 being added to the history. The prompt is defined as the text
1468 that was output to the readline address after the lastest new‐
1469 line character and before an input character was typed. The pat‐
1470 tern is a regular expression, e.g. "^[Pp]assword:.*$" or
1471 "([Uu]ser:|[Pp]assword:)". See regex(7) for details. (example)
1472 prompt=<string>
1474 Passes the string as prompt to the readline function. readline
1475 prints this prompt when stepping through the history. If this
1476 string matches a constant prompt issued by an interactive pro‐
1477 gram on the other socat address, consistent look and feel can be
1478 achieved.
1479 APPLICATION option group
1482 This group contains options that work at data level. Note that these
1484 options only apply to the "raw" data transferred by socat, but not to
1485 protocol data used by addresses like PROXY.
1486 cr Converts the default line termination character NL (’\n’, 0x0a)
1488 to/from CR (’\r’, 0x0d) when writing/reading on this channel.
1489 crnl Converts the default line termination character NL (’\n’, 0x0a)
1491 to/from CRNL ("\r\n", 0x0d0a) when writing/reading on this chan‐
1492 nel (example). Note: socat simply strips all CR characters.
1493 ignoreeof
1495 When EOF occurs on this channel, socat ignores it and tries to
1496 read more data (like "tail -f") (example).
1497 readbytes=<bytes>
1499 socat reads only so many bytes from this address (the address
1500 provides only so many bytes for transfer and pretends to be at
1501 EOF afterwards). Must be greater than 0.
1502 lockfile=<filename>
1504 If lockfile exists, exits with error. If lockfile does not ex‐
1505 ist, creates it and continues, unlinks lockfile on exit.
1506 waitlock=<filename>
1508 If lockfile exists, waits until it disappears. When lockfile
1509 does not exist, creates it and continues, unlinks lockfile on
1510 exit.
1511 escape=<int>
1513 Specifies the numeric code of a character that triggers EOF on
1514 the input stream. It is useful with a terminal in raw mode (ex‐
1515 ample).
1516 SOCKET option group
1519 These options are intended for all kinds of sockets, e.g. IP or UNIX
1521 domain. Most are applied with a setsockopt() call.
1522 bind=<sockname>
1524 Binds the socket to the given socket address using the bind()
1525 system call. The form of <sockname> is socket domain dependent:
1526 IP4 and IP6 allow the form [hostname|hostaddress][:(ser‐
1527 vice|port)] (example), UNIX domain sockets require <filename>,
1528 VSOCK allow the form [cid][:(port)].
1529 connect-timeout=<seconds>
1531 Abort the connection attempt after <seconds> [timeval] with er‐
1532 ror status.
1533 so-bindtodevice=<interface>
1535 Binds the socket to the given <interface>. This option might
1536 require root privilege.
1537 broadcast
1539 For datagram sockets, allows sending to broadcast addresses and
1540 receiving packets addressed to broadcast addresses.
1541 debug Enables socket debugging.
1543 dontroute
1545 Only communicates with directly connected peers, does not use
1546 routers.
1547 keepalive
1549 Enables sending keepalives on the socket.
1550 linger=<seconds>
1552 Blocks shutdown() or close() until data transfers have finished
1553 or the given timeout [int] expired.
1554 oobinline
1556 Places out-of-band data in the input data stream.
1557 priority=<priority>
1559 Sets the protocol defined <priority> [<int>] for outgoing pack‐
1560 ets.
1561 rcvbuf=<bytes>
1563 Sets the size of the receive buffer after the socket() call to
1564 <bytes> [int]. With TCP sockets, this value corresponds to the
1565 socket’s maximal window size.
1566 rcvbuf-late=<bytes>
1568 Sets the size of the receive buffer when the socket is already
1569 connected to <bytes> [int]. With TCP sockets, this value corre‐
1570 sponds to the socket’s maximal window size.
1571 rcvlowat=<bytes>
1573 Specifies the minimum number of received bytes [int] until the
1574 socket layer will pass the buffered data to socat.
1575 reuseaddr
1577 Allows other sockets to bind to an address even if parts of it
1578 (e.g. the local port) are already in use by socat (example).
1579 sndbuf=<bytes>
1581 Sets the size of the send buffer after the socket() call to
1582 <bytes> [int].
1583 sndbuf-late=<bytes>
1585 Sets the size of the send buffer when the socket is connected to
1586 <bytes> [int].
1587 sndlowat=<bytes>
1589 Specifies the minimum number of bytes in the send buffer until
1590 the socket layer will send the data to <bytes> [int].
1591 pf=<string>
1593 Forces the use of the specified IP version or protocol. <string>
1594 can be something like "ip4" or "ip6". The resulting value is
1595 used as first argument to the socket() or socketpair() calls.
1596 This option affects address resolution and the required syntax
1597 of bind and range options.
1598 socktype=<type>
1600 Sets the type of the socket, specified as second argument to the
1601 socket() or socketpair() calls, to <type> [int]. Address resolu‐
1602 tion is not affected by this option. Under Linux, 1 means
1603 stream oriented socket, 2 means datagram socket, 3 means raw
1604 socket, and 5 seqpacket (stream keeping packet boundaries).
1605 protocol
1607 Sets the protocol of the socket, specified as third argument to
1608 the socket() or socketpair() calls, to <protocol> [int]. Address
1609 resolution is not affected by this option. 6 means TCP, 17
1610 means UDP.
1611 reuseport
1613 Set the SO_REUSEPORT socket option.
1614 so-timestamp
1616 Sets the SO_TIMESTAMP socket option. This enables receiving and
1617 logging of timestamp ancillary messages.
1618 setsockopt=<level>:<optname>:<optval>
1620 Invokes setsockopt() for the socket with the given parameters.
1621 level [int] is used as second argument to setsockopt() and spec‐
1622 ifies the layer, e.g. SOL_TCP for TCP (6 on Linux), or
1623 SOL_SOCKET for the socket layer (1 on Linux). optname [int] is
1624 the third argument to setsockopt() and tells which socket option
1625 is to be set. For the actual numbers you might have to look up
1626 the appropriate include files of your system. For the 4th and
1627 5th setsockopt() parameters, value [dalan] specifies an arbi‐
1628 trary sequence of bytes that are passed to the function per
1629 pointer, with the automatically derived length parameter.
1630 setsockopt-int=<level>:<optname>:<optval>
1632 Like setsockopt, but <optval> is a pointer to int [int]
1633 setsockopt-listen=<level>:<optname>:<optval>
1635 Like setsockopt, but for listen type addresses it is applied to
1636 the listening socket instead of the connected socket.
1637 setsockopt-string=<level>:<optname>:<optval>
1639 Like setsockopt, but <optval> is a string. This string is
1640 passed to the function with trailing null character, and the
1641 length parameter is automatically derived from the data.
1642 UNIX option group
1645 These options apply to UNIX domain based addresses.
1647 unix-tightsocklen=[0|1]
1649 On socket operations, pass a socket address length that does not
1650 include the whole struct sockaddr_un record but (besides other
1651 components) only the relevant part of the filename or abstract
1652 string. Default is 1.
1653 IP4 and IP6 option groups
1656 These options can be used with IPv4 and IPv6 based sockets.
1658 tos=<tos>
1660 Sets the TOS (type of service) field of outgoing packets to
1661 <tos> [byte] (see RFC 791).
1662 ttl=<ttl>
1664 Sets the TTL (time to live) field of outgoing packets to <ttl>
1665 [byte].
1666 ip-options=<data>
1668 Sets IP options like source routing. Must be given in binary
1669 form, recommended format is a leading "x" followed by an even
1670 number of hex digits. This option may be used multiple times,
1671 data are appended. E.g., to connect to host 10.0.0.1 via some
1672 gateway using a loose source route, use the gateway as address
1673 parameter and set a loose source route using the option ip-op‐
1674 tions=x8307040a000001 .
1675 IP options are defined in RFC 791.
1676 mtudiscover=<0|1|2>
1678 Takes 0, 1, 2 to never, want, or always use path MTU discover on
1679 this socket.
1680 ip-pktinfo
1682 Sets the IP_PKTINFO socket option. This enables receiving and
1683 logging of ancillary messages containing destination address and
1684 interface (Linux) (example).
1685 ip-recverr
1687 Sets the IP_RECVERR socket option. This enables receiving and
1688 logging of ancillary messages containing detailed error informa‐
1689 tion.
1690 ip-recvopts
1692 Sets the IP_RECVOPTS socket option. This enables receiving and
1693 logging of IP options ancillary messages (Linux, *BSD).
1694 ip-recvtos
1696 Sets the IP_RECVTOS socket option. This enables receiving and
1697 logging of TOS (type of service) ancillary messages (Linux).
1698 ip-recvttl
1700 Sets the IP_RECVTTL socket option. This enables receiving and
1701 logging of TTL (time to live) ancillary messages (Linux, *BSD).
1702 ip-recvdstaddr
1704 Sets the IP_RECVDSTADDR socket option. This enables receiving
1705 and logging of ancillary messages containing destination address
1706 (*BSD) (example).
1707 ip-recvif
1709 Sets the IP_RECVIF socket option. This enables receiving and
1710 logging of interface ancillary messages (*BSD) (example).
1711 ip-add-membership=<multicast-address:interface-address>
1713 ip-add-membership=<multicast-address:interface-name>
1715 ip-add-membership=<multicast-address:interface-index>
1717 ip-add-membership=<multicast-address:interface-address:interface-name>
1719 ip-add-membership=<multicast-address:interface-address:interface-index>
1721 Makes the socket member of the specified multicast group. This
1722 is currently only implemented for IPv4. The option takes the IP
1723 address of the multicast group and info about the desired net‐
1724 work interface. The most common syntax is the first one, while
1725 the others are only available on systems that provide struct
1726 mreqn (Linux).
1727 The indices of active network interfaces can be shown using the
1728 utility procan.
1729 ip-add-source-membership=<multicast-address:interface-ad‐
1731 dress:source-address>
1732 Makes the socket member of the specified multicast group for the
1733 specified source, i.e. only multicast traffic from this address
1734 is to be delivered. This is currently only implemented for
1735 IPv4.
1736 ip-multicast-if=<hostname>
1738 Specifies hostname or address of the network interface to be
1739 used for multicast traffic.
1740 ip-multicast-loop=<bool>
1742 Specifies if outgoing multicast traffic should loop back to the
1743 interface.
1744 ip-multicast-ttl=<byte>
1746 Sets the TTL used for outgoing multicast traffic. Default is 1.
1747 ip-transparent
1749 Sets the IP_TRANSPARENT socket option. This option might re‐
1750 quire root privilege.
1751 res-debug
1753 res-aaonly
1755 res-usevc
1757 res-primary
1759 res-igntc
1761 res-recurse
1763 res-defnames
1765 res-stayopen
1767 res-dnsrch
1769 These options set the corresponding resolver (name resolution)
1770 option flags. Append "=0" to clear a default option. See man
1771 resolver(5) for more information on these options. Note: these
1772 options are valid only for the address they are applied to.
1773 IP6 option group
1775 These options can only be used on IPv6 based sockets. See IP options
1777 for options that can be applied to both IPv4 and IPv6 sockets.
1778 ipv6only=<bool>
1780 Sets the IPV6_V6ONLY socket option. If 0, the TCP stack will
1781 also accept connections using IPv4 protocol on the same port.
1782 The default is system dependent.
1783 ipv6-recvdstopts
1785 Sets the IPV6_RECVDSTOPTS socket option. This enables receiving
1786 and logging of ancillary messages containing the destination op‐
1787 tions.
1788 ipv6-recvhoplimit
1790 Sets the IPV6_RECVHOPLIMIT socket option. This enables receiving
1791 and logging of ancillary messages containing the hoplimit.
1792 ipv6-recvhopopts
1794 Sets the IPV6_RECVHOPOPTS socket option. This enables receiving
1795 and logging of ancillary messages containing the hop options.
1796 ipv6-recvpktinfo
1798 Sets the IPV6_RECVPKTINFO socket option. This enables receiving
1799 and logging of ancillary messages containing destination address
1800 and interface.
1801 ipv6-unicast-hops=link(TYPE_INT)(<int>)
1803 Sets the IPV6_UNICAST_HOPS socket option. This sets the hop
1804 count limit (TTL) for outgoing unicast packets.
1805 ipv6-recvrthdr
1807 Sets the IPV6_RECVRTHDR socket option. This enables receiving
1808 and logging of ancillary messages containing routing informa‐
1809 tion.
1810 ipv6-tclass
1812 Sets the IPV6_TCLASS socket option. This sets the transfer class
1813 of outgoing packets.
1814 ipv6-recvtclass
1816 Sets the IPV6_RECVTCLASS socket option. This enables receiving
1817 and logging of ancillary messages containing the transfer class.
1818 TCP option group
1821 These options may be applied to TCP sockets. They work by invoking set‐
1823 sockopt() with the appropriate parameters.
1824 cork Doesn’t send packets smaller than MSS (maximal segment size).
1826 defer-accept
1828 While listening, accepts connections only when data from the
1829 peer arrived.
1830 keepcnt=<count>
1832 Sets the number of keepalives before shutting down the socket to
1833 <count> [int].
1834 keepidle=<seconds>
1836 Sets the idle time before sending the first keepalive to <sec‐
1837 onds> [int].
1838 keepintvl=<seconds>
1840 Sets the interval between two keepalives to <seconds> [int].
1841 linger2=<seconds>
1843 Sets the time to keep the socket in FIN-WAIT-2 state to <sec‐
1844 onds> [int].
1845 mss=<bytes>
1847 Sets the MSS (maximum segment size) after the socket() call to
1848 <bytes> [int]. This value is then proposed to the peer with the
1849 SYN or SYN/ACK packet (example).
1850 mss-late=<bytes>
1852 Sets the MSS of the socket after connection has been established
1853 to <bytes> [int].
1854 nodelay
1856 Turns off the Nagle algorithm for measuring the RTT (round trip
1857 time).
1858 rfc1323
1860 Enables RFC1323 TCP options: TCP window scale, round-trip time
1861 measurement (RTTM), and protect against wrapped sequence numbers
1862 (PAWS) (AIX).
1863 stdurg Enables RFC1122 compliant urgent pointer handling (AIX).
1865 syncnt=<count>
1867 Sets the maximal number of SYN retransmits during connect to
1868 <count> [int].
1869 md5sig Enables generation of MD5 digests on the packets (FreeBSD).
1871 noopt Disables use of TCP options (FreeBSD, MacOSX).
1873 nopush sets the TCP_NOPUSH socket option (FreeBSD, MacOSX).
1875 sack-disable
1877 Disables use the selective acknowledge feature (OpenBSD).
1878 signature-enable
1880 Enables generation of MD5 digests on the packets (OpenBSD).
1881 abort-threshold=<milliseconds>
1883 Sets the time to wait for an answer of the peer on an estab‐
1884 lished connection (HP-UX).
1885 conn-abort-threshold=<milliseconds>
1887 Sets the time to wait for an answer of the server during the
1888 initial connect (HP-UX).
1889 keepinit
1891 Sets the time to wait for an answer of the server during con‐
1892 nect() before giving up. Value in half seconds, default is 150
1893 (75s) (Tru64).
1894 paws Enables the "protect against wrapped sequence numbers" feature
1896 (Tru64).
1897 sackena
1899 Enables selective acknowledge (Tru64).
1900 tsoptena
1902 Enables the time stamp option that allows RTT recalculation on
1903 existing connections (Tru64).
1904 UDP option group
1907 This option may be applied to UDP datagram sockets.
1909 udp-ignore-peerport>
1911 Address UDP-DATAGRAM expects incoming responses to come from the
1912 port specified in its second parameter. With this option, it ac‐
1913 cepts packets coming from any port.
1914 SCTP option group
1917 These options may be applied to SCTP stream sockets.
1919 sctp-nodelay
1921 Sets the SCTP_NODELAY socket option that disables the Nagle al‐
1922 gorithm.
1923 sctp-maxseg=<bytes>
1925 Sets the SCTP_MAXSEG socket option to <bytes> [int]. This value
1926 is then proposed to the peer with the SYN or SYN/ACK packet.
1927 UDP, TCP, and SCTP option group
1930 Here we find options that are related to the network port mechanism and
1932 thus can be used with UDP, TCP, and SCTP client and server addresses.
1933 sourceport=<port>
1935 For outgoing (client) TCP and UDP connections, it sets the
1936 source <port> using an extra bind() call. With TCP or UDP lis‐
1937 ten addresses, socat immediately shuts down the connection if
1938 the client does not use this sourceport. UDP-RECV, UDP-RECVFROM,
1939 UDP-SENDTO, and UDP-DATAGRAM addresses ignore the packet when it
1940 does not match. (example).
1941 lowport
1943 Outgoing (client) TCP and UDP connections with this option use
1944 an unused random source port between 640 and 1023 incl. On UNIX
1945 class operating systems, this requires root privilege, and thus
1946 indicates that the client process is authorized by local root.
1947 TCP and UDP listen addresses with this option immediately shut
1948 down the connection if the client does not use a sourceport <=
1949 1023. This mechanism can provide limited authorization under
1950 some circumstances.
1951 SOCKS option group
1954 When using SOCKS type addresses, some socks specific options can be
1956 set.
1957 socksport=<tcp service>
1959 Overrides the default "socks" service or port 1080 for the socks
1960 server port with <TCP service>.
1961 socksuser=<user>
1963 Sends the <user> [string] in the username field to the socks
1964 server. Default is the actual user name ($LOGNAME or $USER) (ex‐
1965 ample).
1966 HTTP option group
1969 Options that can be provided with HTTP type addresses. The only HTTP
1971 address currently implemented is proxy-connect.
1972 proxyport=<TCP service>
1974 Overrides the default HTTP proxy port 8080 with <TCP service>.
1975 ignorecr
1977 The HTTP protocol requires the use of CR+NL as line terminator.
1978 When a proxy server violates this standard, socat might not un‐
1979 derstand its answer. This option directs socat to interprete NL
1980 as line terminator and to ignore CR in the answer. Nevertheless,
1981 socat sends CR+NL to the proxy.
1982 proxy-authorization=<username>:<password>
1984 Provide "basic" authentication to the proxy server. The argument
1985 to the option is used with a "Proxy-Authorization: Basic" header
1986 in base64 encoded form.
1987 Note: username and password are visible for every user on the
1988 local machine in the process list; username and password are
1989 transferred to the proxy server unencrypted (base64 encoded) and
1990 might be sniffed.
1991 proxy-authorization-file=<filename>
1993 Like option proxy-authorization, but the credentials are read
1994 from the file and therefore not visible in the process list.
1995 resolve
1997 Per default, socat sends to the proxy a CONNECT request contain‐
1998 ing the target hostname. With this option, socat resolves the
1999 hostname locally and sends the IP address. Please note that, ac‐
2000 cording to RFC 2396, only name resolution to IPv4 addresses is
2001 implemented.
2002 RANGE option group
2005 These options check if a connecting client should be granted access.
2007 They can be applied to listening and receiving network sockets.
2008 tcp-wrappers options fall into this group.
2009 range=<address-range>
2011 After accepting a connection, tests if the peer is within range.
2012 For IPv4 addresses, address-range takes the form address/bits,
2013 e.g. 10.0.0.0/8, or address:mask, e.g. 10.0.0.0:255.0.0.0 (ex‐
2014 ample); for IPv6, it is [ip6-address]/bits, e.g. [::1]/128. If
2015 the client address does not match, socat refuses the connection
2016 attempt, issues a warning, and keeps listening/receiving.
2017 tcpwrap[=<name>]
2019 Uses Wietse Venema’s libwrap (tcpd) library to determine if the
2020 client is allowed to connect. The configuration files are
2021 /etc/hosts.allow and /etc/hosts.deny per default, see "man 5
2022 hosts_access" for more information. The optional <name> (type
2023 string) is passed to the wrapper functions as daemon process
2024 name (example). If omitted, the basename of socats invocation
2025 (argv[0]) is passed. If both tcpwrap and range options are ap‐
2026 plied to an address, both conditions must be fulfilled to allow
2027 the connection.
2028 allow-table=<filename>
2030 Takes the specified file instead of /etc/hosts.allow.
2031 deny-table=<filename>
2033 Takes the specified file instead of /etc/hosts.deny.
2034 tcpwrap-etc=<directoryname>
2036 Looks for hosts.allow and hosts.deny in the specified directory.
2037 Is overridden by options hosts-allow and hosts-deny.
2038 LISTEN option group
2041 Options specific to listening sockets.
2043 backlog=<count>
2045 Sets the backlog value passed with the listen() system call to
2046 <count> [int]. Default is 5.
2047 accept-timeout=<seconds>
2049 End waiting for a connection after <seconds> [timeval] with er‐
2050 ror status.
2051 max-children=<count>
2053 Limits the number of concurrent child processes [int]. Default
2054 is no limit.
2055 CHILD option group
2058 Options for addresses with multiple connections via child processes.
2060 fork After establishing a connection, handles its channel in a child
2062 process and keeps the parent process attempting to produce more
2063 connections, either by listening or by connecting in a loop (ex‐
2064 ample).
2065 OPENSSL-CONNECT and OPENSSL-LISTEN differ in when they actually
2066 fork off the child: OPENSSL-LISTEN forks before the SSL hand‐
2067 shake, while OPENSSL-CONNECT forks afterwards. retry and for‐
2068 ever options are not inherited by the child process.
2069 On some operating systems (e.g. FreeBSD) this option does not
2070 work for UDP-LISTEN addresses.
2071 EXEC option group
2074 Options for addresses that invoke a program.
2076 path=<string>
2078 Overrides the PATH environment variable for searching the pro‐
2079 gram with <string>. This $PATH value is effective in the child
2080 process too.
2081 login Prefixes argv[0] for the execvp() call with ’-’, thus making a
2083 shell behave as login shell.
2084 FORK option group
2087 EXEC or SYSTEM addresses invoke a program using a child process and
2089 transfer data between socat and the program. The interprocess communi‐
2090 cation mechanism can be influenced with the following options. Per de‐
2091 fault, a socketpair() is created and assigned to stdin and stdout of
2092 the child process, while stderr is inherited from the socat process,
2093 and the child process uses file descriptors 0 and 1 for communicating
2094 with the main socat process.
2095 nofork Does not fork a subprocess for executing the program, instead
2097 calls execvp() or system() directly from the actual socat in‐
2098 stance. This avoids the overhead of another process between the
2099 program and its peer, but introduces a lot of restrictions:
2100 o this option can only be applied to the second socat address.
2102 o it cannot be applied to a part of a dual address.
2104 o the first socat address cannot be OPENSSL or READLINE
2106 o socat options -b, -t, -D, -l, -v, -x become useless
2108 o for both addresses, options ignoreeof, cr, and crnl become use‐
2110 less
2111 o for the second address (the one with option nofork), options ap‐
2113 pend, cloexec, flock, user, group, mode, nonblock, perm-late,
2114 setlk, and setpgid cannot be applied. Some of these could be
2115 used on the first address though.
2116 pipes Creates a pair of unnamed pipes for interprocess communication
2118 instead of a socket pair.
2119 openpty
2121 Establishes communication with the sub process using a pseudo
2122 terminal created with openpty() instead of the default (socket‐
2123 pair or ptmx).
2124 ptmx Establishes communication with the sub process using a pseudo
2126 terminal created by opening /dev/ptmx or /dev/ptc instead of the
2127 default (socketpair).
2128 pty Establishes communication with the sub process using a pseudo
2130 terminal instead of a socket pair. Creates the pty with an
2131 available mechanism. If openpty and ptmx are both available, it
2132 uses ptmx because this is POSIX compliant (example).
2133 ctty Makes the pty the controlling tty of the sub process (example).
2135 stderr Directs stderr of the sub process to its output channel by mak‐
2137 ing stderr a dup() of stdout (example).
2138 fdin=<fdnum>
2140 Assigns the sub processes input channel to its file descriptor
2141 <fdnum> instead of stdin (0). The program started from the sub‐
2142 process has to use this fd for reading data from socat (exam‐
2143 ple).
2144 fdout=<fdnum>
2146 Assigns the sub processes output channel to its file descriptor
2147 <fdnum> instead of stdout (1). The program started from the sub‐
2148 process has to use this fd for writing data to socat (example).
2149 sighup, sigint, sigquit
2151 Has socat pass signals of this type to the sub process. If no
2152 address has this option, socat terminates on these signals.
2153 TERMIOS option group
2156 For addresses that work on a tty (e.g., stdio, file:/dev/tty,
2158 exec:...,pty), the terminal parameters defined in the UN*X termios
2159 mechanism are made available as address option parameters. Please note
2160 that changes of the parameters of your interactive terminal remain ef‐
2161 fective after socat’s termination, so you might have to enter "reset"
2162 or "stty sane" in your shell afterwards. For EXEC and SYSTEM addresses
2163 with option PTY, these options apply to the pty by the child processes.
2164 b0 Disconnects the terminal.
2166 b19200 Sets the serial line speed to 19200 baud. Some other rates are
2168 possible; use something like socat -hh |grep ’ b[1-9]’ to find
2169 all speeds supported by your implementation.
2170 Note: On some operating systems, these options may not be avail‐
2171 able. Use ispeed or ospeed instead.
2172 echo=<bool>
2174 Enables or disables local echo.
2175 icanon=<bool>
2177 Sets or clears canonical mode, enabling line buffering and some
2178 special characters.
2179 raw Sets raw mode, thus passing input and output almost unprocessed.
2181 This option is obsolete, use option rawer or cfmakeraw instead.
2182 rawer Makes terminal rawer than raw option. This option implicitly
2184 turns off echo. (example).
2185 cfmakeraw
2187 Sets raw mode by invoking cfmakeraw() or by simulating this
2188 call. This option implicitly turns off echo.
2189 ignbrk=<bool>
2191 Ignores or interpretes the BREAK character (e.g., ^C)
2192 brkint=<bool>
2194 bs0
2196 bs1
2198 bsdly=<0|1>
2200 clocal=<bool>
2202 cr0
2205 cr1
2206 cr2
2207 cr3
2208 Sets the carriage return delay to 0, 1, 2, or 3, respectively.
2210 0 means no delay, the other values are terminal dependent.
2211 crdly=<0|1|2|3>
2213 cread=<bool>
2215 crtscts=<bool>
2217 cs5
2220 cs6
2221 cs7
2222 cs8
2223 Sets the character size to 5, 6, 7, or 8 bits, respectively.
2225 csize=<0|1|2|3>
2227 cstopb=<bool>
2229 Sets two stop bits, rather than one.
2230 dsusp=<byte>
2232 Sets the value for the VDSUSP character that suspends the cur‐
2233 rent foreground process and reactivates the shell (all except
2234 Linux).
2235 echoctl=<bool>
2237 Echos control characters in hat notation (e.g. ^A)
2238 echoe=<bool>
2240 echok=<bool>
2242 echoke=<bool>
2244 echonl=<bool>
2246 echoprt=<bool>
2248 eof=<byte>
2250 eol=<byte>
2252 eol2=<byte>
2254 erase=<byte>
2256 discard=<byte>
2258 ff0
2260 ff1
2262 ffdly=<bool>
2264 flusho=<bool>
2266 hupcl=<bool>
2268 icrnl=<bool>
2270 iexten=<bool>
2272 igncr=<bool>
2274 ignpar=<bool>
2276 imaxbel=<bool>
2278 inlcr=<bool>
2280 inpck=<bool>
2282 intr=<byte>
2284 isig=<bool>
2286 ispeed=<unsigned-int>
2288 Set the baud rate for incoming data on this line.
2289 See also: ospeed, b19200
2290 istrip=<bool>
2292 iuclc=<bool>
2294 ixany=<bool>
2296 ixoff=<bool>
2298 ixon=<bool>
2300 kill=<byte>
2302 lnext=<byte>
2304 min=<byte>
2306 nl0 Sets the newline delay to 0.
2308 nl1
2310 nldly=<bool>
2312 noflsh=<bool>
2314 ocrnl=<bool>
2316 ofdel=<bool>
2318 ofill=<bool>
2320 olcuc=<bool>
2322 onlcr=<bool>
2324 onlret=<bool>
2326 onocr=<bool>
2328 opost=<bool>
2330 Enables or disables output processing; e.g., converts NL to
2331 CR-NL.
2332 ospeed=<unsigned-int>
2334 Set the baud rate for outgoing data on this line.
2335 See also: ispeed, b19200
2336 parenb=<bool>
2338 Enable parity generation on output and parity checking for in‐
2339 put.
2340 parmrk=<bool>
2342 parodd=<bool>
2344 pendin=<bool>
2346 quit=<byte>
2348 reprint=<byte>
2350 sane Brings the terminal to something like a useful default state.
2352 start=<byte>
2354 stop=<byte>
2356 susp=<byte>
2358 swtc=<byte>
2360 tab0
2362 tab1
2364 tab2
2366 tab3
2368 tabdly=<unsigned-int>
2370 time=<byte>
2372 tostop=<bool>
2374 vt0
2376 vt1
2378 vtdly=<bool>
2380 werase=<byte>
2382 xcase=<bool>
2384 xtabs
2386 i-pop-all
2388 With UNIX System V STREAMS, removes all drivers from the stack.
2389 i-push=<string>
2391 With UNIX System V STREAMS, pushes the driver (module) with the
2392 given name (string) onto the stack. For example, to make sure
2393 that a character device on Solaris supports termios etc, use the
2394 following options:
2395 i-pop-all,i-push=ptem,i-push=ldterm,i-push=ttcompat
2396 PTY option group
2399 These options are intended for use with the pty address type.
2401 link=<filename>
2403 Generates a symbolic link that points to the actual pseudo ter‐
2404 minal (pty). This might help to solve the problem that ptys are
2405 generated with more or less unpredictable names, making it dif‐
2406 ficult to directly access the socat generated pty automatically.
2407 With this option, the user can specify a "fix" point in the file
2408 hierarchy that helps him to access the actual pty (example).
2409 Beginning with socat version 1.4.3, the symbolic link is removed
2410 when the address is closed (but see option unlink-close).
2411 wait-slave
2413 Blocks the open phase until a process opens the slave side of
2414 the pty. Usually, socat continues after generating the pty with
2415 opening the next address or with entering the transfer loop.
2416 With the wait-slave option, socat waits until some process opens
2417 the slave side of the pty before continuing. This option only
2418 works if the operating system provides the poll() system call.
2419 And it depends on an undocumented behaviour of pty’s, so it does
2420 not work on all operating systems. It has successfully been
2421 tested on Linux, FreeBSD, NetBSD, and on Tru64 with openpty.
2422 pty-interval=<seconds>
2424 When the wait-slave option is set, socat periodically checks the
2425 HUP condition using poll() to find if the pty’s slave side has
2426 been opened. The default polling interval is 1s. Use the pty-in‐
2427 terval option [timeval] to change this value.
2428 OPENSSL option group
2431 These options apply to the openssl and openssl-listen address types.
2433 cipher=<cipherlist>
2435 Specifies the list of ciphers that may be used for the connec‐
2436 tion. See the man page of ciphers , section CIPHER LIST FORMAT,
2437 for detailed information about syntax, values, and default of
2438 <cipherlist>.
2439 Several cipher strings may be given, separated by ’:’. Some
2440 simple cipher strings:
2441 3DES Uses a cipher suite with triple DES.
2443 MD5 Uses a cipher suite with MD5.
2445 aNULL Uses a cipher suite without authentication.
2447 NULL Does not use encryption.
2449 HIGH Uses a cipher suite with "high" encryption. Note that the peer
2451 must support the selected property, or the negotiation will
2452 fail.
2453 method=<ssl-method>
2455 This option is based on deprecated functions and is only avail‐
2456 able when socat was build with option --with-openssl-method.
2457 Use option min-proto-version and maybe max-proto-version in‐
2458 stead. Sets the protocol version to be used. Valid strings (not
2459 case sensitive) are:
2460 SSL2 Select SSL protocol version 2.
2462 SSL3 Select SSL protocol version 3.
2464 SSL23 Select the best available SSL or TLS protocol.
2466 TLS1 Select TLS protocol version 1.
2468 TLS1.1 Select TLS protocol version 1.1.
2470 TLS1.2 Select TLS protocol version 1.2. When this option is not pro‐
2472 vided OpenSSL negotiates the mothod with its peer.
2473 min-proto-version
2475 This option tells OpenSSL to use this or a later SSL/TLS proto‐
2476 col version and refuses to accept a lower/older protocol. Valid
2477 syntax is:
2478 SSL2 Select SSL protocol version 2.
2480 SSL3 Select SSL protocol version 3.
2482 TLS1
2484 TLS1.0 Select TLS protocol version 1.
2486 TLS1.1 Select TLS protocol version 1.1.
2488 TLS1.2 Select TLS protocol version 1.2.
2490 TLS1.3 Select TLS protocol version 1.3.
2492 openssl-max-proto-version
2494 This option is similar to min-proto-version, however, it disal‐
2495 lows use of a higher protocol version. Useful for testing the
2496 peer.
2497 verify=<bool>
2499 Controls check of the peer’s certificate. Default is 1 (true).
2500 Disabling verify might open your socket for everyone, making the
2501 encryption useless!
2502 cert=<filename>
2504 Specifies the file with the certificate and private key for au‐
2505 thentication. The certificate must be in OpenSSL format
2506 (*.pem). With openssl-listen, use of this option is strongly
2507 recommended. Except with cipher aNULL, "no shared ciphers" error
2508 will occur when no certificate is given.
2509 key=<filename>
2511 Specifies the file with the private key. The private key may be
2512 in this file or in the file given with the cert option. The
2513 party that has to proof that it is the owner of a certificate
2514 needs the private key.
2515 dhparams=<filename>
2517 Specifies the file with the Diffie Hellman parameters. These pa‐
2518 rameters may also be in the file given with the cert option in
2519 which case the dhparams option is not needed.
2520 cafile=<filename>
2522 Specifies the file with the trusted (root) authority certifi‐
2523 cates. The file must be in PEM format and should contain one or
2524 more certificates. The party that checks the authentication of
2525 its peer trusts only certificates that are in this file.
2526 capath=<dirname>
2528 Specifies the directory with the trusted (root) certificates.
2529 The directory must contain certificates in PEM format and their
2530 hashes (see OpenSSL documentation)
2531 egd=<filename>
2533 On some systems, openssl requires an explicit source of random
2534 data. Specify the socket name where an entropy gathering daemon
2535 like egd provides random data, e.g. /dev/egd-pool.
2536 pseudo On systems where openssl cannot find an entropy source and where
2538 no entropy gathering daemon can be utilized, this option acti‐
2539 vates a mechanism for providing pseudo entropy. This is achieved
2540 by taking the current time in microseconds for feeding the libc
2541 pseudo random number generator with an initial value. openssl is
2542 then feeded with output from random() calls.
2543 NOTE:This mechanism is not sufficient for generation of secure
2544 keys!
2545 compress
2547 Enable or disable the use of compression for a connection. Set‐
2548 ting this to "none" disables compression, setting it to "auto"
2549 lets OpenSSL choose the best available algorithm supported by
2550 both parties. The default is to not touch any compression-re‐
2551 lated settings. NOTE: Requires OpenSSL 0.9.8 or higher and dis‐
2552 abling compression with OpenSSL 0.9.8 affects all new connec‐
2553 tions in the process.
2554 commonname=<string>
2556 Specify the commonname that the peer certificate must match.
2557 With OPENSSL-CONNECT address this overrides the given hostname
2558 or IP target address; with OPENSSL-LISTEN this turns on check of
2559 peer certificates commonname. This option has only meaning when
2560 option verify is not disabled and the chosen cipher provides a
2561 peer certificate.
2562 no-sni=<bool>
2564 Do not use the client side Server Name Indication (SNI) feature
2565 that selects the desired server certificate.
2566 Note: SNI is automatically used since socat version 1.7.4.0 and
2567 uses commonname or the given host name.
2568 snihost=<string>
2570 Set the client side Server Name Indication (SNI) host name dif‐
2571 ferent from the addressed server name or common name. This might
2572 be useful when the server certificate has multiple host names or
2573 wildcard names because the SNI host name is passed in cleartext
2574 to the server and might be eavesdropped; with this option a mock
2575 name of the desired certificate may be transferred.
2576 fips Enables FIPS mode if compiled in. For info about the FIPS en‐
2578 cryption implementation standard see http://oss-insti‐
2579 tute.org/fips-faq.html. This mode might require that the in‐
2580 volved certificates are generated with a FIPS enabled version of
2581 openssl. Setting or clearing this option on one socat address
2582 affects all OpenSSL addresses of this process.
2583 RETRY option group
2586 Options that control retry of some system calls, especially connection
2588 attempts.
2589 retry=<num>
2591 Number of retries before the connection or listen attempt is
2592 aborted. Default is 0, which means just one attempt.
2593 interval=<timespec>
2595 Time between consecutive attempts (seconds, [timespec]). Default
2596 is 1 second.
2597 forever
2599 Performs an unlimited number of retry attempts.
2600 TUN option group
2603 Options that control Linux TUN/TAP interface device addresses.
2605 tun-device=<device-file>
2607 Instructs socat to take another path for the TUN clone device.
2608 Default is /dev/net/tun.
2609 tun-name=<if-name>
2611 Gives the resulting network interface a specific name instead of
2612 the system generated (tun0, tun1, etc.)
2613 tun-type=[tun|tap]
2615 Sets the type of the TUN device; use this option to generate a
2616 TAP device. See the Linux docu for the difference between these
2617 types. When you try to establish a tunnel between two TUN de‐
2618 vices, their types should be the same.
2619 iff-no-pi
2621 Sets the IFF_NO_PI flag which controls if the device includes
2622 additional packet information in the tunnel. When you try to
2623 establish a tunnel between two TUN devices, these flags should
2624 have the same values.
2625 iff-up Sets the TUN network interface status UP. Strongly recommended.
2627 iff-broadcast
2629 Sets the BROADCAST flag of the TUN network interface.
2630 iff-debug
2632 Sets the DEBUG flag of the TUN network interface.
2633 iff-loopback
2635 Sets the LOOPBACK flag of the TUN network interface.
2636 iff-pointopoint
2638 Sets the POINTOPOINT flag of the TUN device.
2639 iff-notrailers
2641 Sets the NOTRAILERS flag of the TUN device.
2642 iff-running
2644 Sets the RUNNING flag of the TUN device.
2645 iff-noarp
2647 Sets the NOARP flag of the TUN device.
2648 iff-promisc
2650 Sets the PROMISC flag of the TUN device.
2651 iff-allmulti
2653 Sets the ALLMULTI flag of the TUN device.
2654 iff-master
2656 Sets the MASTER flag of the TUN device.
2657 iff-slave
2659 Sets the SLAVE flag of the TUN device.
2660 iff-multicast
2662 Sets the MULTICAST flag of the TUN device.
2663 iff-portsel
2665 Sets the PORTSEL flag of the TUN device.
2666 iff-automedia
2668 Sets the AUTOMEDIA flag of the TUN device.
2669 iff-dynamic
2671 Sets the DYNAMIC flag of the TUN device.
2672
2675 This section explains the different data types that address parameters
2676 and address options can take.
2677 address-range
2679 Is currently only implemented for IPv4 and IPv6. See address-op‐
2680 tion `range’
2681 bool "0" or "1"; if value is omitted, "1" is taken.
2683 byte An unsigned int number, read with strtoul() , lower or equal to
2685 UCHAR_MAX .
2686 command-line
2688 A string specifying a program name and its arguments, separated
2689 by single spaces.
2690 data This is a more general data specification. The given text string
2692 contains information about the target data type and value. Gen‐
2693 erally a leading character specifies the type of the following
2694 data item. In its specific context a default data type may ex‐
2695 ist.
2696 Currently only the following specifications are implemented:
2697 i A signed integer number, stored in host byte order.
2699 Example: i-1000 (Integer number -1000)
2700 I An unsigned integer number, stored in host byte order.
2702 l A signed long integer number, stored in host byte order.
2704 L An unsigned long integer number, stored in host byte order.
2706 s A signed short integer number, stored in host byte order.
2708 S An unsigned short integer number, stored in host byte order.
2710 b A signed byte (signed char).
2712 B An unsigned byte (unsigned char).
2714 x Following is an even number of hex digits, stored as sequence of
2716 bytes.
2717 Example: x7f000001 (IP address 127.0.0.1)
2718 " Following is a string that is used with the common conversions
2720 \n \r \t \f \b \a \e \0; the string must be closed with ’"’.
2721 Please note that the quotes and backslashes need to be escaped
2722 from shell and socat conversion.
2723 Example: "Hello world!\n"
2724 ’ A single char, with the usual conversions. Please note that the
2726 quotes and backslashes need to be escaped from shell and socat
2727 conversion.
2728 Example: ’a’ Data items may be separated with white space
2729 without need to repeat the type specifier again.
2730 directory
2732 A string with usual UN*X directory name semantics.
2733 facility
2735 The name of a syslog facility in lower case characters.
2736 fdnum An unsigned int type, read with strtoul() , specifying a UN*X
2738 file descriptor.
2739 filename
2741 A string with usual UN*X filename semantics.
2742 group If the first character is a decimal digit, the value is read
2744 with strtoul() as unsigned integer specifying a group id. Other‐
2745 wise, it must be an existing group name.
2746 int A number following the rules of the strtol() function with base
2748 "0", i.e. decimal number, octal number with leading "0", or
2749 hexadecimal number with leading "0x". The value must fit into a
2750 C int.
2751 interface
2753 A string specifying the device name of a network interface as
2754 shown by ifconfig or procan, e.g. "eth0".
2755 IP address
2757 An IPv4 address in numbers-and-dots notation, an IPv6 address in
2758 hex notation enclosed in brackets, or a hostname that resolves
2759 to an IPv4 or an IPv6 address.
2760 Examples: 127.0.0.1, [::1], www.dest-unreach.org, dns1
2761 IPv4 address
2763 An IPv4 address in numbers-and-dots notation or a hostname that
2764 resolves to an IPv4 address.
2765 Examples: 127.0.0.1, www.dest-unreach.org, dns2
2766 IPv6 address
2768 An IPv6 address in hexnumbers-and-colons notation enclosed in
2769 brackets, or a hostname that resolves to an IPv6 address.
2770 Examples: [::1], [1234:5678:9abc:def0:1234:5678:9abc:def0],
2771 ip6name.domain.org
2772 long A number read with strtol() . The value must fit into a C long.
2774 long long
2776 A number read with strtoll() . The value must fit into a C long
2777 long.
2778 off_t An implementation dependend signed number, usually 32 bits, read
2780 with strtol or strtoll.
2781 off64_t
2783 An implementation dependend signed number, usually 64 bits, read
2784 with strtol or strtoll.
2785 mode_t An unsigned integer, read with strtoul() , specifying mode (per‐
2787 mission) bits.
2788 pid_t A number, read with strtol() , specifying a process id.
2790 port A uint16_t (16 bit unsigned number) specifying a TCP or UDP
2792 port, read with strtoul() .
2793 protocol
2795 An unsigned 8 bit number, read with strtoul() .
2796 size_t An unsigned number with size_t limitations, read with strtoul .
2798 sockname
2800 A socket address. See address-option `bind’
2801 string A sequence of characters, not containing ’\0’ and, depending on
2803 the position within the command line, ’:’, ’,’, or "!!". Note
2804 that you might have to escape shell meta characters in the com‐
2805 mand line.
2806 TCP service
2808 A service name, not starting with a digit, that is resolved by
2809 getservbyname() , or an unsigned int 16 bit number read with
2810 strtoul() .
2811 timeval
2813 A double float specifying seconds; the number is mapped into a
2814 struct timeval, consisting of seconds and microseconds.
2815 timespec
2817 A double float specifying seconds; the number is mapped into a
2818 struct timespec, consisting of seconds and nanoseconds.
2819 UDP service
2821 A service name, not starting with a digit, that is resolved by
2822 getservbyname() , or an unsigned int 16 bit number read with
2823 strtoul() .
2824 unsigned int
2826 A number read with strtoul() . The value must fit into a C un‐
2827 signed int.
2828 user If the first character is a decimal digit, the value is read
2830 with strtoul() as unsigned integer specifying a user id. Other‐
2831 wise, it must be an existing user name.
2832 VSOCK cid
2834 A uint32_t (32 bit unsigned number) specifying a VSOCK Context
2835 Identifier (CID), read with strtoul() . There are several spe‐
2836 cial addresses: VMADDR_CID_ANY (-1U) means any address for bind‐
2837 ing; VMADDR_CID_HOST (2) is the well-known address of the host.
2838 VSOCK port
2840 A uint32_t (32 bit unsigned number) specifying a VSOCK port,
2841 read with strtoul() .
2842
2845 socat - TCP4:www.domain.org:80
2846 transfers data between STDIO (-) and a TCP4 connection to port
2849 80 of host www.domain.org. This example results in an interac‐
2850 tive connection similar to telnet or netcat. The stdin terminal
2851 parameters are not changed, so you may close the relay with ^D
2852 or abort it with ^C.
2853 socat -d -d READLINE,history=$HOME/.http_history \
2855 TCP4:www.domain.org:www,crnl
2856 this is similar to the previous example, but you can edit the
2858 current line in a bash like manner (READLINE) and use the his‐
2859 tory file .http_history; socat prints messages about progress
2860 (-d -d). The port is specified by service name (www), and cor‐
2861 rect network line termination characters (crnl) instead of NL
2862 are used.
2863 socat TCP4-LISTEN:www TCP4:www.domain.org:www
2865 installs a simple TCP port forwarder. With TCP4-LISTEN it lis‐
2868 tens on local port "www" until a connection comes in, accepts
2869 it, then connects to the remote host (TCP4) and starts data
2870 transfer. It will not accept a second connection.
2871 socat -d -d -lmlocal2 \
2873 TCP4-LISTEN:80,bind=myaddr1,reuseaddr,fork,su=nobody,range=10.0.0.0/8 \
2874 TCP4:www.domain.org:80,bind=myaddr2
2875 TCP port forwarder, each side bound to another local IP address
2877 (bind). This example handles an almost arbitrary number of par‐
2878 allel or consecutive connections by fork’ing a new process after
2879 each accept() . It provides a little security by su’ing to user
2880 nobody after forking; it only permits connections from the pri‐
2881 vate 10 network (range); due to reuseaddr, it allows immediate
2882 restart after master process’s termination, even if some child
2883 sockets are not completely shut down. With -lmlocal2, socat
2884 logs to stderr until successfully reaching the accept loop. Fur‐
2885 ther logging is directed to syslog with facility local2.
2886 socat TCP4-LISTEN:5555,fork,tcpwrap=script \
2888 EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr
2889 a simple server that accepts connections (TCP4-LISTEN) and
2891 fork’s a new child process for each connection; every child acts
2892 as single relay. The client must match the rules for daemon
2893 process name "script" in /etc/hosts.allow and /etc/hosts.deny,
2894 otherwise it is refused access (see "man 5 hosts_access"). For
2895 EXEC’uting the program, the child process chroot’s to
2896 /home/sandbox, su’s to user sandbox, and then starts the program
2897 /home/sandbox/bin/myscript. Socat and myscript communicate via a
2898 pseudo tty (pty); myscript’s stderr is redirected to stdout, so
2899 its error messages are transferred via socat to the connected
2900 client.
2901 socat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \
2903 TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512
2904 mail.sh is a shell script, distributed with socat, that imple‐
2906 ments a simple SMTP client. It is programmed to "speak" SMTP on
2907 its FDs 3 (in) and 4 (out). The fdin and fdout options tell so‐
2908 cat to use these FDs for communication with the program. Because
2909 mail.sh inherits stdin and stdout while socat does not use them,
2910 the script can read a mail body from stdin. Socat makes alias1
2911 your local source address (bind), cares for correct network line
2912 termination (crnl) and sends at most 512 data bytes per packet
2913 (mss).
2914 socat -,escape=0x0f /dev/ttyS0,rawer,crnl
2916 opens an interactive connection via the serial line, e.g. for
2919 talking with a modem. rawer sets the console’s and ttyS0’s ter‐
2920 minal parameters to practicable values, crnl converts to correct
2921 newline characters. escape allows terminating the socat process
2922 with character control-O. Consider using READLINE instead of
2923 the first address.
2924 socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
2926 SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20
2927 with UNIX-LISTEN, socat opens a listening UNIX domain socket
2929 /tmp/.X11-unix/X1. This path corresponds to local XWindow dis‐
2930 play :1 on your machine, so XWindow client connections to DIS‐
2931 PLAY=:1 are accepted. Socat then speaks with the SOCKS4 server
2932 host.victim.org that might permit sourceport 20 based connec‐
2933 tions due to an FTP related weakness in its static IP filters.
2934 Socat pretends to be invoked by socksuser nobody, and requests
2935 to be connected to loopback port 6000 (only weak sockd configu‐
2936 rations will allow this). So we get a connection to the victims
2937 XWindow server and, if it does not require MIT cookies or Ker‐
2938 beros authentication, we can start work. Please note that there
2939 can only be one connection at a time, because TCP can establish
2940 only one session with a given set of addresses and ports.
2941 socat -u /tmp/readdata,seek-end=0,ignoreeof -
2943 this is an example for unidirectional data transfer (-u). Socat
2946 transfers data from file /tmp/readdata (implicit address GOPEN),
2947 starting at its current end (seek-end=0 lets socat start reading
2948 at current end of file; use seek=0 or no seek option to first
2949 read the existing data) in a "tail -f" like mode (ignoreeof).
2950 The "file" might also be a listening UNIX domain socket (do not
2951 use a seek option then).
2952 (sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |
2954 socat - EXEC:'ssh -l user server',pty,setsid,ctty
2955 EXEC’utes an ssh session to server. Uses a pty for communication
2957 between socat and ssh, makes it ssh’s controlling tty (ctty),
2958 and makes this pty the owner of a new process group (setsid), so
2959 ssh accepts the password from socat.
2960 socat -u TCP4-LISTEN:3334,reuseaddr,fork \
2962 OPEN:/tmp/in.log,creat,append
2963 implements a simple network based message collector. For each
2965 client connecting to port 3334, a new child process is generated
2966 (option fork). All data sent by the clients are append’ed to
2967 the file /tmp/in.log. If the file does not exist, socat creat’s
2968 it. Option reuseaddr allows immediate restart of the server
2969 process.
2970 socat READLINE,noecho=’[Pp]assword:’ EXEC:’ftp ftp.server.com’,pty,set‐
2972 sid,ctty
2973 wraps a command line history (READLINE) around the EXEC’uted ftp
2976 client utility. This allows editing and reuse of FTP commands
2977 for relatively comfortable browsing through the ftp directory
2978 hierarchy. The password is echoed! pty is required to have ftp
2979 issue a prompt. Nevertheless, there may occur some confusion
2980 with the password and FTP prompts.
2981 socat PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \
2983 EXEC:"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"
2984 generates a pseudo terminal device (PTY) on the client that can
2986 be reached under the symbolic link $HOME/dev/vmodem0. An appli‐
2987 cation that expects a serial line or modem can be configured to
2988 use $HOME/dev/vmodem0; its traffic will be directed to a modem‐
2989 server via ssh where another socat instance links it to
2990 /dev/ttyS0.
2991 socat TCP4-LISTEN:2022,reuseaddr,fork \
2993 PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass
2994 starts a forwarder that accepts connections on port 2022, and
2996 directs them through the proxy daemon listening on port 3128
2997 (proxyport) on host proxy, using the CONNECT method, where they
2998 are authenticated as "user" with "pass" (proxyauth). The proxy
2999 should establish connections to host www.domain.org on port 22
3000 then.
3001 socat - SSL:server:4443,cafile=server.crt,cert=client.pem
3003 is an OpenSSL client that tries to establish a secure connection
3006 to an SSL server. Option cafile specifies a file that contains
3007 trust certificates: we trust the server only when it presents
3008 one of these certificates and proofs that it owns the related
3009 private key. Otherwise the connection is terminated. With cert
3010 a file containing the client certificate and the associated pri‐
3011 vate key is specified. This is required in case the server
3012 wishes a client authentication; many Internet servers do not.
3013 The first address (’-’) can be replaced by almost any other so‐
3014 cat address.
3015 socat OPENSSL-LISTEN:4443,reuse‐
3017 addr,pf=ip4,fork,cert=server.pem,cafile=client.crt PIPE
3018 is an OpenSSL server that accepts TCP connections, presents the
3021 certificate from the file server.pem and forces the client to
3022 present a certificate that is verified against cafile.crt.
3023 The second address (’PIPE’) can be replaced by almost any other
3024 socat address.
3025 For instructions on generating and distributing OpenSSL keys and
3026 certificates see the additional socat docu socat-openssl.txt.
3027 echo |socat -u - file:/tmp/bigfile,create,largefile,seek=100000000000
3029 creates a 100GB sparse file; this requires a file system type
3032 that supports this (ext2, ext3, reiserfs, jfs; not minix, vfat).
3033 The operation of writing 1 byte might take long (reiserfs: some
3034 minutes; ext2: "no" time), and the resulting file can consume
3035 some disk space with just its inodes (reiserfs: 2MB; ext2:
3036 16KB).
3037 socat tcp-l:7777,reuseaddr,fork system:’filan -i 0 -s >&2’,nofork
3039 listens for incoming TCP connections on port 7777. For each ac‐
3042 cepted connection, invokes a shell. This shell has its stdin and
3043 stdout directly connected to the TCP socket (nofork). The shell
3044 starts filan and lets it print the socket addresses to stderr
3045 (your terminal window).
3046 echo -e "\0\14\0\0\c" |socat -u -
3048 file:/usr/bin/squid.exe,seek=0x00074420
3049 functions as primitive binary editor: it writes the 4 bytes 000
3052 014 000 000 to the executable /usr/bin/squid at offset
3053 0x00074420 (this is a real world patch to make the squid exe‐
3054 cutable from Cygwin run under Windows, actual per May 2004).
3055 socat - tcp:www.blackhat.org:31337,readbytes=1000
3057 connects to an unknown service and prevents being flooded.
3060 socat -U TCP:target:9999,end-close TCP-L:8888,reuseaddr,fork
3062 merges data arriving from different TCP streams on port 8888 to
3065 just one stream to target:9999. The end-close option prevents
3066 the child processes forked off by the second address from termi‐
3067 nating the shared connection to 9999 (close(2) just unlinks the
3068 inode which stays active as long as the parent process lives;
3069 shutdown(2) would actively terminate the connection).
3070 socat - UDP4-DATAGRAM:192.168.1.0:123,sp=123,broad‐
3072 cast,range=192.168.1.0/24
3073 sends a broadcast to the network 192.168.1.0/24 and receives the
3076 replies of the timeservers there. Ignores NTP packets from hosts
3077 outside this network.
3078 socat - SOCKET-DATA‐
3080 GRAM:2:2:17:x007bxc0a80100x0000000000000000,bind=x007bx00000000x0000000000000000,set‐
3081 sock‐
3082 opt-int=1:6:1,range=x0000xc0a80100x0000000000000000:x0000xffffff00x0000000000000000
3083 is semantically equivalent to the previous example, but all pa‐
3086 rameters are specified in generic form. the value 6 of setsock‐
3087 opt-int is the Linux value for SO_BROADCAST.
3088 socat - IP4-DATAGRAM:255.255.255.255:44,broadcast,range=10.0.0.0/8
3090 sends a broadcast to the local network(s) using protocol 44. Ac‐
3093 cepts replies from the private address range only.
3094 socat - UDP4-DATAGRAM:224.255.0.1:6666,bind=:6666,ip-add-member‐
3096 ship=224.255.0.1:eth0
3097 transfers data from stdin to the specified multicast address us‐
3100 ing UDP. Both local and remote ports are 6666. Tells the inter‐
3101 face eth0 to also accept multicast packets of the given group.
3102 Multiple hosts on the local network can run this command, so all
3103 data sent by any of the hosts will be received by all the other
3104 ones. Note that there are many possible reasons for failure, in‐
3105 cluding IP-filters, routing issues, wrong interface selection by
3106 the operating system, bridges, or a badly configured switch.
3107 socat UDP:host2:4443 TUN:192.168.255.1/24,up
3109 establishes one side of a virtual (but not private!) network
3112 with host2 where a similar process might run, with UDP-L and tun
3113 address 192.168.255.2. They can reach each other using the ad‐
3114 dresses 192.168.255.1 and 192.168.255.2. Note that streaming
3115 eg.via TCP or SSL does not guarantee to retain packet boundaries
3116 and might thus cause packet loss.
3117 socat - VSOCK-CONNECT:2:1234
3119 establishes a VSOCK connection with the host (host is always
3122 reachable with the well-know CID=2) on 1234 port.
3123 socat - VSOCK-LISTEN:1234
3125 listens for a VSOCK connection on 1234 port.
3128 socat - VSOCK-CONNECT:31:4321,bind:5555
3130 establishes a VSOCK connection with the guest that have CID=31
3133 on 1234 port, binding the local socket to the 5555 port.
3134 socat VSOCK-LISTEN:3333,reuseaddr,fork VSOCK-CONNECT:42,3333
3136 starts a forwarder that accepts VSOCK connections on port 3333,
3139 and directs them to the guest with CID=42 on the same port.
3140 socat VSOCK-LISTEN:22,reuseaddr,fork TCP:localhost:22
3142 forwards VSOCK connections from 22 port to the local SSH server.
3145 Running this in a VM allows you to connect via SSH from the host
3146 using VSOCK, as in the example below.
3147 socat TCP4-LISTEN:22222,reuseaddr,fork VSOCK-CONNECT:33:22
3149 forwards TCP connections from 22222 port to the guest with
3152 CID=33 listening on VSOCK port 22. Running this in the host,
3153 allows you to connect via SSH running "ssh -p 22222 user@local‐
3154 host", if the guest runs the example above.
3155 socat PTY,link=/var/run/ppp,rawer INTERFACE:hdlc0
3157 circumvents the problem that pppd requires a serial device and
3160 thus might not be able to work on a synchronous line that is
3161 represented by a network device. socat creates a PTY to make
3162 pppd happy, binds to the network interface hdlc0, and can trans‐
3163 fer data between both devices. Use pppd on device /var/run/ppp
3164 then.
3165 socat -T 1 -d -d TCP-L:10081,reuseaddr,fork,crlf SYSTEM:"echo -e
3167 \"\\\"HTTP/1.0 200 OK\\\nDocumentType: text/plain\\\n\\\ndate:
3168 \$\(date\)\\\nserver:\$SOCAT_SOCKADDR:\$SOCAT_SOCKPORT\\\nclient: \$SO‐
3169 CAT_PEERADDR:\$SOCAT_PEERPORT\\\n\\\"\"; cat; echo -e \"\\\"\\\n\\\"\""
3170 creates a simple HTTP echo server: each HTTP client that con‐
3173 nects gets a valid HTTP reply that contains information about
3174 the client address and port as it is seen by the server host,
3175 the host address (which might vary on multihomed servers), and
3176 the original client request.
3177 socat -d -d UDP4-RECVFROM:9999,so-broadcast,so-timestamp,ip-pkt‐
3179 info,ip-recverr,ip-recvopts,ip-recvtos,ip-recvttl!!- SYSTEM:’export;
3180 sleep 1’ |grep SOCAT
3181 waits for an incoming UDP packet on port 9999 and prints the en‐
3184 vironment variables provided by socat. On BSD based systems you
3185 have to replace ip-pktinfo with ip-recvdstaddr,ip-recvif. Espe‐
3186 cially interesting is SOCAT_IP_DSTADDR: it contains the target
3187 address of the packet which may be a unicast, multicast, or
3188 broadcast address.
3189 echo -e "M-SEARCH * HTTP/1.1\nHOST: 239.255.255.250:1900\nMAN:
3191 \"ssdp:discover\"\nMX: 4\nST: \"ssdp:all\"\n" |socat - UDP-DATA‐
3192 GRAM:239.255.255.250:1900,crlf
3193 sends an SSDP (Simple Service Discovery Protocol) query to the
3196 local network and collects and outputs the answers received.
3197
3202 Socat uses a logging mechanism that allows filtering messages by sever‐
3203 ity. The severities provided are more or less compatible to the appro‐
3204 priate syslog priority. With one or up to four occurrences of the -d
3205 command line option, the lowest priority of messages that are issued
3206 can be selected. Each message contains a single uppercase character
3207 specifying the messages severity (one of F, E, W, N, I, or D)
3208 FATAL: Conditions that require unconditional and immediate program ter‐
3210 mination.
3211 ERROR: Conditions that prevent proper program processing. Usually the
3213 program is terminated (see option -s).
3214 WARNING:
3216 Something did not function correctly or is in a state where cor‐
3217 rect further processing cannot be guaranteed, but might be pos‐
3218 sible.
3219 NOTICE:
3221 Interesting actions of the program, e.g. for supervising socat
3222 in some kind of server mode.
3223 INFO: Description of what the program does, and maybe why it happens.
3225 Allows monitoring the lifecycles of file descriptors.
3226 DEBUG: Description of how the program works, all system or library
3228 calls and their results.
3229 Log messages can be written to stderr, to a file, or to syslog.
3232 On exit, socat gives status 0 if it terminated due to EOF or inactivity
3234 timeout, with a positive value on error, and with a negative value on
3235 fatal error.
3236
3238 /usr/bin/socat
3239 /usr/bin/filan
3240 /usr/bin/procan
3241
3243 Input variables carry information from the environment to socat, output
3244 variables are set by socat for use in executed scripts and programs.
3245 In the output variables beginning with "SOCAT" this prefix is actually
3247 replaced by the upper case name of the executable or the value of op‐
3248 tion -lp.
3249 SOCAT_DEFAULT_LISTEN_IP (input)
3251 (Values 4 or 6) Sets the IP version to be used for listen, recv,
3252 and recvfrom addresses if no pf (protocol-family) option is
3253 given. Is overridden by socat options -4 or -6.
3254 SOCAT_PREFERRED_RESOLVE_IP (input)
3256 (Values 0, 4, or 6) Sets the IP version to be used when resolv‐
3257 ing target host names when version is not specified by address
3258 type, option pf (protocol-family), or address format. If name
3259 resolution does not return a matching entry, the first result
3260 (with differing IP version) is taken. With value 0, socat always
3261 selects the first record and its IP version.
3262 SOCAT_FORK_WAIT (input)
3264 Specifies the time (seconds) to sleep the parent and child pro‐
3265 cesses after successful fork(). Useful for debugging.
3266 SOCAT_VERSION (output)
3268 Socat sets this variable to its version string, e.g. "1.7.0.0"
3269 for released versions or e.g. "1.6.0.1+envvar" for temporary
3270 versions; can be used in scripts invoked by socat.
3271 SOCAT_PID (output)
3273 Socat sets this variable to its process id. In case of fork ad‐
3274 dress option, SOCAT_PID gets the child processes id. Forking for
3275 exec and system does not change SOCAT_PID.
3276 SOCAT_PPID (output)
3278 Socat sets this variable to its process id. In case of fork, SO‐
3279 CAT_PPID keeps the pid of the master process.
3280 SOCAT_PEERADDR (output)
3282 With passive socket addresses (all LISTEN and RECVFROM ad‐
3283 dresses), this variable is set to a string describing the peers
3284 socket address. Port information is not included.
3285 SOCAT_PEERPORT (output)
3287 With appropriate passive socket addresses (TCP, UDP, and SCTP -
3288 LISTEN and RECVFROM), this variable is set to a string contain‐
3289 ing the number of the peer port.
3290 SOCAT_SOCKADDR (output)
3292 With all LISTEN addresses, this variable is set to a string de‐
3293 scribing the local socket address. Port information is not in‐
3294 cluded example
3295 SOCAT_SOCKPORT (output)
3297 With TCP-LISTEN, UDP-LISTEN, and SCTP-LISTEN addresses, this
3298 variable is set to the local port.
3299 SOCAT_TIMESTAMP (output)
3301 With all RECVFROM addresses where address option so-timestamp is
3302 applied, socat sets this variable to the resulting timestamp.
3303 SOCAT_IP_OPTIONS (output)
3305 With all IPv4 based RECVFROM addresses where address option
3306 ip-recvopts is applied, socat fills this variable with the IP
3307 options of the received packet.
3308 SOCAT_IP_DSTADDR (output)
3310 With all IPv4 based RECVFROM addresses where address option
3311 ip-recvdstaddr (BSD) or ip-pktinfo (other platforms) is applied,
3312 socat sets this variable to the destination address of the re‐
3313 ceived packet. This is particularly useful to identify broadcast
3314 and multicast addressed packets.
3315 SOCAT_IP_IF (output)
3317 With all IPv4 based RECVFROM addresses where address option
3318 ip-recvif (BSD) or ip-pktinfo (other platforms) is applied, so‐
3319 cat sets this variable to the name of the interface where the
3320 packet was received.
3321 SOCAT_IP_LOCADDR (output)
3323 With all IPv4 based RECVFROM addresses where address option
3324 ip-pktinfo is applied, socat sets this variable to the address
3325 of the interface where the packet was received.
3326 SOCAT_IP_TOS (output)
3328 With all IPv4 based RECVFROM addresses where address option
3329 ip-recvtos is applied, socat sets this variable to the TOS (type
3330 of service) of the received packet.
3331 SOCAT_IP_TTL (output)
3333 With all IPv4 based RECVFROM addresses where address option
3334 ip-recvttl is applied, socat sets this variable to the TTL (time
3335 to live) of the received packet.
3336 SOCAT_IPV6_HOPLIMIT (output)
3338 With all IPv6 based RECVFROM addresses where address option
3339 ipv6-recvhoplimit is applied, socat sets this variable to the
3340 hoplimit value of the received packet.
3341 SOCAT_IPV6_DSTADDR (output)
3343 With all IPv6 based RECVFROM addresses where address option
3344 ipv6-recvpktinfo is applied, socat sets this variable to the
3345 destination address of the received packet.
3346 SOCAT_IPV6_TCLASS (output)
3348 With all IPv6 based RECVFROM addresses where address option
3349 ipv6-recvtclass is applied, socat sets this variable to the
3350 transfer class of the received packet.
3351 SOCAT_OPENSSL_X509_ISSUER (output)
3353 Issuer field from peer certificate
3354 SOCAT_OPENSSL_X509_SUBJECT (output)
3356 Subject field from peer certificate
3357 SOCAT_OPENSSL_X509_COMMONNAME (output)
3359 commonName entries from peer certificates subject. Multiple val‐
3360 ues are separated by " // ".
3361 SOCAT_OPENSSL_X509_* (output)
3363 all other entries from peer certificates subject
3364 SOCAT_OPENSSL_X509V3_DNS (output)
3366 DNS entries from peer certificates extensions - subjectAltName
3367 field. Multiple values are separated by " // ".
3368 HOSTNAME (input)
3370 Is used to determine the hostname for logging (see -lh).
3371 LOGNAME (input)
3373 Is used as name for the socks client user name if no socksuser
3374 is given.
3375 With options su and su-d, LOGNAME is set to the given user name.
3376 USER (input)
3378 Is used as name for the socks client user name if no socksuser
3379 is given and LOGNAME is empty.
3380 With options su and su-d, USER is set to the given user name.
3381 SHELL (output)
3383 With options su and su-d, SHELL is set to the login shell of the
3384 given user.
3385 PATH (output)
3387 Can be set with option path for exec and system addresses.
3388 HOME (output)
3390 With options su and su-d, HOME is set to the home directory of
3391 the given user.
3392
3394 The work of the following groups and organizations was invaluable for
3395 this project:
3396 The FSF (GNU, http://www.fsf.org/) project with their free and portable
3398 development software and lots of other useful tools and libraries.
3399 The Linux developers community (http://www.linux.org/) for providing a
3401 free, open source operating system.
3402 The Open Group (http://www.unix-systems.org/) for making their standard
3404 specifications available on the Internet for free.
3405
3407 This man page describes version 1.7.4 of socat.
3408
3410 Addresses cannot be nested, so a single socat process cannot, e.g.,
3411 drive ssl over socks.
3412 Address option ftruncate without value uses default 1 instead of 0.
3414 Verbose modes (-x and/or -v) display line termination characters incon‐
3416 sistently when address options cr or crnl are used: They show the data
3417 after conversion in either direction.
3418 The data transfer blocksize setting (-b) is ignored with address read‐
3420 line.
3421 Send bug reports to <socat@dest-unreach.org>
3423
3425 nc(1), rinetd(8), openssl(1), stunnel(8), rlwrap(1), setsid(1)
3426 Socat home page http://www.dest-unreach.org/socat/
3428
3430 Gerhard Rieger <rieger@dest-unreach.org> and contributors
3431 socat(1)