man/man5/users.5

   1 .\"     # DS - begin display
   2 .de DS
   3 .RS
   4 .nf
   5 .sp
   6 ..
   7 .\"     # DE - end display
   8 .de DE
   9 .fi
  10 .RE
  11 .sp
  12 ..
  13 .TH USERS 5 "04 Jan 2004" "" "FreeRADIUS user authorization file"
  14 .SH NAME
  15 users \- user authorization file for the FreeRADIUS server
  16 .SH DESCRIPTION
  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.
  21
  22 Every line starting with a hash sign
  23 .RB (' # ')
  24 is treated as comment and ignored.
  25 .PP
  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 separated 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.
  34
  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.
  40
  41 If the incoming request matches NO entry, then the request is
  42 rejected.
  43
  44 .SH CAVEATS
  45 The special keyword \fBDEFAULT\fP matches any usernames.
  46
  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.
  53
  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
  56 order.
  57
  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.
  61
  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.
  66
  67 Once the \fBusers\fP file has been processed, the request is authenticated,
  68 using the method given by \fBAuth-Type\fP.
  69
  70 .SH OPERATORS
  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.
  74
  75 .TP 0.5i
  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
  80 same attribute.
  81 .br
  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
  84 attribute."
  85
  86 .TP 0.5i
  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.
  91 .br
  92 As a reply item, it has an identical meaning, but for the reply items,
  93 instead of the request items.
  94
  95 .TP 0.5i
  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.
  99 .br
 100 Not allowed as a reply item.
 101
 102 .TP 0.5i
 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.
 106 .br
 107 As a reply item, it has an identical meaning, but the attribute is
 108 added to the reply items.
 109
 110 .TP 0.5i
 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.
 114 .br
 115 Not allowed as a reply item.
 116
 117 .TP 0.5i
 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.
 121 .br
 122 Not allowed as a reply item.
 123
 124 .TP 0.5i
 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.
 128 .br
 129 Not allowed as a reply item.
 130
 131 .TP 0.5i
 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.
 135 .br
 136 Not allowed as a reply item.
 137
 138 .TP 0.5i
 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.
 142 .br
 143 Not allowed as a reply item.
 144
 145 .TP 0.5i
 146 .B "Attribute =* Value"
 147 As a check item, it matches if the request contains the named
 148 attribute, no matter what the value is.
 149 .br
 150 Not allowed as a reply item.
 151
 152 .TP 0.5i
 153 .B "Attribute !* Value"
 154 As a check item, it matches if the request does not contain the named
 155 attribute, no matter what the value is.
 156 .br
 157 Not allowed as a reply item.
 158
 159 .SH EXAMPLES
 160
 161 .DS
 162 bob     Cleartext-Password := "hello"
 163
 164 .DE
 165 .RS
 166 Requests containing the User-Name attribute, with value "bob", will be
 167 authenticated using the "known good" password "hello".  There are no
 168 reply items, so the reply will be empty.
 169 .RE
 170
 171 .DS
 172 DEFAULT Auth-Type = System
 173 .br
 174         Fall-Through = Yes
 175
 176 .DE
 177 .RS
 178 For all users reaching this entry, perform authentication against the
 179 system, unless Auth-Type has already been set.  Also, process any
 180 following entries which may match.
 181 .RE
 182
 183 .DS
 184 DEFAULT Service-Type == Framed-User, Framed-Protocol == PPP
 185 .br
 186         Service-Type = Framed-User,
 187 .br
 188         Framed-Protocol = PPP,
 189 .br
 190         Fall-Through = Yes
 191
 192 .DE
 193 .RS
 194 If the request packet contains the attributes Service-Type and
 195 Framed-Protocol, with the given values, then include those attributes
 196 in the reply.
 197
 198 That is, give the user what they ask for.  This entry also shows how
 199 to specify multiple reply items.
 200 .RE
 201
 202 See the \fBusers\fP file supplied with the server for more examples
 203 and comments.
 204
 205 .SH HINTS
 206 Run the server in debugging mode (\fB-X\fP), and use the
 207 \fBradclient\fP program to send it test packets which you think will
 208 match specific entries.  The server will print out which entries were
 209 matched for that request, so you can verify your expectations.  This
 210 should be the FIRST thing you do if you suspect problems with the
 211 file.
 212
 213 Care should be taken when writing entries for the \fBusers\fP file.  It is
 214 easy to misconfigure the server so that requests are accepted when you
 215 wish to reject them.  The entries should be ordered, and the
 216 Fall-Through item should be used ONLY where it is required.
 217
 218 Entries rejecting certain requests should go at the top of the file,
 219 and should not have a Fall-Through item in their reply items.  Entries
 220 for specific users, who do not have a Fall-Through item, should come
 221 next.  Any DEFAULT entries should usually come last, except as fall-through
 222 entries that set reply attributes.
 223
 224 .SH FILES
 225 /etc/raddb/mods-config/files/
 226 .SH "SEE ALSO"
 227 .BR radclient (1),
 228 .BR radiusd (8),
 229 .BR dictionary (5),
 230
 231 .SH AUTHOR
 232 The FreeRADIUS team.