authbind source

AUTHBIND(1)                    Debian Linux manual                   AUTHBIND(1)



NAME
       authbind - bind sockets to privileged ports without root

SYNOPSIS
       authbind [options] program [argument ...]

DESCRIPTION
       authbind  allows  a  program  which does not or should not run as root to
       bind to low-numbered ports in a controlled way.

       You must invoke the program using authbind.  authbind will  set  up  some
       environment  variables,  including  an  LD_PRELOAD,  which will allow the
       program (including any subprocesses it may run) to bind  to  low-numbered
       (<512) ports if the system is configured to allow this.

OPTIONS
       --deep Normally, authbind arranges for only the program which it directly
              invokes to be affected by its special version of bind(2).  If  you
              specify  --deep  then  all  programs  which  that  program invokes
              directly or indirectly will be affected, so long as  they  do  not
              unset the environment variables set up by authbind.

       --depth levels
              Causes  authbind  to  affect programs which are levels deep in the
              calling graph.  The default is --depth 1.

ACCESS CONTROL
       Access to low numbered ports is controlled by permissions and contents of
       files in a configuration area, /etc/authbind.

       Firstly, /etc/authbind/byport/port is tested.  If this file is accessible
       for execution to the calling user, according to access(2),  then  binding
       to  the  port  is  authorised.  If the file can be seen not to exist (the
       existence check returns ENOENT) then further tests will be used  to  find
       authorisation;  otherwise,  binding  is not authorised, and the bind call
       will return with the errno value from the access(2) call, usually  EACCES
       (Permission denied).

       Secondly,    if    that    test    fails    to    resolve   the   matter,
       /etc/authbind/byaddr/addr,port   (any   protocol)   or    failing    that
       /etc/authbind/byaddr/addr:port  (IPv4 only) is tested, in the same manner
       as above.  Here addr is as from inet_ntop, and port is the (local) TCP or
       UDP port number, expressed as an unsigned integer in the minimal non-zero
       number of digits.

       Thirdly, for IPv6 only: since the textual representation  from  inet_ntop
       is  complicated  to  predict, a variant of addr is also tested which does
       not use the double colon abbreviation: each 16-byte  chunk  expressed  in
       the  minimal  nonzero  number  of  hex  digits  (i.e. with leading zeroes
       removed), the chunks being separated by colons as is conventional.

       Fourthly,   if   the   question   is   still   unresolved,    the    file
       /etc/authbind/byuid/uid  will  be  opened and read.  If the file does not
       exist then the binding is not  authorised  and  bind  will  return  EPERM
       (Operation  not permitted, or Not owner).  If the file does exist it will
       be searched for a line of the form
            addrmin[-addrmax],portmin[-portmax]
            addr[/length],portmin[-portmax]
            addr4/length:portmin,portmax
       matching the request.  The first form requires that the address  lies  in
       the  relevant range (inclusive at both ends).  The second and third forms
       require that the initial length bits of addr match those in the  proposed
       bind  call.   The  third  form  is  only  available  for  IPv4 since IPv6
       addresses contain colons.  Addresses in the byuid file can be in any form
       acceptable  to inet_pton.  In all cases the proposed port number must lie
       is in the inclusive range specified.  If such a line is  found  then  the
       binding  is  authorised.   Otherwise  it  is not, and bind will fail with
       ENOENT (No such file or directory).

       If a  read  error  occurs,  or  the  directory  /etc/authbind  cannot  be
       accessed,  then  not  only  will  bind fail, but an error message will be
       printed to stderr.  Unrecognised lines in  /etc/authbind/byuid/uid  files
       are silently ignored, as are lines whose addr has non-zero bits more than
       length from the top or where some min is larger than max.

EXAMPLE
       So for example an attempt by uid 432  to  bind  to  port  80  of  address
       [2620:106:e002:f00f::21]  would  result in authbind calling access(2) on,
       in order,
              /etc/authbind/byport/80
              /etc/authbind/byaddr/2620:106:e002:f00f::21,80
              /etc/authbind/byaddr/2620:106:e002:f00f:0:0:0:21,80
       If none of these files exist, authbind will read
              /etc/authbind/byuid/432
       and search for a line to permit the relevant access;  examples  of  lines
       which would do so are:
              2620:106:e002:f00f::21,80
              ::/0,80

PORTS 512-1023
       Authorising   binding  to  ports  from  512  to  1023  inclusive  is  not
       recommended.  Some protocols (including some versions of  NFS)  authorise
       clients by seeing that they are using a port number in this range.  So by
       authorising a program to be a server  for  such  a  port,  you  are  also
       authorising it to impersonate the whole host for those protocols.

       To  make  sure  that  this  isn't  done  by  accident, if the port number
       requested is in the range 512-1023, authbind will expect  the  permission
       files to have an additional !  at the start of their leafname.

