Browse code

Fixing documentation

oej authored on 18/10/2009 22:39:51
Showing 3 changed files
... ...
@@ -10,38 +10,37 @@ Ron Winacott
10 10
 
11 11
    Copyright � 2006 SOMA Networks, Inc.
12 12
    Revision History
13
-   Revision $Revision$ $Date: 2008-08-06 12:08:33 +0200
14
-                              (Mi, 06 Aug 2008) $
15
-     __________________________________________________________
13
+   Revision $Revision$ $Date$
14
+     __________________________________________________________________
16 15
 
17 16
    Table of Contents
18 17
 
19 18
    1. Admin Guide
20 19
 
21
-        1.1. Overview
22
-        1.2. How it works
23
-        1.3. Dependencies
20
+        1. Overview
21
+        2. How it works
22
+        3. Dependencies
24 23
 
25
-              1.3.1. Kamailio Modules
26
-              1.3.2. External Libraries or Applications
24
+              3.1. Kamailio Modules
25
+              3.2. External Libraries or Applications
27 26
 
28
-        1.4. Exported Parameters
27
+        4. Exported Parameters
29 28
 
30
-              1.4.1. enable_stats (integer)
31
-              1.4.2. min_se (integer)
32
-              1.4.3. timeout_avp (string)
33
-              1.4.4. reject_to_small (integer)
34
-              1.4.5. sst_flag (integer)
29
+              4.1. enable_stats (integer)
30
+              4.2. min_se (integer)
31
+              4.3. timeout_avp (string)
32
+              4.4. reject_to_small (integer)
33
+              4.5. sst_flag (integer)
35 34
 
36
-        1.5. Exported Functions
35
+        5. Exported Functions
37 36
 
38
-              1.5.1. sstCheckMin(send_reply_flag)
37
+              5.1. sstCheckMin(send_reply_flag)
39 38
 
40
-        1.6. Exported Statistics
39
+        6. Exported Statistics
41 40
 
42
-              1.6.1. expired_sst
41
+              6.1. expired_sst
43 42
 
44
-        1.7. Installation and Running
43
+        7. Installation and Running
45 44
 
46 45
    List of Examples
47 46
 
... ...
@@ -55,42 +54,73 @@ Ron Winacott
55 55
 
56 56
 Chapter 1. Admin Guide
57 57
 
58
-1.1. Overview
58
+   Table of Contents
59
+
60
+   1. Overview
61
+   2. How it works
62
+   3. Dependencies
63
+
64
+        3.1. Kamailio Modules
65
+        3.2. External Libraries or Applications
66
+
67
+   4. Exported Parameters
68
+
69
+        4.1. enable_stats (integer)
70
+        4.2. min_se (integer)
71
+        4.3. timeout_avp (string)
72
+        4.4. reject_to_small (integer)
73
+        4.5. sst_flag (integer)
74
+
75
+   5. Exported Functions
76
+
77
+        5.1. sstCheckMin(send_reply_flag)
78
+
79
+   6. Exported Statistics
80
+
81
+        6.1. expired_sst
59 82
 
60
-   The sst module provides a way to update the dialog expire timer
61
-   based on the SIP INVITE/200 OK Session-Expires header value.
62
-   You can use the sst module in an Kamailio proxy to allow
63
-   freeing of local resources of dead (expired) calls.
83
+   7. Installation and Running
64 84
 
65
-   You can also use the sst module to validate the MIN_SE header
66
-   value and reply to any request with a "422 - Session Timer Too
67
-   Small" if the value is too small for your Kamailio
68
-   configuration.
85
+1. Overview
69 86
 
70
-1.2. How it works
87
+   SIP session timers are used to make sure that a session (dialog) is
88
+   still alive, even though there may have been a long time since the last
89
+   in-dialog message. If the other end is not responding, the dialog will
90
+   be hung up automatically. SIP session timers need to be supported by
91
+   all end points for it to work. It's a SIP extension, standardized by
92
+   the IETF.
71 93
 
72
-   The sst module uses the dialog module to be notified of any new
73
-   or updated dialogs. It will then look for and extract the
74
-   session-expire: header value (if there is one) and override the
75
-   dialog expire timer value for the current context dialog by
76
-   setting the avp value.
94
+   The sst module provides a way to update the dialog expiry timer based
95
+   on the SIP INVITE/200 OK Session-Expires header value. You can use the
96
+   sst module in an Kamailio proxy to allow freeing of local resources of
97
+   dead calls.
77 98
 
