SST Module (SIP Session Timer)

Ron Winacott

   SOMA Networks, Inc.

Edited by

Ron Winacott

   Copyright © 2006 SOMA Networks, Inc.
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. How it works
        3. Dependencies

              3.1. Kamailio Modules
              3.2. External Libraries or Applications

        4. Parameters

              4.1. enable_stats (integer)
              4.2. min_se (integer)
              4.3. timeout_avp (string)
              4.4. reject_to_small (integer)
              4.5. sst_flag (integer)

        5. Functions

              5.1. sstCheckMin(send_reply_flag)

        6. Statistics

              6.1. expired_sst

        7. Installation and Running

   List of Examples

   1.1. Session timer call flow
   1.2. Set enable_stats parameter
   1.3. Set min_se parameter
   1.4. Set timeout_avp parameter
   1.5. Set reject_to_small parameter
   1.6. Set sst_flag parameter
   1.7. sstCheckMin usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. How it works
   3. Dependencies

        3.1. Kamailio Modules
        3.2. External Libraries or Applications

   4. Parameters

        4.1. enable_stats (integer)
        4.2. min_se (integer)
        4.3. timeout_avp (string)
        4.4. reject_to_small (integer)
        4.5. sst_flag (integer)

   5. Functions

        5.1. sstCheckMin(send_reply_flag)

   6. Statistics

        6.1. expired_sst

   7. Installation and Running

1. Overview

   SIP session timers are used to make sure that a session (dialog) is
   still alive, even though there may have been a long time since the last
   in-dialog message. If the other end is not responding, the dialog will
   be hung up automatically. SIP session timers need to be supported by
   all end points for it to work. It's a SIP extension, standardized by
   the IETF.

   The sst module provides a way to update the dialog expiry timer based
   on the SIP INVITE/200 OK Session-Expires header value. You can use the
   sst module in an Kamailio proxy to allow freeing of local resources of
   dead calls.

   You can also use the sst module to validate the MIN_SE header value and
   reply to any request with a "422 - Session Timer Too Small" if the
   value is too small for your Kamailio configuration.

2. How it works

   The sst module uses the “dialog module” to be notified of any new or
   updated dialogs. It will then look for and extract the session-expire:
   header value (if there is one) and override the dialog expire timer
   value for the current context dialog by setting the avp value.

   You flag any call setup INVITE that you want to cause a timed session
   to be established. This will cause Kamailio to request the use of
   session timers if the UAC does not request it.

   All of this happens with a properly configured dialog and sst module
   and setting the dialog flag and the sst flag at the time any INVITE sip
   message is seen. There is no kamailio.cfg script function call required
   to set the dialog expire timeout value. See the “dialog module” users
   guide for more information.

   The “sstCheckMin()” script function can be used to verify that the
   Session-expires / MIN-SE header field values are not too small for your
   server. If the SST min_se parameter value is smaller than the messages
   Session-Expires / MIN-SE values, the test will return true. You can
   also configure the function to send the 422 error response for you.

   The following was taken from the RFC as a call flow example:

   Example 1.1. Session timer call flow
+-------+    +-------+       +-------+
| UAC-1 |    | PROXY |       | UAC-2 |
+-------+    +-------+       +-------+
    |(1) INVITE  |               |
    |SE: 50      |               |
    |----------->|               |
    |            |(2)sstCheckMin |
    |            |-----+         |
    |            |     |         |
    |            |<----+         |
    |(3) 422     |               |
    |MSE:1800    |               |
    |<-----------|               |
    |            |               |
    |(4)ACK      |               |
    |----------->|               |
    |            |               |
    |(5) INVITE  |               |
    |SE: 1800    |               |
    |MSE: 1800   |               |
    |----------->|               |
    |            |(6)sstCheckMin |
    |            |-----+         |
    |            |     |         |
    |            |<----+         |
    |            |(7)setflag     |
    |            |Dialog flag    |
    |            |Set expire     |
    |            |-----+         |
    |            |     |         |
    |            |<----+         |
    |            |               |
    |            |(8)INVITE      |
    |            |SE: 1800       |
    |            |MSE: 1800      |
    |            |-------------->|
    |            |               |
 ...

3. Dependencies

   3.1. Kamailio Modules
   3.2. External Libraries or Applications

3.1. Kamailio Modules

   The following modules must be loaded before this module:
     * dialog or dialog-ng - dialog module and its dependencies. (tm)
     * sl - stateless module.

3.2. External Libraries or Applications

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

4. Parameters

   4.1. enable_stats (integer)
   4.2. min_se (integer)
   4.3. timeout_avp (string)
   4.4. reject_to_small (integer)
   4.5. sst_flag (integer)

4.1. enable_stats (integer)

   If the statistics support should be enabled or not. Via statistic
   variables, the module provide information about the dialog processing.
   Set it to zero to disable or to non-zero to enable it.

   Default value is “1” (enabled).

   Example 1.2. Set enable_stats parameter