MECHANISM
       The  shared  library loaded using LD_PRELOAD overrides the bind(2) system
       call.  When a program invoked via authbind calls bind to bind a socket to
       a  low-numbered  TCP/IP  port, and if the program doesn't already have an
       effective uid of 0, the version of bind supposed by  authbind  forks  and
       executes  a  setuid-root  helper  program.  For non-TCP/IP sockets, high-
       numbered ports, or programs which are already root, authbind  passes  the
       call  to  the original bind(2) system call, which is found using dlsym(3)
       with the handle RTLD_NEXT.

ERROR HANDLING
       Usually the normal C error handling mechanisms apply.  If authbind cannot
       find  the program it has been asked to execute it will print a message to
       stderr and exit with code 255.

       The helper program usually reports back to the  shared  library  with  an
       exit  status containing an errno value which encodes whether the bind was
       permitted and successful.  This will be returned to the  calling  program
       in the usual way.

       In the case of apparent configuration or other serious errors the library
       and/or the helper program  may  cause  messages  to  be  printed  to  the
       program's stderr, was well as returning -1 from bind.

BUGS
       authbind  currently  only supports IPv4 and IPv6 sockets.  Programs which
       open other kinds of sockets will not benefit from authbind, but it  won't
       get in their way.

       The  use  of  LD_PRELOAD  makes  an  authbind  installation specific to a
       particular C library.  This version is for GNU/Linux libc6 (glibc2).

       authbind may not operate correctly with multithreaded  programs.   It  is
       inherently  very  difficult  (if  not  impossible) to perform the kind of
       trickery that authbind does while preventing all undesirable interactions
       between  authbind's  activities  and  those  of (say) a threading runtime
       system.

       It is quite possible that authbind  and  other  programs  and  facilities
       which use LD_PRELOAD may interfere with each other, causing unpredictable
       behaviour or even core dumps.  authbind is known sometimes  not  to  work
       correctly  with  fakeroot,  for  example  (even  supposing  it  could  be
       determined what `correctly' means in this context).

       authbind is ineffective with setuid programs, because they do not  honour
       LD_PRELOAD  references  outside  the  system  directories,  for  security
       reasons.  (In fact, setuid programs should not honour LD_PRELOAD at all.)
       Of  course  a setuid-root program does not need authbind, but it might be
       useful to apply it to program which are setuid to another user or setgid.
       If  the  author  or  builder of such a programs wishes it to use authbind
       they could have it load the libauthbind library  explicitly  rather  than
       via LD_PRELOAD.

       Some  programs  may  have trouble because authbind spawns a child process
       `under their feet', causing (for example) a fork(2) to happen and SIGCHLD
       signal  to  be  delivered.   Unfortunately  the Unix API does not make it
       possible to deal with this problem in a sane way.

       The access control configuration scheme is somewhat strange.

FILES AND ENVIRONMENT VARIABLES
       /usr/lib/authbind/libauthbind.so.1.0
              The shared library  which  authbind  causes  to  be  loaded  using
              LD_PRELOAD, and which actually implements the diversion of bind(2)
              to an external program.

       LD_PRELOAD
              The variable used by the dynamic linker when starting  dynamically
              linked  programs  and  deciding which shared libraries to load and
              modifed by the authbind program to allow it to override the  usual
              meaning of bind(2).

       AUTHBIND_LIB
              If set, forces authbind to use its value as the path to the shared
              library to put in LD_PRELOAD, instead of  the  compiled-in  value.
              In  any  case, unless --deep was specified, authbind will set this
              variable to the name of the library actually added to  LD_PRELOAD,
              so that the library can find and remove the right entry.

       AUTHBIND_LEVELS
              This variable is set by authbind to the number of levels left from
              the --depth or --deep option, minus one.  It is decremented during
              _init  by  the  library on each program call, and the library will
              remove itself from the  LD_PRELOAD  when  it  reaches  zero.   The
              special value y means --deep was specified.

SEE ALSO
       bind(2), authbind-helper(8), dlsym(3), ld.so(8)

AUTHOR
       authbind  and  this  manpage  were  written  by  Ian  Jackson.   They are
       Copyright (C)1998,2012 by him and released under the GNU  General  Public
       Licence;  there  is  NO  WARRANTY.   See  /usr/doc/authbind/copyright and
       /usr/doc/copyright/GPL for details.



Debian Project                  30th August 1998                     AUTHBIND(1)

Locations of this man page

SystemPackageVersionNameFilename
Debian 7.0utils/authbind2.1.1authbind.1/usr/share/man/man1/authbind.1.gz
Ubuntu 14.10utils/authbind2.1.1authbind.1/usr/share/man/man1/authbind.1.gz
Ubuntu 14.04utils/authbind2.1.1authbind.1/usr/share/man/man1/authbind.1.gz
Ubuntu 13.10utils/authbind2.1.1authbind.1/usr/share/man/man1/authbind.1.gz
Ubuntu 13.04utils/authbind2.1.1authbind.1/usr/share/man/man1/authbind.1.gz
Ubuntu 12.10utils/authbind2.1.1authbind.1/usr/share/man/man1/authbind.1.gz