$Revision: 1488 $
$Date: 2007-01-11 19:05:13 +0200 (Thu, 11 Jan 2007) $
User's Guide
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 OpenSER 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 OpenSER configuration.
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 cuase a
timed session to be established. This will cuase OpenSER 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
openser.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:
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 |
| |-------------->|
| | |
...
Dependencies
&ser; Modules
The following modules must be loaded
before this module:
dialog - dialog module and its decencies. (tm)
sl - stateless module.
External Libraries or Applications
The following libraries or applications must be installed before running
&ser; with this module loaded:
None.
Exported Parameters
<varname>enable_stats</varname> (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).
Set <varname>enable_stats</varname> parameter
...
modparam("sst", "enable_stats", 0)
...
<varname>min_se</varname> (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.
Set <varname>min_se</varname> parameter
...
modparam("sst", "min_se", 2400)
...
<varname>timeout_avp</varname> (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.
Set <varname>timeout_avp</varname> 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)")
...
<varname>reject_to_small</varname> (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).
Set <varname>reject_to_small</varname> parameter
...
modparam("sst", "reject_to_small", 0)
...
<varname>sst_flag</varname> (integer)
Keeping with OpenSER, the module will not do
anything to any message unless instructed to do so via
the openser.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!
.
Set <varname>sst_flag</varname> 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
}
...
}
Exported Functions
<function moreinfo="none">sstCheckMin(send_reply_flag)</function>
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.
<function>sstCheckMin</function> 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);
}
}
...
Exported Statistics
<varname>expired_sst</varname>
Number of dialogs which got expired session timer.
Installation & Running
just load the module and remember to set the timeout_avp value.