mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
413 lines
11 KiB
413 lines
11 KiB
<?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;
|
|
|
|
]>
|
|
<!-- Domain Module User's Guide -->
|
|
|
|
<chapter>
|
|
|
|
<title>&adminguide;</title>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
<para>
|
|
Domain module implements checks that based on domain table
|
|
determine if a domain is <quote>local</quote>.
|
|
A <quote>local</quote> domain is one that the proxy is
|
|
responsible for. SIP URIs of local users must have hostpart
|
|
that is equal to one of these domains.
|
|
</para>
|
|
<para>
|
|
Domain module reads the contents of domain and domain_attrs
|
|
tables into cache memory when the module is loaded.
|
|
Any changes in domain or domain_attrs tables must thus be
|
|
followed by <quote>domain.reload</quote> rpc command in
|
|
order to reflect them in module behavior.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<para>
|
|
The module depends on the following modules (in the other words the
|
|
listed modules must be loaded before this module):
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>database</emphasis> -- Any database module</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Parameters</title>
|
|
<section>
|
|
<title><varname>db_url</varname> (string)</title>
|
|
<para>
|
|
This is <acronym>URL</acronym> of the database to be used.
|
|
</para>
|
|
<para>
|
|
Default value is
|
|
<quote>&defaultrodb;</quote>
|
|
</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>domain_table</varname> (string)</title>
|
|
<para>
|
|
Name of table containing names of local domains that the proxy is
|
|
responsible for.
|
|
</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>
|
|
<title><varname>domain_attrs_table</varname> (string)</title>
|
|
<para>
|
|
Name of table containing attributes of local domains.
|
|
</para>
|
|
<para>
|
|
Default value is <quote>domain_attrs</quote>.
|
|
</para>
|
|
<example>
|
|
<title>Setting domain_attrs_table parameter</title>
|
|
<programlisting format="linespecific">
|
|
modparam("domain", "domain_attrs_table", "local_domain_attributes")
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>did_col</varname> (string)</title>
|
|
<para>
|
|
Name of column containing domain id (did) of domain in domain
|
|
and domain_attrs tables. In domain table, a did column value
|
|
may be NULL, which means that it has same value as
|
|
domain column.
|
|
</para>
|
|
<para>
|
|
Default value is <quote>did</quote>.
|
|
</para>
|
|
<example>
|
|
<title>Setting did_col parameter</title>
|
|
<programlisting format="linespecific">
|
|
modparam("domain", "did_col", "domain_did")
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>domain_col</varname> (string)</title>
|
|
<para>
|
|
Name of column containing domain name in domain table.
|
|
</para>
|
|
<para>
|
|
Default value is <quote>domain</quote>.
|
|
</para>
|
|
<example>
|
|
<title>Setting domain_col parameter</title>
|
|
<programlisting format="linespecific">
|
|
modparam("domain", "domain_col", "domain_name")
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>name_col</varname> (string)</title>
|
|
<para>
|
|
Name of column containing attribute name in domain_attrs table.
|
|
</para>
|
|
<para>
|
|
Default value is <quote>name</quote>.
|
|
</para>
|
|
<example>
|
|
<title>Setting name_col parameter</title>
|
|
<programlisting format="linespecific">
|
|
modparam("domain", "name_col", "attr_name")
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>type_col</varname> (string)</title>
|
|
<para>
|
|
Name of column containing attribute type in domain_attrs table.
|
|
Type value 0 is integer and type value 2 is string.
|
|
</para>
|
|
<para>
|
|
Default value is <quote>type</quote>.
|
|
</para>
|
|
<example>
|
|
<title>Setting name_col parameter</title>
|
|
<programlisting format="linespecific">
|
|
modparam("domain", "type_col", "attr_type")
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>value_col</varname> (string)</title>
|
|
<para>
|
|
Name of column containing attribute value in domain_attrs table.
|
|
</para>
|
|
<para>
|
|
Default value is <quote>value</quote>.
|
|
</para>
|
|
<example>
|
|
<title>Setting value_col parameter</title>
|
|
<programlisting format="linespecific">
|
|
modparam("domain", "value_col", "attr_value")
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<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>
|
|
|
|
|
|
</section>
|
|
<section>
|
|
<title>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>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
|
|
BRANCH_ROUTE, and LOCAL_ROUTE.
|
|
</para>
|
|
<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>
|
|
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()
|
|
is called.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
|
|
BRANCH_ROUTE, and LOCAL_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title>is_uri_host_local usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (is_uri_host_local()) {
|
|
...
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><function moreinfo="none">is_domain_local(pseudo_variable)</function></title>
|
|
<para>
|
|
This function checks if the domain contained in the
|
|
pseudo_variable is local.
|
|
</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
|
|
be taken from any of the above mentioned sources.
|
|
The following equivalences exist:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
is_domain_local("$rd") is same as is_uri_host_local()
|
|
</para></listitem>
|
|
<listitem><para>
|
|
is_domain_local("$fd") is same as is_from_local()
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
|
|
BRANCH_ROUTE, and LOCAL_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title>is_domain_local usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (is_domain_local("$rd")) {
|
|
...
|
|
};
|
|
if (is_domain_local("$fd")) {
|
|
...
|
|
};
|
|
if (is_domain_local("$avp(some_avp_alias)")) {
|
|
...
|
|
};
|
|
if (is_domain_local("$avp(i:850)")) {
|
|
...
|
|
};
|
|
if (is_domain_local("$avp(s:some_avp)")) {
|
|
...
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><function moreinfo="none">lookup_domain(domain[, prefix])</function></title>
|
|
<para>
|
|
This function checks if domain given in
|
|
domain argument (pseudo variable) is local and, if so,
|
|
adds attributes
|
|
associated with domain's id (did) to AVPs. If prefix
|
|
argument (string) is given, names of attributes are prefixes by
|
|
it. In addition to attributes given in domain_attrs
|
|
table, AVP did containing did of domain is added.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
|
|
BRANCH_ROUTE, and LOCAL_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title>lookup_domain</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (lookup_domain("$fd", "from_")) {
|
|
xlog("L_INFO", "did of domain $fd is $avp(from_did)\n");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>MI 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>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:domain_reload:_reply_fifo_file_
|
|
_empty_line_
|
|
</programlisting>
|
|
|
|
</section>
|
|
<section>
|
|
<title><function moreinfo="none">domain_dump</function></title>
|
|
<para>
|
|
Causes domain module to dump hash indexes and domain names in
|
|
its cache memory.
|
|
</para>
|
|
<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>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<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>
|
|
<title>Known Limitations</title>
|
|
<para>
|
|
There is an unlikely race condition on domain reload. If a
|
|
process uses a table, which is reloaded at the same time twice
|
|
through <acronym>FIFO</acronym> or <acronym>RPC</acronym>,
|
|
the second reload will delete the
|
|
original table still in use by the process.
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
|