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 schemas are available in raddb/sql/<DB>/*, where <DB> is the
25 name of the database (mysql, postgresql, etc.)
27 The SQL module employs two sets of check and reply item tables for
28 processing in the authorization stage. One set of tables (radcheck and
29 radreply) are specific to a single user. The other set of tables
30 (radgroupcheck and radgroupreply) is used to apply check and reply items
31 to users that are members of a certain SQL group. The usergroup table
32 provides the list of groups each user is a member of along with a priority
33 field to control the order in which groups are processed.
35 When a request comes into the server and is processed by the SQL module,
36 the flow goes something like this:
38 1. Search the radcheck table for any check attributes specific to the user
39 2. If check attributes are found, and there's a match, pull the reply items
40 from the radreply table for this user and add them to the reply
41 3. Group processing then begins if any of the following conditions are met:
42 a. The user IS NOT found in radcheck
43 b. The user IS found in radcheck, but the check items don't match
44 c. The user IS found in radcheck, the check items DO match AND
45 Fall-Through is set in the radreply table
46 d. The user IS found in radcheck, the check items DO match AND
47 the read_groups directive is set to 'yes'
48 4. If groups are to be processed for this user, the first thing that is
49 done is the list of groups this user is a member of is pulled from the
50 usergroup table ordered by the priority field. The priority field of
51 the usergroup table allows us to control the order in which groups are
52 processed, so that we can emulate the ordering in the users file. This
53 can be important in many cases.
54 5. For each group this user is a member of, the corresponding check items
55 are pulled from radgroupcheck table and compared with the request. If
56 there is a match, the reply items for this group are pulled from the
57 radgroupreply table and applied.
58 6. Processing continues to the next group IF:
59 a. There was not a match for the last group's check items OR
60 b. Fall-Through was set in the last group's reply items
61 (The above is exactly the same as in the users file)
62 7. Finally, if the user has a User-Profile attribute set or the Default
63 Profile option is set in the sql.conf, then steps 4-6 are repeated for
64 the groups that the profile is a member of.
66 For any fairly complex setup, it is likely that most of the actual
67 processing will be done in the groups. In these cases, the user entry in
68 radcheck will be of limited use except for things like setting the user's
69 password. So, one might have the following setup:
72 joeuser Cleartext-Password := somepassword
75 joeuser Fall-Through = Yes
78 Check items for various connection scenarios
81 reply items for the groups
84 joeuser WLANgroup 1(this is the priority)
90 One of the fields of the SQL schema is named 'op' This is for the
91 'operator' used by the attributes. e.g.:
93 Framed-IP-Address = 1.2.3.4
94 ^ ATTRIBUTE ----^ ^ OP ^ VALUE
96 If you want the server to be completely misconfigured, and to never
97 do what you want, leave the 'op' field blank. If you want to be
98 rudely told to RTFM, then post questions on the mailing list, asking
100 "why doesn't my SQL configuration work when I leave the 'op' field empty?"
103 The short answer is that with the op field empty, the server does
104 not know what you want it to do with the attribute. Should it be
105 added to the reply? Maybe you wanted to compare the operator to one
106 in the request? The server simply doesn't know.
108 So put a value in the field. The value is the string form of the
109 operator: "=", ">=", etc. See Section 4, below, for more details.
112 3. Authentication versus Authorization
114 Many people ask if they can "authenticate" users to their SQL
115 database. The answer to this question is "You're asking the wrong
118 An SQL database stores information. An SQL database is NOT an
119 authentication server. The ONLY users who should be able to
120 authenticate themselves to the database are the people who
121 administer it. Most administrators do NOT want every user to be
122 able to access the database, which means that most users will not be
123 able to "authenticate" themselves to the database.
125 Instead, the users will have their authorization information (name,
126 password, configuration) stored in the database. The configuration
127 files for FreeRADIUS contain a username and password used to
128 authenticate FreeRADIUS to the SQL server. (See raddb/sql.conf).
129 Once the FreeRADIUS authentication server is connected to the SQL
130 database server, then FreeRADIUS can pull user names and passwords
131 out of the database, and use that information to perform the
136 The list of operators is given below.
138 Op Example and documentation
139 -- -------------------------
141 = "Attribute = Value"
143 Not allowed as a check item for RADIUS protocol attributes. It is
144 allowed for server configuration attributes (Auth-Type, etc), and sets
145 the value of on attribute, only if there is no other item of the
148 As a reply item, it means "add the item to the reply list, but
149 only if there is no other item of the same attribute."
152 := "Attribute := Value"
154 Always matches as a check item, and replaces in the
155 configuration items any attribute of the same name. If no
156 attribute of that name appears in the request, then this
159 As a reply item, it has an identical meaning, but for the
160 reply items, instead of the request items.
162 == "Attribute == Value"
164 As a check item, it matches if the named attribute is present
165 in the request, AND has the given value.
167 Not allowed as a reply item.
170 += "Attribute += Value"
172 Always matches as a check item, and adds the current attribute
173 with value to the list of configuration items.
175 As a reply item, it has an identical meaning, but the
176 attribute is added to the reply items.
179 != "Attribute != Value"
181 As a check item, matches if the given attribute is in the
182 request, AND does not have the given value.
184 Not allowed as a reply item.
187 > "Attribute > Value"
189 As a check item, it matches if the request contains an
190 attribute with a value greater than the one given.
192 Not allowed as a reply item.
195 >= "Attribute >= Value"
197 As a check item, it matches if the request contains an
198 attribute with a value greater than, or equal to the one
201 Not allowed as a reply item.
203 < "Attribute < Value"
205 As a check item, it matches if the request contains an
206 attribute with a value less than the one given.
208 Not allowed as a reply item.
211 <= "Attribute <= Value"
213 As a check item, it matches if the request contains an
214 attribute with a value less than, or equal to the one given.
216 Not allowed as a reply item.
219 =~ "Attribute =~ Expression"
221 As a check item, it matches if the request contains an
222 attribute which matches the given regular expression. This
223 operator may only be applied to string attributes.
225 Not allowed as a reply item.
228 !~ "Attribute !~ Expression"
230 As a check item, it matches if the request contains an
231 attribute which does not match the given regular expression.
232 This operator may only be applied to string attributes.
234 Not allowed as a reply item.
237 =* "Attribute =* Value"
239 As a check item, it matches if the request contains the named
240 attribute, no matter what the value is.
242 Not allowed as a reply item.
245 !* "Attribute !* Value"
247 As a check item, it matches if the request does not contain
248 the named attribute, no matter what the value is.
250 Not allowed as a reply item.
254 Just like any other module, multiple instances of the rlm_sql
255 module can be defined and used wherever you like.
257 The default .conf files for the different database types,
258 contain 1 instance without a name like so:
263 You can create multiple named instances like so:
271 And then you can use a specific instance in radiusd.conf, like