1socat(1)                                                              socat(1)
2
3
4

NAME

6       socat - Multipurpose relay (SOcket CAT)
7

SYNOPSIS

9       socat [options] <address> <address>
10       socat -V
11       socat -h[h[h]] | -?[?[?]]
12       filan
13       procan
14

DESCRIPTION

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
23       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
28       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
33       The life cycle of a socat instance typically consists of four phases.
34
35       In the init phase, the command line options are parsed and  logging  is
36       initialized.
37
38       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
43       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
50       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

OPTIONS

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
62       -V     Print version and available feature information to  stdout,  and
63              exit.
64
65       -h | -?
66              Print  a help text to stdout describing command line options and
67              available address types, and exit.
68
69       -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
74       -hhh | -???
75              Like -hh, plus a list of all available address option names.
76
77       -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
81       -d -d  Prints fatal, error, warning, and notice messages.
82
83       -d -d -d
84              Prints fatal, error, warning, notice, and info messages.
85
86       -d -d -d -d
87              Prints fatal, error, warning, notice, info, and debug messages.
88
89       -D     Logs information about  file  descriptors  before  starting  the
90              transfer phase.
91
92       -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
98       -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
103       -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
107       -lp<progname>
108              Overrides the program name printed in error  messages  and  used
109              for constructing environment variable names.
110
111       -lu    Extends  the  timestamp of error messages to microsecond resolu‐
112              tion. Does not work when logging to syslog.
113
114       -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
122       -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
126       -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
131       -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
136       -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
140       -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
146       -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
154       -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
160       -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
164       -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
168       -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
173       -L<lockfile>
174              If  lockfile  exists,  exits  with  error.  If lockfile does not
175              exist, creates it and continues, unlinks lockfile on exit.
176
177       -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
182       -4     Use IP version 4 in case that the addresses do not implicitly or
183              explicitly specify a version; this is the default.
184
185       -6     Use IP version 6 in case that the addresses do not implicitly or
186              explicitly specify a version.
187
188

ADDRESS SPECIFICATIONS

190       With the address command line arguments, the user gives socat  instruc‐
191       tions and the necessary information for establishing the byte streams.
192
193       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
198       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
205       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
209       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
218       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
225       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
230       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

ADDRESS TYPES

239       This section describes the available address types with their keywords,
240       parameters, and semantics.
241
242       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
256       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
272       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
278       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
290       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
301       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
309       IP4-SENDTO:<host>:<protocol>
310              Like IP-SENDTO, but always uses IPv4.
311              Option groups: FD,SOCKET,IP4
312
313       IP6-SENDTO:<host>:<protocol>
314              Like IP-SENDTO, but always uses IPv6.
315              Option groups: FD,SOCKET,IP6
316
317
318       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
332       IP4-DATAGRAM:<host>:<protocol>
333              Like IP-DATAGRAM, but always uses IPv4.  (example)
334              Option groups: FD,SOCKET,IP4,RANGE
335
336       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
341
342       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
361       IP4-RECVFROM:<protocol>
362              Like IP-RECVFROM, but always uses IPv4.
363              Option groups: FD,SOCKET,IP4,CHILD,RANGE
364
365       IP6-RECVFROM:<protocol>
366              Like IP-RECVFROM, but always uses IPv6.
367              Option groups: FD,SOCKET,IP6,CHILD,RANGE
368
369
370       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
382       IP4-RECV:<protocol>
383              Like IP-RECV, but always uses IPv4.
384              Option groups: FD,SOCKET,IP4,RANGE
385
386       IP6-RECV:<protocol>
387              Like IP-RECV, but always uses IPv6.
388              Option groups: FD,SOCKET,IP6,RANGE
389
390
391       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
400       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
419       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
435       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
451       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
460       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
472       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
480       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
489       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
500       SCTP4-CONNECT:<host>:<port>
501              Like SCTP-CONNECT, but only supports IPv4 protocol.
502              Option groups: FD,SOCKET,IP4,SCTP,CHILD,RETRY
503
504       SCTP6-CONNECT:<host>:<port>
505              Like SCTP-CONNECT, but only supports IPv6 protocol.
506              Option groups: FD,SOCKET,IP6,SCTP,CHILD,RETRY
507
508       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
520       SCTP4-LISTEN:<port>
521              Like SCTP-LISTEN, but only supports IPv4 protocol.
522              Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4,SCTP,RETRY
523
524       SCTP6-LISTEN:<port>
525              Like SCTP-LISTEN, but only supports IPv6 protocol.
526              Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6,SCTP,RETRY
527
528       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
545       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
562       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
579       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
593       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
607       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
621       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
630       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
635       STDERR Uses file descriptor 2.
636              Option groups: FD (TERMIOS,REG,SOCKET)
637              See also: FD
638
639       STDIN  Uses file descriptor 0.
640              Option groups: FD (TERMIOS,REG,SOCKET)
641              Useful options: readbytes
642              See also: FD
643
644       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
649       STDOUT Uses file descriptor 1.
650              Option groups: FD (TERMIOS,REG,SOCKET)
651              See also: FD
652
653       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
665       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
675       TCP4:<host>:<port>
676              Like TCP, but only supports IPv4 protocol (example).
677              Option groups: FD,SOCKET,IP4,TCP,RETRY
678
679       TCP6:<host>:<port>
680              Like TCP, but only supports IPv6 protocol.
681              Option groups: FD,SOCKET,IP6,TCP,RETRY
682
683       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
695       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
699       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
704       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
717       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
728       UDP4:<host>:<port>
729              Like UDP, but only supports IPv4 protocol.
730              Option groups: FD,SOCKET,IP4
731
732       UDP6:<host>:<port>
733              Like UDP, but only supports IPv6 protocol.
734              Option groups: FD,SOCKET,IP6
735
736       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
750       UDP4-DATAGRAM:<address>:<port>
751              Like  UDP-DATAGRAM,  but  only supports IPv4 protocol (example1,
752              example2).
753              Option groups: FD,SOCKET,IP4, RANGE
754
755       UDP6-DATAGRAM:<address>:<port>
756              Like UDP-DATAGRAM, but only supports IPv6 protocol.
757              Option groups: FD,SOCKET,IP6,RANGE
758
759       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
771       UDP4-LISTEN:<port>
772              Like UDP-LISTEN, but only support IPv4 protocol.
773              Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP4
774
775       UDP6-LISTEN:<port>
776              Like UDP-LISTEN, but only support IPv6 protocol.
777              Option groups: FD,SOCKET,LISTEN,CHILD,RANGE,IP6
778
779       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
792       UDP4-SENDTO:<host>:<port>
793              Like UDP-SENDTO, but only supports IPv4 protocol.
794              Option groups: FD,SOCKET,IP4
795
796       UDP6-SENDTO:<host>:<port>
797              Like UDP-SENDTO, but only supports IPv6 protocol.
798              Option groups: FD,SOCKET,IP6
799
800       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
814       UDP4-RECVFROM:<port>
815              Like UDP-RECVFROM, but only supports IPv4 protocol.
816              Option groups: FD,SOCKET,IP4,CHILD,RANGE
817
818       UDP6-RECVFROM:<port>
819              Like UDP-RECVFROM, but only supports IPv6 protocol.
820              Option groups: FD,SOCKET,IP6,CHILD,RANGE
821
822       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
833       UDP4-RECV:<port>
834              Like UDP-RECV, but only supports IPv4 protocol.
835              Option groups: FD,SOCKET,IP4,RANGE
836
837       UDP6-RECV:<port>
838              Like UDP-RECV, but only supports IPv6 protocol.
839              Option groups: FD,SOCKET,IP6,RANGE
840
841       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
851       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
864       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
877       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
889       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
898       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
907       ABSTRACT-CONNECT:<string>
908
909       ABSTRACT-LISTEN:<string>
910
911       ABSTRACT-SENDTO:<string>
912
913       ABSTRACT-RECVFROM:<string>
914
915       ABSTRACT-RECV:<string>
916
917       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
926

