siputils

Hardy Kahl

   1&1 Internet AG

Henning Westerholt

   1&1 Internet AG

Nils Ohlmeier

   FhG Fokus

Jan Janak

   FhG FOKUS

Daniel-Constantin Mierla

   Asipto SRL

Gabriel Vasile

   FhG FOKUS

Edited by

Jan Janak

Edited by

Bogdan-Andrei Iancu

Edited by

Gabriel Vasile

   Copyright © 2008, 2005, 2003 1&1 Internet AG, FhG Fokus,
   voice-system.ro
   Revision History
   Revision $Revision: 4872 $ $Date: 2008-09-09 17:39:38 +0200
                              (Di, 09 Sep 2008) $
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. Kamailio Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. ring_timeout (int)
              1.3.2. options_accept (string)
              1.3.3. options_accept_encoding (string)
              1.3.4. contact_flds_separator (string)
              1.3.5. options_accept_language (string)
              1.3.6. options_support (string)

        1.4. Exported Functions

              1.4.1. ring_insert_callid()
              1.4.2. options_reply()
              1.4.3. is_user(username)
              1.4.4. has_totag()
              1.4.5. uri_param(param)
              1.4.6. uri_param(param,value)
              1.4.7. add_uri_param(param)
              1.4.8. tel2sip()
              1.4.9. is_uri_user_e164(pseudo-variable)
              1.4.10. encode_contact(encoding_prefix)
              1.4.11. decode_contact()
              1.4.12. decode_contact_header()
              1.4.13. cmp_uri(str1, str2)
              1.4.14. cmp_aor(str1, str2)

   List of Examples

   1.1. Set ring_timeout parameter
   1.2. Set options_accept parameter
   1.3. Set options_accept_encoding parameter
   1.4. Set db_url parameter
   1.5. Set options_accept_language parameter
   1.6. Set options_support parameter
   1.7. ring_insert_callid() usage
   1.8. options_reply usage
   1.9. is_user usage
   1.10. has_totag usage
   1.11. uri_param usage
   1.12. uri_param usage
   1.13. add_uri_param usage
   1.14. tel2sip usage
   1.15. is_uri_user_e164 usage
   1.16. encode_contact usage
   1.17. decode_contact usage
   1.18. decode_contact_header usage
   1.19. cmp_uri usage
   1.20. cmp_aor usage

Chapter 1. Admin Guide

1.1. Overview

   This module implement various functions and checks related to
   SIP message handling and URI handling.

   It offers some functions related to handle ringing. In a
   parallel forking scenario you get several 183s with SDP. You
   don't want that your customers hear more than one ringtone or
   answer machine in parallel on the phone. So its necessary to
   drop the 183 in this cases and send a 180 instead.

   This module provides a function to answer OPTIONS requests
   which are directed to the server itself. This means an OPTIONS
   request which has the address of the server in the request URI,
   and no username in the URI. The request will be answered with a
   200 OK which the capabilities of the server.

   To answer OPTIONS request directed to your server is the
   easiest way for is-alive-tests on the SIP (application) layer
   from remote (similar to ICMP echo requests, also known as
   "ping", on the network layer).

1.2. Dependencies

1.2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * sl -- Stateless replies.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running Kamailio with this module loaded:
     * None.

1.3. Exported Parameters

1.3.1. ring_timeout (int)

   Timeout value in seconds, define how long the call-id is stored
   in the internal list. A reasonable value is "30".

   Default value is "0".

   Example 1.1. Set ring_timeout parameter
...
modparam("siputils", "ring_timeout", 30)
...

1.3.2. options_accept (string)

   This parameter is the content of the Accept header field. Note:
   it is not clearly written in RFC3261 if a proxy should accept
   any content (the default "*/*") because it does not care about
   content. Or if it does not accept any content, which is "".

   Default value is "*/*".

   Example 1.2. Set options_accept parameter
...
modparam("siputils", "options_accept", "application/*")
...

1.3.3. options_accept_encoding (string)

   This parameter is the content of the Accept-Encoding header
   field. Please do not change the default value because Kamailio
   does not support any encodings yet.

   Default value is "".

   Example 1.3. Set options_accept_encoding parameter
...
modparam("siputils", "options_accept_encoding", "gzip")
...

1.3.4. contact_flds_separator (string)

   First char of this parameter is used as separator for
   encoding/decoding Contact header.

Warning

   First char of this field must be set to a value which is not
   used inside username,password or other fields of contact.
   Otherwise it is possible for the decoding step to fail/produce
   wrong results.

   Default value is "*".

   Example 1.4. Set db_url parameter
...
modparam("siputils", "contact_flds_separator", "-")
...

   then an encoded uri might look
   sip:user-password-ip-port-protocol@PublicIP

1.3.5. options_accept_language (string)

   This parameter is the content of the Accept-Language header
   field. You can set any language code which you prefer for error
   descriptions from other devices, but presumably there are not
   much devices around which support other languages then the
   default English.

   Default value is "en".

   Example 1.5. Set options_accept_language parameter
...
modparam("siputils", "options_accept_language", "de")
...

1.3.6. options_support (string)

   This parameter is the content of the Support header field.
   Please do not change the default value, because Kamailio
   currently does not support any of the SIP extensions registered
   at the IANA.

   Default value is "".

   Example 1.6. Set options_support parameter
...
modparam("siputils", "options_support", "100rel")
...

1.4. Exported Functions

