README

   1
   2 about
   3 -----
   4
   5 socat is a relay for bidirectional data transfer between two independent data
   6 channels. Each of these data channels may be a file, pipe, device (serial line
   7 etc. or a pseudo terminal), a socket (UNIX, IP4, IP6 - raw, UDP, TCP), an
   8 SSL socket, proxy CONNECT connection, a file descriptor (stdin etc.), the GNU
   9 line editor (readline), a program, or a combination of two of these.
  10 These modes include generation of "listening" sockets, named pipes, and pseudo
  11 terminals.
  12
  13 socat can be used, e.g., as TCP port forwarder (one-shot or daemon), as an
  14 external socksifier, for attacking weak firewalls, as a shell interface to UNIX
  15 sockets, IP6 relay, for redirecting TCP oriented programs to a serial line, to
  16 logically connect serial lines on different computers, or to establish a
  17 relatively secure environment (su and  chroot) for running client or server
  18 shell scripts with network connections.
  19
  20 Many options are available to refine socats behaviour:
  21 terminal parameters, open() options, file permissions, file and process owners,
  22 basic socket options like bind address, advanced socket options like IP source
  23 routing, linger, TTL, TOS (type of service), or TCP performance tuning.
  24
  25 More capabilities, like daemon mode with forking, client address check,
  26 "tail -f" mode, some stream data processing (line terminator conversion),
  27 choosing sockets, pipes, or ptys for interprocess communication, debug and
  28 trace options, logging to syslog, stderr or file, and last but not least
  29 precise error messages make it a versatile tool for many different purposes.
  30
  31 In fact, many of these features already exist in specialized tools; but until
  32 now, there does not seem to exists another tool that provides such a generic,
  33 flexible, simple and almost comprehensive (UNIX) byte stream connector.
  34
  35
  36 packages
  37 --------
  38
  39 before bothering with compilers, dependencies and include files, you might
  40 try to get a binary distribution that matches your platform. Have a look at
  41 the projects home page for actual information regarding socat binary
  42 distributions.
  43
  44
  45 platforms
  46 ---------
  47
  48 socat 1.8.0 was compiled and more or less successfully tested under the
  49 following operating systems:
  50
  51 Debian 4 on x86_64
  52 FreeBSD 10 on amd64
  53 OpenBSD 7.2 on amd64
  54 OpenIndiana 2021-04 on i386 with gcc
  55 Ubuntu 10.04 on i386
  56 Ubuntu 12..22
  57 Rocky 9
  58 Cygwin 10.0
  59
  60
  61 install
  62 -------
  63
  64 Get the tarball and extract it:
  65         tar xzf socat.tar.gz
  66         cd socat-1.8.0.0
  67         ./configure
  68         make
  69         su
  70         make install    # installs socat, filan, and procan in /usr/local/bin
  71
  72 For compiling socat, gcc (or clang) is recommended.
  73 If gcc (or a compiler with similar front end) is not available, the configure
  74 script might fail to determine some features
  75
  76 If you have problems with the OpenSSL library, you can apply the option
  77 "--disable-openssl" to configure.
  78
  79 If you have problems with the readline library or (n)curses, you can apply the
  80 option "--disable-readline" to configure.
  81
  82 If you have problems with the tcp wrappers library, you can apply the option
  83 "--disable-libwrap" to configure.
  84
  85 If you still get errors or a tremendous amount of warnings you can exclude
  86 the features for system call tracing and file descriptor analyzing by
  87 applying the options "--disable-sycls --disable-filan" to configure.
  88
  89 You still need the functions vsnprintf and snprintf that are in the GNU libc,
  90 but might not be available with some proprietary libc's.
  91
  92 The configure script looks for headers and libraries of openssl, readline, and
  93 tcp wrappers in the OS'es standard places and in the subdirectories include/
  94 and lib/ of the following places:
  95    /sw/
  96    /usr/local/
  97    /opt/freeware/
  98    /usr/sfw/
  99 and for openssl also in:
 100    /usr/local/ssl/
 101 In case of unexpected behaviour it is important to understand that configure
 102 first searches for the appropriate include file and then expects to find the
 103 library in the associated lib directory. That means, when e.g. a OpenSSL
 104 installation resides under /usr/local and there is a symbolic link from
 105 /usr/include/ssl/ssl.h to /usr/local/ssl/include/ssl/ssl.h, configure will find
 106 the /usr/include/... header and will therefore expect libssl in /usr/lib
 107 instead of /usr/local/...
 108
 109 If configure does not find a header file or library but you know where it is,
 110 you can specify additional search locations, e.g.:
 111    export LIBS="-L$HOME/lib"
 112    export CPPFLAGS="-I$HOME/include"
 113 before running configure and make.
 114
 115 For other operating systems, if socat does not compile without errors, refer to
 116 the file PORTING.
 117
 118
 119 platform specifics - Debian (Ubuntu, ...)
 120 -----------------------------------------
 121
 122 libssl-dev
 123
 124
 125 platform specifics - redhat
 126 ---------------------------
 127
 128 Install the following packages before building socat:
 129   tcp_wrappers-devel
 130   readline-devel
 131   openssl-devel
 132
 133 On RedHat Linux 9.0, including openssl/ssl.h might fail due to problems with
 134 the krb5-devel package. configure reacts with disabling openssl integration.
 135 To solve this issue, help cpp to find the krb5.h include file:
 136 CPPFLAGS="-I/usr/kerberos/include" ./configure
 137
 138
 139 platform specifics - aix
 140 ------------------------
 141
 142 The flock() prototype is not available but the function is. Thus, to enable the
 143 socat flock options, run configure and then change in config.h the line
 144 /* #undef HAVE_FLOCK */
 145 to
 146 #define HAVE_FLOCK 1
 147 and continue the build process.
 148
 149 When using the OpenSSL rpm provided by IBM, configure might need the
 150 environment variable setting:
 151 LIBS="-L/opt/freeware/lib"
 152
 153 When using the OpenSSL bundle provided by IBM, egd needs to be installed too
 154 to get enough entropy.
 155
 156 socat compiles not only with gcc, but also with xlc. Just adapt the Makefile:
 157 replace gcc by /usr/vac/bin/xlc and remove gcc specific options
 158 "-Wall -Wno-parentheses".
 159
 160 When linking with the OpenSSL library provided by IBM, errors may occur:
 161 ld: 0711-317 ERROR: Undefined symbol: .__umoddi3
 162 In this case, you need to link with libgcc or compile libcrypt yourself using
 163 xlc, or disable SSL (in config.h, undefine WITH_OPENSSL and recompile)
 164
 165 The score of test.sh can be improved by uncommenting MISCDELAY=1 in this
 166 script.
 167
 168
 169 platform specifics - solaris
 170 ----------------------------
 171
 172 If libreadline or libssl are in a directory not searched by the loader per
 173 default, e.g. /opt/sfw/lib, you must add this directory to $LD_LIBRARY_PATH,
 174 for running both configure and the socat executables, e.g.:
 175 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/sfw/lib
 176
 177 For some shell scripts, it is preferable to have /usr/xpg4/bin at a prominent
 178 position in $PATH.
 179
 180 With the default compiler define _GNU_SOURCE, the CMSG_* macros are not
 181 available, and therefore ancillary messages cannot be used. To enable these try
 182 the following:
 183 After running ./configure, edit Makefile and replace "-D_GNU_SOURCE" with
 184 "-D_XPG4_2 -D__EXTENSIONS__" and run make
 185
 186
 187 platform specifics - hp-ux
 188 --------------------------
 189
 190 Ancillary messages cannot be compiled in with socat: both struct msghdr and
 191 struct cmsghdr are required. Compiling with -D_XOPEN_SOURCE_EXTENDED provides
 192 struct msghdr but disables struct cmsghdr while -D_OPEN_SOURCE disables struct
 193 msghdr but disables struct cmsghdr. Please contact socat development if you
 194 know a solution.
 195
 196 Shutting down the write channel of a UNIX domain socket does not seem to
 197 trigger an EOF on the peer socket. This makes problems with the exec and
 198 system addresses.
 199
 200 This OS provides the type "long long", but not the strtoll() function to read
 201 data into a long long variable.
 202
 203 UNIX domain sockets are only supported with SOCK_STREAM, not with datagrams
 204 (see man 7 unix).
 205
 206 With UDP sockets it seems to happen that the select() call reports available
 207 data (or EOF) but a subsequent read() call hangs.
 208
 209
 210 platform specifics - tru64
 211 --------------------------
 212
 213 When the use of the readline address fails with an error like:
 214 socat: /sbin/loader: Fatal Error: Reference to unresolvable symbol "tgetent" in ".../libreadline.so.4"
 215 and you still want to use shared libraries, try the following workaround:
 216 $ make distclean; LIBS="-static" ./configure
 217 remove the "-static" occurrence in Makefile
 218 $ make
 219
 220
 221 documentation
 222 -------------
 223
 224 These files reside in the doc subdirectory:
 225
 226 socat.1 is the man page, socat.html is the HTML based man page. It is actual,
 227 but describes only the more useful options.
 228
 229 doc/socat-openssltunnel.html is a simple tutorial for a private SSL connection.
 230 doc/socat-multicast.html is a short tutorial for multicast and broadcast
 231 communications.
 232 doc/socat-tun shows how to build a virtual network between two hosts.
 233
 234 socat.1 and socat.html can be generated from socat.yo (which is released with
 235 socat 1.6.0.1 and later) using the yodl document language package. Maintenance
 236 of yodl had been discontinued by its author
 237 (http://www.xs4all.nl/~jantien/yodl/) (there seems to be a revival at
 238 http://yodl.sourceforge.net/ though). For socat, the revival version 3.03 is used,
 239
 240
 241 license
 242 -------
 243
 244 socat is distributed under the terms of the GNU GPLv2;
 245 except for install-sh, which is copyright MIT, with its own license;
 246
 247 In addition, as a special exception, the copyright holder
 248 gives permission to link the code of this program with
 249 any version of the OpenSSL library which is distributed
 250 under a license identical to that listed in the included
 251 COPYING.OpenSSL file, and distribute linked combinations
 252 including the two. You must obey the GNU General Public
 253 License in all respects for all of the code used other
 254 than OpenSSL. If you modify this file, you may extend this
 255 exception to your version of the file, but you are not
 256 obligated to do so. If you do not wish to do so, delete
 257 this exception statement from your version.
 258
 259
 260     This program is free software; you can redistribute it and/or modify
 261     it under the terms of the GNU General Public License as published by
 262     the Free Software Foundation, version 2 of the License
 263
 264     This program is distributed in the hope that it will be useful,
 265     but WITHOUT ANY WARRANTY; without even the implied warranty of
 266     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 267     GNU General Public License for more details.
 268
 269     You should have received a copy of the GNU General Public License
 270     along with this program; if not, write to the Free Software
 271     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 272
 273
 274 contact
 275 -------
 276
 277 For questions, bug reports, ideas, contributions etc. please contact
 278 socat@dest-unreach.org
 279
 280 For socat source distribution, bug fixes, and latest news see
 281         http://www.dest-unreach.org/socat/
 282
 283 www.socat.org is an alternate site providing the same contents.
 284
 285 public git repository:
 286         git://repo.or.cz/socat.git
 287         http://repo.or.cz/socat.git