X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=authbind.git;a=blobdiff_plain;f=authbind.1;h=d73e998990a92e6139d5c2ef6165f7aaac8e0569;hp=52f0204f38eeb39440e50d9085749895867801b0;hb=89f63ba8c7025f91bb40c532bd531db562e6e61c;hpb=c4ec7395c65a9a0c8df87434cc91030ba47d7542

diff --git a/authbind.1 b/authbind.1
index 52f0204..d73e998 100644
--- a/authbind.1
+++ b/authbind.1
@@ -89,13 +89,22 @@ Secondly, if that test fails to resolve the matter,
 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
+.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 contain any ommitted zeroes or colons.
+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
@@ -105,21 +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
-.IR		addrmin [\fB\-\fR addrmax ]\fB,\fR portmin \fB\-\fR portmax
+.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 form requires that the initial
+The second and third forms require that the initial
 .I length
 bits of
 .I addr
 match those in the proposed
 .B bind
-call and is only available for IPv4.
-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
@@ -128,12 +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
-.PP
 If a read error occurs, or the directory
 .B /etc/authbind
 cannot be accessed, then not only will
@@ -141,21 +146,47 @@ 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
-.I addr4
+files are silently ignored, as are lines whose
+.I addr
 has non-zero bits more than
 .I length
-from the top) or where
+from the top or where some
 .I min
 is larger than
 .IR max .
-.PP
+.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,
+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 !