SST Module (SIP Session Timer)
Ron Winacott
SOMA Networks, Inc.
Edited by
Ron Winacott
Copyright © 2006 SOMA Networks, Inc.
Revision History
Revision $Revision: 6428 $ $Date: 2009-07-21 10:45:05 +0300
(Tue, 21 Jul 2009) $
__________________________________________________________
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. timeout_avp (string)
1.4.5. reject_to_small (integer)
1.4.6. sst_flag (integer)
1.5. Exported Functions
1.5.1. sstCheckMin(send_reply_flag)
1.6. Exported Statistics
1.6.1. expired_sst
1.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 sst_interval parameter
1.5. Set timeout_avp parameter
1.6. Set reject_to_small parameter
1.7. Set sst_flag parameter
1.8. 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 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 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. timeout_avp (string)
This parameter MUST be set to the same value as the dialog
parameter of the same name. If this parameter is NOT set, the
sst module will not do anything!
This is how the sst module knows which avp in the dialog module
to change with the new expire value.
Default value is "NULL!" it is not set by default.
Example 1.5. Set timeout_avp parameter
...
modparam("dialog", "timeout_avp", "$avp(i:10)")
# Set the sst modules timeout_avp to be the same value
modparam("sst", "timeout_avp", "$avp(i:10)")
...
1.4.5. 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.6. Set reject_to_small parameter
...
modparam("sst", "reject_to_small", 0)
...
1.4.6. sst_flag (integer)
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 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 of the module will not load.
Default value is "Not set!".
Example 1.7. 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
}
...
}
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 - The value to compare the MIN_SE header value
to.
Example 1.8. 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);
}
}
...
1.6. Exported Statistics
1.6.1. expired_sst
Number of dialogs which got expired session timer.
1.7. Installation and Running
just load the module and remember to set the timeout_avp value.
