Log functions always write a trailing newline.

[socket2unix/socket2unix.git] / README

diff --git a/README b/README
index ba408bd3a9b8220fde53126493821437b5a54343..60d639f7ad48fb031ad316eb4000f6e35ce28794 100644 (file)
--- a/README
+++ b/README
@@ -8,7 +8,7 @@ sockets are usable by everyone on the system.
 
 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
@@ -30,9 +30,10 @@ Then either install the library with `make install` or just copy it from
     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
@@ -71,6 +72,45 @@ The following additional environment variables are available:
 - '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