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.