man/man5/users.5

   1 .TH USERS 5 "05 August 2000" "" "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\fB 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.
  66 .br
  67 As a reply item, it means "add the item
  68 to the reply list, but only if there is no other item of the same
  69 attribute."
  70
  71 .TP 0.5i
  72 .B "Attribute := Value"
  73 Always matches as a check item, and replaces in the request any
  74 attribute of the same name.  If no attribute of that name appears in
  75 the request, then this attribute is added.
  76 .br
  77 As a reply item, it has an identical meaning, but for the reply items,
  78 instead of the request items.
  79
  80 .TP 0.5i
  81 .B "Attribute == Value"
  82 As a check item, it matches if the named attribute is present in the
  83 request, AND has the given value.
  84 .br
  85 Not allowed as a reply item.
  86
  87 .TP 0.5i
  88 .B "Attribute += Value"
  89 Always matches as a check item, and adds the current attribute with
  90 value to the incoming request.
  91 .br
  92 As a reply item, it has an identical meaning, but the attribute is
  93 added to the reply items.
  94
  95 .TP 0.5i
  96 .B "Attribute != Value"
  97 As a check item, matches if the given attribute is in the request, AND
  98 does not have the given value.
  99 .br
 100 Not allowed as a reply item.
 101
 102 .TP 0.5i
 103 .B "Attribute > Value"
 104 As a check item, it matches if the request contains an attribute with
 105 a value greater than the one given.
 106 .br
 107 Not allowed as a reply item.
 108
 109 .TP 0.5i
 110 .B "Attribute >= Value"
 111 As a check item, it matches if the request contains an attribute with
 112 a value greater than, or equal to the one given.
 113 .br
 114 Not allowed as a reply item.
 115
 116 .TP 0.5i
 117 .B "Attribute < Value"
 118 As a check item, it matches if the request contains an attribute with
 119 a value less than the one given.
 120 .br
 121 Not allowed as a reply item.
 122
 123 .TP 0.5i
 124 .B "Attribute <= Value"
 125 As a check item, it matches if the request contains an attribute with
 126 a value less than, or equal to the one given.
 127 .br
 128 Not allowed as a reply item.
 129
 130 .TP 0.5i
 131 .B "Attribute =~ Expression"
 132 As a check item, it matches if the request contains an attribute which
 133 matches the given regular expression.  This operator may only be
 134 applied to string attributes.
 135 .br
 136 Not allowed as a reply item.
 137
 138 .TP 0.5i
 139 .B "Attribute !~ Expression"
 140 As a check item, it matches if the request contains an attribute which
 141 does not match the given regular expression.  This operator may only be
 142 applied to string attributes.
 143 .br
 144 Not allowed as a reply item.
 145
 146 .SH EXAMPLES
 147
 148 .DS
 149 bob     Auth-Type := Local, Password == "bob"
 150
 151 .DE
 152 .RS
 153 Requests containing the User-Name attribute, with value "bob", will be
 154 authenticated using the local password "bob".  There are no reply
 155 items, so the reply will be empty.
 156 .RE
 157
 158 .DS
 159 DEFAULT Auth-Type := System
 160 .br
 161         Fall-Through = Yes
 162
 163 .DE
 164 .RS
 165 For all users reaching this entry, perform authentication against the
 166 system.  Also, process any following entries which may match.
 167 .RE
 168
 169 .DS
 170 DEFAULT Service-Type==Framed-User, Framed-Protocol==PPP
 171 .br
 172         Service-Type = Framed-User,
 173 .br
 174         Framed-Protocol = PPP,
 175 .br
 176         Fall-Through = Yes
 177
 178 .DE
 179 .RS
 180 If the request packet contains the attributes Service-Type and
 181 Framed-Protocol, with the given values, then include those attributes
 182 in the reply.
 183
 184 That is, give the user what they ask for.  This entry also shows how
 185 to specify multiple reply items.
 186 .RE
 187
 188 See the \fBusers\fP file supplied with the server for more examples
 189 and comments.
 190
 191 .SH HINTS
 192 Run the server in debugging mode (\fB-X\fP), and use the
 193 \fBradclient\fP program to send it test packets which you think will
 194 match specific entries.  The server will print out which entries were
 195 matched for that request, so you can verify your expectations.  This
 196 should be the FIRST thing you do if you suspect problems with the
 197 file.
 198
 199 Care should be taken when writing entries for the \fBusers\fP file.  It is
 200 easy to misconfigure the server so that requests are accepted when you
 201 wish to reject them.  The entries should be ordered, and the
 202 Fall-Through item should be used ONLY where it is required.
 203
 204 Entries rejecting certain requests should go at the top of the file,
 205 and should not have a Fall-Through item in their reply items.  Entries
 206 for specific users, who do not have a Fall-Through item, should come
 207 next.  Any DEFAULT entries should come last.
 208
 209 .SH FILES
 210 /etc/raddb/users
 211 .SH "SEE ALSO"
 212 .BR radclient (1),
 213 .BR radiusd (8),
 214 .BR dictionary (5),
 215 .BR naslist (5)
 216
 217 .SH AUTHOR
 218 The FreeRADIUS team.