<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section id="overview" xreflabel="Overview">
		<title>Overview</title>
		<para>
		This module provides functionalities for different methods of group
		membership checking.
		</para>
		<section>
			<title>Strict membership checking</title>
			<para>
			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.
			</para>
			<para>
			There is no DB caching support, each check involving a DB query.
			</para>
		</section>
		<section>
			<title>Regular Expression based checking</title>
			<para>
			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) .
			</para>
			<para>
			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.
			</para>
		</section>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				A database module, like mysql, postgres or dbtext.
			</para>
			</listitem>
			<listitem>
			<para>
				An AAA module, like radius or diameter.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before
		running &osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>

	<section id="param_db_url" xreflabel="db_url">
		<title><varname>db_url</varname> (string)</title>
		<para>
		&url; of the database table to be used.
		</para>

		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">

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

</programlisting>
		</example>
	</section>

	<section id="param_table" xreflabel="table">
		<title><varname>table</varname> (string)</title>
		<para>
		Name of the table holding strict definitions of groups and
		their members.
		</para>
		<para>
		<emphasis>
			Default value is <quote>grp</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>table</varname> parameter</title>
		<programlisting format="linespecific">

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

</programlisting>
		</example>
	</section>

	<section id="param_user_column" xreflabel="user_column">
		<title><varname>user_column</varname> (string)</title>
		<para>
		Name of the <quote>table</quote> column holding usernames.
		</para>
		<para>
		<emphasis>
			Default value is <quote>username</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>user_column</varname> parameter</title>
		<programlisting format="linespecific">

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

</programlisting>
		</example>
	</section>

	<section id="param_domain_column" xreflabel="domain_column">
		<title><varname>domain_column</varname> (string)</title>
		<para>
		Name of the <quote>table</quote> column holding domains.
		</para>
		<para>
		<emphasis>
			Default value is <quote>domain</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>domain_column</varname> parameter</title>
		<programlisting format="linespecific">

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

</programlisting>
		</example>
	</section>

	<section id="param_group_column" xreflabel="group_column">
		<title><varname>group_column</varname> (string)</title>
		<para>
		Name of the <quote>table</quote> column holding groups.
		</para>
		<para>
		<emphasis>
			Default value is <quote>grp</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>group_column</varname> parameter</title>
		<programlisting format="linespecific">

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

</programlisting>
		</example>
	</section>

	<section id="param_use_domain" xreflabel="use_domain">
		<title><varname>use_domain</varname> (integer)</title>
		<para>
		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.
		</para>
		<para>
		<emphasis>
			Default value is 0 (no).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>use_domain</varname> parameter</title>
		<programlisting format="linespecific">

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

</programlisting>
		</example>
	</section>

	<section id="param_re_table" xreflabel="re_table">
		<title><varname>re_table</varname> (string)</title>
		<para>
		Name of the table holding definitions for regular-expression
		based groups. If no table is defined, the regular-expression
		support is disabled.
		</para>
		<para>
		<emphasis>
			Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>re_table</varname> parameter</title>
		<programlisting format="linespecific">

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

</programlisting>
		</example>
	</section>

	<section id="param_re_exp_column" xreflabel="re_exp_column">
		<title><varname>re_exp_column</varname> (string)</title>
		<para>
		Name of the <quote>re_table</quote> column holding the regular
		expression used for user matching.
		</para>
		<para>
		<emphasis>
			Default value is <quote>reg_exp</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>re_exp_column</varname> parameter</title>
		<programlisting format="linespecific">

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

</programlisting>
		</example>
	</section>

	<section id="param_re_gid_column" xreflabel="re_gid_column">
		<title><varname>re_gid_column</varname> (string)</title>
		<para>
		Name of the <quote>re_table</quote> column holding the group IDs.
		</para>
		<para>
		<emphasis>
			Default value is <quote>group_id</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>re_gid_column</varname> parameter</title>
		<programlisting format="linespecific">

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

</programlisting>
		</example>
	</section>

	<section id="param_multiple_gid" xreflabel="multiple_gid">
		<title><varname>multiple_gid</varname> (integer)</title>
		<para>
		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.
		</para>
		<para>
		<emphasis>
			Default value is <quote>1</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>multiple_gid</varname> parameter</title>
		<programlisting format="linespecific">

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

