sipwise
/
kamailio
mirror of https://github.com/sipwise/kamailio.git
1
0
Fork 0
Code Issues Releases Wiki Activity
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.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '9a7f5fc24a'
${ noResults }
kamailio/modules/ipops/doc/ipops_admin.xml

535 lines
13 KiB
Raw Blame History

<?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>
<para>
This module offers operations for handling IP addresses, both IPv4 and IPv6.
</para>
<para>
IPv6 is defined in <ulink url="http://tools.ietf.org/html/rfc2460">RFC 2460</ulink>.
The same IPv6 address can be represented by different ASCII strings, so binary comparison is required.
For example, the following IPv6 addresses are equivalent:
</para>
<itemizedlist>
<listitem>
<para>2001:DB8:0000:0000:0008:0800:200C:417A</para>
</listitem>
<listitem>
<para>2001:DB8:0:0:8:800:200C:417A</para>
</listitem>
<listitem>
<para>2001:DB8::200C:417A</para>
</listitem>
</itemizedlist>
<para>
When using IPv6 in an URI (i.e. a SIP URI) the IP address must be written in "IPv6 reference" format
(which is the textual representation of the IPv6 enclosed between [ ] symbols).
An example is <quote>sip:alice@[2001:DB8:0:0:8:800:200C:417A]</quote>. This allows separation of
address and port number with a :, like <quote>[2001:DB8:0:0:8:800:200C:417A]:5060</quote>.
This module also allows comparing an IPv6 address with its IPv6 reference representation.
</para>
</section>
<section>
<title>Dependencies</title>
<section>
<title>&siprouter; Modules</title>
<para>
The following modules must be loaded before this module:
<itemizedlist>
<listitem>
<para>
<emphasis>No dependencies on other &siprouter; 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 &siprouter; with this module loaded:
<itemizedlist>
<listitem>
<para>
<emphasis>No dependencies on external libraries</emphasis>
</para>
</listitem>
</itemizedlist>
</para>
</section>
</section>
<section>
<title>Parameters</title>
</section>
<section>
<title>Functions</title>
<section>
<title>
<function moreinfo="none">is_ip (ip)</function>
</title>
<para>
Returns TRUE if the argument is a valid IPv4, IPv6 or IPv6 reference. FALSE otherwise.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem>
<para>
<emphasis>ip</emphasis> - String or pseudo-variable containing the IP address to evaluate.
</para>
</listitem>
</itemizedlist>
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
</para>
<example>
<title>
<function>is_ip</function> usage
</title>
<programlisting format="linespecific">
...
if (is_ip($rd)) {
xlog("L_INFO", "RURI domain is an IP address (not a host name/domain)\n");
}
...
</programlisting>
</example>
</section>
<section>
<title>
<function moreinfo="none">is_pure_ip (ip)</function>
</title>
<para>
Returns TRUE if the argument is a valid IPv4 or IPv6. FALSE otherwise.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem>
<para>
<emphasis>ip</emphasis> - String or pseudo-variable containing the IP to evaluate.
</para>
</listitem>
</itemizedlist>
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
</para>
<example>
<title>
<function>is_pure_ip</function> usage
</title>
<programlisting format="linespecific">
...
$var(ip) = "::1";
if (is_pure_ip($var(ip))) {
xlog("L_INFO", "it's IPv4 or IPv6\n");
}
...
</programlisting>
</example>
</section>
<section>
<title>
<function moreinfo="none">is_ipv4 (ip)</function>
</title>
<para>
Returns TRUE if the argument is a valid IPv4. FALSE otherwise.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem>
<para>
<emphasis>ip</emphasis> - String or pseudo-variable containing the IP to evaluate.
</para>
</listitem>
</itemizedlist>
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
</para>
<example>
<title>
<function>is_ipv4</function> usage
</title>
<programlisting format="linespecific">
...
if (is_ipv4("1.2.3.4")) {
xlog("L_INFO", "it's IPv4\n");
}
...
</programlisting>
</example>
</section>
<section>
<title>
<function moreinfo="none">is_ipv6 (ip)</function>
</title>
<para>
Returns TRUE if the argument is a valid IPv6. FALSE otherwise.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem>
<para>
<emphasis>ip</emphasis> - String or pseudo-variable containing the IP to evaluate.
</para>
</listitem>
</itemizedlist>
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
</para>
<example>
<title>
<function>is_ipv6</function> usage
</title>
<programlisting format="linespecific">
...
if (is_ipv6("1080:0:0:0:8:800:200C:417A")) {
xlog("L_INFO", "it's IPv6\n");
}
...
</programlisting>
</example>
</section>
<section>
<title>
<function moreinfo="none">is_ipv6_reference (ip)</function>
</title>
<para>
Returns TRUE if the argument is a valid IPv6 reference. FALSE otherwise.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem>
<para>
<emphasis>ip</emphasis> - String or pseudo-variable containing the IP to evaluate.
</para>
</listitem>
</itemizedlist>
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
</para>
<example>
<title>
<function>is_ipv6_reference</function> usage
</title>
<programlisting format="linespecific">
...
if (is_ipv6_reference("[1080:0:0:0:8:800:200C:417A]")) {
xlog("L_INFO", "it's IPv6 reference\n");
}
...
</programlisting>
</example>
</section>
<section>
<title>
<function moreinfo="none">ip_type (ip)</function>
</title>
<para>
Returns the type of the given IP.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem>
<para>
<emphasis>ip</emphasis> - String or pseudo-variable containing the IP to evaluate.
</para>
</listitem>
</itemizedlist>
<para>Return value:</para>
<itemizedlist>
<listitem>
<para>
<emphasis>1</emphasis> - IPv4
</para>
</listitem>
<listitem>
<para>
<emphasis>2</emphasis> - IPv6
</para>
</listitem>
<listitem>
<para>
<emphasis>3</emphasis> - IPv6 reference
</para>
</listitem>
<listitem>
<para>
<emphasis>-1</emphasis> - invalid IP
</para>
</listitem>
</itemizedlist>
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
</para>
<example>
<title>
<function>ip_type</function> usage
</title>
<programlisting format="linespecific">
...
ip_type($var(myip));
switch($rc) {
case 1:
xlog("L_INFO", "it's IPv4\n");
break;
case 2:
xlog("L_INFO", "it's IPv6\n");
break;
case 3:
xlog("L_INFO", "it's IPv6 reference\n");
break;
case -1:
xlog("L_INFO", it's type invalid\n");
break;
}
...
</programlisting>
</example>
</section>
<section>
<title>
<function moreinfo="none">compare_ips (ip1, ip2)</function>
</title>
<para>
Returns TRUE if both IP addresses are the same. FALSE otherwise.
This function also allows comparing an IPv6 address against an IPv6 reference.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem>
<para>
<emphasis>ip1</emphasis> - String or pseudo-variable containing the first IP to compare.
</para>
</listitem>
<listitem>
<para>
<emphasis>ip2</emphasis> - String or pseudo-variable containing the second IP to compare.
</para>
</listitem>
</itemizedlist>
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
</para>
<example>
<title>
<function>compare_ips</function> usage
</title>
<programlisting format="linespecific">
...
if (compare_ips("1080:0000:0000:0000:0008:0800:200C:417A", "[1080::8:800:200C:417A]")) {
xlog("L_INFO", "both are the same IP\n");
}
...
</programlisting>
</example>
</section>
<section>
<title>
<function moreinfo="none">compare_pure_ips (ip1, ip2)</function>
</title>
<para>
Returns TRUE if both IP's are the same. FALSE otherwise. This function does NOT
allow comparing an IPv6 against an IPv6 reference.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem>
<para>
<emphasis>ip1</emphasis> - String or pseudo-variable containing the first IP address to compare.
</para>
</listitem>
<listitem>
<para>
<emphasis>ip2</emphasis> - String or pseudo-variable containing the second IP address to compare.
</para>
</listitem>
</itemizedlist>
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
</para>
<example>
<title>
<function>compare_pure_ips</function> usage
</title>
<programlisting format="linespecific">
...
if (compare_pure_ips($si, "1080::8:800:200C:417A")) {
xlog("L_INFO", "both are the same IP\n");
}
...
</programlisting>
</example>
</section>
<section>
<title>
<function moreinfo="none">is_ip_rfc1918 (ip)</function>
</title>
<para>
Returns TRUE if the argument is a private IPv4 according to RFC 1918. FALSE otherwise.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem>
<para>
<emphasis>ip</emphasis> - String or pseudo-variable containing the IP to evaluate.
</para>
</listitem>
</itemizedlist>
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
</para>
<example>
<title>
<function>is_ip_rfc1918</function> usage
</title>
<programlisting format="linespecific">
...
if (is_ip_rfc1918("10.0.123.123")) {
xlog("L_INFO", "it's a private IPv4\n");
}
...
</programlisting>
</example>
</section>
<section>
<title>
<function moreinfo="none">is_in_subnet (ip, subnet)</function>
</title>
<para>
Returns TRUE if the first argument is an IP address within the (CIDR notation)
subnet in the second argument. FALSE otherwise.
</para>
<para>Parameters:</para>
<itemizedlist>
<listitem>
<para>
<emphasis>ip</emphasis> - string or pseudo-variable containing the ip to evaluate.
</para>
</listitem>
<listitem>
<para>
<emphasis>subnet</emphasis> - string or pseudo-variable containing the (CIDR notation) subnet to evaluate.
</para>
</listitem>
</itemizedlist>
<para>
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
</para>
<example>
<title>
<function>is_in_subnet</function> usage
</title>
<programlisting format="linespecific">
...
if (is_in_subnet("10.0.123.123", "10.0.123.1/24")) {
xlog("L_INFO", "it's in the subnet\n");
}
...
</programlisting>
</example>
</section>
</section>
</chapter>
Reference in new issue View Git Blame Copy Permalink