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