.\" Hey, Emacs!  This is an -*- nroff -*- source file.
.\" Authors: Ian Jackson
.\" 
.\" authbind is Copyright (C) 1998 Ian Jackson
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2, or (at your option)
.\" any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 
.\"
.TH AUTHBIND 1 "30th August 1998" "Debian Project" "Debian Linux manual"
.SH NAME 
authbind \- bind sockets to privileged ports without root
.SH SYNOPSIS
.BR authbind
.RI [ options "] " program " [" argument " ...]"
.SH DESCRIPTION
.B authbind
allows a program which does not or should not run as root to bind to
low-numbered ports in a controlled way.
.PP
You must invoke the program using
.BR authbind ".  " authbind
will set up some environment variables, including an
.BR 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.
.SH OPTIONS
.TP
.B --deep
Normally,
.B authbind
arranges for only the program which it directly invokes to be affected
by its special version of
.BR bind (2).
If you specify
.B --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
.BR authbind .
.TP
.BI --depth " levels"
Causes
.B authbind
to affect programs which are
.I levels
deep in the calling graph.  The default is
.BR "--depth 1" .
.SH ACCESS CONTROL
Access to low numbered ports is controlled by permissions and contents
of files in a configuration area,
.BR /etc/authbind .
.PP
Firstly,
.BI /etc/authbind/byport/ port
is tested.  If this file is accessible for execution to the calling
user, according to
.BR access (2),
then binding to the port is authorised.  If the file can be seen not
to exist (the existence check returns
.BR ENOENT )
then further tests will be used to find authorisation; otherwise,
binding is not authorised, and the
.B bind
call will return with the
.B errno
value from the
.BR access (2)
call, usually
.B EACCES
.RI ( "Permission denied" ).
.PP
Secondly, if that test fails to resolve the matter,
.BI /etc/authbind/byaddr/ addr , port
(any protocol) or failing that
.BI /etc/authbind/byaddr/ addr : port
(IPv4 only)
is tested, in the same manner as above.  Here
.I addr
is as from
.BR inet_ntop ,
and
.I port
is the (local) TCP or UDP port number, expressed as an unsigned
integer in the minimal non-zero number of digits.
.PP
Thirdly, for IPv6 only: since the textual representation from
.B inet_ntop
is complicated to predict, a variant of
.I 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.
.PP
Fourthly, if the question is still unresolved, the file
.BI /etc/authbind/byuid/ uid
will be opened and read.  If the file does not exist then the binding
is not authorised and
.B bind
will return
.B EPERM
.RI ( "Operation not permitted" ", or " "Not owner" ).
If the file does exist it will be searched for a line of the form
.nf
.IR		addrmin [\fB\-\fR addrmax ]\fB,\fR portmin [\fB\-\fR portmax ]
.IR		addr [\fB/\fR length ]\fB,\fR portmin [\fB\-\fR portmax ]
.IB		addr4 / length : portmin , portmax
.fi
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
.I length
bits of
.I addr
match those in the proposed
.B 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
.B bind
will fail with
.B ENOENT
.RI ( "No such file or directory" ).
.PP
If a read error occurs, or the directory
.B /etc/authbind
cannot be accessed, then not only will
.B bind
fail, but an error message will be printed to stderr.  Unrecognised
lines in
.BI /etc/authbind/byuid/ uid
files are silently ignored, as are lines whose
.I addr
has non-zero bits more than
.I length
from the top or where some
.I min
is larger than
.IR max .
.SH 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
.I access(2)
on, in order,
.RS
.B /etc/authbind/byport/80
.br
.B /etc/authbind/byaddr/2620:106:e002:f00f::21,80
.br
.B /etc/authbind/byaddr/2620:106:e002:f00f:0:0:0:21,80
.RE
If none of these files exist, authbind will read
.RS
.B /etc/authbind/byuid/432
.RE
and search for a line to permit
the relevant access; examples of lines which would do so are:
.RS
.B 2620:106:e002:f00f::21,80
.br
.B ::/0,80
.RE
.SH 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
.B !
at the start of their leafname.
.SH MECHANISM
The shared library loaded using
.B LD_PRELOAD
overrides the
.BR bind (2)
system call.  When a program invoked via
.B authbind
calls
.B 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
.B bind
supposed by
.B authbind
forks and executes a setuid-root helper program.  For non-TCP/IP
sockets, high-numbered ports, or programs which are already root,
.B authbind
passes the call to the original
.BR bind (2)
system call, which is found using
.BR dlsym (3)
with the handle
.BR RTLD_NEXT .
.PP
.SH ERROR HANDLING
Usually the normal C error handling mechanisms apply.  If
.B authbind
cannot find the program it has been asked to execute it will print a
message to stderr and exit with code 255.
.PP
The helper program usually reports back to the shared library with an
exit status containing an
.B errno
value which encodes whether the
.B bind
was permitted and successful.  This will be returned to the calling
program in the usual way.
.PP
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
.BR bind .
.SH BUGS
.B authbind
currently only supports IPv4 and IPv6 sockets.
Programs which open other kinds
of sockets will not benefit from
.BR authbind ,
but it won't get in their way.
.PP
The use of
.B LD_PRELOAD
makes an
.B authbind
installation specific to a particular C library.  This version is for
GNU/Linux libc6 (glibc2).
.PP
.B 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.
.PP
It is quite possible that
.B authbind
and other programs and facilities which use
.B LD_PRELOAD
may interfere with each other, causing unpredictable behaviour or even
core dumps.
.B authbind
is known sometimes not to work correctly with
.BR fakeroot ,
for example (even supposing it could be determined what `correctly'
means in this context).
.PP
.B authbind
is ineffective with setuid programs, because they do not honour
.B LD_PRELOAD
references outside the system directories, for security reasons.  (In
fact, setuid programs should not honour
.B LD_PRELOAD
at all.)
Of course a setuid-root program does not need
.BR 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
.B libauthbind
library explicitly rather than via
.BR LD_PRELOAD .
.PP
Some programs may have trouble because
.B authbind
spawns a child process `under their feet', causing (for example) a
.BR fork (2)
to happen and
.B SIGCHLD
signal to be delivered.  Unfortunately the Unix API does not make
it possible to deal with this problem in a sane way.
.PP
The access control configuration scheme is somewhat strange.
.SH FILES AND ENVIRONMENT VARIABLES
.TP
.I /usr/lib/authbind/libauthbind.so.1.0
The shared library which
.B authbind
causes to be loaded using
.BR LD_PRELOAD ,
and which actually implements the diversion of
.BR bind (2)
to an external program.
.TP
.I 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
.B authbind
program to allow it to override the usual meaning of
.BR bind (2) .
.TP
.I AUTHBIND_LIB
If set, forces
.B authbind
to use its value as the path to the shared library to put in
.BR LD_PRELOAD ,
instead of the compiled-in value.  In any case, unless
.B --deep
was specified,
.B authbind
will set this variable to the name of the library actually added to
.BR LD_PRELOAD ,
so that the library can find and remove the right entry.
.TP
.I AUTHBIND_LEVELS
This variable is set by
.B authbind
to the number of levels left from the
.B --depth
or
.B --deep
option, minus one.  It is decremented during
.B _init
by the library on each program call, and the library will remove
itself from the
.B LD_PRELOAD
when it reaches zero.  The special value
.B y
means
.B --deep
was specified.
.SH SEE ALSO
.BR bind (2),
.BR authbind\-helper (8),
.BR dlsym (3),
.BR ld.so (8)
.SH AUTHOR
.B 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
.B /usr/doc/authbind/copyright
and
.B /usr/doc/copyright/GPL
for details.