WebSVN – nexmon – Blame – Rev 1 – /utilities/socat/README

1

office

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.

packages

--------

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

distributions.

platforms

---------

socat 1.7.0 was compiled and more or less successfully tested under the

49

following operating systems:

50

51

Debian lenny/sid on x86, kernel 2.6.24

FreeBSD 6.1 on x86

NetBSD 4.0 on x86

OpenBSD 4.3 on x86

OpenSolaris 10 on x86 with gcc

56

Mac OS X 10.5.5 on iMac G5, with libreadline

57

HP-UX 11.23

58

AIX 5.3 on 64bit Power4 with gcc

59

Cygwin 1.5.25 on i686

60

61

tests on Tru64 can no longer be performed because HP testdrive has taken down

62

these hosts.

63

64

Some versions of socat have been reported to successfully compile under older

65

Linux versions back to RedHat 2.1 (kernel 1.2.13, gcc 2.7.0), under AIX 4.1 and

66

4.3, SunOS 5.7-5.8, FreeBSD 4.2 - 4.9, MacOS X 10.1, Cygwin, Solaris 8 on x86,

67

OSR 5.0.6, NetBSD 1.6.1 and 2.0.2, OpenBSD 3.4 and 3.8, Tru64 5.1B, Mac OS X

68

10.1-10.2, and HP-UX 11

69

70

It might well compile and run under other UNIX like operating systems.

install

-------

Get the tarball and extract it:

77

gtar xzf socat.tar.gz

cd socat-2.0.0-b8

./configure

make

su

make install # installs socat, filan, and procan in /usr/local/bin

83

84

For compiling socat, gcc (or egc) is recommended.

85

If gcc is not available, the configure script will fail to determine

86

some features; then you'd better begin with one of the Makefiles and config.h's

87

from the Config directory.

88

89

If you have problems with the OpenSSL library, you can apply the option

90

"--disable-openssl" to configure.

91

92

If you have problems with the readline library or (n)curses, you can apply the

93

option "--disable-readline" to configure.

94

95

If you have problems with the tcp wrappers library, you can apply the option

96

"--disable-libwrap" to configure.

97

98

If you still get errors or a tremendous amount of warnings you can exclude

99

the features for system call tracing and file descriptor analyzing by

100

applying the options "--disable-sycls --disable-filan" to configure.

101

102

You still need the functions vsnprintf and snprintf that are in the GNU libc,

103

but might not be available with some proprietary libc's.

104

105

The configure script looks for headers and libraries of openssl, readline, and

106

tcp wrappers in the OS'es standard places and in the subdirectories include/

107

and lib/ of the following places:

/sw/

/usr/local/

/opt/freeware/

/usr/sfw/

and for openssl also in:

113

/usr/local/ssl/

114

In case of unexpected behaviour it is important to understand that configure

115

first searches for the appropriate include file and then expects to find the

116

library in the associated lib directory. That means, when e.g. a OpenSSL

117

installation resides under /usr/local and there is a symbolic link from

118

/usr/include/ssl/ssl.h to /usr/local/ssl/include/ssl/ssl.h, configure will find

119

the /usr/include/... header and will therefore expect libssl in /usr/lib

120

instead of /usr/local/...

121

122

If configure does not find a header file or library but you know where it is,

123

you can specify additional search locations, e.g.:

124

export LIBS="-L$HOME/lib"

125

export CPPFLAGS="-I$HOME/include"

126

before running configure and make.

127

128

For other operating systems, if socat does not compile without errors, refer to

the file PORTING.

platform specifics - redhat

133

---------------------------

134

135

Install the following packages before building socat:

tcp_wrappers-devel

readline-devel

openssl-devel

On RedHat Linux 9.0, including openssl/ssl.h might fail due to problems with

141

the krb5-devel package. configure reacts with disabling openssl integration.

142

To solve this issue, help cpp to find the krb5.h include file:

143

CPPFLAGS="-I/usr/kerberos/include" ./configure

144

145

146

platform specifics - aix

147

------------------------

148

149

The flock() prototype is not available but the function is. Thus, to enable the

150

socat flock options, run configure and then change in config.h the line

151

/* #undef HAVE_FLOCK */

152

to

153

#define HAVE_FLOCK 1

154

and continue the build process.

155

156

When using the OpenSSL rpm provided by IBM, configure might need the

157

environment variable setting:

158

LIBS="-L/opt/freeware/lib"

159

160

When using the OpenSSL bundle provided by IBM, egd needs to be installed too

161

to get enough entropy.

162

163

socat compiles not only with gcc, but also with xlc. Just adapt the Makefile:

164

replace gcc by /usr/vac/bin/xlc and remove gcc specific options

165

"-Wall -Wno-parentheses".

166

167

When linking with the OpenSSL library provided by IBM, errors may occur:

168

ld: 0711-317 ERROR: Undefined symbol: .__umoddi3

169

In this case, you need to link with libgcc or compile libcrypt yourself using

170

xlc, or disable SSL (in config.h, undefine WITH_OPENSSL and recompile)

171

172