78
-   You flag any call setup INVITE that you want to cause a timed
79
-   session to be established. This will cause Kamailio to request
80
-   the use of session times if the UAC does not request it.
99
+   You can also use the sst module to validate the MIN_SE header value and
100
+   reply to any request with a "422 - Session Timer Too Small" if the
101
+   value is too small for your Kamailio configuration.
81 102
 
82
-   All of this happens with a properly configured dialog and sst
83
-   module and setting the dialog flag and the sst flag at the time
84
-   any INVITE sip message is seen. There is no kamailio.cfg script
85
-   function call required to set the dialog expire timeout value.
86
-   See the dialog module users guide for more information.
103
+2. How it works
87 104
 
88
-   The sstCheckMin() script function can be used to varify the
89
-   Session-expires / MIN-SE header field values are not too small
90
-   for a proxy. If the SST min_se parameter value is smaller then
91
-   the messages Session-Expires / MIN-SE values, the test will
92
-   return true. You can also configure the function to send the
93
-   422 response for you.
105
+   The sst module uses the "dialog module" to be notified of any new or
106
+   updated dialogs. It will then look for and extract the session-expire:
107
+   header value (if there is one) and override the dialog expire timer
108
+   value for the current context dialog by setting the avp value.
109
+
110
+   You flag any call setup INVITE that you want to cause a timed session
111
+   to be established. This will cause Kamailio to request the use of
112
+   session timers if the UAC does not request it.
113
+
114
+   All of this happens with a properly configured dialog and sst module
115
+   and setting the dialog flag and the sst flag at the time any INVITE sip
116
+   message is seen. There is no kamailio.cfg script function call required
117
+   to set the dialog expire timeout value. See the "dialog module" users
118
+   guide for more information.
119
+
120
+   The "sstCheckMin()" script function can be used to verify that the
121
+   Session-expires / MIN-SE header field values are not too small for your
122
+   server. If the SST min_se parameter value is smaller than the messages
123
+   Session-Expires / MIN-SE values, the test will return true. You can
124
+   also configure the function to send the 422 error response for you.
94 125
 
95 126
    The following was taken from the RFC as a call flow example:
96 127
 
... ...
@@ -134,28 +164,36 @@ Chapter 1. Admin Guide
134 134
     |            |               |
135 135
  ...
136 136
 
137
-1.3. Dependencies
137
+3. Dependencies
138
+
139
+   3.1. Kamailio Modules
140
+   3.2. External Libraries or Applications
138 141
 
139
-1.3.1. Kamailio Modules
142
+3.1. Kamailio Modules
140 143
 
141 144
    The following modules must be loaded before this module:
142
-     * dialog - dialog module and its decencies. (tm)
145
+     * dialog - dialog module and its dependencies. (tm)
143 146
      * sl - stateless module.
144 147
 
145
-1.3.2. External Libraries or Applications
148
+3.2. External Libraries or Applications
146 149
 
147
-   The following libraries or applications must be installed
148
-   before running Kamailio with this module loaded:
150
+   The following libraries or applications must be installed before
151
+   running Kamailio with this module loaded:
149 152
      * None.
150 153
 
151
-1.4. Exported Parameters
154
+4. Exported Parameters
152 155
 
153
-1.4.1. enable_stats (integer)
156
+   4.1. enable_stats (integer)
157
+   4.2. min_se (integer)
158
+   4.3. timeout_avp (string)
159
+   4.4. reject_to_small (integer)
160
+   4.5. sst_flag (integer)
154 161
 
155
-   If the statistics support should be enabled or not. Via
156
-   statistic variables, the module provide information about the
157
-   dialog processing. Set it to zero to disable or to non-zero to
158
-   enable it.
162
+4.1. enable_stats (integer)
163
+
164
+   If the statistics support should be enabled or not. Via statistic
165
+   variables, the module provide information about the dialog processing.
166
+   Set it to zero to disable or to non-zero to enable it.
159 167
 
160 168
    Default value is "1" (enabled).
161 169
 
... ...
@@ -164,15 +202,15 @@ Chapter 1. Admin Guide
164 164
 modparam("sst", "enable_stats", 0)
