chiark / gitweb /
record manpage change in changelog
[authbind.git] / authbind.1
1 .\" Hey, Emacs!  This is an -*- nroff -*- source file.
2 .\" Authors: Ian Jackson
3 .\" 
4 .\" authbind is Copyright (C) 1998 Ian Jackson
5 .\"
6 .\" This program is free software; you can redistribute it and/or modify
7 .\" it under the terms of the GNU General Public License as published by
8 .\" the Free Software Foundation; either version 2, or (at your option)
9 .\" any later version.
10 .\"
11 .\" This program is distributed in the hope that it will be useful,
12 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
13 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14 .\" GNU General Public License for more details.
15 .\"
16 .\" You should have received a copy of the GNU General Public License
17 .\" along with this program; if not, write to the Free Software Foundation,
18 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 
19 .\"
20 .\" $Id$
21 .\"
22 .TH AUTHBIND 1 "30th August 1998" "Debian Project" "Debian Linux manual"
23 .SH NAME 
24 authbind \- bind sockets to privileged ports without root
25 .SH SYNOPSIS
26 .BR authbind
27 .RI [ options "] " program " [" argument " ...]"
28 .SH DESCRIPTION
29 .B authbind
30 allows a program which does not or should not run as root to bind to
31 low-numbered ports in a controlled way.
32 .PP
33 You must invoke the program using
34 .BR authbind ".  " authbind
35 will set up some environment variables, including an
36 .BR LD_PRELOAD ,
37 which will allow the program (including any subprocesses it may run)
38 to bind to low-numbered (<512) ports if the system is configured to
39 allow this.
40 .SH OPTIONS
41 .TP
42 .B --deep
43 Normally,
44 .B authbind
45 arranges for only the program which it directly invokes to be affected
46 by its special version of
47 .BR bind (2).
48 If you specify
49 .B --deep
50 then all programs which that program invokes directly or indirectly
51 will be affected, so long as they do not unset the environment
52 variables set up by
53 .BR authbind .
54 .TP
55 .BI --depth " levels"
56 Causes
57 .B authbind
58 to affect programs which are
59 .I levels
60 deep in the calling graph.  The default is
61 .BR "--depth 1" .
62 .SH ACCESS CONTROL
63 Access to low numbered ports is controlled by permissions and contents
64 of files in a configuration area,
65 .BR /etc/authbind .
66 .PP
67 Firstly,
68 .BI /etc/authbind/byport/ port
69 is tested.  If this file is accessible for execution to the calling
70 user, according to
71 .BR access (2),
72 then binding to the port is authorised.  If the file can be seen not
73 to exist (the existence check returns
74 .BR ENOENT )
75 then further tests will be used to find authorisation; otherwise,
76 binding is not authorised, and the
77 .B bind
78 call will return with the
79 .B errno
80 value from the
81 .BR access (2)
82 call, usually
83 .B EACCES
84 .RI ( "Permission denied" ).
85 .PP
86 Secondly, if that test fails to resolve the matter,
87 .BI /etc/authbind/byaddr/ addr : port
88 is tested, in the same manner as above.
89 .PP
90 Thirdly, if the question is still unresolved, the file
91 .BI /etc/authbind/byuid/ uid
92 will be opened and read.  If the file does not exist then the binding
93 is not authorised and
94 .B bind
95 will return
96 .B EPERM
97 .RI ( "Operation not permitted" ", or " "Not owner" ).
98 If the file does exist it will be searched for a line of the form
99 .nf
100 .IB             addr / length : min\-port , max\-port
101 .fi
102 matching the request (ie, the initial
103 .I length
104 bits of
105 .I addr
106 match those in the proposed
107 .B bind
108 call, and the proposed port number lies is in the inclusive range
109 specified.  If such a line is found then the binding is authorised.
110 Otherwise it is not, and
111 .B bind
112 will fail with
113 .B ENOENT
114 .RI ( "No such file or directory" ).
115 .PP
116 In each case above,
117 .TP
118 .I port
119 is the (local) TCP or UDP port number, expressed as an unsigned
120 integer in the minimal non-zero number of digits, and
121 .TP
122 .I addr
123 is the (local) IP address, as a dotted quad.
124 .PP
125 If a read error occurs, or the directory
126 .B /etc/authbind
127 cannot be accessed, then not only will
128 .B bind
129 fail, but an error message will be printed to stderr.  Unrecognised
130 lines in
131 .BI /etc/authbind/byuid/ uid
132 files are silently ignored (as are lines whose
133 .I addr
134 has non-zero bits more than
135 .I length
136 from the top).
137 .SH MECHANISM
138 The shared library loaded using
139 .B LD_PRELOAD
140 overrides the
141 .BR bind (2)
142 system call.  When a program invoked via
143 .B authbind
144 calls
145 .B bind
146 to bind a socket to a low-numbered TCP/IP port, and if the program
147 doesn't already have an effective uid of 0, the version of
148 .B bind
149 supposed by
150 .B authbind
151 forks and executes a setuid-root helper program.  For non-TCP/IP
152 sockets, high-numbered ports, or programs which are already root,
153 .B authbind
154 passes the call to the original
155 .BR bind (2)
156 system call, which is found using
157 .BR dlsym (3)
158 with the handle
159 .BR RTLD_NEXT .
160 .PP
161 .SH ERROR HANDLING
162 Usually the normal C error handling mechanisms apply.  If
163 .B authbind
164 cannot find the program it has been asked to execute it will print a
165 message to stderr and exit with code 255.
166 .PP
167 The helper program usually reports back to the shared library with an
168 exit status containing an
169 .B errno
170 value which encodes whether the
171 .B bind
172 was permitted and successful.  This will be returned to the calling
173 program in the usual way.
174 .PP
175 In the case of apparent configuration or other serious errors the
176 library and/or the helper program may cause messages to be printed to
177 the program's stderr, was well as returning -1 from
178 .BR bind .
179 .SH BUGS
180 .B authbind
181 currently only supports IPv4 sockets.  Programs which open other kinds
182 of sockets will not benefit from
183 .BR authbind ,
184 but it won't get in their way.
185 .PP
186 The use of
187 .B LD_PRELOAD
188 makes an
189 .B authbind
190 installation specific to a particular C library.  This version is for
191 GNU/Linux libc6 (glibc2).
192 .PP
193 .B authbind
194 may not operate correctly with multithreaded programs.  It is
195 inherently very difficult (if not impossible) to perform the kind of
196 trickery that authbind does while preventing all undesirable
197 interactions between authbind's activities and those of (say) a
198 threading runtime system.
199 .PP
200 It is quite possible that
201 .B authbind
202 and other programs and facilities which use
203 .B LD_PRELOAD
204 may interfere with each other, causing unpredictable behaviour or even
205 core dumps.
206 .B authbind
207 is known sometimes not to work correctly with
208 .BR fakeroot ,
209 for example (even supposing it could be determined what `correctly'
210 means in this context).
211 .PP
212 .B authbind
213 is ineffective with setuid programs, because they do not honour
214 .B LD_PRELOAD
215 references outside the system directories, for security reasons.  (In
216 fact, setuid programs should not honour
217 .B LD_PRELOAD
218 at all.)
219 Of course a setuid-root program does not need
220 .BR authbind ,
221 but it might be useful to apply it to program which are setuid to
222 another user or setgid.  If the author or builder of such a programs
223 wishes it to use authbind they could have it load the
224 .B libauthbind
225 library explicitly rather than via
226 .BR LD_PRELOAD .
227 .PP
228 Some badly-written programs may have trouble because
229 .B authbind
230 spawns a child process `under their feet', causing (for example) a
231 .BR fork (2)
232 to happen and
233 .B SIGCHLD
234 signal to be delivered.  Programs should not rely on standard
235 libraries not doing these things.
236 .PP
237 Ports from 512 to 1023 inclusive cannot be used with
238 .B authbind
239 because that would create a security hole, in conjection with
240 .BR rshd .
241 .PP
242 The access control configuration scheme is somewhat strange.
243 .SH FILES AND ENVIRONMENT VARIABLES
244 .TP
245 .I /usr/lib/authbind/libauthbind.so.1.0
246 The shared library which
247 .B authbind
248 causes to be loaded using
249 .BR LD_PRELOAD ,
250 and which actually implements the diversion of
251 .BR bind (2)
252 to an external program.
253 .TP
254 .I LD_PRELOAD
255 The variable used by the dynamic linker when starting dynamically
256 linked programs and deciding which shared libraries to load and
257 modifed by the
258 .B authbind
259 program to allow it to override the usual meaning of
260 .BR bind (2) .
261 .TP
262 .I AUTHBIND_LIB
263 If set, forces
264 .B authbind
265 to use its value as the path to the shared library to put in
266 .BR LD_PRELOAD ,
267 instead of the compiled-in value.  In any case, unless
268 .B --deep
269 was specified,
270 .B authbind
271 will set this variable to the name of the library actually added to
272 .BR LD_PRELOAD ,
273 so that the library can find and remove the right entry.
274 .TP
275 .I AUTHBIND_LEVELS
276 This variable is set by
277 .B authbind
278 to the number of levels left from the
279 .B --depth
280 or
281 .B --deep
282 option, minus one.  It is decremented during
283 .B _init
284 by the library on each program call, and the library will remove
285 itself from the
286 .B LD_PRELOAD
287 when it reaches zero.  The special value
288 .B y
289 means
290 .B --deep
291 was specified.
292 .SH SEE ALSO
293 .BR bind (2),
294 .BR authbind\-helper (8),
295 .BR dlsym (3),
296 .BR ld.so (8)
297 .SH AUTHOR
298 .B authbind
299 and this manpage were written by Ian Jackson.  They are
300 Copyright (C)1998
301 by him and released under the GNU General Public Licence; there is NO
302 WARRANTY.  See
303 .B /usr/doc/authbind/copyright
304 and
305 .B /usr/doc/copyright/GPL
306 for details.