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 forwared over SSH with `socat`.
  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 use
  34 by any program. Instead remove the file first and then copy the new version.
  35 This is not a bug in socket2unix, but a general problem.
  36
  37
  38 USAGE
  39 -----
  40
  41 Set 'LD_PRELOAD' to include the _absolute_ path to `libsocket2unix.so`:
  42
  43     LD_PRELOAD=/absolute/path/to/libsocket2unix.so
  44
  45 The 'SOCKET2UNIX_PATH' environment variable must be set to the path of the
  46 UNIX socket to use (client) or create (server). The IP version ("v4" or "v6")
  47 and the port number (if applicable) is appended to create a unique path.
  48
  49
  50 Example (server):
  51
  52     $ LD_PRELOAD=/path/to/libsocket2unix.so \
  53         SOCKET2UNIX_PATH=`pwd`/test nc -l -p 5000
  54
  55 This creates two sockets named `socket-v4-5000` and `socket-v6-5000` in the
  56 current directory. If the files already exist and are sockets, they are
  57 overwritten. Other file types are not touched.
  58
  59 Example (client):
  60
  61     $ LD_PRELOAD=/path/to/libsocket2unix.so \
  62         SOCKET2UNIX_PATH=`pwd`/test nc localhost 5000
  63
  64 `nc` connects to the server socket created above and both instances can talk
  65 to each other without knowing they use an UNIX socket instead of a TCP
  66 connection on port 5000.
  67
  68
  69 The following additional environment variables are available:
  70
  71 - 'SOCKET2UNIX_DEBUG':
  72   Control debug level. 1 = errors only, 2 = warnings only, 3 = debug messages.
  73   Default: 2
  74 - 'SOCKET2UNIX_OPTIONS':
  75   Comma separated list of options for socket2unix. Valid options are (without
  76   quotes):
  77   - 'client_only': Don't intercept calls to `listen()` and `accept()`.
  78   - 'server_only': Don't intercept calls to `connect()`.
  79     These options are useful if a program has both client and server
  80     functionality but only one part should be redirected.
  81
  82
  83 BUGS
  84 ----
  85
  86 If you find any bugs not mentioned in this document please report them to
  87 <simon@ruderich.org> with socket2unix in the subject.
  88
  89
  90 AUTHORS
  91 -------
  92
  93 Written by Simon Ruderich <simon@ruderich.org>.
  94
  95
  96 LICENSE
  97 -------
  98
  99 socket2unix is licensed under GPL version 3 or later.
 100
 101 Copyright (C) 2013  Simon Ruderich
 102
 103 This program is free software: you can redistribute it and/or modify
 104 it under the terms of the GNU General Public License as published by
 105 the Free Software Foundation, either version 3 of the License, or
 106 (at your option) any later version.
 107
 108 This program is distributed in the hope that it will be useful,
 109 but WITHOUT ANY WARRANTY; without even the implied warranty of
 110 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 111 GNU General Public License for more details.
 112
 113 You should have received a copy of the GNU General Public License
 114 along with this program.  If not, see <http://www.gnu.org/licenses/>.