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