man/man5/users.5

   1 .TH USERS 5 "04 Jan 2004" "" "FreeRADIUS user authorization file"
   2 .SH NAME
   3 users \- user authorization file for the FreeRADIUS server
   4 .SH DESCRIPTION
   5 The \fBusers\fP file resides in the RADIUS database directory, by
   6 default \fB/etc/raddb\fP.  It contains a series of configuration
   7 directives which are used by the \fIfiles\fP module to decide how to
   8 authorize and authenticate each user request.
   9
  10 Every line starting with a hash sign
  11 .RB (' # ')
  12 is treated as comment and ignored.
  13 .PP
  14 Each entry of the file begins with a username, followed by a (possibly
  15 empty) list of check items, all on one line.  The next line begins
  16 with a tab, and a (possibly empty) list of reply items.  Each item in
  17 the check or reply item list is an attribute of the form \fBname =
  18 value\fP.  Multiple items may be placed on one line, in which case
  19 they must be seperated by commas.  The reply items may be specified
  20 over multiple lines, in which case each line must end with a comma,
  21 and the last line of the reply items must not end with a comma.
  22
  23 The check items are a list of attributes used to match the incoming
  24 request.  If the username matches, AND all of the check items match
  25 the incoming request, then the reply items are added to the list of
  26 attributes which will be used in the reply to that request.  This
  27 process is repeated for all of the entries in the users file.
  28
  29 If the incoming request matches NO entry, then the request is
  30 rejected.
  31
  32 .SH CAVEATS
  33 The special username \fBDEFAULT\fP matches any usernames.
  34
  35 The entries are processed in order, from the top of the \fBusers\fP file,
  36 on down.  If an entry contains the special item \fBFall-Through =
  37 No\fP as a reply attribute, then the processing of the file stops, and
  38 no more entries are matched.  Any reply item list without any
  39 \fBFall-Through\fP attribute is treated as though it included a
  40 \fBFall-Through = No\fP attribute.
  41
  42 If an entry contains the special item \fBFall-Through = Yes\fP as a
  43 reply attribute, then the processing proceeds to the next entry in
  44 order.
  45
  46 Care should be taken when using \fBFall-Through\fP.  The server should
  47 be tested in debugging mode with a number of test requests, in order
  48 to verify that the configured entries behave as expected.
  49
  50 The special attribute \fBAuth-Type\fP is used to identify the
  51 authentication type to be used for that user.  See the
  52 \fBdictionary\fP file for a list of permitted values for the
  53 \fBAuth-Type\fP attribute.
  54
  55 Once the \fBusers\fP file has been processed, the request is authenticated,
  56 using the method given by \fBAuth-Type\fP.
  57
  58 .SH OPERATORS
  59 Additional operators other than \fB=\fP may be used for the attributes in
  60 either the check item, or reply item list.  The following is a list of
  61 operators, and their meaning.
  62
  63 .TP 0.5i
  64 .B "Attribute = Value"
  65 Not allowed as a check item for RADIUS protocol attributes.  It is
  66 allowed for server configuration attributes (Auth-Type, etc), and sets
  67 the value of on attribute, only if there is no other item of the
  68 same attribute.
  69 .br
  70 As a reply item, it means "add the item
  71 to the reply list, but only if there is no other item of the same
  72 attribute."
  73
  74 .TP 0.5i
  75 .B "Attribute := Value"
  76 Always matches as a check item, and replaces in the configuration
  77 items any attribute of the same name.  If no attribute of that name
  78 appears in the request, then this attribute is added.
  79 .br
  80 As a reply item, it has an identical meaning, but for the reply items,
  81 instead of the request items.
  82
  83 .TP 0.5i
  84 .B "Attribute == Value"
  85 As a check item, it matches if the named attribute is present in the
  86 request, AND has the given value.
  87 .br
  88 Not allowed as a reply item.
  89
  90 .TP 0.5i
  91 .B "Attribute += Value"
  92 Always matches as a check item, and adds the current attribute with
  93 value to the list of configuration items.
  94 .br
  95 As a reply item, it has an identical meaning, but the attribute is
  96 added to the reply items.
  97
  98 .TP 0.5i
  99 .B "Attribute != Value"
 100 As a check item, matches if the given attribute is in the request, AND
 101 does not have the given value.
 102 .br
 103 Not allowed as a reply item.
 104
 105 .TP 0.5i
 106 .B "Attribute > Value"
 107 As a check item, it matches if the request contains an attribute with
 108 a value greater than the one given.
 109 .br
 110 Not allowed as a reply item.
 111
 112 .TP 0.5i
 113 .B "Attribute >= Value"
 114 As a check item, it matches if the request contains an attribute with
 115 a value greater than, or equal to the one given.
 116 .br
 117 Not allowed as a reply item.
 118
 119 .TP 0.5i
 120 .B "Attribute < Value"
 121 As a check item, it matches if the request contains an attribute with
 122 a value less than the one given.
 123 .br
 124 Not allowed as a reply item.
 125
 126 .TP 0.5i
 127 .B "Attribute <= Value"
 128 As a check item, it matches if the request contains an attribute with
 129 a value less than, or equal to the one given.
 130 .br
 131 Not allowed as a reply item.
 132
 133 .TP 0.5i
 134 .B "Attribute =~ Expression"
 135 As a check item, it matches if the request contains an attribute which
 136 matches the given regular expression.  This operator may only be
 137 applied to string attributes.
 138 .br
 139 Not allowed as a reply item.
 140
 141 .TP 0.5i
 142 .B "Attribute !~ Expression"
 143 As a check item, it matches if the request contains an attribute which
 144 does not match the given regular expression.  This operator may only be
 145 applied to string attributes.
 146 .br
 147 Not allowed as a reply item.
 148
 149 .TP 0.5i
 150 .B "Attribute =* Value"
 151 As a check item, it matches if the request contains the named
 152 attribute, no matter what the value is.
 153 .br
 154 Not allowed as a reply item.
 155
 156 .TP 0.5i
 157 .B "Attribute !* Value"
 158 As a check item, it matches if the request does not contain the named
 159 attribute, no matter what the value is.
 160 .br
 161 Not allowed as a reply item.
 162
 163 .SH EXAMPLES
 164
 165 .DS
 166 bob     User-Password == "hello"
 167
 168 .DE
 169 .RS
 170 Requests containing the User-Name attribute, with value "bob", will be
 171 authenticated using the password "bob".  There are no reply items, so
 172 the reply will be empty.
 173 .RE
 174
 175 .DS
 176 DEFAULT Auth-Type = System
 177 .br
 178         Fall-Through = Yes
 179
 180 .DE
 181 .RS
 182 For all users reaching this entry, perform authentication against the
 183 system, unless Auth-Type has already been set.  Also, process any
 184 following entries which may match.
 185 .RE
 186
 187 .DS
 188 DEFAULT Service-Type == Framed-User, Framed-Protocol == PPP
 189 .br
 190         Service-Type = Framed-User,
 191 .br
 192         Framed-Protocol = PPP,
 193 .br
 194         Fall-Through = Yes
 195
 196 .DE
 197 .RS
 198 If the request packet contains the attributes Service-Type and
 199 Framed-Protocol, with the given values, then include those attributes
 200 in the reply.
 201
 202 That is, give the user what they ask for.  This entry also shows how
 203 to specify multiple reply items.
 204 .RE
 205
 206 See the \fBusers\fP file supplied with the server for more examples
 207 and comments.
 208
 209 .SH HINTS
 210 Run the server in debugging mode (\fB-X\fP), and use the
 211 \fBradclient\fP program to send it test packets which you think will
 212 match specific entries.  The server will print out which entries were
 213 matched for that request, so you can verify your expectations.  This
 214 should be the FIRST thing you do if you suspect problems with the
 215 file.
 216
 217 Care should be taken when writing entries for the \fBusers\fP file.  It is
 218 easy to misconfigure the server so that requests are accepted when you
 219 wish to reject them.  The entries should be ordered, and the
 220 Fall-Through item should be used ONLY where it is required.
 221
 222 Entries rejecting certain requests should go at the top of the file,
 223 and should not have a Fall-Through item in their reply items.  Entries
 224 for specific users, who do not have a Fall-Through item, should come
 225 next.  Any DEFAULT entries should usually come last, except as fall-through
 226 entries that set reply attributes.
 227
 228 .SH FILES
 229 /etc/raddb/users
 230 .SH "SEE ALSO"
 231 .BR radclient (1),
 232 .BR radiusd (8),
 233 .BR dictionary (5),
 234 .BR naslist (5)
 235
 236 .SH AUTHOR
 237 The FreeRADIUS team.