modules_k/domain/doc/domain_admin.xml
33d03d8d
 <?xml version="1.0" encoding='ISO-8859-1'?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
 
 <!-- Include general documentation entities -->
 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
 %docentities;
 
 ]>
31ccf6a2
 <!-- Domain Module User's Guide -->
 
 <chapter>
033b5989
 	
9fc784c6
 	<title>&adminguide;</title>
31ccf6a2
 	
 	<section>
 	<title>Overview</title>
 	<para>
3d6ab631
 		Domain module implements checks that based on domain table determine 
 		if a host part of an <acronym>URI</acronym> is <quote>local</quote> or 
 		not.  A <quote>local</quote> domain is one that the proxy is responsible 
 		for.
31ccf6a2
 	</para>
 	<para>
3d6ab631
 		Domain module operates in caching or non-caching mode depending on 
 		value of module parameter <parameter moreinfo="none">db_mode</parameter>.
 		In caching mode domain module reads the contents of domain table into 
 		cache memory when the module is loaded.  After that domain table is 
 		re-read only when module is given domain_reload fifo command.  Any
 		changes in domain table must thus be followed by 
 		<quote>domain_reload</quote> command in order to reflect them in 
 		module behavior. In non-caching mode domain module always queries domain
31ccf6a2
 		table in the database.
 	</para>
 	<para>
3d6ab631
 		Caching is implemented using a hash table. The size of the hash table 
 		is given by HASH_SIZE constant defined in domain_mod.h. 
 		Its <quote>factory default</quote> value is 128.
31ccf6a2
 	</para>
 	</section>
3d6ab631
 
31ccf6a2
 	<section>
 	<title>Dependencies</title>
 	<para>
3d6ab631
 		The module depends on the following modules (in the other words the 
 		listed modules must be loaded before this module):
31ccf6a2
 		<itemizedlist>
 		<listitem>
 			<para><emphasis>database</emphasis> -- Any database module</para>
 		</listitem>
 		</itemizedlist>
 	</para>
 	</section>
3d6ab631
 
31ccf6a2
 	<section>
 	<title>Exported Parameters</title>
 	<section>
 		<title><varname>db_url</varname> (string)</title>
 		<para>
 		This is <acronym>URL</acronym> of the database to be used.
 		</para>
 		<para>
3d6ab631
 		Default value is 
 			<quote>mysql://openserro:openserro@localhost/openser</quote>
31ccf6a2
 		</para>
 		<example>
 		<title>Setting db_url parameter</title>
 		<programlisting format="linespecific">
 modparam("domain", "db_url", "mysql://ser:pass@db_host/ser")
 </programlisting>
 		</example>
 	</section>
 	<section>
 		<title><varname>db_mode</varname> (integer)</title>
 		<para>
3d6ab631
 		Database mode: 0 means non-caching, 1 means caching.
31ccf6a2
 		</para>
 		<para>
 		Default value is 0 (non-caching).
 		</para>
 		<example>
164d9185
 		<title>db_mode example</title>
31ccf6a2
 		<programlisting format="linespecific">
 modparam("domain", "db_mode", 1)   # Use caching
 </programlisting>
 		</example>
 	</section>
 	<section>
 		<title><varname>domain_table</varname> (string)</title>
 		<para>
3d6ab631
 		Name of table containing names of local domains that the proxy is 
 		responsible for. Local users must have in their sip uri a host part 
 		that is equal to one of these domains.
31ccf6a2
 		</para>
 		<para>
 		Default value is <quote>domain</quote>.
 		</para>
 		<example>
 		<title>Setting domain_table parameter</title>
 		<programlisting format="linespecific">
 modparam("domain", "domain_table", "new_name")
 </programlisting>
 		</example>
 	</section>
 	<section>
9dea244e
 		<title><varname>domain_col</varname> (string)</title>
31ccf6a2
 		<para>
 		Name of column containing domains in domain table.
 		</para>
 		<para>
 		Default value is <quote>domain</quote>.
 		</para>
 		<example>
9dea244e
 		<title>Setting domain_col parameter</title>
31ccf6a2
 		<programlisting format="linespecific">
9dea244e
 modparam("domain", "domain_col", "domain_name")
31ccf6a2
 </programlisting>
 		</example>
 	</section>
3653a528
 	<section>
 		<title><varname>register_myself</varname> (integer)</title>
 		<para>
 			Register the list of domains to match 'myself' check:
 			0 means no myself registration, 1 means enable myself
 			registration.
 		</para>
 		<para>
 		Default value is 0 (disable).
 		</para>
 		<example>
 		<title>register_myself example</title>
 		<programlisting format="linespecific">
 modparam("domain", "register_myself", 1)
 </programlisting>
 		</example>
 	</section>
 
31ccf6a2
 	
 	</section>
 	<section>
 	<title>Exported Functions</title>
 	<section>
 		<title><function moreinfo="none">is_from_local()</function></title>
 		<para>
 		Checks based on domain table if host part of From header uri is
 		one of the local domains that the proxy is responsible for
 		</para>
791bd4be
 		<para>
 		This function can be used from REQUEST_ROUTE.
 		</para>
