group Module

Jan Janak

   FhG FOKUS

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Jan Janak

   Copyright  2003 FhG FOKUS
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview

              1.1. Strict membership checking
              1.2. Regular Expression based checking

        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. db_url (string)
              3.2. table (string)
              3.3. user_column (string)
              3.4. domain_column (string)
              3.5. group_column (string)
              3.6. use_domain (integer)
              3.7. re_table (string)
              3.8. re_exp_column (string)
              3.9. re_gid_column (string)
              3.10. multiple_gid (integer)

        4. Functions

              4.1. is_user_in(URI, group)
              4.2. get_user_group(URI, AVP)

   List of Examples

   1.1. Set db_url parameter
   1.2. Set table parameter
   1.3. Set user_column parameter
   1.4. Set domain_column parameter
   1.5. Set group_column parameter
   1.6. Set use_domain parameter
   1.7. Set re_table parameter
   1.8. Set re_exp_column parameter
   1.9. Set re_gid_column parameter
   1.10. Set multiple_gid parameter
   1.11. is_user_in usage
   1.12. get_user_group usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview

        1.1. Strict membership checking
        1.2. Regular Expression based checking

   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. db_url (string)
        3.2. table (string)
        3.3. user_column (string)
        3.4. domain_column (string)
        3.5. group_column (string)
        3.6. use_domain (integer)
        3.7. re_table (string)
        3.8. re_exp_column (string)
        3.9. re_gid_column (string)
        3.10. multiple_gid (integer)

   4. Functions

        4.1. is_user_in(URI, group)
        4.2. get_user_group(URI, AVP)

1. Overview

   1.1. Strict membership checking
   1.2. Regular Expression based checking

   This module provides functionality for two different methods of group
   membership checking.

1.1. Strict membership checking

   The module uses a database table that contains a list of users and
   groups they belong to. The module provides the possibility to check if
   a specific user belongs to a specific group.

   There is no DB caching support, which means that each check involves a
   DB query.

1.2. Regular Expression based checking

   Another database table contains list of regular expressions and group
   IDs. A matching occurs if the user URI match the regular expression.
   This type of matching may be used to fetch the group ID(s) the user
   belongs to (via RE matching) .

   Due to performance reasons (regular expression evaluation), DB cache
   support is available: the table content is loaded into memory at
   startup and all regular expressions are compiled.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * A database module, like db_mysql, db_postgres or db_text

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None.

3. Parameters

   3.1. db_url (string)
   3.2. table (string)
   3.3. user_column (string)
   3.4. domain_column (string)
   3.5. group_column (string)
   3.6. use_domain (integer)
   3.7. re_table (string)
   3.8. re_exp_column (string)
   3.9. re_gid_column (string)
   3.10. multiple_gid (integer)

3.1. db_url (string)

   URL of the database table to be used.

   Default value is "mysql://kamailioro:kamailioro@localhost/kamailio".

   Example 1.1. Set db_url parameter
...
modparam("group", "db_url", "dbdriver://username:password@dbhost/dbname")
...

3.2. table (string)

   Name of the table holding strict definitions of groups and their
   members.

   Default value is "grp".

   Example 1.2. Set table parameter
...
modparam("group", "table", "grp_table")
...

3.3. user_column (string)

   Name of the "table" column holding usernames.

   Default value is "username".

   Example 1.3. Set user_column parameter
...
modparam("group", "user_column", "user")
...

3.4. domain_column (string)

   Name of the "table" column holding domains.

   Default value is "domain".

   Example 1.4. Set domain_column parameter
...
modparam("group", "domain_column", "realm")
...

3.5. group_column (string)

   Name of the "table" column holding group names.

   Default value is "grp".

   Example 1.5. Set group_column parameter
...
modparam("group", "group_column", "grp")
...

3.6. use_domain (integer)

   If enabled (set to a non zero value) then the domain will be used also
   used for strict group matching; otherwise only the username part will
   be used.

   Default value is 0 (disabled).

   Example 1.6. Set use_domain parameter
...
modparam("group", "use_domain", 1)
...

3.7. re_table (string)

   Name of the table holding definitions for regular-expression based
   groups. If no table is defined, the regular-expression support is
   disabled.

   Default value is "NULL".

   Example 1.7. Set re_table parameter
...
modparam("group", "re_table", "re_grp")
...

3.8. re_exp_column (string)

   Name of the "re_table" column holding the regular expression used for
   user matching.

   Default value is "reg_exp".

   Example 1.8. Set re_exp_column parameter
...
modparam("group", "re_exp_column", "re")
...

3.9. re_gid_column (string)

   Name of the "re_table" column holding the group IDs.

   Default value is "group_id".

   Example 1.9. Set re_gid_column parameter
...
modparam("group", "re_gid_column", "grp_id")
...

3.10. multiple_gid (integer)

   If enabled (non zero value) the regular-expression matching will return
   all group IDs that match the user; otherwise only the first will be
   returned.

   Default value is "1" (enabled).

   Example 1.10. Set multiple_gid parameter
...
modparam("group", "multiple_gid", 0)
...

4. Functions

   4.1. is_user_in(URI, group)
   4.2. get_user_group(URI, AVP)

4.1. is_user_in(URI, group)

   This function is to be used for script group membership. The function
   returns true if username in the given URI is a member of the given
   group and false if not.

   Meaning of the parameters is as follows:
     * URI - URI whose username and optionally domain to be used, this can
       be one of:
          + Request-URI - Use Request-URI username and (optionally)
            domain.
          + To - Use To username and (optionally) domain.
          + From - Use From username and (optionally) domain.
          + Credentials - Use digest credentials username.
          + $avp(name) - Use the URI from the AVP specified by this
            pseudo-variable.
     * group - Name of the group to check.

   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

   Example 1.11. is_user_in usage
...
if (is_user_in("Request-URI", "ld")) {
        ...
};
...

4.2. get_user_group(URI, AVP)

   This function is to be used for regular expression based group
   membership. The function returns true if username in the given URI
   belongs to at least one group; the group ID(s) are returned as AVPs.

   Meaning of the parameters is as follows:
     * URI - URI to be matched against the regular expressions:
          + Request-URI - Use Request-URI
          + To - Use To URI.
          + From - Use From URI
          + Credentials - Use digest credentials username and realm.
          + $avp(name) - Use the URI from the AVP specified by this
            pseudo-variable.
     * AVP - $avp(name) - the matched group IDs are returned in this AVP.

   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

   Example 1.12. get_user_group usage
...
if (get_user_group("Request-URI", "$avp(i:10)")) {
    xgdb("User $ru belongs to $(avp(i:10)[*]) group(s)\n");
    ....
};
...