SST Module (SIP Session Timer)
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. How it works
        1.3. Dependencies

              1.3.1. OpenSIPS Modules
              1.3.2. External Libraries or Applications

        1.4. Exported Parameters

              1.4.1. enable_stats (integer)
              1.4.2. min_se (integer)
              1.4.3. sst_interval (integer)
              1.4.4. reject_to_small (integer)
              1.4.5. sst_flag (string)

        1.5. Exported Functions

              1.5.1. sstCheckMin(send_reply_flag)

        1.6. Exported Statistics

              1.6.1. expired_sst

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

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

Chapter 1. Admin Guide

1.1. Overview

   The sst module provides a way to update the dialog expire timer
   based on the SIP INVITE/200 OK Session-Expires header value.
   You can use the sst module in an OpenSIPS proxy to allow
   freeing of local resources of dead (expired) 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 OpenSIPS
   configuration.

1.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.

   You flag any call setup INVITE that you want to cause a timed
   session to be established. This will cause OpenSIPS to request
   the use of session times 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 opensips.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 varify the
   Session-expires / MIN-SE header field values are not too small
   for a proxy. If the SST min_se parameter value is smaller then
   the messages Session-Expires / MIN-SE values, the test will
   return true. You can also configure the function to send the
   422 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      |
    |            |-------------->|
    |            |               |
 ...

1.3. Dependencies

1.3.1. OpenSIPS Modules

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

1.3.2. External Libraries or Applications

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

1.4. Exported Parameters

1.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)
...

1.4.2. min_se (integer)

   The value is used to set the proxies MIN-SE value and is used
   in the 422 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)
...

1.4.3. sst_interval (integer)

   The sst minimum interval in Session-Expires header if OpenSIPS
   request the use of session times. The used value will be the
   maximum value between OpenSIPS minSE, UAS minSE and this value.

   Per default the interval used will be the min_se value

   Default value is “0” seconds.

   Example 1.4. Set sst_interval parameter
...
modparam("sst", "sst_interval", 2400)
...

1.4.4. reject_to_small (integer)

   In the initial INVITE if the UAC has requested a
   Session-Expire: and it's value is smaller then 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.

   This flag if true will tell the SST module to reject the INVITE
   with a 422 response. If false, the INVITE is forwarded through
   the PROXY with out any modifications.

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

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

1.4.5. sst_flag (string)

   Keeping with OpenSIPS, the module will not do anything to any
   message unless instructed to do so via the opensips.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 when ever you create a new dialog via
   create_dialog() function,you will want to set the sst flag. If
   create_dialog() is not called and the sst flag is set, it will
   not have any effect.

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

   Default value is “Not set!”.

   Example 1.6. Set sst_flag parameter
...
modparam("sst", "sst_flag", "SST_FLAG")
...
route {
  ...
  if ($rm=="INVITE") {
    setflag(SST_FLAG); # Set the sst flag
    create_dialog(); # and then create the dialog
  }
  ...
}

1.5. Exported Functions

1.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 then modules minimum value, this function
   will return true.

   If the fuction 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 (int, optional) - The value to compare the
       MIN_SE header value to.

   Example 1.7. sstCheckMin usage

...
modparam("sst", "sst_flag", 6)
modparam("sst", "min_se", 2400) # Must be >= 90
...

route {
  if ($rm=="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(6);
        create_dialog();
  }
}

... or ...

route {
  if ($rm=="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);
  }
}
...

1.6. Exported Statistics

1.6.1. expired_sst

   Number of dialogs which got expired session timer.

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Bogdan-Andrei Iancu (@bogdan-iancu) 30 25 125 129
   2. Ron Winacott 27 5 2083 265
   3. Liviu Chircu (@liviuchircu) 18 15 54 65
   4. Daniel-Constantin Mierla (@miconda) 15 12 104 104
   5. Razvan Crainea (@razvancrainea) 14 10 106 140
   6. Andrei Datcu (@andrei-datcu) 8 6 122 28
   7. Vlad Patrascu (@rvlad-patrascu) 7 5 23 37
   8. Vlad Paiu (@vladpaiu) 6 4 7 15
   9. Ovidiu Sas (@ovidiusas) 6 3 171 44
   10. Henning Westerholt (@henningw) 5 3 15 18

   All remaining contributors: Anca Vamanu, Christophe Sollet
   (@csollet), Ionut Ionita (@ionutrazvanionita), Damien Sandras
   (@dsandras), Konstantin Bokarius, Dan Pascu (@danpascu),
   Ezequiel Lovelle, Peter Lemenkov (@lemenkov), Edson Gellert
   Schubert, Elena-Ramona Modroiu.

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Bogdan-Andrei Iancu (@bogdan-iancu) Oct 2006 - May 2020
   2.  Razvan Crainea (@razvancrainea)     Jun 2011 - Sep 2019
   3.  Liviu Chircu (@liviuchircu)         Jan 2013 - May 2019
   4.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   5.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   6.  Ionut Ionita (@ionutrazvanionita)   Oct 2016 - Oct 2016
   7.  Vlad Paiu (@vladpaiu)               Jun 2011 - Feb 2015
   8.  Ezequiel Lovelle                    Oct 2014 - Oct 2014
   9.  Andrei Datcu (@andrei-datcu)        Jul 2014 - Jul 2014
   10. Damien Sandras (@dsandras)          Jul 2013 - Jul 2013

   All remaining contributors: Christophe Sollet (@csollet), Anca
   Vamanu, Henning Westerholt (@henningw), Ovidiu Sas
   (@ovidiusas), Daniel-Constantin Mierla (@miconda), Konstantin
   Bokarius, Edson Gellert Schubert, Dan Pascu (@danpascu),
   Elena-Ramona Modroiu, Ron Winacott.

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Liviu Chircu (@liviuchircu), Vlad Patrascu
   (@rvlad-patrascu), Peter Lemenkov (@lemenkov), Razvan Crainea
   (@razvancrainea), Bogdan-Andrei Iancu (@bogdan-iancu), Vlad
   Paiu (@vladpaiu), Christophe Sollet (@csollet), Henning
   Westerholt (@henningw), Daniel-Constantin Mierla (@miconda),
   Konstantin Bokarius, Edson Gellert Schubert, Elena-Ramona
   Modroiu, Ron Winacott.

   Documentation Copyrights:

   Copyright © 2006 SOMA Networks, Inc.