31ccf6a2
 		<example>
 		<title>is_from_local usage</title>
 		<programlisting format="linespecific">
 ...
 if (is_from_local()) {
 	...
 };
 ...
 		</programlisting>
 		</example>
 	</section>
 	<section>
 		<title><function moreinfo="none">is_uri_host_local()</function></title>
 		<para>
a60bf348
 		If called from route or failure route block, checks
 		based on domain table if host part of Request-URI is one
 		of the local domains that the proxy is responsible for.
 		If called from branch route, the test is made on host
 		part of URI of first branch, which thus must have been
 		appended to the transaction before is_uri_host_local()
6d954dc8
 		is called.
31ccf6a2
 		</para>
791bd4be
 		<para>
 		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
 		BRANCH_ROUTE.
 		</para>
31ccf6a2
 		<example>
b68fbcd1
 		<title>is_uri_host_local usage</title>
31ccf6a2
 		<programlisting format="linespecific">
 ...
 if (is_uri_host_local()) {
 	...
 };
6d954dc8
 ...
 		</programlisting>
 		</example>
 	</section>
 	<section>
4428ca04
 		<title><function moreinfo="none">is_domain_local(pseudo_variable)</function></title>
6d954dc8
 		<para>
 		This function checks if the domain contained in the
4428ca04
 		pseudo_variable is local.
6d954dc8
 		</para>
 		<para>
 		This function is a generalized form of the is_from_local()
 		and is_uri_host_local() functions, being able to completely
 		replace them and also extends them by allowing the domain to
19952e85
 		be taken from any of the above mentioned sources.
                 The following equivalences exist:
6d954dc8
 		</para>
 		<itemizedlist>
 		<listitem><para>
19952e85
 			is_domain_local("$rd") is same as is_uri_host_local()
6d954dc8
 		</para></listitem>
 		<listitem><para>
19952e85
 			is_domain_local("$fd") is same as is_from_local()
6d954dc8
 		</para></listitem>
 		</itemizedlist>
 		<para>
 		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
 		BRANCH_ROUTE.
 		</para>
 		<example>
 		<title>is_domain_local usage</title>
 		<programlisting format="linespecific">
 ...
19952e85
 if (is_domain_local("$rd")) {
 	...
 };
 if (is_domain_local("$fd")) {
6d954dc8
 	...
 };
19952e85
 if (is_domain_local("$avp(some_avp_alias)")) {
6d954dc8
 	...
 };
19952e85
 if (is_domain_local("$avp(i:850)")) {
6d954dc8
 	...
 };
19952e85
 if (is_domain_local("$avp(s:some_avp)")) {
6d954dc8
 	...
 };
31ccf6a2
 ...
 		</programlisting>
 		</example>
 	</section>
 	</section>
 	<section>
e5495f50
 	<title>Exported MI Functions</title>
31ccf6a2
 	<section>
231d507f
 		<title><function moreinfo="none">domain_reload</function></title>
31ccf6a2
 		<para>
 		Causes domain module to re-read the contents of domain table
 		into cache memory.
 		</para>
231d507f
 		<para>
 		Name: <emphasis>domain_reload</emphasis>
 		</para>
 		<para>Parameters: <emphasis>none</emphasis></para>
  		<para>
 		MI FIFO Command Format:
 		</para>
         <programlisting  format="linespecific">
 		:domain_reload:_reply_fifo_file_
 		_empty_line_
 		</programlisting>
 		
31ccf6a2
 	</section>
 	<section>
231d507f
 		<title><function moreinfo="none">domain_dump</function></title>
31ccf6a2
 		<para>
 		Causes domain module to dump hash indexes and domain names in
 		its cache memory.
 		</para>
231d507f
 		<para>
 		Name: <emphasis>domain_dump</emphasis>
 		</para>
 		<para>Parameters: <emphasis>none</emphasis></para>
  		<para>
 		MI FIFO Command Format:
 		</para>
         <programlisting  format="linespecific">
 		:domain_dump:_reply_fifo_file_
 		_empty_line_
 		</programlisting>
31ccf6a2
 	</section>
 	</section>
 	<section>
d59a7f56
 	<title>Exported RPC Commands</title>
 	<section>
 		<title><function moreinfo="none">domain.reload</function></title>
 		<para>
 		Causes domain module to re-read the contents of domain table
 		into cache memory.
 		</para>
 		<para>
 		Name: <emphasis>domain.reload</emphasis>
 		</para>
 		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
 		Example:
 		</para>
         <programlisting  format="linespecific">
 		sercmd domain.reload
 		</programlisting>
 	</section>
 	<section>
 		<title><function moreinfo="none">domain.dump</function></title>
 		<para>
 		Causes domain module to dump domain names in
 		its cache memory.
 		</para>
 		<para>
 		Name: <emphasis>domain.dump</emphasis>
 		</para>
 		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
 		Example:
 		</para>
         <programlisting  format="linespecific">
 		sercmd domain.dump
 		</programlisting>
 	</section>
 	</section>
 	<section>
31ccf6a2
 	<title>Known Limitations</title>
 	<para>
3d6ab631
 		There is an unlikely race condition on domain list update.  If a 
 		process uses a table, which is reloaded at the same time twice 
 		through <acronym>FIFO</acronym>, the second reload will delete the 
 		original table still in use by the process.
31ccf6a2
 	</para>
 	</section>
 </chapter>