ADDRESS OPTIONS

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
932       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
939       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
952       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
959       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
966       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
972       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
977
978       FD option group
979
980       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
989       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
996       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
1003       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
1008       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
1014       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
1020       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
1025       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
1030       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
1035       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
1040       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
1044       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
1052       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
1057       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
1065       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
1070       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
1081       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
1086       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
1092       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
1100       binary Opens  the file in binary mode to avoid implicit line terminator
1101              conversions (Cygwin).
1102
1103       text   Opens the file in text mode to force  implicit  line  terminator
1104              conversions (Cygwin).
1105
1106       noinherit
1107              Does not keep this file open in a spawned process (Cygwin).
1108
1109       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
1117       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
1131       shut-none
1132              Changes the (address dependent)  method  of  shutting  down  the
1133              write part of a connection to not do anything.
1134
1135       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
1140       shut-close
1141              Changes  the  (address  dependent)  method  of shutting down the
1142              write part of a connection to close(fd).
1143
1144       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
1151       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
1157       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
1162       ioctl-int=<request>:<value>
1163              Calls  ioctl() with the request value as second argument and the
1164              integer value as third argument.
1165
1166       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
1170       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
1175       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
1179
1180       NAMED option group
1181
1182       These options work on file system entries.
1183       See also options user, group, and mode.
1184
1185       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
1190       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
1195       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
1200       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
1206       unlink-early
1207              Unlinks  (removes)  the  file  before opening it and even before
1208              applying user-early etc.
1209
1210       unlink Unlinks (removes)  the  file  before  accessing  it,  but  after
1211              user-early etc.
1212
1213       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
1217       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
1224
1225       OPEN option group
1226
1227       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
1231       creat=<bool>
1232              Creates the file if it does not exist (example).
1233
1234       dsync=<bool>
1235              Blocks  write()  calls  until  metainfo is physically written to
1236              media.
1237
1238       excl=<bool>
1239              With option creat, if file exists this is an error.
1240
1241       largefile=<bool>
1242              On 32 bit systems, allows a file larger than 2^31 bytes.
1243
1244       noatime
1245              Sets the O_NOATIME options, so reads do not  change  the  access
1246              timestamp.
1247
1248       noctty=<bool>
1249              Does not make this file the controlling terminal.
1250
1251       nofollow=<bool>
1252              Does not follow symbolic links.
1253
1254       nshare=<bool>
1255              Does not allow sharing this file with other processes.
1256
1257       rshare=<bool>
1258              Does not allow other processes to open this file for writing.
1259
1260       rsync=<bool>
1261              Blocks write() until metainfo is physically written to media.
1262
1263       sync=<bool>
1264              Blocks write() until data is physically written to media.
1265
1266       rdonly=<bool>
1267              Opens the file for reading only.
1268
1269       wronly=<bool>
1270              Opens the file for writing only.
1271
1272       trunc  Truncates the file to size 0 during opening it.
1273
1274
1275       REG and BLK option group
1276
1277       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
1280       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
1286       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
1292       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
1298       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
1304       secrm=<bool>
1305
1306       unrm=<bool>
1307
1308       compr=<bool>
1309
1310       ext2-sync=<bool>
1311
1312       immutable=<bool>
1313
1314       ext2-append=<bool>
1315
1316       nodump=<bool>
1317
1318       ext2-noatime=<bool>
1319
1320       journal-data=<bool>
1321
1322       notail=<bool>
1323
1324       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
1331
1332       PROCESS option group
1333
1334       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
1339       chroot=<directory>
1340              Performs  a  chroot()  operation to <directory> after processing
1341              the address (example). This call might require root privilege.
1342
1343       chroot-early=<directory>
1344              Performs a chroot() operation to <directory> before opening  the
1345              address. This call might require root privilege.
1346
1347       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
1352       setgid-early=<group>
1353              Like setgit but is performed before opening the address.
1354
1355       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
1361       setuid-early=<user>
1362              Like setuid but is performed before opening the address.
1363
1364       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
1369       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
1375       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
1380       setsid Makes the process the leader of a new session (example).
1381
1382
1383       READLINE option group
1384
1385       These options apply to the readline address type.
1386
1387       history=<filename>
1388              Reads and writes history from/to <filename> (example).
1389
1390       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
1397       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
1406       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
1413
1414       APPLICATION option group
1415
1416       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
1420       cr     Converts  the default line termination character NL (’\n’, 0x0a)
1421              to/from CR (’\r’, 0x0d) when writing/reading on this channel.
1422
1423       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
1427       ignoreeof
1428              When EOF occurs on this channel, socat ignores it and  tries  to
1429              read more data (like "tail -f") (example).
1430
1431       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
1436       lockfile=<filename>
1437              If  lockfile  exists,  exits  with  error.  If lockfile does not
1438              exist, creates it and continues, unlinks lockfile on exit.
1439
1440       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
1445       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
1450
1451       SOCKET option group
1452
1453       These options are intended for all kinds of sockets, e.g.  IP  or  UNIX
1454       domain. Most are applied with a setsockopt() call.
1455
1456       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
1462       connect-timeout=<seconds>
1463              Abort the connection  attempt  after  <seconds>  [timeval]  with
1464              error status.
1465
1466       so-bindtodevice=<interface>
1467              Binds  the  socket  to the given <interface>.  This option might
1468              require root privilege.
1469
1470       broadcast
1471              For datagram sockets, allows sending to broadcast addresses  and
1472              receiving packets addressed to broadcast addresses.
1473
1474       debug  Enables socket debugging.
1475
1476       dontroute
1477              Only  communicates  with  directly connected peers, does not use
1478              routers.
1479
1480       keepalive
1481              Enables sending keepalives on the socket.
1482
1483       linger=<seconds>
1484              Blocks shutdown() or close() until data transfers have  finished
1485              or the given timeout [int] expired.
1486
1487       oobinline
1488              Places out-of-band data in the input data stream.
1489
1490       priority=<priority>
1491              Sets  the protocol defined <priority> [<int>] for outgoing pack‐
1492              ets.
1493
1494       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
1499       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
1504       rcvlowat=<bytes>
1505              Specifies the minimum number of received bytes [int]  until  the
1506              socket layer will pass the buffered data to socat.
1507
1508       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
1512       sndbuf=<bytes>
1513              Sets the size of the send buffer  after  the  socket()  call  to
1514              <bytes> [int].
1515
1516       sndbuf-late=<bytes>
1517              Sets the size of the send buffer when the socket is connected to
1518              <bytes> [int].
1519
1520       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
1524       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
1531       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
1538       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
1544       reuseport
1545              Set the SO_REUSEPORT socket option.
1546
1547       so-timestamp
1548              Sets the SO_TIMESTAMP socket option. This enables receiving  and
1549              logging of timestamp ancillary messages.
1550
1551       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
1563       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
1568       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
1573
1574       UNIX option group
1575
1576       These options apply to UNIX domain based addresses.
1577
1578       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
1584
1585       IP4 and IP6 option groups
1586
1587       These options can be used with IPv4 and IPv6 based sockets.
1588
1589       tos=<tos>
1590              Sets  the  TOS  (type  of  service) field of outgoing packets to
1591              <tos> [byte] (see RFC 791).
1592
1593       ttl=<ttl>
1594              Sets the TTL (time to live) field of outgoing packets  to  <ttl>
1595              [byte].
1596
1597       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
1607       mtudiscover=<0|1|2>
1608              Takes 0, 1, 2 to never, want, or always use path MTU discover on
1609              this socket.
1610
1611       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
1616       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
1621       ip-recvopts
1622              Sets the IP_RECVOPTS socket option. This enables  receiving  and
1623              logging of IP options ancillary messages (Linux, *BSD).
1624
1625       ip-recvtos
1626              Sets  the  IP_RECVTOS  socket option. This enables receiving and
1627              logging of TOS (type of service) ancillary messages (Linux).
1628
1629       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
1633       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
1638       ip-recvif
1639              Sets  the  IP_RECVIF  socket  option. This enables receiving and
1640              logging of interface ancillary messages (*BSD) (example).
1641
1642       ip-add-membership=<multicast-address:interface-address>
1643
1644       ip-add-membership=<multicast-address:interface-name>
1645
1646       ip-add-membership=<multicast-address:interface-index>
1647
1648       ip-add-membership=<multicast-address:interface-address:interface-name>
1649
1650       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
1660       ip-multicast-if=<hostname>
1661              Specifies hostname or address of the  network  interface  to  be
1662              used for multicast traffic.
1663
1664       ip-multicast-loop=<bool>
1665              Specifies  if outgoing multicast traffic should loop back to the
1666              interface.
1667
1668       ip-multicast-ttl=<byte>
1669              Sets the TTL used for outgoing multicast traffic. Default is 1.
1670
1671       res-debug
1672
1673       res-aaonly
1674
1675       res-usevc
1676
1677       res-primary
1678
1679       res-igntc
1680
1681       res-recurse
1682
1683       res-defnames
1684
1685       res-stayopen
1686
1687       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
1693       IP6 option group
1694
1695       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
1698       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
1703       ipv6-recvdstopts
1704              Sets the IPV6_RECVDSTOPTS socket option. This enables  receiving
1705              and  logging  of  ancillary  messages containing the destination
1706              options.
1707
1708       ipv6-recvhoplimit
1709              Sets the IPV6_RECVHOPLIMIT socket option. This enables receiving
1710              and logging of ancillary messages containing the hoplimit.
1711
1712       ipv6-recvhopopts
1713              Sets  the IPV6_RECVHOPOPTS socket option. This enables receiving
1714              and logging of ancillary messages containing the hop options.
1715
1716       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
1721       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
1725       ipv6-recvrthdr
1726              Sets  the  IPV6_RECVRTHDR  socket option. This enables receiving
1727              and logging of ancillary messages  containing  routing  informa‐
1728              tion.
1729
1730       ipv6-tclass
1731              Sets the IPV6_TCLASS socket option. This sets the transfer class
1732              of outgoing packets.
1733
1734       ipv6-recvtclass
1735              Sets the IPV6_RECVTCLASS socket option. This  enables  receiving
1736              and logging of ancillary messages containing the transfer class.
1737
1738
1739       TCP option group
1740
1741       These options may be applied to TCP sockets. They work by invoking set‐
1742       sockopt() with the appropriate parameters.
1743
1744       cork   Doesn’t send packets smaller than MSS (maximal segment size).
1745
1746       defer-accept
1747              While listening, accepts connections only  when  data  from  the
1748              peer arrived.
1749
1750       keepcnt=<count>
1751              Sets the number of keepalives before shutting down the socket to
1752              <count> [int].
1753
1754       keepidle=<seconds>
1755              Sets the idle time before sending the first keepalive  to  <sec‐
1756              onds> [int].
1757
1758       keepintvl=<seconds>
1759              Sets the interval between two keepalives to <seconds> [int].
1760
1761       linger2=<seconds>
1762              Sets  the  time  to keep the socket in FIN-WAIT-2 state to <sec‐
1763              onds> [int].
1764
1765       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
1770       mss-late=<bytes>
1771              Sets the MSS of the socket after connection has been established
1772              to <bytes> [int].
1773
1774       nodelay
1775              Turns  off the Nagle algorithm for measuring the RTT (round trip
1776              time).
1777
1778       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
1783       stdurg Enables RFC1122 compliant urgent pointer handling (AIX).
1784
1785       syncnt=<count>
1786              Sets the maximal number of SYN  retransmits  during  connect  to
1787              <count> [int].
1788
1789       md5sig Enables generation of MD5 digests on the packets (FreeBSD).
1790
1791       noopt  Disables use of TCP options (FreeBSD, MacOSX).
1792
1793       nopush sets the TCP_NOPUSH socket option (FreeBSD, MacOSX).
1794
1795       sack-disable
1796              Disables use the selective acknowledge feature (OpenBSD).
1797
1798       signature-enable
1799              Enables generation of MD5 digests on the packets (OpenBSD).
1800
1801       abort-threshold=<milliseconds>
1802              Sets  the  time  to  wait for an answer of the peer on an estab‐
1803              lished connection (HP-UX).
1804
1805       conn-abort-threshold=<milliseconds>
1806              Sets the time to wait for an answer of  the  server  during  the
1807              initial connect (HP-UX).
1808
1809       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
1814       paws   Enables  the  "protect against wrapped sequence numbers" feature
1815              (Tru64).
1816
1817       sackena
1818              Enables selective acknowledge (Tru64).
1819
1820       tsoptena
1821              Enables the time stamp option that allows RTT  recalculation  on
1822              existing connections (Tru64).
1823
1824
1825       SCTP option group
1826
1827       These options may be applied to SCTP stream sockets.
1828
1829       sctp-nodelay
1830              Sets  the  SCTP_NODELAY  socket  option  that disables the Nagle
1831              algorithm.
1832
1833       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
1837
1838       UDP, TCP, and SCTP option groups
1839
1840       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
1843       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
1849       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
1859
1860       SOCKS option group
1861
1862       When using SOCKS type addresses, some socks  specific  options  can  be
1863       set.
1864
1865       socksport=<tcp service>
1866              Overrides the default "socks" service or port 1080 for the socks
1867              server port with <TCP service>.
1868
1869       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
1874
1875       HTTP option group
1876
1877       Options that can be provided with HTTP type addresses.  The  only  HTTP
1878       address currently implemented is proxy-connect.
1879
1880       proxyport=<TCP service>
1881              Overrides the default HTTP proxy port 8080 with <TCP service>.
1882
1883       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
1890       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
1899       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
1906
1907       RANGE option group
1908
1909       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
1913       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
1921       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
1932       allow-table=<filename>
1933              Takes the specified file instead of /etc/hosts.allow.
1934
1935       deny-table=<filename>
1936              Takes the specified file instead of /etc/hosts.deny.
1937
1938       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
1942
1943       LISTEN option group
1944
1945       Options specific to listening sockets.
1946
1947       backlog=<count>
1948              Sets the backlog value passed with the listen() system  call  to
1949              <count> [int]. Default is 5.
1950
1951       max-children=<count>
1952              Limits  the number of concurrent child processes [int].  Default
1953              is no limit.
1954
1955
1956       CHILD option group
1957
1958       Options for addresses with multiple connections via child processes.
1959
1960       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
1971
1972       EXEC option group
1973
1974       Options for addresses that invoke a program.
1975
1976       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
1981       login  Prefixes  argv[0]  for the execvp() call with ’-’, thus making a
1982              shell behave as login shell.
1983
1984
1985       FORK option group
1986
1987       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
1995       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
2000       o      this option can only be applied to the second socat address.
2001
2002       o      it cannot be applied to a part of a dual address.
2003
2004       o      the first socat address cannot be OPENSSL or READLINE
2005
2006       o      socat options -b, -t, -D, -l, -v, -x become useless
2007
2008       o      for  both addresses, options ignoreeof, cr, and crnl become use‐
2009              less
2010
2011       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
2016       pipes  Creates  a  pair of unnamed pipes for interprocess communication
2017              instead of a socket pair.
2018
2019       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
2024       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
2028       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
2033       ctty   Makes the pty the controlling tty of the sub process (example).
2034
2035       stderr Directs  stderr of the sub process to its output channel by mak‐
2036              ing stderr a dup() of stdout (example).
2037
2038       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
2044       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
2049       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
2053
2054       TERMIOS option group
2055
2056       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
2064       b0     Disconnects the terminal.
2065
2066       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
2072       echo=<bool>
2073              Enables or disables local echo.
2074
2075       icanon=<bool>
2076              Sets  or clears canonical mode, enabling line buffering and some
2077              special characters.
2078
2079       raw    Sets raw mode, thus passing input and output almost unprocessed.
2080              This option is obsolete, use option rawer or cfmakeraw instead.
2081
2082       rawer  Makes  terminal  rawer  than  raw option. This option implicitly
2083              turns off echo. (example).
2084
2085       cfmakeraw
2086              Sets raw mode by invoking  cfmakeraw()  or  by  simulating  this
2087              call. This option implicitly turns off echo.
2088
2089       ignbrk=<bool>
2090              Ignores or interpretes the BREAK character (e.g., ^C)
2091
2092       brkint=<bool>
2093
2094       bs0
2095
2096       bs1
2097
2098       bsdly=<0|1>
2099
2100       clocal=<bool>
2101
2102
2103       cr0
2104       cr1
2105       cr2
2106       cr3
2107
2108              Sets  the  carriage return delay to 0, 1, 2, or 3, respectively.
2109              0 means no delay, the other values are terminal dependent.
2110
2111       crdly=<0|1|2|3>
2112
2113       cread=<bool>
2114
2115       crtscts=<bool>
2116
2117
2118       cs5
2119       cs6
2120       cs7
2121       cs8
2122
2123              Sets the character size to 5, 6, 7, or 8 bits, respectively.
2124
2125       csize=<0|1|2|3>
2126
2127       cstopb=<bool>
2128              Sets two stop bits, rather than one.
2129
2130       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
2135       echoctl=<bool>
2136              Echos control characters in hat notation (e.g. ^A)
2137
2138       echoe=<bool>
2139
2140       echok=<bool>
2141
2142       echoke=<bool>
2143
2144       echonl=<bool>
2145
2146       echoprt=<bool>
2147
2148       eof=<byte>
2149
2150       eol=<byte>
2151
2152       eol2=<byte>
2153
2154       erase=<byte>
2155
2156       discard=<byte>
2157
2158       ff0
2159
2160       ff1
2161
2162       ffdly=<bool>
2163
2164       flusho=<bool>
2165
2166       hupcl=<bool>
2167
2168       icrnl=<bool>
2169
2170       iexten=<bool>
2171
2172       igncr=<bool>
2173
2174       ignpar=<bool>
2175
2176       imaxbel=<bool>
2177
2178       inlcr=<bool>
2179
2180       inpck=<bool>
2181
2182       intr=<byte>
2183
2184       isig=<bool>
2185
2186       ispeed=<unsigned-int>
2187              Set the baud rate for incoming data on this line.
2188              See also: ospeed, b19200
2189
2190       istrip=<bool>
2191
2192       iuclc=<bool>
2193
2194       ixany=<bool>
2195
2196       ixoff=<bool>
2197
2198       ixon=<bool>
2199
2200       kill=<byte>
2201
2202       lnext=<byte>
2203
2204       min=<byte>
2205
2206       nl0    Sets the newline delay to 0.
2207
2208       nl1
2209
2210       nldly=<bool>
2211
2212       noflsh=<bool>
2213
2214       ocrnl=<bool>
2215
2216       ofdel=<bool>
2217
2218       ofill=<bool>
2219
2220       olcuc=<bool>
2221
2222       onlcr=<bool>
2223
2224       onlret=<bool>
2225
2226       onocr=<bool>
2227
2228       opost=<bool>
2229              Enables or disables output  processing;  e.g.,  converts  NL  to
2230              CR-NL.
2231
2232       ospeed=<unsigned-int>
2233              Set the baud rate for outgoing data on this line.
2234              See also: ispeed, b19200
2235
2236       parenb=<bool>
2237              Enable  parity  generation  on  output  and  parity checking for
2238              input.
2239
2240       parmrk=<bool>
2241
2242       parodd=<bool>
2243
2244       pendin=<bool>
2245
2246       quit=<byte>
2247
2248       reprint=<byte>
2249
2250       sane   Brings the terminal to something like a useful default state.
2251
2252       start=<byte>
2253
2254       stop=<byte>
2255
2256       susp=<byte>
2257
2258       swtc=<byte>
2259
2260       tab0
2261
2262       tab1
2263
2264       tab2
2265
2266       tab3
2267
2268       tabdly=<unsigned-int>
2269
2270       time=<byte>
2271
2272       tostop=<bool>
2273
2274       vt0
2275
2276       vt1
2277
2278       vtdly=<bool>
2279
2280       werase=<byte>
2281
2282       xcase=<bool>
2283
2284       xtabs
2285
2286       i-pop-all
2287              With UNIX System V STREAMS, removes all drivers from the stack.
2288
2289       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
2296
2297       PTY option group
2298
2299       These options are intended for use with the pty address type.
2300
2301       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
2311       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
2322       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
2328
2329       OPENSSL option group
2330
2331       These options apply to the openssl and openssl-listen address types.
2332
2333       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
2341       3DES   Uses a cipher suite with triple DES.
2342
2343       MD5    Uses a cipher suite with MD5.
2344
2345       aNULL  Uses a cipher suite without authentication.
2346
2347       NULL   Does not use encryption.
2348
2349       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
2353       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
2359       SSL2   Select SSL protocol version 2.
2360
2361       SSL3   Select SSL protocol version 3.
2362
2363       SSL23  Select the best available SSL or TLS protocol.
2364
2365       TLS1   Select TLS protocol version 1.
2366
2367       TLS1.1 Select TLS protocol version 1.1.
2368
2369       TLS1.2 Select  TLS  protocol version 1.2.  When this option is not pro‐
2370              vided OpenSSL negotiates the mothod with its peer.
2371
2372       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
2377       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
2384       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
2390       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
2395       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
2401       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
2406       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
2411       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
2420       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
2429       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
2437       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
2444
2445       RETRY option group
2446
2447       Options that control retry of some system calls, especially  connection
2448       attempts.
2449
2450       retry=<num>
2451              Number  of  retries  before  the connection or listen attempt is
2452              aborted.  Default is 0, which means just one attempt.
2453
2454       interval=<timespec>
2455              Time between consecutive attempts (seconds, [timespec]). Default
2456              is 1 second.
2457
2458       forever
2459              Performs an unlimited number of retry attempts.
2460
2461
2462       TUN option group
2463
2464       Options that control Linux TUN/TAP interface device addresses.
2465
2466       tun-device=<device-file>
2467              Instructs  socat  to take another path for the TUN clone device.
2468              Default is /dev/net/tun.
2469
2470       tun-name=<if-name>
2471              Gives the resulting network interface a specific name instead of
2472              the system generated (tun0, tun1, etc.)
2473
2474       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
2480       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
2486       iff-up Sets the TUN network interface status UP. Strongly recommended.
2487
2488       iff-broadcast
2489              Sets the BROADCAST flag of the TUN network interface.
2490
2491       iff-debug
2492              Sets the DEBUG flag of the TUN network interface.
2493
2494       iff-loopback
2495              Sets the LOOPBACK flag of the TUN network interface.
2496
2497       iff-pointopoint
2498              Sets the POINTOPOINT flag of the TUN device.
2499
2500       iff-notrailers
2501              Sets the NOTRAILERS flag of the TUN device.
2502
2503       iff-running
2504              Sets the RUNNING flag of the TUN device.
2505
2506       iff-noarp
2507              Sets the NOARP flag of the TUN device.
2508
2509       iff-promisc
2510              Sets the PROMISC flag of the TUN device.
2511
2512       iff-allmulti
2513              Sets the ALLMULTI flag of the TUN device.
2514
2515       iff-master
2516              Sets the MASTER flag of the TUN device.
2517
2518       iff-slave
2519              Sets the SLAVE flag of the TUN device.
2520
2521       iff-multicast
2522              Sets the MULTICAST flag of the TUN device.
2523
2524       iff-portsel
2525              Sets the PORTSEL flag of the TUN device.
2526
2527       iff-automedia
2528              Sets the AUTOMEDIA flag of the TUN device.
2529
2530       iff-dynamic
2531              Sets the DYNAMIC flag of the TUN device.
2532
2533