165 165
 ...
166 166
 
167
-1.4.2. min_se (integer)
167
+4.2. min_se (integer)
168 168
 
169
-   The value is used to set the proxies MIN-SE value and is used
170
-   in the 422 reply as the proxies MIN-SE: header value if the
171
-   sstCheckMin() flag is set to true and the check fails.
169
+   The value is used to set the proxies MIN-SE value and is used in the
170
+   422 error reply as the proxys MIN-SE: header value if the
171
+   "sstCheckMin()" flag is set to true and the check fails.
172 172
 
173
-   If not set and sstCheckMin() is called with the send-reply flag
174
-   set to true, the default 1800 seconds will be used as the
175
-   compare and the MIN-SE: header value if the 422 reply is sent.
173
+   If not set and "sstCheckMin()" is called with the send-reply flag set
174
+   to true, the default 1800 seconds will be used as the compare and the
175
+   MIN-SE: header value if the 422 reply is sent.
176 176
 
177 177
    Default value is "1800" seconds.
178 178
 
... ...
@@ -181,13 +219,13 @@ modparam("sst", "enable_stats", 0)
181 181
 modparam("sst", "min_se", 2400)
182 182
 ...
183 183
 
184
-1.4.3. timeout_avp (string)
184
+4.3. timeout_avp (string)
185 185
 
186
-   This parameter MUST be set to the same value as the dialog
187
-   parameter of the same name. If this parameter is NOT set, the
188
-   sst module will not do anything!
186
+   This parameter MUST be set to the same value as the dialog module
187
+   parameter of the same name. If this parameter is NOT set, the sst
188
+   module will not do anything!
189 189
 
190
-   This is how the sst module knows which avp in the dialog module
190
+   This is how the sst module knows which avp in the dialog module it has
191 191
    to change with the new expire value.
192 192
 
193 193
    Default value is "NULL!" it is not set by default.
... ...
@@ -199,18 +237,17 @@ modparam("dialog", "timeout_avp", "$avp(i:10)")
199 199
 modparam("sst", "timeout_avp", "$avp(i:10)")
200 200
 ...
201 201
 
202
-1.4.4. reject_to_small (integer)
202
+4.4. reject_to_small (integer)
203 203
 
204
-   In the initial INVITE if the UAC has requested a
205
-   Session-Expire: and it's value is smaller then our local
206
-   policies Min-SE (see min_se above), then the PROXY has the
207
-   right to reject the call by replying to the message with a 422
208
-   Session Timer Too Small and state our local Min-SE: value. The
209
-   INVITE is NOT forwarded on through the PROXY.
204
+   In the initial INVITE if the UAC has requested a Session-Expire: and
205
+   it's value is smaller than our local policies Min-SE (see min_se
206
+   above), then the proxy has the right to reject the call by replying to
207
+   the message with a "422 Session Timer Too Small" and state our local
208
+   Min-SE: value. The INVITE is NOT forwarded on through the proxy.
210 209
 
211
-   This flag if true will tell the SST module to reject the INVITE
212
-   with a 422 response. If false, the INVITE is forwarded through
213
-   the PROXY with out any modifications.
210
+   If this flag is true, the SST module to reject the INVITE with a 422
211
+   response. If false, the INVITE is forwarded through the PROXY without
212
+   any modifications.
214 213
 
215 214
    Default value is "1" (true/on).
216 215
 
... ...
@@ -219,20 +256,19 @@ modparam("sst", "timeout_avp", "$avp(i:10)")
219 219
 modparam("sst", "reject_to_small", 0)
220 220
 ...
221 221
 
222
-1.4.5. sst_flag (integer)
222
+4.5. sst_flag (integer)
223 223
 
224
-   Keeping with Kamailio, the module will not do anything to any
225
-   message unless instructed to do so via the kamailio.cfg script.
226
-   You must set the sst_flag value in the setflag() call of the
227
-   INVITE you want the sst module to process. But before you can
228
-   do that, you need to tell the sst module which flag value you
229
-   are assigning to sst.
224
+   Keeping with Kamailio, the module will not do anything to any message
225
+   unless instructed to do so via the kamailio.cfg script. You must set
226
+   the sst_flag value in the setflag() call of the INVITE you want the sst
227
+   module to process. But before you can do that, you need to tell the sst
228
+   module which flag value you are assigning to sst.
230 229
 
