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