doc/rlm_sql

   1         SQL Module
   2
   3 0. Introduction
   4
   5   The SQL module is composed of two parts: a generic SQL front-end
   6   (rlm_sql), and a series of database-dependent back-end drivers,
   7   (rlm_sql_mysql, rlm_sql_postgresql, etc.)
   8
   9   In order to build the drivers, you MUST ALSO install the development
  10   versions of the database.  That is, you must have the appropriate
  11   header files and client libraries for (say) MySQL.  The
  12   rlm_sql_mysql driver is NOT a complete MySQL client implementation.
  13   Instead, it is a small 'shim' between the FreeRADIUS rlm_sql module,
  14   and the MySQL client libraries.
  15
  16
  17   In general, the SQL schemas mirror the layout of the 'users' file.
  18   So for configuring check items and reply items, see 'man 5 users',
  19   and the examples in the 'users' file.
  20
  21
  22 1. Schema and usage
  23
  24   The schemas are available in raddb/sql/<DB>/*, where <DB> is the
  25   name of the database (mysql, postgresql, etc.)
  26
  27   The SQL module employs two sets of check and reply item tables for
  28   processing in the authorization stage.  One set of tables (radcheck and
  29   radreply) are specific to a single user.  The other set of tables
  30   (radgroupcheck and radgroupreply) is used to apply check and reply items
  31   to users that are members of a certain SQL group.  The usergroup table
  32   provides the list of groups each user is a member of along with a priority
  33   field to control the order in which groups are processed.
  34
  35   When a request comes into the server and is processed by the SQL module,
  36   the flow goes something like this:
  37
  38   1. Search the radcheck table for any check attributes specific to the user
  39   2. If check attributes are found, and there's a match, pull the reply items
  40      from the radreply table for this user and add them to the reply
  41   3. Group processing then begins if any of the following conditions are met:
  42      a. The user IS NOT found in radcheck
  43      b. The user IS found in radcheck, but the check items don't match
  44      c. The user IS found in radcheck, the check items DO match AND
  45         Fall-Through is set in the radreply table
  46      d. The user IS found in radcheck, the check items DO match AND
  47         the read_groups directive is set to 'yes'
  48   4. If groups are to be processed for this user, the first thing that is
  49      done is the list of groups this user is a member of is pulled from the
  50      usergroup table ordered by the priority field.  The priority field of
  51      the usergroup table allows us to control the order in which groups are
  52      processed, so that we can emulate the ordering in the users file.  This
  53      can be important in many cases.
  54   5. For each group this user is a member of, the corresponding check items
  55      are pulled from radgroupcheck table and compared with the request.  If
  56      there is a match, the reply items for this group are pulled from the
  57      radgroupreply table and applied.
  58   6. Processing continues to the next group IF:
  59      a. There was not a match for the last group's check items OR
  60      b. Fall-Through was set in the last group's reply items
  61      (The above is exactly the same as in the users file)
  62   7. Finally, if the user has a User-Profile attribute set or the Default
  63      Profile option is set in the sql.conf, then steps 4-6 are repeated for
  64      the groups that the profile is a member of.
  65
  66   For any fairly complex setup, it is likely that most of the actual
  67   processing will be done in the groups.  In these cases, the user entry in
  68   radcheck will be of limited use except for things like setting the user's
  69   password.  So, one might have the following setup:
  70
  71   radcheck table:
  72   joeuser        Cleartext-Password      :=       somepassword
  73
  74   radreply table:
  75   joeuser        Fall-Through       =        Yes
  76
  77   radgroupcheck table:
  78   Check items for various connection scenarios
  79
  80   radgroupreply table:
  81   reply items for the groups
  82
  83   usergroup table:
  84   joeuser      WLANgroup    1(this is the priority)
  85   joeuser      PPPgroup     2
  86
  87
  88 2. What NOT to do.
  89
  90   One of the fields of the SQL schema is named 'op'  This is for the
  91   'operator' used by the attributes.  e.g.:
  92
  93    Framed-IP-Address  =      1.2.3.4
  94    ^ ATTRIBUTE ----^  ^ OP   ^ VALUE
  95
  96   If you want the server to be completely misconfigured, and to never
  97   do what you want, leave the 'op' field blank.  If you want to be
  98   rudely told to RTFM, then post questions on the mailing list, asking
  99
 100   "why doesn't my SQL configuration work when I leave the 'op' field empty?"
 101
 102
 103   The short answer is that with the op field empty, the server does
 104   not know what you want it to do with the attribute.  Should it be
 105   added to the reply?  Maybe you wanted to compare the operator to one
 106   in the request?   The server simply doesn't know.
 107
 108   So put a value in the field.  The value is the string form of the
 109   operator: "=", ">=", etc.  See Section 4, below, for more details.
 110
 111
 112 3. Authentication versus Authorization
 113
 114   Many people ask if they can "authenticate" users to their SQL
 115   database.  The answer to this question is "You're asking the wrong
 116   question."
 117
 118   An SQL database stores information.  An SQL database is NOT an
 119   authentication server.  The ONLY users who should be able to
 120   authenticate themselves to the database are the people who
 121   administer it.  Most administrators do NOT want every user to be
 122   able to access the database, which means that most users will not be
 123   able to "authenticate" themselves to the database.
 124
 125   Instead, the users will have their authorization information (name,
 126   password, configuration) stored in the database.  The configuration
 127   files for FreeRADIUS contain a username and password used to
 128   authenticate FreeRADIUS to the SQL server.  (See raddb/sql.conf).
 129   Once the FreeRADIUS authentication server is connected to the SQL
 130   database server, then FreeRADIUS can pull user names and passwords
 131   out of the database, and use that information to perform the
 132   authentication.
 133
 134 4. Operators
 135
 136  The list of operators is given below.
 137
 138  Op     Example and documentation
 139  --     -------------------------
 140
 141  =      "Attribute = Value"
 142
 143         Not allowed as a check item for RADIUS protocol attributes.  It is
 144         allowed for server configuration attributes (Auth-Type, etc), and sets
 145         the value of on attribute, only if there is no other item of the
 146         same attribute.
 147
 148         As a reply item, it means "add the item to the reply list, but
 149         only if there is no other item of the same attribute."
 150
 151
 152  :=     "Attribute := Value"
 153
 154         Always matches as a check item, and replaces in the
 155         configuration items any attribute of the same name.  If no
 156         attribute of that name appears in the request, then this
 157         attribute is added.
 158
 159         As a reply item, it has an identical meaning, but for the
 160         reply items, instead of the request items.
 161
 162  ==     "Attribute == Value"
 163
 164         As a check item, it matches if the named attribute is present
 165         in the request, AND has the given value.
 166
 167         Not allowed as a reply item.
 168
 169
 170  +=     "Attribute += Value"
 171
 172         Always matches as a check item, and adds the current attribute
 173         with value to the list of configuration items.
 174
 175         As a reply item, it has an identical meaning, but the
 176         attribute is added to the reply items.
 177
 178
 179  !=     "Attribute != Value"
 180
 181         As a check item, matches if the given attribute is in the
 182         request, AND does not have the given value.
 183
 184         Not allowed as a reply item.
 185
 186
 187  >      "Attribute > Value"
 188
 189         As a check item, it matches if the request contains an
 190         attribute with a value greater than the one given.
 191
 192         Not allowed as a reply item.
 193
 194
 195  >=     "Attribute >= Value"
 196
 197         As a check item, it matches if the request contains an
 198         attribute with a value greater than, or equal to the one
 199         given.
 200
 201         Not allowed as a reply item.
 202
 203  <      "Attribute < Value"
 204
 205         As a check item, it matches if the request contains an
 206         attribute with a value less than the one given.
 207
 208         Not allowed as a reply item.
 209
 210
 211  <=     "Attribute <= Value"
 212
 213         As a check item, it matches if the request contains an
 214         attribute with a value less than, or equal to the one given.
 215
 216         Not allowed as a reply item.
 217
 218
 219  =~     "Attribute =~ Expression"
 220
 221         As a check item, it matches if the request contains an
 222         attribute which matches the given regular expression.  This
 223         operator may only be applied to string attributes.
 224
 225         Not allowed as a reply item.
 226
 227
 228  !~     "Attribute !~ Expression"
 229
 230         As a check item, it matches if the request contains an
 231         attribute which does not match the given regular expression.
 232         This operator may only be applied to string attributes.
 233
 234         Not allowed as a reply item.
 235
 236
 237  =*     "Attribute =* Value"
 238
 239         As a check item, it matches if the request contains the named
 240         attribute, no matter what the value is.
 241
 242         Not allowed as a reply item.
 243
 244
 245  !*     "Attribute !* Value"
 246
 247         As a check item, it matches if the request does not contain
 248         the named attribute, no matter what the value is.
 249
 250         Not allowed as a reply item.
 251
 252 5. Instances
 253
 254   Just like any other module, multiple instances of the rlm_sql
 255   module can be defined and used wherever you like.
 256
 257   The default .conf files for the different database types,
 258   contain 1 instance without a name like so:
 259   sql {
 260     ...
 261   }
 262
 263   You can create multiple named instances like so:
 264   sql sql_instance1 {
 265     ...
 266   }
 267   sql sql_instance2 {
 268     ...
 269   }
 270
 271   And then you can use a specific instance in radiusd.conf, like
 272   so:
 273   authorize {
 274     ...
 275     sql_instance1
 276     ...
 277   }
 278   accounting {
 279     ...
 280     sql_instance1
 281     sql_instance2
 282     ...
 283   }