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