chiark / gitweb /
finalise 2.1.2
[authbind.git] / authbind.1
index a7bb5b5..d73e998 100644 (file)
 .\" along with this program; if not, write to the Free Software Foundation,
 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 
 .\"
-.\" $Id$
-.\"
 .TH AUTHBIND 1 "30th August 1998" "Debian Project" "Debian Linux manual"
 .SH NAME 
 authbind \- bind sockets to privileged ports without root
 .SH SYNOPSIS
-.BI authbind " program"
-.RI [ argument " ...]"
+.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
@@ -37,6 +35,28 @@ will set up some environment variables, including an
 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,
@@ -62,10 +82,29 @@ call, usually
 .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
-is tested, in the same manner as above.
+(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
-Thirdly, if the question is still unresolved, the file
+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
@@ -75,15 +114,24 @@ will return
 .RI ( "Operation not permitted" ", or " "Not owner" ).
 If the file does exist it will be searched for a line of the form
 .nf
-.IB            addr / length : min\-port , max\-port
+.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 (ie, the initial
+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, and the proposed port number lies is in the inclusive range
+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
@@ -91,15 +139,6 @@ will fail with
 .B ENOENT
 .RI ( "No such file or directory" ).
 .PP
-In each case above,
-.TP
-.I port
-is the (local) TCP or UDP port number, expressed as an unsigned
-integer in the minimal non-zero number of digits, and
-.TP
-.I addr
-is the (local) IP address, as a dotted quad.
-.PP
 If a read error occurs, or the directory
 .B /etc/authbind
 cannot be accessed, then not only will
@@ -107,11 +146,51 @@ cannot be accessed, then not only will
 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
+files are silently ignoredas are lines whose
 .I addr
 has non-zero bits more than
 .I length
-from the top).
+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
@@ -156,7 +235,8 @@ the program's stderr, was well as returning -1 from
 .BR bind .
 .SH BUGS
 .B authbind
-currently only supports IPv4 sockets.  Programs which open other kinds
+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.
@@ -168,6 +248,13 @@ makes an
 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
@@ -183,7 +270,11 @@ means in this context).
 .B authbind
 is ineffective with setuid programs, because they do not honour
 .B LD_PRELOAD
-for security reasons.  Of course a setuid-root program does not need
+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
@@ -192,19 +283,14 @@ wishes it to use authbind they could have it load the
 library explicitly rather than via
 .BR LD_PRELOAD .
 .PP
-Some badly-written programs may have trouble because
+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.  Programs should not rely on standard
-libraries not doing these things.
-.PP
-Ports from 512 to 1023 inclusive cannot be used with
-.B authbind
-because that would create a security hole, in conjection with
-.BR rshd .
+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
@@ -231,16 +317,31 @@ 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.
+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_NESTED
-Do not set this variable.  It is set to
-.B 1
-by
-.B libauthbind
-when it invokes the helper program.  This allows detection of the
-situation where the helper has not been installed setuid, which would
-otherwise lead to infinite recursion.
+.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),
@@ -249,7 +350,7 @@ otherwise lead to infinite recursion.
 .SH AUTHOR
 .B authbind
 and this manpage were written by Ian Jackson.  They are
-Copyright (C)1998
+Copyright (C)1998,2012
 by him and released under the GNU General Public Licence; there is NO
 WARRANTY.  See
 .B /usr/doc/authbind/copyright