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 .BR /etc/authbind/byport/ [ ! ]\fIport\fR
  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 .BR /etc/authbind/byaddr/ \fIaddr\fR : [ ! ]\fIport\fR
  88 is tested, in the same manner as above.
  89 .PP
  90 Thirdly, if the question is still unresolved, the file
  91 .BR /etc/authbind/byuid/ [ ! ]\fIuid\fR
  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             addr4 / length : min\-port , max\-port
 101 .IR             addrmin [\fB-\fR addrmax ]\fB:\fR min\-port \fB,\fR max\-port
 102 .fi
 103 matching the request.   The first form requires that the initial
 104 .I length
 105 bits of
 106 .I addr
 107 match those in the proposed
 108 .B bind
 109 call.  The second form requires that the address lies in the
 110 relevant range (inclusive at both ends).  Addresses can
 111 be in any form acceptable to inet_pton.  In both cases
 112 the proposed port number must lie is in the inclusive range
 113 specified.  If such a line is found then the binding is authorised.
 114 Otherwise it is not, and
 115 .B bind
 116 will fail with
 117 .B ENOENT
 118 .RI ( "No such file or directory" ).
 119 .PP
 120 In each case above,
 121 .TP
 122 .I port
 123 is the (local) TCP or UDP port number, expressed as an unsigned
 124 integer in the minimal non-zero number of digits, and
 125 .TP
 126 .I addr
 127 is the (local) IP address, as a dotted quad.
 128 .PP
 129 If a read error occurs, or the directory
 130 .B /etc/authbind
 131 cannot be accessed, then not only will
 132 .B bind
 133 fail, but an error message will be printed to stderr.  Unrecognised
 134 lines in
 135 .BI /etc/authbind/byuid/ uid
 136 files are silently ignored (as are lines whose
 137 .I addr
 138 has non-zero bits more than
 139 .I length
 140 from the top).
 141 .TP
 142 Authorising binding to ports from 512 to 1023 inclusive is
 143 not recommended.  Some protocols (including some versions of NFS)
 144 authorise clients by seeing that they are using a port number in this
 145 range.  So by authorising a program to be a server for such a port,
 146 you are also authorising it to impersonate the whole host for those
 147 protocols.  To make sure that this isn't done by accident,
 148 if the port number requested is in the range 512-1023, all the files
 149 checked and read will have the additional
 150 .B !
 151 character.
 152 .SH MECHANISM
 153 The shared library loaded using
 154 .B LD_PRELOAD
 155 overrides the
 156 .BR bind (2)
 157 system call.  When a program invoked via
 158 .B authbind
 159 calls
 160 .B bind
 161 to bind a socket to a low-numbered TCP/IP port, and if the program
 162 doesn't already have an effective uid of 0, the version of
 163 .B bind
 164 supposed by
 165 .B authbind
 166 forks and executes a setuid-root helper program.  For non-TCP/IP
 167 sockets, high-numbered ports, or programs which are already root,
 168 .B authbind
 169 passes the call to the original
 170 .BR bind (2)
 171 system call, which is found using
 172 .BR dlsym (3)
 173 with the handle
 174 .BR RTLD_NEXT .
 175 .PP
 176 .SH ERROR HANDLING
 177 Usually the normal C error handling mechanisms apply.  If
 178 .B authbind
 179 cannot find the program it has been asked to execute it will print a
 180 message to stderr and exit with code 255.
 181 .PP
 182 The helper program usually reports back to the shared library with an
 183 exit status containing an
 184 .B errno
 185 value which encodes whether the
 186 .B bind
 187 was permitted and successful.  This will be returned to the calling
 188 program in the usual way.
 189 .PP
 190 In the case of apparent configuration or other serious errors the
 191 library and/or the helper program may cause messages to be printed to
 192 the program's stderr, was well as returning -1 from
 193 .BR bind .
 194 .SH BUGS
 195 .B authbind
 196 currently only supports IPv4 and IPv6 sockets.
 197 Programs which open other kinds
 198 of sockets will not benefit from
 199 .BR authbind ,
 200 but it won't get in their way.
 201 .PP
 202 The use of
 203 .B LD_PRELOAD
 204 makes an
 205 .B authbind
 206 installation specific to a particular C library.  This version is for
 207 GNU/Linux libc6 (glibc2).
 208 .PP
 209 .B authbind
 210 may not operate correctly with multithreaded programs.  It is
 211 inherently very difficult (if not impossible) to perform the kind of
 212 trickery that authbind does while preventing all undesirable
 213 interactions between authbind's activities and those of (say) a
 214 threading runtime system.
 215 .PP
 216 It is quite possible that
 217 .B authbind
 218 and other programs and facilities which use
 219 .B LD_PRELOAD
 220 may interfere with each other, causing unpredictable behaviour or even
 221 core dumps.
 222 .B authbind
 223 is known sometimes not to work correctly with
 224 .BR fakeroot ,
 225 for example (even supposing it could be determined what `correctly'
 226 means in this context).
 227 .PP
 228 .B authbind
 229 is ineffective with setuid programs, because they do not honour
 230 .B LD_PRELOAD
 231 references outside the system directories, for security reasons.  (In
 232 fact, setuid programs should not honour
 233 .B LD_PRELOAD
 234 at all.)
 235 Of course a setuid-root program does not need
 236 .BR authbind ,
 237 but it might be useful to apply it to program which are setuid to
 238 another user or setgid.  If the author or builder of such a programs
 239 wishes it to use authbind they could have it load the
 240 .B libauthbind
 241 library explicitly rather than via
 242 .BR LD_PRELOAD .
 243 .PP
 244 Some badly-written programs may have trouble because
 245 .B authbind
 246 spawns a child process `under their feet', causing (for example) a
 247 .BR fork (2)
 248 to happen and
 249 .B SIGCHLD
 250 signal to be delivered.  Programs should not rely on standard
 251 libraries not doing these things.
 252 .PP
 253 The access control configuration scheme is somewhat strange.
 254 .SH FILES AND ENVIRONMENT VARIABLES
 255 .TP
 256 .I /usr/lib/authbind/libauthbind.so.1.0
 257 The shared library which
 258 .B authbind
 259 causes to be loaded using
 260 .BR LD_PRELOAD ,
 261 and which actually implements the diversion of
 262 .BR bind (2)
 263 to an external program.
 264 .TP
 265 .I LD_PRELOAD
 266 The variable used by the dynamic linker when starting dynamically
 267 linked programs and deciding which shared libraries to load and
 268 modifed by the
 269 .B authbind
 270 program to allow it to override the usual meaning of
 271 .BR bind (2) .
 272 .TP
 273 .I AUTHBIND_LIB
 274 If set, forces
 275 .B authbind
 276 to use its value as the path to the shared library to put in
 277 .BR LD_PRELOAD ,
 278 instead of the compiled-in value.  In any case, unless
 279 .B --deep
 280 was specified,
 281 .B authbind
 282 will set this variable to the name of the library actually added to
 283 .BR LD_PRELOAD ,
 284 so that the library can find and remove the right entry.
 285 .TP
 286 .I AUTHBIND_LEVELS
 287 This variable is set by
 288 .B authbind
 289 to the number of levels left from the
 290 .B --depth
 291 or
 292 .B --deep
 293 option, minus one.  It is decremented during
 294 .B _init
 295 by the library on each program call, and the library will remove
 296 itself from the
 297 .B LD_PRELOAD
 298 when it reaches zero.  The special value
 299 .B y
 300 means
 301 .B --deep
 302 was specified.
 303 .SH SEE ALSO
 304 .BR bind (2),
 305 .BR authbind\-helper (8),
 306 .BR dlsym (3),
 307 .BR ld.so (8)
 308 .SH AUTHOR
 309 .B authbind
 310 and this manpage were written by Ian Jackson.  They are
 311 Copyright (C)1998
 312 by him and released under the GNU General Public Licence; there is NO
 313 WARRANTY.  See
 314 .B /usr/doc/authbind/copyright
 315 and
 316 .B /usr/doc/copyright/GPL
 317 for details.