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