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.