group_user.sgml

性能优秀的SIP Proxy

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

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1.7 $</revnumber>
		<date>$Date: 2005/12/06 18:00:39 $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>
	
	<section>
		<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>
	<title>Dependencies</title>
	<section>
		<title>&ser; 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>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before 
		running &ser; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>db_url</varname> (string)</title>
		<para>
		&url; of the database table to be used.
		</para>
		<para>
		<emphasis>
			Default value is 
			<quote>mysql://openserro:openserro@localhost/openser</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("group", "db_url", "mysql://username:password@dbhost/openser")
...
</programlisting>
		</example>
	</section>

	<section>
		<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>
		<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>
		<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>
		<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>
		<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>
		<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>
		<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>reg_exp_column</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("group", "reg_exp_column", "re")
...
</programlisting>
		</example>
	</section>

	<section>
		<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>
		<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>

	<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">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;</emphasis> - &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>
				<listitem>
				<para>$avp[avp_name|avp_alias] - Use the URI from the AVP
				specified by this pseudo-variable.</para>
				</listitem>
			</itemizedlist>
			</para>
		</listitem>
		<listitem>
			<para><emphasis>group</emphasis> - Name of the group to check.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>is_user_in</function> usage</title>
		<programlisting format="linespecific">
...
if (is_user_in("Request-URI", "ld")) {
	...
};
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">get_user_group(URI, AVP)</function>
		</title>
		<para>
		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 on group; the group ID(s) are returned as AVPs.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>&uri;</emphasis> - &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>$avp[avp_name|avp_alias] - Use the URI from the AVP
				specified by this pseudo-variable.</para>
				</listitem>
			</itemizedlist>
			</para>
		</listitem>
		<listitem>
			<para><emphasis>AVP_ID</emphasis> - The matched group IDs are
			returned as AVPs named <quote>AVP</quote>. It accepts a full AVP
			specification: AVP, ID and NAME.
			alias also</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>get_user_group</function> usage</title>
		<programlisting format="linespecific">
...
if (get_user_group("Request-URI", "i:10")) {
    xgdb("User $ru belongs to $avp(i:10[*]) group(s)\n");
    ....
};
...
</programlisting>
		</example>
	</section>
	</section>


</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("group.sgml" "Book" "chapter")
End:
-->