README: Add example about socket forwarding with socat.

diff --git a/README b/README
index da69397ca75d01bbc8cf7d34c5609d5c0fc83f40..4776f6fb7e706aac144901a671449b725cec7d7b 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 forwared over SSH with `socat` (see below).
 
 
 DEPENDENCIES
@@ -80,6 +80,38 @@ The following additional environment variables are available:
     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
 ----