finalise 2.0.0

[authbind.git] / authbind.1

diff --git a/authbind.1 b/authbind.1
index 2b372eaf08396cf2c5bc5e6af200e35e88999404..52f0204f38eeb39440e50d9085749895867801b0 100644 (file)
--- a/authbind.1
+++ b/authbind.1
@@ -17,8 +17,6 @@
 .\" along with this program; if not, write to the Free Software Foundation,
 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 
 .\"
 .\" 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
 .TH AUTHBIND 1 "30th August 1998" "Debian Project" "Debian Linux manual"
 .SH NAME 
 authbind \- bind sockets to privileged ports without root


@@ -84,8 +82,18 @@ call, usually
 .RI ( "Permission denied" ).
 .PP
 Secondly, if that test fails to resolve the matter,
 .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
 .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 .
+Since this is not completely predictable for IPv6,
+for IPv6 a variant of
+.I addr
+is also tested which does not contain any ommitted zeroes or colons.

 .PP
 Thirdly, if the question is still unresolved, the file
 .BI /etc/authbind/byuid/ uid
 .PP
 Thirdly, if the question is still unresolved, the file
 .BI /etc/authbind/byuid/ uid


@@ -97,15 +105,22 @@ 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
 .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
+.IB            addr4 / length : portmin , portmax

 .fi
 .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 form requires that the initial

 .I length
 bits of
 .I addr
 match those in the proposed
 .B bind
 .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 and is only available for IPv4.
+Addresses can
+be in any form acceptable to inet_pton.  In both 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
 specified.  If such a line is found then the binding is authorised.
 Otherwise it is not, and
 .B bind


@@ -118,9 +133,6 @@ In each case above,
 .I port
 is the (local) TCP or UDP port number, expressed as an unsigned
 integer in the minimal non-zero number of digits, and
 .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
 .PP
 If a read error occurs, or the directory
 .B /etc/authbind


@@ -130,10 +142,24 @@ 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
 lines in
 .BI /etc/authbind/byuid/ uid
 files are silently ignored (as are lines whose

-.I addr
+.I addr4

 has non-zero bits more than
 .I length
 has non-zero bits more than
 .I length

-from the top).
+from the top) or where
+.I min
+is larger than
+.IR max .
+.PP
+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
 .SH MECHANISM
 The shared library loaded using
 .B LD_PRELOAD


@@ -178,7 +204,8 @@ the program's stderr, was well as returning -1 from
 .BR bind .
 .SH BUGS
 .B authbind
 .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.
 of sockets will not benefit from
 .BR authbind ,
 but it won't get in their way.


@@ -225,19 +252,14 @@ wishes it to use authbind they could have it load the
 library explicitly rather than via
 .BR LD_PRELOAD .
 .PP
 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
 .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
 .PP
 The access control configuration scheme is somewhat strange.
 .SH FILES AND ENVIRONMENT VARIABLES


@@ -297,7 +319,7 @@ was specified.
 .SH AUTHOR
 .B authbind
 and this manpage were written by Ian Jackson.  They are
 .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
 by him and released under the GNU General Public Licence; there is NO
 WARRANTY.  See
 .B /usr/doc/authbind/copyright