group Module


Table of Contents

1. Admin Guide
1.1. Overview
1.1.1. Strict membership checking
1.1.2. Regular Expression based checking
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. db_url (string)
1.3.2. table (string)
1.3.3. user_column (string)
1.3.4. domain_column (string)
1.3.5. group_column (string)
1.3.6. use_domain (integer)
1.3.7. re_table (string)
1.3.8. re_exp_column (string)
1.3.9. re_gid_column (string)
1.3.10. multiple_gid (integer)
1.3.11. aaa_url (string)
1.4. Exported Functions
1.4.1. db_is_user_in(URI, group)
1.4.2. db_get_user_group(URI, AVP)
1.4.3. aaa_is_user_in(URI, group)
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors

List of Tables

2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
2.2. Most recently active contributors(1) to this module

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 reg_exp_column parameter
1.9. Set re_gid_column parameter
1.10. Set multiple_gid parameter
1.11. Set aaa_url parameter
1.12. db_is_user_in usage
1.13. db_get_user_group usage
1.14. aaa_is_user_in usage

Chapter 1. Admin Guide

1.1. Overview

This module provides functionalities for different methods of group membership checking.

1.1.1. Strict membership checking

There is a database table that contains 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, each check involving a DB query.

1.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 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.

1.2. Dependencies

1.2.1. OpenSIPS Modules

The following modules must be loaded before this module:

  • A database module, like mysql, postgres or dbtext.

  • An AAA module, like radius or diameter.

1.2.2. External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

  • None.

1.3. Exported Parameters

1.3.1. db_url (string)

URL of the database table to be used.

Example 1.1. Set db_url parameter

		
...
modparam("group", "db_url", "mysql://username:password@dbhost/opensips")
...


1.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")
...


1.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")
...


1.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")
...


1.3.5. group_column (string)

Name of the table column holding groups.

Default value is grp.

Example 1.5. Set group_column parameter

		
...
modparam("group", "group_column", "grp")
...


1.3.6. use_domain (integer)

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

Default value is 0 (no).

Example 1.6. Set use_domain parameter

		
...
modparam("group", "use_domain", 1)
...


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")
...


1.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 reg_exp_column parameter

		
...
modparam("group", "reg_exp_column", "re")
...


1.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")
...


1.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.

Example 1.10. Set multiple_gid parameter

		
...
modparam("group", "multiple_gid", 0)
...


1.3.11. aaa_url (string)

This is the url representing the AAA protocol used and the location of the configuration file of this protocol.

Example 1.11. Set aaa_url parameter

...
modparam("group", "aaa_url", "radius:/etc/radiusclient-ng/radiusclient.conf")
...


1.4. Exported Functions

1.4.1.  db_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 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. The string may contain a pseudovariable.

This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

Example 1.12. db_is_user_in usage

		
...
if (db_is_user_in("Request-URI", "ld")) {
	...
};
...
$avp(grouptocheck)="offline";

if (db_is_user_in("Credentials", "$avp(grouptocheck)")) {
	...
};
...


1.4.2.  db_get_user_group(URI, AVP)

This function is to be used for regular expression based group membership, using DB support. 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.13. db_get_user_group usage

		
...
if (db_get_user_group("Request-URI", "$avp(10)")) {
    xdbg("User $ru belongs to $(avp(10)[*]) group(s)\n");
    ....
};
...


1.4.3.  aaa_is_user_in(URI, group)

This function checks group membership, using AAA support. The function returns true if username in the given URI is 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.

  • group - Name of the group to check.

This function can be used from REQUEST_ROUTE.

Example 1.14. aaa_is_user_in usage

		
...
if (aaa_is_user_in("Request-URI", "ld")) {
	...
};
...


Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

 NameDevScoreCommitsLines ++Lines --
1. Bogdan-Andrei Iancu (@bogdan-iancu)4631847397
2. Jan Janak (@janakj)34201370148
3. Daniel-Constantin Mierla (@miconda)2518176226
4. Liviu Chircu (@liviuchircu)1294080
5. Irina-Maria Stanescu10446659
6. Razvan Crainea (@razvancrainea)861612
7. Andrei Pelinescu-Onciul7510140
8. Henning Westerholt (@henningw)752746
9. Edson Gellert Schubert510206
10. Jiri Kuthan (@jiriatipteldotorg)4251

All remaining contributors: Sergio Gutierrez, Konstantin Bokarius, Norman Brandinger (@NormB), UnixDev, Anca Vamanu, Dan Pascu (@danpascu), Vlad Patrascu (@rvlad-patrascu).

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

2.2. By Commit Activity

Table 2.2. Most recently active contributors(1) to this module

 NameCommit Activity
1. Bogdan-Andrei Iancu (@bogdan-iancu)Jul 2005 - Jun 2020
2. Razvan Crainea (@razvancrainea)Jun 2011 - Sep 2019
3. Liviu Chircu (@liviuchircu)Mar 2014 - Nov 2018
4. Vlad Patrascu (@rvlad-patrascu)May 2017 - May 2017
5. Irina-Maria StanescuAug 2009 - Dec 2009
6. Anca VamanuSep 2009 - Sep 2009
7. UnixDevFeb 2009 - Feb 2009
8. Sergio GutierrezDec 2008 - Dec 2008
9. Henning Westerholt (@henningw)Aug 2007 - May 2008
10. Daniel-Constantin Mierla (@miconda)Jul 2005 - Mar 2008

All remaining contributors: Konstantin Bokarius, Edson Gellert Schubert, Dan Pascu (@danpascu), Norman Brandinger (@NormB), Jan Janak (@janakj), Andrei Pelinescu-Onciul, Jiri Kuthan (@jiriatipteldotorg).

(1) including any documentation-related commits, excluding merge commits

Chapter 3. Documentation

3.1. Contributors

Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Liviu Chircu (@liviuchircu), Razvan Crainea (@razvancrainea), Irina-Maria Stanescu, Sergio Gutierrez, Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Dan Pascu (@danpascu), Jan Janak (@janakj).

doc copyrights:

Copyright © 2009 Voice Sistem SRL

Copyright © 2003 FhG FOKUS