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.