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.
1167 lines
32 KiB
1167 lines
32 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;
|
|
|
|
]>
|
|
<!-- Module User's Guide -->
|
|
|
|
<chapter>
|
|
|
|
<title>&adminguide;</title>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
<section id="sec-call-routing">
|
|
<title>Call Routing</title>
|
|
<para>
|
|
The module can be used to determine if a call has appropriate
|
|
permission to be established. Permission rules are stored in
|
|
plaintext configuration files similar to
|
|
<filename moreinfo="none">hosts.allow</filename> and <filename
|
|
moreinfo="none">hosts.deny</filename> files used by tcpd.
|
|
</para>
|
|
<para>
|
|
When <function moreinfo="none">allow_routing</function> function is
|
|
called it tries to find a rule that matches selected fields of the
|
|
message.
|
|
</para>
|
|
<para>
|
|
&kamailio; is a forking proxy and therefore a single message can be sent
|
|
to different destinations simultaneously. When checking permissions
|
|
all the destinations must be checked and if one of them fails, the
|
|
forwarding will fail.
|
|
</para>
|
|
<para>
|
|
The matching algorithm is as follows, first match wins:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Create a set of pairs of form (From, R-URI of branch 1),
|
|
(From, R-URI of branch 2), etc.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Routing will be allowed when all pairs match an entry in the
|
|
allow file.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Otherwise routing will be denied when one of pairs matches an
|
|
entry in the deny file.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Otherwise, routing will be allowed.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
A non-existing permission control file is treated as if it were an
|
|
empty file. Thus, permission control can be turned off by providing
|
|
no permission control files.
|
|
</para>
|
|
<para>
|
|
From header field and Request-URIs are always compared with regular
|
|
expressions! For the syntax see the sample file:
|
|
<filename moreinfo="none">config/permissions.allow</filename>.
|
|
</para>
|
|
</section>
|
|
<section id="sec-registration-permissions">
|
|
<title>Registration Permissions</title>
|
|
<para>
|
|
In addition to call routing it is also possible to check REGISTER
|
|
messages and decide--based on the configuration files--whether the
|
|
message should be allowed and the registration accepted or not.
|
|
</para>
|
|
<para>
|
|
Main purpose of the function is to prevent registration of "prohibited"
|
|
IP addresses. One example, when a malicious user registers a contact
|
|
containing IP address of a PSTN gateway, he might be able to bypass
|
|
authorization checks performed by the SIP proxy. That is undesirable
|
|
and therefore attempts to register IP address of a PSTN gateway should
|
|
be rejected. Files <filename
|
|
moreinfo="none">config/register.allow</filename> and <filename
|
|
moreinfo="none">config/register.deny</filename> contain an example
|
|
configuration.
|
|
</para>
|
|
<para>
|
|
Function for registration checking is called <function
|
|
moreinfo="none">allow_register</function> and the algorithm is very
|
|
similar to the algorithm described in
|
|
<xref linkend="sec-call-routing"/>. The only difference is in the way
|
|
how pairs are created.
|
|
</para>
|
|
<para>
|
|
Instead of From header field the function uses To header field because
|
|
To header field in REGISTER messages contains the URI of the person
|
|
being registered. Instead of the Request-URI of branches the function
|
|
uses Contact header field.
|
|
</para>
|
|
<para>
|
|
Thus, pairs used in matching will look like this: (To, Contact 1),
|
|
(To, Contact 2), (To, Contact 3), and so on..
|
|
</para>
|
|
<para>
|
|
The algorithm of matching is same as described in
|
|
<xref linkend="sec-call-routing"/>.
|
|
</para>
|
|
</section>
|
|
<section id="sec-uri-permissions">
|
|
<title>URI Permissions</title>
|
|
<para>
|
|
The module can be used to determine if request is
|
|
allowed to the destination specified by an URI stored in
|
|
a pvar. Permission rules are stored in
|
|
plaintext configuration files similar to
|
|
<filename moreinfo="none">hosts.allow</filename> and
|
|
<filename moreinfo="none">hosts.deny</filename> used by tcpd.
|
|
</para>
|
|
<para>
|
|
When <function moreinfo="none">allow_uri</function>
|
|
function is called, it tries to find a rule that matches
|
|
selected fields of the message.
|
|
The matching algorithm is as follows, first match wins:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Create a pair <From URI, URI stored in pvar>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Request will be allowed when the pair matches
|
|
an entry in the allow file.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Otherwise request will be denied when the pair
|
|
matches an entry in the deny file.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Otherwise, request will be allowed.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
A non-existing permission control file is treated as if it were an
|
|
empty file. Thus, permission control can be turned off by providing
|
|
no permission control files.
|
|
</para>
|
|
<para>
|
|
From URI and URI stored in pvar are always compared with regular
|
|
expressions! For the syntax see the sample file:
|
|
<filename moreinfo="none">config/permissions.allow</filename>.
|
|
</para>
|
|
</section>
|
|
<section id="sec-address-permissions">
|
|
<title>Address Permissions</title>
|
|
<para>
|
|
The module can be used to determine if an address (IP
|
|
address and port) matches any of the IP subnets
|
|
stored in cached openser database table.
|
|
Port 0 in cached database table matches any port. IP
|
|
address and port to be matched can be either taken from
|
|
the request (allow_source_address) or given as pvar
|
|
arguments (allow_address).
|
|
</para>
|
|
<para>
|
|
Addresses stored in cached database table can be grouped
|
|
together into one or more groups specified by a group
|
|
identifier (positive integer value, i.e., equal or greater than 1).
|
|
Group identifier is given as argument to allow_address and
|
|
allow_source_address functions.
|
|
</para>
|
|
<para>
|
|
As a side effect of matching the address, non-NULL tag
|
|
(see tag_col module parameter) is added as value to
|
|
peer_tag AVP if peer_tag_avp module parameter has been defined.
|
|
</para>
|
|
</section>
|
|
<section id="sec-trusted-requests">
|
|
<title>Trusted Requests</title>
|
|
<para>
|
|
The module can be used to determine if an incoming
|
|
request can be trusted without authentication.
|
|
</para>
|
|
<para>
|
|
When <function moreinfo="none">allow_trusted</function>
|
|
function is called, it tries to find a rule that matches
|
|
the request. Rules contain the following fields:
|
|
<source address, transport protocol, regular
|
|
expression>.
|
|
</para>
|
|
<para>
|
|
A requests is accepted if there exists a rule, where
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
source address is equal to source address of
|
|
request or source address given in pvar,
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
transport protocol is either "ANY" or equal to
|
|
transport protocol of request or transport
|
|
protocol given in pvar, and
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
regular expression is either empty (NULL in
|
|
database) or matches From URI of request.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Otherwise the request is rejected.
|
|
</para>
|
|
<para>
|
|
As a side effect of accepting the request, peer's
|
|
non-NULL tag (see tag_col module parameter) is added as value to
|
|
peer_tag AVP if peer_tag_avp module parameter has been defined.
|
|
</para>
|
|
<para>
|
|
Rules are stored in a database table specified by module
|
|
parameters. There also exists a module parameter
|
|
<varname>dm_mode</varname> that
|
|
determines if rules are cached into memory for faster
|
|
matching or if database is consulted for each invocation
|
|
of allow_trusted function call.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<section>
|
|
<title>&kamailio; Modules</title>
|
|
<para>
|
|
The following modules must be loaded before this module:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>No dependencies on other &kamailio; modules</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>External Libraries or Applications</title>
|
|
<para>
|
|
The following libraries or applications must be installed before running
|
|
&kamailio; with this module loaded:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>None</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Parameters</title>
|
|
<section>
|
|
<title><varname>default_allow_file</varname> (string)</title>
|
|
<para>
|
|
Default allow file used by functions without parameters. If you
|
|
don't specify full pathname then the directory in which is the main
|
|
config file is located will be used.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>permissions.allow</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>default_allow_file</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "default_allow_file", "/etc/permissions.allow")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>default_deny_file</varname> (string)</title>
|
|
<para>
|
|
Default file containing deny rules. The file is used by functions
|
|
without parameters. If you don't specify full pathname then the
|
|
directory in which the main config file is located will be used.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>permissions.deny</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>default_deny_file</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "default_deny_file", "/etc/permissions.deny")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>check_all_branches</varname> (integer)</title>
|
|
<para>
|
|
If set then allow_routing functions will check Request-URI of all
|
|
branches (default). If disabled then only Request-URI of the first
|
|
branch will be checked.
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
Do not disable this parameter unless you really know what you
|
|
are doing.
|
|
</para>
|
|
</warning>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 1.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>check_all_branches</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "check_all_branches", 0)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>allow_suffix</varname> (string)</title>
|
|
<para>
|
|
Suffix to be appended to basename to create filename of the allow
|
|
file when version with one parameter of either
|
|
<function moreinfo="none">allow_routing</function> or
|
|
<function moreinfo="none">allow_register</function> is used.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Including leading dot.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>.allow</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>allow_suffix</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "allow_suffix", ".allow")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>deny_suffix</varname> (string)</title>
|
|
<para>
|
|
Suffix to be appended to basename to create filename of the deny file
|
|
when version with one parameter of either
|
|
<function moreinfo="none">allow_routing</function> or
|
|
<function moreinfo="none">allow_register</function> is used.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Including leading dot.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>.deny</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>deny_suffix</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "deny_suffix", ".deny")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>db_url</varname> (string)</title>
|
|
<para>
|
|
This is URL of the database to be used to store rules used by
|
|
<function moreinfo="none">allow_trusted</function> function.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>NULL</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_url</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "db_url", "&exampledb;")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>address_table</varname> (string)</title>
|
|
<para>
|
|
Name of database table containing IP subnet information used by
|
|
<function moreinfo="none">allow_address</function> and
|
|
<function moreinfo="none">allow_source_address</function>
|
|
functions.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>address</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>address_table</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "address_table", "addr")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>grp_col</varname> (string)</title>
|
|
<para>
|
|
Name of address table column containing group
|
|
identifier of the address.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>grp</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>grp_col</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "grp_col", "group_id")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>ip_addr_col</varname> (string)</title>
|
|
<para>
|
|
Name of address table column containing IP address
|
|
part of the address.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>ip_addr</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>ip_addr_col</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "ip_addr_col", "ip_address")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>mask_col</varname> (string)</title>
|
|
<para>
|
|
Name of address table column containing network mask of
|
|
the address. Possible values are 0-32.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>mask</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>mask_col</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "mask_col", "subnet_length")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>port_col</varname> (string)</title>
|
|
<para>
|
|
Name of address table column containing port
|
|
part of the address.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>port</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>port_col</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "port_col", "prt")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>db_mode</varname> (integer)</title>
|
|
<para>
|
|
Database mode. 0 means non-caching, 1 means caching.
|
|
Valid only for allow_trusted function.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 0 (non-caching).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_mode</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "db_mode", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>trusted_table</varname> (string)</title>
|
|
<para>
|
|
Name of database table containing matching rules used by
|
|
<function moreinfo="none">allow_trusted</function> function.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>trusted</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>trusted_table</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "trusted_table", "pbx")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>source_col</varname> (string)</title>
|
|
<para>
|
|
Name of trusted table column containing source IP
|
|
address that is matched against source IP address of
|
|
received request.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>src_ip</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>source_col</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "source_col", "source_ip_address")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>proto_col</varname> (string)</title>
|
|
<para>
|
|
Name of trusted table column containing transport
|
|
protocol that is matched against transport protocol of
|
|
received request. Possible values that can be stored in
|
|
proto_col are <quote>any</quote>, <quote>udp</quote>,
|
|
<quote>tcp</quote>, <quote>tls</quote>,
|
|
<quote>sctp</quote>, and <quote>none</quote>. Value
|
|
<quote>any</quote> matches always and value
|
|
<quote>none</quote> never.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>proto</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>proto_col</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "proto_col", "transport")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>from_col</varname> (string)</title>
|
|
<para>
|
|
Name of trusted table column containing regular
|
|
expression that is matched against From URI.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>from_pattern</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>from_col</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "from_col", "regexp")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>tag_col</varname> (string)</title>
|
|
<para>
|
|
Name of address or trusted table column containing a string
|
|
that is added as value to peer_tag AVP if peer_tag AVP
|
|
has been defined and if the address or peer matches.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>tag</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>tag_col</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "tag_col", "peer_tag")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>peer_tag_avp</varname> (AVP string)</title>
|
|
<para>
|
|
If defined, the AVP will be
|
|
set as side effect of allow_trusted() call to not NULL
|
|
tag column value of the matching peer.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>undefined</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>peer_tag_avp</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "peer_tag_avp", "$avp(i:707)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>peer_tag_mode</varname> (integer)</title>
|
|
<para>
|
|
Tag mode for allow_trusted(). 0 sets only the tag of the
|
|
first match. 1 adds the tags of all matches to the avp. In addition
|
|
the return value of allow_trusted() is the number of matches.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>peer_tag_mode</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("permissions", "peer_tag_mode", "1")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Functions</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">allow_routing()</function>
|
|
</title>
|
|
<para>
|
|
Returns true if all pairs constructed as described in <xref
|
|
linkend="sec-call-routing"/> have appropriate permissions according to
|
|
the configuration files. This function uses default configuration
|
|
files specified in <varname>default_allow_file</varname> and
|
|
<varname>default_deny_file</varname>.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>allow_routing</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (allow_routing()) {
|
|
t_relay();
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">allow_routing(basename)</function>
|
|
</title>
|
|
<para>
|
|
Returns true if all pairs constructed as described in <xref
|
|
linkend="sec-call-routing"/> have appropriate permissions according
|
|
to the configuration files given as parameters.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>basename</emphasis> - Basename from which allow
|
|
and deny filenames will be created by appending contents of
|
|
<varname>allow_suffix</varname> and <varname>deny_suffix</varname>
|
|
parameters.
|
|
</para>
|
|
<para>
|
|
If the parameter doesn't contain full pathname then the function
|
|
expects the file to be located in the same directory as the main
|
|
configuration file of the server.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>allow_routing(basename)</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (allow_routing("basename")) {
|
|
t_relay();
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">allow_routing(allow_file,deny_file)</function>
|
|
</title>
|
|
<para>
|
|
Returns true if all pairs constructed as described in
|
|
<xref linkend="sec-call-routing"/> have appropriate permissions
|
|
according to the configuration files given as parameters.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>allow_file</emphasis> - File containing allow rules.
|
|
</para>
|
|
<para>
|
|
If the parameter doesn't contain full pathname then the function
|
|
expects the file to be located in the same directory as the main
|
|
configuration file of the server.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>deny_file</emphasis> - File containing deny rules.
|
|
</para>
|
|
<para>
|
|
If the parameter doesn't contain full pathname then the function
|
|
expects the file to be located in the same directory as the main
|
|
configuration file of the server.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>allow_routing(allow_file, deny_file)</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (allow_routing("rules.allow", "rules.deny")) {
|
|
t_relay();
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">allow_register(basename)</function>
|
|
</title>
|
|
<para>
|
|
The function returns true if all pairs constructed as described in <xref
|
|
linkend="sec-registration-permissions"/> have appropriate permissions
|
|
according to the configuration files given as parameters.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>basename</emphasis> - Basename from which allow
|
|
and deny filenames will be created by appending contents of
|
|
<varname>allow_suffix</varname> and <varname>deny_suffix</varname>
|
|
parameters.
|
|
</para>
|
|
<para>
|
|
If the parameter doesn't contain full pathname then the function
|
|
expects the file to be located in the same directory as the main
|
|
configuration file of the server.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>allow_register(basename)</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (method=="REGISTER") {
|
|
if (allow_register("register")) {
|
|
save("location");
|
|
exit;
|
|
} else {
|
|
sl_send_reply("403", "Forbidden");
|
|
};
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">allow_register(allow_file, deny_file)</function>
|
|
</title>
|
|
<para>
|
|
The function returns true if all pairs constructed as described in
|
|
<xref linkend="sec-registration-permissions"/> have appropriate
|
|
permissions according to the configuration files given as parameters.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>allow_file</emphasis> - File containing allow rules.
|
|
</para>
|
|
<para>
|
|
If the parameter doesn't contain full pathname then the function
|
|
expects the file to be located in the same directory as the main
|
|
configuration file of the server.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>deny_file</emphasis> - File containing deny rules.
|
|
</para>
|
|
<para>
|
|
If the parameter doesn't contain full pathname then the function
|
|
expects the file to be located in the same directory as the main
|
|
configuration file of the server.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>allow_register(allow_file, deny_file)</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (method=="REGISTER") {
|
|
if (allow_register("register.allow", "register.deny")) {
|
|
save("location");
|
|
exit;
|
|
} else {
|
|
sl_send_reply("403", "Forbidden");
|
|
};
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">allow_uri(basename, pvar)</function>
|
|
</title>
|
|
<para>
|
|
Returns true if the pair constructed as described in <xref
|
|
linkend="sec-uri-permissions"/> have appropriate permissions
|
|
according to the configuration files specified by the parameter.
|
|
</para>
|
|
<para>Meaning of the parameter is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>basename</emphasis> - Basename from which allow
|
|
and deny filenames will be created by appending contents of
|
|
<varname>allow_suffix</varname> and <varname>deny_suffix</varname>
|
|
parameters.
|
|
</para>
|
|
<para>
|
|
If the parameter doesn't contain full pathname then the function
|
|
expects the file to be located in the same directory as the main
|
|
configuration file of the server.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>pvar</emphasis> - Any
|
|
pseudo-variable defined in &kamailio;.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>allow_uri(basename, pvar)</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (allow_uri("basename", "$rt")) { // Check Refer-To URI
|
|
t_relay();
|
|
};
|
|
if (allow_uri("basename", "$avp(i:705)") { // Check URI stored in $avp(i:705)
|
|
t_relay();
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">allow_address(group_id, ip_addr_pvar, port_pvar)</function>
|
|
</title>
|
|
<para>
|
|
Returns true if IP address and port given as values of pvar
|
|
arguments belonging to a group given as group_id argument
|
|
matches an IP subnet found in cached address table.
|
|
Cached address table entry containing port value 0
|
|
matches any port. group_id argument can be an integer
|
|
string or a pseudo variable.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>allow_address()</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
|
|
// Check if source address/port is in group 1
|
|
if (!allow_address("1", "$si", "$sp")) {
|
|
sl_send_reply("403", "Forbidden");
|
|
};
|
|
// Check IP address/port stored in AVPs i:704/i:705 is in group 2
|
|
if (!allow_address("2", "$avp(i:704)", "$avp(i:705)") {
|
|
sl_send_reply("403", "Forbidden");
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">allow_source_address([group_id])</function>
|
|
</title>
|
|
<para>
|
|
Equal to allow_address(group_id, "$si", "$sp"). If 'group_id' is
|
|
missing, the function is equal to allow_address("1", "$si", "$sp").
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>allow_source_address(group_id)</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
|
|
// Check source address/port of request
|
|
if (!allow_source_address("1")) {
|
|
sl_send_reply("403", "Forbidden");
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">allow_source_address_group()</function>
|
|
</title>
|
|
<para>
|
|
Checks if source address/port is found in cached address or
|
|
subnet table in any group. If yes, returns that group.
|
|
If not returns -1. Port value 0 in cached address and
|
|
group table matches any port.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>allow_source_address_group()</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
|
|
$var(group) = allow_source_address_group();
|
|
if ($var(group) != -1) {
|
|
# do something with $var(group)
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">allow_trusted([src_ip_pvar, proto_pvar])</function>
|
|
</title>
|
|
<para>
|
|
Checks based either on request's source address and transport
|
|
protocol or source address and transport protocol given
|
|
in pvar arguments, and From URI of request
|
|
if request can be trusted without
|
|
authentication. Returns 1 if a match is found
|
|
as described in <xref linkend="sec-trusted-requests"/>
|
|
and -1 otherwise. If a match is found
|
|
and peer_tag_avp has been defined, adds a
|
|
non-NULL tag column value of the
|
|
matching peer to AVP peer_tag_avp.
|
|
</para>
|
|
<para>
|
|
Source address and transport protocol given in pvar
|
|
arguments must be in string format. Valid transport
|
|
protocol values are (ignoring case) "any", "udp, "tcp", "tls",
|
|
and "sctp".
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>allow_trusted()</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (allow_trusted()) {
|
|
t_relay();
|
|
};
|
|
...
|
|
if (allow_trusted("$si", "$proto")) {
|
|
t_relay();
|
|
};
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>MI Commands</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">address_reload</function>
|
|
</title>
|
|
<para>
|
|
Causes permissions module to re-read the contents of
|
|
address database table into cache
|
|
memory. In cache memory the entries are
|
|
for performance reasons stored in two
|
|
different tables: address table and
|
|
subnet table depending on the value of
|
|
the mask field (32 or smaller).
|
|
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">address_dump</function>
|
|
</title>
|
|
<para>
|
|
Causes permissions module to dump
|
|
contents of cache memory address table.
|
|
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">subnet_dump</function>
|
|
</title>
|
|
<para>
|
|
Causes permissions module to dump
|
|
contents of cache memory subnet table.
|
|
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">trusted_reload</function>
|
|
</title>
|
|
<para>
|
|
Causes permissions module to re-read the contents of
|
|
trusted table into cache memory.
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">trusted_dump</function>
|
|
</title>
|
|
<para>
|
|
Causes permissions module to dump contents of trusted
|
|
table from cache memory.
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">allow_uri</function>
|
|
</title>
|
|
<para>
|
|
Tests if (URI, Contact) pair is allowed according to
|
|
allow/deny files. The files must already have been
|
|
loaded by &kamailio;.
|
|
</para>
|
|
<para>Parameters: </para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>basename</emphasis> -
|
|
Basename from
|
|
which allow and deny filenames will be created by
|
|
appending contents of allow_suffix and deny_suffix
|
|
parameters.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>URI</emphasis> - URI to be tested
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>Contact</emphasis> - Contact
|
|
to be tested
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
|