DATA VALUES

2535       This  section explains the different data types that address parameters
2536       and address options can take.
2537
2538       address-range
2539              Is  currently  only  implemented  for   IPv4   and   IPv6.   See
2540              address-option `range’
2541
2542       bool   "0" or "1"; if value is omitted, "1" is taken.
2543
2544       byte   An  unsigned int number, read with strtoul() , lower or equal to
2545              UCHAR_MAX .
2546
2547       command-line
2548              A string specifying a program name and its arguments,  separated
2549              by single spaces.
2550
2551       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
2555       directory
2556              A string with usual UN*X directory name semantics.
2557
2558       facility
2559              The name of a syslog facility in lower case characters.
2560
2561       fdnum  An  unsigned  int  type, read with strtoul() , specifying a UN*X
2562              file descriptor.
2563
2564       filename
2565              A string with usual UN*X filename semantics.
2566
2567       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
2571       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
2576       interface
2577              A  string  specifying  the device name of a network interface as
2578              shown by ifconfig or procan, e.g. "eth0".
2579
2580       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
2586       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
2591       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
2597       long   A number read with strtol() . The value must fit into a C long.
2598
2599       long long
2600              A  number read with strtoll() . The value must fit into a C long
2601              long.
2602
2603       off_t  An implementation dependend signed number, usually 32 bits, read
2604              with strtol or strtoll.
2605
2606       off64_t
2607              An implementation dependend signed number, usually 64 bits, read
2608              with strtol or strtoll.
2609
2610       mode_t An unsigned integer, read with strtoul() , specifying mode (per‐
2611              mission) bits.
2612
2613       pid_t  A number, read with strtol() , specifying a process id.
2614
2615       port   A  uint16_t  (16  bit  unsigned  number) specifying a TCP or UDP
2616              port, read with strtoul() .
2617
2618       protocol
2619              An unsigned 8 bit number, read with strtoul() .
2620
2621       size_t An unsigned number with size_t limitations, read with strtoul .
2622
2623       sockname
2624              A socket address. See address-option `bind’
2625
2626       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
2631       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
2636       timeval
2637              A  double  float specifying seconds; the number is mapped into a
2638              struct timeval, consisting of seconds and microseconds.
2639
2640       timespec
2641              A double float specifying seconds; the number is mapped  into  a
2642              struct timespec, consisting of seconds and nanoseconds.
2643
2644       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
2649       unsigned int
2650              A  number  read  with  strtoul()  .  The value must fit into a C
2651              unsigned int.
2652
2653       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
2657

