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 Cleartext-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)
87 One of the fields of the SQL schema is named 'op' This is for the
88 'operator' used by the attributes. e.g.:
90 Framed-IP-Address = 1.2.3.4
91 ^ ATTRIBUTE ----^ ^ OP ^ VALUE
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
97 "why doesn't my SQL configuration work when I leave the 'op' field empty?"
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.
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.
109 3. Authentication versus Authorization
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
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.
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
133 The list of operators is given below.
135 Op Example and documentation
136 -- -------------------------
138 = "Attribute = Value"
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
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."
149 := "Attribute := Value"
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
156 As a reply item, it has an identical meaning, but for the
157 reply items, instead of the request items.
159 == "Attribute == Value"
161 As a check item, it matches if the named attribute is present
162 in the request, AND has the given value.
164 Not allowed as a reply item.
167 += "Attribute += Value"
169 Always matches as a check item, and adds the current attribute
170 with value to the list of configuration items.
172 As a reply item, it has an identical meaning, but the
173 attribute is added to the reply items.
176 != "Attribute != Value"
178 As a check item, matches if the given attribute is in the
179 request, AND does not have the given value.
181 Not allowed as a reply item.
184 > "Attribute > Value"
186 As a check item, it matches if the request contains an
187 attribute with a value greater than the one given.
189 Not allowed as a reply item.
192 >= "Attribute >= Value"
194 As a check item, it matches if the request contains an
195 attribute with a value greater than, or equal to the one
198 Not allowed as a reply item.
200 < "Attribute < Value"
202 As a check item, it matches if the request contains an
203 attribute with a value less than the one given.
205 Not allowed as a reply item.
208 <= "Attribute <= Value"
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.
213 Not allowed as a reply item.
216 =~ "Attribute =~ Expression"
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.
222 Not allowed as a reply item.
225 !~ "Attribute !~ Expression"
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.
231 Not allowed as a reply item.
234 =* "Attribute =* Value"
236 As a check item, it matches if the request contains the named
237 attribute, no matter what the value is.
239 Not allowed as a reply item.
242 !* "Attribute !* Value"
244 As a check item, it matches if the request does not contain
245 the named attribute, no matter what the value is.
247 Not allowed as a reply item.
251 Just like any other module, multiple instances of the rlm_sql
252 module can be defined and used wherever you like.
254 The default .conf files for the different database types,
255 contain 1 instance without a name like so:
260 You can create multiple named instances like so:
268 And then you can use a specific instance in radiusd.conf, like