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