Merge from sid [dgit]

[authbind.git] / authbind.1

diff --git a/authbind.1 b/authbind.1
index 09f9fc2c2b02e52c8cc6e0ffbe8b38c0ecf4514c..d73e998990a92e6139d5c2ef6165f7aaac8e0569 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


@@ -65,7 +63,7 @@ of files in a configuration area,
 .BR /etc/authbind .
 .PP
 Firstly,
 .BR /etc/authbind .
 .PP
 Firstly,

-.BR /etc/authbind/byport/ [ ! ]\fIport\fR
+.BI /etc/authbind/byport/ port

 is tested.  If this file is accessible for execution to the calling
 user, according to
 .BR access (2),
 is tested.  If this file is accessible for execution to the calling
 user, according to
 .BR access (2),


@@ -84,11 +82,30 @@ 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,

-.BR /etc/authbind/byaddr/ \fIaddr\fR : [ ! ]\fIport\fR
-is tested, in the same manner as above.
+.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
 .PP

-Thirdly, if the question is still unresolved, the file
-.BR /etc/authbind/byuid/ [ ! ]\fIuid\fR
+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 be opened and read.  If the file does not exist then the binding
 is not authorised and
 .B bind


@@ -97,18 +114,23 @@ 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            addr4 / length : min\-port , max\-port
-.IR            addrmin [\fB-\fR addrmax ]\fB:\fR min\-port \fB,\fR 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
 .fi

-matching the request.   The first form requires that 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
 .I length
 bits of
 .I addr
 match those in the proposed
 .B bind

-call.  The second form requires that the address lies in the
-relevant range (inclusive at both ends).  Addresses can
-be in any form acceptable to inet_pton.  In both cases
+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
 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


@@ -117,15 +139,6 @@ will fail with
 .B ENOENT
 .RI ( "No such file or directory" ).
 .PP
 .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
 If a read error occurs, or the directory
 .B /etc/authbind
 cannot be accessed, then not only will


@@ -133,22 +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
 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 ignored, as are lines whose

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

-from the top).
-.TP
+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
 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, all the files
-checked and read will have the additional
+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 !
 .B !

-character.
+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


@@ -241,14 +283,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.
+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


@@ -308,7 +350,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