]> ruderich.org/simon Gitweb - socket2unix/socket2unix.git/blob - README
4776f6fb7e706aac144901a671449b725cec7d7b
[socket2unix/socket2unix.git] / 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` (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 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 EXAMPLES
84 --------
85
86 `socat` can be used to forward UNIX sockets over SSH. Thanks to [1] for the
87 necessary commands.
88
89 [1]: http://www.debian-administration.org/users/dkg/weblog/68
90
91 `socat` is required on both local and remote system.
92
93 To forward the server socket `path/to/socket/remote` from `remote-host` to
94 `path/to/socket/local` on the local host run this command on the local system:
95
96     $ socat UNIX-LISTEN:path/to/socket/local,reuseaddr,fork \
97         EXEC:'ssh remote-host socat STDIO UNIX-CONNECT\:path/to/socket/remote'
98
99 Any program on the local host can then connect to `path/to/socket/local` and
100 the connection gets forwarded to `remote-host`.
101
102 To use the forwarding with socket2unix the sockets must be named appropriately
103 (see above). For example to use socket2unix on the client-side:
104
105     $ socat UNIX-LISTEN:socket-v4-4711,reuseaddr,fork ...
106
107 Connect to the forwarded socket:
108
109     $ LD_PRELOAD=/path/to/libsocket2unix.so \
110         SOCKET2UNIX_PATH=`pwd`/socket nc -4 localhost 3000
111
112 The same works for the remote socket.
113
114
115 BUGS
116 ----
117
118 If you find any bugs not mentioned in this document please report them to
119 <simon@ruderich.org> with socket2unix in the subject.
120
121
122 AUTHORS
123 -------
124
125 Written by Simon Ruderich <simon@ruderich.org>.
126
127
128 LICENSE
129 -------
130
131 socket2unix is licensed under GPL version 3 or later.
132
133 Copyright (C) 2013  Simon Ruderich
134
135 This program is free software: you can redistribute it and/or modify
136 it under the terms of the GNU General Public License as published by
137 the Free Software Foundation, either version 3 of the License, or
138 (at your option) any later version.
139
140 This program is distributed in the hope that it will be useful,
141 but WITHOUT ANY WARRANTY; without even the implied warranty of
142 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
143 GNU General Public License for more details.
144
145 You should have received a copy of the GNU General Public License
146 along with this program.  If not, see <http://www.gnu.org/licenses/>.