1 .\" # DS - begin display
13 .TH USERS 5 "04 Jan 2004" "" "FreeRADIUS user authorization file"
15 users \- user authorization file for the FreeRADIUS server
17 The \fBusers\fP files reside in the files module configuration directory,
18 by default \fB/etc/raddb/mods-config/files/\fP. It contains a series
19 of configuration directives which are used by the \fIfiles\fP
20 module to decide how to authorize and authenticate each user request.
22 Every line starting with a hash sign
24 is treated as comment and ignored.
26 Each entry of the file begins with a username, followed by a (possibly
27 empty) list of check items, all on one line. The next line begins
28 with a tab, and a (possibly empty) list of reply items. Each item in
29 the check or reply item list is an attribute of the form \fBname =
30 value\fP. Multiple items may be placed on one line, in which case
31 they must be seperated by commas. The reply items may be specified
32 over multiple lines, in which case each line must end with a comma,
33 and the last line of the reply items must not end with a comma.
35 The check items are a list of attributes used to match the incoming
36 request. If the username matches, AND all of the check items match
37 the incoming request, then the reply items are added to the list of
38 attributes which will be used in the reply to that request. This
39 process is repeated for all of the entries in the users file.
41 If the incoming request matches NO entry, then the request is
45 The special username \fBDEFAULT\fP matches any usernames.
47 The entries are processed in order, from the top of the \fBusers\fP file,
48 on down. If an entry contains the special item \fBFall-Through =
49 No\fP as a reply attribute, then the processing of the file stops, and
50 no more entries are matched. Any reply item list without any
51 \fBFall-Through\fP attribute is treated as though it included a
52 \fBFall-Through = No\fP attribute.
54 If an entry contains the special item \fBFall-Through = Yes\fP as a
55 reply attribute, then the processing proceeds to the next entry in
58 Care should be taken when using \fBFall-Through\fP. The server should
59 be tested in debugging mode with a number of test requests, in order
60 to verify that the configured entries behave as expected.
62 The special attribute \fBAuth-Type\fP is used to identify the
63 authentication type to be used for that user. See the
64 \fBdictionary\fP file for a list of permitted values for the
65 \fBAuth-Type\fP attribute.
67 Once the \fBusers\fP file has been processed, the request is authenticated,
68 using the method given by \fBAuth-Type\fP.
71 Additional operators other than \fB=\fP may be used for the attributes in
72 either the check item, or reply item list. The following is a list of
73 operators, and their meaning.
76 .B "Attribute = Value"
77 Not allowed as a check item for RADIUS protocol attributes. It is
78 allowed for server configuration attributes (Auth-Type, etc), and sets
79 the value of on attribute, only if there is no other item of the
82 As a reply item, it means "add the item
83 to the reply list, but only if there is no other item of the same
87 .B "Attribute := Value"
88 Always matches as a check item, and replaces in the configuration
89 items any attribute of the same name. If no attribute of that name
90 appears in the request, then this attribute is added.
92 As a reply item, it has an identical meaning, but for the reply items,
93 instead of the request items.
96 .B "Attribute == Value"
97 As a check item, it matches if the named attribute is present in the
98 request, AND has the given value.
100 Not allowed as a reply item.
103 .B "Attribute += Value"
104 Always matches as a check item, and adds the current attribute with
105 value to the list of configuration items.
107 As a reply item, it has an identical meaning, but the attribute is
108 added to the reply items.
111 .B "Attribute != Value"
112 As a check item, matches if the given attribute is in the request, AND
113 does not have the given value.
115 Not allowed as a reply item.
118 .B "Attribute > Value"
119 As a check item, it matches if the request contains an attribute with
120 a value greater than the one given.
122 Not allowed as a reply item.
125 .B "Attribute >= Value"
126 As a check item, it matches if the request contains an attribute with
127 a value greater than, or equal to the one given.
129 Not allowed as a reply item.
132 .B "Attribute < Value"
133 As a check item, it matches if the request contains an attribute with
134 a value less than the one given.
136 Not allowed as a reply item.
139 .B "Attribute <= Value"
140 As a check item, it matches if the request contains an attribute with
141 a value less than, or equal to the one given.
143 Not allowed as a reply item.
146 .B "Attribute =~ Expression"
147 As a check item, it matches if the request contains an attribute which
148 matches the given regular expression. This operator may only be
149 applied to string attributes.
151 Not allowed as a reply item.
154 .B "Attribute !~ Expression"
155 As a check item, it matches if the request contains an attribute which
156 does not match the given regular expression. This operator may only be
157 applied to string attributes.
159 Not allowed as a reply item.
162 .B "Attribute =* Value"
163 As a check item, it matches if the request contains the named
164 attribute, no matter what the value is.
166 Not allowed as a reply item.
169 .B "Attribute !* Value"
170 As a check item, it matches if the request does not contain the named
171 attribute, no matter what the value is.
173 Not allowed as a reply item.
178 bob Cleartext-Password := "hello"
182 Requests containing the User-Name attribute, with value "bob", will be
183 authenticated using the "known good" password "hello". There are no
184 reply items, so the reply will be empty.
188 DEFAULT Auth-Type = System
194 For all users reaching this entry, perform authentication against the
195 system, unless Auth-Type has already been set. Also, process any
196 following entries which may match.
200 DEFAULT Service-Type == Framed-User, Framed-Protocol == PPP
202 Service-Type = Framed-User,
204 Framed-Protocol = PPP,
210 If the request packet contains the attributes Service-Type and
211 Framed-Protocol, with the given values, then include those attributes
214 That is, give the user what they ask for. This entry also shows how
215 to specify multiple reply items.
218 See the \fBusers\fP file supplied with the server for more examples
222 Run the server in debugging mode (\fB-X\fP), and use the
223 \fBradclient\fP program to send it test packets which you think will
224 match specific entries. The server will print out which entries were
225 matched for that request, so you can verify your expectations. This
226 should be the FIRST thing you do if you suspect problems with the
229 Care should be taken when writing entries for the \fBusers\fP file. It is
230 easy to misconfigure the server so that requests are accepted when you
231 wish to reject them. The entries should be ordered, and the
232 Fall-Through item should be used ONLY where it is required.
234 Entries rejecting certain requests should go at the top of the file,
235 and should not have a Fall-Through item in their reply items. Entries
236 for specific users, who do not have a Fall-Through item, should come
237 next. Any DEFAULT entries should usually come last, except as fall-through
238 entries that set reply attributes.
241 /etc/raddb/mods-config/files/