# &adminguide;

## Overview

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

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

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

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- A database module, like db_mysql, db_postgres or db_text

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- None.

## Parameters

### `db_url` (string)

&url; of the database table to be used.

Default value is &defaultrodb;.

#### Set `db_url` parameter

    ...
    modparam("group", "db_url", "&exampledb;")
    ...

### `table` (string)

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

Default value is grp.

#### Set `table` parameter

    ...
    modparam("group", "table", "grp_table")
    ...

### `user_column` (string)

Name of the table column holding usernames.

Default value is username.

#### Set `user_column` parameter

    ...
    modparam("group", "user_column", "user")
    ...

### `domain_column` (string)

Name of the table column holding domains.

Default value is domain.

#### Set `domain_column` parameter

    ...
    modparam("group", "domain_column", "realm")
    ...

### `group_column` (string)

Name of the table column holding group names.

Default value is grp.

#### Set `group_column` parameter

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

### `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).

#### Set `use_domain` parameter

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

### `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.

#### Set `re_table` parameter

    ...
    modparam("group", "re_table", "re_grp")
    ...

### `re_exp_column` (string)

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

Default value is reg_exp.

#### Set `re_exp_column` parameter

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

### `re_gid_column` (string)

Name of the re_table column holding the group IDs.

Default value is group_id.

#### Set `re_gid_column` parameter

    ...
    modparam("group", "re_gid_column", "grp_id")
    ...

### `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).

#### Set `multiple_gid` parameter

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

## Functions

### `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.

#### `is_user_in` usage

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

### `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.

#### `get_user_group` usage

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