chiark / gitweb /
Fix incorrect closes.
[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 It is quite possible that
194 .B authbind
195 and other programs and facilities which use
196 .B LD_PRELOAD
197 may interfere with each other, causing unpredictable behaviour or even
198 core dumps.
199 .B authbind
200 is known sometimes not to work correctly with
201 .BR fakeroot ,
202 for example (even supposing it could be determined what `correctly'
203 means in this context).
204 .PP
205 .B authbind
206 is ineffective with setuid programs, because they do not honour
207 .B LD_PRELOAD
208 for security reasons.  Of course a setuid-root program does not need
209 .BR authbind ,
210 but it might be useful to apply it to program which are setuid to
211 another user or setgid.  If the author or builder of such a programs
212 wishes it to use authbind they could have it load the
213 .B libauthbind
214 library explicitly rather than via
215 .BR LD_PRELOAD .
216 .PP
217 Some badly-written programs may have trouble because
218 .B authbind
219 spawns a child process `under their feet', causing (for example) a
220 .BR fork (2)
221 to happen and
222 .B SIGCHLD
223 signal to be delivered.  Programs should not rely on standard
224 libraries not doing these things.
225 .PP
226 Ports from 512 to 1023 inclusive cannot be used with
227 .B authbind
228 because that would create a security hole, in conjection with
229 .BR rshd .
230 .PP
231 The access control configuration scheme is somewhat strange.
232 .SH FILES AND ENVIRONMENT VARIABLES
233 .TP
234 .I /usr/lib/authbind/libauthbind.so.1.0
235 The shared library which
236 .B authbind
237 causes to be loaded using
238 .BR LD_PRELOAD ,
239 and which actually implements the diversion of
240 .BR bind (2)
241 to an external program.
242 .TP
243 .I LD_PRELOAD
244 The variable used by the dynamic linker when starting dynamically
245 linked programs and deciding which shared libraries to load and
246 modifed by the
247 .B authbind
248 program to allow it to override the usual meaning of
249 .BR bind (2) .
250 .TP
251 .I AUTHBIND_LIB
252 If set, forces
253 .B authbind
254 to use its value as the path to the shared library to put in
255 .BR LD_PRELOAD ,
256 instead of the compiled-in value.  In any case, unless
257 .B --deep
258 was specified,
259 .B authbind
260 will set this variable to the name of the library actually added to
261 .BR LD_PRELOAD ,
262 so that the library can find and remove the right entry.
263 .TP
264 .I AUTHBIND_LEVELS
265 This variable is set by
266 .B authbind
267 to the number of levels left from the
268 .B --depth
269 or
270 .B --deep
271 option, minus one.  It is decremented during
272 .B _init
273 by the library on each program call, and the library will remove
274 itself from the
275 .B LD_PRELOAD
276 when it reaches zero.  The special value
277 .B y
278 means
279 .B --deep
280 was specified.
281 .SH SEE ALSO
282 .BR bind (2),
283 .BR authbind\-helper (8),
284 .BR dlsym (3),
285 .BR ld.so (8)
286 .SH AUTHOR
287 .B authbind
288 and this manpage were written by Ian Jackson.  They are
289 Copyright (C)1998
290 by him and released under the GNU General Public Licence; there is NO
291 WARRANTY.  See
292 .B /usr/doc/authbind/copyright
293 and
294 .B /usr/doc/copyright/GPL
295 for details.