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 .BI authbind " program"
  27 .RI [ 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 (<1024) ports if the system is configured to
  39 allow this.
  40 .SH ACCESS CONTROL
  41 Access to low numbered ports is controlled by permissions and contents
  42 of files in a configuration area,
  43 .BR /etc/authbind .
  44 .PP
  45 Firstly,
  46 .BI /etc/authbind/byport/ port
  47 is tested.  If this file is accessible for execution to the calling
  48 user, according to
  49 .BR access (2),
  50 then binding to the port is authorised.  If the file can be seen not
  51 to exist (the existence check returns
  52 .BR ENOENT )
  53 then further tests will be used to find authorisation; otherwise,
  54 binding is not authorised, and the
  55 .B bind
  56 call will return with the
  57 .B errno
  58 value from the
  59 .BR access (2)
  60 call, usually
  61 .B EACCES
  62 .RI ( "Permission denied" ).
  63 .PP
  64 Secondly, if that test fails to resolve the matter,
  65 .BI /etc/authbind/byaddr/ addr : port
  66 is tested, in the same manner as above.
  67 .PP
  68 Thirdly, if the question is still unresolved, the file
  69 .BI /etc/authbind/byuid/ uid
  70 will be opened and read.  If the file does not exist then the binding
  71 is not authorised and
  72 .B bind
  73 will return
  74 .B EPERM
  75 .RI ( "Operation not permitted" ", or " "Not owner" ).
  76 If the file does exist it will be searched for a line of the form
  77 .nf
  78 .IB             addr / length : min\-port , max\-port
  79 .fi
  80 matching the request (ie, the initial
  81 .I length
  82 bits of
  83 .I addr
  84 match those in the proposed
  85 .B bind
  86 call, and the proposed port number lies is in the inclusive range
  87 specified.  If such a line is found then the binding is authorised.
  88 Otherwise it is not, and
  89 .B bind
  90 will fail with
  91 .B ENOENT
  92 .RI ( "No such file or directory" ).
  93 .PP
  94 In each case above,
  95 .TP
  96 .I port
  97 is the (local) TCP or UDP port number, expressed as an unsigned
  98 integer in the minimal non-zero number of digits, and
  99 .TP
 100 .I addr
 101 is the (local) IP address, as a dotted quad.
 102 .PP
 103 If a read error occurs, or the directory
 104 .B /etc/authbind
 105 cannot be accessed, then not only will
 106 .B bind
 107 fail, but an error message will be printed to stderr.  Unrecognised
 108 lines in
 109 .BI /etc/authbind/byuid/ uid
 110 files are silently ignored (as are lines whose
 111 .I addr
 112 has non-zero bits more than
 113 .I length
 114 from the top).
 115 .SH MECHANISM
 116 The shared library loaded using
 117 .B LD_PRELOAD
 118 overrides the
 119 .BR bind (2)
 120 system call.  When a program invoked via
 121 .B authbind
 122 calls
 123 .B bind
 124 to bind a socket to a low-numbered TCP/IP port, and if the program
 125 doesn't already have an effective uid of 0, the version of
 126 .B bind
 127 supposed by
 128 .B authbind
 129 forks and executes a setuid-root helper program.  For non-TCP/IP
 130 sockets, high-numbered ports, or programs which are already root,
 131 .B authbind
 132 passes the call to the original
 133 .BR bind (2)
 134 system call, which is found using
 135 .BR dlsym (3)
 136 with the handle
 137 .BR RTLD_NEXT .
 138 .PP
 139 .SH ERROR HANDLING
 140 Usually the normal C error handling mechanisms apply.  If
 141 .B authbind
 142 cannot find the program it has been asked to execute it will print a
 143 message to stderr and exit with code 255.
 144 .PP
 145 The helper program usually reports back to the shared library with an
 146 exit status containing an
 147 .B errno
 148 value which encodes whether the
 149 .B bind
 150 was permitted and successful.  This will be returned to the calling
 151 program in the usual way.
 152 .PP
 153 In the case of apparent configuration or other serious errors the
 154 library and/or the helper program may cause messages to be printed to
 155 the program's stderr, was well as returning -1 from
 156 .BR bind .
 157 .SH BUGS
 158 .B authbind
 159 currently only supports IPv4 sockets.  Programs which open other kinds
 160 of sockets will not benefit from
 161 .BR authbind ,
 162 but it won't get in their way.
 163 .PP
 164 The use of
 165 .B LD_PRELOAD
 166 makes an
 167 .B authbind
 168 installation specific to a particular C library.  This version is for
 169 GNU/Linux libc6 (glibc2).
 170 .PP
 171 It is quite possible that
 172 .B authbind
 173 and other programs and facilities which use
 174 .B LD_PRELOAD
 175 may interfere with each other, causing unpredictable behaviour or even
 176 core dumps.
 177 .B authbind
 178 is known sometimes not to work correctly with
 179 .BR fakeroot ,
 180 for example (even supposing it could be determined what `correctly'
 181 means in this context).
 182 .PP
 183 .B authbind
 184 is ineffective with setuid programs, because they do not honour
 185 .B LD_PRELOAD
 186 for security reasons.  Of course a setuid-root program does not need
 187 .BR authbind ,
 188 but it might be useful to apply it to program which are setuid to
 189 another user or setgid.  If the author or builder of such a programs
 190 wishes it to use authbind they could have it load the
 191 .B libauthbind
 192 library explicitly rather than via
 193 .BR LD_PRELOAD .
 194 .PP
 195 Some badly-written programs may have trouble because
 196 .B authbind
 197 spawns a child process `under their feet', causing (for example) a
 198 .BR fork (2)
 199 to happen and
 200 .B SIGCHLD
 201 signal to be delivered.  Programs should not rely on standard
 202 libraries not doing these things.
 203 .PP
 204 The access control configuration scheme is somewhat strange.
 205 .SH FILES AND ENVIRONMENT VARIABLES
 206 .TP
 207 .I /usr/lib/authbind/libauthbind.so.1.0
 208 The shared library which
 209 .B authbind
 210 causes to be loaded using
 211 .BR LD_PRELOAD ,
 212 and which actually implements the diversion of
 213 .BR bind (2)
 214 to an external program.
 215 .TP
 216 .I LD_PRELOAD
 217 The variable used by the dynamic linker when starting dynamically
 218 linked programs and deciding which shared libraries to load and
 219 modifed by the
 220 .B authbind
 221 program to allow it to override the usual meaning of
 222 .BR bind (2) .
 223 .TP
 224 .I AUTHBIND_LIB
 225 If set, forces
 226 .B authbind
 227 to use its value as the path to the shared library to put in
 228 .BR LD_PRELOAD ,
 229 instead of the compiled-in value.
 230 .TP
 231 .I AUTHBIND_NESTED
 232 Do not set this variable.  It is set to
 233 .B 1
 234 by
 235 .B libauthbind
 236 when it invokes the helper program.  This allows detection of the
 237 situation where the helper has not been installed setuid, which would
 238 otherwise lead to infinite recursion.
 239 .SH SEE ALSO
 240 .BR bind (2),
 241 .BR authbind\-helper (8),
 242 .BR dlsym (3),
 243 .BR ld.so (8)
 244 .SH AUTHOR
 245 .B authbind
 246 and this manpage were written by Ian Jackson.  They are
 247 Copyright (C)1998
 248 by him and released under the GNU General Public Licence; there is NO
 249 WARRANTY.  See
 250 .B /usr/doc/authbind/copyright
 251 and
 252 .B /usr/doc/copyright/GPL
 253 for details.