231
-   In most cases when ever you set the dialog flag you will want
232
-   to set the sst flag. If the dialog flag is not set and the sst
233
-   flag is set, it will not have any effect.
230
+   In most cases whenever you set the dialog flag you will want to set the
231
+   sst flag. If the dialog flag is not set and the sst flag is set, it
232
+   will not have any effect.
234 233
 
235
-   This parameter must be set of the module will not load.
234
+   This parameter must be set or the module will not load.
236 235
 
237 236
    Default value is "Not set!".
238 237
 
... ...
@@ -250,26 +286,26 @@ route {
250 250
   ...
251 251
 }
252 252
 
253
-1.5. Exported Functions
253
+5. Exported Functions
254
+
255
+   5.1. sstCheckMin(send_reply_flag)
254 256
 
255
-1.5.1.  sstCheckMin(send_reply_flag)
257
+5.1. sstCheckMin(send_reply_flag)
256 258
 
257 259
    Check the current Session-Expires / MIN-SE values against the
258
-   sst_min_se parameter value. If the Session-Expires or MIN_SE
259
-   header value is less then modules minimum value, this function
260
-   will return true.
260
+   sst_min_se parameter value. If the Session-Expires or MIN_SE header
261
+   value is less than the modules minimum value, this function will return
262
+   true.
261 263
 
262
-   If the fuction is called with the send_reply_flag set to true
263
-   (1) and the requested Session-Expires / MIN-SE values are too
264
-   small, a 422 reply will be sent for you. The 422 will carry a
265
-   MIN-SE: header with the sst min_se parameter value set.
264
+   If the fuction is called with the send_reply_flag set to true (1) and
265
+   the requested Session-Expires / MIN-SE values are too small, a 422
266
+   reply will be sent for you. The 422 will carry a MIN-SE: header with
267
+   the sst min_se parameter value set.
266 268
 
267 269
    Meaning of the parameters is as follows:
268
-     * min_allowed - The value to compare the MIN_SE header value
269
-       to.
270
+     * min_allowed - The value to compare the MIN_SE header value to.
270 271
 
271 272
    Example 1.7. sstCheckMin usage
272
-
273 273
 ...
274 274
 modparam("dialog", "timeout_avp", "$avp(i:4242)")
275 275
 modparam("dialog", "dlg_flag", 5)
