1 files changed, 228 insertions, 0 deletions
diff --git a/man/man5/users.5 b/man/man5/users.5
new file mode 100644
index 0000000..4586b96
--- /dev/null
+++ b/man/man5/users.5
@@ -0,0 +1,228 @@
+.\"     # DS - begin display
+.de DS
+.RS
+.nf
+.sp
+..
+.\"     # DE - end display
+.de DE
+.fi
+.RE
+.sp
+..
+.TH USERS 5 "04 Jan 2004" "" "FreeRADIUS user authorization file"
+.SH NAME
+users \- user authorization file for the FreeRADIUS server
+.SH DESCRIPTION
+The \fBusers\fP files reside in the files module configuration directory,
+by default \fB/etc/raddb/mods-config/files/\fP.  It contains a series
+of configuration directives which are used by the \fIfiles\fP 
+module to decide how to authorize and authenticate each user request.
+
+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, all on one line.  The next line begins
+with a tab, and a (possibly empty) list of reply items.  Each item in
+the check or reply item list is an attribute of the form \fBname =
+value\fP.  Multiple items may be placed on one line, in which case
+they must be separated by commas.  The reply items may be specified
+over multiple lines, in which case each line must end with a comma,
+and the last line of the reply items must not end with a comma.
+
+The check items are a list of attributes used to match the incoming
+request.  If the username matches, AND all of the check items match
+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 keyword \fBDEFAULT\fP matches any usernames.
+
+The entries are processed in order, from the top of the \fBusers\fP file,
+on down.  If an entry contains the special item \fBFall-Through =
+No\fP as a reply attribute, then the processing of the file stops, and
+no more entries are matched.  Any reply item list without any
+\fBFall-Through\fP attribute is treated as though it included a
+\fBFall-Through = No\fP attribute.
+
+If an entry contains the special item \fBFall-Through = Yes\fP as a
+reply attribute, then the processing proceeds to the next entry in
+order.
+
+Care should be taken when using \fBFall-Through\fP.  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 \fBAuth-Type\fP is used to identify the
+authentication type to be used for that user.  See the
+\fBdictionary\fP file for a list of permitted values for the
+\fBAuth-Type\fP attribute.
+
+Once the \fBusers\fP file has been processed, the request is authenticated,
+using the method given by \fBAuth-Type\fP.
+
+.SH OPERATORS
+Additional operators other than \fB=\fP 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.
+
+.TP 0.5i
+.B "Attribute = Value"
+Not allowed as a check item for RADIUS protocol attributes.  It is
+allowed for server configuration attributes (Auth-Type, etc), and sets
+the value of on attribute, only if there is no other item of the
+same attribute.
+.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."
+
+.TP 0.5i
+.B "Attribute := Value"
+Always matches as a check item, and replaces in the configuration
+items any attribute of the same name.  If no attribute of that name
+appears in the request, then this attribute is added.
+.br
+As a reply item, it has an identical meaning, but for the reply items,
+instead of the request items.
+
+.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.
+
+.TP 0.5i
+.B "Attribute += Value"
+Always matches as a check item, and adds the current attribute with
+value to the tail of the list of configuration items.
+.br
+As a reply item, it has an identical meaning, but the attribute is
+added to the tail of the reply items list.
+
+.TP 0.5i
+.B "Attribute ^= Value"
+Always matches as a check item, and adds the current attribute with
+value to the head of the list of configuration items.
+.br
+As a reply item, it has an identical meaning, but the attribute is
+added to the head of the reply items list.
+
+.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.
+
+.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.
+
+.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.
+
+.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.
+
+.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.
+
+.TP 0.5i
+.B "Attribute =* Value"
+As a check item, it matches if the request contains the named
+attribute, no matter what the value is.
+.br
+Not allowed as a reply item.
+
+.TP 0.5i
+.B "Attribute !* Value"
+As a check item, it matches if the request does not contain the named
+attribute, no matter what the value is.
+.br
+Not allowed as a reply item.
+
+.SH EXAMPLES
+
+.DS
+bob	Cleartext-Password := "hello"
+
+.DE
+.RS
+Requests containing the User-Name attribute, with value "bob", will be
+authenticated using the "known good" password "hello".  There are no
+reply items, so the reply will be empty.
+.RE
+
+.DS
+DEFAULT Service-Type == Framed-User, Framed-Protocol == PPP
+.br
+	Service-Type = Framed-User,
+.br
+	Framed-Protocol = PPP,
+.br
+	Fall-Through = Yes
+
+.DE
+.RS
+If the request packet contains the attributes Service-Type and
+Framed-Protocol, with the given values, then include those attributes
+in the reply.
+
+That is, give the user what they ask for.  This entry also shows how
+to specify multiple reply items.
+.RE
+
+See the \fBusers\fP file supplied with the server for more examples
+and comments.
+
+.SH HINTS
+Run the server in debugging mode (\fB-X\fP), and use the
+\fBradclient\fP 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 \fBusers\fP 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 usually come last, except as fall-through
+entries that set reply attributes.
+
+.SH FILES
+/etc/raddb/mods-config/files/
+.SH "SEE ALSO"
+.BR radclient (1),
+.BR radiusd (8),
+.BR dictionary (5),
+
+.SH AUTHOR
+The FreeRADIUS team.