...
modparam("sst", "enable_stats", 0)
...

4.2. min_se (integer)

   The value is used to set the proxies MIN-SE value and is used in the
   422 error reply as the proxies MIN-SE: header value if the
   “sstCheckMin()” flag is set to true and the check fails.

   If not set and “sstCheckMin()” is called with the send-reply flag set
   to true, the default 1800 seconds will be used as the compare and the
   MIN-SE: header value if the 422 reply is sent.

   Default value is “1800” seconds.

   Example 1.3. Set min_se parameter
...
modparam("sst", "min_se", 2400)
...

4.3. timeout_avp (string)

   This parameter must be set to the same value as the dialog module
   parameter of the same name, when it is wanted to update dialog timeout
   using Session-Expires header value. If this parameter is not set, the
   sst module will not update dialog timeout.

   With this parameter, the sst module knows which avp is expected by the
   dialog module to change to a new expire value.

   Note that the avp is set only for requests within dialog, not for the
   initial INVITE. For this one, it can be done using script operations,
   see the next example for such solution.

   Default value is “NULL” (not set by default).

   Example 1.4. Set timeout_avp parameter
...
modparam("dialog", "timeout_avp", "$avp(dlgtimeout)")
# Set the sst modules timeout_avp to be the same value
modparam("sst", "timeout_avp", "$avp(dlgtimeout)")
...
request_route {
    ...
    # when wanting to use Session-Expires value for initial INVITE
    if(is_method("INVITE") and !has_totag()) {
        if(is_present_hf("Session-Expires")) {
            $avp(dlgtimeout) = $(hdr(Session-Expires){s.int});
        }
    }
    ...
}
...

4.4. reject_to_small (integer)

   In the initial INVITE if the UAC has requested a Session-Expire: and
   it's value is smaller than our local policies Min-SE (see min_se
   above), then the proxy has the right to reject the call by replying to
   the message with a “422 Session Timer Too Small” and state our local
   Min-SE: value. The INVITE is NOT forwarded on through the proxy.

   If this flag is true, the SST module to reject the INVITE with a 422
   response. If false, the INVITE is forwarded through the PROXY without
   any modifications.

   Default value is “1” (true/on).

   Example 1.5. Set reject_to_small parameter
...
modparam("sst", "reject_to_small", 0)
...

4.5. sst_flag (integer)

   Keeping with Kamailio, the module will not do anything to any message
   unless instructed to do so via the kamailio.cfg script. You must set
   the sst_flag value in the setflag() call of the INVITE you want the sst
   module to process. But before you can do that, you need to tell the sst
   module which flag value you are assigning to sst.

   In most cases whenever you set the dialog flag you will want to set the
   sst flag. If the dialog flag is not set and the sst flag is set, it
   will not have any effect.

   This parameter must be set or the module will not load.

   Default value is “Not set!”.

   Example 1.6. Set sst_flag parameter
...
modparam("dialog", "dlg_flag", 5)
modparam("sst", "sst_flag", 6)
...
route {
  ...
  if (method=="INVITE") {
    setflag(5); # set the dialog flag
    setflag(6); # Set the sst flag
  }
  ...
}

5. Functions

   5.1. sstCheckMin(send_reply_flag)

5.1.  sstCheckMin(send_reply_flag)

   Check the current Session-Expires / MIN-SE values against the
   sst_min_se parameter value. If the Session-Expires or MIN_SE header
   value is less than the modules minimum value, this function will return
   true.

   If the function is called with the send_reply_flag set to true (1) and
   the requested Session-Expires / MIN-SE values are too small, a 422
   reply will be sent for you. The 422 will carry a MIN-SE: header with
   the sst min_se parameter value set.

   Meaning of the parameters is as follows:
     * min_allowed - The value to compare the MIN_SE header value to.

   Example 1.7. sstCheckMin usage
...
modparam("dialog", "timeout_avp", "$avp(i:4242)")
modparam("dialog", "dlg_flag", 5)
...
modparam("sst", "sst_flag", 6)
modparam("sst", "timeout_avp", "$avp(i:4242)")
modparam("sst", "min_se", 2400) # Must be >= 90
...

route {
  if (method=="INVITE") {
        if (sstCheckMin("1")) {
                xlog("L_ERR", "422 Session Timer Too Small reply sent.\n");
                exit;
        }
        # track the session timers via the dialog module
        setflag(5);
        setflag(6);
  }
}

... or ...

route {
  if (method=="INVITE") {
        if (sstCheckMin("0")) {
                xlog("L_ERR", "Session Timer Too Small, dropping request\n");
                exit;
        }
        # track the session timers via the dialog module
        setflag(5);
        setflag(6);
  }
}
...

6. Statistics

   6.1. expired_sst

6.1. expired_sst

   Number of dialogs which got expired session timer.

7. Installation and Running

   Just load the module and remember to set the timeout_avp value.
