man/man5/users.5

   1 .TH USERS 5 "05 August 2000"
   2 .SH NAME
   3 users \- RADIUS users file
   4 .SH DESCRIPTION
   5 The \fIusers\fP file resides in the radius database directory,
   6 by default \fI/etc/raddb\fP.  It contains a series of configuration
   7 directives which are used by the server to decide how to authorize and
   8 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.  The next line begins with a tab, and a
  16 (possibly empty) list of reply items.  Each item in the check or reply
  17 item list is an attribute of the form \fIname = value\fP.  Multiple
  18 items may be placed on one line, in which case they must be seperated
  19 by commas.
  20
  21 The check items are a list of attributes used to match the incoming
  22 request.  If the username matches, AND all of the check items match
  23 the incoming request, then the reply items are added to the list of
  24 attributes which will be used in the reply to that request.  This
  25 process is repeated for all of the entries in the users file.
  26
  27 If the incoming request matches NO entry, then the request is
  28 rejected.
  29
  30 .SH CAVEATS
  31 The special username \fIDEFAULT\fP matches any usernames.
  32
  33 The entries are processed in order, from the top of the 'users' file,
  34 on down.  If an entry contains the special attribute 'Fall-Through =
  35 No' as a reply attribute, then the processing of the file stops, and
  36 no more entries are matched.  Any reply item list without any
  37 Fall-Through attribute is treated as though it included a
  38 'Fall-Through = No' attribute.
  39
  40 If an entry contains the special attribute 'Fall-Through = Yes' as a
  41 reply attribute, then the processing proceeds to the next entry in
  42 order.
  43
  44 Care should be taken when using Fall-Through.  The server should be
  45 tested in debugging mode with a number of test requests, in order to
  46 verify that the configured entries behave as expected.
  47
  48 The special attribute Auth-Type is used to identify the authentication
  49 type to be used for that user.  See the dictionary file for a list of
  50 permitted Auth-Type values.
  51
  52 Once the 'users' has been processed, the request is authenticated.
  53
  54 .SH OPERATORS
  55 Additional operators other than '=' may be used for the attributes in
  56 either the check item, or reply item list.  The following is a list of
  57 operators, and their meaning.
  58
  59 .TP 0.5i
  60 .B "Attribute = Value"
  61 Not allowed as a check item.
  62 .br
  63 As a reply item, it means "add the item
  64 to the reply list, but only if there is no other item of the same
  65 attribute."
  66
  67 .TP 0.5i
  68 .B "Attribute := Value"
  69 Always matches as a check item, and replaces in the request any
  70 attribute of the same name.  If no attribute of that name appears in
  71 the request, then this attribute is added.
  72 .br
  73 As a reply item, it has an identical meaning, but for the reply items,
  74 instead of the request items.
  75
  76 .TP 0.5i
  77 .B "Attribute == Value"
  78 As a check item, it matches if the named attribute is present in the
  79 request, AND has the given value.
  80 .br
  81 Not allowed as a reply item.
  82
  83 .TP 0.5i
  84 .B "Attribute += Value"
  85 Always matches as a check item, and adds the current attribute with
  86 value to the incoming request.
  87 .br
  88 As a reply item, it has an identical meaning, but the attribute is
  89 added to the reply items.
  90
  91 .TP 0.5i
  92 .B "Attribute != Value"
  93 As a check item, matches if the given attribute is in the request, AND
  94 does not have the given value.
  95 .br
  96 Not allowed as a reply item.
  97
  98 .TP 0.5i
  99 .B "Attribute > Value"
 100 As a check item, it matches if the request contains an attribute with
 101 a value greater than the one given.
 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, or equal to 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 less than 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, or equal to the one given.
 123 .br
 124 Not allowed as a reply item.
 125
 126 .TP 0.5i
 127 .B "Attribute =~ Expression"
 128 As a check item, it matches if the request contains an attribute which
 129 matches the given regular expression.  This operator may only be
 130 applied to string attributes.
 131 .br
 132 Not allowed as a reply item.
 133
 134 .TP 0.5i
 135 .B "Attribute !~ Expression"
 136 As a check item, it matches if the request contains an attribute which
 137 does not match the given regular expression.  This operator may only be
 138 applied to string attributes.
 139 .br
 140 Not allowed as a reply item.
 141
 142 .SH EXAMPLES
 143
 144 .DS
 145 bob     Auth-Type := Local, Password == "bob"
 146
 147 .DE
 148 .RS
 149 Requests containing the User-Name attribute, with value "bob", will be
 150 authenticated using the local password "bob".  There are no reply
 151 items, so the reply will be empty.
 152 .RE
 153
 154 .DS
 155 DEFAULT Auth-Type := System
 156 .br
 157         Fall-Through = Yes
 158
 159 .DE
 160 .RS
 161 For all other users, perform authentication against the system.  Also,
 162 process any following entries which may match.
 163 .RE
 164
 165 See the 'users' file supplied with the server for more examples and
 166 comments.
 167
 168 .SH HINTS
 169 Run the server in debugging mode (-X), and use the radclient program
 170 to send it test packets which you think will match specific entries.
 171 The server will print out which entries were matched for that request,
 172 so you can verify your expectations.  This should be the FIRST thing
 173 you do if you suspect problems with the file.
 174
 175 Care should be taken when writing entries for the 'users' file.  It is
 176 easy to misconfigure the server so that requests are accepted when you
 177 wish to reject them.  The entries should be ordered, and the
 178 Fall-Through item should be used ONLY where it is required.
 179
 180 Entries rejecting certain requests should go at the top of the file,
 181 and should not have a Fall-Through item in their reply items.  Entries
 182 for specific users, who do not have a Fall-Through item, should come
 183 next.  Any DEFAULT entries should come last.
 184
 185 .SH FILES
 186 .I /etc/raddb/users
 187 .SH "SEE ALSO"
 188 .BR radclient (1),
 189 .BR radiusd (8),
 190 .BR dictionary (5),
 191 .BR naslist (5)
 192
 193 .SH AUTHOR
 194 The FreeRADIUS team.