modules: readme files regenerated - sl ... [skip ci]
[sip-router] / src / modules / sl / README
1 The SL Module - Stateless request handling
2
3 Bogdan Iancu
4
5    FhG FOKUS
6
7 Daniel-Constantin Mierla
8
9    asipto.com
10
11    Copyright © 2003 FhG FOKUS
12      __________________________________________________________________
13
14    Table of Contents
15
16    1. Admin Guide
17
18         1. Overview
19         2. Parameters
20
21               2.1. default_code (int)
22               2.2. default_reason (str)
23               2.3. bind_tm (int)
24
25         3. Functions
26
27               3.1. sl_send_reply(code, reason)
28               3.2. send_reply(code, reason)
29               3.3. sl_reply_error()
30               3.4. sl_forward _reply([ code, [ reason ] ])
31
32         4. Statistics
33
34               4.1. 1xx_replies
35               4.2. 200_replies
36               4.3. 202_replies
37               4.4. 2xx_replies
38               4.5. 300_replies
39               4.6. 301_replies
40               4.7. 302_replies
41               4.8. 3xx_replies
42               4.9. 400_replies
43               4.10. 401_replies
44               4.11. 403_replies
45               4.12. 404_replies
46               4.13. 407_replies
47               4.14. 408_replies
48               4.15. 483_replies
49               4.16. 4xx_replies
50               4.17. 500_replies
51               4.18. 5xx_replies
52               4.19. 6xx_replies
53               4.20. xxx_replies
54               4.21. sent_replies
55               4.22. sent_err_replies
56               4.23. failures
57               4.24. received_ACKs
58
59    List of Examples
60
61    1.1. default_code example
62    1.2. default_reason example
63    1.3. bind_tm example
64    1.4. sl_send_reply usage
65    1.5. send_reply usage
66    1.6. sl_reply_error usage
67    1.7. send_reply usage
68
69 Chapter 1. Admin Guide
70
71    Table of Contents
72
73    1. Overview
74    2. Parameters
75
76         2.1. default_code (int)
77         2.2. default_reason (str)
78         2.3. bind_tm (int)
79
80    3. Functions
81
82         3.1. sl_send_reply(code, reason)
83         3.2. send_reply(code, reason)
84         3.3. sl_reply_error()
85         3.4. sl_forward _reply([ code, [ reason ] ])
86
87    4. Statistics
88
89         4.1. 1xx_replies
90         4.2. 200_replies
91         4.3. 202_replies
92         4.4. 2xx_replies
93         4.5. 300_replies
94         4.6. 301_replies
95         4.7. 302_replies
96         4.8. 3xx_replies
97         4.9. 400_replies
98         4.10. 401_replies
99         4.11. 403_replies
100         4.12. 404_replies
101         4.13. 407_replies
102         4.14. 408_replies
103         4.15. 483_replies
104         4.16. 4xx_replies
105         4.17. 500_replies
106         4.18. 5xx_replies
107         4.19. 6xx_replies
108         4.20. xxx_replies
109         4.21. sent_replies
110         4.22. sent_err_replies
111         4.23. failures
112         4.24. received_ACKs
113
114 1. Overview
115
116    The SL module allows the SIP server to act as a stateless UA server and
117    generate replies to SIP requests without keeping state. That is
118    beneficial in many scenarios, in which you wish not to burden server's
119    memory and scale well.
120
121    The SL module needs to filter ACKs sent after a local stateless reply
122    to an INVITE was generated. To recognize such ACKs, ser adds a special
123    "signature" in to-tags. This signature is sought for in incoming ACKs,
124    and if included, the ACKs are absorbed.
125
126    To speed up the filtering process, the module uses a timeout mechanism.
127    When a reply is sent, a timer us set. As long as the timer is valid,
128    the incoming ACK requests will be checked using TO tag value. Once the
129    timer expires, all the ACK messages are let through - a long time
130    passed till it sent a reply, so it does not expect any ACK that have to
131    be blocked.
132
133    The ACK filtering may fail in some rare cases. If you think these
134    matter to you, better use stateful processing (TM module) for INVITE
135    processing. Particularly, the problem happens when a UA sends an INVITE
136    which already has a to-tag in it (e.g., a re-INVITE) and the server
137    want to reply to it. Then, it will keep the current to-tag, which will
138    be mirrored in ACK. SER will not see its signature and forward the ACK
139    downstream. Caused harm is not bad--just a useless ACK is forwarded.
140
141 2. Parameters
142
143    2.1. default_code (int)
144    2.2. default_reason (str)
145    2.3. bind_tm (int)
146
147 2.1. default_code (int)
148
149    Default reply status code.
150
151    Default value is 500.
152
153    Example 1.1. default_code example
154 ...
155 modparam("sl", "default_code", 505)
156 ...
157
158 2.2. default_reason (str)
159
160    Default reply reason phrase.
161
162    Default value is 'Internal Server Error'.
163
164    Example 1.2. default_reason example
165 ...
166 modparam("sl", "default_reason", "Server Error")
167 ...
168
169 2.3. bind_tm (int)
170
171    Controls if SL module should attempt to bind to TM module in order to
172    send stateful reply when the transaction is created.
173
174    Default value is 1 (enabled).
175
176    Example 1.3. bind_tm example
177 ...
178 modparam("sl", "bind_tm", 0)  # feature disabled
179 ...
180
181 3. Functions
182
183    3.1. sl_send_reply(code, reason)
184    3.2. send_reply(code, reason)
185    3.3. sl_reply_error()
186    3.4. sl_forward _reply([ code, [ reason ] ])
187
188 3.1.  sl_send_reply(code, reason)
189
190    For the current request, a reply is sent back having the given code and
191    text reason. The reply is sent stateless, totally independent of the
192    Transaction module and with no retransmission for the INVITE's replies.
193
194    If the code is in the range 300-399 (redirect reply), the current
195    destination set is appended to the reply as Contact headers. The
196    destination set contains the request URI (R-URI), if it is modified
197    compared to the received one, plus the branches added to the request
198    (e.g., after an append_branch() or lookup("location")). If the R-URI
199    was changed but it is not desired to be part of the destination set, it
200    can be reverted using the function revert_uri().
201
202    Custom headers to the reply can be added using append_to_reply()
203    function from textops module.
204
205    Meaning of the parameters is as follows:
206      * code - Return code.
207      * reason - Reason phrase.
208
209    Example 1.4. sl_send_reply usage
210 ...
211 sl_send_reply("404", "Not found");
212 ...
213
214 3.2.  send_reply(code, reason)
215
216    For the current request, a reply is sent back having the given code and
217    text reason. The reply is sent stateful or stateless, depending of the
218    TM module: if a transaction exists for the current request, then the
219    reply is sent statefully, otherwise stateless.
220
221    Meaning of the parameters is as follows:
222      * code - Return code.
223      * reason - Reason phrase.
224
225    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE. It can
226    be used on ONREPLY_ROUTE executed by tm module (upon a t_on_reply()
227    callback).
228
229    Example 1.5. send_reply usage
230 ...
231 send_reply("404", "Not found");
232 ...
233 send_reply("403", "Invalid user - $fU");
234 ...
235
236 3.3.  sl_reply_error()
237
238    Sends back an error reply describing the nature of the last internal
239    error. Usually this function should be used after a script function
240    that returned an error code.
241
242    Example 1.6. sl_reply_error usage
243 ...
244 sl_reply_error();
245 ...
246
247 3.4.  sl_forward _reply([ code, [ reason ] ])
248
249    Forward statelessy the current received SIP reply, with the option to
250    change the status code and reason text. The new code has to be in the
251    same class. The received reply is forwarded as well by core when the
252    config execution ended, unless it is dropped from config.
253
254    Meaning of the parameters is as follows:
255      * code - Status code.
256      * reason - Reason phrase.
257
258    This function can be used from ONREPLY_ROUTE.
259
260    Example 1.7. send_reply usage
261 ...
262 if(status=="408")
263     sl_forward_reply("404", "Not found");
264 ...
265
266 4. Statistics
267
268    4.1. 1xx_replies
269    4.2. 200_replies
270    4.3. 202_replies
271    4.4. 2xx_replies
272    4.5. 300_replies
273    4.6. 301_replies
274    4.7. 302_replies
275    4.8. 3xx_replies
276    4.9. 400_replies
277    4.10. 401_replies
278    4.11. 403_replies
279    4.12. 404_replies
280    4.13. 407_replies
281    4.14. 408_replies
282    4.15. 483_replies
283    4.16. 4xx_replies
284    4.17. 500_replies
285    4.18. 5xx_replies
286    4.19. 6xx_replies
287    4.20. xxx_replies
288    4.21. sent_replies
289    4.22. sent_err_replies
290    4.23. failures
291    4.24. received_ACKs
292
293 4.1. 1xx_replies
294
295    Number of 1xx replies.
296
297 4.2. 200_replies
298
299    Number of 201 replies.
300
301 4.3. 202_replies
302
303    Number of 202 replies.
304
305 4.4. 2xx_replies
306
307    Number of 2xx replies.
308
309 4.5. 300_replies
310
311    Number of 300 replies.
312
313 4.6. 301_replies
314
315    Number of 301 replies.
316
317 4.7. 302_replies
318
319    Number of 302 replies.
320
321 4.8. 3xx_replies
322
323    Number of 3xx replies.
324
325 4.9. 400_replies
326
327    Number of 400 replies.
328
329 4.10. 401_replies
330
331    Number of 401 replies.
332
333 4.11. 403_replies
334
335    Number of 403 replies.
336
337 4.12. 404_replies
338
339    Number of 404 replies.
340
341 4.13. 407_replies
342
343    Number of 407 replies.
344
345 4.14. 408_replies
346
347    Number of 408 replies.
348
349 4.15. 483_replies
350
351    Number of 483 replies.
352
353 4.16. 4xx_replies
354
355    Number of 4xx replies.
356
357 4.17. 500_replies
358
359    Number of 500 replies.
360
361 4.18. 5xx_replies
362
363    Number of 5xx replies.
364
365 4.19. 6xx_replies
366
367    Number of 6xx replies.
368
369 4.20. xxx_replies
370
371    Number of replies whose code don't match any above.
372
373 4.21. sent_replies
374
375    Number of all sent replies.
376
377 4.22. sent_err_replies
378
379    Number of sent error replies.
380
381 4.23. failures
382
383    Number of failures.
384
385 4.24. received_ACKs
386
387    Number of received ACKs filtered by SL module.