added even more text. It might actually make sense now.

diff --git a/man/man5/users.5 b/man/man5/users.5
index 3eb20c2..1392090 100644 (file)
--- a/man/man5/users.5
+++ b/man/man5/users.5
@@ -11,7 +11,6 @@ Every line starting with a hash sign
 .RB (' # ')
 is treated as comment and ignored.
 .PP
-
 Each entry of the file begins with a username, followed by a (possibly
 empty) list of check items.  The next line begins with a tab, and a
 (possibly empty) list of reply items.  Each item in the check or reply
@@ -25,6 +24,9 @@ the incoming request, then the reply items are added to the list of
 attributes which will be used in the reply to that request.  This
 process is repeated for all of the entries in the users file.
 
+If the incoming request matches NO entry, then the request is
+rejected.
+
 .SH CAVEATS
 The special username \fIDEFAULT\fP matches any usernames.
 
@@ -43,19 +45,27 @@ Care should be taken when using Fall-Through.  The server should be
 tested in debugging mode with a number of test requests, in order to
 verify that the configured entries behave as expected.
 
+The special attribute Auth-Type is used to identify the authentication
+type to be used for that user.  See the dictionary file for a list of
+permitted Auth-Type values.
+
+Once the 'users' has been processed, the request is authenticated.
+
 .SH OPERATORS
 Additional operators other than '=' may be used for the attributes in
 either the check item, or reply item list.  The following is a list of
 operators, and their meaning.
 
-.IP "Attribute = Value"
+.TP 0.5i
+.B "Attribute = Value"
 Not allowed as a check item.
 .br
 As a reply item, it means "add the item
 to the reply list, but only if there is no other item of the same
 attribute."
 
-.IP "Attribute := Value"
+.TP 0.5i
+.B "Attribute := Value"
 Always matches as a check item, and replaces in the request any
 attribute of the same name.  If no attribute of that name appears in
 the request, then this attribute is added.
@@ -63,71 +73,121 @@ the request, then this attribute is added.
 As a reply item, it has an identical meaning, but for the reply items,
 instead of the request items.
 
-.IP "Attribute == Value"
+.TP 0.5i
+.B "Attribute == Value"
 As a check item, it matches if the named attribute is present in the
 request, AND has the given value.
 .br
 Not allowed as a reply item.
 
-.IP "Attribute += Value"
+.TP 0.5i
+.B "Attribute += Value"
 Always matches as a check item, and adds the current attribute with
 value to the incoming request.
 .br
 As a reply item, it has an identical meaning, but the attribute is
 added to the reply items.
 
-.IP "Attribute != Value"
+.TP 0.5i
+.B "Attribute != Value"
 As a check item, matches if the given attribute is in the request, AND
 does not have the given value.
 .br
 Not allowed as a reply item.
 
-.IP "Attribute > Value"
+.TP 0.5i
+.B "Attribute > Value"
 As a check item, it matches if the request contains an attribute with
 a value greater than the one given.
 .br
 Not allowed as a reply item.
 
-.IP "Attribute >= Value"
+.TP 0.5i
+.B "Attribute >= Value"
 As a check item, it matches if the request contains an attribute with
 a value greater than, or equal to the one given.
 .br
 Not allowed as a reply item.
 
-.IP "Attribute < Value"
+.TP 0.5i
+.B "Attribute < Value"
 As a check item, it matches if the request contains an attribute with
 a value less than the one given.
 .br
 Not allowed as a reply item.
 
-.IP "Attribute <= Value"
+.TP 0.5i
+.B "Attribute <= Value"
 As a check item, it matches if the request contains an attribute with
 a value less than, or equal to the one given.
 .br
 Not allowed as a reply item.
 
-.IP "Attribute =~ Expression"
+.TP 0.5i
+.B "Attribute =~ Expression"
 As a check item, it matches if the request contains an attribute which
 matches the given regular expression.  This operator may only be
 applied to string attributes.
 .br
 Not allowed as a reply item.
 
-.IP "Attribute !~ Expression"
+.TP 0.5i
+.B "Attribute !~ Expression"
 As a check item, it matches if the request contains an attribute which
 does not match the given regular expression.  This operator may only be
 applied to string attributes.
 .br
 Not allowed as a reply item.
 
+.SH EXAMPLES
+
+.DS
+bob    Auth-Type := Local, Password == "bob"
 
+.DE
+.RS
+Requests containing the User-Name attribute, with value "bob", will be
+authenticated using the local password "bob".  There are no reply
+items, so the reply will be empty.
+.RE
 
+.DS
+DEFAULT        Auth-Type := System
+.br
+       Fall-Through = Yes
+
+.DE
+.RS
+For all other users, perform authentication against the system.  Also,
+process any following entries which may match.
+.RE
+
+See the 'users' file supplied with the server for more examples and
+comments.
+
+.SH HINTS
+Run the server in debugging mode (-X), and use the radclient program
+to send it test packets which you think will match specific entries.
+The server will print out which entries were matched for that request,
+so you can verify your expectations.  This should be the FIRST thing
+you do if you suspect problems with the file.
+
+Care should be taken when writing entries for the 'users' file.  It is
+easy to misconfigure the server so that requests are accepted when you
+wish to reject them.  The entries should be ordered, and the
+Fall-Through item should be used ONLY where it is required.
+
+Entries rejecting certain requests should go at the top of the file,
+and should not have a Fall-Through item in their reply items.  Entries
+for specific users, who do not have a Fall-Through item, should come
+next.  Any DEFAULT entries should come last.
 
 .SH FILES
 .I /etc/raddb/users
 .SH "SEE ALSO"
+.BR radclient (1),
 .BR radiusd (8),
-.BR dictionary (5)
+.BR dictionary (5),
 .BR naslist (5)
 
 .SH AUTHOR