Commit | Line | Data |
---|---|---|
e4976bb0 | 1 | .de VS |
2 | .sp 1 | |
3 | .RS | |
4 | .nf | |
5 | .ft B | |
6 | .. | |
7 | .de VE | |
8 | .ft R | |
9 | .fi | |
10 | .RE | |
11 | .sp 1 | |
12 | .. | |
13 | .TH noip 1 "5 May 2005" "Straylight/Edgeware" "Preload hacks" | |
14 | .SH NAME | |
15 | noip \- run programs without the ability to use IP sockets | |
16 | .SH SYNOPSIS | |
17 | .B noip | |
18 | .RI [ command | |
19 | .RI [ args ...]] | |
20 | .SH DESCRIPTION | |
21 | The | |
22 | .B noip | |
23 | program runs | |
24 | .I command | |
25 | (by default, the user's shell, as determined by the | |
26 | .B SHELL | |
27 | environment variable) in an environment where attempts to use TCP/IP | |
28 | networking are (mostly) transparently translated into the use of | |
29 | Unix-domain sockets in a private directory. | |
30 | .PP | |
31 | There are many programs which use TCP/IP for their own internal | |
32 | communications needs, largely unnecessarily. This can present security | |
33 | problems: even if a program binds its listening sockets to | |
34 | .BR localhost , | |
35 | other users on the same system can still connect, and many such programs | |
36 | don't seem to have authentication systems. | |
37 | .PP | |
38 | .B noip | |
39 | addresses this problem by intercepting a program's networking calls and | |
40 | making it use Unix-domain sockets in a private directory instead of | |
41 | TCP/IP. Now its communications are truly private to the running user. | |
42 | .SS The socket directory | |
43 | The | |
44 | .B noip | |
45 | program keeps its sockets in a directory whose name can be configured, | |
46 | but by default is | |
47 | .BI noip- \c | |
48 | .IR username , | |
49 | where | |
50 | .I username | |
51 | is determined by the | |
52 | .B USER | |
53 | or | |
54 | .B LOGNAME | |
55 | environment variables, or is | |
56 | .BI uid- \c | |
57 | .IR realuid | |
58 | in the temporary directory, which in turn is determined by the | |
59 | .B TMPDIR | |
60 | or | |
61 | .B TMP | |
62 | environment variables, or is | |
63 | .BR /tmp . | |
64 | The sockets in this directory are simply named | |
65 | .IB dottedquad : port | |
66 | after the Internet sockets they represent. | |
67 | .PP | |
68 | If the socket directory does not exist when a program running under | |
69 | .B noip | |
70 | starts up, it is created and made readable and writable only by the | |
71 | current user. Also, it is scanned and any apparently stale sockets are | |
72 | removed. | |
73 | .SS Configuration | |
74 | The operation of | |
75 | .B noip | |
76 | is controlled by a configuration file. By default, | |
77 | .B noip | |
78 | reads configuration from | |
79 | .B .noip | |
80 | in the calling user's home directory, as determined by the | |
81 | .B HOME | |
5b49f527 | 82 | environment, or, failing that, looking up the effective user id in the |
83 | password database. However, if the environment variable | |
a6d9626b | 84 | .B NOIP_CONFIG |
85 | is set, then the file it names is read instead (assuming it exists; if | |
86 | it doesn't, no configuration is read). | |
e4976bb0 | 87 | .PP |
88 | The configuration file has a simple line-based format. A line is | |
89 | ignored if it consists only of whitespace, or if its first whitespace | |
90 | character is | |
91 | .RB ` # '. | |
92 | Otherwise, the first whitespace-delimited word is a keyword and the | |
93 | remainder of the line is a value. The following keywords are | |
94 | recognized. | |
95 | .TP | |
96 | .BR "debug " [\fInumber\fR] | |
97 | If | |
98 | .I number | |
99 | is nonzero, turn debugging on; if it is zero, turn debugging off. The | |
100 | default, if no | |
101 | .I number | |
102 | is given, is to turn debugging on. Debugging is written to standard | |
103 | error. Some debugging is produced before the configuration file is | |
104 | read; the environment variable | |
105 | .B NOIP_DEBUG | |
106 | can be used to control this. | |
107 | .TP | |
108 | .BI "socketdir " directory | |
109 | Store the Unix-domain sockets in | |
110 | .IR directory | |
a6d9626b | 111 | rather than the default. The environment variable |
112 | .B NOIP_SOCKETDIR | |
113 | can also be used to control which directory is used for sockets. | |
e4976bb0 | 114 | .TP |
f6049fdd | 115 | .BI "autoports " min "\-" max |
116 | Select which ports are used for implicit binding. Allocating ports can | |
117 | be a bit slow, since checking whether a Unix domain socket is in use is | |
118 | difficult. A wide range makes things easier, because | |
119 | .B noip | |
120 | starts by trying ports at random from the given range. The environment | |
121 | variable | |
122 | .B NOIP_AUTOPORTS | |
123 | can also be used to control which ports are assigned automatically. | |
124 | .TP | |
e4976bb0 | 125 | .BI "realbind " acl-entry |
126 | Add an entry to the | |
127 | .B realbind | |
128 | access control list (ACL). When a program attempts to | |
129 | .BR bind (2) | |
130 | a socket to an address, the | |
131 | .B realbind | |
132 | ACL is consulted. If the address is matched, then the program is | |
133 | allowed to bind a real Internet socket to that address; otherwise, the | |
a6d9626b | 134 | socket is bound to a Unix-domain socket. Three environment variables |
135 | are consulted too: | |
136 | .BR NOIP_REALBIND_BEFORE , | |
137 | .BR NOIP_REALBIND , | |
138 | and | |
139 | .BR NOIP_REALBIND_AFTER . | |
140 | The | |
141 | .B _BEFORE | |
142 | rules are inserted at the front of the list; the | |
143 | .B _AFTER | |
144 | rules are appended on the end. Currently, the rules in | |
145 | .B NOIP_REALBIND | |
146 | are also put at the end (before the | |
147 | .B _AFTER | |
148 | rules), though this may change later. | |
e4976bb0 | 149 | .TP |
a6d9626b | 150 | .BI "realconnect " acl-entry |
e4976bb0 | 151 | Add an entry to the |
152 | .B realconnect | |
153 | access control list (ACL). When a program attempts to | |
154 | .BR connect (2) | |
155 | a socket to an address, or to contact another socket using | |
156 | .BR sendto (2) | |
157 | or | |
158 | .BR sendmsg (2), | |
159 | the | |
160 | .B realconnect | |
161 | ACL is consulted. If the destination address is matched, then the | |
162 | program is allowed to contact the real Internet socket; otherwise, the | |
a6d9626b | 163 | attempt is made to contact a Unix-domain socket. Three environment variables |
164 | are consulted too: | |
165 | .BR NOIP_REALCONNET_BEFORE , | |
166 | .BR NOIP_REALCONNECT , | |
167 | and | |
168 | .BR NOIP_REALCONNECT_AFTER . | |
169 | The | |
170 | .B _BEFORE | |
171 | rules are inserted at the front of the list; the | |
172 | .B _AFTER | |
173 | rules are appended on the end. Currently, the rules in | |
174 | .B NOIP_REALCONNECT | |
175 | are also put at the end (before the | |
176 | .B _AFTER | |
177 | rules), though this may change later. | |
e4976bb0 | 178 | .PP |
179 | (Aside: An attempt to connect to a remote host may not be a hopeless failure, | |
180 | even if a real IP socket is denied: | |
181 | .B noip | |
182 | deliberately makes no attempt to check that addresses being bound to | |
183 | sockets correspond to locally available addresses; and besides, sockets | |
184 | can be introduced into the directory by other programs simulating remote | |
185 | servers.) | |
186 | .PP | |
187 | An | |
188 | .I acl-entry | |
a6d9626b | 189 | is a comma-separated list of entries of the form: |
e4976bb0 | 190 | .IP |
191 | .BR + | \- | |
192 | .IR address \c | |
193 | .RB [ \- \c | |
194 | .IR address | \c | |
195 | .BR / \c | |
9314b85a | 196 | .IR prefix-length ]| \c |
e4976bb0 | 197 | .BR local | any |
198 | .RB [ : \c | |
199 | .IR port [ \c | |
200 | .BI \- \c | |
201 | .IR port ]] | |
202 | .PP | |
203 | (The spaces in the above are optional.) | |
204 | .PP | |
99222954 | 205 | The leading sign says whether matching addresses should be |
e4976bb0 | 206 | .I accepted |
207 | .RB (` + ') | |
208 | or | |
209 | .I denied | |
210 | .RB (` \- '). | |
211 | .PP | |
212 | The IP-address portion may be any of the following | |
213 | .TP | |
214 | .B any | |
215 | Matches all addresses. | |
216 | .TP | |
217 | .B local | |
218 | Matches the address of one of the machine's network interfaces. | |
219 | .TP | |
220 | .I address | |
2a06ea0b | 221 | Matches just the given IPv4 or IPv6 address. An |
9314b85a | 222 | .I address |
2a06ea0b MW |
223 | may be enclosed in square brackets; IPv6 addresses must be so enclosed, |
224 | because colons are significant in the rest of the ACL syntax. | |
e4976bb0 | 225 | .TP |
226 | .IB address \- address | |
227 | Matches any address which falls in the given range. Addresses are | |
228 | compared lexicographically, with octets to the left given precedence | |
229 | over octets to the right. | |
230 | .TP | |
9314b85a MW |
231 | .IB address / prefix-length |
232 | Matches an address in the given network. | |
e4976bb0 | 233 | .PP |
234 | The port portion may be omitted (which means `match any port'), or may | |
235 | be a single | |
236 | .I port | |
237 | or a range | |
238 | .IB port \- port | |
239 | to match. | |
240 | .PP | |
241 | Range comparisons are always inclusive of both endpoints. | |
242 | .PP | |
243 | ACL entries are processed in the order they appear in the configuration | |
244 | file. The default action of an ACL, used if none of its entries match, | |
245 | is the opposite of the last actual entry in the list: if the last entry | |
246 | says `accept', then the default is to deny, and vice-versa. If the ACL | |
247 | is empty, the default is to deny all addresses. | |
248 | .PP | |
249 | For example, it may be useful to allow access at least to a DNS server. | |
250 | This can be accomplished by adding a line | |
251 | .VS | |
a8be0591 | 252 | realconnect +1.2.3.4:53 |
e4976bb0 | 253 | .VE |
254 | to the configuration file, where 1.2.3.4 is the IP address of one of | |
255 | your DNS server. | |
256 | .SS Example applications | |
257 | SLIME is an Emacs extension for doing interactive programming with Lisp | |
258 | systems. It communicates with the Lisp system using TCP sockets, since | |
259 | Unix-domain sockets are unavailable on Windows, and besides, they are | |
260 | less well supported by Lisp implementations. Unfortunately, when the | |
261 | author wrote this program, SLIME applied no authentication on its TCP | |
262 | port, allowing any local user to take over the running Lisp. Worse, | |
263 | some Lisps are unable to bind a listening socket to a particular | |
264 | address, leaving the socket potentially available to anyone on the | |
265 | network. By running Emacs under | |
266 | .BR noip , | |
267 | the security hole is closed completely and no messing with | |
268 | authentication secrets is needed. | |
269 | .PP | |
270 | SSH is an excellent tool for secure communications over hostile | |
271 | networks. In particular, its ability to forward TCP connections to a | |
272 | port on one side of an SSH tunnel to the other side is very useful. | |
273 | However, such a forwarded port is available to all users on the source | |
274 | side of the tunnel. Using | |
275 | .B noip | |
276 | and a suitable configuration, a user can restrict access to a forwarded | |
277 | port to himself or a small group. | |
278 | .SH BUGS | |
279 | .B noip | |
280 | is implemented as an | |
281 | .B LD_PRELOAD | |
282 | hack. It won't work on setuid programs. Also, perhaps more | |
a8be0591 | 283 | importantly, it can't do anything to prevent a |
e4976bb0 | 284 | .I malicious |
a8be0591 | 285 | program's use of networking: a program could theoretically issue sockets |
e4976bb0 | 286 | system calls directly instead of using the C library calls that |
287 | .B noip | |
288 | intercepts. It is intended only as a tool for enhancing the security of | |
289 | software written by well-meaning programmers who don't understand the | |
290 | security aspects of writing networking code. | |
291 | .PP | |
292 | It's very hard to tell exactly what state a Unix-domain socket is in. | |
293 | If the filesystem object isn't there, it's not active, but if it | |
294 | .I is | |
295 | then the socket might be in use or it might be stale. | |
296 | .B noip | |
297 | consults | |
298 | .B /proc/net/unix | |
299 | to decide whether a socket is in use, but this can fail in two ways. | |
300 | Firstly, if the socket is created and renamed, the kernel doesn't | |
301 | notice, and | |
302 | .B noip | |
303 | will think that the new name is stale. Secondly, if the socket is | |
304 | created, used, unlinked while it's still in use, and recreated, then | |
305 | .B noip | |
306 | will think that it's in use when in fact it's gone stale. Don't mess | |
307 | with | |
308 | .BR noip 's | |
309 | sockets unless you know what you're doing. | |
310 | .PP | |
311 | The procedure to replace a Unix-domain socket by an Internet one is | |
312 | fairly thorough, but there are some missing cases. In particular, if | |
313 | the socket being bound or connected is a duplicate (using | |
314 | .BR dup (2)) | |
315 | then only one of the copies will be fixed. Similarly, copies owned by | |
316 | child processes will be unaffected. | |
317 | .PP | |
318 | This manual is surprisingly long and complicated for such a simple hack. | |
319 | .SH AUTHOR | |
a8be0591 | 320 | Mark Wooding, <mdw@distorted.org.uk> |