chiark / gitweb /
cross-building: Do not include a makefile
[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 .TH AUTHBIND 1 "30th August 1998" "Debian Project" "Debian Linux manual"
21 .SH NAME 
22 authbind \- bind sockets to privileged ports without root
23 .SH SYNOPSIS
24 .BR authbind
25 .RI [ options "] " program " [" argument " ...]"
26 .SH DESCRIPTION
27 .B authbind
28 allows a program which does not or should not run as root to bind to
29 low-numbered ports in a controlled way.
30 .PP
31 You must invoke the program using
32 .BR authbind ".  " authbind
33 will set up some environment variables, including an
34 .BR LD_PRELOAD ,
35 which will allow the program (including any subprocesses it may run)
36 to bind to low-numbered (<512) ports if the system is configured to
37 allow this.
38 .SH OPTIONS
39 .TP
40 .B --deep
41 Normally,
42 .B authbind
43 arranges for only the program which it directly invokes to be affected
44 by its special version of
45 .BR bind (2).
46 If you specify
47 .B --deep
48 then all programs which that program invokes directly or indirectly
49 will be affected, so long as they do not unset the environment
50 variables set up by
51 .BR authbind .
52 .TP
53 .BI --depth " levels"
54 Causes
55 .B authbind
56 to affect programs which are
57 .I levels
58 deep in the calling graph.  The default is
59 .BR "--depth 1" .
60 .SH ACCESS CONTROL
61 Access to low numbered ports is controlled by permissions and contents
62 of files in a configuration area,
63 .BR /etc/authbind .
64 .PP
65 Firstly,
66 .BI /etc/authbind/byport/ port
67 is tested.  If this file is accessible for execution to the calling
68 user, according to
69 .BR access (2),
70 then binding to the port is authorised.  If the file can be seen not
71 to exist (the existence check returns
72 .BR ENOENT )
73 then further tests will be used to find authorisation; otherwise,
74 binding is not authorised, and the
75 .B bind
76 call will return with the
77 .B errno
78 value from the
79 .BR access (2)
80 call, usually
81 .B EACCES
82 .RI ( "Permission denied" ).
83 .PP
84 Secondly, if that test fails to resolve the matter,
85 .BI /etc/authbind/byaddr/ addr , port
86 (any protocol) or failing that
87 .BI /etc/authbind/byaddr/ addr : port
88 (IPv4 only)
89 is tested, in the same manner as above.  Here
90 .I addr
91 is as from
92 .BR inet_ntop ,
93 and
94 .I port
95 is the (local) TCP or UDP port number, expressed as an unsigned
96 integer in the minimal non-zero number of digits.
97 .PP
98 Thirdly, for IPv6 only: since the textual representation from
99 .B inet_ntop
100 is complicated to predict, a variant of
101 .I addr
102 is also tested which does not use the double colon abbreviation:
103 each 16-byte chunk expressed in the minimal nonzero number
104 of hex digits (i.e. with leading zeroes removed), the chunks
105 being separated by colons as is conventional.
106 .PP
107 Fourthly, if the question is still unresolved, the file
108 .BI /etc/authbind/byuid/ uid
109 will be opened and read.  If the file does not exist then the binding
110 is not authorised and
111 .B bind
112 will return
113 .B EPERM
114 .RI ( "Operation not permitted" ", or " "Not owner" ).
115 If the file does exist it will be searched for a line of the form
116 .nf
117 .IR             addrmin [\fB\-\fR addrmax ]\fB,\fR portmin [\fB\-\fR portmax ]
118 .IR             addr [\fB/\fR length ]\fB,\fR portmin [\fB\-\fR portmax ]
119 .IB             addr4 / length : portmin , portmax
120 .fi
121 matching the request.
122 The first form requires that the address lies in the
123 relevant range (inclusive at both ends).
124 The second and third forms require that the initial
125 .I length
126 bits of
127 .I addr
128 match those in the proposed
129 .B bind
130 call.  The third form is only available for IPv4 since IPv6 addresses
131 contain colons.
132 Addresses in the byuid file can
133 be in any form acceptable to inet_pton.  In all cases
134 the proposed port number must lie is in the inclusive range
135 specified.  If such a line is found then the binding is authorised.
136 Otherwise it is not, and
137 .B bind
138 will fail with
139 .B ENOENT
140 .RI ( "No such file or directory" ).
141 .PP
142 If a read error occurs, or the directory
143 .B /etc/authbind
144 cannot be accessed, then not only will
145 .B bind
146 fail, but an error message will be printed to stderr.  Unrecognised
147 lines in
148 .BI /etc/authbind/byuid/ uid
149 files are silently ignored, as are lines whose
150 .I addr
151 has non-zero bits more than
152 .I length
153 from the top or where some
154 .I min
155 is larger than
156 .IR max .
157 .SH EXAMPLE
158 So for example an attempt by uid 432
159 to bind to port 80 of address [2620:106:e002:f00f::21]
160 would result in authbind calling
161 .I access(2)
162 on, in order,
163 .RS
164 .B /etc/authbind/byport/80
165 .br
166 .B /etc/authbind/byaddr/2620:106:e002:f00f::21,80
167 .br
168 .B /etc/authbind/byaddr/2620:106:e002:f00f:0:0:0:21,80
169 .RE
170 If none of these files exist, authbind will read
171 .RS
172 .B /etc/authbind/byuid/432
173 .RE
174 and search for a line to permit
175 the relevant access; examples of lines which would do so are:
176 .RS
177 .B 2620:106:e002:f00f::21,80
178 .br
179 .B ::/0,80
180 .RE
181 .SH PORTS 512-1023
182 Authorising binding to ports from 512 to 1023 inclusive is
183 not recommended.  Some protocols (including some versions of NFS)
184 authorise clients by seeing that they are using a port number in this
185 range.  So by authorising a program to be a server for such a port,
186 you are also authorising it to impersonate the whole host for those
187 protocols.
188
189 To make sure that this isn't done by accident,
190 if the port number requested is in the range 512-1023, authbind
191 will expect the permission files to have an additional
192 .B !
193 at the start of their leafname.
194 .SH MECHANISM
195 The shared library loaded using
196 .B LD_PRELOAD
197 overrides the
198 .BR bind (2)
199 system call.  When a program invoked via
200 .B authbind
201 calls
202 .B bind
203 to bind a socket to a low-numbered TCP/IP port, and if the program
204 doesn't already have an effective uid of 0, the version of
205 .B bind
206 supposed by
207 .B authbind
208 forks and executes a setuid-root helper program.  For non-TCP/IP
209 sockets, high-numbered ports, or programs which are already root,
210 .B authbind
211 passes the call to the original
212 .BR bind (2)
213 system call, which is found using
214 .BR dlsym (3)
215 with the handle
216 .BR RTLD_NEXT .
217 .PP
218 .SH ERROR HANDLING
219 Usually the normal C error handling mechanisms apply.  If
220 .B authbind
221 cannot find the program it has been asked to execute it will print a
222 message to stderr and exit with code 255.
223 .PP
224 The helper program usually reports back to the shared library with an
225 exit status containing an
226 .B errno
227 value which encodes whether the
228 .B bind
229 was permitted and successful.  This will be returned to the calling
230 program in the usual way.
231 .PP
232 In the case of apparent configuration or other serious errors the
233 library and/or the helper program may cause messages to be printed to
234 the program's stderr, was well as returning -1 from
235 .BR bind .
236 .SH BUGS
237 .B authbind
238 currently only supports IPv4 and IPv6 sockets.
239 Programs which open other kinds
240 of sockets will not benefit from
241 .BR authbind ,
242 but it won't get in their way.
243 .PP
244 The use of
245 .B LD_PRELOAD
246 makes an
247 .B authbind
248 installation specific to a particular C library.  This version is for
249 GNU/Linux libc6 (glibc2).
250 .PP
251 .B authbind
252 may not operate correctly with multithreaded programs.  It is
253 inherently very difficult (if not impossible) to perform the kind of
254 trickery that authbind does while preventing all undesirable
255 interactions between authbind's activities and those of (say) a
256 threading runtime system.
257 .PP
258 It is quite possible that
259 .B authbind
260 and other programs and facilities which use
261 .B LD_PRELOAD
262 may interfere with each other, causing unpredictable behaviour or even
263 core dumps.
264 .B authbind
265 is known sometimes not to work correctly with
266 .BR fakeroot ,
267 for example (even supposing it could be determined what `correctly'
268 means in this context).
269 .PP
270 .B authbind
271 is ineffective with setuid programs, because they do not honour
272 .B LD_PRELOAD
273 references outside the system directories, for security reasons.  (In
274 fact, setuid programs should not honour
275 .B LD_PRELOAD
276 at all.)
277 Of course a setuid-root program does not need
278 .BR authbind ,
279 but it might be useful to apply it to program which are setuid to
280 another user or setgid.  If the author or builder of such a programs
281 wishes it to use authbind they could have it load the
282 .B libauthbind
283 library explicitly rather than via
284 .BR LD_PRELOAD .
285 .PP
286 Some programs may have trouble because
287 .B authbind
288 spawns a child process `under their feet', causing (for example) a
289 .BR fork (2)
290 to happen and
291 .B SIGCHLD
292 signal to be delivered.  Unfortunately the Unix API does not make
293 it possible to deal with this problem in a sane way.
294 .PP
295 The access control configuration scheme is somewhat strange.
296 .SH FILES AND ENVIRONMENT VARIABLES
297 .TP
298 .I /usr/lib/authbind/libauthbind.so.1.0
299 The shared library which
300 .B authbind
301 causes to be loaded using
302 .BR LD_PRELOAD ,
303 and which actually implements the diversion of
304 .BR bind (2)
305 to an external program.
306 .TP
307 .I LD_PRELOAD
308 The variable used by the dynamic linker when starting dynamically
309 linked programs and deciding which shared libraries to load and
310 modifed by the
311 .B authbind
312 program to allow it to override the usual meaning of
313 .BR bind (2) .
314 .TP
315 .I AUTHBIND_LIB
316 If set, forces
317 .B authbind
318 to use its value as the path to the shared library to put in
319 .BR LD_PRELOAD ,
320 instead of the compiled-in value.  In any case, unless
321 .B --deep
322 was specified,
323 .B authbind
324 will set this variable to the name of the library actually added to
325 .BR LD_PRELOAD ,
326 so that the library can find and remove the right entry.
327 .TP
328 .I AUTHBIND_LEVELS
329 This variable is set by
330 .B authbind
331 to the number of levels left from the
332 .B --depth
333 or
334 .B --deep
335 option, minus one.  It is decremented during
336 .B _init
337 by the library on each program call, and the library will remove
338 itself from the
339 .B LD_PRELOAD
340 when it reaches zero.  The special value
341 .B y
342 means
343 .B --deep
344 was specified.
345 .SH SEE ALSO
346 .BR bind (2),
347 .BR authbind\-helper (8),
348 .BR dlsym (3),
349 .BR ld.so (8)
350 .SH AUTHOR
351 .B authbind
352 and this manpage were written by Ian Jackson.  They are
353 Copyright (C)1998,2012
354 by him and released under the GNU General Public Licence; there is NO
355 WARRANTY.  See
356 .B /usr/doc/authbind/copyright
357 and
358 .B /usr/doc/copyright/GPL
359 for details.