... ...
@@ -282,8 +318,7 @@ modparam("sst", "min_se", 2400) # Must be >= 90
282 282
 route {
283 283
   if (method=="INVITE") {
284 284
         if (sstCheckMin("1")) {
285
-                xlog("L_ERR", "422 Session Timer Too Small reply sent.\n
286
-");
285
+                xlog("L_ERR", "422 Session Timer Too Small reply sent.\n");
287 286
                 exit;
288 287
         }
289 288
         # track the session timers via the dialog module
... ...
@@ -297,8 +332,7 @@ route {
297 297
 route {
298 298
   if (method=="INVITE") {
299 299
         if (sstCheckMin("0")) {
300
-                xlog("L_ERR", "Session Timer Too Small, dropping request
301
-\n");
300
+                xlog("L_ERR", "Session Timer Too Small, dropping request\n");
302 301
                 exit;
303 302
         }
304 303
         # track the session timers via the dialog module
... ...
@@ -308,12 +342,14 @@ route {
308 308
 }
309 309
 ...
310 310
 
311
-1.6. Exported Statistics
311
+6. Exported Statistics
312
+
313
+   6.1. expired_sst
312 314
 
313
-1.6.1. expired_sst
315
+6.1. expired_sst
314 316
 
315 317
    Number of dialogs which got expired session timer.
316 318
 
317
-1.7. Installation and Running
319
+7. Installation and Running
318 320
 
319
-   just load the module and remember to set the timeout_avp value.
321
+   Just load the module and remember to set the timeout_avp value.
... ...
@@ -15,47 +15,54 @@
15 15
 	
16 16
 	<section>
17 17
 		<title>Overview</title>
18
+		<para>SIP session timers are used to make sure that
19
+		a session (dialog) is still alive, even though there
20
+		may have been a long time since the last in-dialog message.
21
+		If the other end is not responding, the dialog will
22
+		be hung up automatically. SIP session timers need to
23
+		be supported by all end points for it to work. It's a
24
+		SIP extension, standardized by the IETF.</para>
18 25
 
19 26
 		<para>The sst module provides a way to update the
20
-		dialog expire timer based on the SIP INVITE/200 OK
27
+		dialog expiry timer based on the SIP INVITE/200 OK
21 28
 		Session-Expires header value. You can use the sst
22
-		module in an Kamailio proxy to allow freeing of local
23
-		resources of dead (expired) calls.</para>
29
+		module in an &kamailio; proxy to allow freeing of local
30
+		resources of dead calls.</para>
24 31
 
25 32
 		<para>You can also use the sst module to validate the
26 33
 		MIN_SE header value and reply to any request with a
27 34
 		"422 - Session Timer Too Small" if the value is too
28
-		small for your Kamailio configuration.</para>
35
+		small for your &kamailio; configuration.</para>
29 36
 
30 37
 	</section>
31 38
 	
32 39
 	<section>
33 40
 	<title>How it works</title>
34 41
 	
35
-	<para>The sst module uses the dialog module to be notified of
42
+	<para>The sst module uses the <quote>dialog module</quote> to be notified of
36 43
 	any new or updated dialogs. It will then look for and extract
37 44
 	the session-expire: header value (if there is one) and
38 45
 	override the dialog expire timer value for the current context
39 46
 	dialog by setting the avp value.</para>
40 47
 
41 48
 	<para>You flag any call setup INVITE that you want to cause a
42
-	timed session to be established. This will cause Kamailio to
43
-	request the use of session times if the UAC does not request
49
+	timed session to be established. This will cause &kamailio; to
50
+	request the use of session timers if the UAC does not request
44 51
 	it.</para>
45 52
 
46 53
 	<para>All of this happens with a properly configured dialog
47 54
 	and sst module and setting the dialog flag and the sst flag at
48 55
 	the time any INVITE sip message is seen. There is no
49
-	kamailio.cfg script function call required to set the dialog
50
-	expire timeout value. See the dialog module users guide for
56
+	&kamailioconfig; script function call required to set the dialog
57
+	expire timeout value. See the <quote>dialog module</quote> users guide for
51 58
 	more information.</para>
52 59
 
53
-	<para>The sstCheckMin() script function can be used to varify
54
-	the Session-expires / MIN-SE header field values are not too
55
-	small for a proxy. If the SST min_se parameter value is
56
-	smaller then the messages Session-Expires / MIN-SE values, the
60
+	<para>The <quote>sstCheckMin()</quote> script function can be used to verify
61
+	that the Session-expires / MIN-SE header field values are not too
62
+	small for your server. If the SST min_se parameter value is
63
+	smaller than the messages Session-Expires / MIN-SE values, the
57 64
 	test will return true. You can also configure the function to
58
-	send the 422 response for you.</para>
65
+	send the 422 error response for you.</para>
59 66
 
60 67
 	<para>The following was taken from the RFC as a call flow
61 68
 	example:</para>
... ...
@@ -116,7 +123,7 @@
116 116
 		<itemizedlist>
117 117
 		<listitem>
118 118
 		<para>
119
-		<emphasis>dialog</emphasis> - dialog module and its decencies. (tm)
119
+		<emphasis>dialog</emphasis> - dialog module and its dependencies. (tm)
120 120
 		</para>
121 121
 		</listitem>
122 122
 		<listitem>
... ...
@@ -172,11 +179,11 @@ modparam("sst", "enable_stats", 0)
172 172
 		<title><varname>min_se</varname> (integer)</title>
173 173
 
174 174
 		<para>The value is used to set the proxies MIN-SE
175
-		value and is used in the 422 reply as the proxies
176
-		MIN-SE: header value if the sstCheckMin() flag is set
175
+		value and is used in the 422 error reply as the proxys
176
+		MIN-SE: header value if the <quote>sstCheckMin()</quote> flag is set
177 177
 		to true and the check fails.</para>
178 178
 
179
-		<para>If not set and sstCheckMin() is called with the
179
+		<para>If not set and <quote>sstCheckMin()</quote> is called with the
180 180
 		send-reply flag set to true, the default 1800 seconds
181 181
 		will be used as the compare and the MIN-SE: header
182 182
 		value if the 422 reply is sent.</para>
... ...
@@ -200,11 +207,11 @@ modparam("sst", "min_se", 2400)
200 200
 		<title><varname>timeout_avp</varname> (string)</title>
201 201
 
202 202
 		<para>This parameter MUST be set to the same value as the
203
-		dialog parameter of the same name. If this parameter is
203
+		dialog module parameter of the same name. If this parameter is
204 204
 		NOT set, the sst module will not do anything!</para>
205 205
 
206 206
 		<para>This is how the sst module knows which avp in the
207
-		dialog module to change with the new expire value.</para>
207
+		dialog module it has to change with the new expire value.</para>
208 208
 
209 209
 		<para>
210 210
 		<emphasis>
... ...
@@ -226,16 +233,16 @@ modparam("sst", "timeout_avp", "$avp(i:10)")
226 226
 		<title><varname>reject_to_small</varname> (integer)</title>
227 227
 
228 228
 		<para>In the initial INVITE if the UAC has requested a
229
-		Session-Expire: and it's value is smaller then our
229
+		Session-Expire: and it's value is smaller than our
230 230
 		local policies Min-SE (see min_se above), then the
231
-		PROXY has the right to reject the call by replying to
232
-		the message with a 422 Session Timer Too Small and
231
+		proxy has the right to reject the call by replying to
232
+		the message with a <quote>422 Session Timer Too Small</quote> and
233 233
 		state our local Min-SE: value. The INVITE is NOT
234
-		forwarded on through the PROXY.</para>
234
+		forwarded on through the proxy.</para>
235 235
 
236
-		<para>This flag if true will tell the SST module to
236
+		<para>If this flag is true, the SST module to
237 237
 		reject the INVITE with a 422 response. If false, the
238
-		INVITE is forwarded through the PROXY with out any
238
+		INVITE is forwarded through the PROXY without any
239 239
 		modifications.</para>
240 240
 
241 241
 		<para>
... ...
@@ -255,21 +262,21 @@ modparam("sst", "reject_to_small", 0)
255 255
 <section>
256 256
 		<title><varname>sst_flag</varname> (integer)</title>
257 257
 		
258
-		<para>Keeping with Kamailio, the module will not do
258
+		<para>Keeping with &kamailio;, the module will not do
259 259
 		anything to any message unless instructed to do so via
260
-		the kamailio.cfg script. You must set the sst_flag
260
+		the &kamailioconfig; script. You must set the sst_flag
261 261
 		value in the setflag() call of the INVITE you want the
262 262
 		sst module to process. But before you can do that, you
263 263
 		need to tell the sst module which flag value you are
264 264
 		assigning to sst.</para>
265 265
 
266
-		<para>In most cases when ever you set the dialog flag
266
+		<para>In most cases whenever you set the dialog flag
267 267
 		you will want to set the sst flag. If the dialog flag
268 268
 		is not set and the sst flag is set, it will not have
269 269
 		any effect.</para>
270 270
 
271
-		<para>This parameter must be set of the module will
272
-		not load.</para>
271
+		<para><emphasis>This parameter must be set or the module will
272
+		not load.</emphasis></para>
273 273
 
274 274
 		<para>
275 275
 		<emphasis>
... ...
@@ -305,7 +312,7 @@ route {
305 305
 
306 306
 		<para>Check the current Session-Expires / MIN-SE values
307 307
 		against the sst_min_se parameter value. If the
308
-		Session-Expires or MIN_SE header value is less then
308
+		Session-Expires or MIN_SE header value is less than the
309 309
 		modules minimum value, this function will return
310 310
 		true. </para>
311 311
 
... ...
@@ -380,7 +387,7 @@ route {
380 380
 
381 381
     <section>
382 382
 	<title>Installation and Running</title>
383
-	<para>just load the module and remember to set the timeout_avp value.</para>
383
+	<para>Just load the module and remember to set the timeout_avp value.</para>
384 384
 	</section>
385 385
 </chapter>
386 386
 
... ...
@@ -34,7 +34,7 @@
34 34
 
35 35
 /*!
36 36
  * \file
37
- * \brief SIP-router core :: 
37
+ * \brief SIP-router core :: Stats reporting code
38 38
  * \ingroup core
39 39
  * Module: \ref core
40 40
  */