13 .TH noip 1 "5 May 2005" "Straylight/Edgeware" "Preload hacks"
15 noip \- run programs without the ability to use IP sockets
25 (by default, the user's shell, as determined by the
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.
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
35 other users on the same system can still connect, and many such programs
36 don't seem to have authentication systems.
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
45 program keeps its sockets in a directory whose name can be configured,
55 environment variables, or is
58 in the temporary directory, which in turn is determined by the
62 environment variables, or is
64 The sockets in this directory are simply named
66 after the Internet sockets they represent.
68 If the socket directory does not exist when a program running under
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
76 is controlled by a configuration file. By default,
78 reads configuration from
80 in the calling user's home directory, as determined by the
82 environment, or, failing that, looking up the effective user id in the
83 password database. However, if the environment variable
85 is set, then the file it names is read instead (assuming it exists; if
86 it doesn't, no configuration is read).
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
90 non-whitespace character is
92 Otherwise, the first whitespace-delimited word is a keyword and the
93 remainder of the line is a value. The following keywords are
96 .BR "debug " [\fInumber\fR]
99 is nonzero, turn debugging on; if it is zero, turn debugging off. The
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
106 can be used to control this.
108 .BI "socketdir " directory
109 Store the Unix-domain sockets in
111 rather than the default. The environment variable
113 can also be used to control which directory is used for sockets.
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
120 starts by trying ports at random from the given range. The environment
123 can also be used to control which ports are assigned automatically.
125 .BI "realbind " acl-entry
126 Add a comma-separated list of entries to the
128 access control list (ACL). (See below for the format of an ACL entry.)
129 When a program attempts to
131 a socket to an address, the
133 ACL is consulted. If the address is matched, then the program is
134 allowed to bind a real Internet socket to that address; otherwise, the
135 socket is bound to a Unix-domain socket. Three environment variables
137 .BR NOIP_REALBIND_BEFORE ,
140 .BR NOIP_REALBIND_AFTER .
143 rules are inserted at the front of the list; the
145 rules are appended on the end. Currently, the rules in
147 are also put at the end (before the
149 rules), though this may change later.
151 .BI "realconnect " acl-entry
152 Add a comma-separated list of entries to the
154 access control list (ACL). (See below for the format of an ACL entry.)
155 When a program attempts to
157 a socket to an address, or to contact another socket using
163 ACL is consulted. If the destination address is matched, then the
164 program is allowed to contact the real Internet socket; otherwise, the
165 attempt is made to contact a Unix-domain socket. Three environment variables
167 .BR NOIP_REALCONNET_BEFORE ,
168 .BR NOIP_REALCONNECT ,
170 .BR NOIP_REALCONNECT_AFTER .
173 rules are inserted at the front of the list; the
175 rules are appended on the end. Currently, the rules in
177 are also put at the end (before the
179 rules), though this may change later.
181 (Aside: An attempt to connect to a remote host may not be a hopeless failure,
182 even if a real IP socket is denied:
184 deliberately makes no attempt to check that addresses being bound to
185 sockets correspond to locally available addresses; and besides, sockets
186 can be introduced into the directory by other programs simulating remote
189 .BI "impbind " bind-rule
190 Add a comma-separated list of entries to the implicit-bind rule list.
191 When a program attempts to transmit from a socket \(en e.g., with
195 \(en without binding its local address first,
197 consults this list to decide on the correct local address to assign.
198 Each entry in the list has the form
205 The rules are tried in order: if the remote address matches (in the same
206 way as in an ACL entry) the address range on the left side of the rule,
207 then the socket is bound to the address from the right side; if the
208 address on the right is
210 then the remote address is used.
212 Three environment variables
214 .BR NOIP_IMPBIND_BEFORE ,
217 .BR NOIP_IMPBIND_AFTER .
220 rules are inserted at the front of the list; the
222 rules are appended on the end. Currently, the rules in
224 are also put at the end (before the
226 rules), though this may change later.
231 is a comma-separated list of entries of the form:
238 (The spaces in the above are optional.)
240 The leading sign says whether matching addresses should be
249 portion may be any of the following.
252 Matches all addresses.
255 Matches the address of one of the machine's network interfaces.
258 Matches just the given IPv4 or IPv6 address. An
260 may be enclosed in square brackets; IPv6 addresses must be so enclosed,
261 because colons are significant in the rest of the ACL syntax.
263 .IB address \- address
264 Matches any address which falls in the given range. Addresses are
265 compared lexicographically, with octets to the left given precedence
266 over octets to the right.
268 .IB address / prefix-length
269 Matches an address in the given network.
273 may be omitted (which means `match any port'), or may be a single
279 Range comparisons are always inclusive of both endpoints.
281 ACL entries are processed in the order they appear in the configuration
282 file. The default action of an ACL, used if none of its entries match,
283 is the opposite of the last actual entry in the list: if the last entry
284 says `accept', then the default is to deny, and vice-versa. If the ACL
285 is empty, the default is to deny all addresses.
287 For example, it may be useful to allow access at least to a DNS server.
288 This can be accomplished by adding a line
290 realconnect +1.2.3.4:53
292 to the configuration file, where 1.2.3.4 is the IP address of one of
294 .SS Example applications
295 SLIME is an Emacs extension for doing interactive programming with Lisp
296 systems. It communicates with the Lisp system using TCP sockets, since
297 Unix-domain sockets are unavailable on Windows, and besides, they are
298 less well supported by Lisp implementations. Unfortunately, when the
299 author wrote this program, SLIME applied no authentication on its TCP
300 port, allowing any local user to take over the running Lisp. Worse,
301 some Lisps are unable to bind a listening socket to a particular
302 address, leaving the socket potentially available to anyone on the
303 network. By running Emacs under
305 the security hole is closed completely and no messing with
306 authentication secrets is needed.
308 SSH is an excellent tool for secure communications over hostile
309 networks. In particular, its ability to forward TCP connections to a
310 port on one side of an SSH tunnel to the other side is very useful.
311 However, such a forwarded port is available to all users on the source
312 side of the tunnel. Using
314 and a suitable configuration, a user can restrict access to a forwarded
315 port to himself or a small group.
320 hack. It won't work on setuid programs. Also, perhaps more
321 importantly, it can't do anything to prevent a
323 program's use of networking: a program could theoretically issue sockets
324 system calls directly instead of using the C library calls that
326 intercepts. It is intended only as a tool for enhancing the security of
327 software written by well-meaning programmers who don't understand the
328 security aspects of writing networking code.
330 It's very hard to tell exactly what state a Unix-domain socket is in.
331 If the filesystem object isn't there, it's not active, but if it
333 then the socket might be in use or it might be stale.
337 to decide whether a socket is in use, but this can fail in two ways.
338 Firstly, if the socket is created and renamed, the kernel doesn't
341 will think that the new name is stale. Secondly, if the socket is
342 created, used, unlinked while it's still in use, and recreated, then
344 will think that it's in use when in fact it's gone stale. Don't mess
347 sockets unless you know what you're doing.
349 The procedure to replace a Unix-domain socket by an Internet one is
350 fairly thorough, but there are some missing cases. In particular, if
351 the socket being bound or connected is a duplicate (using
353 then only one of the copies will be fixed. Similarly, copies owned by
354 child processes will be unaffected.
356 This manual is surprisingly long and complicated for such a simple hack.
358 Mark Wooding, <mdw@distorted.org.uk>