diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/modules/rlm_sql | 283 | ||||
| -rw-r--r-- | doc/modules/rlm_sqlcounter | 182 | ||||
| -rw-r--r-- | doc/modules/rlm_sqlippool | 40 |
3 files changed, 505 insertions, 0 deletions
diff --git a/doc/modules/rlm_sql b/doc/modules/rlm_sql new file mode 100644 index 0000000..0f06660 --- /dev/null +++ b/doc/modules/rlm_sql @@ -0,0 +1,283 @@ + SQL Module + +0. Introduction + + The SQL module is composed of two parts: a generic SQL front-end + (rlm_sql), and a series of database-dependent back-end drivers, + (rlm_sql_mysql, rlm_sql_postgresql, etc.) + + In order to build the drivers, you MUST ALSO install the development + versions of the database. That is, you must have the appropriate + header files and client libraries for (say) MySQL. The + rlm_sql_mysql driver is NOT a complete MySQL client implementation. + Instead, it is a small 'shim' between the FreeRADIUS rlm_sql module, + and the MySQL client libraries. + + + In general, the SQL schemas mirror the layout of the 'users' file. + So for configuring check items and reply items, see 'man 5 users', + and the examples in the 'users' file. + + +1. Schema and usage + + The schemas are available in raddb/sql/<DB>/*, where <DB> is the + name of the database (mysql, postgresql, etc.) + + The SQL module employs two sets of check and reply item tables for + processing in the authorization stage. One set of tables (radcheck and + radreply) are specific to a single user. The other set of tables + (radgroupcheck and radgroupreply) is used to apply check and reply items + to users that are members of a certain SQL group. The usergroup table + provides the list of groups each user is a member of along with a priority + field to control the order in which groups are processed. + + When a request comes into the server and is processed by the SQL module, + the flow goes something like this: + + 1. Search the radcheck table for any check attributes specific to the user + 2. If check attributes are found, and there's a match, pull the reply items + from the radreply table for this user and add them to the reply + 3. Group processing then begins if any of the following conditions are met: + a. The user IS NOT found in radcheck + b. The user IS found in radcheck, but the check items don't match + c. The user IS found in radcheck, the check items DO match AND + Fall-Through is set in the radreply table + d. The user IS found in radcheck, the check items DO match AND + the read_groups directive is set to 'yes' + 4. If groups are to be processed for this user, the first thing that is + done is the list of groups this user is a member of is pulled from the + usergroup table ordered by the priority field. The priority field of + the usergroup table allows us to control the order in which groups are + processed, so that we can emulate the ordering in the users file. This + can be important in many cases. + 5. For each group this user is a member of, the corresponding check items + are pulled from radgroupcheck table and compared with the request. If + there is a match, the reply items for this group are pulled from the + radgroupreply table and applied. + 6. Processing continues to the next group IF: + a. There was not a match for the last group's check items OR + b. Fall-Through was set in the last group's reply items + (The above is exactly the same as in the users file) + 7. Finally, if the user has a User-Profile attribute set or the Default + Profile option is set in the sql.conf, then steps 4-6 are repeated for + the groups that the profile is a member of. + + For any fairly complex setup, it is likely that most of the actual + processing will be done in the groups. In these cases, the user entry in + radcheck will be of limited use except for things like setting the user's + password. So, one might have the following setup: + + radcheck table: + joeuser Cleartext-Password := somepassword + + radreply table: + joeuser Fall-Through = Yes + + radgroupcheck table: + Check items for various connection scenarios + + radgroupreply table: + reply items for the groups + + usergroup table: + joeuser WLANgroup 1(this is the priority) + joeuser PPPgroup 2 + + +2. What NOT to do. + + One of the fields of the SQL schema is named 'op' This is for the + 'operator' used by the attributes. e.g.: + + Framed-IP-Address = 1.2.3.4 + ^ ATTRIBUTE ----^ ^ OP ^ VALUE + + If you want the server to be completely misconfigured, and to never + do what you want, leave the 'op' field blank. If you want to be + rudely told to RTFM, then post questions on the mailing list, asking + + "why doesn't my SQL configuration work when I leave the 'op' field empty?" + + + The short answer is that with the op field empty, the server does + not know what you want it to do with the attribute. Should it be + added to the reply? Maybe you wanted to compare the operator to one + in the request? The server simply doesn't know. + + So put a value in the field. The value is the string form of the + operator: "=", ">=", etc. See Section 4, below, for more details. + + +3. Authentication versus Authorization + + Many people ask if they can "authenticate" users to their SQL + database. The answer to this question is "You're asking the wrong + question." + + An SQL database stores information. An SQL database is NOT an + authentication server. The ONLY users who should be able to + authenticate themselves to the database are the people who + administer it. Most administrators do NOT want every user to be + able to access the database, which means that most users will not be + able to "authenticate" themselves to the database. + + Instead, the users will have their authorization information (name, + password, configuration) stored in the database. The configuration + files for FreeRADIUS contain a username and password used to + authenticate FreeRADIUS to the SQL server. (See raddb/sql.conf). + Once the FreeRADIUS authentication server is connected to the SQL + database server, then FreeRADIUS can pull user names and passwords + out of the database, and use that information to perform the + authentication. + +4. Operators + + The list of operators is given below. + + Op Example and documentation + -- ------------------------- + + = "Attribute = Value" + + Not allowed as a check item for RADIUS protocol attributes. It is + allowed for server configuration attributes (Auth-Type, etc), and sets + the value of on attribute, only if there is no other item of the + same attribute. + + As a reply item, it means "add the item to the reply list, but + only if there is no other item of the same attribute." + + + := "Attribute := Value" + + Always matches as a check item, and replaces in the + configuration items any attribute of the same name. If no + attribute of that name appears in the request, then this + attribute is added. + + As a reply item, it has an identical meaning, but for the + reply items, instead of the request items. + + == "Attribute == Value" + + As a check item, it matches if the named attribute is present + in the request, AND has the given value. + + Not allowed as a reply item. + + + += "Attribute += Value" + + Always matches as a check item, and adds the current attribute + with value to the list of configuration items. + + As a reply item, it has an identical meaning, but the + attribute is added to the reply items. + + + != "Attribute != Value" + + As a check item, matches if the given attribute is in the + request, AND does not have the given value. + + Not allowed as a reply item. + + + > "Attribute > Value" + + As a check item, it matches if the request contains an + attribute with a value greater than the one given. + + Not allowed as a reply item. + + + >= "Attribute >= Value" + + As a check item, it matches if the request contains an + attribute with a value greater than, or equal to the one + given. + + Not allowed as a reply item. + + < "Attribute < Value" + + As a check item, it matches if the request contains an + attribute with a value less than the one given. + + Not allowed as a reply item. + + + <= "Attribute <= Value" + + As a check item, it matches if the request contains an + attribute with a value less than, or equal to the one given. + + Not allowed as a reply item. + + + =~ "Attribute =~ Expression" + + As a check item, it matches if the request contains an + attribute which matches the given regular expression. This + operator may only be applied to string attributes. + + Not allowed as a reply item. + + + !~ "Attribute !~ Expression" + + As a check item, it matches if the request contains an + attribute which does not match the given regular expression. + This operator may only be applied to string attributes. + + Not allowed as a reply item. + + + =* "Attribute =* Value" + + As a check item, it matches if the request contains the named + attribute, no matter what the value is. + + Not allowed as a reply item. + + + !* "Attribute !* Value" + + As a check item, it matches if the request does not contain + the named attribute, no matter what the value is. + + Not allowed as a reply item. + +5. Instances + + Just like any other module, multiple instances of the rlm_sql + module can be defined and used wherever you like. + + The default .conf files for the different database types, + contain 1 instance without a name like so: + sql { + ... + } + + You can create multiple named instances like so: + sql sql_instance1 { + ... + } + sql sql_instance2 { + ... + } + + And then you can use a specific instance in radiusd.conf, like + so: + authorize { + ... + sql_instance1 + ... + } + accounting { + ... + sql_instance1 + sql_instance2 + ... + } diff --git a/doc/modules/rlm_sqlcounter b/doc/modules/rlm_sqlcounter new file mode 100644 index 0000000..54ad170 --- /dev/null +++ b/doc/modules/rlm_sqlcounter @@ -0,0 +1,182 @@ +rlm_sqlcounter installation and running guide +by Ram Narula ram@princess1.net +Internet for Education (Thailand) + +*) Pre-requisites: +Make sure to have configured radiusd with rlm_sqlcounter +installed + +> make clean +> ./configure --with-experimental-modules +> make +> make install + +Make sure to have radiusd running properly under sql +and there must be a "sql" entry under accounting{ } section +of radiusd.conf + +*) Configuration: + +[1] Create a text file called sqlcounter.conf in the same +directory where radiusd.conf resides (usually /usr/local/etc/raddb) +with the following content (for mysql): + +#-----# +sqlcounter noresetcounter { + sql_module_instance = sqlcca3 + counter_name = Max-All-Session-Time + check_name = Max-All-Session + reply_name = Session-Timeout + key = User-Name + reset = never + + query = "SELECT SUM(AcctSessionTime) FROM radacct WHERE UserName='%{%k}'" + + } + + +sqlcounter dailycounter { + sql_module_instance = sqlcca3 + driver = "rlm_sqlcounter" + counter_name = Daily-Session-Time + check_name = Max-Daily-Session + reply_name = Session-Timeout + key = User-Name + reset = daily + + query = "SELECT SUM(AcctSessionTime - GREATEST((%b - UNIX_TIMESTAMP(AcctStartTime)), 0)) FROM radacct WHERE UserName='%{%k}' AND UNIX_TIMESTAMP(AcctStartTime) + AcctSessionTime > '%b'" + + } + +sqlcounter monthlycounter { + sql_module_instance = sqlcca3 + counter_name = Monthly-Session-Time + check_name = Max-Monthly-Session + reply_name = Session-Timeout + key = User-Name + reset = monthly + + query = "SELECT SUM(AcctSessionTime - GREATEST((%b - UNIX_TIMESTAMP(AcctStartTime)), 0)) FROM radacct WHERE UserName='%{%k}' AND UNIX_TIMESTAMP(AcctStartTime) + AcctSessionTime > '%b'" + + } + +#-----# + +The respective lines for postgresql are: + +query = "SELECT SUM(AcctSessionTime) FROM radacct WHERE UserName='%{%k}'" +query = "SELECT SUM(AcctSessionTime - GREATEST((%b - EXTRACT(epoch FROM AcctStartTime)), 0)) FROM radacct WHERE UserName='%{%k}' AND EXTRACT(epoch FROM AcctStartTime) + AcctSessionTime > '%b'" +query = "SELECT SUM(AcctSessionTime - GREATEST((%b - EXTRACT(epoch FROM AcctStartTime)), 0)) FROM radacct WHERE UserName='%{%k}' AND EXTRACT(epoch FROM AcctStartTime) + AcctSessionTime > '%b'" + +If you are running postgres 7.x, you may not have a GREATEST function. + +An example of one is: + +CREATE OR REPLACE FUNCTION "greater"(integer, integer) RETURNS integer AS ' +DECLARE + res INTEGER; + one INTEGER := 0; + two INTEGER := 0; +BEGIN + one = $1; + two = $2; + IF one IS NULL THEN + one = 0; + END IF; + IF two IS NULL THEN + two = 0; + END IF; + IF one > two THEN + res := one; + ELSE + res := two; + END IF; + RETURN res; +END; +' LANGUAGE 'plpgsql'; + +[2] Include the above file to radiusd.conf by adding a line in +modules{ } section + +modules { + +$INCLUDE ${confdir}/sqlcounter.conf + +...some other entries here... + +[3] Make sure to have the sqlcounter names under authorize section +like the followings: + +authorize { +...some entries here... +...some entries here... +...some entries here... +...some entries here... + +noresetcounter +dailycounter +monthlycounter +} + +noresetcounter: the counter that never resets, can be used +for real session-time cumulation + +dailycounter: the counter that resets everyday, can be used +for limiting daily access time (eg. 3 hours a day) + +monthlycounter: the counter that resets monthly, can be used for +limiting monthly access time (eg. 50 hours per month) + +You can make your own names and directives for resetting the counter +by reading the sample sqlcounter configuration in +raddb/experimental.conf + + + +*) Implementation: + +Add sqlcounter names to be used into radcheck or radgroupcheck +table appropriately for sql. For users file just follow the +example below. + +Note: The users in the example below must be able to login +normally as the example will only show how to apply sqlcounter +counters. + +Scenarios +[1] username test0001 have total time limit of 15 hours +(user can login as many times as needed but can be online for +total time of 15 hours which is 54000 seconds) +If using normal users file authentication the entry can look like: + +test0001 Max-All-Session := 54000, User-Password == "blah" + Service-Type = Framed-User, + Framed-Protocol = PPP + +or for sql make sure to have Max-All-Session entry under either +radcheck or radgroup check table: +> INSERT into radcheck VALUES ('','test0001','Max-All-Session','54000',':='); + +[2] username test0002 have total time limit of 3 hours a day + +test0002 Max-Daily-Session := 10800, User-Password == "blah" + Service-Type = Framed-User, + Framed-Protocol = PPP +or in sql: +> INSERT into radcheck VALUES ('','test0002','Max-Daily-Session','10800',':='); + + +[3] username test0003 have total time limit of 90 hours a month + +test0003 Max-Monthly-Session := 324000, User-Password == "blah" + Service-Type = Framed-User, + Framed-Protocol = PPP +in sql: +> INSERT into radcheck VALUES ('','test0003','Max-Monthly-Session','10800',':='); + + +Note that Max-All-Session, Max-Daily-Session and Max-Monthly-Session are +definied in sqlcounter.conf + +VERY IMPORTANT: +Accounting must be done via sql or this will not work. diff --git a/doc/modules/rlm_sqlippool b/doc/modules/rlm_sqlippool new file mode 100644 index 0000000..3d2840f --- /dev/null +++ b/doc/modules/rlm_sqlippool @@ -0,0 +1,40 @@ +Welcome to the SQL Based IP Pool module. + +********************************************************************** +As of September 2006 this module is still under some development and +currently is only tested by the developers on PostgreSQL (Version 8.1) + Use it at your own risk! +If plan to attempt to use a DB other than PostgreSQL please expect to +have to do extra work which is not for SQL newbies. +Having said that it works great for us in production and should (with +some work) function correctly with other SQL server types. +********************************************************************** + + +To use the sqlipool module you simply need to have an IP-Pool Attribute +(Keep in mind that its a **CHECK** item, not reply) in the required +configuration file, which is either in files(users), sql or any other +type of configuration schema. + +The initialization of the radippool table is left to the user instead of +being handled inside the module. This allows pool management to be done +from any sql capable programming language and pools can be created, +resized, deleted at run time without radiusd needing to be restarted. + +The only required fields are, pool_name and ip_address. A pool consists +of one or more rows in the table with the same pool_name and a different +ip_address. There is no restriction on which ip addresses/ranges may be in +the same pool, and addresses do not need to be concurrent. + +We are currently using the variable definitions of the xlat module, so +before editing the sqlippool.conf file, please go and read the +variables.rst in the doc/configuration directory. It will help you alot!.. + +As you may noticed, there is a pool-key variable in the config file which +allows you to select which attribute is unique according to your NAS setup. +On a standard dialup NAS this is going to be "NAS-Port" but on an ethernet +or wireless network it will probably be "Calling-Station-Id". Other more +exotic options like "3GPP-IMSI" may also exist depending on your NAS. +The only requirement is that the pool-key must be unique and must be +received in both Access-Request and Accounting packages so that we know to +clear the lease on the ip when the session disconnects. |