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 -b<size>
137 Sets the data transfer block <size> [size_t]. At most <size>
138 bytes are transferred per step. Default is 8192 bytes.
139 -s By default, socat terminates when an error occurred to prevent
141 the process from running when some option could not be applied.
142 With this option, socat is sloppy with errors and tries to con‐
143 tinue. Even with this option, socat will exit on fatals, and
144 will abort connection attempts when security checks failed.
145 -t<timeout>
147 When one channel has reached EOF, the write part of the other
148 channel is shut down. Then, socat waits <timeout> [timeval] sec‐
149 onds before terminating. Default is 0.5 seconds. This timeout
150 only applies to addresses where write and read part can be
151 closed independently. When during the timeout interval the read
152 part gives EOF, socat terminates without awaiting the timeout.
153 -T<timeout>
155 Total inactivity timeout: when socat is already in the transfer
156 loop and nothing has happened for <timeout> [timeval] seconds
157 (no data arrived, no interrupt occurred...) then it terminates.
158 Useful with protocols like UDP that cannot transfer EOF.
159 -u Uses unidirectional mode. The first address is only used for
161 reading, and the second address is only used for writing (exam‐
162 ple).
163 -U Uses unidirectional mode in reverse direction. The first address
165 is only used for writing, and the second address is only used
166 for reading.
167 -g During address option parsing, don’t check if the option is con‐
169 sidered useful in the given address environment. Use it if you
170 want to force, e.g., appliance of a socket option to a serial
171 device.
172 -L<lockfile>
174 If lockfile exists, exits with error. If lockfile does not
175 exist, creates it and continues, unlinks lockfile on exit.
176 -W<lockfile>
178 If lockfile exists, waits until it disappears. When lockfile
179 does not exist, creates it and continues, unlinks lockfile on
180 exit.
181 -4 Use IP version 4 in case that the addresses do not implicitly or
183 explicitly specify a version; this is the default.
184 -6 Use IP version 6 in case that the addresses do not implicitly or
186 explicitly specify a version.
187
190 With the address command line arguments, the user gives socat instruc‐
191 tions and the necessary information for establishing the byte streams.
192 An address specification usually consists of an address type keyword,
194 zero or more required address parameters separated by ’:’ from the key‐
195 word and from each other, and zero or more address options separated by
196 ’,’.
197 The keyword specifies the address type (e.g., TCP4, OPEN, EXEC). For
199 some keywords there exist synonyms (’-’ for STDIO, TCP for TCP4). Key‐
200 words are case insensitive. For a few special address types, the key‐
201 word may be omitted: Address specifications starting with a number are
202 assumed to be FD (raw file descriptor) addresses; if a ’/’ is found
203 before the first ’:’ or ’,’, GOPEN (generic file open) is assumed.
204 The required number and type of address parameters depend on the
206 address type. E.g., TCP4 requires a server specification (name or
207 address), and a port specification (number or service name).
208 Zero or more address options may be given with each address. They
210 influence the address in some ways. Options consist of an option key‐
211 word or an option keyword and a value, separated by ’=’. Option key‐
212 words are case insensitive. For filtering the options that are useful
213 with an address type, each option is member of one option group. For
214 each address type there is a set of option groups allowed. Only options
215 belonging to one of these address groups may be used (except with
216 option -g).
217 Address specifications following the above schema are also called sin‐
219 gle address specifications. Two single addresses can be combined with
220 "!!" to form a dual type address for one channel. Here, the first
221 address is used by socat for reading data, and the second address for
222 writing data. There is no way to specify an option only once for being
223 applied to both single addresses.
224 Usually, addresses are opened in read/write mode. When an address is
226 part of a dual address specification, or when option -u or -U is used,
227 an address might be used only for reading or for writing. Considering
228 this is important with some address types.
229 With socat version 1.5.0 and higher, the lexical analysis tries to han‐
231 dle quotes and parenthesis meaningfully and allows escaping of special
232 characters. If one of the characters ( { [ ’ is found, the correspond‐
233 ing closing character - ) } ] ’ - is looked for; they may also be
234 nested. Within these constructs, socats special characters and strings
235 : , !! are not handled specially. All those characters and strings can
236 be escaped with \ or within ""
237
239 This section describes the available address types with their keywords,
240 parameters, and semantics.
241 CREATE:<filename>
243 Opens <filename> with creat() and uses the file descriptor for
244 writing. This address type requires write-only context, because
245 a file opened with creat cannot be read from.
246 Flags like O_LARGEFILE cannot be applied. If you need them use
247 OPEN with options create,create.
248 <filename> must be a valid existing or not existing path. If
249 <filename> is a named pipe, creat() might block; if <filename>
250 refers to a socket, this is an error.
251 Option groups: FD,REG,NAMED
252 Useful options: mode, user, group, unlink-early, unlink-late,
253 append
254 See also: OPEN, GOPEN
255 EXEC:<command-line>
257 Forks a sub process that establishes communication with its par‐
258 ent process and invokes the specified program with execvp() .
259 <command-line> is a simple command with arguments separated by
260 single spaces. If the program name contains a ’/’, the part
261 after the last ’/’ is taken as ARGV[0]. If the program name is a
262 relative path, the execvp() semantics for finding the program
263 via $PATH apply. After successful program start, socat writes
264 data to stdin of the process and reads from its stdout using a
265 UNIX domain socket generated by socketpair() per default. (exam‐
266 ple)
267 Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
268 Useful options: path, fdin, fdout, chroot, su, su-d, nofork,
269 pty, stderr, ctty, setsid, pipes, login, sigint, sigquit
270 See also: SYSTEM
271 FD:<fdnum>
273 Uses the file descriptor <fdnum>. It must already exist as valid
274 UN*X file descriptor.
275 Option groups: FD (TERMIOS,REG,SOCKET)
276 See also: STDIO, STDIN, STDOUT, STDERR
277 GOPEN:<filename>
279 (Generic open) This address type tries to handle any file system
280 entry except directories usefully. <filename> may be a relative
281 or absolute path. If it already exists, its type is checked. In
282 case of a UNIX domain socket, socat connects; if connecting
283 fails, socat assumes a datagram socket and uses sendto() calls.
284 If the entry is not a socket, socat opens it applying the
285 O_APPEND flag. If it does not exist, it is opened with flag
286 O_CREAT as a regular file (example).
287 Option groups: FD,REG,SOCKET,NAMED,OPEN
288 See also: OPEN, CREATE, UNIX-CONNECT
289 IP-SENDTO:<host>:<protocol>
291 Opens a raw IP socket. Depending on host specification or option
292 pf, IP protocol version 4 or 6 is used. It uses <protocol> to
293 send packets to <host> [IP address] and receives packets from
294 host, ignores packets from other hosts. Protocol 255 uses the
295 raw socket with the IP header being part of the data.
296 Option groups: FD,SOCKET,IP4,IP6
297 Useful options: pf, ttl
298 See also: IP4-SENDTO, IP6-SENDTO, IP-RECVFROM, IP-RECV,
299 UDP-SENDTO, UNIX-SENDTO
300 INTERFACE:<interface>
302 Communicates with a network connected on an interface using raw
303 packets including link level data. <interface> is the name of
304 the network interface. Currently only available on Linux.
305 Option groups: FD,SOCKET
306 Useful options: pf, type
307 See also: ip-recv
308 IP4-SENDTO:<host>:<protocol>
310 Like IP-SENDTO, but always uses IPv4.
311 Option groups: FD,SOCKET,IP4
312 IP6-SENDTO:<host>:<protocol>
314 Like IP-SENDTO, but always uses IPv6.
315 Option groups: FD,SOCKET,IP6
316 IP-DATAGRAM:<address>:<protocol>
319 Sends outgoing data to the specified address which may in par‐
320 ticular be a broadcast or multicast address. Packets arriving on
321 the local socket are checked if their source addresses match
322 RANGE or TCPWRAP options. This address type can for example be
323 used for implementing symmetric or asymmetric broadcast or mul‐
324 ticast communications.
325 Option groups: FD, SOCKET, IP4, IP6, RANGE
326 Useful options: bind, range, tcpwrap, broadcast, ip-multi‐
327 cast-loop, ip-multicast-ttl, ip-multicast-if, ip-add-membership,
328 ttl, tos, pf
329 See also: IP4-DATAGRAM, IP6-DATAGRAM, IP-SENDTO, IP-RECVFROM,
330 IP-RECV, UDP-DATAGRAM
331 IP4-DATAGRAM:<host>:<protocol>
333 Like IP-DATAGRAM, but always uses IPv4. (example)
334 Option groups: FD,SOCKET,IP4,RANGE
335 IP6-DATAGRAM:<host>:<protocol>
337 Like IP-DATAGRAM, but always uses IPv6. Please note that IPv6
338 does not know broadcasts.
339 Option groups: FD,SOCKET,IP6,RANGE
340 IP-RECVFROM:<protocol>
343 Opens a raw IP socket of <protocol>. Depending on option pf, IP
344 protocol version 4 or 6 is used. It receives one packet from an
345 unspecified peer and may send one or more answer packets to that
346 peer. This mode is particularly useful with fork option where
347 each arriving packet - from arbitrary peers - is handled by its
348 own sub process. This allows a behaviour similar to typical UDP
349 based servers like ntpd or named.
350 Please note that the reply packets might be fetched as incoming
351 traffic when sender and receiver IP address are identical
352 because there is no port number to distinguish the sockets.
353 This address works well with IP-SENDTO address peers (see
354 above). Protocol 255 uses the raw socket with the IP header
355 being part of the data.
356 Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
357 Useful options: pf, fork, range, ttl, broadcast
358 See also: IP4-RECVFROM, IP6-RECVFROM, IP-SENDTO, IP-RECV,
359 UDP-RECVFROM, UNIX-RECVFROM
360 IP4-RECVFROM:<protocol>
362 Like IP-RECVFROM, but always uses IPv4.
363 Option groups: FD,SOCKET,IP4,CHILD,RANGE
364 IP6-RECVFROM:<protocol>
366 Like IP-RECVFROM, but always uses IPv6.
367 Option groups: FD,SOCKET,IP6,CHILD,RANGE
368 IP-RECV:<protocol>
371 Opens a raw IP socket of <protocol>. Depending on option pf, IP
372 protocol version 4 or 6 is used. It receives packets from multi‐
373 ple unspecified peers and merges the data. No replies are pos‐
374 sible. It can be, e.g., addressed by socat IP-SENDTO address
375 peers. Protocol 255 uses the raw socket with the IP header
376 being part of the data.
377 Option groups: FD,SOCKET,IP4,IP6,RANGE
378 Useful options: pf, range
379 See also: IP4-RECV, IP6-RECV, IP-SENDTO, IP-RECVFROM, UDP-RECV,
380 UNIX-RECV
381 IP4-RECV:<protocol>
383 Like IP-RECV, but always uses IPv4.
384 Option groups: FD,SOCKET,IP4,RANGE
385 IP6-RECV:<protocol>
387 Like IP-RECV, but always uses IPv6.
388 Option groups: FD,SOCKET,IP6,RANGE
389 OPEN:<filename>
392 Opens <filename> using the open() system call (example). This
393 operation fails on UNIX domain sockets.
394 Note: This address type is rarely useful in bidirectional mode.
395 Option groups: FD,REG,NAMED,OPEN
396 Useful options: creat, excl, noatime, nofollow, append, rdonly,
397 wronly, lock, readbytes, ignoreeof
398 See also: CREATE, GOPEN, UNIX-CONNECT
399 OPENSSL:<host>:<port>
401 Tries to establish a SSL connection to <port> [TCP service] on
402 <host> [IP address] using TCP/IP version 4 or 6 depending on
403 address specification, name resolution, or option pf.
404 NOTE: Up to version 1.7.2.4 the server certificate was only
405 checked for validity against the system certificate store or
406 cafile or capath, but not for match with the server’s name or
407 its IP address. Since version 1.7.3.0 socat checks the peer
408 certificate for match with the <host> parameter or the value of
409 the openssl-commonname option. Socat tries to match it against
410 the certificates subject commonName, and the certifications
411 extension subjectAltName DNS names. Wildcards in the certificate
412 are supported.
413 Option groups: FD,SOCKET,IP4,IP6,TCP,OPENSSL,RETRY
414 Useful options: cipher, verify, commonname, cafile, capath, cer‐
415 tificate, key, compress, bind, pf, connect-timeout, sourceport,
416 retry
417 See also: OPENSSL-LISTEN, TCP
418 OPENSSL-LISTEN:<port>
420 Listens on tcp <port> [TCP service]. The IP version is 4 or the
421 one specified with pf. When a connection is accepted, this
422 address behaves as SSL server.
423 Note: You probably want to use the certificate option with this
424 address.
425 NOTE: The client certificate is only checked for validity
426 against cafile or capath, but not for match with the client’s
427 name or its IP address!
428 Option groups: FD,SOCKET,IP4,IP6,TCP,LIS‐
429 TEN,OPENSSL,CHILD,RANGE,RETRY
430 Useful options: pf, cipher, verify, commonname, cafile, capath,
431 certificate, key, compress, fork, bind, range, tcpwrap, su,
432 reuseaddr, retry
433 See also: OPENSSL, TCP-LISTEN
434 PIPE:<filename>
436 If <filename> already exists, it is opened. If it does not
437 exist, a named pipe is created and opened. Beginning with socat
438 version 1.4.3, the named pipe is removed when the address is
439 closed (but see option unlink-close
440 Note: When a pipe is used for both reading and writing, it works
441 as echo service.
442 Note: When a pipe is used for both reading and writing, and
443 socat tries to write more bytes than the pipe can buffer (Linux
444 2.4: 2048 bytes), socat might block. Consider using socat
445 option, e.g., -b 2048
446 Option groups: FD,NAMED,OPEN
447 Useful options: rdonly, nonblock, group, user, mode,
448 unlink-early
449 See also: unnamed pipe
450 PIPE Creates an unnamed pipe and uses it for reading and writing. It
452 works as an echo, because everything written to it appeares
453 immediately as read data.
454 Note: When socat tries to write more bytes than the pipe can
455 queue (Linux 2.4: 2048 bytes), socat might block. Consider,
456 e.g., using option -b 2048
457 Option groups: FD
458 See also: named pipe
459 PROXY:<proxy>:<hostname>:<port>
461 Connects to an HTTP proxy server on port 8080 using TCP/IP ver‐
462 sion 4 or 6 depending on address specification, name resolution,
463 or option pf, and sends a CONNECT request for hostname:port. If
464 the proxy grants access and succeeds to connect to the target,
465 data transfer between socat and the target can start. Note that
466 the traffic need not be HTTP but can be an arbitrary protocol.
467 Option groups: FD,SOCKET,IP4,IP6,TCP,HTTP,RETRY
468 Useful options: proxyport, ignorecr, proxyauth, resolve, crnl,
469 bind, connect-timeout, mss, sourceport, retry
470 See also: SOCKS, TCP
471 PTY Generates a pseudo terminal (pty) and uses its master side.
473 Another process may open the pty’s slave side using it like a
474 serial line or terminal. (example). If both the ptmx and the
475 openpty mechanisms are available, ptmx is used (POSIX).
476 Option groups: FD,NAMED,PTY,TERMIOS
477 Useful options: link, openpty, wait-slave, mode, user, group
478 See also: UNIX-LISTEN, PIPE, EXEC, SYSTEM
479 READLINE
481 Uses GNU readline and history on stdio to allow editing and
482 reusing input lines (example). This requires the GNU readline
483 and history libraries. Note that stdio should be a (pseudo) ter‐
484 minal device, otherwise readline does not seem to work.
485 Option groups: FD,READLINE,TERMIOS
486 Useful options: history, noecho
487 See also: STDIO
488 SCTP-CONNECT:<host>:<port>
490 Establishes an SCTP stream connection to the specified <host>
491 [IP address] and <port> [TCP service] using IP version 4 or 6
492 depending on address specification, name resolution, or option
493 pf.
494 Option groups: FD,SOCKET,IP4,IP6,SCTP,CHILD,RETRY
495 Useful options: bind, pf, connect-timeout, tos, mtudiscover,
496 sctp-maxseg, sctp-nodelay, nonblock, sourceport, retry, read‐
497 bytes
498 See also: SCTP4-CONNECT, SCTP6-CONNECT, SCTP-LISTEN, TCP-CONNECT
499 SCTP4-CONNECT:<host>:<port>
501 Like SCTP-CONNECT, but only supports IPv4 protocol.
502 Option groups: FD,SOCKET,IP4,SCTP,CHILD,RETRY
503 SCTP6-CONNECT:<host>:<port>
505 Like SCTP-CONNECT, but only supports IPv6 protocol.
506 Option groups: FD,SOCKET,IP6,SCTP,CHILD,RETRY
507 SCTP-LISTEN:<port>
509 Listens on <port> [TCP service] and accepts an SCTP connection.
510 The IP version is 4 or the one specified with address option pf,
511 socat option (-4, -6), or environment variable
512 SOCAT_DEFAULT_LISTEN_IP. Note that opening this address usually
513 blocks until a client connects.
514 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,SCTP,RETRY
515 Useful options: crnl, fork, bind, range, tcpwrap, pf, max-chil‐
516 dren, backlog, sctp-maxseg, sctp-nodelay, su, reuseaddr, retry,
517 cool-write
518 See also: SCTP4-LISTEN, SCTP6-LISTEN, TCP-LISTEN, SCTP-CONNECT
519 SCTP4-LISTEN:<port>
521 Like SCTP-LISTEN, but only supports IPv4 protocol.
522 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,SCTP,RETRY
523 SCTP6-LISTEN:<port>
525 Like SCTP-LISTEN, but only supports IPv6 protocol.
526 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,SCTP,RETRY
527 SOCKET-CONNECT:<domain>:<protocol>:<remote-address>
529 Creates a stream socket using the first and second given socket
530 parameters and SOCK_STREAM (see man socket(2)) and connects to
531 the remote-address. The two socket parameters have to be speci‐
532 fied by int numbers. Consult your OS documentation and include
533 files to find the appropriate values. The remote-address must be
534 the data representation of a sockaddr structure without sa_fam‐
535 ily and (BSD) sa_len components.
536 Please note that you can - beyond the options of the specified
537 groups - also use options of higher level protocols when you
538 apply socat option -g.
539 Option groups: FD,SOCKET,CHILD,RETRY
540 Useful options: bind, setsockopt-int, setsockopt-bin, setsock‐
541 opt-string
542 See also: TCP, UDP-CONNECT, UNIX-CONNECT, SOCKET-LISTEN,
543 SOCKET-SENDTO
544 SOCKET-DATAGRAM:<domain>:<type>:<protocol>:<remote-address>
546 Creates a datagram socket using the first three given socket
547 parameters (see man socket(2)) and sends outgoing data to the
548 remote-address. The three socket parameters have to be specified
549 by int numbers. Consult your OS documentation and include files
550 to find the appropriate values. The remote-address must be the
551 data representation of a sockaddr structure without sa_family
552 and (BSD) sa_len components.
553 Please note that you can - beyond the options of the specified
554 groups - also use options of higher level protocols when you
555 apply socat option -g.
556 Option groups: FD,SOCKET,RANGE
557 Useful options: bind, range, setsockopt-int, setsockopt-bin,
558 setsockopt-string
559 See also: UDP-DATAGRAM, IP-DATAGRAM, SOCKET-SENDTO, SOCKET-RECV,
560 SOCKET-RECVFROM
561 SOCKET-LISTEN:<domain>:<protocol>:<local-address>
563 Creates a stream socket using the first and second given socket
564 parameters and SOCK_STREAM (see man socket(2)) and waits for
565 incoming connections on local-address. The two socket parameters
566 have to be specified by int numbers. Consult your OS documenta‐
567 tion and include files to find the appropriate values. The
568 local-address must be the data representation of a sockaddr
569 structure without sa_family and (BSD) sa_len components.
570 Please note that you can - beyond the options of the specified
571 groups - also use options of higher level protocols when you
572 apply socat option -g.
573 Option groups: FD,SOCKET,LISTEN,RANGE,CHILD,RETRY
574 Useful options: setsockopt-int, setsockopt-bin, setsock‐
575 opt-string
576 See also: TCP, UDP-CONNECT, UNIX-CONNECT, SOCKET-LISTEN,
577 SOCKET-SENDTO, SOCKET-SENDTO
578 SOCKET-RECV:<domain>:<type>:<protocol>:<local-address>
580 Creates a socket using the three given socket parameters (see
581 man socket(2)) and binds it to <local-address>. Receives arriv‐
582 ing data. The three parameters have to be specified by int num‐
583 bers. Consult your OS documentation and include files to find
584 the appropriate values. The local-address must be the data rep‐
585 resentation of a sockaddr structure without sa_family and (BSD)
586 sa_len components.
587 Option groups: FD,SOCKET,RANGE
588 Useful options: range, setsockopt-int, setsockopt-bin, setsock‐
589 opt-string
590 See also: UDP-RECV, IP-RECV, UNIX-RECV, SOCKET-DATAGRAM,
591 SOCKET-SENDTO, SOCKET-RECVFROM
592 SOCKET-RECVFROM:<domain>:<type>:<protocol>:<local-address>
594 Creates a socket using the three given socket parameters (see
595 man socket(2)) and binds it to <local-address>. Receives arriv‐
596 ing data and sends replies back to the sender. The first three
597 parameters have to be specified as int numbers. Consult your OS
598 documentation and include files to find the appropriate values.
599 The local-address must be the data representation of a sockaddr
600 structure without sa_family and (BSD) sa_len components.
601 Option groups: FD,SOCKET,CHILD,RANGE
602 Useful options: fork, range, setsockopt-int, setsockopt-bin,
603 setsockopt-string
604 See also: UDP-RECVFROM, IP-RECVFROM, UNIX-RECVFROM, SOCKET-DATA‐
605 GRAM, SOCKET-SENDTO, SOCKET-RECV
606 SOCKET-SENDTO:<domain>:<type>:<protocol>:<remote-address>
608 Creates a socket using the three given socket parameters (see
609 man socket(2)). Sends outgoing data to the given address and
610 receives replies. The three parameters have to be specified as
611 int numbers. Consult your OS documentation and include files to
612 find the appropriate values. The remote-address must be the data
613 representation of a sockaddr structure without sa_family and
614 (BSD) sa_len components.
615 Option groups: FD,SOCKET
616 Useful options: bind, setsockopt-int, setsockopt-bin, setsock‐
617 opt-string
618 See also: UDP-SENDTO, IP-SENDTO, UNIX-SENDTO, SOCKET-DATAGRAM,
619 SOCKET-RECV SOCKET-RECVFROM
620 SOCKS4:<socks-server>:<host>:<port>
622 Connects via <socks-server> [IP address] to <host> [IPv4
623 address] on <port> [TCP service], using socks version 4 protocol
624 over IP version 4 or 6 depending on address specification, name
625 resolution, or option pf (example).
626 Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
627 Useful options: socksuser, socksport, sourceport, pf, retry
628 See also: SOCKS4A, PROXY, TCP
629 SOCKS4A:<socks-server>:<host>:<port>
631 like SOCKS4, but uses socks protocol version 4a, thus leaving
632 host name resolution to the socks server.
633 Option groups: FD,SOCKET,IP4,IP6,TCP,SOCKS4,RETRY
634 STDERR Uses file descriptor 2.
636 Option groups: FD (TERMIOS,REG,SOCKET)
637 See also: FD
638 STDIN Uses file descriptor 0.
640 Option groups: FD (TERMIOS,REG,SOCKET)
641 Useful options: readbytes
642 See also: FD
643 STDIO Uses file descriptor 0 for reading, and 1 for writing.
645 Option groups: FD (TERMIOS,REG,SOCKET)
646 Useful options: readbytes
647 See also: FD
648 STDOUT Uses file descriptor 1.
650 Option groups: FD (TERMIOS,REG,SOCKET)
651 See also: FD
652 SYSTEM:<shell-command>
654 Forks a sub process that establishes communication with its par‐
655 ent process and invokes the specified program with system() .
656 Please note that <shell-command> [string] must not contain ’,’
657 or "!!", and that shell meta characters may have to be pro‐
658 tected. After successful program start, socat writes data to
659 stdin of the process and reads from its stdout.
660 Option groups: FD,SOCKET,EXEC,FORK,TERMIOS
661 Useful options: path, fdin, fdout, chroot, su, su-d, nofork,
662 pty, stderr, ctty, setsid, pipes, sigint, sigquit
663 See also: EXEC
664 TCP:<host>:<port>
666 Connects to <port> [TCP service] on <host> [IP address] using
667 TCP/IP version 4 or 6 depending on address specification, name
668 resolution, or option pf.
669 Option groups: FD,SOCKET,IP4,IP6,TCP,RETRY
670 Useful options: crnl, bind, pf, connect-timeout, tos, mtudis‐
671 cover, mss, nodelay, nonblock, sourceport, retry, readbytes
672 See also: TCP4, TCP6, TCP-LISTEN, UDP, SCTP-CONNECT, UNIX-CON‐
673 NECT
674 TCP4:<host>:<port>
676 Like TCP, but only supports IPv4 protocol (example).
677 Option groups: FD,SOCKET,IP4,TCP,RETRY
678 TCP6:<host>:<port>
680 Like TCP, but only supports IPv6 protocol.
681 Option groups: FD,SOCKET,IP6,TCP,RETRY
682 TCP-LISTEN:<port>
684 Listens on <port> [TCP service] and accepts a TCP/IP connection.
685 The IP version is 4 or the one specified with address option pf,
686 socat option (-4, -6), or environment variable
687 SOCAT_DEFAULT_LISTEN_IP. Note that opening this address usually
688 blocks until a client connects.
689 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6,TCP,RETRY
690 Useful options: crnl, fork, bind, range, tcpwrap, pf, max-chil‐
691 dren, backlog, mss, su, reuseaddr, retry, cool-write
692 See also: TCP4-LISTEN, TCP6-LISTEN, UDP-LISTEN, SCTP-LISTEN,
693 UNIX-LISTEN, OPENSSL-LISTEN, TCP-CONNECT
694 TCP4-LISTEN:<port>
696 Like TCP-LISTEN, but only supports IPv4 protocol (example).
697 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,TCP,RETRY
698 TCP6-LISTEN:<port>
700 Like TCP-LISTEN, but only supports IPv6 protocol.
701 Additional useful option: ipv6only
702 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,TCP,RETRY
703 TUN[:<if-addr>/<bits>]
705 Creates a Linux TUN/TAP device and optionally assignes it the
706 address and netmask given by the parameters. The resulting net‐
707 work interface is almost ready for use by other processes; socat
708 serves its "wire side". This address requires read and write
709 access to the tunnel cloning device, usually /dev/net/tun , as
710 well as permission to set some ioctl()s. Option iff-up is
711 required to immediately activate the interface!
712 Option groups: FD,NAMED,OPEN,TUN
713 Useful options: iff-up, tun-device, tun-name, tun-type,
714 iff-no-pi
715 See also: ip-recv
716 UDP:<host>:<port>
718 Connects to <port> [UDP service] on <host> [IP address] using
719 UDP/IP version 4 or 6 depending on address specification, name
720 resolution, or option pf.
721 Please note that, due to UDP protocol properties, no real con‐
722 nection is established; data has to be sent for `connecting’ to
723 the server, and no end-of-file condition can be transported.
724 Option groups: FD,SOCKET,IP4,IP6
725 Useful options: ttl, tos, bind, sourceport, pf
726 See also: UDP4, UDP6, UDP-LISTEN, TCP, IP
727 UDP4:<host>:<port>
729 Like UDP, but only supports IPv4 protocol.
730 Option groups: FD,SOCKET,IP4
731 UDP6:<host>:<port>
733 Like UDP, but only supports IPv6 protocol.
734 Option groups: FD,SOCKET,IP6
735 UDP-DATAGRAM:<address>:<port>
737 Sends outgoing data to the specified address which may in par‐
738 ticular be a broadcast or multicast address. Packets arriving on
739 the local socket are checked for the correct remote port and if
740 their source addresses match RANGE or TCPWRAP options. This
741 address type can for example be used for implementing symmetric
742 or asymmetric broadcast or multicast communications.
743 Option groups: FD,SOCKET,IP4,IP6,RANGE
744 Useful options: bind, range, tcpwrap, broadcast, ip-multi‐
745 cast-loop, ip-multicast-ttl, ip-multicast-if, ip-add-membership,
746 ttl, tos, sourceport, pf
747 See also: UDP4-DATAGRAM, UDP6-DATAGRAM, UDP-SENDTO,
748 UDP-RECVFROM, UDP-RECV, UDP-CONNECT, UDP-LISTEN, IP-DATAGRAM
749 UDP4-DATAGRAM:<address>:<port>
751 Like UDP-DATAGRAM, but only supports IPv4 protocol (example1,
752 example2).
753 Option groups: FD,SOCKET,IP4, RANGE
754 UDP6-DATAGRAM:<address>:<port>
756 Like UDP-DATAGRAM, but only supports IPv6 protocol.
757 Option groups: FD,SOCKET,IP6,RANGE
758 UDP-LISTEN:<port>
760 Waits for a UDP/IP packet arriving on <port> [UDP service] and
761 `connects’ back to sender. The accepted IP version is 4 or the
762 one specified with option pf. Please note that, due to UDP pro‐
763 tocol properties, no real connection is established; data has to
764 arrive from the peer first, and no end-of-file condition can be
765 transported. Note that opening this address usually blocks until
766 a client connects.
767 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,IP6
768 Useful options: fork, bind, range, pf
769 See also: UDP, UDP4-LISTEN, UDP6-LISTEN, TCP-LISTEN
770 UDP4-LISTEN:<port>
772 Like UDP-LISTEN, but only support IPv4 protocol.
773 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4
774 UDP6-LISTEN:<port>
776 Like UDP-LISTEN, but only support IPv6 protocol.
777 Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6
778 UDP-SENDTO:<host>:<port>
780 Communicates with the specified peer socket, defined by <port>
781 [UDP service] on <host> [IP address], using UDP/IP version 4 or
782 6 depending on address specification, name resolution, or option
783 pf. It sends packets to and receives packets from that peer
784 socket only. This address effectively implements a datagram
785 client. It works well with socat UDP-RECVFROM and UDP-RECV
786 address peers.
787 Option groups: FD,SOCKET,IP4,IP6
788 Useful options: ttl, tos, bind, sourceport, pf
789 See also: UDP4-SENDTO, UDP6-SENDTO, UDP-RECVFROM, UDP-RECV,
790 UDP-CONNECT, UDP-LISTEN, IP-SENDTO
791 UDP4-SENDTO:<host>:<port>
793 Like UDP-SENDTO, but only supports IPv4 protocol.
794 Option groups: FD,SOCKET,IP4
795 UDP6-SENDTO:<host>:<port>
797 Like UDP-SENDTO, but only supports IPv6 protocol.
798 Option groups: FD,SOCKET,IP6
799 UDP-RECVFROM:<port>
801 Creates a UDP socket on <port> [UDP service] using UDP/IP ver‐
802 sion 4 or 6 depending on option pf. It receives one packet from
803 an unspecified peer and may send one or more answer packets to
804 that peer. This mode is particularly useful with fork option
805 where each arriving packet - from arbitrary peers - is handled
806 by its own sub process. This allows a behaviour similar to typi‐
807 cal UDP based servers like ntpd or named. This address works
808 well with socat UDP-SENDTO address peers.
809 Option groups: FD,SOCKET,IP4,IP6,CHILD,RANGE
810 Useful options: fork, ttl, tos, bind, sourceport, pf
811 See also: UDP4-RECVFROM, UDP6-RECVFROM, UDP-SENDTO, UDP-RECV,
812 UDP-CONNECT, UDP-LISTEN, IP-RECVFROM, UNIX-RECVFROM
813 UDP4-RECVFROM:<port>
815 Like UDP-RECVFROM, but only supports IPv4 protocol.
816 Option groups: FD,SOCKET,IP4,CHILD,RANGE
817 UDP6-RECVFROM:<port>
819 Like UDP-RECVFROM, but only supports IPv6 protocol.
820 Option groups: FD,SOCKET,IP6,CHILD,RANGE
821 UDP-RECV:<port>
823 Creates a UDP socket on <port> [UDP service] using UDP/IP ver‐
824 sion 4 or 6 depending on option pf. It receives packets from
825 multiple unspecified peers and merges the data. No replies are
826 possible. It works well with, e.g., socat UDP-SENDTO address
827 peers; it behaves similar to a syslog server.
828 Option groups: FD,SOCKET,IP4,IP6,RANGE
829 Useful options: fork, pf, bind, sourceport, ttl, tos
830 See also: UDP4-RECV, UDP6-RECV, UDP-SENDTO, UDP-RECVFROM,
831 UDP-CONNECT, UDP-LISTEN, IP-RECV, UNIX-RECV
832 UDP4-RECV:<port>
834 Like UDP-RECV, but only supports IPv4 protocol.
835 Option groups: FD,SOCKET,IP4,RANGE
836 UDP6-RECV:<port>
838 Like UDP-RECV, but only supports IPv6 protocol.
839 Option groups: FD,SOCKET,IP6,RANGE
840 UNIX-CONNECT:<filename>
842 Connects to <filename> assuming it is a UNIX domain socket. If
843 <filename> does not exist, this is an error; if <filename> is
844 not a UNIX domain socket, this is an error; if <filename> is a
845 UNIX domain socket, but no process is listening, this is an
846 error.
847 Option groups: FD,SOCKET,NAMED,RETRY,UNIX
848 ) Useful options: bind
849 See also: UNIX-LISTEN, UNIX-SENDTO, TCP
850 UNIX-LISTEN:<filename>
852 Listens on <filename> using a UNIX domain stream socket and
853 accepts a connection. If <filename> exists and is not a socket,
854 this is an error. If <filename> exists and is a UNIX domain
855 socket, binding to the address fails (use option unlink-early!).
856 Note that opening this address usually blocks until a client
857 connects. Beginning with socat version 1.4.3, the file system
858 entry is removed when this address is closed (but see option
859 unlink-close) (example).
860 Option groups: FD,SOCKET,NAMED,LISTEN,CHILD,RETRY,UNIX
861 Useful options: fork, umask, mode, user, group, unlink-early
862 See also: UNIX-CONNECT, UNIX-RECVFROM, UNIX-RECV, TCP-LISTEN
863 UNIX-SENDTO:<filename>
865 Communicates with the specified peer socket, defined by [<file‐
866 name>] assuming it is a UNIX domain datagram socket. It sends
867 packets to and receives packets from that peer socket only.
868 Please note that it might be necessary to bind the local socket
869 to an address (e.g. /tmp/sock1, which must not exist before).
870 This address type works well with socat UNIX-RECVFROM and
871 UNIX-RECV address peers.
872 Option groups: FD,SOCKET,NAMED,UNIX
873 Useful options: bind
874 See also: UNIX-RECVFROM, UNIX-RECV, UNIX-CONNECT, UDP-SENDTO,
875 IP-SENDTO
876 UNIX-RECVFROM:<filename>
878 Creates a UNIX domain datagram socket [<filename>]. Receives
879 one packet and may send one or more answer packets to that peer.
880 This mode is particularly useful with fork option where each
881 arriving packet - from arbitrary peers - is handled by its own
882 sub process. This address works well with socat UNIX-SENDTO
883 address peers.
884 Option groups: FD,SOCKET,NAMED,CHILD,UNIX
885 Useful options: fork
886 See also: UNIX-SENDTO, UNIX-RECV, UNIX-LISTEN, UDP-RECVFROM,
887 IP-RECVFROM
888 UNIX-RECV:<filename>
890 Creates a UNIX domain datagram socket [<filename>]. Receives
891 packets from multiple unspecified peers and merges the data. No
892 replies are possible. It can be, e.g., addressed by socat
893 UNIX-SENDTO address peers. It behaves similar to a syslog
894 server. Option groups: FD,SOCKET,NAMED,UNIX
895 See also: UNIX-SENDTO, UNIX-RECVFROM, UNIX-LISTEN, UDP-RECV,
896 IP-RECV
897 UNIX-CLIENT:<filename>
899 Communicates with the specified peer socket, defined by [<file‐
900 name>] assuming it is a UNIX domain socket. It first tries to
901 connect and, if that fails, assumes it is a datagram socket,
902 thus supporting both types.
903 Option groups: FD,SOCKET,NAMED,UNIX
904 Useful options: bind
905 See also: UNIX-CONNECT, UNIX-SENDTO, GOPEN
906 ABSTRACT-CONNECT:<string>
908 ABSTRACT-LISTEN:<string>
910 ABSTRACT-SENDTO:<string>
912 ABSTRACT-RECVFROM:<string>
914 ABSTRACT-RECV:<string>
916 ABSTRACT-CLIENT:<string>
918 The ABSTRACT addresses are almost identical to the related UNIX
919 addresses except that they do not address file system based
920 sockets but an alternate UNIX domain address space. To achieve
921 this the socket address strings are prefixed with "\0" inter‐
922 nally. This feature is available (only?) on Linux. Option
923 groups are the same as with the related UNIX addresses, except
924 that the ABSTRACT addresses are not member of the NAMED group.
925
928 Address options can be applied to address specifications to influence
929 the process of opening the addresses and the properties of the result‐
930 ing data channels.
931 For technical reasons not every option can be applied to every address
933 type; e.g., applying a socket option to a regular file will fail. To
934 catch most useless combinations as early as in the open phase, the con‐
935 cept of option groups was introduced. Each option belongs to one or
936 more option groups. Options can be used only with address types that
937 support at least one of their option groups (but see option -g).
938 Address options have data types that their values must conform to.
940 Every address option consists of just a keyword or a keyword followed
941 by "=value", where value must conform to the options type. Some
942 address options manipulate parameters of system calls; e.g., option
943 sync sets the O_SYNC flag with the open() call. Other options cause a
944 system or library call; e.g., with option `ttl=value’ the setsock‐
945 opt(fd, SOL_IP, IP_TTL, value, sizeof(int)) call is applied. Other
946 options set internal socat variables that are used during data trans‐
947 fer; e.g., `crnl’ causes explicit character conversions. A few options
948 have more complex implementations; e.g., su-d (substuser-delayed)
949 inquires some user and group infos, stores them, and applies them later
950 after a possible chroot() call.
951 If multiple options are given to an address, their sequence in the
953 address specification has (almost) no effect on the sequence of their
954 execution/application. Instead, socat has built in an option phase
955 model that tries to bring the options in a useful order. Some options
956 exist in different forms (e.g., unlink, unlink-early, unlink-late) to
957 control the time of their execution.
958 If the same option is specified more than once within one address spec‐
960 ification, with equal or different values, the effect depends on the
961 kind of option. Options resulting in function calls like setsockopt()
962 cause multiple invocations. With options that set parameters for a
963 required call like open() or set internal flags, the value of the last
964 option occurrence is effective.
965 The existence or semantics of many options are system dependent. Socat
967 usually does NOT try to emulate missing libc or kernel features, it
968 just provides an interface to the underlying system. So, if an operat‐
969 ing system lacks a feature, the related option is simply not available
970 on this platform.
971 The following paragraphs introduce just the more common address
973 options. For a more comprehensive reference and to find information
974 about canonical option names, alias names, option phases, and platforms
975 see file xio.help.
976 FD option group
979 This option group contains options that are applied to a UN*X style
981 file descriptor, no matter how it was generated. Because all current
982 socat address types are file descriptor based, these options may be
983 applied to any address.
984 Note: Some of these options are also member of another option group,
985 that provides another, non-fd based mechanism. For these options, it
986 depends on the actual address type and its option groups which mecha‐
987 nism is used. The second, non-fd based mechanism is prioritized.
988 cloexec=<bool>
990 Sets the FD_CLOEXEC flag with the fcntl() system call to value
991 <bool>. If set, the file descriptor is closed on exec() family
992 function calls. Socat internally handles this flag for the fds
993 it controls, so in most cases there will be no need to apply
994 this option.
995 setlk Tries to set a discretionary write lock to the whole file using
997 the fcntl(fd, F_SETLK, ...) system call. If the file is already
998 locked, this call results in an error. On Linux, when the file
999 permissions for group are "S" (g-x,g+s), and the file system is
1000 locally mounted with the "mand" option, the lock is mandatory,
1001 i.e. prevents other processes from opening the file.
1002 setlkw Tries to set a discretionary waiting write lock to the whole
1004 file using the fcntl(fd, F_SETLKW, ...) system call. If the
1005 file is already locked, this call blocks. See option setlk for
1006 information about making this lock mandatory.
1007 setlk-rd
1009 Tries to set a discretionary read lock to the whole file using
1010 the fcntl(fd, F_SETLK, ...) system call. If the file is already
1011 write locked, this call results in an error. See option setlk
1012 for information about making this lock mandatory.
1013 setlkw-rd
1015 Tries to set a discretionary waiting read lock to the whole file
1016 using the fcntl(fd, F_SETLKW, ...) system call. If the file is
1017 already write locked, this call blocks. See option setlk for
1018 information about making this lock mandatory.
1019 flock-ex
1021 Tries to set a blocking exclusive advisory lock to the file
1022 using the flock(fd, LOCK_EX) system call. Socat hangs in this
1023 call if the file is locked by another process.
1024 flock-ex-nb
1026 Tries to set a nonblocking exclusive advisory lock to the file
1027 using the flock(fd, LOCK_EX|LOCK_NB) system call. If the file is
1028 already locked, this option results in an error.
1029 flock-sh
1031 Tries to set a blocking shared advisory lock to the file using
1032 the flock(fd, LOCK_SH) system call. Socat hangs in this call if
1033 the file is locked by another process.
1034 flock-sh-nb
1036 Tries to set a nonblocking shared advisory lock to the file
1037 using the flock(fd, LOCK_SH|LOCK_NB) system call. If the file is
1038 already locked, this option results in an error.
1039 lock Sets a blocking lock on the file. Uses the setlk or flock mecha‐
1041 nism depending on availability on the particular platform. If
1042 both are available, the POSIX variant (setlkw) is used.
1043 user=<user>
1045 Sets the <user> (owner) of the stream. If the address is member
1046 of the NAMED option group, socat uses the chown() system call
1047 after opening the file or binding to the UNIX domain socket
1048 (race condition!). Without filesystem entry, socat sets the
1049 user of the stream using the fchown() system call. These calls
1050 might require root privilege.
1051 user-late=<user>
1053 Sets the owner of the fd to <user> with the fchown() system call
1054 after opening or connecting the channel. This is useful only on
1055 file system entries.
1056 group=<group>
1058 Sets the <group> of the stream. If the address is member of the
1059 NAMED option group, socat uses the chown() system call after
1060 opening the file or binding to the UNIX domain socket (race con‐
1061 dition!). Without filesystem entry, socat sets the group of the
1062 stream with the fchown() system call. These calls might require
1063 group membership or root privilege.
1064 group-late=<group>
1066 Sets the group of the fd to <group> with the fchown() system
1067 call after opening or connecting the channel. This is useful
1068 only on file system entries.
1069 mode=<mode>
1071 Sets the <mode> [mode_t] (permissions) of the stream. If the
1072 address is member of the NAMED option group and uses the open()
1073 or creat() call, the mode is applied with these. If the address
1074 is member of the NAMED option group without using these system
1075 calls, socat uses the chmod() system call after opening the
1076 filesystem entry or binding to the UNIX domain socket (race con‐
1077 dition!). Otherwise, socat sets the mode of the stream using
1078 fchmod() . These calls might require ownership or root privi‐
1079 lege.
1080 perm-late=<mode>
1082 Sets the permissions of the fd to value <mode> [mode_t] using
1083 the fchmod() system call after opening or connecting the chan‐
1084 nel. This is useful only on file system entries.
1085 append=<bool>
1087 Always writes data to the actual end of file. If the address is
1088 member of the OPEN option group, socat uses the O_APPEND flag
1089 with the open() system call (example). Otherwise, socat applies
1090 the fcntl(fd, F_SETFL, O_APPEND) call.
1091 nonblock=<bool>
1093 Tries to open or use file in nonblocking mode. Its only effects
1094 are that the connect() call of TCP addresses does not block, and
1095 that opening a named pipe for reading does not block. If the
1096 address is member of the OPEN option group, socat uses the
1097 O_NONBLOCK flag with the open() system call. Otherwise, socat
1098 applies the fcntl(fd, F_SETFL, O_NONBLOCK) call.
1099 binary Opens the file in binary mode to avoid implicit line terminator
1101 conversions (Cygwin).
1102 text Opens the file in text mode to force implicit line terminator
1104 conversions (Cygwin).
1105 noinherit
1107 Does not keep this file open in a spawned process (Cygwin).
1108 cool-write
1110 Takes it easy when write fails with EPIPE or ECONNRESET and logs
1111 the message with notice level instead of error. This prevents
1112 the log file from being filled with useless error messages when
1113 socat is used as a high volume server or proxy where clients
1114 often abort the connection.
1115 This option is experimental.
1116 end-close
1118 Changes the (address dependent) method of ending a connection to
1119 just close the file descriptors. This is useful when the connec‐
1120 tion is to be reused by or shared with other processes (exam‐
1121 ple).
1122 Normally, socket connections will be ended with shutdown(2)
1123 which terminates the socket even if it is shared by multiple
1124 processes. close(2) "unlinks" the socket from the process but
1125 keeps it active as long as there are still links from other pro‐
1126 cesses.
1127 Similarly, when an address of type EXEC or SYSTEM is ended,
1128 socat usually will explicitly kill the sub process. With this
1129 option, it will just close the file descriptors.
1130 shut-none
1132 Changes the (address dependent) method of shutting down the
1133 write part of a connection to not do anything.
1134 shut-down
1136 Changes the (address dependent) method of shutting down the
1137 write part of a connection to shutdown(fd, SHUT_WR). Is only
1138 useful with sockets.
1139 shut-close
1141 Changes the (address dependent) method of shutting down the
1142 write part of a connection to close(fd).
1143 shut-null
1145 When one address indicates EOF, socat will send a zero sized
1146 packet to the write channel of the other address to transfer the
1147 EOF condition. This is useful with UDP and other datagram proto‐
1148 cols. Has been tested against netcat and socat with option
1149 null-eof.
1150 null-eof
1152 Normally socat will ignore empty (zero size payload) packets
1153 arriving on datagram sockets, so it survives port scans. With
1154 this option socat interprets empty datagram packets as EOF indi‐
1155 cator (see shut-null).
1156 ioctl-void=<request>
1158 Calls ioctl() with the request value as second argument and NULL
1159 as third argument. This option allows utilizing ioctls that are
1160 not explicitly implemented in socat.
1161 ioctl-int=<request>:<value>
1163 Calls ioctl() with the request value as second argument and the
1164 integer value as third argument.
1165 ioctl-intp=<request>:<value>
1167 Calls ioctl() with the request value as second argument and a
1168 pointer to the integer value as third argument.
1169 ioctl-bin=<request>:<value>
1171 Calls ioctl() with the request value as second argument and a
1172 pointer to the given data value as third argument. This data
1173 must be specified in <dalan> form.
1174 ioctl-string=<request>:<value>
1176 Calls ioctl() with the request value as second argument and a
1177 pointer to the given string as third argument. <dalan> form.
1178 NAMED option group
1181 These options work on file system entries.
1183 See also options user, group, and mode.
1184 user-early=<user>
1186 Changes the <user> (owner) of the file system entry before
1187 accessing it, using the chown() system call. This call might
1188 require root privilege.
1189 group-early=<group>
1191 Changes the <group> of the file system entry before accessing
1192 it, using the chown() system call. This call might require group
1193 membership or root privilege.
1194 perm-early=<mode>
1196 Changes the <mode> [mode_t] of the file system entry before
1197 accessing it, using the chmod() system call. This call might
1198 require ownership or root privilege.
1199 umask=<mode>
1201 Sets the umask of the process to <mode> [mode_t] before access‐
1202 ing the file system entry (useful with UNIX domain sockets!).
1203 This call might affect all further operations of the socat
1204 process!
1205 unlink-early
1207 Unlinks (removes) the file before opening it and even before
1208 applying user-early etc.
1209 unlink Unlinks (removes) the file before accessing it, but after
1211 user-early etc.
1212 unlink-late
1214 Unlinks (removes) the file after opening it to make it inacces‐
1215 sible for other processes after a short race condition.
1216 unlink-close
1218 Removes the addresses file system entry when closing the
1219 address. For named pipes, listening unix domain sockets, and
1220 the symbolic links of pty addresses, the default is 1; for cre‐
1221 ated files, opened files, generic opened files, and client unix
1222 domain sockets the default is 0.
1223 OPEN option group
1226 The OPEN group options allow setting flags with the open() system call.
1228 E.g., option `creat’ sets the O_CREAT flag.
1229 See also options append and nonblock.
1230 creat=<bool>
1232 Creates the file if it does not exist (example).
1233 dsync=<bool>
1235 Blocks write() calls until metainfo is physically written to
1236 media.
1237 excl=<bool>
1239 With option creat, if file exists this is an error.
1240 largefile=<bool>
1242 On 32 bit systems, allows a file larger than 2^31 bytes.
1243 noatime
1245 Sets the O_NOATIME options, so reads do not change the access
1246 timestamp.
1247 noctty=<bool>
1249 Does not make this file the controlling terminal.
1250 nofollow=<bool>
1252 Does not follow symbolic links.
1253 nshare=<bool>
1255 Does not allow sharing this file with other processes.
1256 rshare=<bool>
1258 Does not allow other processes to open this file for writing.
1259 rsync=<bool>
1261 Blocks write() until metainfo is physically written to media.
1262 sync=<bool>
1264 Blocks write() until data is physically written to media.
1265 rdonly=<bool>
1267 Opens the file for reading only.
1268 wronly=<bool>
1270 Opens the file for writing only.
1271 trunc Truncates the file to size 0 during opening it.
1273 REG and BLK option group
1276 These options are usually applied to a UN*X file descriptor, but their
1278 semantics make sense only on a file supporting random access.
1279 seek=<offset>
1281 Applies the lseek(fd, <offset>, SEEK_SET) (or lseek64 ) system
1282 call, thus positioning the file pointer absolutely to <offset>
1283 [off_t or off64_t]. Please note that a missing value defaults to
1284 1, not 0.
1285 seek-cur=<offset>
1287 Applies the lseek(fd, <offset>, SEEK_CUR) (or lseek64 ) system
1288 call, thus positioning the file pointer <offset> [off_t or
1289 off64_t] bytes relatively to its current position (which is usu‐
1290 ally 0). Please note that a missing value defaults to 1, not 0.
1291 seek-end=<offset>
1293 Applies the lseek(fd, <offset>, SEEK_END) (or lseek64 ) system
1294 call, thus positioning the file pointer <offset> [off_t or
1295 off64_t] bytes relatively to the files current end. Please note
1296 that a missing value defaults to 1, not 0.
1297 ftruncate=<offset>
1299 Applies the ftruncate(fd, <offset>) (or ftruncate64 if avail‐
1300 able) system call, thus truncating the file at the position
1301 <offset> [off_t or off64_t]. Please note that a missing value
1302 defaults to 1, not 0.
1303 secrm=<bool>
1305 unrm=<bool>
1307 compr=<bool>
1309 ext2-sync=<bool>
1311 immutable=<bool>
1313 ext2-append=<bool>
1315 nodump=<bool>
1317 ext2-noatime=<bool>
1319 journal-data=<bool>
1321 notail=<bool>
1323 dirsync=<bool>
1325 These options change non standard file attributes on operating
1326 systems and file systems that support these features, like Linux
1327 with ext2fs, ext3fs, or reiserfs. See man 1 chattr for informa‐
1328 tion on these options. Please note that there might be a race
1329 condition between creating the file and applying these options.
1330 PROCESS option group
1333 Options of this group change the process properties instead of just
1335 affecting one data channel. For EXEC and SYSTEM addresses and for LIS‐
1336 TEN and CONNECT type addresses with option FORK, these options apply to
1337 the child processes instead of the main socat process.
1338 chroot=<directory>
1340 Performs a chroot() operation to <directory> after processing
1341 the address (example). This call might require root privilege.
1342 chroot-early=<directory>
1344 Performs a chroot() operation to <directory> before opening the
1345 address. This call might require root privilege.
1346 setgid=<group>
1348 Changes the primary <group> of the process after processing the
1349 address. This call might require root privilege. Please note
1350 that this option does not drop other group related privileges.
1351 setgid-early=<group>
1353 Like setgit but is performed before opening the address.
1354 setuid=<user>
1356 Changes the <user> (owner) of the process after processing the
1357 address. This call might require root privilege. Please note
1358 that this option does not drop group related privileges. Check
1359 if option su better fits your needs.
1360 setuid-early=<user>
1362 Like setuid but is performed before opening the address.
1363 su=<user>
1365 Changes the <user> (owner) and groups of the process after pro‐
1366 cessing the address (example). This call might require root
1367 privilege.
1368 su-d=<user>
1370 Short name for substuser-delayed. Changes the <user> (owner)
1371 and groups of the process after processing the address (exam‐
1372 ple). The user and his groups are retrieved before a possible
1373 chroot() . This call might require root privilege.
1374 setpgid=<pid_t>
1376 Makes the process a member of the specified process group
1377 <pid_t>. If no value is given, or if the value is 0 or 1, the
1378 process becomes leader of a new process group.
1379 setsid Makes the process the leader of a new session (example).
1381 READLINE option group
1384 These options apply to the readline address type.
1386 history=<filename>
1388 Reads and writes history from/to <filename> (example).
1389 noprompt
1391 Since version 1.4.0, socat per default tries to determine a
1392 prompt - that is then passed to the readline call - by remember‐
1393 ing the last incomplete line of the output. With this option,
1394 socat does not pass a prompt to readline, so it begins line
1395 editing in the first column of the terminal.
1396 noecho=<pattern>
1398 Specifies a regular pattern for a prompt that prevents the fol‐
1399 lowing input line from being displayed on the screen and from
1400 being added to the history. The prompt is defined as the text
1401 that was output to the readline address after the lastest new‐
1402 line character and before an input character was typed. The pat‐
1403 tern is a regular expression, e.g. "^[Pp]assword:.*$" or
1404 "([Uu]ser:|[Pp]assword:)". See regex(7) for details. (example)
1405 prompt=<string>
1407 Passes the string as prompt to the readline function. readline
1408 prints this prompt when stepping through the history. If this
1409 string matches a constant prompt issued by an interactive pro‐
1410 gram on the other socat address, consistent look and feel can be
1411 achieved.
1412 APPLICATION option group
1415 This group contains options that work at data level. Note that these
1417 options only apply to the "raw" data transferred by socat, but not to
1418 protocol data used by addresses like PROXY.
1419 cr Converts the default line termination character NL (’\n’, 0x0a)
1421 to/from CR (’\r’, 0x0d) when writing/reading on this channel.
1422 crnl Converts the default line termination character NL (’\n’, 0x0a)
1424 to/from CRNL ("\r\n", 0x0d0a) when writing/reading on this chan‐
1425 nel (example). Note: socat simply strips all CR characters.
1426 ignoreeof
1428 When EOF occurs on this channel, socat ignores it and tries to
1429 read more data (like "tail -f") (example).
1430 readbytes=<bytes>
1432 socat reads only so many bytes from this address (the address
1433 provides only so many bytes for transfer and pretends to be at
1434 EOF afterwards). Must be greater than 0.
1435 lockfile=<filename>
1437 If lockfile exists, exits with error. If lockfile does not
1438 exist, creates it and continues, unlinks lockfile on exit.
1439 waitlock=<filename>
1441 If lockfile exists, waits until it disappears. When lockfile
1442 does not exist, creates it and continues, unlinks lockfile on
1443 exit.
1444 escape=<int>
1446 Specifies the numeric code of a character that triggers EOF on
1447 the input stream. It is useful with a terminal in raw mode
1448 (example).
1449 SOCKET option group
1452 These options are intended for all kinds of sockets, e.g. IP or UNIX
1454 domain. Most are applied with a setsockopt() call.
1455 bind=<sockname>
1457 Binds the socket to the given socket address using the bind()
1458 system call. The form of <sockname> is socket domain dependent:
1459 IP4 and IP6 allow the form [hostname|hostaddress][:(ser‐
1460 vice|port)] (example), UNIX domain sockets require <filename>.
1461 connect-timeout=<seconds>
1463 Abort the connection attempt after <seconds> [timeval] with
1464 error status.
1465 so-bindtodevice=<interface>
1467 Binds the socket to the given <interface>. This option might
1468 require root privilege.
1469 broadcast
1471 For datagram sockets, allows sending to broadcast addresses and
1472 receiving packets addressed to broadcast addresses.
1473 debug Enables socket debugging.
1475 dontroute
1477 Only communicates with directly connected peers, does not use
1478 routers.
1479 keepalive
1481 Enables sending keepalives on the socket.
1482 linger=<seconds>
1484 Blocks shutdown() or close() until data transfers have finished
1485 or the given timeout [int] expired.
1486 oobinline
1488 Places out-of-band data in the input data stream.
1489 priority=<priority>
1491 Sets the protocol defined <priority> [<int>] for outgoing pack‐
1492 ets.
1493 rcvbuf=<bytes>
1495 Sets the size of the receive buffer after the socket() call to
1496 <bytes> [int]. With TCP sockets, this value corresponds to the
1497 socket’s maximal window size.
1498 rcvbuf-late=<bytes>
1500 Sets the size of the receive buffer when the socket is already
1501 connected to <bytes> [int]. With TCP sockets, this value corre‐
1502 sponds to the socket’s maximal window size.
1503 rcvlowat=<bytes>
1505 Specifies the minimum number of received bytes [int] until the
1506 socket layer will pass the buffered data to socat.
1507 reuseaddr
1509 Allows other sockets to bind to an address even if parts of it
1510 (e.g. the local port) are already in use by socat (example).
1511 sndbuf=<bytes>
1513 Sets the size of the send buffer after the socket() call to
1514 <bytes> [int].
1515 sndbuf-late=<bytes>
1517 Sets the size of the send buffer when the socket is connected to
1518 <bytes> [int].
1519 sndlowat=<bytes>
1521 Specifies the minimum number of bytes in the send buffer until
1522 the socket layer will send the data to <bytes> [int].
1523 pf=<string>
1525 Forces the use of the specified IP version or protocol. <string>
1526 can be something like "ip4" or "ip6". The resulting value is
1527 used as first argument to the socket() or socketpair() calls.
1528 This option affects address resolution and the required syntax
1529 of bind and range options.
1530 type=<type>
1532 Sets the type of the socket, specified as second argument to the
1533 socket() or socketpair() calls, to <type> [int]. Address resolu‐
1534 tion is not affected by this option. Under Linux, 1 means
1535 stream oriented socket, 2 means datagram socket, and 3 means raw
1536 socket.
1537 prototype
1539 Sets the protocol of the socket, specified as third argument to
1540 the socket() or socketpair() calls, to <prototype> [int].
1541 Address resolution is not affected by this option. 6 means TCP,
1542 17 means UDP.
1543 reuseport
1545 Set the SO_REUSEPORT socket option.
1546 so-timestamp
1548 Sets the SO_TIMESTAMP socket option. This enables receiving and
1549 logging of timestamp ancillary messages.
1550 setsockopt-int=<level>:<optname>:<optval>
1552 Invokes setsockopt() for the socket with the given parameters.
1553 level [int] is used as second argument to setsockopt() and spec‐
1554 ifies the layer, e.g. SOL_TCP for TCP (6 on Linux), or
1555 SOL_SOCKET for the socket layer (1 on Linux). optname [int] is
1556 the third argument to setsockopt() and tells which socket option
1557 is to be set. For the actual numbers you might have to look up
1558 the appropriate include files of your system. The 4th setsock‐
1559 opt() parameter, value [int], is passed to the function per
1560 pointer, and for the length parameter sizeof(int) is taken
1561 implicitely.
1562 setsockopt-bin=<level>:<optname>:<optval>
1564 Like setsockopt-int, but <optval> must be provided in dalan for‐
1565 mat and specifies an arbitrary sequence of bytes; the length
1566 parameter is automatically derived from the data.
1567 setsockopt-string=<level>:<optname>:<optval>
1569 Like setsockopt-int, but <optval> must be a string. This string
1570 is passed to the function with trailing null character, and the
1571 length parameter is automatically derived from the data.
1572 UNIX option group
1575 These options apply to UNIX domain based addresses.
1577 unix-tightsocklen=[0|1]
1579 On socket operations, pass a socket address length that does not
1580 include the whole struct sockaddr_un record but (besides other
1581 components) only the relevant part of the filename or abstract
1582 string. Default is 1.
1583 IP4 and IP6 option groups
1586 These options can be used with IPv4 and IPv6 based sockets.
1588 tos=<tos>
1590 Sets the TOS (type of service) field of outgoing packets to
1591 <tos> [byte] (see RFC 791).
1592 ttl=<ttl>
1594 Sets the TTL (time to live) field of outgoing packets to <ttl>
1595 [byte].
1596 ip-options=<data>
1598 Sets IP options like source routing. Must be given in binary
1599 form, recommended format is a leading "x" followed by an even
1600 number of hex digits. This option may be used multiple times,
1601 data are appended. E.g., to connect to host 10.0.0.1 via some
1602 gateway using a loose source route, use the gateway as address
1603 parameter and set a loose source route using the option
1604 ip-options=x8307040a000001 .
1605 IP options are defined in RFC 791.
1606 mtudiscover=<0|1|2>
1608 Takes 0, 1, 2 to never, want, or always use path MTU discover on
1609 this socket.
1610 ip-pktinfo
1612 Sets the IP_PKTINFO socket option. This enables receiving and
1613 logging of ancillary messages containing destination address and
1614 interface (Linux) (example).
1615 ip-recverr
1617 Sets the IP_RECVERR socket option. This enables receiving and
1618 logging of ancillary messages containing detailed error informa‐
1619 tion.
1620 ip-recvopts
1622 Sets the IP_RECVOPTS socket option. This enables receiving and
1623 logging of IP options ancillary messages (Linux, *BSD).
1624 ip-recvtos
1626 Sets the IP_RECVTOS socket option. This enables receiving and
1627 logging of TOS (type of service) ancillary messages (Linux).
1628 ip-recvttl
1630 Sets the IP_RECVTTL socket option. This enables receiving and
1631 logging of TTL (time to live) ancillary messages (Linux, *BSD).
1632 ip-recvdstaddr
1634 Sets the IP_RECVDSTADDR socket option. This enables receiving
1635 and logging of ancillary messages containing destination address
1636 (*BSD) (example).
1637 ip-recvif
1639 Sets the IP_RECVIF socket option. This enables receiving and
1640 logging of interface ancillary messages (*BSD) (example).
1641 ip-add-membership=<multicast-address:interface-address>
1643 ip-add-membership=<multicast-address:interface-name>
1645 ip-add-membership=<multicast-address:interface-index>
1647 ip-add-membership=<multicast-address:interface-address:interface-name>
1649 ip-add-membership=<multicast-address:interface-address:interface-index>
1651 Makes the socket member of the specified multicast group. This
1652 is currently only implemented for IPv4. The option takes the IP
1653 address of the multicast group and info about the desired net‐
1654 work interface. The most common syntax is the first one, while
1655 the others are only available on systems that provide struct
1656 mreqn (Linux).
1657 The indices of active network interfaces can be shown using the
1658 utility procan.
1659 ip-multicast-if=<hostname>
1661 Specifies hostname or address of the network interface to be
1662 used for multicast traffic.
1663 ip-multicast-loop=<bool>
1665 Specifies if outgoing multicast traffic should loop back to the
1666 interface.
1667 ip-multicast-ttl=<byte>
1669 Sets the TTL used for outgoing multicast traffic. Default is 1.
1670 res-debug
1672 res-aaonly
1674 res-usevc
1676 res-primary
1678 res-igntc
1680 res-recurse
1682 res-defnames
1684 res-stayopen
1686 res-dnsrch
1688 These options set the corresponding resolver (name resolution)
1689 option flags. Append "=0" to clear a default option. See man
1690 resolver(5) for more information on these options. Note: these
1691 options are valid only for the address they are applied to.
1692 IP6 option group
1694 These options can only be used on IPv6 based sockets. See IP options
1696 for options that can be applied to both IPv4 and IPv6 sockets.
1697 ipv6only=<bool>
1699 Sets the IPV6_V6ONLY socket option. If 0, the TCP stack will
1700 also accept connections using IPv4 protocol on the same port.
1701 The default is system dependent.
1702 ipv6-recvdstopts
1704 Sets the IPV6_RECVDSTOPTS socket option. This enables receiving
1705 and logging of ancillary messages containing the destination
1706 options.
1707 ipv6-recvhoplimit
1709 Sets the IPV6_RECVHOPLIMIT socket option. This enables receiving
1710 and logging of ancillary messages containing the hoplimit.
1711 ipv6-recvhopopts
1713 Sets the IPV6_RECVHOPOPTS socket option. This enables receiving
1714 and logging of ancillary messages containing the hop options.
1715 ipv6-recvpktinfo
1717 Sets the IPV6_RECVPKTINFO socket option. This enables receiving
1718 and logging of ancillary messages containing destination address
1719 and interface.
1720 ipv6-unicast-hops=link(TYPE_INT)(<int>)
1722 Sets the IPV6_UNICAST_HOPS socket option. This sets the hop
1723 count limit (TTL) for outgoing unicast packets.
1724 ipv6-recvrthdr
1726 Sets the IPV6_RECVRTHDR socket option. This enables receiving
1727 and logging of ancillary messages containing routing informa‐
1728 tion.
1729 ipv6-tclass
1731 Sets the IPV6_TCLASS socket option. This sets the transfer class
1732 of outgoing packets.
1733 ipv6-recvtclass
1735 Sets the IPV6_RECVTCLASS socket option. This enables receiving
1736 and logging of ancillary messages containing the transfer class.
1737 TCP option group
1740 These options may be applied to TCP sockets. They work by invoking set‐
1742 sockopt() with the appropriate parameters.
1743 cork Doesn’t send packets smaller than MSS (maximal segment size).
1745 defer-accept
1747 While listening, accepts connections only when data from the
1748 peer arrived.
1749 keepcnt=<count>
1751 Sets the number of keepalives before shutting down the socket to
1752 <count> [int].
1753 keepidle=<seconds>
1755 Sets the idle time before sending the first keepalive to <sec‐
1756 onds> [int].
1757 keepintvl=<seconds>
1759 Sets the interval between two keepalives to <seconds> [int].
1760 linger2=<seconds>
1762 Sets the time to keep the socket in FIN-WAIT-2 state to <sec‐
1763 onds> [int].
1764 mss=<bytes>
1766 Sets the MSS (maximum segment size) after the socket() call to
1767 <bytes> [int]. This value is then proposed to the peer with the
1768 SYN or SYN/ACK packet (example).
1769 mss-late=<bytes>
1771 Sets the MSS of the socket after connection has been established
1772 to <bytes> [int].
1773 nodelay
1775 Turns off the Nagle algorithm for measuring the RTT (round trip
1776 time).
1777 rfc1323
1779 Enables RFC1323 TCP options: TCP window scale, round-trip time
1780 measurement (RTTM), and protect against wrapped sequence numbers
1781 (PAWS) (AIX).
1782 stdurg Enables RFC1122 compliant urgent pointer handling (AIX).
1784 syncnt=<count>
1786 Sets the maximal number of SYN retransmits during connect to
1787 <count> [int].
1788 md5sig Enables generation of MD5 digests on the packets (FreeBSD).
1790 noopt Disables use of TCP options (FreeBSD, MacOSX).
1792 nopush sets the TCP_NOPUSH socket option (FreeBSD, MacOSX).
1794 sack-disable
1796 Disables use the selective acknowledge feature (OpenBSD).
1797 signature-enable
1799 Enables generation of MD5 digests on the packets (OpenBSD).
1800 abort-threshold=<milliseconds>
1802 Sets the time to wait for an answer of the peer on an estab‐
1803 lished connection (HP-UX).
1804 conn-abort-threshold=<milliseconds>
1806 Sets the time to wait for an answer of the server during the
1807 initial connect (HP-UX).
1808 keepinit
1810 Sets the time to wait for an answer of the server during con‐
1811 nect() before giving up. Value in half seconds, default is 150
1812 (75s) (Tru64).
1813 paws Enables the "protect against wrapped sequence numbers" feature
1815 (Tru64).
1816 sackena
1818 Enables selective acknowledge (Tru64).
1819 tsoptena
1821 Enables the time stamp option that allows RTT recalculation on
1822 existing connections (Tru64).
1823 SCTP option group
1826 These options may be applied to SCTP stream sockets.
1828 sctp-nodelay
1830 Sets the SCTP_NODELAY socket option that disables the Nagle
1831 algorithm.
1832 sctp-maxseg=<bytes>
1834 Sets the SCTP_MAXSEG socket option to <bytes> [int]. This value
1835 is then proposed to the peer with the SYN or SYN/ACK packet.
1836 UDP, TCP, and SCTP option groups
1839 Here we find options that are related to the network port mechanism and
1841 thus can be used with UDP, TCP, and SCTP client and server addresses.
1842 sourceport=<port>
1844 For outgoing (client) TCP and UDP connections, it sets the
1845 source <port> using an extra bind() call. With TCP or UDP lis‐
1846 ten addresses, socat immediately shuts down the connection if
1847 the client does not use this sourceport (example).
1848 lowport
1850 Outgoing (client) TCP and UDP connections with this option use
1851 an unused random source port between 640 and 1023 incl. On UNIX
1852 class operating systems, this requires root privilege, and thus
1853 indicates that the client process is authorized by local root.
1854 TCP and UDP listen addresses with this option immediately shut
1855 down the connection if the client does not use a sourceport <=
1856 1023. This mechanism can provide limited authorization under
1857 some circumstances.
1858 SOCKS option group
1861 When using SOCKS type addresses, some socks specific options can be
1863 set.
1864 socksport=<tcp service>
1866 Overrides the default "socks" service or port 1080 for the socks
1867 server port with <TCP service>.
1868 socksuser=<user>
1870 Sends the <user> [string] in the username field to the socks
1871 server. Default is the actual user name ($LOGNAME or $USER)
1872 (example).
1873 HTTP option group
1876 Options that can be provided with HTTP type addresses. The only HTTP
1878 address currently implemented is proxy-connect.
1879 proxyport=<TCP service>
1881 Overrides the default HTTP proxy port 8080 with <TCP service>.
1882 ignorecr
1884 The HTTP protocol requires the use of CR+NL as line terminator.
1885 When a proxy server violates this standard, socat might not
1886 understand its answer. This option directs socat to interprete
1887 NL as line terminator and to ignore CR in the answer. Neverthe‐
1888 less, socat sends CR+NL to the proxy.
1889 proxyauth=<username>:<password>
1891 Provide "basic" authentication to the proxy server. The argument
1892 to the option is used with a "Proxy-Authorization: Base" header
1893 in base64 encoded form.
1894 Note: username and password are visible for every user on the
1895 local machine in the process list; username and password are
1896 transferred to the proxy server unencrypted (base64 encoded) and
1897 might be sniffed.
1898 resolve
1900 Per default, socat sends to the proxy a CONNECT request contain‐
1901 ing the target hostname. With this option, socat resolves the
1902 hostname locally and sends the IP address. Please note that,
1903 according to RFC 2396, only name resolution to IPv4 addresses is
1904 implemented.
1905 RANGE option group
1908 These options check if a connecting client should be granted access.
1910 They can be applied to listening and receiving network sockets.
1911 tcp-wrappers options fall into this group.
1912 range=<address-range>
1914 After accepting a connection, tests if the peer is within range.
1915 For IPv4 addresses, address-range takes the form address/bits,
1916 e.g. 10.0.0.0/8, or address:mask, e.g. 10.0.0.0:255.0.0.0
1917 (example); for IPv6, it is [ip6-address]/bits, e.g. [::1]/128.
1918 If the client address does not match, socat refuses the connec‐
1919 tion attempt, issues a warning, and keeps listening/receiving.
1920 tcpwrap[=<name>]
1922 Uses Wietse Venema’s libwrap (tcpd) library to determine if the
1923 client is allowed to connect. The configuration files are
1924 /etc/hosts.allow and /etc/hosts.deny per default, see "man 5
1925 hosts_access" for more information. The optional <name> (type
1926 string) is passed to the wrapper functions as daemon process
1927 name (example). If omitted, the basename of socats invocation
1928 (argv[0]) is passed. If both tcpwrap and range options are
1929 applied to an address, both conditions must be fulfilled to
1930 allow the connection.
1931 allow-table=<filename>
1933 Takes the specified file instead of /etc/hosts.allow.
1934 deny-table=<filename>
1936 Takes the specified file instead of /etc/hosts.deny.
1937 tcpwrap-etc=<directoryname>
1939 Looks for hosts.allow and hosts.deny in the specified directory.
1940 Is overridden by options hosts-allow and hosts-deny.
1941 LISTEN option group
1944 Options specific to listening sockets.
1946 backlog=<count>
1948 Sets the backlog value passed with the listen() system call to
1949 <count> [int]. Default is 5.
1950 max-children=<count>
1952 Limits the number of concurrent child processes [int]. Default
1953 is no limit.
1954 CHILD option group
1957 Options for addresses with multiple connections via child processes.
1959 fork After establishing a connection, handles its channel in a child
1961 process and keeps the parent process attempting to produce more
1962 connections, either by listening or by connecting in a loop
1963 (example).
1964 OPENSSL-CONNECT and OPENSSL-LISTEN differ in when they actually
1965 fork off the child: OPENSSL-LISTEN forks before the SSL hand‐
1966 shake, while OPENSSL-CONNECT forks afterwards. RETRY and FOR‐
1967 EVER options are not inherited by the child process.
1968 On some operating systems (e.g. FreeBSD) this option does not
1969 work for UDP-LISTEN addresses.
1970 EXEC option group
1973 Options for addresses that invoke a program.
1975 path=<string>
1977 Overrides the PATH environment variable for searching the pro‐
1978 gram with <string>. This $PATH value is effective in the child
1979 process too.
1980 login Prefixes argv[0] for the execvp() call with ’-’, thus making a
1982 shell behave as login shell.
1983 FORK option group
1986 EXEC or SYSTEM addresses invoke a program using a child process and
1988 transfer data between socat and the program. The interprocess communi‐
1989 cation mechanism can be influenced with the following options. Per
1990 default, a socketpair() is created and assigned to stdin and stdout of
1991 the child process, while stderr is inherited from the socat process,
1992 and the child process uses file descriptors 0 and 1 for communicating
1993 with the main socat process.
1994 nofork Does not fork a subprocess for executing the program, instead
1996 calls execvp() or system() directly from the actual socat
1997 instance. This avoids the overhead of another process between
1998 the program and its peer, but introduces a lot of restrictions:
1999 o this option can only be applied to the second socat address.
2001 o it cannot be applied to a part of a dual address.
2003 o the first socat address cannot be OPENSSL or READLINE
2005 o socat options -b, -t, -D, -l, -v, -x become useless
2007 o for both addresses, options ignoreeof, cr, and crnl become use‐
2009 less
2010 o for the second address (the one with option nofork), options
2012 append, cloexec, flock, user, group, mode, nonblock, perm-late,
2013 setlk, and setpgid cannot be applied. Some of these could be
2014 used on the first address though.
2015 pipes Creates a pair of unnamed pipes for interprocess communication
2017 instead of a socket pair.
2018 openpty
2020 Establishes communication with the sub process using a pseudo
2021 terminal created with openpty() instead of the default (socket‐
2022 pair or ptmx).
2023 ptmx Establishes communication with the sub process using a pseudo
2025 terminal created by opening /dev/ptmx or /dev/ptc instead of the
2026 default (socketpair).
2027 pty Establishes communication with the sub process using a pseudo
2029 terminal instead of a socket pair. Creates the pty with an
2030 available mechanism. If openpty and ptmx are both available, it
2031 uses ptmx because this is POSIX compliant (example).
2032 ctty Makes the pty the controlling tty of the sub process (example).
2034 stderr Directs stderr of the sub process to its output channel by mak‐
2036 ing stderr a dup() of stdout (example).
2037 fdin=<fdnum>
2039 Assigns the sub processes input channel to its file descriptor
2040 <fdnum> instead of stdin (0). The program started from the sub‐
2041 process has to use this fd for reading data from socat (exam‐
2042 ple).
2043 fdout=<fdnum>
2045 Assigns the sub processes output channel to its file descriptor
2046 <fdnum> instead of stdout (1). The program started from the sub‐
2047 process has to use this fd for writing data to socat (example).
2048 sighup, sigint, sigquit
2050 Has socat pass signals of this type to the sub process. If no
2051 address has this option, socat terminates on these signals.
2052 TERMIOS option group
2055 For addresses that work on a tty (e.g., stdio, file:/dev/tty,
2057 exec:...,pty), the terminal parameters defined in the UN*X termios
2058 mechanism are made available as address option parameters. Please note
2059 that changes of the parameters of your interactive terminal remain
2060 effective after socat’s termination, so you might have to enter "reset"
2061 or "stty sane" in your shell afterwards. For EXEC and SYSTEM addresses
2062 with option PTY, these options apply to the pty by the child processes.
2063 b0 Disconnects the terminal.
2065 b19200 Sets the serial line speed to 19200 baud. Some other rates are
2067 possible; use something like socat -hh |grep ’ b[1-9]’ to find
2068 all speeds supported by your implementation.
2069 Note: On some operating systems, these options may not be avail‐
2070 able. Use ispeed or ospeed instead.
2071 echo=<bool>
2073 Enables or disables local echo.
2074 icanon=<bool>
2076 Sets or clears canonical mode, enabling line buffering and some
2077 special characters.
2078 raw Sets raw mode, thus passing input and output almost unprocessed.
2080 This option is obsolete, use option rawer or cfmakeraw instead.
2081 rawer Makes terminal rawer than raw option. This option implicitly
2083 turns off echo. (example).
2084 cfmakeraw
2086 Sets raw mode by invoking cfmakeraw() or by simulating this
2087 call. This option implicitly turns off echo.
2088 ignbrk=<bool>
2090 Ignores or interpretes the BREAK character (e.g., ^C)
2091 brkint=<bool>
2093 bs0
2095 bs1
2097 bsdly=<0|1>
2099 clocal=<bool>
2101 cr0
2104 cr1
2105 cr2
2106 cr3
2107 Sets the carriage return delay to 0, 1, 2, or 3, respectively.
2109 0 means no delay, the other values are terminal dependent.
2110 crdly=<0|1|2|3>
2112 cread=<bool>
2114 crtscts=<bool>
2116 cs5
2119 cs6
2120 cs7
2121 cs8
2122 Sets the character size to 5, 6, 7, or 8 bits, respectively.
2124 csize=<0|1|2|3>
2126 cstopb=<bool>
2128 Sets two stop bits, rather than one.
2129 dsusp=<byte>
2131 Sets the value for the VDSUSP character that suspends the cur‐
2132 rent foreground process and reactivates the shell (all except
2133 Linux).
2134 echoctl=<bool>
2136 Echos control characters in hat notation (e.g. ^A)
2137 echoe=<bool>
2139 echok=<bool>
2141 echoke=<bool>
2143 echonl=<bool>
2145 echoprt=<bool>
2147 eof=<byte>
2149 eol=<byte>
2151 eol2=<byte>
2153 erase=<byte>
2155 discard=<byte>
2157 ff0
2159 ff1
2161 ffdly=<bool>
2163 flusho=<bool>
2165 hupcl=<bool>
2167 icrnl=<bool>
2169 iexten=<bool>
2171 igncr=<bool>
2173 ignpar=<bool>
2175 imaxbel=<bool>
2177 inlcr=<bool>
2179 inpck=<bool>
2181 intr=<byte>
2183 isig=<bool>
2185 ispeed=<unsigned-int>
2187 Set the baud rate for incoming data on this line.
2188 See also: ospeed, b19200
2189 istrip=<bool>
2191 iuclc=<bool>
2193 ixany=<bool>
2195 ixoff=<bool>
2197 ixon=<bool>
2199 kill=<byte>
2201 lnext=<byte>
2203 min=<byte>
2205 nl0 Sets the newline delay to 0.
2207 nl1
2209 nldly=<bool>
2211 noflsh=<bool>
2213 ocrnl=<bool>
2215 ofdel=<bool>
2217 ofill=<bool>
2219 olcuc=<bool>
2221 onlcr=<bool>
2223 onlret=<bool>
2225 onocr=<bool>
2227 opost=<bool>
2229 Enables or disables output processing; e.g., converts NL to
2230 CR-NL.
2231 ospeed=<unsigned-int>
2233 Set the baud rate for outgoing data on this line.
2234 See also: ispeed, b19200
2235 parenb=<bool>
2237 Enable parity generation on output and parity checking for
2238 input.
2239 parmrk=<bool>
2241 parodd=<bool>
2243 pendin=<bool>
2245 quit=<byte>
2247 reprint=<byte>
2249 sane Brings the terminal to something like a useful default state.
2251 start=<byte>
2253 stop=<byte>
2255 susp=<byte>
2257 swtc=<byte>
2259 tab0
2261 tab1
2263 tab2
2265 tab3
2267 tabdly=<unsigned-int>
2269 time=<byte>
2271 tostop=<bool>
2273 vt0
2275 vt1
2277 vtdly=<bool>
2279 werase=<byte>
2281 xcase=<bool>
2283 xtabs
2285 i-pop-all
2287 With UNIX System V STREAMS, removes all drivers from the stack.
2288 i-push=<string>
2290 With UNIX System V STREAMS, pushes the driver (module) with the
2291 given name (string) onto the stack. For example, to make sure
2292 that a character device on Solaris supports termios etc, use the
2293 following options:
2294 i-pop-all,i-push=ptem,i-push=ldterm,i-push=ttcompat
2295 PTY option group
2298 These options are intended for use with the pty address type.
2300 link=<filename>
2302 Generates a symbolic link that points to the actual pseudo ter‐
2303 minal (pty). This might help to solve the problem that ptys are
2304 generated with more or less unpredictable names, making it dif‐
2305 ficult to directly access the socat generated pty automatically.
2306 With this option, the user can specify a "fix" point in the file
2307 hierarchy that helps him to access the actual pty (example).
2308 Beginning with socat version 1.4.3, the symbolic link is removed
2309 when the address is closed (but see option unlink-close).
2310 wait-slave
2312 Blocks the open phase until a process opens the slave side of
2313 the pty. Usually, socat continues after generating the pty with
2314 opening the next address or with entering the transfer loop.
2315 With the wait-slave option, socat waits until some process opens
2316 the slave side of the pty before continuing. This option only
2317 works if the operating system provides the poll() system call.
2318 And it depends on an undocumented behaviour of pty’s, so it does
2319 not work on all operating systems. It has successfully been
2320 tested on Linux, FreeBSD, NetBSD, and on Tru64 with openpty.
2321 pty-interval=<seconds>
2323 When the wait-slave option is set, socat periodically checks the
2324 HUP condition using poll() to find if the pty’s slave side has
2325 been opened. The default polling interval is 1s. Use the
2326 pty-interval option [timeval] to change this value.
2327 OPENSSL option group
2330 These options apply to the openssl and openssl-listen address types.
2332 cipher=<cipherlist>
2334 Selects the list of ciphers that may be used for the connection.
2335 See the man page of ciphers , section CIPHER LIST FORMAT, for
2336 detailed information about syntax, values, and default of
2337 <cipherlist>.
2338 Several cipher strings may be given, separated by ’:’. Some
2339 simple cipher strings:
2340 3DES Uses a cipher suite with triple DES.
2342 MD5 Uses a cipher suite with MD5.
2344 aNULL Uses a cipher suite without authentication.
2346 NULL Does not use encryption.
2348 HIGH Uses a cipher suite with "high" encryption. Note that the peer
2350 must support the selected property, or the negotiation will
2351 fail.
2352 method=<ssl-method>
2354 This option is based on deprecated functions and is only avail‐
2355 able when socat was build with option --with-openssl-method.
2356 Sets the protocol version to be used. Valid strings (not case
2357 sensitive) are:
2358 SSL2 Select SSL protocol version 2.
2360 SSL3 Select SSL protocol version 3.
2362 SSL23 Select the best available SSL or TLS protocol.
2364 TLS1 Select TLS protocol version 1.
2366 TLS1.1 Select TLS protocol version 1.1.
2368 TLS1.2 Select TLS protocol version 1.2. When this option is not pro‐
2370 vided OpenSSL negotiates the mothod with its peer.
2371 verify=<bool>
2373 Controls check of the peer’s certificate. Default is 1 (true).
2374 Disabling verify might open your socket for everyone, making the
2375 encryption useless!
2376 cert=<filename>
2378 Specifies the file with the certificate and private key for
2379 authentication. The certificate must be in OpenSSL format
2380 (*.pem). With openssl-listen, use of this option is strongly
2381 recommended. Except with cipher aNULL, "no shared ciphers" error
2382 will occur when no certificate is given.
2383 key=<filename>
2385 Specifies the file with the private key. The private key may be
2386 in this file or in the file given with the cert option. The
2387 party that has to proof that it is the owner of a certificate
2388 needs the private key.
2389 dhparams=<filename>
2391 Specifies the file with the Diffie Hellman parameters. These
2392 parameters may also be in the file given with the cert option in
2393 which case the dhparams option is not needed.
2394 cafile=<filename>
2396 Specifies the file with the trusted (root) authority certifi‐
2397 cates. The file must be in PEM format and should contain one or
2398 more certificates. The party that checks the authentication of
2399 its peer trusts only certificates that are in this file.
2400 capath=<dirname>
2402 Specifies the directory with the trusted (root) certificates.
2403 The directory must contain certificates in PEM format and their
2404 hashes (see OpenSSL documentation)
2405 egd=<filename>
2407 On some systems, openssl requires an explicit source of random
2408 data. Specify the socket name where an entropy gathering daemon
2409 like egd provides random data, e.g. /dev/egd-pool.
2410 pseudo On systems where openssl cannot find an entropy source and where
2412 no entropy gathering daemon can be utilized, this option acti‐
2413 vates a mechanism for providing pseudo entropy. This is achieved
2414 by taking the current time in microseconds for feeding the libc
2415 pseudo random number generator with an initial value. openssl is
2416 then feeded with output from random() calls.
2417 NOTE:This mechanism is not sufficient for generation of secure
2418 keys!
2419 compress
2421 Enable or disable the use of compression for a connection. Set‐
2422 ting this to "none" disables compression, setting it to "auto"
2423 lets OpenSSL choose the best available algorithm supported by
2424 both parties. The default is to not touch any compres‐
2425 sion-related settings. NOTE: Requires OpenSSL 0.9.8 or higher
2426 and disabling compression with OpenSSL 0.9.8 affects all new
2427 connections in the process.
2428 commonname=<string>
2430 Specify the commonname that the peer certificate must match.
2431 With OPENSSL-CONNECT address this overrides the given hostname
2432 or IP target address; with OPENSSL-LISTEN this turns on check of
2433 peer certificates commonname. This option has only meaning when
2434 option verify is not disabled and the chosen cipher provides a
2435 peer certificate.
2436 fips Enables FIPS mode if compiled in. For info about the FIPS
2438 encryption implementation standard see http://oss-insti‐
2439 tute.org/fips-faq.html. This mode might require that the
2440 involved certificates are generated with a FIPS enabled version
2441 of openssl. Setting or clearing this option on one socat address
2442 affects all OpenSSL addresses of this process.
2443 RETRY option group
2446 Options that control retry of some system calls, especially connection
2448 attempts.
2449 retry=<num>
2451 Number of retries before the connection or listen attempt is
2452 aborted. Default is 0, which means just one attempt.
2453 interval=<timespec>
2455 Time between consecutive attempts (seconds, [timespec]). Default
2456 is 1 second.
2457 forever
2459 Performs an unlimited number of retry attempts.
2460 TUN option group
2463 Options that control Linux TUN/TAP interface device addresses.
2465 tun-device=<device-file>
2467 Instructs socat to take another path for the TUN clone device.
2468 Default is /dev/net/tun.
2469 tun-name=<if-name>
2471 Gives the resulting network interface a specific name instead of
2472 the system generated (tun0, tun1, etc.)
2473 tun-type=[tun|tap]
2475 Sets the type of the TUN device; use this option to generate a
2476 TAP device. See the Linux docu for the difference between these
2477 types. When you try to establish a tunnel between two TUN
2478 devices, their types should be the same.
2479 iff-no-pi
2481 Sets the IFF_NO_PI flag which controls if the device includes
2482 additional packet information in the tunnel. When you try to
2483 establish a tunnel between two TUN devices, these flags should
2484 have the same values.
2485 iff-up Sets the TUN network interface status UP. Strongly recommended.
2487 iff-broadcast
2489 Sets the BROADCAST flag of the TUN network interface.
2490 iff-debug
2492 Sets the DEBUG flag of the TUN network interface.
2493 iff-loopback
2495 Sets the LOOPBACK flag of the TUN network interface.
2496 iff-pointopoint
2498 Sets the POINTOPOINT flag of the TUN device.
2499 iff-notrailers
2501 Sets the NOTRAILERS flag of the TUN device.
2502 iff-running
2504 Sets the RUNNING flag of the TUN device.
2505 iff-noarp
2507 Sets the NOARP flag of the TUN device.
2508 iff-promisc
2510 Sets the PROMISC flag of the TUN device.
2511 iff-allmulti
2513 Sets the ALLMULTI flag of the TUN device.
2514 iff-master
2516 Sets the MASTER flag of the TUN device.
2517 iff-slave
2519 Sets the SLAVE flag of the TUN device.
2520 iff-multicast
2522 Sets the MULTICAST flag of the TUN device.
2523 iff-portsel
2525 Sets the PORTSEL flag of the TUN device.
2526 iff-automedia
2528 Sets the AUTOMEDIA flag of the TUN device.
2529 iff-dynamic
2531 Sets the DYNAMIC flag of the TUN device.
2532
2535 This section explains the different data types that address parameters
2536 and address options can take.
2537 address-range
2539 Is currently only implemented for IPv4 and IPv6. See
2540 address-option `range’
2541 bool "0" or "1"; if value is omitted, "1" is taken.
2543 byte An unsigned int number, read with strtoul() , lower or equal to
2545 UCHAR_MAX .
2546 command-line
2548 A string specifying a program name and its arguments, separated
2549 by single spaces.
2550 data A raw data specification following dalan syntax. Currently the
2552 only valid form is a string starting with ’x’ followed by an
2553 even number of hex digits, specifying a sequence of bytes.
2554 directory
2556 A string with usual UN*X directory name semantics.
2557 facility
2559 The name of a syslog facility in lower case characters.
2560 fdnum An unsigned int type, read with strtoul() , specifying a UN*X
2562 file descriptor.
2563 filename
2565 A string with usual UN*X filename semantics.
2566 group If the first character is a decimal digit, the value is read
2568 with strtoul() as unsigned integer specifying a group id. Other‐
2569 wise, it must be an existing group name.
2570 int A number following the rules of the strtol() function with base
2572 "0", i.e. decimal number, octal number with leading "0", or
2573 hexadecimal number with leading "0x". The value must fit into a
2574 C int.
2575 interface
2577 A string specifying the device name of a network interface as
2578 shown by ifconfig or procan, e.g. "eth0".
2579 IP address
2581 An IPv4 address in numbers-and-dots notation, an IPv6 address in
2582 hex notation enclosed in brackets, or a hostname that resolves
2583 to an IPv4 or an IPv6 address.
2584 Examples: 127.0.0.1, [::1], www.dest-unreach.org, dns1
2585 IPv4 address
2587 An IPv4 address in numbers-and-dots notation or a hostname that
2588 resolves to an IPv4 address.
2589 Examples: 127.0.0.1, www.dest-unreach.org, dns2
2590 IPv6 address
2592 An iPv6 address in hexnumbers-and-colons notation enclosed in
2593 brackets, or a hostname that resolves to an IPv6 address.
2594 Examples: [::1], [1234:5678:9abc:def0:1234:5678:9abc:def0],
2595 ip6name.domain.org
2596 long A number read with strtol() . The value must fit into a C long.
2598 long long
2600 A number read with strtoll() . The value must fit into a C long
2601 long.
2602 off_t An implementation dependend signed number, usually 32 bits, read
2604 with strtol or strtoll.
2605 off64_t
2607 An implementation dependend signed number, usually 64 bits, read
2608 with strtol or strtoll.
2609 mode_t An unsigned integer, read with strtoul() , specifying mode (per‐
2611 mission) bits.
2612 pid_t A number, read with strtol() , specifying a process id.
2614 port A uint16_t (16 bit unsigned number) specifying a TCP or UDP
2616 port, read with strtoul() .
2617 protocol
2619 An unsigned 8 bit number, read with strtoul() .
2620 size_t An unsigned number with size_t limitations, read with strtoul .
2622 sockname
2624 A socket address. See address-option `bind’
2625 string A sequence of characters, not containing ’\0’ and, depending on
2627 the position within the command line, ’:’, ’,’, or "!!". Note
2628 that you might have to escape shell meta characters in the com‐
2629 mand line.
2630 TCP service
2632 A service name, not starting with a digit, that is resolved by
2633 getservbyname() , or an unsigned int 16 bit number read with
2634 strtoul() .
2635 timeval
2637 A double float specifying seconds; the number is mapped into a
2638 struct timeval, consisting of seconds and microseconds.
2639 timespec
2641 A double float specifying seconds; the number is mapped into a
2642 struct timespec, consisting of seconds and nanoseconds.
2643 UDP service
2645 A service name, not starting with a digit, that is resolved by
2646 getservbyname() , or an unsigned int 16 bit number read with
2647 strtoul() .
2648 unsigned int
2650 A number read with strtoul() . The value must fit into a C
2651 unsigned int.
2652 user If the first character is a decimal digit, the value is read
2654 with strtoul() as unsigned integer specifying a user id. Other‐
2655 wise, it must be an existing user name.
2656
2659 socat - TCP4:www.domain.org:80
2660 transfers data between STDIO (-) and a TCP4 connection to port
2663 80 of host www.domain.org. This example results in an interac‐
2664 tive connection similar to telnet or netcat. The stdin terminal
2665 parameters are not changed, so you may close the relay with ^D
2666 or abort it with ^C.
2667 socat -d -d READLINE,history=$HOME/.http_history \
2669 TCP4:www.domain.org:www,crnl
2670 this is similar to the previous example, but you can edit the
2672 current line in a bash like manner (READLINE) and use the his‐
2673 tory file .http_history; socat prints messages about progress
2674 (-d -d). The port is specified by service name (www), and cor‐
2675 rect network line termination characters (crnl) instead of NL
2676 are used.
2677 socat TCP4-LISTEN:www TCP4:www.domain.org:www
2679 installs a simple TCP port forwarder. With TCP4-LISTEN it lis‐
2682 tens on local port "www" until a connection comes in, accepts
2683 it, then connects to the remote host (TCP4) and starts data
2684 transfer. It will not accept a second connection.
2685 socat -d -d -lmlocal2 \
2687 TCP4-LISTEN:80,bind=myaddr1,reuseaddr,fork,su=nobody,range=10.0.0.0/8 \
2688 TCP4:www.domain.org:80,bind=myaddr2
2689 TCP port forwarder, each side bound to another local IP address
2691 (bind). This example handles an almost arbitrary number of par‐
2692 allel or consecutive connections by fork’ing a new process after
2693 each accept() . It provides a little security by su’ing to user
2694 nobody after forking; it only permits connections from the pri‐
2695 vate 10 network (range); due to reuseaddr, it allows immediate
2696 restart after master process’s termination, even if some child
2697 sockets are not completely shut down. With -lmlocal2, socat
2698 logs to stderr until successfully reaching the accept loop. Fur‐
2699 ther logging is directed to syslog with facility local2.
2700 socat TCP4-LISTEN:5555,fork,tcpwrap=script \
2702 EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr
2703 a simple server that accepts connections (TCP4-LISTEN) and
2705 fork’s a new child process for each connection; every child acts
2706 as single relay. The client must match the rules for daemon
2707 process name "script" in /etc/hosts.allow and /etc/hosts.deny,
2708 otherwise it is refused access (see "man 5 hosts_access"). For
2709 EXEC’uting the program, the child process chroot’s to
2710 /home/sandbox, su’s to user sandbox, and then starts the program
2711 /home/sandbox/bin/myscript. Socat and myscript communicate via a
2712 pseudo tty (pty); myscript’s stderr is redirected to stdout, so
2713 its error messages are transferred via socat to the connected
2714 client.
2715 socat EXEC:"mail.sh target@domain.com",fdin=3,fdout=4 \
2717 TCP4:mail.relay.org:25,crnl,bind=alias1.server.org,mss=512
2718 mail.sh is a shell script, distributed with socat, that imple‐
2720 ments a simple SMTP client. It is programmed to "speak" SMTP on
2721 its FDs 3 (in) and 4 (out). The fdin and fdout options tell
2722 socat to use these FDs for communication with the program.
2723 Because mail.sh inherits stdin and stdout while socat does not
2724 use them, the script can read a mail body from stdin. Socat
2725 makes alias1 your local source address (bind), cares for correct
2726 network line termination (crnl) and sends at most 512 data bytes
2727 per packet (mss).
2728 socat -,escape=0x0f /dev/ttyS0,rawer,crnl
2730 opens an interactive connection via the serial line, e.g. for
2733 talking with a modem. rawer sets the console’s and ttyS0’s ter‐
2734 minal parameters to practicable values, crnl converts to correct
2735 newline characters. escape allows terminating the socat process
2736 with character control-O. Consider using READLINE instead of
2737 the first address.
2738 socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
2740 SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20
2741 with UNIX-LISTEN, socat opens a listening UNIX domain socket
2743 /tmp/.X11-unix/X1. This path corresponds to local XWindow dis‐
2744 play :1 on your machine, so XWindow client connections to DIS‐
2745 PLAY=:1 are accepted. Socat then speaks with the SOCKS4 server
2746 host.victim.org that might permit sourceport 20 based connec‐
2747 tions due to an FTP related weakness in its static IP filters.
2748 Socat pretends to be invoked by socksuser nobody, and requests
2749 to be connected to loopback port 6000 (only weak sockd configu‐
2750 rations will allow this). So we get a connection to the victims
2751 XWindow server and, if it does not require MIT cookies or Ker‐
2752 beros authentication, we can start work. Please note that there
2753 can only be one connection at a time, because TCP can establish
2754 only one session with a given set of addresses and ports.
2755 socat -u /tmp/readdata,seek-end=0,ignoreeof -
2757 this is an example for unidirectional data transfer (-u). Socat
2760 transfers data from file /tmp/readdata (implicit address GOPEN),
2761 starting at its current end (seek-end=0 lets socat start reading
2762 at current end of file; use seek=0 or no seek option to first
2763 read the existing data) in a "tail -f" like mode (ignoreeof).
2764 The "file" might also be a listening UNIX domain socket (do not
2765 use a seek option then).
2766 (sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |
2768 socat - EXEC:'ssh -l user server',pty,setsid,ctty
2769 EXEC’utes an ssh session to server. Uses a pty for communication
2771 between socat and ssh, makes it ssh’s controlling tty (ctty),
2772 and makes this pty the owner of a new process group (setsid), so
2773 ssh accepts the password from socat.
2774 socat -u TCP4-LISTEN:3334,reuseaddr,fork \
2776 OPEN:/tmp/in.log,creat,append
2777 implements a simple network based message collector. For each
2779 client connecting to port 3334, a new child process is generated
2780 (option fork). All data sent by the clients are append’ed to
2781 the file /tmp/in.log. If the file does not exist, socat creat’s
2782 it. Option reuseaddr allows immediate restart of the server
2783 process.
2784 socat READLINE,noecho=’[Pp]assword:’ EXEC:’ftp ftp.server.com’,pty,set‐
2786 sid,ctty
2787 wraps a command line history (READLINE) around the EXEC’uted ftp
2790 client utility. This allows editing and reuse of FTP commands
2791 for relatively comfortable browsing through the ftp directory
2792 hierarchy. The password is echoed! pty is required to have ftp
2793 issue a prompt. Nevertheless, there may occur some confusion
2794 with the password and FTP prompts.
2795 socat PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \
2797 EXEC:"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"
2798 generates a pseudo terminal device (PTY) on the client that can
2800 be reached under the symbolic link $HOME/dev/vmodem0. An appli‐
2801 cation that expects a serial line or modem can be configured to
2802 use $HOME/dev/vmodem0; its traffic will be directed to a modem‐
2803 server via ssh where another socat instance links it to
2804 /dev/ttyS0.
2805 socat TCP4-LISTEN:2022,reuseaddr,fork \
2807 PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass
2808 starts a forwarder that accepts connections on port 2022, and
2810 directs them through the proxy daemon listening on port 3128
2811 (proxyport) on host proxy, using the CONNECT method, where they
2812 are authenticated as "user" with "pass" (proxyauth). The proxy
2813 should establish connections to host www.domain.org on port 22
2814 then.
2815 socat - SSL:server:4443,cafile=server.crt,cert=client.pem
2817 is an OpenSSL client that tries to establish a secure connection
2820 to an SSL server. Option cafile specifies a file that contains
2821 trust certificates: we trust the server only when it presents
2822 one of these certificates and proofs that it owns the related
2823 private key. Otherwise the connection is terminated. With cert
2824 a file containing the client certificate and the associated pri‐
2825 vate key is specified. This is required in case the server
2826 wishes a client authentication; many Internet servers do not.
2827 The first address (’-’) can be replaced by almost any other
2828 socat address.
2829 socat OPENSSL-LISTEN:4443,reuse‐
2831 addr,pf=ip4,fork,cert=server.pem,cafile=client.crt PIPE
2832 is an OpenSSL server that accepts TCP connections, presents the
2835 certificate from the file server.pem and forces the client to
2836 present a certificate that is verified against cafile.crt.
2837 The second address (’PIPE’) can be replaced by almost any other
2838 socat address.
2839 For instructions on generating and distributing OpenSSL keys and
2840 certificates see the additional socat docu socat-openssl.txt.
2841 echo |socat -u - file:/tmp/bigfile,create,largefile,seek=100000000000
2843 creates a 100GB sparse file; this requires a file system type
2846 that supports this (ext2, ext3, reiserfs, jfs; not minix, vfat).
2847 The operation of writing 1 byte might take long (reiserfs: some
2848 minutes; ext2: "no" time), and the resulting file can consume
2849 some disk space with just its inodes (reiserfs: 2MB; ext2:
2850 16KB).
2851 socat tcp-l:7777,reuseaddr,fork system:’filan -i 0 -s >&2’,nofork
2853 listens for incoming TCP connections on port 7777. For each
2856 accepted connection, invokes a shell. This shell has its stdin
2857 and stdout directly connected to the TCP socket (nofork). The
2858 shell starts filan and lets it print the socket addresses to
2859 stderr (your terminal window).
2860 echo -e "\0\14\0\0\c" |socat -u -
2862 file:/usr/bin/squid.exe,seek=0x00074420
2863 functions as primitive binary editor: it writes the 4 bytes 000
2866 014 000 000 to the executable /usr/bin/squid at offset
2867 0x00074420 (this is a real world patch to make the squid exe‐
2868 cutable from Cygwin run under Windows, actual per May 2004).
2869 socat - tcp:www.blackhat.org:31337,readbytes=1000
2871 connects to an unknown service and prevents being flooded.
2874 socat -U TCP:target:9999,end-close TCP-L:8888,reuseaddr,fork
2876 merges data arriving from different TCP streams on port 8888 to
2879 just one stream to target:9999. The end-close option prevents
2880 the child processes forked off by the second address from termi‐
2881 nating the shared connection to 9999 (close(2) just unlinks the
2882 inode which stays active as long as the parent process lives;
2883 shutdown(2) would actively terminate the connection).
2884 socat - UDP4-DATAGRAM:192.168.1.0:123,sp=123,broad‐
2886 cast,range=192.168.1.0/24
2887 sends a broadcast to the network 192.168.1.0/24 and receives the
2890 replies of the timeservers there. Ignores NTP packets from hosts
2891 outside this network.
2892 socat - SOCKET-DATA‐
2894 GRAM:2:2:17:x007bxc0a80100x0000000000000000,bind=x007bx00000000x0000000000000000,set‐
2895 sock‐
2896 opt-int=1:6:1,range=x0000xc0a80100x0000000000000000:x0000xffffff00x0000000000000000
2897 is semantically equivalent to the previous example, but all
2900 parameters are specified in generic form. the value 6 of set‐
2901 sockopt-int is the Linux value for SO_BROADCAST.
2902 socat - IP4-DATAGRAM:255.255.255.255:44,broadcast,range=10.0.0.0/8
2904 sends a broadcast to the local network(s) using protocol 44.
2907 Accepts replies from the private address range only.
2908 socat - UDP4-DATAGRAM:224.255.0.1:6666,bind=:6666,ip-add-member‐
2910 ship=224.255.0.1:eth0
2911 transfers data from stdin to the specified multicast address
2914 using UDP. Both local and remote ports are 6666. Tells the
2915 interface eth0 to also accept multicast packets of the given
2916 group. Multiple hosts on the local network can run this command,
2917 so all data sent by any of the hosts will be received by all the
2918 other ones. Note that there are many possible reasons for fail‐
2919 ure, including IP-filters, routing issues, wrong interface
2920 selection by the operating system, bridges, or a badly config‐
2921 ured switch.
2922 socat TCP:host2:4443 TUN:192.168.255.1/24,up
2924 establishes one side of a virtual (but not private!) network
2927 with host2 where a similar process might run, with UDP-L and tun
2928 address 192.168.255.2. They can reach each other using the
2929 addresses 192.168.255.1 and 192.168.255.2. Note that streaming
2930 eg. via TCP or SSL does not guarantee to retain packet bound‐
2931 aries and may thus cause packet loss.
2932 socat PTY,link=/var/run/ppp,rawer INTERFACE:hdlc0
2934 circumvents the problem that pppd requires a serial device and
2937 thus might not be able to work on a synchronous line that is
2938 represented by a network device. socat creates a PTY to make
2939 pppd happy, binds to the network interface hdlc0, and can trans‐
2940 fer data between both devices. Use pppd on device /var/run/ppp
2941 then.
2942 socat -T 1 -d -d TCP-L:10081,reuseaddr,fork,crlf SYSTEM:"echo -e
2944 \"\\\"HTTP/1.0 200 OK\\\nDocumentType: text/plain\\\n\\\ndate:
2945 \$\(date\)\\\nserver:\$SOCAT_SOCKADDR:\$SOCAT_SOCKPORT\\\nclient:
2946 \$SOCAT_PEERADDR:\$SOCAT_PEERPORT\\\n\\\"\"; cat; echo -e
2947 \"\\\"\\\n\\\"\""
2948 creates a simple HTTP echo server: each HTTP client that con‐
2951 nects gets a valid HTTP reply that contains information about
2952 the client address and port as it is seen by the server host,
2953 the host address (which might vary on multihomed servers), and
2954 the original client request.
2955 socat -d -d UDP4-RECVFROM:9999,so-broadcast,so-timestamp,ip-pkt‐
2957 info,ip-recverr,ip-recvopts,ip-recvtos,ip-recvttl!!- SYSTEM:’export;
2958 sleep 1’ |grep SOCAT
2959 waits for an incoming UDP packet on port 9999 and prints the
2962 environment variables provided by socat. On BSD based systems
2963 you have to replace ip-pktinfo with ip-recvdstaddr,ip-recvif.
2964 Especially interesting is SOCAT_IP_DSTADDR: it contains the tar‐
2965 get address of the packet which may be a unicast, multicast, or
2966 broadcast address.
2967
2972 Socat uses a logging mechanism that allows filtering messages by sever‐
2973 ity. The severities provided are more or less compatible to the appro‐
2974 priate syslog priority. With one or up to four occurrences of the -d
2975 command line option, the lowest priority of messages that are issued
2976 can be selected. Each message contains a single uppercase character
2977 specifying the messages severity (one of F, E, W, N, I, or D)
2978 FATAL: Conditions that require unconditional and immediate program ter‐
2980 mination.
2981 ERROR: Conditions that prevent proper program processing. Usually the
2983 program is terminated (see option -s).
2984 WARNING:
2986 Something did not function correctly or is in a state where cor‐
2987 rect further processing cannot be guaranteed, but might be pos‐
2988 sible.
2989 NOTICE:
2991 Interesting actions of the program, e.g. for supervising socat
2992 in some kind of server mode.
2993 INFO: Description of what the program does, and maybe why it happens.
2995 Allows monitoring the lifecycles of file descriptors.
2996 DEBUG: Description of how the program works, all system or library
2998 calls and their results.
2999 Log messages can be written to stderr, to a file, or to syslog.
3002 On exit, socat gives status 0 if it terminated due to EOF or inactivity
3004 timeout, with a positive value on error, and with a negative value on
3005 fatal error.
3006
3008 /usr/bin/socat
3009 /usr/bin/filan
3010 /usr/bin/procan
3011
3013 Input variables carry information from the environment to socat, output
3014 variables are set by socat for use in executed scripts and programs.
3015 In the output variables beginning with "SOCAT" this prefix is actually
3017 replaced by the upper case name of the executable or the value of
3018 option -lp.
3019 SOCAT_DEFAULT_LISTEN_IP (input)
3021 (Values 4 or 6) Sets the IP version to be used for listen, recv,
3022 and recvfrom addresses if no pf (protocol-family) option is
3023 given. Is overridden by socat options -4 or -6.
3024 SOCAT_PREFERRED_RESOLVE_IP (input)
3026 (Values 0, 4, or 6) Sets the IP version to be used when resolv‐
3027 ing target host names when version is not specified by address
3028 type, option pf (protocol-family), or address format. If name
3029 resolution does not return a matching entry, the first result
3030 (with differing IP version) is taken. With value 0, socat always
3031 selects the first record and its IP version.
3032 SOCAT_FORK_WAIT (input)
3034 Specifies the time (seconds) to sleep the parent and child pro‐
3035 cesses after successful fork(). Useful for debugging.
3036 SOCAT_VERSION (output)
3038 Socat sets this variable to its version string, e.g. "1.7.0.0"
3039 for released versions or e.g. "1.6.0.1+envvar" for temporary
3040 versions; can be used in scripts invoked by socat.
3041 SOCAT_PID (output)
3043 Socat sets this variable to its process id. In case of fork
3044 address option, SOCAT_PID gets the child processes id. Forking
3045 for exec and system does not change SOCAT_PID.
3046 SOCAT_PPID (output)
3048 Socat sets this variable to its process id. In case of fork,
3049 SOCAT_PPID keeps the pid of the master process.
3050 SOCAT_PEERADDR (output)
3052 With passive socket addresses (all LISTEN and RECVFROM
3053 addresses), this variable is set to a string describing the
3054 peers socket address. Port information is not included.
3055 SOCAT_PEERPORT (output)
3057 With appropriate passive socket addresses (TCP, UDP, and SCTP -
3058 LISTEN and RECVFROM), this variable is set to a string contain‐
3059 ing the number of the peer port.
3060 SOCAT_SOCKADDR (output)
3062 With all LISTEN addresses, this variable is set to a string
3063 describing the local socket address. Port information is not
3064 included example
3065 SOCAT_SOCKPORT (output)
3067 With TCP-LISTEN, UDP-LISTEN, and SCTP-LISTEN addresses, this
3068 variable is set to the local port.
3069 SOCAT_TIMESTAMP (output)
3071 With all RECVFROM addresses where address option so-timestamp is
3072 applied, socat sets this variable to the resulting timestamp.
3073 SOCAT_IP_OPTIONS (output)
3075 With all IPv4 based RECVFROM addresses where address option
3076 ip-recvopts is applied, socat fills this variable with the IP
3077 options of the received packet.
3078 SOCAT_IP_DSTADDR (output)
3080 With all IPv4 based RECVFROM addresses where address option
3081 ip-recvdstaddr (BSD) or ip-pktinfo (other platforms) is applied,
3082 socat sets this variable to the destination address of the
3083 received packet. This is particularly useful to identify broad‐
3084 cast and multicast addressed packets.
3085 SOCAT_IP_IF (output)
3087 With all IPv4 based RECVFROM addresses where address option
3088 ip-recvif (BSD) or ip-pktinfo (other platforms) is applied,
3089 socat sets this variable to the name of the interface where the
3090 packet was received.
3091 SOCAT_IP_LOCADDR (output)
3093 With all IPv4 based RECVFROM addresses where address option
3094 ip-pktinfo is applied, socat sets this variable to the address
3095 of the interface where the packet was received.
3096 SOCAT_IP_TOS (output)
3098 With all IPv4 based RECVFROM addresses where address option
3099 ip-recvtos is applied, socat sets this variable to the TOS (type
3100 of service) of the received packet.
3101 SOCAT_IP_TTL (output)
3103 With all IPv4 based RECVFROM addresses where address option
3104 ip-recvttl is applied, socat sets this variable to the TTL (time
3105 to live) of the received packet.
3106 SOCAT_IPV6_HOPLIMIT (output)
3108 With all IPv6 based RECVFROM addresses where address option
3109 ipv6-recvhoplimit is applied, socat sets this variable to the
3110 hoplimit value of the received packet.
3111 SOCAT_IPV6_DSTADDR (output)
3113 With all IPv6 based RECVFROM addresses where address option
3114 ipv6-recvpktinfo is applied, socat sets this variable to the
3115 destination address of the received packet.
3116 SOCAT_IPV6_TCLASS (output)
3118 With all IPv6 based RECVFROM addresses where address option
3119 ipv6-recvtclass is applied, socat sets this variable to the
3120 transfer class of the received packet.
3121 SOCAT_OPENSSL_X509_ISSUER (output)
3123 Issuer field from peer certificate
3124 SOCAT_OPENSSL_X509_SUBJECT (output)
3126 Subject field from peer certificate
3127 SOCAT_OPENSSL_X509_COMMONNAME (output)
3129 commonName entries from peer certificates subject. Multiple val‐
3130 ues are separated by " // ".
3131 SOCAT_OPENSSL_X509_* (output)
3133 all other entries from peer certificates subject
3134 SOCAT_OPENSSL_X509V3_DNS (output)
3136 DNS entries from peer certificates extensions - subjectAltName
3137 field. Multiple values are separated by " // ".
3138 HOSTNAME (input)
3140 Is used to determine the hostname for logging (see -lh).
3141 LOGNAME (input)
3143 Is used as name for the socks client user name if no socksuser
3144 is given.
3145 With options su and su-d, LOGNAME is set to the given user name.
3146 USER (input)
3148 Is used as name for the socks client user name if no socksuser
3149 is given and LOGNAME is empty.
3150 With options su and su-d, USER is set to the given user name.
3151 SHELL (output)
3153 With options su and su-d, SHELL is set to the login shell of the
3154 given user.
3155 PATH (output)
3157 Can be set with option path for exec and system addresses.
3158 HOME (output)
3160 With options su and su-d, HOME is set to the home directory of
3161 the given user.
3162
3164 The work of the following groups and organizations was invaluable for
3165 this project:
3166 The FSF (GNU, http://www.fsf.org/ project with their free and portable
3168 development software and lots of other useful tools and libraries.
3169 The Linux developers community (http://www.linux.org/) for providing a
3171 free, open source operating system.
3172 The Open Group (http://www.unix-systems.org/) for making their standard
3174 specifications available on the Internet for free.
3175
3177 This man page describes version 1.7.3 of socat.
3178
3180 Addresses cannot be nested, so a single socat process cannot, e.g.,
3181 drive ssl over socks.
3182 Address option ftruncate without value uses default 1 instead of 0.
3184 Verbose modes (-x and/or -v) display line termination characters incon‐
3186 sistently when address options cr or crnl are used: They show the data
3187 after conversion in either direction.
3188 The data transfer blocksize setting (-b) is ignored with address read‐
3190 line.
3191 Send bug reports to <socat@dest-unreach.org>
3193
3195 nc(1), rinetd(8), openssl(1), stunnel(8), rlwrap(1), setsid(1)
3196 Socat home page http://www.dest-unreach.org/socat/
3198
3200 Gerhard Rieger <rieger@dest-unreach.org> and contributors
3201 socat(1)