README

   1 README
   2 ======
   3
   4 socket2unix is a simple 'LD_PRELOAD' wrapper to ``convert'' network sockets to
   5 UNIX sockets. Useful on remote systems with untrusted users (but trusted root)
   6 to be able to launch a server which is accessible only by the user. Normal
   7 sockets are usable by everyone on the system.
   8
   9 It works for both servers (`listen(3)`) and clients (`connect(3)`).
  10
  11 These UNIX sockets can also be forwarded over SSH with `socat` (see below).
  12
  13
  14 DEPENDENCIES
  15 ------------
  16
  17 - C99 compiler
  18 - dynamic linker/loader which supports 'LD_PRELOAD' (e.g. GNU/Linux's or
  19   FreeBSD's ld.so)
  20
  21
  22 INSTALLATION
  23 ------------
  24
  25     ./configure && make && make check
  26
  27 Then either install the library with `make install` or just copy it from
  28 `src/.libs/` to wherever you want to install it:
  29
  30     rm -f /destination/path/for/library/libsocket2unix.so
  31     cp -L src/.libs/libsocket2unix.so /destination/path/for/library/
  32
  33 *Important:* Don't overwrite an existing `libsocket2unix.so` file which is in
  34 use by any program or the program may crash. Instead remove the file first and
  35 then copy the new version. This is not a bug in socket2unix, but a general
  36 problem.
  37
  38
  39 USAGE
  40 -----
  41
  42 Set 'LD_PRELOAD' to include the _absolute_ path to `libsocket2unix.so`:
  43
  44     LD_PRELOAD=/absolute/path/to/libsocket2unix.so
  45
  46 The 'SOCKET2UNIX_PATH' environment variable must be set to the path of the
  47 UNIX socket to use (client) or create (server). The IP version ("v4" or "v6")
  48 and the port number (if applicable) is appended to create a unique path.
  49
  50
  51 Example (server):
  52
  53     $ LD_PRELOAD=/path/to/libsocket2unix.so \
  54         SOCKET2UNIX_PATH=`pwd`/test nc -l -p 5000
  55
  56 This creates two sockets named `socket-v4-5000` and `socket-v6-5000` in the
  57 current directory. If the files already exist and are sockets, they are
  58 overwritten. Other file types are not touched.
  59
  60 Example (client):
  61
  62     $ LD_PRELOAD=/path/to/libsocket2unix.so \
  63         SOCKET2UNIX_PATH=`pwd`/test nc localhost 5000
  64
  65 `nc` connects to the server socket created above and both instances can talk
  66 to each other without knowing they use an UNIX socket instead of a TCP
  67 connection on port 5000.
  68
  69
  70 The following additional environment variables are available:
  71
  72 - 'SOCKET2UNIX_DEBUG':
  73   Control debug level. 1 = errors only, 2 = warnings only, 3 = debug messages.
  74   Default: 2
  75 - 'SOCKET2UNIX_OPTIONS':
  76   Comma separated list of options for socket2unix. Valid options are (without
  77   quotes):
  78   - 'client_only': Don't intercept calls to `listen()` and `accept()`.
  79   - 'server_only': Don't intercept calls to `connect()`.
  80     These options are useful if a program has both client and server
  81     functionality but only one part should be redirected.
  82
  83
  84 EXAMPLES
  85 --------
  86
  87 `socat` can be used to forward UNIX sockets over SSH. Thanks to [1] for the
  88 necessary commands.
  89
  90 [1]: http://www.debian-administration.org/users/dkg/weblog/68
  91
  92 `socat` is required on both local and remote system.
  93
  94 To forward the server socket `path/to/socket/remote` from `remote-host` to
  95 `path/to/socket/local` on the local host run this command on the local system:
  96
  97     $ socat UNIX-LISTEN:path/to/socket/local,reuseaddr,fork \
  98         EXEC:'ssh remote-host socat STDIO UNIX-CONNECT\:path/to/socket/remote'
  99
 100 Any program on the local host can then connect to `path/to/socket/local` and
 101 the connection gets forwarded to `remote-host`.
 102
 103 To use the forwarding with socket2unix the sockets must be named appropriately
 104 (see above). For example to use socket2unix on the client-side:
 105
 106     $ socat UNIX-LISTEN:socket-v4-4711,reuseaddr,fork ...
 107
 108 Connect to the forwarded socket:
 109
 110     $ LD_PRELOAD=/path/to/libsocket2unix.so \
 111         SOCKET2UNIX_PATH=`pwd`/socket nc -4 localhost 3000
 112
 113 The same works for the remote socket.
 114
 115
 116 BUGS
 117 ----
 118
 119 If you find any bugs not mentioned in this document please report them to
 120 <simon@ruderich.org> with socket2unix in the subject.
 121
 122
 123 AUTHORS
 124 -------
 125
 126 Written by Simon Ruderich <simon@ruderich.org>.
 127
 128
 129 LICENSE
 130 -------
 131
 132 socket2unix is licensed under GPL version 3 or later.
 133
 134 Copyright (C) 2013  Simon Ruderich
 135
 136 This program is free software: you can redistribute it and/or modify
 137 it under the terms of the GNU General Public License as published by
 138 the Free Software Foundation, either version 3 of the License, or
 139 (at your option) any later version.
 140
 141 This program is distributed in the hope that it will be useful,
 142 but WITHOUT ANY WARRANTY; without even the implied warranty of
 143 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 144 GNU General Public License for more details.
 145
 146 You should have received a copy of the GNU General Public License
 147 along with this program.  If not, see <http://www.gnu.org/licenses/>.