1.4.1.  ring_insert_callid()

   Inserting the call-id in the internal list, which is checked
   when further replies arrive. Any 183 reply that is received
   during the timeout value will be converted to a 180 message,
   the SDP body is removed as well. Please not that you need to
   set a positive timeout value in order to use this function.

   The function returns TRUE on success, and FALSE during
   processing failures.

   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

   Example 1.7. ring_insert_callid() usage
...
ring_insert_callid();
...

1.4.2.  options_reply()

   This function checks if the request method is OPTIONS and if
   the request URI does not contain an username. If both is true
   the request will be answered stateless with "200 OK" and the
   capabilities from the modules parameters.

   It sends "500 Server Internal Error" for some errors and
   returns false if it is called for a wrong request.

   The check for the request method and the missing username is
   optional because it is also done by the function itself. But
   you should not call this function outside the myself check
   because in this case the function could answer OPTIONS requests
   which are sent to you as outbound proxy but with an other
   destination then your proxy (this check is currently missing in
   the function).

   This function can be used from REQUEST_ROUTE.

   Example 1.8. options_reply usage
...
if (uri==myself) {
        if ((method==OPTIONS) && (! uri=~"sip:.*[@]+.*")) {
                options_reply();
        }
}
...

1.4.3.  is_user(username)

   Check if the username in credentials matches the given
   username.

   Meaning of the parameters is as follows:
     * username - Username string.

   This function can be used from REQUEST_ROUTE.

   Example 1.9. is_user usage
...
if (is_user("john")) {
        ...
};
...

1.4.4.  has_totag()

   Check if To header field uri contains tag parameter.

   This function can be used from REQUEST_ROUTE.

   Example 1.10. has_totag usage
...
if (has_totag()) {
        ...
};
...

1.4.5.  uri_param(param)

   Find if Request URI has a given parameter with no value

   Meaning of the parameters is as follows:
     * param - parameter name to look for.

   This function can be used from REQUEST_ROUTE.

   Example 1.11. uri_param usage
...
if (uri_param("param1")) {
        ...
};
...

1.4.6.  uri_param(param,value)

   Find if Request URI has a given parameter with matching value

   Meaning of the parameters is as follows:
     * param - parameter name to look for.
     * value - parameter value to match.

   This function can be used from REQUEST_ROUTE.

   Example 1.12. uri_param usage
...
if (uri_param("param1","value1")) {
        ...
};
...

1.4.7.  add_uri_param(param)

   Add to RURI a parameter (name=value);

   Meaning of the parameters is as follows:
     * param - parameter to be appended in "name=value" format.

   This function can be used from REQUEST_ROUTE.

   Example 1.13. add_uri_param usage
...
add_uri_param("nat=yes");
...

1.4.8.  tel2sip()

   Converts RURI, if it is tel URI, to SIP URI. Returns true, only
   if conversion succeeded or if no conversion was needed (like
   RURI was not tel URI.

   This function can be used from REQUEST_ROUTE.

   Example 1.14. tel2sip usage
...
tel2sip();
...

1.4.9.  is_uri_user_e164(pseudo-variable)

   Checks if userpart of URI stored in pseudo variable is E164
   number.

   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

   Example 1.15. is_uri_user_e164 usage
...
if (is_uri_user_e164("$fu")) {  # Check From header URI user part
   ...
}
if (is_uri_user_e164("$avp(i:705)") {
   # Check user part of URI stored in avp i:705
   ...
};
...

1.4.10.  encode_contact(encoding_prefix)

   This function will encode uri-s inside Contact header in the
   following manner
   sip:username:password@ip:port;transport=protocol goes
   sip:enc_pref*username*ip*port*protocol@public_ip * is the
   default separator.

   The function returns negative on error, 1 on success.

   Meaning of the parameters is as follows:
     * encoding_prefix - Something to allow us to determine that a
       contact is encoded publicip--a routable IP, most probably
       you should put your external IP of your NAT box.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.

   Example 1.16. encode_contact usage
...
if (src_ip == 10.0.0.0/8) encode_contact("enc_prefix","193.175.135.38");

...

1.4.11.  decode_contact()

   This function will decode the URI in first line in packets
   which come with encoded URI in the following manner
   sip:enc_pref*username*ip*port*protocol@public_ip goes to
   sip:username:password@ip:port;transport=protocol It uses the
   default set parameter for contact encoding separator.

   The function returns negative on error, 1 on success.

   Meaning of the parameters is as follows:

   This function can be used from REQUEST_ROUTE.

   Example 1.17. decode_contact usage
...
if (uri =~ "^enc*") { decode_contact(); }
...

1.4.12.  decode_contact_header()

   This function will decode URIs inside Contact header in the
   following manner
   sip:enc_pref*username*ip*port*protocol@public_ip goes to
   sip:username:password@ip:port;transport=protocol. It uses the
   default set parameter for contact encoding separator.

   The function returns negative on error, 1 on success.

   Meaning of the parameters is as follows:

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.

   Example 1.18. decode_contact_header usage
...
if (uri =~ "^enc*") { decode_contact_header(); }
...

1.4.13.  cmp_uri(str1, str2)

   The function returns true if the two parameters matches as SIP
   URI.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE and BRANCH_ROUTE.

   Example 1.19. cmp_uri usage
...
if(cmp_uri("$ru", "sip:kamailio@kamailio.org"))
{
    # do interesting stuff here
}
...

1.4.14.  cmp_aor(str1, str2)

   The function returns true if the two parameters matches as AoR.
   The parameters have to be SIP URIs.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
   FAILURE_ROUTE and BRANCH_ROUTE.

   Example 1.20. cmp_aor usage
...
if(cmp_aor("$rU@KaMaIlIo.org", "sip:kamailio@$fd"))
{
    # do interesting stuff here
}
...
