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