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.)
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.
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.
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.
32 When a request comes into the server and is processed by the SQL module,
33 the flow goes something like this:
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.
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:
69 joeuser User-Password == somepassword
72 joeuser Fall-Through = Yes
75 Check items for various connection scenarios
78 reply items for the groups
81 joeuser WLANgroup 1(this is the priority)
84 A web page with some helpful documentation is:
86 http://www.frontios.com/freeradius.html
88 NOTE: this page may be slightly out of date when dealing with the database
94 One of the fields of the SQL schema is named 'op' This is for the
95 'operator' used by the attributes. e.g.:
97 Framed-IP-Address = 1.2.3.4
98 ^ ATTRIBUTE ----^ ^ OP ^ VALUE
100 If you want the server to be completely misconfigured, and to never
101 do what you want, leave the 'op' field blank. If you want to be
102 rudely told to RTFM, then post questions on the mailing list, asking
104 "why doesn't my SQL configuration work when I leave the 'op' field empty?"
107 The short answer is that with the op field empty, the server does
108 not know what you want it to do with the attribute. Should it be
109 added to the reply? Maybe you wanted to compare the operator to one
110 in the request? The server simply doesn't know.
112 So put a value in the field. The value is the string form of the
113 operator: "=", ">=", etc. See Section 4, below, for more details.
116 3. Authentication versus Authorization
118 Many people ask if they can "authenticate" users to their SQL
119 database. The answer to this question is "You're asking the wrong
122 An SQL database stores information. An SQL database is NOT an
123 authentication server. The ONLY users who should be able to
124 authenticate themselves to the database are the people who
125 administer it. Most administrators do NOT want every user to be
126 able to access the database, which means that most users will not be
127 able to "authenticate" themselves to the database.
129 Instead, the users will have their authorization information (name,
130 password, configuration) stored in the database. The configuration
131 files for FreeRADIUS contain a username and password used to
132 authenticate FreeRADIUS to the SQL server. (See raddb/sql.conf).
133 Once the FreeRADIUS authentication server is connected to the SQL
134 database server, then FreeRADIUS can pull user names and passwords
135 out of the database, and use that information to perform the
140 The list of operators is given below.
142 Op Example and documentation
143 -- -------------------------
145 = "Attribute = Value"
147 Not allowed as a check item for RADIUS protocol attributes. It is
148 allowed for server configuration attributes (Auth-Type, etc), and sets
149 the value of on attribute, only if there is no other item of the
152 As a reply item, it means "add the item to the reply list, but
153 only if there is no other item of the same attribute."
156 := "Attribute := Value"
158 Always matches as a check item, and replaces in the
159 configuration items any attribute of the same name. If no
160 attribute of that name appears in the request, then this
163 As a reply item, it has an identical meaning, but for the
164 reply items, instead of the request items.
166 == "Attribute == Value"
168 As a check item, it matches if the named attribute is present
169 in the request, AND has the given value.
171 Not allowed as a reply item.
174 += "Attribute += Value"
176 Always matches as a check item, and adds the current attribute
177 with value to the list of configuration items.
179 As a reply item, it has an identical meaning, but the
180 attribute is added to the reply items.
183 != "Attribute != Value"
185 As a check item, matches if the given attribute is in the
186 request, AND does not have the given value.
188 Not allowed as a reply item.
191 > "Attribute > Value"
193 As a check item, it matches if the request contains an
194 attribute with a value greater than the one given.
196 Not allowed as a reply item.
199 >= "Attribute >= Value"
201 As a check item, it matches if the request contains an
202 attribute with a value greater than, or equal to the one
205 Not allowed as a reply item.
207 < "Attribute < Value"
209 As a check item, it matches if the request contains an
210 attribute with a value less than the one given.
212 Not allowed as a reply item.
215 <= "Attribute <= Value"
217 As a check item, it matches if the request contains an
218 attribute with a value less than, or equal to the one given.
220 Not allowed as a reply item.
223 =~ "Attribute =~ Expression"
225 As a check item, it matches if the request contains an
226 attribute which matches the given regular expression. This
227 operator may only be applied to string attributes.
229 Not allowed as a reply item.
232 !~ "Attribute !~ Expression"
234 As a check item, it matches if the request contains an
235 attribute which does not match the given regular expression.
236 This operator may only be applied to string attributes.
238 Not allowed as a reply item.
241 =* "Attribute =* Value"
243 As a check item, it matches if the request contains the named
244 attribute, no matter what the value is.
246 Not allowed as a reply item.
249 !* "Attribute !* Value"
251 As a check item, it matches if the request does not contain
252 the named attribute, no matter what the value is.
254 Not allowed as a reply item.
258 Just like any other module, multiple instances of the rlm_sql
259 module can be defined and used wherever you like.
261 The default .conf files for the different database types,
262 contain 1 instance without a name like so:
267 You can create multiple named instances like so:
275 And then you can use a specific instance in radiusd.conf, like