X-Git-Url: https://ruderich.org/simon/gitweb/?p=socket2unix%2Fsocket2unix.git;a=blobdiff_plain;f=README;h=60d639f7ad48fb031ad316eb4000f6e35ce28794;hp=da69397ca75d01bbc8cf7d34c5609d5c0fc83f40;hb=HEAD;hpb=16e3b5325c41eee1aa88ecd4e054be7b608a7810

diff --git a/README b/README
index da69397..60d639f 100644
--- 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
@@ -80,6 +81,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
 ----