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