1 .\" Hey, Emacs! This is an -*- nroff -*- source file.
2 .\" Authors: Ian Jackson
4 .\" authbind is Copyright (C) 1998 Ian Jackson
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)
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.
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.
22 .TH AUTHBIND 1 "30th August 1998" "Debian Project" "Debian Linux manual"
24 authbind \- bind sockets to privileged ports without root
27 .RI [ options "] " program " [" argument " ...]"
30 allows a program which does not or should not run as root to bind to
31 low-numbered ports in a controlled way.
33 You must invoke the program using
34 .BR authbind ". " authbind
35 will set up some environment variables, including an
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
45 arranges for only the program which it directly invokes to be affected
46 by its special version of
50 then all programs which that program invokes directly or indirectly
51 will be affected, so long as they do not unset the environment
58 to affect programs which are
60 deep in the calling graph. The default is
63 Access to low numbered ports is controlled by permissions and contents
64 of files in a configuration area,
68 .BI /etc/authbind/byport/ port
69 is tested. If this file is accessible for execution to the calling
72 then binding to the port is authorised. If the file can be seen not
73 to exist (the existence check returns
75 then further tests will be used to find authorisation; otherwise,
76 binding is not authorised, and the
78 call will return with the
84 .RI ( "Permission denied" ).
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.
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
97 .RI ( "Operation not permitted" ", or " "Not owner" ).
98 If the file does exist it will be searched for a line of the form
100 .IB addr / length : min\-port , max\-port
102 matching the request (ie, the initial
106 match those in the proposed
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
114 .RI ( "No such file or directory" ).
119 is the (local) TCP or UDP port number, expressed as an unsigned
120 integer in the minimal non-zero number of digits, and
123 is the (local) IP address, as a dotted quad.
125 If a read error occurs, or the directory
127 cannot be accessed, then not only will
129 fail, but an error message will be printed to stderr. Unrecognised
131 .BI /etc/authbind/byuid/ uid
132 files are silently ignored (as are lines whose
134 has non-zero bits more than
138 The shared library loaded using
142 system call. When a program invoked via
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
151 forks and executes a setuid-root helper program. For non-TCP/IP
152 sockets, high-numbered ports, or programs which are already root,
154 passes the call to the original
156 system call, which is found using
162 Usually the normal C error handling mechanisms apply. If
164 cannot find the program it has been asked to execute it will print a
165 message to stderr and exit with code 255.
167 The helper program usually reports back to the shared library with an
168 exit status containing an
170 value which encodes whether the
172 was permitted and successful. This will be returned to the calling
173 program in the usual way.
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
181 currently only supports IPv4 sockets. Programs which open other kinds
182 of sockets will not benefit from
184 but it won't get in their way.
190 installation specific to a particular C library. This version is for
191 GNU/Linux libc6 (glibc2).
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.
200 It is quite possible that
202 and other programs and facilities which use
204 may interfere with each other, causing unpredictable behaviour or even
207 is known sometimes not to work correctly with
209 for example (even supposing it could be determined what `correctly'
210 means in this context).
213 is ineffective with setuid programs, because they do not honour
215 references outside the system directories, for security reasons. (In
216 fact, setuid programs should not honour
219 Of course a setuid-root program does not need
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
225 library explicitly rather than via
228 Some badly-written programs may have trouble because
230 spawns a child process `under their feet', causing (for example) a
234 signal to be delivered. Programs should not rely on standard
235 libraries not doing these things.
237 Ports from 512 to 1023 inclusive cannot be used with
239 because that would create a security hole, in conjection with
242 The access control configuration scheme is somewhat strange.
243 .SH FILES AND ENVIRONMENT VARIABLES
245 .I /usr/lib/authbind/libauthbind.so.1.0
246 The shared library which
248 causes to be loaded using
250 and which actually implements the diversion of
252 to an external program.
255 The variable used by the dynamic linker when starting dynamically
256 linked programs and deciding which shared libraries to load and
259 program to allow it to override the usual meaning of
265 to use its value as the path to the shared library to put in
267 instead of the compiled-in value. In any case, unless
271 will set this variable to the name of the library actually added to
273 so that the library can find and remove the right entry.
276 This variable is set by
278 to the number of levels left from the
282 option, minus one. It is decremented during
284 by the library on each program call, and the library will remove
287 when it reaches zero. The special value
294 .BR authbind\-helper (8),
299 and this manpage were written by Ian Jackson. They are
301 by him and released under the GNU General Public Licence; there is NO
303 .B /usr/doc/authbind/copyright
305 .B /usr/doc/copyright/GPL