EXAMPLES

2659       socat - TCP4:www.domain.org:80
2660
2661
2662              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
2668       socat -d -d READLINE,history=$HOME/.http_history \
2669       TCP4:www.domain.org:www,crnl
2670
2671              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
2678       socat TCP4-LISTEN:www TCP4:www.domain.org:www
2679
2680
2681              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
2686       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
2690              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
2701       socat TCP4-LISTEN:5555,fork,tcpwrap=script \
2702       EXEC:/bin/myscript,chroot=/home/sandbox,su-d=sandbox,pty,stderr
2703
2704              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
2716       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
2719              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
2729       socat -,escape=0x0f /dev/ttyS0,rawer,crnl
2730
2731
2732              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
2739       socat UNIX-LISTEN:/tmp/.X11-unix/X1,fork \
2740       SOCKS4:host.victim.org:127.0.0.1:6000,socksuser=nobody,sourceport=20
2741
2742              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
2756       socat -u /tmp/readdata,seek-end=0,ignoreeof -
2757
2758
2759              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
2767       (sleep 5; echo PASSWORD; sleep 5; echo ls; sleep 1) |
2768       socat - EXEC:'ssh -l user server',pty,setsid,ctty
2769
2770              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
2775       socat -u TCP4-LISTEN:3334,reuseaddr,fork \
2776       OPEN:/tmp/in.log,creat,append
2777
2778              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
2785       socat READLINE,noecho=’[Pp]assword:’ EXEC:’ftp ftp.server.com’,pty,set‐
2786       sid,ctty
2787
2788
2789              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
2796       socat PTY,link=$HOME/dev/vmodem0,rawer,wait-slave \
2797       EXEC:"ssh modemserver.us.org socat - /dev/ttyS0,nonblock,rawer"
2798
2799              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
2806       socat TCP4-LISTEN:2022,reuseaddr,fork \
2807       PROXY:proxy:www.domain.org:22,proxyport=3128,proxyauth=user:pass
2808
2809              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
2816       socat - SSL:server:4443,cafile=server.crt,cert=client.pem
2817
2818
2819              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
2830       socat                                        OPENSSL-LISTEN:4443,reuse‐
2831       addr,pf=ip4,fork,cert=server.pem,cafile=client.crt PIPE
2832
2833
2834              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
2842       echo |socat -u - file:/tmp/bigfile,create,largefile,seek=100000000000
2843
2844
2845              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
2852       socat tcp-l:7777,reuseaddr,fork system:’filan -i 0 -s >&2’,nofork
2853
2854
2855              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
2861       echo        -e        "\0\14\0\0\c"         |socat         -u         -
2862       file:/usr/bin/squid.exe,seek=0x00074420
2863
2864
2865              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
2870       socat - tcp:www.blackhat.org:31337,readbytes=1000
2871
2872
2873              connects to an unknown service and prevents being flooded.
2874
2875       socat -U TCP:target:9999,end-close TCP-L:8888,reuseaddr,fork
2876
2877
2878              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
2885       socat           -           UDP4-DATAGRAM:192.168.1.0:123,sp=123,broad‐
2886       cast,range=192.168.1.0/24
2887
2888
2889              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
2893       socat                          -                           SOCKET-DATA‐
2894       GRAM:2:2:17:x007bxc0a80100x0000000000000000,bind=x007bx00000000x0000000000000000,set‐
2895       sock‐
2896       opt-int=1:6:1,range=x0000xc0a80100x0000000000000000:x0000xffffff00x0000000000000000
2897
2898
2899              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
2903       socat - IP4-DATAGRAM:255.255.255.255:44,broadcast,range=10.0.0.0/8
2904
2905
2906              sends a broadcast to the local  network(s)  using  protocol  44.
2907              Accepts replies from the private address range only.
2908
2909       socat     -    UDP4-DATAGRAM:224.255.0.1:6666,bind=:6666,ip-add-member‐
2910       ship=224.255.0.1:eth0
2911
2912
2913              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
2923       socat TCP:host2:4443 TUN:192.168.255.1/24,up
2924
2925
2926              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
2933       socat PTY,link=/var/run/ppp,rawer INTERFACE:hdlc0
2934
2935
2936              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
2943       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
2949
2950              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
2956       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
2960
2961              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
2968
2969
2970

