MAN page from openSUSE Leap 42 authbind-2.1.1-2.1.x86_64.rpm

AUTHBIND

Section: Debian Linux manual (1)
Updated: 30th August 1998
Index

NAME

authbind - bind sockets to privileged ports without root

SYNOPSIS

authbind[options] program [argument ...]

DESCRIPTION

authbindallows a program which does not or should not run as root to bind tolow-numbered ports in a controlled way.

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

OPTIONS

--deep: Normally,authbindarranges for only the program which it directly invokes to be affectedby its special version ofbind(2).If you specify--deepthen all programs which that program invokes directly or indirectlywill be affected, so long as they do not unset the environmentvariables set up byauthbind.
--depth levels: Causesauthbindto affect programs which arelevelsdeep in the calling graph. The default is--depth 1.

ACCESS CONTROL

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

Firstly,/etc/authbind/byport/portis tested. If this file is accessible for execution to the callinguser, according toaccess(2),then binding to the port is authorised. If the file can be seen notto exist (the existence check returnsENOENT)then further tests will be used to find authorisation; otherwise,binding is not authorised, and thebindcall will return with theerrnovalue from theaccess(2)call, usuallyEACCES(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. Hereaddris as frominet_ntop,andportis the (local) TCP or UDP port number, expressed as an unsignedinteger in the minimal non-zero number of digits.

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

Fourthly, if the question is still unresolved, the file/etc/authbind/byuid/uidwill be opened and read. If the file does not exist then the bindingis not authorised andbindwill returnEPERM(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 therelevant range (inclusive at both ends).The second and third forms require that the initiallengthbits ofaddrmatch those in the proposedbindcall. The third form is only available for IPv4 since IPv6 addressescontain colons.Addresses in the byuid file canbe in any form acceptable to inet_pton. In all casesthe proposed port number must lie is in the inclusive rangespecified. If such a line is found then the binding is authorised.Otherwise it is not, andbindwill fail withENOENT(No such file or directory).

If a read error occurs, or the directory/etc/authbindcannot be accessed, then not only willbindfail, but an error message will be printed to stderr. Unrecognisedlines in/etc/authbind/byuid/uidfiles are silently ignored, as are lines whoseaddrhas non-zero bits more thanlengthfrom the top or where someminis larger thanmax.

EXAMPLE

So for example an attempt by uid 432to bind to port 80 of address [2620:106:e002:f00f::21]would result in authbind callingaccess(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 permitthe 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 isnot recommended. Some protocols (including some versions of NFS)authorise clients by seeing that they are using a port number in thisrange. So by authorising a program to be a server for such a port,you are also authorising it to impersonate the whole host for thoseprotocols.

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

MECHANISM

The shared library loaded usingLD_PRELOADoverrides thebind(2)system call. When a program invoked viaauthbindcallsbindto bind a socket to a low-numbered TCP/IP port, and if the programdoesn't already have an effective uid of 0, the version ofbindsupposed byauthbindforks and executes a setuid-root helper program. For non-TCP/IPsockets, high-numbered ports, or programs which are already root,authbindpasses the call to the originalbind(2)system call, which is found usingdlsym(3)with the handleRTLD_NEXT.

ERROR HANDLING

Usually the normal C error handling mechanisms apply. Ifauthbindcannot find the program it has been asked to execute it will print amessage to stderr and exit with code 255.

The helper program usually reports back to the shared library with anexit status containing anerrnovalue which encodes whether thebindwas permitted and successful. This will be returned to the callingprogram in the usual way.

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

BUGS

authbindcurrently only supports IPv4 and IPv6 sockets.Programs which open other kindsof sockets will not benefit fromauthbind,but it won't get in their way.

The use ofLD_PRELOADmakes anauthbindinstallation specific to a particular C library. This version is forGNU/Linux libc6 (glibc2).

authbindmay not operate correctly with multithreaded programs. It isinherently very difficult (if not impossible) to perform the kind oftrickery that authbind does while preventing all undesirableinteractions between authbind's activities and those of (say) athreading runtime system.

It is quite possible thatauthbindand other programs and facilities which useLD_PRELOADmay interfere with each other, causing unpredictable behaviour or evencore dumps.authbindis known sometimes not to work correctly withfakeroot,for example (even supposing it could be determined what `correctly'means in this context).

authbindis ineffective with setuid programs, because they do not honourLD_PRELOADreferences outside the system directories, for security reasons. (Infact, setuid programs should not honourLD_PRELOADat all.)Of course a setuid-root program does not needauthbind,but it might be useful to apply it to program which are setuid toanother user or setgid. If the author or builder of such a programswishes it to use authbind they could have it load thelibauthbindlibrary explicitly rather than viaLD_PRELOAD.

Some programs may have trouble becauseauthbindspawns a child process `under their feet', causing (for example) afork(2)to happen andSIGCHLDsignal to be delivered. Unfortunately the Unix API does not makeit 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 whichauthbindcauses to be loaded usingLD_PRELOAD,and which actually implements the diversion ofbind(2)to an external program.
LD_PRELOAD: The variable used by the dynamic linker when starting dynamicallylinked programs and deciding which shared libraries to load andmodifed by theauthbindprogram to allow it to override the usual meaning ofbind(2).
AUTHBIND_LIB: If set, forcesauthbindto use its value as the path to the shared library to put inLD_PRELOAD,instead of the compiled-in value. In any case, unless--deepwas specified,authbindwill set this variable to the name of the library actually added toLD_PRELOAD,so that the library can find and remove the right entry.
AUTHBIND_LEVELS: This variable is set byauthbindto the number of levels left from the--depthor--deepoption, minus one. It is decremented during_initby the library on each program call, and the library will removeitself from theLD_PRELOADwhen it reaches zero. The special valueymeans--deepwas specified.

AUTHOR

authbindand this manpage were written by Ian Jackson. They areCopyright (C)1998,2012by him and released under the GNU General Public Licence; there is NOWARRANTY. See/usr/doc/authbind/copyrightand/usr/doc/copyright/GPLfor details.

This document was created byman2html,using the manual pages.