.\"     # 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/freeradius/3.0/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 list of configuration items.
.br
As a reply item, it has an identical meaning, but the attribute is
added to the reply items.

.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	Auth-Type = System
.br
	Fall-Through = Yes

.DE
.RS
For all users reaching this entry, perform authentication against the
system, unless Auth-Type has already been set.  Also, process any
following entries which may match.
.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/freeradius/3.0/mods-config/files/
.SH "SEE ALSO"
.BR radclient (1),
.BR radiusd (8),
.BR dictionary (5),

.SH AUTHOR
The FreeRADIUS team.