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. Miscellaneous configuration
  23
  24   The SQL module has little documentation, sorry.  A helpful
  25   web page is:
  26
  27         http://www.frontios.com/freeradius.html
  28
  29   If anyone has comments on this (or other) documentation, PLEASE
  30   email them to the freeradius-devel list, so that they may be included here.
  31
  32
  33 2. What NOT to do.
  34
  35   One of the fields of the SQL schema is named 'op'  This is for the
  36   'operator' used by the attributes.  e.g.:
  37
  38    Framed-IP-Address  =      1.2.3.4
  39    ^ ATTRIBUTE ----^  ^ OP   ^ VALUE
  40
  41   If you want the server to be completely misconfigured, and to never
  42   do what you want, leave the 'op' field blank.  If you want to be
  43   rudely told to RTFM, then post questions on the mailing list, asking
  44
  45   "why doesn't my SQL configuration work when I leave the 'op' field empty?"
  46
  47
  48   The short answer is that with the op field empty, the server does
  49   not know what you want it to do with the attribute.  Should it be
  50   added to the reply?  Maybe you wanted to compare the operator to one
  51   in the request?   The server simply doesn't know.
  52
  53   So put a value in the field.  The value is the string form of the
  54   operator: "=", ">=", etc.  See Section 4, below, for more details.
  55
  56
  57 3. Authentication versus Authorization
  58
  59   Many people ask if they can "authenticate" users to their SQL
  60   database.  The answer to this question is "You're asking the wrong
  61   question."
  62
  63   An SQL database stores information.  An SQL database is NOT an
  64   authentication server.  The ONLY users who should be able to
  65   authenticate themselves to the database are the people who
  66   administer it.  Most administrators do NOT want every user to be
  67   able to access the database, which means that most users will not be
  68   able to "authenticate" themselves to the database.
  69
  70   Instead, the users will have their authorization information (name,
  71   password, configuration) stored in the database.  The configuration
  72   files for FreeRADIUS contain a username and password used to
  73   authenticate FreeRADIUS to the SQL server.  (See raddb/sql.conf).
  74   Once the FreeRADIUS authentication server is connected to the SQL
  75   database server, then FreeRADIUS can pull user names and passwords
  76   out of the database, and use that information to perform the
  77   authentication.
  78
  79 4. Operators
  80
  81  The list of operators is given below.
  82
  83  Op     Example and documentation
  84  --     -------------------------
  85
  86  =      "Attribute = Value"
  87
  88         Not allowed as a check item for RADIUS protocol attributes.  It is
  89         allowed for server configuration attributes (Auth-Type, etc), and sets
  90         the value of on attribute, only if there is no other item of the
  91         same attribute.
  92
  93         As a reply item, it means "add the item to the reply list, but
  94         only if there is no other item of the same attribute."
  95
  96
  97  :=     "Attribute := Value"
  98
  99         Always matches as a check item, and replaces in the
 100         configuration items any attribute of the same name.  If no
 101         attribute of that name appears in the request, then this
 102         attribute is added.
 103
 104         As a reply item, it has an identical meaning, but for the
 105         reply items, instead of the request items.
 106
 107  ==     "Attribute == Value"
 108
 109         As a check item, it matches if the named attribute is present
 110         in the request, AND has the given value.
 111
 112         Not allowed as a reply item.
 113
 114
 115  +=     "Attribute += Value"
 116
 117         Always matches as a check item, and adds the current attribute
 118         with value to the list of configuration items.
 119
 120         As a reply item, it has an identical meaning, but the
 121         attribute is added to the reply items.
 122
 123
 124  !=     "Attribute != Value"
 125
 126         As a check item, matches if the given attribute is in the
 127         request, AND does not have the given value.
 128
 129         Not allowed as a reply item.
 130
 131
 132  >      "Attribute > Value"
 133
 134         As a check item, it matches if the request contains an
 135         attribute with a value greater than the one given.
 136
 137         Not allowed as a reply item.
 138
 139
 140  >=     "Attribute >= Value"
 141
 142         As a check item, it matches if the request contains an
 143         attribute with a value greater than, or equal to the one
 144         given.
 145
 146         Not allowed as a reply item.
 147
 148  <      "Attribute < Value"
 149
 150         As a check item, it matches if the request contains an
 151         attribute with a value less than the one given.
 152
 153         Not allowed as a reply item.
 154
 155
 156  <=     "Attribute <= Value"
 157
 158         As a check item, it matches if the request contains an
 159         attribute with a value less than, or equal to the one given.
 160
 161         Not allowed as a reply item.
 162
 163
 164  =~     "Attribute =~ Expression"
 165
 166         As a check item, it matches if the request contains an
 167         attribute which matches the given regular expression.  This
 168         operator may only be applied to string attributes.
 169
 170         Not allowed as a reply item.
 171
 172
 173  !~     "Attribute !~ Expression"
 174
 175         As a check item, it matches if the request contains an
 176         attribute which does not match the given regular expression.
 177         This operator may only be applied to string attributes.
 178
 179         Not allowed as a reply item.
 180
 181
 182  =*     "Attribute =* Value"
 183
 184         As a check item, it matches if the request contains the named
 185         attribute, no matter what the value is.
 186
 187         Not allowed as a reply item.
 188
 189
 190  !*     "Attribute !* Value"
 191
 192         As a check item, it matches if the request does not contain
 193         the named attribute, no matter what the value is.
 194
 195         Not allowed as a reply item.
 196