It works for both servers (`listen(3)`) and clients (`connect(3)`).
-These UNIX sockets can also be forwared over SSH with `socat`.
+These UNIX sockets can also be forwarded over SSH with `socat` (see below).
DEPENDENCIES
rm -f /destination/path/for/library/libsocket2unix.so
cp -L src/.libs/libsocket2unix.so /destination/path/for/library/
-*Important:* Don't overwrite an existing `libsocket2unix.so` file which is use
-by any program. Instead remove the file first and then copy the new version.
-This is not a bug in socket2unix, but a general problem.
+*Important:* Don't overwrite an existing `libsocket2unix.so` file which is in
+use by any program or the program may crash. Instead remove the file first and
+then copy the new version. This is not a bug in socket2unix, but a general
+problem.
USAGE
- 'SOCKET2UNIX_DEBUG':
Control debug level. 1 = errors only, 2 = warnings only, 3 = debug messages.
Default: 2
+- 'SOCKET2UNIX_OPTIONS':
+ Comma separated list of options for socket2unix. Valid options are (without
+ quotes):
+ - 'client_only': Don't intercept calls to `listen()` and `accept()`.
+ - 'server_only': Don't intercept calls to `connect()`.
+ These options are useful if a program has both client and server
+ functionality but only one part should be redirected.
+
+
+EXAMPLES
+--------
+
+`socat` can be used to forward UNIX sockets over SSH. Thanks to [1] for the
+necessary commands.
+
+[1]: http://www.debian-administration.org/users/dkg/weblog/68
+
+`socat` is required on both local and remote system.
+
+To forward the server socket `path/to/socket/remote` from `remote-host` to
+`path/to/socket/local` on the local host run this command on the local system:
+
+ $ socat UNIX-LISTEN:path/to/socket/local,reuseaddr,fork \
+ EXEC:'ssh remote-host socat STDIO UNIX-CONNECT\:path/to/socket/remote'
+
+Any program on the local host can then connect to `path/to/socket/local` and
+the connection gets forwarded to `remote-host`.
+
+To use the forwarding with socket2unix the sockets must be named appropriately
+(see above). For example to use socket2unix on the client-side:
+
+ $ socat UNIX-LISTEN:socket-v4-4711,reuseaddr,fork ...
+
+Connect to the forwarded socket:
+
+ $ LD_PRELOAD=/path/to/libsocket2unix.so \
+ SOCKET2UNIX_PATH=`pwd`/socket nc -4 localhost 3000
+
+The same works for the remote socket.
BUGS