mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
354 lines
10 KiB
354 lines
10 KiB
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 - 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 proxys 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. 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 it has
|
|
to change with the new expire value.
|
|
|
|
Default value is "NULL!" it is not set by default.
|
|
|
|
Example 1.4. 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)")
|
|
...
|
|
|
|
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 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.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.
|