The score of test.sh can be improved by uncommenting MISCDELAY=1 in this

script.

platform specifics - solaris

177

----------------------------

178

179

If libreadline or libssl are in a directory not searched by the loader per

180

default, e.g. /opt/sfw/lib, you must add this directory to $LD_LIBRARY_PATH,

181

for running both configure and the socat executables, e.g.:

182

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/sfw/lib

183

184

For some shell scripts, it is preferable to have /usr/xpg4/bin at a prominent

185

position in $PATH.

186

187

With the default compiler define _GNU_SOURCE, the CMSG_* macros are not

188

available, and therefore ancillary messages cannot be used. To enable these try

189

the following:

190

After running ./configure, edit Makefile and replace "-D_GNU_SOURCE" with

191

"-D_XPG4_2 -D__EXTENSIONS__" and run make

192

193

194

platform specifics - hp-ux

195

--------------------------

196

197

Ancillary messages cannot be compiled in with socat: both struct msghdr and

198

struct cmsghdr are required. Compiling with -D_XOPEN_SOURCE_EXTENDED provides

199

struct msghdr but disables struct cmsghdr while -D_OPEN_SOURCE disables struct

200

msghdr but disables struct cmsghdr. Please contact socat development if you

201

know a solution.

202

203

Shutting down the write channel of a UNIX domain socket does not seem to

204

trigger an EOF on the peer socket. This makes problems with the exec and

205

system addresses.

206

207

This OS provides the type "long long", but not the strtoll() function to read

208

data into a long long variable.

209

210

UNIX domain sockets are only supported with SOCK_STREAM, not with datagrams

211

(see man 7 unix).

212

213

With UDP sockets it seems to happen that the select() call reports available

214

data (or EOF) but a subsequent read() call hangs.

215

216

217

platform specifics - tru64

218

--------------------------

219

220

When the use of the readline address fails with an error like:

221

socat: /sbin/loader: Fatal Error: Reference to unresolvable symbol "tgetent" in ".../libreadline.so.4"

222

and you still want to use shared libraries, try the following workaround:

223

$ make distclean; LIBS="-static" ./configure

224

remove the "-static" occurrence in Makefile

$ make

documentation

-------------

These files reside in the doc subdirectory:

232

233

socat.1 is the man page, socat.html is the HTML based man page. It is actual,

234

but describes only the more useful options.

235

236

xio.help is an older, but more exact description in text form; with socat

237

version 1.6.0 it is outdated.

238

239

doc/socat-openssltunnel.html is a simple tutorial for a private SSL connection.

240

doc/socat-multicast.html is a short tutorial for multicast and broadcast

241

communications.

242

doc/socat-tun shows how to build a virtual network between two hosts.

243

244

socat.1 and socat.html can be generated from socat.yo (which is released with

245

socat 1.6.0.1 and later) using the yodl document language package. Maintenance

246

of yodl had been discontinued by its author

247

(http://www.xs4all.nl/~jantien/yodl/) (there seems to be a revival at

248

http://yodl.sourceforge.net/ though). For socat, the old version 1.31 is used;

249

an rpm is still distributed with recent OpenSuSE versions (confirmed for

250

OpenSuSE 10.1 in suse/i586/yodl-1.31.18-1142.i586.rpm). It appears to install

251

smoothly also under RedHat Linux. After yodl 1.31 installation, the following

252

correction must be performed in /usr/share/yodl/shared.yo in two places:

253

< whenhtml(htmlcommand(<!)ARG1+htmlcommand(>)))

254

> whenhtml(htmlcommand()))

license

-------

socat is distributed under the terms of the GNU GPLv2;

261

except for install-sh, which is copyright MIT, with its own license;

262

263

In addition, as a special exception, the copyright holder

264

gives permission to link the code of this program with

265

any version of the OpenSSL library which is distributed

266

under a license identical to that listed in the included

267

COPYING.OpenSSL file, and distribute linked combinations

268

including the two. You must obey the GNU General Public

269

License in all respects for all of the code used other

270

than OpenSSL. If you modify this file, you may extend this

271

exception to your version of the file, but you are not

272

obligated to do so. If you do not wish to do so, delete

273

this exception statement from your version.

274

275

276

This program is free software; you can redistribute it and/or modify

277

it under the terms of the GNU General Public License as published by

278

the Free Software Foundation, version 2 of the License

279

280

This program is distributed in the hope that it will be useful,

281

but WITHOUT ANY WARRANTY; without even the implied warranty of

282

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

283

GNU General Public License for more details.

284

285

You should have received a copy of the GNU General Public License

286

along with this program; if not, write to the Free Software

287

Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

contact

-------

For questions, bug reports, ideas, contributions etc. please contact

294

socat@dest-unreach.org

295

296

For socat source distribution, bug fixes, and latest news see

297

http://www.dest-unreach.org/socat/

298

299

www.socat.org is an alternate site providing the same contents.

300

301

public git repository:

302

git://repo.or.cz/socat.git

303

http://repo.or.cz/r/socat.git

nexmon – Blame information for rev 1