</programlisting>
		</example>
	</section>
	<section id="param_aaa_url" xreflabel="aaa_url">
		<title><varname>aaa_url</varname> (string)</title>
		<para>
			This is the url representing the AAA protocol used and the location of the configuration file of this protocol.
		</para>
		<example>
		<title>Set <varname>aaa_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("group", "aaa_url", "radius:/etc/radiusclient-ng/radiusclient.conf")
...

</programlisting>
		</example>
	</section>
	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_db_is_user_in" xreflabel="db_is_user_in()">
		<title>
		<function moreinfo="none">db_is_user_in(uri, group)</function>
		</title>
		<para>
		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.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>uri (string)</emphasis> - a SIP &uri; whose
				username and optionally domain to be used.  Possible values:
			<itemizedlist>
				<listitem>
				<para>"Request-URI" - Use Request-URI username and
				(optionally) domain.</para>
				</listitem>
				<listitem>
				<para>"To" - Use To username and (optionally) domain.</para>
				</listitem>
				<listitem>
				<para>"From" - Use From username and (optionally) domain.</para>
				</listitem>
				<listitem>
				<para>"Credentials" - Use digest credentials username.</para>
				</listitem>
				<listitem>
				<para>(default) - parse the given input as a SIP URI</para>
				</listitem>
			</itemizedlist>
			</para>
		</listitem>
		<listitem>
			<para><emphasis>group (string)</emphasis> - the group to check
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>db_is_user_in</function> usage</title>
		<programlisting format="linespecific">

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

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

</programlisting>
		</example>
	</section>


	<section id="func_db_get_user_group" xreflabel="db_get_user_group()">
		<title>
		<function moreinfo="none">db_get_user_group(uri, output_avp)</function>
		</title>
		<para>
		This function is to be used for regular expression based group
		membership, using DB support.  The function returns true if the username in
		the given "uri" belongs to at least one group.</para>
		<para>All matching group IDs
		shall be returned in "output_avp" if <xref linkend="param_multiple_gid"/>
		is enabled, otherwise only the first one to match (the records are
		attempted in reversed order of the results returned by the RDBMS).
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>uri (string)</emphasis> - a SIP &uri; to be matched
				against the regular expressions:
			<itemizedlist>
				<listitem>
				<para>"Request-URI" - Use Request-URI</para>
				</listitem>
				<listitem>
				<para>"To" - Use To URI.</para>
				</listitem>
				<listitem>
				<para>"From" - Use From URI</para>
				</listitem>
				<listitem>
				<para>"Credentials" - Use digest credentials username
				and realm.</para>
				</listitem>
				<listitem>
				<para>(default) - parse the given input as a SIP URI</para>
				</listitem>
			</itemizedlist>
			</para>
		</listitem>
		<listitem>
			<para><emphasis>output_avp (var)</emphasis> - a list of matched
				group IDs
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>db_get_user_group</function> usage</title>
		<programlisting format="linespecific">

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

</programlisting>
		</example>
	</section>
	<section id="func_aaa_is_user_in" xreflabel="aaa_is_user_in()">
		<title>
		<function moreinfo="none">aaa_is_user_in(uri, group)</function>
		</title>
		<para>
		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.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>uri (string)</emphasis> - a SIP &uri; whose
				username and optionally domain to be used, this can be one of:
			<itemizedlist>
				<listitem>
				<para>"Request-URI" - Use Request-URI username and
				(optionally) domain.</para>
				</listitem>
				<listitem>
				<para>"To" - Use To username and (optionally) domain.</para>
				</listitem>
				<listitem>
				<para>"From" - Use From username and (optionally) domain.</para>
				</listitem>
				<listitem>
				<para>"Credentials" - Use digest credentials username.</para>
				</listitem>
			</itemizedlist>
			</para>
		</listitem>
		<listitem>
			<para><emphasis>group (string)</emphasis> - Name of the group to check.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>aaa_is_user_in</function> usage</title>
		<programlisting format="linespecific">

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

</programlisting>
		</example>
	</section>
	</section>


</chapter>