DIAGNOSTICS

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
2979       FATAL: Conditions that require unconditional and immediate program ter‐
2980              mination.
2981
2982       ERROR: Conditions  that  prevent proper program processing. Usually the
2983              program is terminated (see option -s).
2984
2985       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
2990       NOTICE:
2991              Interesting actions of the program, e.g. for  supervising  socat
2992              in some kind of server mode.
2993
2994       INFO:  Description  of what the program does, and maybe why it happens.
2995              Allows monitoring the lifecycles of file descriptors.
2996
2997       DEBUG: Description of how the program  works,  all  system  or  library
2998              calls and their results.
2999
3000
3001       Log messages can be written to stderr, to a file, or to syslog.
3002
3003       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

FILES

3008       /usr/bin/socat
3009       /usr/bin/filan
3010       /usr/bin/procan
3011

ENVIRONMENT VARIABLES

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
3016       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
3020       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
3025       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
3033       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
3037       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
3042       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
3047       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
3051       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
3056       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
3061       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
3066       SOCAT_SOCKPORT (output)
3067              With  TCP-LISTEN,  UDP-LISTEN,  and  SCTP-LISTEN addresses, this
3068              variable is set to the local port.
3069
3070       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
3074       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
3079       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
3086       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
3092       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
3097       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
3102       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
3107       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
3112       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
3117       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
3122       SOCAT_OPENSSL_X509_ISSUER (output)
3123              Issuer field from peer certificate
3124
3125       SOCAT_OPENSSL_X509_SUBJECT (output)
3126              Subject field from peer certificate
3127
3128       SOCAT_OPENSSL_X509_COMMONNAME (output)
3129              commonName entries from peer certificates subject. Multiple val‐
3130              ues are separated by " // ".
3131
3132       SOCAT_OPENSSL_X509_* (output)
3133              all other entries from peer certificates subject
3134
3135       SOCAT_OPENSSL_X509V3_DNS (output)
3136              DNS  entries  from peer certificates extensions - subjectAltName
3137              field. Multiple values are separated by " // ".
3138
3139       HOSTNAME (input)
3140              Is used to determine the hostname for logging (see -lh).
3141
3142       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
3147       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
3152       SHELL (output)
3153              With options su and su-d, SHELL is set to the login shell of the
3154              given user.
3155
3156       PATH (output)
3157              Can be set with option path for exec and system addresses.
3158
3159       HOME (output)
3160              With  options  su and su-d, HOME is set to the home directory of
3161              the given user.
3162

CREDITS

3164       The work of the following groups and organizations was  invaluable  for
3165       this project:
3166
3167       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
3170       The Linux developers community (http://www.linux.org/) for providing  a
3171       free, open source operating system.
3172
3173       The Open Group (http://www.unix-systems.org/) for making their standard
3174       specifications available on the Internet for free.
3175

VERSION

3177       This man page describes version 1.7.3 of socat.
3178

BUGS

3180       Addresses cannot be nested, so a single  socat  process  cannot,  e.g.,
3181       drive ssl over socks.
3182
3183       Address option ftruncate without value uses default 1 instead of 0.
3184
3185       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
3189       The  data transfer blocksize setting (-b) is ignored with address read‐
3190       line.
3191
3192       Send bug reports to <socat@dest-unreach.org>
3193

SEE ALSO

3195       nc(1), rinetd(8), openssl(1), stunnel(8), rlwrap(1), setsid(1)
3196
3197       Socat home page http://www.dest-unreach.org/socat/
3198

AUTHOR

3200       Gerhard Rieger <rieger@dest-unreach.org> and contributors
3201
3202
3203
3204                                                                      socat(1)
Impressum