1socat(1) socat(1)
2
6 socat - Multipurpose relay (SOcket CAT)
7
9 socat [options] <address> <address>
10 socat -V
11 socat -h[h[h]] | -?[?[?]]
12 filan
13 procan
14
16 Socat is a command line based utility that establishes two bidirec‐
17 tional byte streams and transfers data between them. Because the
18 streams can be constructed from a large set of different types of data
19 sinks and sources (see address types), and because lots of address
20 options may be applied to the streams, socat can be used for many dif‐
21 ferent purposes.
22 Filan is a utility that prints information about its active file
24 descriptors to stdout. It has been written for debugging socat, but
25 might be useful for other purposes too. Use the -h option to find more
26 infos.
27 Procan is a utility that prints information about process parameters to
29 stdout. It has been written to better understand some UNIX process
30 properties and for debugging socat, but might be useful for other pur‐
31 poses too.
32 The life cycle of a socat instance typically consists of four phases.
34 In the init phase, the command line options are parsed and logging is
36 initialized.
37 During the open phase, socat opens the first address and afterwards the
39 second address. These steps are usually blocking; thus, especially for
40 complex address types like socks, connection requests or authentication
41 dialogs must be completed before the next step is started.
42 In the transfer phase, socat watches both streams’ read and write file
44 descriptors via select() , and, when data is available on one side and
45 can be written to the other side, socat reads it, performs newline
46 character conversions if required, and writes the data to the write
47 file descriptor of the other stream, then continues waiting for more
48 data in both directions.
49 When one of the streams effectively reaches EOF, the closing phase
51 begins. Socat transfers the EOF condition to the other stream, i.e.
52 tries to shutdown only its write stream, giving it a chance to termi‐
53 nate gracefully. For a defined time socat continues to transfer data in
54 the other direction, but then closes all remaining channels and termi‐
55 nates.
56
58 Socat provides some command line options that modify the behaviour of
59 the program. They have nothing to do with so called address options
60 that are used as parts of address specifications.
61 -V Print version and available feature information to stdout, and
63 exit.
64 -h | -?
66 Print a help text to stdout describing command line options and
67 available address types, and exit.
68 -hh | -??
70 Like -h, plus a list of the short names of all available address
71 options. Some options are platform dependend, so this output is
72 helpful for checking the particular implementation.
73 -hhh | -???
75 Like -hh, plus a list of all available address option names.
76 -d Without this option, only fatal and error messages are gener‐
78 ated; applying this option also prints warning messages. See
79 DIAGNOSTICS for more information.
80 -d -d Prints fatal, error, warning, and notice messages.
82 -d -d -d
84 Prints fatal, error, warning, notice, and info messages.
85 -d -d -d -d
87 Prints fatal, error, warning, notice, info, and debug messages.
88 -D Logs information about file descriptors before starting the
90 transfer phase.
91 -ly[<facility>]
93 Writes messages to syslog instead of stderr; severity as defined
94 with -d option. With optional <facility>, the syslog type can be
95 selected, default is "daemon". Third party libraries might not
96 obey this option.
97 -lf <logfile>
99 Writes messages to <logfile> [filename] instead of stderr. Some
100 third party libraries, in particular libwrap, might not obey
101 this option.
102 -ls Writes messages to stderr (this is the default). Some third
104 party libraries might not obey this option, in particular lib‐
105 wrap appears to only log to syslog.
106 -lp<progname>
108 Overrides the program name printed in error messages and used
109 for constructing environment variable names.
110 -lu Extends the timestamp of error messages to microsecond resolu‐
112 tion. Does not work when logging to syslog.
113 -lm[<facility>]
115 Mixed log mode. During startup messages are printed to stderr;
116 when socat starts the transfer phase loop or daemon mode (i.e.
117 after opening all streams and before starting data transfer, or,
118 with listening sockets with fork option, before the first accept
119 call), it switches logging to syslog. With optional <facility>,
120 the syslog type can be selected, default is "daemon".
121 -lh Adds hostname to log messages. Uses the value from environment
123 variable HOSTNAME or the value retrieved with uname() if HOST‐
124 NAME is not set.
125 -v Writes the transferred data not only to their target streams,
127 but also to stderr. The output format is text with some conver‐
128 sions for readability, and prefixed with "> " or "< " indicating
129 flow directions.
130 -x Writes the transferred data not only to their target streams,
132 but also to stderr. The output format is hexadecimal, prefixed
133 with "> " or "< " indicating flow directions. Can be combined
134 with -v .
135 -r <file>
137 Dumps the raw (binary) data flowing from left to right address
138 to the given file.
139 -R <file>
141 Dumps the raw (binary) data flowing from right to left address
142 to the given file.
143 -b<size>
145 Sets the data transfer block <size> [size_t]. At most <size>
146 bytes are transferred per step. Default is 8192 bytes.
147 -s By default, socat terminates when an error occurred to prevent
149 the process from running when some option could not be applied.
150 With this option, socat is sloppy with errors and tries to con‐
151 tinue. Even with this option, socat will exit on fatals, and
152 will abort connection attempts when security checks failed.
153 -t<timeout>
155 When one channel has reached EOF, the write part of the other
156 channel is shut down. Then, socat waits <timeout> [timeval] sec‐
157 onds before terminating. Default is 0.5 seconds. This timeout
158 only applies to addresses where write and read part can be
159 closed independently. When during the timeout interval the read
160 part gives EOF, socat terminates without awaiting the timeout.
161 -T<timeout>
163 Total inactivity timeout: when socat is already in the transfer
164 loop and nothing has happened for <timeout> [timeval] seconds
165 (no data arrived, no interrupt occurred...) then it terminates.
166 Useful with protocols like UDP that cannot transfer EOF.
167 -u Uses unidirectional mode. The first address is only used for
169 reading, and the second address is only used for writing (exam‐
170 ple).
171 -U Uses unidirectional mode in reverse direction. The first address
173 is only used for writing, and the second address is only used
174 for reading.
175 -g During address option parsing, don’t check if the option is con‐
177 sidered useful in the given address environment. Use it if you
178 want to force, e.g., appliance of a socket option to a serial
179 device.
180 -L<lockfile>
182 If lockfile exists, exits with error. If lockfile does not
183 exist, creates it and continues, unlinks lockfile on exit.
184 -W<lockfile>
186 If lockfile exists, waits until it disappears. When lockfile
187 does not exist, creates it and continues, unlinks lockfile on
188 exit.
189 -4 Use IP version 4 in case that the addresses do not implicitly or
191 explicitly specify a version; this is the default.
192 -6 Use IP version 6 in case that the addresses do not implicitly or
194 explicitly specify a version.
195
198 With the address command line arguments, the user gives socat instruc‐
199 tions and the necessary information for establishing the byte streams.
200 An address specification usually consists of an address type keyword,
202 zero or more required address parameters separated by ’:’ from the key‐
203 word and from each other, and zero or more address options separated by
204 ’,’.
205 The keyword specifies the address type (e.g., TCP4, OPEN, EXEC). For
207 some keywords there exist synonyms (’-’ for STDIO, TCP for TCP4). Key‐
208 words are case insensitive. For a few special address types, the key‐
209 word may be omitted: Address specifications starting with a number are
210 assumed to be FD (raw file descriptor) addresses; if a ’/’ is found
211 before the first ’:’ or ’,’, GOPEN (generic file open) is assumed.
212 The required number and type of address parameters depend on the
214 address type. E.g., TCP4 requires a server specification (name or
215 address), and a port specification (number or service name).
216 Zero or more address options may be given with each address. They
218 influence the address in some ways. Options consist of an option key‐
219 word or an option keyword and a value, separated by ’=’. Option key‐
220 words are case insensitive. For filtering the options that are useful
221 with an address type, each option is member of one option group. For
222 each address type there is a set of option groups allowed. Only options
223 belonging to one of these address groups may be used (except with
224 option -g).
225 Address specifications following the above schema are also called sin‐
227 gle address specifications. Two single addresses can be combined with
228 "!!" to form a dual type address for one channel. Here, the first
229 address is used by socat for reading data, and the second address for
230 writing data. There is no way to specify an option only once for being
231 applied to both single addresses.
232 Usually, addresses are opened in read/write mode. When an address is
234 part of a dual address specification, or when option -u or -U is used,
235 an address might be used only for reading or for writing. Considering
236 this is important with some address types.
237 With socat version 1.5.0 and higher, the lexical analysis tries to han‐
239 dle quotes and parenthesis meaningfully and allows escaping of special
240 characters. If one of the characters ( { [ ’ is found, the correspond‐
241 ing closing character - ) } ] ’ - is looked for; they may also be
242 nested. Within these constructs, socats special characters and strings
243 : , !! are not handled specially. All those characters and strings can
244 be escaped with \ or within ""
245
247 This section describes the available address types with their keywords,
248 parameters, and semantics.
249 CREATE:<filename>
251 Opens <filename> with creat() and uses the file descriptor for
252 writing. This address type requires write-only context, because
253 a file opened with creat cannot be read from.
254 Flags like O_LARGEFILE cannot be applied. If you need them use
255 OPEN with options create,create.
256 <filename> must be a valid existing or not existing path. If
257 <filename> is a named pipe, creat() might block; if <filename>
258 refers to a socket, this is an error.
259 Option groups: FD,REG,NAMED
260 Useful options: mode, user, group, unlink-early, unlink-late,
261 append
262 See also: OPEN, GOPEN
263 EXEC:<command-line>
265 Forks a sub process that establishes communication with its par‐
266 ent process and invokes the specified program with execvp() .
267 <command-line> is a simple command with arguments separated by
268 single spaces. If the program name contains a ’/’, the part
269 after the last ’/’ is taken as ARGV[0]. If the program name is a
270 relative path, the execvp() semantics for finding the program
271 via $PATH apply. After successful program start, socat writes
272 data to stdin of the process and reads from its stdout using a
273 UNIX domain socket generated by socketpair() per default. (exam‐
274 ple)
275 Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
276 Useful options: path, fdin, fdout, chroot, su, su-d, nofork,
277 pty, stderr, ctty, setsid, pipes, login, sigint, sigquit
278 See also: SYSTEM
279 FD:<fdnum>
281 Uses the file descriptor <fdnum>. It must already exist as valid
282 UN*X file descriptor.
283 Option groups: FD (TERMIOS,REG,SOCKET)
284 See also: STDIO, STDIN, STDOUT, STDERR
285 GOPEN:<filename>
287 (Generic open) This address type tries to handle any file system
288 entry except directories usefully. <filename> may be a relative
289 or absolute path. If it already exists, its type is checked. In
290 case of a UNIX domain socket, socat connects; if connecting
291 fails, socat assumes a datagram socket and uses sendto() calls.
292 If the entry is not a socket, socat opens it applying the
293 O_APPEND flag. If it does not exist, it is opened with flag
294 O_CREAT as a regular file (example).
295 Option groups: FD,REG,SOCKET,NAMED,OPEN
296 See also: OPEN, CREATE, UNIX-CONNECT
297 IP-SENDTO:<host>:<protocol>
299 Opens a raw IP socket. Depending on host specification or option
300 pf, IP protocol version 4 or 6 is used. It uses <protocol> to
301 send packets to <host> [IP address] and receives packets from
302 host, ignores packets from other hosts. Protocol 255 uses the
303 raw socket with the IP header being part of the data.
304 Option groups: FD,SOCKET,IP4,IP6
305 Useful options: pf, ttl
306 See also: IP4-SENDTO, IP6-SENDTO, IP-RECVFROM, IP-RECV,
307 UDP-SENDTO, UNIX-SENDTO
308 INTERFACE:<interface>
310 Communicates with a network connected on an interface using raw
311 packets including link level data. <interface> is the name of
312 the network interface. Currently only available on Linux.
313 Option groups: FD,SOCKET
314 Useful options: pf, type
315 See also: ip-recv
316 IP4-SENDTO:<host>:<protocol>
318 Like IP-SENDTO, but always uses IPv4.
319 Option groups: FD,SOCKET,IP4
320 IP6-SENDTO:<host>:<protocol>
322 Like IP-SENDTO, but always uses IPv6.
323 Option groups: FD,SOCKET,IP6
324 IP-DATAGRAM:<address>:<protocol>
327 Sends outgoing data to the specified address which may in par‐
328 ticular be a broadcast or multicast address. Packets arriving on
329 the local socket are checked if their source addresses match
330 RANGE or TCPWRAP options. This address type can for example be
331 used for implementing symmetric or asymmetric broadcast or mul‐
332 ticast communications.
333 Option groups: FD, SOCKET, IP4, IP6, RANGE
334 Useful options: bind, range, tcpwrap, broadcast, ip-multi‐
335 cast-loop, ip-multicast-ttl, ip-multicast-if, ip-add-membership,
336 ip-add-source-membership, ttl, tos, pf
337 See also: IP4-DATAGRAM, IP6-DATAGRAM, IP-SENDTO, IP-RECVFROM,
338 IP-RECV, UDP-DATAGRAM
339 IP4-DATAGRAM:<host>:<protocol>
341 Like IP-DATAGRAM, but always uses IPv4. (example)
342 Option groups: FD,SOCKET,IP4,RANGE
343 IP6-DATAGRAM:<host>:<protocol>
345 Like IP-DATAGRAM, but always uses IPv6. Please note that IPv6
346 does not know broadcasts.
347 Option groups: FD,SOCKET,IP6,RANGE
348 IP-RECVFROM:<protocol>
351 Opens a raw IP socket of <protocol>. Depending on option pf, IP
352 protocol version 4 or 6 is used. It receives one packet from an
353 unspecified peer and may send one or more answer packets to that
354 peer. This mode is particularly useful with fork option where
355 each arriving packet - from arbitrary peers - is handled by its
356 own sub process. This allows a behaviour similar to typical UDP
357 based servers like ntpd or named.
358 Please note that the reply packets might be fetched as incoming
359 traffic when sender and receiver IP address are identical
360 because there is no port number to distinguish the sockets.
361 This address works well with IP-SENDTO address peers (see
362 above). Protocol 255 uses the raw socket with the IP header
363 being part of the data.
364 See the note about RECVFROM addresses.
365 Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
366 Useful options: pf, fork, range, ttl, broadcast
367 See also: IP4-RECVFROM, IP6-RECVFROM, IP-SENDTO, IP-RECV,
368 UDP-RECVFROM, UNIX-RECVFROM
369 IP4-RECVFROM:<protocol>
371 Like IP-RECVFROM, but always uses IPv4.
372 Option groups: FD,SOCKET,IP4,CHILD,RANGE
373 IP6-RECVFROM:<protocol>
375 Like IP-RECVFROM, but always uses IPv6.
376 Option groups: FD,SOCKET,IP6,CHILD,RANGE
377 IP-RECV:<protocol>
380 Opens a raw IP socket of <protocol>. Depending on option pf, IP
381 protocol version 4 or 6 is used. It receives packets from multi‐
382 ple unspecified peers and merges the data. No replies are pos‐
383 sible. It can be, e.g., addressed by socat IP-SENDTO address
384 peers. Protocol 255 uses the raw socket with the IP header
385 being part of the data.
386 Option groups: FD,SOCKET,IP4,IP6,RANGE
387 Useful options: pf, range
388 See also: IP4-RECV, IP6-RECV, IP-SENDTO, IP-RECVFROM, UDP-RECV,
389 UNIX-RECV
390 IP4-RECV:<protocol>
392 Like IP-RECV, but always uses IPv4.
393 Option groups: FD,SOCKET,IP4,RANGE
394 IP6-RECV:<protocol>
396 Like IP-RECV, but always uses IPv6.
397 Option groups: FD,SOCKET,IP6,RANGE
398 OPEN:<filename>
401 Opens <filename> using the open() system call (example). This
402 operation fails on UNIX domain sockets.
403 Note: This address type is rarely useful in bidirectional mode.
404 Option groups: FD,REG,NAMED,OPEN
405 Useful options: creat, excl, noatime, nofollow, append, rdonly,
406 wronly, lock, readbytes, ignoreeof
407 See also: CREATE, GOPEN, UNIX-CONNECT
408 OPENSSL:<host>:<port>
410 Tries to establish a SSL connection to <port> [TCP service] on
411 <host> [IP address] using TCP/IP version 4 or 6 depending on
412 address specification, name resolution, or option pf.
413 NOTE: Up to version 1.7.2.4 the server certificate was only
414 checked for validity against the system certificate store or
415 cafile or capath, but not for match with the server’s name or
416 its IP address. Since version 1.7.3.0 socat checks the peer
417 certificate for match with the <host> parameter or the value of
418 the openssl-commonname option. Socat tries to match it against
419 the certificates subject commonName, and the certificates exten‐
420 sion subjectAltName DNS names. Wildcards in the certificate are
421 supported.
422 Option groups: FD,SOCKET,IP4,IP6,TCP,OPENSSL,RETRY
423 Useful options: cipher, verify, commonname, cafile, capath, cer‐
424 tificate, key, compress, bind, pf, connect-timeout, sourceport,
425 retry
426 See also: OPENSSL-LISTEN, TCP
427 OPENSSL-LISTEN:<port>
429 Listens on tcp <port> [TCP service]. The IP version is 4 or the
430 one specified with pf. When a connection is accepted, this
431 address behaves as SSL server.
432 Note: You probably want to use the certificate option with this
433 address.
434 NOTE: The client certificate is only checked for validity
435 against cafile or capath, but not for match with the client’s
436 name or its IP address!
437 Option groups: FD,SOCKET,IP4,IP6,TCP,LIS‐
438 TEN,OPENSSL,CHILD,RANGE,RETRY
439 Useful options: pf, cipher, verify, commonname, cafile, capath,
440 certificate, key, compress, fork, bind, range, tcpwrap, su,
441 reuseaddr, retry
442 See also: OPENSSL, TCP-LISTEN
443 OPENSSL-DTLS-CLIENT:<host>:<port>
445 Tries to establish a DTLS connection to <port> [UDP service] on
446 <host> [IP address] using UDP/IP version 4 or 6 depending on
447 address specification, name resolution, or option pf.
448 Socat checks the peer certificates subjectAltName or commonName
449 against the addresses option openssl-commonname or the host
450 name. Wildcards in the certificate are supported.
451 Use socat option -b to make datagrams small enough to fit with
452 overhead on the network. Use option -T to prevent indefinite
453 hanging when peer went down quietly.
454 Option groups: FD,SOCKET,IP4,IP6,OPENSSL,RETRY
455 Useful options: cipher, verify, commonname, cafile, capath, cer‐
456 tificate, key, compress, bind, pf, sourceport, retry
457 See also: OPENSSL-DTLS-SERVER, OPENSSL-CONNECT, UDP-CONNECT
458 OPENSSL-DTLS-SERVER:<port>
460 Listens on UDP <port> [UDP service]. The IP version is 4 or the
461 one specified with pf. When a connection is accepted, this
462 address behaves as DTLS server.
463 Note: You probably want to use the certificate option with this
464 address.
465 NOTE: The client certificate is only checked for validity
466 against cafile or capath, but not for match with the client’s
467 name or its IP address! Use socat option -b to make datagrams
468 small enough to fit with overhead on the network. Use option -T
469 to prevent indefinite hanging when peer went down quietly.
470 Option groups: FD,SOCKET,IP4,IP6,LIS‐
471 TEN,OPENSSL,CHILD,RANGE,RETRY
472 Useful options: pf, cipher, verify, commonname, cafile, capath,
473 certificate, key, compress, fork, bind, range, tcpwrap, su,
474 reuseaddr, retry
475 See also: OPENSSL-DTLS-CLIENT, OPENSSL-LISTEN, UDP-LISTEN
476 PIPE:<filename>
478 If <filename> already exists, it is opened. If it does not
479 exist, a named pipe is created and opened. Beginning with socat
480 version 1.4.3, the named pipe is removed when the address is
481 closed (but see option unlink-close
482 Note: When a pipe is used for both reading and writing, it works
483 as echo service.
484 Note: When a pipe is used for both reading and writing, and
485 socat tries to write more bytes than the pipe can buffer (Linux
486 2.4: 2048 bytes), socat might block. Consider using socat
487 option, e.g., -b 2048
488 Option groups: FD,NAMED,OPEN
489 Useful options: rdonly, nonblock, group, user, mode,
490 unlink-early
491 See also: unnamed pipe
492 PIPE Creates an unnamed pipe and uses it for reading and writing. It
494 works as an echo, because everything written to it appeares
495 immediately as read data.
496 Note: When socat tries to write more bytes than the pipe can
497 queue (Linux 2.4: 2048 bytes), socat might block. Consider,
498 e.g., using option -b 2048
499 Option groups: FD
500 See also: named pipe
501 PROXY:<proxy>:<hostname>:<port>
503 Connects to an HTTP proxy server on port 8080 using TCP/IP ver‐
504 sion 4 or 6 depending on address specification, name resolution,
505 or option pf, and sends a CONNECT request for hostname:port. If
506 the proxy grants access and succeeds to connect to the target,
507 data transfer between socat and the target can start. Note that
508 the traffic need not be HTTP but can be an arbitrary protocol.
509 Option groups: FD,SOCKET,IP4,IP6,TCP,HTTP,RETRY
510 Useful options: proxyport, ignorecr, proxyauth, resolve, crnl,
511 bind, connect-timeout, mss, sourceport, retry
512 See also: SOCKS, TCP
513 PTY Generates a pseudo terminal (pty) and uses its master side.
515 Another process may open the pty’s slave side using it like a
516 serial line or terminal. (example). If both the ptmx and the
517 openpty mechanisms are available, ptmx is used (POSIX).
518 Option groups: FD,NAMED,PTY,TERMIOS
519 Useful options: link, openpty, wait-slave, mode, user, group
520 See also: UNIX-LISTEN, PIPE, EXEC, SYSTEM
521 READLINE
523 Uses GNU readline and history on stdio to allow editing and
524 reusing input lines (example). This requires the GNU readline
525 and history libraries. Note that stdio should be a (pseudo) ter‐
526 minal device, otherwise readline does not seem to work.
527 Option groups: FD,READLINE,TERMIOS
528 Useful options: history, noecho
529 See also: STDIO
530 SCTP-CONNECT:<host>:<port>
532 Establishes an SCTP stream connection to the specified <host>
533 [IP address] and <port> [TCP service] using IP version 4 or 6
534 depending on address specification, name resolution, or option
535 pf.
536 Option groups: FD,SOCKET,IP4,IP6,SCTP,CHILD,RETRY
537 Useful options: bind, pf, connect-timeout, tos, mtudiscover,
538 sctp-maxseg, sctp-nodelay, nonblock, sourceport, retry, read‐
539 bytes
540 See also: SCTP4-CONNECT, SCTP6-CONNECT, SCTP-LISTEN, TCP-CONNECT
541 SCTP4-CONNECT:<host>:<port>
543 Like SCTP-CONNECT, but only supports IPv4 protocol.
544 Option groups: FD,SOCKET,IP4,SCTP,CHILD,RETRY
545 SCTP6-CONNECT:<host>:<port>
547 Like SCTP-CONNECT, but only supports IPv6 protocol.
548 Option groups: FD,SOCKET,IP6,SCTP,CHILD,RETRY
549 SCTP-LISTEN:<port>
551 Listens on <port> [TCP service] and accepts an SCTP connection.
552 The IP version is 4 or the one specified with address option pf,
553 socat option (-4, -6), or environment variable
554 SOCAT_DEFAULT_LISTEN_IP. Note that opening this address usually
555 blocks until a client connects.
556 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,SCTP,RETRY
557 Useful options: crnl, fork, bind, range, tcpwrap, pf, max-chil‐
558 dren, backlog, accept-timeout, sctp-maxseg, sctp-nodelay, su,
559 reuseaddr, retry, cool-write
560 See also: SCTP4-LISTEN, SCTP6-LISTEN, TCP-LISTEN, SCTP-CONNECT
561 SCTP4-LISTEN:<port>
563 Like SCTP-LISTEN, but only supports IPv4 protocol.
564 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,SCTP,RETRY
565 SCTP6-LISTEN:<port>
567 Like SCTP-LISTEN, but only supports IPv6 protocol.
568 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,SCTP,RETRY
569 SOCKET-CONNECT:<domain>:<protocol>:<remote-address>
571 Creates a stream socket using the first and second given socket
572 parameters and SOCK_STREAM (see man socket(2)) and connects to
573 the remote-address. The two socket parameters have to be speci‐
574 fied by int numbers. Consult your OS documentation and include
575 files to find the appropriate values. The remote-address must be
576 the data representation of a sockaddr structure without sa_fam‐
577 ily and (BSD) sa_len components.
578 Please note that you can - beyond the options of the specified
579 groups - also use options of higher level protocols when you
580 apply socat option -g.
581 Option groups: FD,SOCKET,CHILD,RETRY
582 Useful options: bind, setsockopt,
583 See also: TCP, UDP-CONNECT, UNIX-CONNECT, SOCKET-LISTEN,
584 SOCKET-SENDTO
585 SOCKET-DATAGRAM:<domain>:<type>:<protocol>:<remote-address>
587 Creates a datagram socket using the first three given socket
588 parameters (see man socket(2)) and sends outgoing data to the
589 remote-address. The three socket parameters have to be specified
590 by int numbers. Consult your OS documentation and include files
591 to find the appropriate values. The remote-address must be the
592 data representation of a sockaddr structure without sa_family
593 and (BSD) sa_len components.
594 Please note that you can - beyond the options of the specified
595 groups - also use options of higher level protocols when you
596 apply socat option -g.
597 Option groups: FD,SOCKET,RANGE
598 Useful options: bind, range, setsockopt,
599 See also: UDP-DATAGRAM, IP-DATAGRAM, SOCKET-SENDTO, SOCKET-RECV,
600 SOCKET-RECVFROM
601 SOCKET-LISTEN:<domain>:<protocol>:<local-address>
603 Creates a stream socket using the first and second given socket
604 parameters and SOCK_STREAM (see man socket(2)) and waits for
605 incoming connections on local-address. The two socket parameters
606 have to be specified by int numbers. Consult your OS documenta‐
607 tion and include files to find the appropriate values. The
608 local-address must be the data representation of a sockaddr
609 structure without sa_family and (BSD) sa_len components.
610 Please note that you can - beyond the options of the specified
611 groups - also use options of higher level protocols when you
612 apply socat option -g.
613 Option groups: FD,SOCKET,LISTEN,RANGE,CHILD,RETRY
614 Useful options: setsockopt, setsockopt-listen,
615 See also: TCP, UDP-CONNECT, UNIX-CONNECT, SOCKET-LISTEN,
616 SOCKET-SENDTO, SOCKET-SENDTO
617 SOCKET-RECV:<domain>:<type>:<protocol>:<local-address>
619 Creates a socket using the three given socket parameters (see
620 man socket(2)) and binds it to <local-address>. Receives arriv‐
621 ing data. The three parameters have to be specified by int num‐
622 bers. Consult your OS documentation and include files to find
623 the appropriate values. The local-address must be the data rep‐
624 resentation of a sockaddr structure without sa_family and (BSD)
625 sa_len components.
626 Option groups: FD,SOCKET,RANGE
627 Useful options: range, setsockopt, setsockopt-listen
628 See also: UDP-RECV, IP-RECV, UNIX-RECV, SOCKET-DATAGRAM,
629 SOCKET-SENDTO, SOCKET-RECVFROM
630 SOCKET-RECVFROM:<domain>:<type>:<protocol>:<local-address>
632 Creates a socket using the three given socket parameters (see
633 man socket(2)) and binds it to <local-address>. Receives arriv‐
634 ing data and sends replies back to the sender. The first three
635 parameters have to be specified as int numbers. Consult your OS
636 documentation and include files to find the appropriate values.
637 The local-address must be the data representation of a sockaddr
638 structure without sa_family and (BSD) sa_len components.
639 See the note about RECVFROM addresses.
640 Option groups: FD,SOCKET,CHILD,RANGE
641 Useful options: fork, range, setsockopt, setsockopt-listen
642 See also: UDP-RECVFROM, IP-RECVFROM, UNIX-RECVFROM, SOCKET-DATA‐
643 GRAM, SOCKET-SENDTO, SOCKET-RECV
644 SOCKET-SENDTO:<domain>:<type>:<protocol>:<remote-address>
646 Creates a socket using the three given socket parameters (see
647 man socket(2)). Sends outgoing data to the given address and
648 receives replies. The three parameters have to be specified as
649 int numbers. Consult your OS documentation and include files to
650 find the appropriate values. The remote-address must be the data
651 representation of a sockaddr structure without sa_family and
652 (BSD) sa_len components.
653 Option groups: FD,SOCKET
654 Useful options: bind, setsockopt, setsockopt-listen
655 See also: UDP-SENDTO, IP-SENDTO, UNIX-SENDTO, SOCKET-DATAGRAM,
656 SOCKET-RECV SOCKET-RECVFROM
657 SOCKS4:<socks-server>:<host>:<port>
659 Connects via <socks-server> [IP address] to <host> [IPv4
660 address] on <port> [TCP service], using socks version 4 protocol
661 over IP version 4 or 6 depending on address specification, name
662 resolution, or option pf (example).
663 Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
664 Useful options: socksuser, socksport, sourceport, pf, retry
665 See also: SOCKS4A, PROXY, TCP
666 SOCKS4A:<socks-server>:<host>:<port>
668 like SOCKS4, but uses socks protocol version 4a, thus leaving
669 host name resolution to the socks server.
670 Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
671 STDERR Uses file descriptor 2.
673 Option groups: FD (TERMIOS,REG,SOCKET)
674 See also: FD
675 STDIN Uses file descriptor 0.
677 Option groups: FD (TERMIOS,REG,SOCKET)
678 Useful options: readbytes
679 See also: FD
680 STDIO Uses file descriptor 0 for reading, and 1 for writing.
682 Option groups: FD (TERMIOS,REG,SOCKET)
683 Useful options: readbytes
684 See also: FD
685 STDOUT Uses file descriptor 1.
687 Option groups: FD (TERMIOS,REG,SOCKET)
688 See also: FD
689 SYSTEM:<shell-command>
691 Forks a sub process that establishes communication with its par‐
692 ent process and invokes the specified program with system() .
693 Please note that <shell-command> [string] must not contain ’,’
694 or "!!", and that shell meta characters may have to be pro‐
695 tected. After successful program start, socat writes data to
696 stdin of the process and reads from its stdout.
697 Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
698 Useful options: path, fdin, fdout, chroot, su, su-d, nofork,
699 pty, stderr, ctty, setsid, pipes, sigint, sigquit
700 See also: EXEC
701 TCP:<host>:<port>
703 Connects to <port> [TCP service] on <host> [IP address] using
704 TCP/IP version 4 or 6 depending on address specification, name
705 resolution, or option pf.
706 Option groups: FD,SOCKET,IP4,IP6,TCP,RETRY
707 Useful options: crnl, bind, pf, connect-timeout, tos, mtudis‐
708 cover, mss, nodelay, nonblock, sourceport, retry, readbytes
709 See also: TCP4, TCP6, TCP-LISTEN, UDP, SCTP-CONNECT, UNIX-CON‐
710 NECT
711 TCP4:<host>:<port>
713 Like TCP, but only supports IPv4 protocol (example).
714 Option groups: FD,SOCKET,IP4,TCP,RETRY
715 TCP6:<host>:<port>
717 Like TCP, but only supports IPv6 protocol.
718 Option groups: FD,SOCKET,IP6,TCP,RETRY
719 TCP-LISTEN:<port>
721 Listens on <port> [TCP service] and accepts a TCP/IP connection.
722 The IP version is 4 or the one specified with address option pf,
723 socat option (-4, -6), or environment variable
724 SOCAT_DEFAULT_LISTEN_IP. Note that opening this address usually
725 blocks until a client connects.
726 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,TCP,RETRY
727 Useful options: crnl, fork, bind, range, tcpwrap, pf, max-chil‐
728 dren, backlog, accept-timeout, mss, su, reuseaddr, retry,
729 cool-write
730 See also: TCP4-LISTEN, TCP6-LISTEN, UDP-LISTEN, SCTP-LISTEN,
731 UNIX-LISTEN, OPENSSL-LISTEN, TCP-CONNECT
732 TCP4-LISTEN:<port>
734 Like TCP-LISTEN, but only supports IPv4 protocol (example).
735 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,TCP,RETRY
736 TCP6-LISTEN:<port>
738 Like TCP-LISTEN, but only supports IPv6 protocol.
739 Additional useful option: ipv6only
740 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,TCP,RETRY
741 TUN[:<if-addr>/<bits>]
743 Creates a Linux TUN/TAP device and optionally assignes it the
744 address and netmask given by the parameters. The resulting net‐
745 work interface is almost ready for use by other processes; socat
746 serves its "wire side". This address requires read and write
747 access to the tunnel cloning device, usually /dev/net/tun , as
748 well as permission to set some ioctl()s. Option iff-up is
749 required to immediately activate the interface!
750 Note: If you intend to transfer packets between two Socat "wire
751 sides" you need a protocol that keeps packet boundaries,
752 e.g.UDP; TCP might work with option nodelay.
753 Option groups: FD,NAMED,OPEN,TUN
754 Useful options: iff-up, tun-device, tun-name, tun-type,
755 iff-no-pi
756 See also: ip-recv
757 UDP:<host>:<port>
759 Connects to <port> [UDP service] on <host> [IP address] using
760 UDP/IP version 4 or 6 depending on address specification, name
761 resolution, or option pf.
762 Please note that, due to UDP protocol properties, no real con‐
763 nection is established; data has to be sent for `connecting’ to
764 the server, and no end-of-file condition can be transported.
765 Option groups: FD,SOCKET,IP4,IP6
766 Useful options: ttl, tos, bind, sourceport, pf
767 See also: UDP4, UDP6, UDP-LISTEN, TCP, IP
768 UDP4:<host>:<port>
770 Like UDP, but only supports IPv4 protocol.
771 Option groups: FD,SOCKET,IP4
772 UDP6:<host>:<port>
774 Like UDP, but only supports IPv6 protocol.
775 Option groups: FD,SOCKET,IP6
776 UDP-DATAGRAM:<address>:<port>
778 Sends outgoing data to the specified address which may in par‐
779 ticular be a broadcast or multicast address. Packets arriving on
780 the local socket are checked for the correct remote port only
781 when option sourceport is used (this is a change with Socat ver‐
782 sion 1.7.4.0) and if their source addresses match RANGE or TCP‐
783 WRAP options. This address type can for example be used for
784 implementing symmetric or asymmetric broadcast or multicast com‐
785 munications.
786 Option groups: FD,SOCKET,IP4,IP6,RANGE
787 Useful options: bind, range, tcpwrap, broadcast, ip-multi‐
788 cast-loop, ip-multicast-ttl, ip-multicast-if, ip-add-membership,
789 ip-add-source-membership, ttl, tos, sourceport, pf
790 See also: UDP4-DATAGRAM, UDP6-DATAGRAM, UDP-SENDTO,
791 UDP-RECVFROM, UDP-RECV, UDP-CONNECT, UDP-LISTEN, IP-DATAGRAM
792 UDP4-DATAGRAM:<address>:<port>
794 Like UDP-DATAGRAM, but only supports IPv4 protocol (example1,
795 example2).
796 Option groups: FD,SOCKET,IP4, RANGE
797 UDP6-DATAGRAM:<address>:<port>
799 Like UDP-DATAGRAM, but only supports IPv6 protocol.
800 Option groups: FD,SOCKET,IP6,RANGE
801 UDP-LISTEN:<port>
803 Waits for a UDP/IP packet arriving on <port> [UDP service] and
804 `connects’ back to sender. The accepted IP version is 4 or the
805 one specified with option pf. Please note that, due to UDP pro‐
806 tocol properties, no real connection is established; data has to
807 arrive from the peer first, and no end-of-file condition can be
808 transported. Note that opening this address usually blocks until
809 a client connects.
810 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6
811 Useful options: fork, bind, range, pf
812 See also: UDP, UDP4-LISTEN, UDP6-LISTEN, TCP-LISTEN
813 UDP4-LISTEN:<port>
815 Like UDP-LISTEN, but only support IPv4 protocol.
816 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4
817 UDP6-LISTEN:<port>
819 Like UDP-LISTEN, but only support IPv6 protocol.
820 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6
821 UDP-SENDTO:<host>:<port>
823 Communicates with the specified peer socket, defined by <port>
824 [UDP service] on <host> [IP address], using UDP/IP version 4 or
825 6 depending on address specification, name resolution, or option
826 pf. It sends packets to and receives packets from that peer
827 socket only. This address effectively implements a datagram
828 client. It works well with socat UDP-RECVFROM and UDP-RECV
829 address peers.
830 Option groups: FD,SOCKET,IP4,IP6
831 Useful options: ttl, tos, bind, sourceport, pf
832 See also: UDP4-SENDTO, UDP6-SENDTO, UDP-RECVFROM, UDP-RECV,
833 UDP-CONNECT, UDP-LISTEN, IP-SENDTO
834 UDP4-SENDTO:<host>:<port>
836 Like UDP-SENDTO, but only supports IPv4 protocol.
837 Option groups: FD,SOCKET,IP4
838 UDP6-SENDTO:<host>:<port>
840 Like UDP-SENDTO, but only supports IPv6 protocol.
841 Option groups: FD,SOCKET,IP6
842 UDP-RECVFROM:<port>
844 Creates a UDP socket on <port> [UDP service] using UDP/IP ver‐
845 sion 4 or 6 depending on option pf. It receives one packet from
846 an unspecified peer and may send one or more answer packets to
847 that peer. This mode is particularly useful with fork option
848 where each arriving packet - from arbitrary peers - is handled
849 by its own sub process. This allows a behaviour similar to typi‐
850 cal UDP based servers like ntpd or named. This address works
851 well with socat UDP-SENDTO address peers.
852 Note: When the second address fails before entering the transfer
853 loop the packet is dropped. Use option retry or forever on the
854 second address to avoid data loss.
855 Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
856 Useful options: fork, ttl, tos, bind, sourceport, pf
857 See also: UDP4-RECVFROM, UDP6-RECVFROM, UDP-SENDTO, UDP-RECV,
858 UDP-CONNECT, UDP-LISTEN, IP-RECVFROM, UNIX-RECVFROM
859 UDP4-RECVFROM:<port>
861 Like UDP-RECVFROM, but only supports IPv4 protocol.
862 Option groups: FD,SOCKET,IP4,CHILD,RANGE
863 UDP6-RECVFROM:<port>
865 Like UDP-RECVFROM, but only supports IPv6 protocol.
866 Option groups: FD,SOCKET,IP6,CHILD,RANGE
867 UDP-RECV:<port>
869 Creates a UDP socket on <port> [UDP service] using UDP/IP ver‐
870 sion 4 or 6 depending on option pf. It receives packets from
871 multiple unspecified peers and merges the data. No replies are
872 possible. It works well with, e.g., socat UDP-SENDTO address
873 peers; it behaves similar to a syslog server.
874 Note: if you need the fork option, use UDP-RECVFROM in unidirec‐
875 tional mode (with option -u) instead.
876 Option groups: FD,SOCKET,IP4,IP6,RANGE
877 Useful options: pf, bind, sourceport, ttl, tos
878 See also: UDP4-RECV, UDP6-RECV, UDP-SENDTO, UDP-RECVFROM,
879 UDP-CONNECT, UDP-LISTEN, IP-RECV, UNIX-RECV
880 UDP4-RECV:<port>
882 Like UDP-RECV, but only supports IPv4 protocol.
883 Option groups: FD,SOCKET,IP4,RANGE
884 UDP6-RECV:<port>
886 Like UDP-RECV, but only supports IPv6 protocol.
887 Option groups: FD,SOCKET,IP6,RANGE
888 UNIX-CONNECT:<filename>
890 Connects to <filename> assuming it is a UNIX domain socket. If
891 <filename> does not exist, this is an error; if <filename> is
892 not a UNIX domain socket, this is an error; if <filename> is a
893 UNIX domain socket, but no process is listening, this is an
894 error.
895 Option groups: FD,SOCKET,NAMED,RETRY,UNIX
896 ) Useful options: bind
897 See also: UNIX-LISTEN, UNIX-SENDTO, TCP
898 UNIX-LISTEN:<filename>
900 Listens on <filename> using a UNIX domain stream socket and
901 accepts a connection. If <filename> exists and is not a socket,
902 this is an error. If <filename> exists and is a UNIX domain
903 socket, binding to the address fails (use option unlink-early!).
904 Note that opening this address usually blocks until a client
905 connects. Beginning with socat version 1.4.3, the file system
906 entry is removed when this address is closed (but see option
907 unlink-close) (example).
908 Option groups: FD,SOCKET,NAMED,LISTEN,CHILD,RETRY,UNIX
909 Useful options: fork, umask, mode, user, group, unlink-early
910 See also: UNIX-CONNECT, UNIX-RECVFROM, UNIX-RECV, TCP-LISTEN
911 UNIX-SENDTO:<filename>
913 Communicates with the specified peer socket, defined by [<file‐
914 name>] assuming it is a UNIX domain datagram socket. It sends
915 packets to and receives packets from that peer socket only.
916 Please note that it might be necessary to bind the local socket
917 to an address (e.g. /tmp/sock1, which must not exist before).
918 This address type works well with socat UNIX-RECVFROM and
919 UNIX-RECV address peers.
920 Option groups: FD,SOCKET,NAMED,UNIX
921 Useful options: bind
922 See also: UNIX-RECVFROM, UNIX-RECV, UNIX-CONNECT, UDP-SENDTO,
923 IP-SENDTO
924 UNIX-RECVFROM:<filename>
926 Creates a UNIX domain datagram socket [<filename>]. Receives
927 one packet and may send one or more answer packets to that peer.
928 This mode is particularly useful with fork option where each
929 arriving packet - from arbitrary peers - is handled by its own
930 sub process. This address works well with socat UNIX-SENDTO
931 address peers.
932 Option groups: FD,SOCKET,NAMED,CHILD,UNIX
933 See the note about RECVFROM addresses.
934 Useful options: fork
935 See also: UNIX-SENDTO, UNIX-RECV, UNIX-LISTEN, UDP-RECVFROM,
936 IP-RECVFROM
937 UNIX-RECV:<filename>
939 Creates a UNIX domain datagram socket [<filename>]. Receives
940 packets from multiple unspecified peers and merges the data. No
941 replies are possible. It can be, e.g., addressed by socat
942 UNIX-SENDTO address peers. It behaves similar to a syslog
943 server.
944 Option groups: FD,SOCKET,NAMED,UNIX
945 See also: UNIX-SENDTO, UNIX-RECVFROM, UNIX-LISTEN, UDP-RECV,
946 IP-RECV
947 UNIX-CLIENT:<filename>
949 Communicates with the specified peer socket, defined by [<file‐
950 name>] assuming it is a UNIX domain socket. It first tries to
951 connect and, if that fails, assumes it is a datagram socket,
952 thus supporting both types.
953 Option groups: FD,SOCKET,NAMED,UNIX
954 Useful options: bind
955 See also: UNIX-CONNECT, UNIX-SENDTO, GOPEN
956 VSOCK-CONNECT:<cid>:<port>
958 Establishes a VSOCK stream connection to the specified <cid>
959 [VSOCK cid] and <port> [VSOCK port].
960 Option groups: FD,SOCKET,CHILD,RETRY
961 Useful options: bind, pf, connect-timeout, retry, readbytes
962 See also: VSOCK-LISTEN,
963 VSOCK-LISTEN:<port>
965 Listens on <port> [VSOCK port] and accepts a VSOCK connection.
966 Note that opening this address usually blocks until a client
967 connects.
968 Option groups: FD,SOCKET,LISTEN,CHILD,RETRY
969 Useful options: fork, bind, pf, max-children, backlog, su,
970 reuseaddr, retry, cool-write
971 See also: VSOCK-CONNECT
972 ABSTRACT-CONNECT:<string>
974 ABSTRACT-LISTEN:<string>
976 ABSTRACT-SENDTO:<string>
978 ABSTRACT-RECVFROM:<string>
980 ABSTRACT-RECV:<string>
982 ABSTRACT-CLIENT:<string>
984 The ABSTRACT addresses are almost identical to the related UNIX
985 addresses except that they do not address file system based
986 sockets but an alternate UNIX domain address space. To achieve
987 this the socket address strings are prefixed with "\0" inter‐
988 nally. This feature is available (only?) on Linux. Option
989 groups are the same as with the related UNIX addresses, except
990 that the ABSTRACT addresses are not member of the NAMED group.
991
994 Address options can be applied to address specifications to influence
995 the process of opening the addresses and the properties of the result‐
996 ing data channels.
997 For technical reasons not every option can be applied to every address
999 type; e.g., applying a socket option to a regular file will fail. To
1000 catch most useless combinations as early as in the open phase, the con‐
1001 cept of option groups was introduced. Each option belongs to one or
1002 more option groups. Options can be used only with address types that
1003 support at least one of their option groups (but see option -g).
1004 Address options have data types that their values must conform to.
1006 Every address option consists of just a keyword or a keyword followed
1007 by "=value", where value must conform to the options type. Some
1008 address options manipulate parameters of system calls; e.g., option
1009 sync sets the O_SYNC flag with the open() call. Other options cause a
1010 system or library call; e.g., with option `ttl=value’ the setsock‐
1011 opt(fd, SOL_IP, IP_TTL, value, sizeof(int)) call is applied. Other
1012 options set internal socat variables that are used during data trans‐
1013 fer; e.g., `crnl’ causes explicit character conversions. A few options
1014 have more complex implementations; e.g., su-d (substuser-delayed)
1015 inquires some user and group infos, stores them, and applies them later
1016 after a possible chroot() call.
1017 If multiple options are given to an address, their sequence in the
1019 address specification has (almost) no effect on the sequence of their
1020 execution/application. Instead, socat has built in an option phase
1021 model that tries to bring the options in a useful order. Some options
1022 exist in different forms (e.g., unlink, unlink-early, unlink-late) to
1023 control the time of their execution.
1024 If the same option is specified more than once within one address spec‐
1026 ification, with equal or different values, the effect depends on the
1027 kind of option. Options resulting in function calls like setsockopt()
1028 cause multiple invocations. With options that set parameters for a
1029 required call like open() or set internal flags, the value of the last
1030 option occurrence is effective.
1031 The existence or semantics of many options are system dependent. Socat
1033 usually does NOT try to emulate missing libc or kernel features, it
1034 just provides an interface to the underlying system. So, if an operat‐
1035 ing system lacks a feature, the related option is simply not available
1036 on this platform.
1037 The following paragraphs introduce just the more common address
1039 options. For a more comprehensive reference and to find information
1040 about canonical option names, alias names, option phases, and platforms
1041 see file xio.help.
1042 FD option group
1045 This option group contains options that are applied to a UN*X style
1047 file descriptor, no matter how it was generated. Because all current
1048 socat address types are file descriptor based, these options may be
1049 applied to any address.
1050 Note: Some of these options are also member of another option group,
1051 that provides another, non-fd based mechanism. For these options, it
1052 depends on the actual address type and its option groups which mecha‐
1053 nism is used. The second, non-fd based mechanism is prioritized.
1054 cloexec=<bool>
1056 Sets the FD_CLOEXEC flag with the fcntl() system call to value
1057 <bool>. If set, the file descriptor is closed on exec() family
1058 function calls. Socat internally handles this flag for the fds
1059 it controls, so in most cases there will be no need to apply
1060 this option.
1061 setlk Tries to set a discretionary write lock to the whole file using
1063 the fcntl(fd, F_SETLK, ...) system call. If the file is already
1064 locked, this call results in an error. On Linux, when the file
1065 permissions for group are "S" (g-x,g+s), and the file system is
1066 locally mounted with the "mand" option, the lock is mandatory,
1067 i.e. prevents other processes from opening the file.
1068 setlkw Tries to set a discretionary waiting write lock to the whole
1070 file using the fcntl(fd, F_SETLKW, ...) system call. If the
1071 file is already locked, this call blocks. See option setlk for
1072 information about making this lock mandatory.
1073 setlk-rd
1075 Tries to set a discretionary read lock to the whole file using
1076 the fcntl(fd, F_SETLK, ...) system call. If the file is already
1077 write locked, this call results in an error. See option setlk
1078 for information about making this lock mandatory.
1079 setlkw-rd
1081 Tries to set a discretionary waiting read lock to the whole file
1082 using the fcntl(fd, F_SETLKW, ...) system call. If the file is
1083 already write locked, this call blocks. See option setlk for
1084 information about making this lock mandatory.
1085 flock-ex
1087 Tries to set a blocking exclusive advisory lock to the file
1088 using the flock(fd, LOCK_EX) system call. Socat hangs in this
1089 call if the file is locked by another process.
1090 flock-ex-nb
1092 Tries to set a nonblocking exclusive advisory lock to the file
1093 using the flock(fd, LOCK_EX|LOCK_NB) system call. If the file is
1094 already locked, this option results in an error.
1095 flock-sh
1097 Tries to set a blocking shared advisory lock to the file using
1098 the flock(fd, LOCK_SH) system call. Socat hangs in this call if
1099 the file is locked by another process.
1100 flock-sh-nb
1102 Tries to set a nonblocking shared advisory lock to the file
1103 using the flock(fd, LOCK_SH|LOCK_NB) system call. If the file is
1104 already locked, this option results in an error.
1105 lock Sets a blocking lock on the file. Uses the setlk or flock mecha‐
1107 nism depending on availability on the particular platform. If
1108 both are available, the POSIX variant (setlkw) is used.
1109 user=<user>
1111 Sets the <user> (owner) of the stream. If the address is member
1112 of the NAMED option group, socat uses the chown() system call
1113 after opening the file or binding to the UNIX domain socket
1114 (race condition!). Without filesystem entry, socat sets the
1115 user of the stream using the fchown() system call. These calls
1116 might require root privilege.
1117 user-late=<user>
1119 Sets the owner of the fd to <user> with the fchown() system call
1120 after opening or connecting the channel. This is useful only on
1121 file system entries.
1122 group=<group>
1124 Sets the <group> of the stream. If the address is member of the
1125 NAMED option group, socat uses the chown() system call after
1126 opening the file or binding to the UNIX domain socket (race con‐
1127 dition!). Without filesystem entry, socat sets the group of the
1128 stream with the fchown() system call. These calls might require
1129 group membership or root privilege.
1130 group-late=<group>
1132 Sets the group of the fd to <group> with the fchown() system
1133 call after opening or connecting the channel. This is useful
1134 only on file system entries.
1135 mode=<mode>
1137 Sets the <mode> [mode_t] (permissions) of the stream. If the
1138 address is member of the NAMED option group and uses the open()
1139 or creat() call, the mode is applied with these. If the address
1140 is member of the NAMED option group without using these system
1141 calls, socat uses the chmod() system call after opening the
1142 filesystem entry or binding to the UNIX domain socket (race con‐
1143 dition!). Otherwise, socat sets the mode of the stream using
1144 fchmod() . These calls might require ownership or root privi‐
1145 lege.
1146 perm-late=<mode>
1148 Sets the permissions of the fd to value <mode> [mode_t] using
1149 the fchmod() system call after opening or connecting the chan‐
1150 nel. This is useful only on file system entries.
1151 append=<bool>
1153 Always writes data to the actual end of file. If the address is
1154 member of the OPEN option group, socat uses the O_APPEND flag
1155 with the open() system call (example). Otherwise, socat applies
1156 the fcntl(fd, F_SETFL, O_APPEND) call.
1157 nonblock=<bool>
1159 Tries to open or use file in nonblocking mode. Its only effects
1160 are that the connect() call of TCP addresses does not block, and
1161 that opening a named pipe for reading does not block. If the
1162 address is member of the OPEN option group, socat uses the
1163 O_NONBLOCK flag with the open() system call. Otherwise, socat
1164 applies the fcntl(fd, F_SETFL, O_NONBLOCK) call.
1165 binary Opens the file in binary mode to avoid implicit line terminator
1167 conversions (Cygwin).
1168 text Opens the file in text mode to force implicit line terminator
1170 conversions (Cygwin).
1171 noinherit
1173 Does not keep this file open in a spawned process (Cygwin).
1174 cool-write
1176 Takes it easy when write fails with EPIPE or ECONNRESET and logs
1177 the message with notice level instead of error. This prevents
1178 the log file from being filled with useless error messages when
1179 socat is used as a high volume server or proxy where clients
1180 often abort the connection.
1181 This option is experimental.
1182 end-close
1184 Changes the (address dependent) method of ending a connection to
1185 just close the file descriptors. This is useful when the connec‐
1186 tion is to be reused by or shared with other processes (exam‐
1187 ple).
1188 Normally, socket connections will be ended with shutdown(2)
1189 which terminates the socket even if it is shared by multiple
1190 processes. close(2) "unlinks" the socket from the process but
1191 keeps it active as long as there are still links from other pro‐
1192 cesses.
1193 Similarly, when an address of type EXEC or SYSTEM is ended,
1194 socat usually will explicitly kill the sub process. With this
1195 option, it will just close the file descriptors.
1196 shut-none
1198 Changes the (address dependent) method of shutting down the
1199 write part of a connection to not do anything.
1200 shut-down
1202 Changes the (address dependent) method of shutting down the
1203 write part of a connection to shutdown(fd, SHUT_WR). Is only
1204 useful with sockets.
1205 shut-close
1207 Changes the (address dependent) method of shutting down the
1208 write part of a connection to close(fd).
1209 shut-null
1211 When one address indicates EOF, socat will send a zero sized
1212 packet to the write channel of the other address to transfer the
1213 EOF condition. This is useful with UDP and other datagram proto‐
1214 cols. Has been tested against netcat and socat with option
1215 null-eof.
1216 null-eof
1218 Normally socat will ignore empty (zero size payload) packets
1219 arriving on datagram sockets, so it survives port scans. With
1220 this option socat interprets empty datagram packets as EOF indi‐
1221 cator (see shut-null).
1222 ioctl-void=<request>
1224 Calls ioctl() with the request value as second argument and NULL
1225 as third argument. This option allows utilizing ioctls that are
1226 not explicitly implemented in socat.
1227 ioctl-int=<request>:<value>
1229 Calls ioctl() with the request value as second argument and the
1230 integer value as third argument.
1231 ioctl-intp=<request>:<value>
1233 Calls ioctl() with the request value as second argument and a
1234 pointer to the integer value as third argument.
1235 ioctl-bin=<request>:<value>
1237 Calls ioctl() with the request value as second argument and a
1238 pointer to the given data value as third argument. This data
1239 must be specified in <dalan> form.
1240 ioctl-string=<request>:<value>
1242 Calls ioctl() with the request value as second argument and a
1243 pointer to the given string as third argument. <dalan> form.
1244 NAMED option group
1247 These options work on file system entries.
1249 Please note that, with UNIX domain client addresses, this means the
1250 bind entry, not the target/peer entry.
1251 See also options user, group, and mode.
1252 user-early=<user>
1254 Changes the <user> (owner) of the file system entry before
1255 accessing it, using the chown() system call. This call might
1256 require root privilege.
1257 group-early=<group>
1259 Changes the <group> of the file system entry before accessing
1260 it, using the chown() system call. This call might require group
1261 membership or root privilege.
1262 perm-early=<mode>
1264 Changes the <mode> [mode_t] of the file system entry before
1265 accessing it, using the chmod() system call. This call might
1266 require ownership or root privilege.
1267 umask=<mode>
1269 Sets the umask of the process to <mode> [mode_t] before access‐
1270 ing the file system entry (useful with UNIX domain sockets!).
1271 This call might affect all further operations of the socat
1272 process!
1273 unlink-early
1275 Unlinks (removes) the file before opening it and even before
1276 applying user-early etc.
1277 unlink Unlinks (removes) the file before accessing it, but after
1279 user-early etc.
1280 unlink-late
1282 Unlinks (removes) the file after opening it to make it inacces‐
1283 sible for other processes after a short race condition.
1284 unlink-close
1286 Removes the addresses file system entry when closing the
1287 address. For named pipes, UNIX domain sockets, and the symbolic
1288 links of pty addresses, the default is 1; for created files,
1289 opened files, and generic opened files the default is 0.
1290 OPEN option group
1293 The OPEN group options allow setting flags with the open() system call.
1295 E.g., option `creat’ sets the O_CREAT flag.
1296 See also options append and nonblock.
1297 creat=<bool>
1299 Creates the file if it does not exist (example).
1300 dsync=<bool>
1302 Blocks write() calls until metainfo is physically written to
1303 media.
1304 excl=<bool>
1306 With option creat, if file exists this is an error.
1307 largefile=<bool>
1309 On 32 bit systems, allows a file larger than 2^31 bytes.
1310 noatime
1312 Sets the O_NOATIME options, so reads do not change the access
1313 timestamp.
1314 noctty=<bool>
1316 Does not make this file the controlling terminal.
1317 nofollow=<bool>
1319 Does not follow symbolic links.
1320 nshare=<bool>
1322 Does not allow sharing this file with other processes.
1323 rshare=<bool>
1325 Does not allow other processes to open this file for writing.
1326 rsync=<bool>
1328 Blocks write() until metainfo is physically written to media.
1329 sync=<bool>
1331 Blocks write() until data is physically written to media.
1332 rdonly=<bool>
1334 Opens the file for reading only.
1335 wronly=<bool>
1337 Opens the file for writing only.
1338 trunc Truncates the file to size 0 during opening it.
1340 REG and BLK option group
1343 These options are usually applied to a UN*X file descriptor, but their
1345 semantics make sense only on a file supporting random access.
1346 seek=<offset>
1348 Applies the lseek(fd, <offset>, SEEK_SET) (or lseek64 ) system
1349 call, thus positioning the file pointer absolutely to <offset>
1350 [off_t or off64_t]. Please note that a missing value defaults to
1351 1, not 0.
1352 seek-cur=<offset>
1354 Applies the lseek(fd, <offset>, SEEK_CUR) (or lseek64 ) system
1355 call, thus positioning the file pointer <offset> [off_t or
1356 off64_t] bytes relatively to its current position (which is usu‐
1357 ally 0). Please note that a missing value defaults to 1, not 0.
1358 seek-end=<offset>
1360 Applies the lseek(fd, <offset>, SEEK_END) (or lseek64 ) system
1361 call, thus positioning the file pointer <offset> [off_t or
1362 off64_t] bytes relatively to the files current end. Please note
1363 that a missing value defaults to 1, not 0.
1364 ftruncate=<offset>
1366 Applies the ftruncate(fd, <offset>) (or ftruncate64 if avail‐
1367 able) system call, thus truncating the file at the position
1368 <offset> [off_t or off64_t]. Please note that a missing value
1369 defaults to 1, not 0.
1370 secrm=<bool>
1372 unrm=<bool>
1374 compr=<bool>
1376 fs-sync=<bool>
1378 immutable=<bool>
1380 fs-append=<bool>
1382 nodump=<bool>
1384 fs-noatime=<bool>
1386 journal-data=<bool>
1388 notail=<bool>
1390 dirsync=<bool>
1392 These options change non standard file attributes on operating
1393 systems and file systems that support these features, like Linux
1394 with ext2fs and successors, xfs, or reiserfs. See man 1 chattr
1395 for information on these options. Please note that there might
1396 be a race condition between creating the file and applying these
1397 options.
1398 PROCESS option group
1401 Options of this group change the process properties instead of just
1403 affecting one data channel. For EXEC and SYSTEM addresses and for LIS‐
1404 TEN and CONNECT type addresses with option FORK, these options apply to
1405 the child processes instead of the main socat process.
1406 chroot=<directory>
1408 Performs a chroot() operation to <directory> after processing
1409 the address (example). This call might require root privilege.
1410 chroot-early=<directory>
1412 Performs a chroot() operation to <directory> before opening the
1413 address. This call might require root privilege.
1414 setgid=<group>
1416 Changes the primary <group> of the process after processing the
1417 address. This call might require root privilege. Please note
1418 that this option does not drop other group related privileges.
1419 setgid-early=<group>
1421 Like setgit but is performed before opening the address.
1422 setuid=<user>
1424 Changes the <user> (owner) of the process after processing the
1425 address. This call might require root privilege. Please note
1426 that this option does not drop group related privileges. Check
1427 if option su better fits your needs.
1428 setuid-early=<user>
1430 Like setuid but is performed before opening the address.
1431 su=<user>
1433 Changes the <user> (owner) and groups of the process after pro‐
1434 cessing the address (example). This call might require root
1435 privilege.
1436 su-d=<user>
1438 Short name for substuser-delayed. Changes the <user> (owner)
1439 and groups of the process after processing the address (exam‐
1440 ple). The user and his groups are retrieved before a possible
1441 chroot() . This call might require root privilege.
1442 setpgid=<pid_t>
1444 Makes the process a member of the specified process group
1445 <pid_t>. If no value is given, or if the value is 0 or 1, the
1446 process becomes leader of a new process group.
1447 setsid Makes the process the leader of a new session (example).
1449 READLINE option group
1452 These options apply to the readline address type.
1454 history=<filename>
1456 Reads and writes history from/to <filename> (example).
1457 noprompt
1459 Since version 1.4.0, socat per default tries to determine a
1460 prompt - that is then passed to the readline call - by remember‐
1461 ing the last incomplete line of the output. With this option,
1462 socat does not pass a prompt to readline, so it begins line
1463 editing in the first column of the terminal.
1464 noecho=<pattern>
1466 Specifies a regular pattern for a prompt that prevents the fol‐
1467 lowing input line from being displayed on the screen and from
1468 being added to the history. The prompt is defined as the text
1469 that was output to the readline address after the lastest new‐
1470 line character and before an input character was typed. The pat‐
1471 tern is a regular expression, e.g. "^[Pp]assword:.*$" or
1472 "([Uu]ser:|[Pp]assword:)". See regex(7) for details. (example)
1473 prompt=<string>
1475 Passes the string as prompt to the readline function. readline
1476 prints this prompt when stepping through the history. If this
1477 string matches a constant prompt issued by an interactive pro‐
1478 gram on the other socat address, consistent look and feel can be
1479 achieved.
1480 APPLICATION option group
1483 This group contains options that work at data level. Note that these
1485 options only apply to the "raw" data transferred by socat, but not to
1486 protocol data used by addresses like PROXY.
1487 cr Converts the default line termination character NL (’\n’, 0x0a)
1489 to/from CR (’\r’, 0x0d) when writing/reading on this channel.
1490 crnl Converts the default line termination character NL (’\n’, 0x0a)
1492 to/from CRNL ("\r\n", 0x0d0a) when writing/reading on this chan‐
1493 nel (example). Note: socat simply strips all CR characters.
1494 ignoreeof
1496 When EOF occurs on this channel, socat ignores it and tries to
1497 read more data (like "tail -f") (example).
1498 readbytes=<bytes>
1500 socat reads only so many bytes from this address (the address
1501 provides only so many bytes for transfer and pretends to be at
1502 EOF afterwards). Must be greater than 0.
1503 lockfile=<filename>
1505 If lockfile exists, exits with error. If lockfile does not
1506 exist, creates it and continues, unlinks lockfile on exit.
1507 waitlock=<filename>
1509 If lockfile exists, waits until it disappears. When lockfile
1510 does not exist, creates it and continues, unlinks lockfile on
1511 exit.
1512 escape=<int>
1514 Specifies the numeric code of a character that triggers EOF on
1515 the input stream. It is useful with a terminal in raw mode
1516 (example).
1517 SOCKET option group
1520 These options are intended for all kinds of sockets, e.g. IP or UNIX
1522 domain. Most are applied with a setsockopt() call.
1523 bind=<sockname>
1525 Binds the socket to the given socket address using the bind()
1526 system call. The form of <sockname> is socket domain dependent:
1527 IP4 and IP6 allow the form [hostname|hostaddress][:(ser‐
1528 vice|port)] (example), UNIX domain sockets require <filename>,
1529 VSOCK allow the form [cid][:(port)].
1530 connect-timeout=<seconds>
1532 Abort the connection attempt after <seconds> [timeval] with
1533 error status.
1534 so-bindtodevice=<interface>
1536 Binds the socket to the given <interface>. This option might
1537 require root privilege.
1538 broadcast
1540 For datagram sockets, allows sending to broadcast addresses and
1541 receiving packets addressed to broadcast addresses.
1542 debug Enables socket debugging.
1544 dontroute
1546 Only communicates with directly connected peers, does not use
1547 routers.
1548 keepalive
1550 Enables sending keepalives on the socket.
1551 linger=<seconds>
1553 Blocks shutdown() or close() until data transfers have finished
1554 or the given timeout [int] expired.
1555 oobinline
1557 Places out-of-band data in the input data stream.
1558 priority=<priority>
1560 Sets the protocol defined <priority> [<int>] for outgoing pack‐
1561 ets.
1562 rcvbuf=<bytes>
1564 Sets the size of the receive buffer after the socket() call to
1565 <bytes> [int]. With TCP sockets, this value corresponds to the
1566 socket’s maximal window size.
1567 rcvbuf-late=<bytes>
1569 Sets the size of the receive buffer when the socket is already
1570 connected to <bytes> [int]. With TCP sockets, this value corre‐
1571 sponds to the socket’s maximal window size.
1572 rcvlowat=<bytes>
1574 Specifies the minimum number of received bytes [int] until the
1575 socket layer will pass the buffered data to socat.
1576 reuseaddr
1578 Allows other sockets to bind to an address even if parts of it
1579 (e.g. the local port) are already in use by socat (example).
1580 sndbuf=<bytes>
1582 Sets the size of the send buffer after the socket() call to
1583 <bytes> [int].
1584 sndbuf-late=<bytes>
1586 Sets the size of the send buffer when the socket is connected to
1587 <bytes> [int].
1588 sndlowat=<bytes>
1590 Specifies the minimum number of bytes in the send buffer until
1591 the socket layer will send the data to <bytes> [int].
1592 pf=<string>
1594 Forces the use of the specified IP version or protocol. <string>
1595 can be something like "ip4" or "ip6". The resulting value is
1596 used as first argument to the socket() or socketpair() calls.
1597 This option affects address resolution and the required syntax
1598 of bind and range options.
1599 type=<type>
1601 Sets the type of the socket, specified as second argument to the
1602 socket() or socketpair() calls, to <type> [int]. Address resolu‐
1603 tion is not affected by this option. Under Linux, 1 means
1604 stream oriented socket, 2 means datagram socket, and 3 means raw
1605 socket.
1606 protocol
1608 Sets the protocol of the socket, specified as third argument to
1609 the socket() or socketpair() calls, to <protocol> [int]. Address
1610 resolution is not affected by this option. 6 means TCP, 17
1611 means UDP.
1612 reuseport
1614 Set the SO_REUSEPORT socket option.
1615 so-timestamp
1617 Sets the SO_TIMESTAMP socket option. This enables receiving and
1618 logging of timestamp ancillary messages.
1619 setsockopt=<level>:<optname>:<optval>
1621 Invokes setsockopt() for the socket with the given parameters.
1622 level [int] is used as second argument to setsockopt() and spec‐
1623 ifies the layer, e.g. SOL_TCP for TCP (6 on Linux), or
1624 SOL_SOCKET for the socket layer (1 on Linux). optname [int] is
1625 the third argument to setsockopt() and tells which socket option
1626 is to be set. For the actual numbers you might have to look up
1627 the appropriate include files of your system. For the 4th and
1628 5th setsockopt() parameters, value [dalan] specifies an arbi‐
1629 trary sequence of bytes that are passed to the function per
1630 pointer, with the automatically derived length parameter.
1631 setsockopt-int=<level>:<optname>:<optval>
1633 Like setsockopt, but <optval> is a pointer to int [int]
1634 setsockopt-listen=<level>:<optname>:<optval>
1636 Like setsockopt, but for listen type addresses it is applied to
1637 the listening socket instead of the connected socket.
1638 setsockopt-string=<level>:<optname>:<optval>
1640 Like setsockopt, but <optval> is a string. This string is
1641 passed to the function with trailing null character, and the
1642 length parameter is automatically derived from the data.
1643 UNIX option group
1646 These options apply to UNIX domain based addresses.
1648 unix-tightsocklen=[0|1]
1650 On socket operations, pass a socket address length that does not
1651 include the whole struct sockaddr_un record but (besides other
1652 components) only the relevant part of the filename or abstract
1653 string. Default is 1.
1654 IP4 and IP6 option groups
1657 These options can be used with IPv4 and IPv6 based sockets.
1659 tos=<tos>
1661 Sets the TOS (type of service) field of outgoing packets to
1662 <tos> [byte] (see RFC 791).
1663 ttl=<ttl>
1665 Sets the TTL (time to live) field of outgoing packets to <ttl>
1666 [byte].
1667 ip-options=<data>
1669 Sets IP options like source routing. Must be given in binary
1670 form, recommended format is a leading "x" followed by an even
1671 number of hex digits. This option may be used multiple times,
1672 data are appended. E.g., to connect to host 10.0.0.1 via some
1673 gateway using a loose source route, use the gateway as address
1674 parameter and set a loose source route using the option
1675 ip-options=x8307040a000001 .
1676 IP options are defined in RFC 791.
1677 mtudiscover=<0|1|2>
1679 Takes 0, 1, 2 to never, want, or always use path MTU discover on
1680 this socket.
1681 ip-pktinfo
1683 Sets the IP_PKTINFO socket option. This enables receiving and
1684 logging of ancillary messages containing destination address and
1685 interface (Linux) (example).
1686 ip-recverr
1688 Sets the IP_RECVERR socket option. This enables receiving and
1689 logging of ancillary messages containing detailed error informa‐
1690 tion.
1691 ip-recvopts
1693 Sets the IP_RECVOPTS socket option. This enables receiving and
1694 logging of IP options ancillary messages (Linux, *BSD).
1695 ip-recvtos
1697 Sets the IP_RECVTOS socket option. This enables receiving and
1698 logging of TOS (type of service) ancillary messages (Linux).
1699 ip-recvttl
1701 Sets the IP_RECVTTL socket option. This enables receiving and
1702 logging of TTL (time to live) ancillary messages (Linux, *BSD).
1703 ip-recvdstaddr
1705 Sets the IP_RECVDSTADDR socket option. This enables receiving
1706 and logging of ancillary messages containing destination address
1707 (*BSD) (example).
1708 ip-recvif
1710 Sets the IP_RECVIF socket option. This enables receiving and
1711 logging of interface ancillary messages (*BSD) (example).
1712 ip-add-membership=<multicast-address:interface-address>
1714 ip-add-membership=<multicast-address:interface-name>
1716 ip-add-membership=<multicast-address:interface-index>
1718 ip-add-membership=<multicast-address:interface-address:interface-name>
1720 ip-add-membership=<multicast-address:interface-address:interface-index>
1722 Makes the socket member of the specified multicast group. This
1723 is currently only implemented for IPv4. The option takes the IP
1724 address of the multicast group and info about the desired net‐
1725 work interface. The most common syntax is the first one, while
1726 the others are only available on systems that provide struct
1727 mreqn (Linux).
1728 The indices of active network interfaces can be shown using the
1729 utility procan.
1730 ip-add-source-membership=<multicast-address:inter‐
1732 face-address:source-address>
1733 Makes the socket member of the specified multicast group for the
1734 specified source, i.e. only multicast traffic from this address
1735 is to be delivered. This is currently only implemented for
1736 IPv4.
1737 ip-multicast-if=<hostname>
1739 Specifies hostname or address of the network interface to be
1740 used for multicast traffic.
1741 ip-multicast-loop=<bool>
1743 Specifies if outgoing multicast traffic should loop back to the
1744 interface.
1745 ip-multicast-ttl=<byte>
1747 Sets the TTL used for outgoing multicast traffic. Default is 1.
1748 ip-transparent
1750 Sets the IP_TRANSPARENT socket option. This option might
1751 require root privilege.
1752 res-debug
1754 res-aaonly
1756 res-usevc
1758 res-primary
1760 res-igntc
1762 res-recurse
1764 res-defnames
1766 res-stayopen
1768 res-dnsrch
1770 These options set the corresponding resolver (name resolution)
1771 option flags. Append "=0" to clear a default option. See man
1772 resolver(5) for more information on these options. Note: these
1773 options are valid only for the address they are applied to.
1774 IP6 option group
1776 These options can only be used on IPv6 based sockets. See IP options
1778 for options that can be applied to both IPv4 and IPv6 sockets.
1779 ipv6only=<bool>
1781 Sets the IPV6_V6ONLY socket option. If 0, the TCP stack will
1782 also accept connections using IPv4 protocol on the same port.
1783 The default is system dependent.
1784 ipv6-recvdstopts
1786 Sets the IPV6_RECVDSTOPTS socket option. This enables receiving
1787 and logging of ancillary messages containing the destination
1788 options.
1789 ipv6-recvhoplimit
1791 Sets the IPV6_RECVHOPLIMIT socket option. This enables receiving
1792 and logging of ancillary messages containing the hoplimit.
1793 ipv6-recvhopopts
1795 Sets the IPV6_RECVHOPOPTS socket option. This enables receiving
1796 and logging of ancillary messages containing the hop options.
1797 ipv6-recvpktinfo
1799 Sets the IPV6_RECVPKTINFO socket option. This enables receiving
1800 and logging of ancillary messages containing destination address
1801 and interface.
1802 ipv6-unicast-hops=link(TYPE_INT)(<int>)
1804 Sets the IPV6_UNICAST_HOPS socket option. This sets the hop
1805 count limit (TTL) for outgoing unicast packets.
1806 ipv6-recvrthdr
1808 Sets the IPV6_RECVRTHDR socket option. This enables receiving
1809 and logging of ancillary messages containing routing informa‐
1810 tion.
1811 ipv6-tclass
1813 Sets the IPV6_TCLASS socket option. This sets the transfer class
1814 of outgoing packets.
1815 ipv6-recvtclass
1817 Sets the IPV6_RECVTCLASS socket option. This enables receiving
1818 and logging of ancillary messages containing the transfer class.
1819 TCP option group
1822 These options may be applied to TCP sockets. They work by invoking set‐
1824 sockopt() with the appropriate parameters.
1825 cork Doesn’t send packets smaller than MSS (maximal segment size).
1827 defer-accept
1829 While listening, accepts connections only when data from the
1830 peer arrived.
1831 keepcnt=<count>
1833 Sets the number of keepalives before shutting down the socket to
1834 <count> [int].
1835 keepidle=<seconds>
1837 Sets the idle time before sending the first keepalive to <sec‐
1838 onds> [int].
1839 keepintvl=<seconds>
1841 Sets the interval between two keepalives to <seconds> [int].
1842 linger2=<seconds>
1844 Sets the time to keep the socket in FIN-WAIT-2 state to <sec‐
1845 onds> [int].
1846 mss=<bytes>
1848 Sets the MSS (maximum segment size) after the socket() call to
1849 <bytes> [int]. This value is then proposed to the peer with the
1850 SYN or SYN/ACK packet (example).
1851 mss-late=<bytes>
1853 Sets the MSS of the socket after connection has been established
1854 to <bytes> [int].
1855 nodelay
1857 Turns off the Nagle algorithm for measuring the RTT (round trip
1858 time).
1859 rfc1323
1861 Enables RFC1323 TCP options: TCP window scale, round-trip time
1862 measurement (RTTM), and protect against wrapped sequence numbers
1863 (PAWS) (AIX).
1864 stdurg Enables RFC1122 compliant urgent pointer handling (AIX).
1866 syncnt=<count>
1868 Sets the maximal number of SYN retransmits during connect to
1869 <count> [int].
1870 md5sig Enables generation of MD5 digests on the packets (FreeBSD).
1872 noopt Disables use of TCP options (FreeBSD, MacOSX).
1874 nopush sets the TCP_NOPUSH socket option (FreeBSD, MacOSX).
1876 sack-disable
1878 Disables use the selective acknowledge feature (OpenBSD).
1879 signature-enable
1881 Enables generation of MD5 digests on the packets (OpenBSD).
1882 abort-threshold=<milliseconds>
1884 Sets the time to wait for an answer of the peer on an estab‐
1885 lished connection (HP-UX).
1886 conn-abort-threshold=<milliseconds>
1888 Sets the time to wait for an answer of the server during the
1889 initial connect (HP-UX).
1890 keepinit
1892 Sets the time to wait for an answer of the server during con‐
1893 nect() before giving up. Value in half seconds, default is 150
1894 (75s) (Tru64).
1895 paws Enables the "protect against wrapped sequence numbers" feature
1897 (Tru64).
1898 sackena
1900 Enables selective acknowledge (Tru64).
1901 tsoptena
1903 Enables the time stamp option that allows RTT recalculation on
1904 existing connections (Tru64).
1905 UDP option group
1908 This option may be applied to UDP datagram sockets.
1910 udp-ignore-peerport>
1912 Address UDP-DATAGRAM expects incoming responses to come from the
1913 port specified in its second parameter. With this option, it
1914 accepts packets coming from any port.
1915 SCTP option group
1918 These options may be applied to SCTP stream sockets.
1920 sctp-nodelay
1922 Sets the SCTP_NODELAY socket option that disables the Nagle
1923 algorithm.
1924 sctp-maxseg=<bytes>
1926 Sets the SCTP_MAXSEG socket option to <bytes> [int]. This value
1927 is then proposed to the peer with the SYN or SYN/ACK packet.
1928 UDP, TCP, and SCTP option group
1931 Here we find options that are related to the network port mechanism and
1933 thus can be used with UDP, TCP, and SCTP client and server addresses.
1934 sourceport=<port>
1936 For outgoing (client) TCP and UDP connections, it sets the
1937 source <port> using an extra bind() call. With TCP or UDP lis‐
1938 ten addresses, socat immediately shuts down the connection if
1939 the client does not use this sourceport. UDP-RECV, UDP-RECVFROM,
1940 UDP-SENDTO, and UDP-DATAGRAM addresses ignore the packet when it
1941 does not match. (example).
1942 lowport
1944 Outgoing (client) TCP and UDP connections with this option use
1945 an unused random source port between 640 and 1023 incl. On UNIX
1946 class operating systems, this requires root privilege, and thus
1947 indicates that the client process is authorized by local root.
1948 TCP and UDP listen addresses with this option immediately shut
1949 down the connection if the client does not use a sourceport <=
1950 1023. This mechanism can provide limited authorization under
1951 some circumstances.
1952 SOCKS option group
1955 When using SOCKS type addresses, some socks specific options can be
1957 set.
1958 socksport=<tcp service>
1960 Overrides the default "socks" service or port 1080 for the socks
1961 server port with <TCP service>.
1962 socksuser=<user>
1964 Sends the <user> [string] in the username field to the socks
1965 server. Default is the actual user name ($LOGNAME or $USER)
1966 (example).
1967 HTTP option group
1970 Options that can be provided with HTTP type addresses. The only HTTP
1972 address currently implemented is proxy-connect.
1973 proxyport=<TCP service>
1975 Overrides the default HTTP proxy port 8080 with <TCP service>.
1976 ignorecr
1978 The HTTP protocol requires the use of CR+NL as line terminator.
1979 When a proxy server violates this standard, socat might not
1980 understand its answer. This option directs socat to interprete
1981 NL as line terminator and to ignore CR in the answer. Neverthe‐
1982 less, socat sends CR+NL to the proxy.
1983 proxy-authorization=<username>:<password>
1985 Provide "basic" authentication to the proxy server. The argument
1986 to the option is used with a "Proxy-Authorization: Basic" header
1987 in base64 encoded form.
1988 Note: username and password are visible for every user on the
1989 local machine in the process list; username and password are
1990 transferred to the proxy server unencrypted (base64 encoded) and
1991 might be sniffed.
1992 proxy-authorization-file=<filename>
1994 Like option proxy-authorization, but the credentials are read
1995 from the file and therefore not visible in the process list.
1996 resolve
1998 Per default, socat sends to the proxy a CONNECT request contain‐
1999 ing the target hostname. With this option, socat resolves the
2000 hostname locally and sends the IP address. Please note that,
2001 according to RFC 2396, only name resolution to IPv4 addresses is
2002 implemented.
2003 RANGE option group
2006 These options check if a connecting client should be granted access.
2008 They can be applied to listening and receiving network sockets.
2009 tcp-wrappers options fall into this group.
2010 range=<address-range>
2012 After accepting a connection, tests if the peer is within range.
2013 For IPv4 addresses, address-range takes the form address/bits,
2014 e.g. 10.0.0.0/8, or address:mask, e.g. 10.0.0.0:255.0.0.0
2015 (example); for IPv6, it is [ip6-address]/bits, e.g. [::1]/128.
2016 If the client address does not match, socat refuses the connec‐
2017 tion attempt, issues a warning, and keeps listening/receiving.
2018 tcpwrap[=<name>]
2020 Uses Wietse Venema’s libwrap (tcpd) library to determine if the
2021 client is allowed to connect. The configuration files are
2022 /etc/hosts.allow and /etc/hosts.deny per default, see "man 5
2023 hosts_access" for more information. The optional <name> (type
2024 string) is passed to the wrapper functions as daemon process
2025 name (example). If omitted, the basename of socats invocation
2026 (argv[0]) is passed. If both tcpwrap and range options are
2027 applied to an address, both conditions must be fulfilled to
2028 allow the connection.
2029 allow-table=<filename>
2031 Takes the specified file instead of /etc/hosts.allow.
2032 deny-table=<filename>
2034 Takes the specified file instead of /etc/hosts.deny.
2035 tcpwrap-etc=<directoryname>
2037 Looks for hosts.allow and hosts.deny in the specified directory.
2038 Is overridden by options hosts-allow and hosts-deny.
2039 LISTEN option group
2042 Options specific to listening sockets.
2044 backlog=<count>
2046 Sets the backlog value passed with the listen() system call to
2047 <count> [int]. Default is 5.
2048 accept-timeout=<seconds>
2050 End waiting for a connection after <seconds> [timeval] with
2051 error status.
2052 max-children=<count>
2054 Limits the number of concurrent child processes [int]. Default
2055 is no limit.
2056 CHILD option group
2059 Options for addresses with multiple connections via child processes.
2061 fork After establishing a connection, handles its channel in a child
2063 process and keeps the parent process attempting to produce more
2064 connections, either by listening or by connecting in a loop
2065 (example).
2066 OPENSSL-CONNECT and OPENSSL-LISTEN differ in when they actually
2067 fork off the child: OPENSSL-LISTEN forks before the SSL hand‐
2068 shake, while OPENSSL-CONNECT forks afterwards. retry and for‐
2069 ever options are not inherited by the child process.
2070 On some operating systems (e.g. FreeBSD) this option does not
2071 work for UDP-LISTEN addresses.
2072 EXEC option group
2075 Options for addresses that invoke a program.
2077 path=<string>
2079 Overrides the PATH environment variable for searching the pro‐
2080 gram with <string>. This $PATH value is effective in the child
2081 process too.
2082 login Prefixes argv[0] for the execvp() call with ’-’, thus making a
2084 shell behave as login shell.
2085 FORK option group
2088 EXEC or SYSTEM addresses invoke a program using a child process and
2090 transfer data between socat and the program. The interprocess communi‐
2091 cation mechanism can be influenced with the following options. Per
2092 default, a socketpair() is created and assigned to stdin and stdout of
2093 the child process, while stderr is inherited from the socat process,
2094 and the child process uses file descriptors 0 and 1 for communicating
2095 with the main socat process.
2096 nofork Does not fork a subprocess for executing the program, instead
2098 calls execvp() or system() directly from the actual socat
2099 instance. This avoids the overhead of another process between
2100 the program and its peer, but introduces a lot of restrictions:
2101 o this option can only be applied to the second socat address.
2103 o it cannot be applied to a part of a dual address.
2105 o the first socat address cannot be OPENSSL or READLINE
2107 o socat options -b, -t, -D, -l, -v, -x become useless
2109 o for both addresses, options ignoreeof, cr, and crnl become use‐
2111 less
2112 o for the second address (the one with option nofork), options
2114 append, cloexec, flock, user, group, mode, nonblock, perm-late,
2115 setlk, and setpgid cannot be applied. Some of these could be
2116 used on the first address though.
2117 pipes Creates a pair of unnamed pipes for interprocess communication
2119 instead of a socket pair.
2120 openpty
2122 Establishes communication with the sub process using a pseudo
2123 terminal created with openpty() instead of the default (socket‐
2124 pair or ptmx).
2125 ptmx Establishes communication with the sub process using a pseudo
2127 terminal created by opening /dev/ptmx or /dev/ptc instead of the
2128 default (socketpair).
2129 pty Establishes communication with the sub process using a pseudo
2131 terminal instead of a socket pair. Creates the pty with an
2132 available mechanism. If openpty and ptmx are both available, it
2133 uses ptmx because this is POSIX compliant (example).
2134 ctty Makes the pty the controlling tty of the sub process (example).
2136 stderr Directs stderr of the sub process to its output channel by mak‐
2138 ing stderr a dup() of stdout (example).
2139 fdin=<fdnum>
2141 Assigns the sub processes input channel to its file descriptor
2142 <fdnum> instead of stdin (0). The program started from the sub‐
2143 process has to use this fd for reading data from socat (exam‐
2144 ple).
2145 fdout=<fdnum>
2147 Assigns the sub processes output channel to its file descriptor
2148 <fdnum> instead of stdout (1). The program started from the sub‐
2149 process has to use this fd for writing data to socat (example).
2150 sighup, sigint, sigquit
2152 Has socat pass signals of this type to the sub process. If no
2153 address has this option, socat terminates on these signals.
2154 TERMIOS option group
2157 For addresses that work on a tty (e.g., stdio, file:/dev/tty,
2159 exec:...,pty), the terminal parameters defined in the UN*X termios
2160 mechanism are made available as address option parameters. Please note
2161 that changes of the parameters of your interactive terminal remain
2162 effective after socat’s termination, so you might have to enter "reset"
2163 or "stty sane" in your shell afterwards. For EXEC and SYSTEM addresses
2164 with option PTY, these options apply to the pty by the child processes.
2165 b0 Disconnects the terminal.
2167 b19200 Sets the serial line speed to 19200 baud. Some other rates are
2169 possible; use something like socat -hh |grep ’ b[1-9]’ to find
2170 all speeds supported by your implementation.
2171 Note: On some operating systems, these options may not be avail‐
2172 able. Use ispeed or ospeed instead.
2173 echo=<bool>
2175 Enables or disables local echo.
2176 icanon=<bool>
2178 Sets or clears canonical mode, enabling line buffering and some
2179 special characters.
2180 raw Sets raw mode, thus passing input and output almost unprocessed.
2182 This option is obsolete, use option rawer or cfmakeraw instead.
2183 rawer Makes terminal rawer than raw option. This option implicitly
2185 turns off echo. (example).
2186 cfmakeraw
2188 Sets raw mode by invoking cfmakeraw() or by simulating this
2189 call. This option implicitly turns off echo.
2190 ignbrk=<bool>
2192 Ignores or interpretes the BREAK character (e.g., ^C)
2193 brkint=<bool>
2195 bs0
2197 bs1
2199 bsdly=<0|1>
2201 clocal=<bool>
2203 cr0
2206 cr1
2207 cr2
2208 cr3
2209 Sets the carriage return delay to 0, 1, 2, or 3, respectively.
2211 0 means no delay, the other values are terminal dependent.
2212 crdly=<0|1|2|3>
2214 cread=<bool>
2216 crtscts=<bool>
2218 cs5
2221 cs6
2222 cs7
2223 cs8
2224 Sets the character size to 5, 6, 7, or 8 bits, respectively.
2226 csize=<0|1|2|3>
2228 cstopb=<bool>
2230 Sets two stop bits, rather than one.
2231 dsusp=<byte>
2233 Sets the value for the VDSUSP character that suspends the cur‐
2234 rent foreground process and reactivates the shell (all except
2235 Linux).
2236 echoctl=<bool>
2238 Echos control characters in hat notation (e.g. ^A)
2239 echoe=<bool>
2241 echok=<bool>
2243 echoke=<bool>
2245 echonl=<bool>
2247 echoprt=<bool>
2249 eof=<byte>
2251 eol=<byte>
2253 eol2=<byte>
2255 erase=<byte>
2257 discard=<byte>
2259 ff0
2261 ff1
2263 ffdly=<bool>
2265 flusho=<bool>
2267 hupcl=<bool>
2269 icrnl=<bool>
2271 iexten=<bool>
2273 igncr=<bool>
2275 ignpar=<bool>
2277 imaxbel=<bool>
2279 inlcr=<bool>
2281 inpck=<bool>
2283 intr=<byte>
2285 isig=<bool>
2287 ispeed=<unsigned-int>
2289 Set the baud rate for incoming data on this line.
2290 See also: ospeed, b19200
2291 istrip=<bool>
2293 iuclc=<bool>
2295 ixany=<bool>
2297 ixoff=<bool>
2299 ixon=<bool>
2301 kill=<byte>
2303 lnext=<byte>
2305 min=<byte>
2307 nl0 Sets the newline delay to 0.
2309 nl1
2311 nldly=<bool>
2313 noflsh=<bool>
2315 ocrnl=<bool>
2317 ofdel=<bool>
2319 ofill=<bool>
2321 olcuc=<bool>
2323 onlcr=<bool>
2325 onlret=<bool>
2327 onocr=<bool>
2329 opost=<bool>
2331 Enables or disables output processing; e.g., converts NL to
2332 CR-NL.
2333 ospeed=<unsigned-int>
2335 Set the baud rate for outgoing data on this line.
2336 See also: ispeed, b19200
2337 parenb=<bool>
2339 Enable parity generation on output and parity checking for
2340 input.
2341 parmrk=<bool>
2343 parodd=<bool>
2345 pendin=<bool>
2347 quit=<byte>
2349 reprint=<byte>
2351 sane Brings the terminal to something like a useful default state.
2353 start=<byte>
2355 stop=<byte>
2357 susp=<byte>
2359 swtc=<byte>
2361 tab0
2363 tab1
2365 tab2
2367 tab3
2369 tabdly=<unsigned-int>
2371 time=<byte>
2373 tostop=<bool>
2375 vt0
2377 vt1
2379 vtdly=<bool>
2381 werase=<byte>
2383 xcase=<bool>
2385 xtabs
2387 i-pop-all
2389 With UNIX System V STREAMS, removes all drivers from the stack.
2390 i-push=<string>
2392 With UNIX System V STREAMS, pushes the driver (module) with the
2393 given name (string) onto the stack. For example, to make sure
2394 that a character device on Solaris supports termios etc, use the
2395 following options:
2396 i-pop-all,i-push=ptem,i-push=ldterm,i-push=ttcompat
2397 PTY option group
2400 These options are intended for use with the pty address type.
2402 link=<filename>
2404 Generates a symbolic link that points to the actual pseudo ter‐
2405 minal (pty). This might help to solve the problem that ptys are
2406 generated with more or less unpredictable names, making it dif‐
2407 ficult to directly access the socat generated pty automatically.
2408 With this option, the user can specify a "fix" point in the file
2409 hierarchy that helps him to access the actual pty (example).
2410 Beginning with socat version 1.4.3, the symbolic link is removed
2411 when the address is closed (but see option unlink-close).
2412 wait-slave
2414 Blocks the open phase until a process opens the slave side of
2415 the pty. Usually, socat continues after generating the pty with
2416 opening the next address or with entering the transfer loop.
2417 With the wait-slave option, socat waits until some process opens
2418 the slave side of the pty before continuing. This option only
2419 works if the operating system provides the poll() system call.
2420 And it depends on an undocumented behaviour of pty’s, so it does
2421 not work on all operating systems. It has successfully been
2422 tested on Linux, FreeBSD, NetBSD, and on Tru64 with openpty.
2423 pty-interval=<seconds>
2425 When the wait-slave option is set, socat periodically checks the
2426 HUP condition using poll() to find if the pty’s slave side has
2427 been opened. The default polling interval is 1s. Use the
2428 pty-interval option [timeval] to change this value.
2429 OPENSSL option group
2432 These options apply to the openssl and openssl-listen address types.
2434 cipher=<cipherlist>
2436 Selects the list of ciphers that may be used for the connection.
2437 See the man page of ciphers , section CIPHER LIST FORMAT, for
2438 detailed information about syntax, values, and default of
2439 <cipherlist>.
2440 Several cipher strings may be given, separated by ’:’. Some
2441 simple cipher strings:
2442 3DES Uses a cipher suite with triple DES.
2444 MD5 Uses a cipher suite with MD5.
2446 aNULL Uses a cipher suite without authentication.
2448 NULL Does not use encryption.
2450 HIGH Uses a cipher suite with "high" encryption. Note that the peer
2452 must support the selected property, or the negotiation will
2453 fail.
2454 method=<ssl-method>
2456 This option is based on deprecated functions and is only avail‐
2457 able when socat was build with option --with-openssl-method.
2458 Sets the protocol version to be used. Valid strings (not case
2459 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 verify=<bool>
2475 Controls check of the peer’s certificate. Default is 1 (true).
2476 Disabling verify might open your socket for everyone, making the
2477 encryption useless!
2478 cert=<filename>
2480 Specifies the file with the certificate and private key for
2481 authentication. The certificate must be in OpenSSL format
2482 (*.pem). With openssl-listen, use of this option is strongly
2483 recommended. Except with cipher aNULL, "no shared ciphers" error
2484 will occur when no certificate is given.
2485 key=<filename>
2487 Specifies the file with the private key. The private key may be
2488 in this file or in the file given with the cert option. The
2489 party that has to proof that it is the owner of a certificate
2490 needs the private key.
2491 dhparams=<filename>
2493 Specifies the file with the Diffie Hellman parameters. These
2494 parameters may also be in the file given with the cert option in
2495 which case the dhparams option is not needed.
2496 cafile=<filename>
2498 Specifies the file with the trusted (root) authority certifi‐
2499 cates. The file must be in PEM format and should contain one or
2500 more certificates. The party that checks the authentication of
2501 its peer trusts only certificates that are in this file.
2502 capath=<dirname>
2504 Specifies the directory with the trusted (root) certificates.
2505 The directory must contain certificates in PEM format and their
2506 hashes (see OpenSSL documentation)
2507 egd=<filename>
2509 On some systems, openssl requires an explicit source of random
2510 data. Specify the socket name where an entropy gathering daemon
2511 like egd provides random data, e.g. /dev/egd-pool.
2512 pseudo On systems where openssl cannot find an entropy source and where
2514 no entropy gathering daemon can be utilized, this option acti‐
2515 vates a mechanism for providing pseudo entropy. This is achieved
2516 by taking the current time in microseconds for feeding the libc
2517 pseudo random number generator with an initial value. openssl is
2518 then feeded with output from random() calls.
2519 NOTE:This mechanism is not sufficient for generation of secure
2520 keys!
2521 compress
2523 Enable or disable the use of compression for a connection. Set‐
2524 ting this to "none" disables compression, setting it to "auto"
2525 lets OpenSSL choose the best available algorithm supported by
2526 both parties. The default is to not touch any compres‐
2527 sion-related settings. NOTE: Requires OpenSSL 0.9.8 or higher
2528 and disabling compression with OpenSSL 0.9.8 affects all new
2529 connections in the process.
2530 commonname=<string>
2532 Specify the commonname that the peer certificate must match.
2533 With OPENSSL-CONNECT address this overrides the given hostname
2534 or IP target address; with OPENSSL-LISTEN this turns on check of
2535 peer certificates commonname. This option has only meaning when
2536 option verify is not disabled and the chosen cipher provides a
2537 peer certificate.
2538 no-sni=<bool>
2540 Do not use the client side Server Name Indication (SNI) feature
2541 that selects the desired server certificate.
2542 Note: SNI is automatically used since socat version 1.7.4.0 and
2543 uses commonname or the given host name.
2544 snihost=<string>
2546 Set the client side Server Name Indication (SNI) host name dif‐
2547 ferent from the addressed server name or common name. This might
2548 be useful when the server certificate has multiple host names or
2549 wildcard names because the SNI host name is passed in cleartext
2550 to the server and might be eavesdropped; with this option a mock
2551 name of the desired certificate may be transferred.
2552 fips Enables FIPS mode if compiled in. For info about the FIPS
2554 encryption implementation standard see http://oss-insti‐
2555 tute.org/fips-faq.html. This mode might require that the
2556 involved certificates are generated with a FIPS enabled version
2557 of openssl. Setting or clearing this option on one socat address
2558 affects all OpenSSL addresses of this process.
2559 RETRY option group
2562 Options that control retry of some system calls, especially connection
2564 attempts.
2565 retry=<num>
2567 Number of retries before the connection or listen attempt is
2568 aborted. Default is 0, which means just one attempt.
2569 interval=<timespec>
2571 Time between consecutive attempts (seconds, [timespec]). Default
2572 is 1 second.
2573 forever
2575 Performs an unlimited number of retry attempts.
2576 TUN option group
2579 Options that control Linux TUN/TAP interface device addresses.
2581 tun-device=<device-file>
2583 Instructs socat to take another path for the TUN clone device.
2584 Default is /dev/net/tun.
2585 tun-name=<if-name>
2587 Gives the resulting network interface a specific name instead of
2588 the system generated (tun0, tun1, etc.)
2589 tun-type=[tun|tap]
2591 Sets the type of the TUN device; use this option to generate a
2592 TAP device. See the Linux docu for the difference between these
2593 types. When you try to establish a tunnel between two TUN
2594 devices, their types should be the same.
2595 iff-no-pi
2597 Sets the IFF_NO_PI flag which controls if the device includes
2598 additional packet information in the tunnel. When you try to
2599 establish a tunnel between two TUN devices, these flags should
2600 have the same values.
2601 iff-up Sets the TUN network interface status UP. Strongly recommended.
2603 iff-broadcast
2605 Sets the BROADCAST flag of the TUN network interface.
2606 iff-debug
2608 Sets the DEBUG flag of the TUN network interface.
2609 iff-loopback
2611 Sets the LOOPBACK flag of the TUN network interface.
2612 iff-pointopoint
2614 Sets the POINTOPOINT flag of the TUN device.
2615 iff-notrailers
2617 Sets the NOTRAILERS flag of the TUN device.
2618 iff-running
2620 Sets the RUNNING flag of the TUN device.
2621 iff-noarp
2623 Sets the NOARP flag of the TUN device.
2624 iff-promisc
2626 Sets the PROMISC flag of the TUN device.
2627 iff-allmulti
2629 Sets the ALLMULTI flag of the TUN device.
2630 iff-master
2632 Sets the MASTER flag of the TUN device.
2633 iff-slave
2635 Sets the SLAVE flag of the TUN device.
2636 iff-multicast
2638 Sets the MULTICAST flag of the TUN device.
2639 iff-portsel
2641 Sets the PORTSEL flag of the TUN device.
2642 iff-automedia
2644 Sets the AUTOMEDIA flag of the TUN device.
2645 iff-dynamic
2647 Sets the DYNAMIC flag of the TUN device.
2648
2651 This section explains the different data types that address parameters
2652 and address options can take.
2653 address-range
2655 Is currently only implemented for IPv4 and IPv6. See
2656 address-option `range’
2657 bool "0" or "1"; if value is omitted, "1" is taken.
2659 byte An unsigned int number, read with strtoul() , lower or equal to
2661 UCHAR_MAX .
2662 command-line
2664 A string specifying a program name and its arguments, separated
2665 by single spaces.
2666 data This is a more general data specification. The given text string
2668 contains information about the target data type and value. Gen‐
2669 erally a leading character specifies the type of the following
2670 data item. In its specific context a default data type may
2671 exist.
2672 Currently only the following specifications are implemented:
2673 i A signed integer number, stored in host byte order.
2675 Example: i-1000 (Integer number -1000)
2676 I An unsigned integer number, stored in host byte order.
2678 l A signed long integer number, stored in host byte order.
2680 L An unsigned long integer number, stored in host byte order.
2682 s A signed short integer number, stored in host byte order.
2684 S An unsigned short integer number, stored in host byte order.
2686 b A signed byte (signed char).
2688 B An unsigned byte (unsigned char).
2690 x Following is an even number of hex digits, stored as sequence of
2692 bytes.
2693 Example: x7f000001 (IP address 127.0.0.1)
2694 " Following is a string that is used with the common conversions
2696 \n \r \t \f \b \a \e \0; the string must be closed with ’"’.
2697 Please note that the quotes and backslashes need to be escaped
2698 from shell and socat conversion.
2699 Example: "Hello world!\n"
2700 ’ A single char, with the usual conversions. Please note that the
2702 quotes and backslashes need to be escaped from shell and socat
2703 conversion.
2704 Example: ’a’ Data items may be separated with white space
2705 without need to repeat the type specifier again.
2706 directory
2708 A string with usual UN*X directory name semantics.
2709 facility
2711 The name of a syslog facility in lower case characters.
2712 fdnum An unsigned int type, read with strtoul() , specifying a UN*X
2714 file descriptor.
2715 filename
2717 A string with usual UN*X filename semantics.
2718 group If the first character is a decimal digit, the value is read
2720 with strtoul() as unsigned integer specifying a group id. Other‐
2721 wise, it must be an existing group name.
2722 int A number following the rules of the strtol() function with base
2724 "0", i.e. decimal number, octal number with leading "0", or
2725 hexadecimal number with leading "0x". The value must fit into a
2726 C int.
2727 interface
2729 A string specifying the device name of a network interface as
2730 shown by ifconfig or procan, e.g. "eth0".
2731 IP address
2733 An IPv4 address in numbers-and-dots notation, an IPv6 address in
2734 hex notation enclosed in brackets, or a hostname that resolves
2735 to an IPv4 or an IPv6 address.
2736 Examples: 127.0.0.1, [::1], www.dest-unreach.org, dns1
2737 IPv4 address
2739 An IPv4 address in numbers-and-dots notation or a hostname that
2740 resolves to an IPv4 address.
2741 Examples: 127.0.0.1, www.dest-unreach.org, dns2
2742 IPv6 address
2744 An IPv6 address in hexnumbers-and-colons notation enclosed in
2745 brackets, or a hostname that resolves to an IPv6 address.
2746 Examples: [::1], [1234:5678:9abc:def0:1234:5678:9abc:def0],
2747 ip6name.domain.org
2748 long A number read with strtol() . The value must fit into a C long.
2750 long long
2752 A number read with strtoll() . The value must fit into a C long
2753 long.
2754 off_t An implementation dependend signed number, usually 32 bits, read
2756 with strtol or strtoll.
2757 off64_t
2759 An implementation dependend signed number, usually 64 bits, read
2760 with strtol or strtoll.
2761 mode_t An unsigned integer, read with strtoul() , specifying mode (per‐
2763 mission) bits.
2764 pid_t A number, read with strtol() , specifying a process id.
2766 port A uint16_t (16 bit unsigned number) specifying a TCP or UDP
2768 port, read with strtoul() .
2769 protocol
2771 An unsigned 8 bit number, read with strtoul() .
2772 size_t An unsigned number with size_t limitations, read with strtoul .
2774 sockname
2776 A socket address. See address-option `bind’
2777 string A sequence of characters, not containing ’\0’ and, depending on
2779 the position within the command line, ’:’, ’,’, or "!!". Note
2780 that you might have to escape shell meta characters in the com‐
2781 mand line.
2782 TCP service
2784 A service name, not starting with a digit, that is resolved by
2785 getservbyname() , or an unsigned int 16 bit number read with
2786 strtoul() .
2787 timeval
2789 A double float specifying seconds; the number is mapped into a
2790 struct timeval, consisting of seconds and microseconds.
2791 timespec
2793 A double float specifying seconds; the number is mapped into a
2794 struct timespec, consisting of seconds and nanoseconds.
2795 UDP service
2797 A service name, not starting with a digit, that is resolved by
2798 getservbyname() , or an unsigned int 16 bit number read with
2799 strtoul() .
2800 unsigned int
2802 A number read with strtoul() . The value must fit into a C
2803 unsigned int.
2804 user If the first character is a decimal digit, the value is read
2806 with strtoul() as unsigned integer specifying a user id. Other‐
2807 wise, it must be an existing user name.
2808 VSOCK cid
2810 A uint32_t (32 bit unsigned number) specifying a VSOCK Context
2811 Identifier (CID), read with strtoul() . There are several spe‐
2812 cial addresses: VMADDR_CID_ANY (-1U) means any address for bind‐
2813 ing; VMADDR_CID_HOST (2) is the well-known address of the host.
2814 VSOCK port
2816 A uint32_t (32 bit unsigned number) specifying a VSOCK port,
2817 read with strtoul() .
2818
2821 socat - TCP4:www.domain.org:80
2822 transfers data between STDIO (-) and a TCP4 connection to port
2825 80 of host www.domain.org. This example results in an interac‐
2826 tive connection similar to telnet or netcat. The stdin terminal
2827 parameters are not changed, so you may close the relay with ^D
2828 or abort it with ^C.
2829 socat -d -d READLINE,history=$HOME/.http_history \
2831 TCP4:www.domain.org:www,crnl
2832 this is similar to the previous example, but you can edit the
2834 current line in a bash like manner (READLINE) and use the his‐
2835 tory file .http_history; socat prints messages about progress
2836 (-d -d). The port is specified by service name (www), and cor‐
2837 rect network line termination characters (crnl) instead of NL
2838 are used.
2839 socat TCP4-LISTEN:www TCP4:www.domain.org:www
2841 installs a simple TCP port forwarder. With TCP4-LISTEN it lis‐
2844 tens on local port "www" until a connection comes in, accepts
2845 it, then connects to the remote host (TCP4) and starts data
2846 transfer. It will not accept a second connection.
2847 socat -d -d -lmlocal2 \
2849 TCP4-LISTEN:80,bind=myaddr1,reuseaddr,fork,su=nobody,range=10.0.0.0/8 \
2850 TCP4:www.domain.org:80,bind=myaddr2
2851 TCP port forwarder, each side bound to another local IP address
2853 (bind). This example handles an almost arbitrary number of par‐
2854 allel or consecutive connections by fork’ing a new process after
2855 each accept() . It provides a little security by su’ing to user
2856 nobody after forking; it only permits connections from the pri‐
2857 vate 10 network (range); due to reuseaddr, it allows immediate
2858 restart after master process’s termination, even if some child
2859 sockets are not completely shut down. With -lmlocal2, socat
2860 logs to stderr until successfully reaching the accept loop. Fur‐
2861 ther logging is directed to syslog with facility local2.
2862 socat TCP4-LISTEN:5555,fork,tcpwrap=script \
2864 EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr
2865 a simple server that accepts connections (TCP4-LISTEN) and
2867 fork’s a new child process for each connection; every child acts
2868 as single relay. The client must match the rules for daemon
2869 process name "script" in /etc/hosts.allow and /etc/hosts.deny,
2870 otherwise it is refused access (see "man 5 hosts_access"). For
2871 EXEC’uting the program, the child process chroot’s to
2872 /home/sandbox, su’s to user sandbox, and then starts the program
2873 /home/sandbox/bin/myscript. Socat and myscript communicate via a
2874 pseudo tty (pty); myscript’s stderr is redirected to stdout, so
2875 its error messages are transferred via socat to the connected
2876 client.
2877 socat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \
2879 TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512
2880 mail.sh is a shell script, distributed with socat, that imple‐
2882 ments a simple SMTP client. It is programmed to "speak" SMTP on
2883 its FDs 3 (in) and 4 (out). The fdin and fdout options tell
2884 socat to use these FDs for communication with the program.
2885 Because mail.sh inherits stdin and stdout while socat does not
2886 use them, the script can read a mail body from stdin. Socat
2887 makes alias1 your local source address (bind), cares for correct
2888 network line termination (crnl) and sends at most 512 data bytes
2889 per packet (mss).
2890 socat -,escape=0x0f /dev/ttyS0,rawer,crnl
2892 opens an interactive connection via the serial line, e.g. for
2895 talking with a modem. rawer sets the console’s and ttyS0’s ter‐
2896 minal parameters to practicable values, crnl converts to correct
2897 newline characters. escape allows terminating the socat process
2898 with character control-O. Consider using READLINE instead of
2899 the first address.
2900 socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
2902 SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20
2903 with UNIX-LISTEN, socat opens a listening UNIX domain socket
2905 /tmp/.X11-unix/X1. This path corresponds to local XWindow dis‐
2906 play :1 on your machine, so XWindow client connections to DIS‐
2907 PLAY=:1 are accepted. Socat then speaks with the SOCKS4 server
2908 host.victim.org that might permit sourceport 20 based connec‐
2909 tions due to an FTP related weakness in its static IP filters.
2910 Socat pretends to be invoked by socksuser nobody, and requests
2911 to be connected to loopback port 6000 (only weak sockd configu‐
2912 rations will allow this). So we get a connection to the victims
2913 XWindow server and, if it does not require MIT cookies or Ker‐
2914 beros authentication, we can start work. Please note that there
2915 can only be one connection at a time, because TCP can establish
2916 only one session with a given set of addresses and ports.
2917 socat -u /tmp/readdata,seek-end=0,ignoreeof -
2919 this is an example for unidirectional data transfer (-u). Socat
2922 transfers data from file /tmp/readdata (implicit address GOPEN),
2923 starting at its current end (seek-end=0 lets socat start reading
2924 at current end of file; use seek=0 or no seek option to first
2925 read the existing data) in a "tail -f" like mode (ignoreeof).
2926 The "file" might also be a listening UNIX domain socket (do not
2927 use a seek option then).
2928 (sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |
2930 socat - EXEC:'ssh -l user server',pty,setsid,ctty
2931 EXEC’utes an ssh session to server. Uses a pty for communication
2933 between socat and ssh, makes it ssh’s controlling tty (ctty),
2934 and makes this pty the owner of a new process group (setsid), so
2935 ssh accepts the password from socat.
2936 socat -u TCP4-LISTEN:3334,reuseaddr,fork \
2938 OPEN:/tmp/in.log,creat,append
2939 implements a simple network based message collector. For each
2941 client connecting to port 3334, a new child process is generated
2942 (option fork). All data sent by the clients are append’ed to
2943 the file /tmp/in.log. If the file does not exist, socat creat’s
2944 it. Option reuseaddr allows immediate restart of the server
2945 process.
2946 socat READLINE,noecho=’[Pp]assword:’ EXEC:’ftp ftp.server.com’,pty,set‐
2948 sid,ctty
2949 wraps a command line history (READLINE) around the EXEC’uted ftp
2952 client utility. This allows editing and reuse of FTP commands
2953 for relatively comfortable browsing through the ftp directory
2954 hierarchy. The password is echoed! pty is required to have ftp
2955 issue a prompt. Nevertheless, there may occur some confusion
2956 with the password and FTP prompts.
2957 socat PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \
2959 EXEC:"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"
2960 generates a pseudo terminal device (PTY) on the client that can
2962 be reached under the symbolic link $HOME/dev/vmodem0. An appli‐
2963 cation that expects a serial line or modem can be configured to
2964 use $HOME/dev/vmodem0; its traffic will be directed to a modem‐
2965 server via ssh where another socat instance links it to
2966 /dev/ttyS0.
2967 socat TCP4-LISTEN:2022,reuseaddr,fork \
2969 PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass
2970 starts a forwarder that accepts connections on port 2022, and
2972 directs them through the proxy daemon listening on port 3128
2973 (proxyport) on host proxy, using the CONNECT method, where they
2974 are authenticated as "user" with "pass" (proxyauth). The proxy
2975 should establish connections to host www.domain.org on port 22
2976 then.
2977 socat - SSL:server:4443,cafile=server.crt,cert=client.pem
2979 is an OpenSSL client that tries to establish a secure connection
2982 to an SSL server. Option cafile specifies a file that contains
2983 trust certificates: we trust the server only when it presents
2984 one of these certificates and proofs that it owns the related
2985 private key. Otherwise the connection is terminated. With cert
2986 a file containing the client certificate and the associated pri‐
2987 vate key is specified. This is required in case the server
2988 wishes a client authentication; many Internet servers do not.
2989 The first address (’-’) can be replaced by almost any other
2990 socat address.
2991 socat OPENSSL-LISTEN:4443,reuse‐
2993 addr,pf=ip4,fork,cert=server.pem,cafile=client.crt PIPE
2994 is an OpenSSL server that accepts TCP connections, presents the
2997 certificate from the file server.pem and forces the client to
2998 present a certificate that is verified against cafile.crt.
2999 The second address (’PIPE’) can be replaced by almost any other
3000 socat address.
3001 For instructions on generating and distributing OpenSSL keys and
3002 certificates see the additional socat docu socat-openssl.txt.
3003 echo |socat -u - file:/tmp/bigfile,create,largefile,seek=100000000000
3005 creates a 100GB sparse file; this requires a file system type
3008 that supports this (ext2, ext3, reiserfs, jfs; not minix, vfat).
3009 The operation of writing 1 byte might take long (reiserfs: some
3010 minutes; ext2: "no" time), and the resulting file can consume
3011 some disk space with just its inodes (reiserfs: 2MB; ext2:
3012 16KB).
3013 socat tcp-l:7777,reuseaddr,fork system:’filan -i 0 -s >&2’,nofork
3015 listens for incoming TCP connections on port 7777. For each
3018 accepted connection, invokes a shell. This shell has its stdin
3019 and stdout directly connected to the TCP socket (nofork). The
3020 shell starts filan and lets it print the socket addresses to
3021 stderr (your terminal window).
3022 echo -e "\0\14\0\0\c" |socat -u -
3024 file:/usr/bin/squid.exe,seek=0x00074420
3025 functions as primitive binary editor: it writes the 4 bytes 000
3028 014 000 000 to the executable /usr/bin/squid at offset
3029 0x00074420 (this is a real world patch to make the squid exe‐
3030 cutable from Cygwin run under Windows, actual per May 2004).
3031 socat - tcp:www.blackhat.org:31337,readbytes=1000
3033 connects to an unknown service and prevents being flooded.
3036 socat -U TCP:target:9999,end-close TCP-L:8888,reuseaddr,fork
3038 merges data arriving from different TCP streams on port 8888 to
3041 just one stream to target:9999. The end-close option prevents
3042 the child processes forked off by the second address from termi‐
3043 nating the shared connection to 9999 (close(2) just unlinks the
3044 inode which stays active as long as the parent process lives;
3045 shutdown(2) would actively terminate the connection).
3046 socat - UDP4-DATAGRAM:192.168.1.0:123,sp=123,broad‐
3048 cast,range=192.168.1.0/24
3049 sends a broadcast to the network 192.168.1.0/24 and receives the
3052 replies of the timeservers there. Ignores NTP packets from hosts
3053 outside this network.
3054 socat - SOCKET-DATA‐
3056 GRAM:2:2:17:x007bxc0a80100x0000000000000000,bind=x007bx00000000x0000000000000000,set‐
3057 sock‐
3058 opt-int=1:6:1,range=x0000xc0a80100x0000000000000000:x0000xffffff00x0000000000000000
3059 is semantically equivalent to the previous example, but all
3062 parameters are specified in generic form. the value 6 of set‐
3063 sockopt-int is the Linux value for SO_BROADCAST.
3064 socat - IP4-DATAGRAM:255.255.255.255:44,broadcast,range=10.0.0.0/8
3066 sends a broadcast to the local network(s) using protocol 44.
3069 Accepts replies from the private address range only.
3070 socat - UDP4-DATAGRAM:224.255.0.1:6666,bind=:6666,ip-add-member‐
3072 ship=224.255.0.1:eth0
3073 transfers data from stdin to the specified multicast address
3076 using UDP. Both local and remote ports are 6666. Tells the
3077 interface eth0 to also accept multicast packets of the given
3078 group. Multiple hosts on the local network can run this command,
3079 so all data sent by any of the hosts will be received by all the
3080 other ones. Note that there are many possible reasons for fail‐
3081 ure, including IP-filters, routing issues, wrong interface
3082 selection by the operating system, bridges, or a badly config‐
3083 ured switch.
3084 socat UDP:host2:4443 TUN:192.168.255.1/24,up
3086 establishes one side of a virtual (but not private!) network
3089 with host2 where a similar process might run, with UDP-L and tun
3090 address 192.168.255.2. They can reach each other using the
3091 addresses 192.168.255.1 and 192.168.255.2. Note that streaming
3092 eg.via TCP or SSL does not guarantee to retain packet boundaries
3093 and might thus cause packet loss.
3094 socat - VSOCK-CONNECT:2:1234
3096 establishes a VSOCK connection with the host (host is always
3099 reachable with the well-know CID=2) on 1234 port.
3100 socat - VSOCK-LISTEN:1234
3102 listens for a VSOCK connection on 1234 port.
3105 socat - VSOCK-CONNECT:31:4321,bind:5555
3107 establishes a VSOCK connection with the guest that have CID=31
3110 on 1234 port, binding the local socket to the 5555 port.
3111 socat VSOCK-LISTEN:3333,reuseaddr,fork VSOCK-CONNECT:42,3333
3113 starts a forwarder that accepts VSOCK connections on port 3333,
3116 and directs them to the guest with CID=42 on the same port.
3117 socat VSOCK-LISTEN:22,reuseaddr,fork TCP:localhost:22
3119 forwards VSOCK connections from 22 port to the local SSH server.
3122 Running this in a VM allows you to connect via SSH from the host
3123 using VSOCK, as in the example below.
3124 socat TCP4-LISTEN:22222,reuseaddr,fork VSOCK-CONNECT:33:22
3126 forwards TCP connections from 22222 port to the guest with
3129 CID=33 listening on VSOCK port 22. Running this in the host,
3130 allows you to connect via SSH running "ssh -p 22222 user@local‐
3131 host", if the guest runs the example above.
3132 socat PTY,link=/var/run/ppp,rawer INTERFACE:hdlc0
3134 circumvents the problem that pppd requires a serial device and
3137 thus might not be able to work on a synchronous line that is
3138 represented by a network device. socat creates a PTY to make
3139 pppd happy, binds to the network interface hdlc0, and can trans‐
3140 fer data between both devices. Use pppd on device /var/run/ppp
3141 then.
3142 socat -T 1 -d -d TCP-L:10081,reuseaddr,fork,crlf SYSTEM:"echo -e
3144 \"\\\"HTTP/1.0 200 OK\\\nDocumentType: text/plain\\\n\\\ndate:
3145 \$\(date\)\\\nserver:\$SOCAT_SOCKADDR:\$SOCAT_SOCKPORT\\\nclient:
3146 \$SOCAT_PEERADDR:\$SOCAT_PEERPORT\\\n\\\"\"; cat; echo -e
3147 \"\\\"\\\n\\\"\""
3148 creates a simple HTTP echo server: each HTTP client that con‐
3151 nects gets a valid HTTP reply that contains information about
3152 the client address and port as it is seen by the server host,
3153 the host address (which might vary on multihomed servers), and
3154 the original client request.
3155 socat -d -d UDP4-RECVFROM:9999,so-broadcast,so-timestamp,ip-pkt‐
3157 info,ip-recverr,ip-recvopts,ip-recvtos,ip-recvttl!!- SYSTEM:’export;
3158 sleep 1’ |grep SOCAT
3159 waits for an incoming UDP packet on port 9999 and prints the
3162 environment variables provided by socat. On BSD based systems
3163 you have to replace ip-pktinfo with ip-recvdstaddr,ip-recvif.
3164 Especially interesting is SOCAT_IP_DSTADDR: it contains the tar‐
3165 get address of the packet which may be a unicast, multicast, or
3166 broadcast address.
3167 echo -e "M-SEARCH * HTTP/1.1\nHOST: 239.255.255.250:1900\nMAN:
3169 \"ssdp:discover\"\nMX: 4\nST: \"ssdp:all\"\n" |./socat - UDP-DATA‐
3170 GRAM:239.255.255.250:1900,crlf
3171 sends an SSDP (Simple Service Discovery Protocol) query to the
3174 local network and collects and outputs the answers received.
3175
3180 Socat uses a logging mechanism that allows filtering messages by sever‐
3181 ity. The severities provided are more or less compatible to the appro‐
3182 priate syslog priority. With one or up to four occurrences of the -d
3183 command line option, the lowest priority of messages that are issued
3184 can be selected. Each message contains a single uppercase character
3185 specifying the messages severity (one of F, E, W, N, I, or D)
3186 FATAL: Conditions that require unconditional and immediate program ter‐
3188 mination.
3189 ERROR: Conditions that prevent proper program processing. Usually the
3191 program is terminated (see option -s).
3192 WARNING:
3194 Something did not function correctly or is in a state where cor‐
3195 rect further processing cannot be guaranteed, but might be pos‐
3196 sible.
3197 NOTICE:
3199 Interesting actions of the program, e.g. for supervising socat
3200 in some kind of server mode.
3201 INFO: Description of what the program does, and maybe why it happens.
3203 Allows monitoring the lifecycles of file descriptors.
3204 DEBUG: Description of how the program works, all system or library
3206 calls and their results.
3207 Log messages can be written to stderr, to a file, or to syslog.
3210 On exit, socat gives status 0 if it terminated due to EOF or inactivity
3212 timeout, with a positive value on error, and with a negative value on
3213 fatal error.
3214
3216 /usr/bin/socat
3217 /usr/bin/filan
3218 /usr/bin/procan
3219
3221 Input variables carry information from the environment to socat, output
3222 variables are set by socat for use in executed scripts and programs.
3223 In the output variables beginning with "SOCAT" this prefix is actually
3225 replaced by the upper case name of the executable or the value of
3226 option -lp.
3227 SOCAT_DEFAULT_LISTEN_IP (input)
3229 (Values 4 or 6) Sets the IP version to be used for listen, recv,
3230 and recvfrom addresses if no pf (protocol-family) option is
3231 given. Is overridden by socat options -4 or -6.
3232 SOCAT_PREFERRED_RESOLVE_IP (input)
3234 (Values 0, 4, or 6) Sets the IP version to be used when resolv‐
3235 ing target host names when version is not specified by address
3236 type, option pf (protocol-family), or address format. If name
3237 resolution does not return a matching entry, the first result
3238 (with differing IP version) is taken. With value 0, socat always
3239 selects the first record and its IP version.
3240 SOCAT_FORK_WAIT (input)
3242 Specifies the time (seconds) to sleep the parent and child pro‐
3243 cesses after successful fork(). Useful for debugging.
3244 SOCAT_VERSION (output)
3246 Socat sets this variable to its version string, e.g. "1.7.0.0"
3247 for released versions or e.g. "1.6.0.1+envvar" for temporary
3248 versions; can be used in scripts invoked by socat.
3249 SOCAT_PID (output)
3251 Socat sets this variable to its process id. In case of fork
3252 address option, SOCAT_PID gets the child processes id. Forking
3253 for exec and system does not change SOCAT_PID.
3254 SOCAT_PPID (output)
3256 Socat sets this variable to its process id. In case of fork,
3257 SOCAT_PPID keeps the pid of the master process.
3258 SOCAT_PEERADDR (output)
3260 With passive socket addresses (all LISTEN and RECVFROM
3261 addresses), this variable is set to a string describing the
3262 peers socket address. Port information is not included.
3263 SOCAT_PEERPORT (output)
3265 With appropriate passive socket addresses (TCP, UDP, and SCTP -
3266 LISTEN and RECVFROM), this variable is set to a string contain‐
3267 ing the number of the peer port.
3268 SOCAT_SOCKADDR (output)
3270 With all LISTEN addresses, this variable is set to a string
3271 describing the local socket address. Port information is not
3272 included example
3273 SOCAT_SOCKPORT (output)
3275 With TCP-LISTEN, UDP-LISTEN, and SCTP-LISTEN addresses, this
3276 variable is set to the local port.
3277 SOCAT_TIMESTAMP (output)
3279 With all RECVFROM addresses where address option so-timestamp is
3280 applied, socat sets this variable to the resulting timestamp.
3281 SOCAT_IP_OPTIONS (output)
3283 With all IPv4 based RECVFROM addresses where address option
3284 ip-recvopts is applied, socat fills this variable with the IP
3285 options of the received packet.
3286 SOCAT_IP_DSTADDR (output)
3288 With all IPv4 based RECVFROM addresses where address option
3289 ip-recvdstaddr (BSD) or ip-pktinfo (other platforms) is applied,
3290 socat sets this variable to the destination address of the
3291 received packet. This is particularly useful to identify broad‐
3292 cast and multicast addressed packets.
3293 SOCAT_IP_IF (output)
3295 With all IPv4 based RECVFROM addresses where address option
3296 ip-recvif (BSD) or ip-pktinfo (other platforms) is applied,
3297 socat sets this variable to the name of the interface where the
3298 packet was received.
3299 SOCAT_IP_LOCADDR (output)
3301 With all IPv4 based RECVFROM addresses where address option
3302 ip-pktinfo is applied, socat sets this variable to the address
3303 of the interface where the packet was received.
3304 SOCAT_IP_TOS (output)
3306 With all IPv4 based RECVFROM addresses where address option
3307 ip-recvtos is applied, socat sets this variable to the TOS (type
3308 of service) of the received packet.
3309 SOCAT_IP_TTL (output)
3311 With all IPv4 based RECVFROM addresses where address option
3312 ip-recvttl is applied, socat sets this variable to the TTL (time
3313 to live) of the received packet.
3314 SOCAT_IPV6_HOPLIMIT (output)
3316 With all IPv6 based RECVFROM addresses where address option
3317 ipv6-recvhoplimit is applied, socat sets this variable to the
3318 hoplimit value of the received packet.
3319 SOCAT_IPV6_DSTADDR (output)
3321 With all IPv6 based RECVFROM addresses where address option
3322 ipv6-recvpktinfo is applied, socat sets this variable to the
3323 destination address of the received packet.
3324 SOCAT_IPV6_TCLASS (output)
3326 With all IPv6 based RECVFROM addresses where address option
3327 ipv6-recvtclass is applied, socat sets this variable to the
3328 transfer class of the received packet.
3329 SOCAT_OPENSSL_X509_ISSUER (output)
3331 Issuer field from peer certificate
3332 SOCAT_OPENSSL_X509_SUBJECT (output)
3334 Subject field from peer certificate
3335 SOCAT_OPENSSL_X509_COMMONNAME (output)
3337 commonName entries from peer certificates subject. Multiple val‐
3338 ues are separated by " // ".
3339 SOCAT_OPENSSL_X509_* (output)
3341 all other entries from peer certificates subject
3342 SOCAT_OPENSSL_X509V3_DNS (output)
3344 DNS entries from peer certificates extensions - subjectAltName
3345 field. Multiple values are separated by " // ".
3346 HOSTNAME (input)
3348 Is used to determine the hostname for logging (see -lh).
3349 LOGNAME (input)
3351 Is used as name for the socks client user name if no socksuser
3352 is given.
3353 With options su and su-d, LOGNAME is set to the given user name.
3354 USER (input)
3356 Is used as name for the socks client user name if no socksuser
3357 is given and LOGNAME is empty.
3358 With options su and su-d, USER is set to the given user name.
3359 SHELL (output)
3361 With options su and su-d, SHELL is set to the login shell of the
3362 given user.
3363 PATH (output)
3365 Can be set with option path for exec and system addresses.
3366 HOME (output)
3368 With options su and su-d, HOME is set to the home directory of
3369 the given user.
3370
3372 The work of the following groups and organizations was invaluable for
3373 this project:
3374 The FSF (GNU, http://www.fsf.org/ project with their free and portable
3376 development software and lots of other useful tools and libraries.
3377 The Linux developers community (http://www.linux.org/) for providing a
3379 free, open source operating system.
3380 The Open Group (http://www.unix-systems.org/) for making their standard
3382 specifications available on the Internet for free.
3383
3385 This man page describes version 1.7.4 of socat.
3386
3388 Addresses cannot be nested, so a single socat process cannot, e.g.,
3389 drive ssl over socks.
3390 Address option ftruncate without value uses default 1 instead of 0.
3392 Verbose modes (-x and/or -v) display line termination characters incon‐
3394 sistently when address options cr or crnl are used: They show the data
3395 after conversion in either direction.
3396 The data transfer blocksize setting (-b) is ignored with address read‐
3398 line.
3399 Send bug reports to <socat@dest-unreach.org>
3401
3403 nc(1), rinetd(8), openssl(1), stunnel(8), rlwrap(1), setsid(1)
3404 Socat home page http://www.dest-unreach.org/socat/
3406
3408 Gerhard Rieger <rieger@dest-unreach.org> and contributors
3409 socat(1)