Browse code

- docbook documentation.

Jan Janak authored on 23/07/2003 20:53:27
Showing 5 changed files
... ...
@@ -1,245 +1,473 @@
1
-#
2
-# $Id$
3
-#
4
-# TM Module README
5
-#
6
-# Module depends on: none
7
-#
8
-
9
-TM Module enables stateful processing of SIP transactions.
10
-The main use of stateful logic, which is costly in terms of
11
-memory and CPU, is some services inherently need state.
12
-For example, transaction-based accounting (module acc) needs
13
-to process transaction state as opposed to individual messages,
14
-and any kinds of forking must be implemented statefuly.
15
-Other use of stateful processing is it trading CPU caused by 
16
-retransmission processing for memory. That makes however only
17
-sense if CPU consumption per request is huge. For example,
18
-if you want to avoid costly DNS resolution for every retransmission
19
-of a request to an unresolveable destination, use stateful mode.
20
-Then, only the initial message burdens server by DNS queries,
21
-subsequent retranmissions will be dropped and will not result in
22
-more processes blocked by DNS resolution. The price is more 
23
-memory consumption and higher processing latency.
24
-
25
-From user's perspective, there are two major functions :
26
-t_relay and t_relay_to. Both setup transaction state,
27
-absorb retransmissions from upstream, generate downstream
28
-retransmissions and correlate replies to requests.
29
-t_relay forwards to current uri (be it original request's
30
-uri or a uri changed by some of uri-modifying functions,
31
-such as sethost). t_relay_to forwards to a specific address.
32
-
33
-In general, if TM is used, it copies clones of received SIP
34
-messages in shared memory. That costs the memory and also CPU
35
-time (memcpys, lookups, shmem locks, etc.) Note that non-TM
36
-functions operate over the received message in private memory,
37
-that means that any core operations will have no effect on
38
-statefuly processed messages after creating the transactional
39
-state. For example, calling addRecordRoute *after* t_relay
40
-is pretty useless, as the RR is added to privately held message
41
-whereas its TM clone is being forwarded.
42
-
43
-TM is quite big and uneasy to programm -- lot of mutexes, shared
44
-memory access, malloc & free, timers -- you really need to be careful
45
-when you do anything. To simplify TM programming, there is the
46
-instrument of callbacks. The callback mechanisms allow programmers
47
-to register their functions to specific event. See t_hooks.h
48
-for a list of possible events.
49
-
50
-Other things programmers may want to know is UAC -- it is 
51
-a very simplictic code which allows you to generate your own
52
-transactions. Particularly useful for things like NOTIFYs or
53
-IM gateways. The UAC takes care of all the transaction
54
-machinery: retransmissions , FR timeouts, forking, etc.
55
-See t_uac prototype in uac.h for more details. Who wants to
56
-see the transaction result may register for a callback.
57
-
58
-Exported parameters:
59
-
60
-Name:		fr_timer
61
-Type:		int (seconds)
62
-Default:	FR_TIME_OUT=30
63
-Desc:		timer which hits if no final reply for a request or
64
-			ACK for a negative INVITE reply arrives
65
-
66
-Name:		fr_inv_timer
67
-Type:		int(seconds)
68
-Default:	INV_FR_TIME_OUT=120
69
-Desc:		timer which hits if no final reply for an INVITE
70
-			arrives after a provisional message was received
71
-
72
-Name:		wt_timer
73
-Type:		int (seconds)
74
-Default:	WT_TIME_OUT=5
75
-Desc:		time for which a transaction stays in memory to absorb
76
-			delayed messages after it completed; also, when this
77
-			timer hits, retransmission of local cancels is stopped
78
-			(a puristic but complex behviour would be not to enter
79
-			wait state until local branches are finished by a final
80
-			reply or FR timer -- we simplified)
81
-
82
-Name:		delete_timer
83
-Type:		int (seconds)
84
-Default:	DEL_TIME_OUT=2
85
-Desc:		time after which a to-be-deleted transaction currently
86
-			ref-ed by a process will be tried to be deleted again
87
-
88
-Name:		retr_timer1p1, 2, 3
89
-Type:		int (seconds)
90
-Default:	RETR_T1=1, 2*RETR_T1, 4*RETR_T1
91
-Desc:		retransmission period
92
-
93
-Name:		retr_timer2
94
-Type:		int (seconds)
95
-Default:	RETR_T2=4
96
-Desc:		maximum retransmission period
97
-
98
-Name:		noisy_ctimer
99
-Type:		int (boolean)
100
-Default:	0 (FALSE)
101
-Desc:		if set, on FR timer INVITE transactions will be 
102
-			explicitly cancelled if possible, silently dropped
103
-			otherwise; preferably, it is turned off to allow
104
-			very long ringing; this behaviour is overridden if
105
-			a request is forked, or some functionality explicitly
106
-			turned it off for a transaction (like acc does to avoid
107
-			unaccounted transactions due to expired timer)
108
-
109
-Exported Functions:
110
-
111
-For use in scripts, t_relay_to and t_relay are design. All other
112
-functions are advanced and should be used with care.
113
-
114
-Name: 	t_relay_to
115
-Params:	ip address, port number
116
-Desc:	relay a message statefuly to a fixed destination; this along with
117
-		t_relay is the function most users want to use -- all other are
118
-		mostly for programming; programmers interested in writing TM
119
-		logic should review how t_relay is implemented in tm.c and how
120
-		TM callbacks work
121
-
122
-Name:	t_relay
123
-Params:	0
124
-Desc:	relay a message statefuly to destination indicated in current URI;
125
-		(if the original URI was rewritten by UsrLoc, RR, strip/prefix,
126
-		etc., the new URI will be taken); returns a negative value on
127
-		failure -- you may still want to send a negative reply upstream
128
-		statelessly not to leave upstream UAC in lurch
129
-Example: if (!t_relay()) { sl_reply_error(); break; };
130
-
131
-Name:	t_on_negative
132
-Params:	reply_route
133
-Desc:	sets reply routing block, to which control is passed after
134
-		a transaction completed with a negative result but before
135
-		sending a final reply; In the refered block, you can
136
-		either start a new branch (good for services such as
137
-		forward_on_no_reply) or send a final reply on your own
138
-		(good for example for message silo, which received 
139
-		a negative reply from upstream and wants to tell
140
-		upstream "202 I will take care of it"); Note that the
141
-		set of command which are useable within reply_routes is
142
-		strictly limited to rewriting URI, initiating new branches,
143
-		logging, and sending stateful replies (t_reply). Any 
144
-		other commands may result in unpredictable behaviour and 
145
-		possible server failure.
146
-		Note that whenever reply_route is entered, uri is reset to
147
-		value which it had on relaying. If it temporarily changed
148
-		during a reply_route processing, subsequent reply_route
149
-		will ignore the changed value and use again the original
150
-		one.
151
-Example: route { t_on_negative("1"); t_relay(); } reply_route[1] {
152
-			revert_uri(); setuser("voicemail"); append_branch(); }
153
-
154
-		see test/onr.cfg for a more complex example of combination
155
-		of serial with parallel forking
156
-
157
-
158
-Name:	append_branch (actually part of core now)
159
-Params:	uri
160
-Desc:	adds a new destination to destination set; if used,
161
-		a subsequent call to t_relay (or t_forward_nonack, 
162
-		on which t_relay is based) than introduces
163
-	    a new branch and forks a transaction; append_branch may
164
-		also be called from reply processing -- this may 
165
-	    be particularly useful for services such as
166
-		"fork_on_no_reply"
167
-
168
-Name:	append_branch
169
-Params:	0
170
-Desc:	similarly to t_fork_to, it extends destination set
171
-		by a new entry; the difference is that current uri
172
-		is taken as new entry;
173
-Example: set_user("john"); t_fork(); set_user("alice");
174
-		 t_fork(); t_relay();
175
-
176
-
177
-Name:	t_newtran
178
-Params: 0
179
-Desc:	creates a new transaction, returns a negative value on 
180
-	    error; this is the only way a script can add a new transaction 
181
-	    in an atomic way; typically, it is used to deploy a UAS
182
-Example: see test/uas.cfg: 
183
-	    if (t_newtran()) { log("UAS logic"); t_reply("999","hello"); }
184
-		else sl_reply_error();
185
-
186
-Name:	t_reply
187
-Params:	code, reason phrase
188
-Desc: 	sends a stateful reply after a transaction has been
189
-		established; see t_newtran for usage; 
190
-
191
-
192
-Name:	t_lookup_request
193
-Params:	0
194
-Desc:	checks if a transaction exists; returns a positive value
195
-		if so, negative otherwise; most likely you will not want
196
-	    to use it, as a typicall application of a looku-up is to
197
-	    introduce a new transaction if none was found; however
198
-	    this is safely (atomically) done using t_newtran
199
-
200
-
201
-Name:	t_retransmit_reply
202
-Params:	0
203
-Desc:	retransmits a reply sent previously by UAS transaction
204
-
205
-Name:	t_release
206
-Params:	0
207
-Desc:	remove transaction from memory (it will be first put on
208
-		a wait timer to absorb delayed messages)
209
-
210
-Name:	t_forward_nonack
211
-Params:	ip, port
212
-Desc:	mainly for internal -- forward a non-ACK request statefuly
213
-
214
-Name:	register_tmcb
215
-Params:	callback type, callback function
216
-Desc:	for programmatic use only -- register a function to be called
217
-		back on an event; see t_hooks.h for more details
218
-
219
-Name:	load_tm
220
-Params:	*import_structure
221
-Desc:	for programmatic use only -- import exported TM functions;
222
-		see the acc module for an example of use
223
-
224
-
225
-External Usage of TM
226
-There are applications which would like to generate SIP
227
-transactions without too big involvement in SIP stack, transaction
228
-management, etc. An example of such an application
229
-is sending instant messages from a website. To address needs
230
-of such apps, SER accepts requests for new transactions via
231
-fifo pipes too. If you want to enable this feature, start
232
-FIFO server with configuration option
233
-	fifo="/tmp/ser_fifo"
234
-Then, an application can easily launch a new transaction by
235
-writing a transaction request to this named pipe. The request
236
-must follow very simple format, which is
237 1
 
2
+tm Module
3
+
4
+Jiri Kuthan
5
+
6
+   FhG FOKUS
7
+
8
+Edited by
9
+
10
+Jiri Kuthan
11
+
12
+   Copyright � 2003 FhG FOKUS
13
+     _________________________________________________________
14
+
15
+   Table of Contents
16
+   1. User's Guide
17
+
18
+        1.1. Overview
19
+        1.2. Dependencies
20
+
21
+              1.2.1. SER Modules
22
+              1.2.2. External Libraries or Applications
23
+
24
+        1.3. Exported Parameters
25
+
26
+              1.3.1. fr_timer (integer)
27
+              1.3.2. fr_inv_timer (integer)
28
+              1.3.3. wt_timer (integer)
29
+              1.3.4. delete_timer (integer)
30
+              1.3.5. retr_timer1p1 (integer)
31
+              1.3.6. retr_timer1p2 (integer)
32
+              1.3.7. retr_timer1p3 (integer)
33
+              1.3.8. retr_timer2 (integer)
34
+              1.3.9. noisy_ctimer (integer)
35
+
36
+        1.4. Exported Functions
37
+
38
+              1.4.1. t_relay_to(ip, port)
39
+              1.4.2. t_relay()
40
+              1.4.3. t_on_negative(reply_route)
41
+              1.4.4. append_branch()
42
+              1.4.5. t_newtran()
43
+              1.4.6. t_reply(code, reason_phrase)
44
+              1.4.7. t_lookup_request()
45
+              1.4.8. t_retransmit_reply()
46
+              1.4.9. t_release()
47
+              1.4.10. t_forward_nonack(ip, port)
48
+              1.4.11. External Usage of TM
49
+              1.4.12. Known Issues
50
+
51
+   2. Developer's Guide
52
+
53
+        2.1. Defines
54
+        2.2. Functions
55
+
56
+              2.2.1. register_tmcb(cb_type, cb_func)
57
+              2.2.2. load_tm(*import_structure)
58
+
59
+   3. Frequently Asked Questions
60
+
61
+   List of Examples
62
+   1-1. Set fr_timer parameter
63
+   1-2. Set fr_inv_timer parameter
64
+   1-3. Set wt_timer parameter
65
+   1-4. Set delete_timer parameter
66
+   1-5. Set retr_timer1p1 parameter
67
+   1-6. Set retr_timer1p2 parameter
68
+   1-7. Set retr_timer1p4 parameter
69
+   1-8. Set retr_timer2 parameter
70
+   1-9. Set noisy_ctimer parameter
71
+   1-10. t_relay_to usage
72
+   1-11. t_relay usage
73
+   1-12. t_on_negative usage
74
+   1-13. append_branch usage
75
+   1-14. t_newtran usage
76
+   1-15. t_reply usage
77
+   1-16. t_lookup_request usage
78
+   1-17. t_retransmit_reply usage
79
+   1-18. t_release usage
80
+   1-19. t_forward_nonack usage
81
+     _________________________________________________________
82
+
83
+Chapter 1. User's Guide
84
+
85
+1.1. Overview
86
+
87
+   TM module enables stateful processing of SIP transactions. The
88
+   main use of stateful logic, which is costly in terms of memory
89
+   and CPU, is some services inherently need state. For example,
90
+   transaction-based accounting (module acc) needs to process
91
+   transaction state as opposed to individual messages, and any
92
+   kinds of forking must be implemented statefuly. Other use of
93
+   stateful processing is it trading CPU caused by retransmission
94
+   processing for memory. That makes however only sense if CPU
95
+   consumption per request is huge. For example, if you want to
96
+   avoid costly DNS resolution for every retransmission of a
97
+   request to an unresolveable destination, use stateful mode.
98
+   Then, only the initial message burdens server by DNS queries,
99
+   subsequent retranmissions will be dropped and will not result
100
+   in more processes blocked by DNS resolution. The price is more
101
+   memory consumption and higher processing latency.
102
+
103
+   From user's perspective, there are two major functions :
104
+   t_relay and t_relay_to. Both setup transaction state, absorb
105
+   retransmissions from upstream, generate downstream
106
+   retransmissions and correlate replies to requests. t_relay
107
+   forwards to current URI (be it original request's URI or a URI
108
+   changed by some of URI-modifying functions, such as sethost).
109
+   t_relay_to forwards to a specific address.
110
+
111
+   In general, if TM is used, it copies clones of received SIP
112
+   messages in shared memory. That costs the memory and also CPU
113
+   time (memcpys, lookups, shmem locks, etc.) Note that non-TM
114
+   functions operate over the received message in private memory,
115
+   that means that any core operations will have no effect on
116
+   statefuly processed messages after creating the transactional
117
+   state. For example, calling record_route after t_relay is
118
+   pretty useless, as the RR is added to privately held message
119
+   whereas its TM clone is being forwarded.
120
+
121
+   TM is quite big and uneasy to programm--lot of mutexes, shared
122
+   memory access, malloc & free, timers--you really need to be
123
+   careful when you do anything. To simplify TM programming,
124
+   there is the instrument of callbacks. The callback mechanisms
125
+   allow programmers to register their functions to specific
126
+   event. See t_hooks.h for a list of possible events.
127
+
128
+   Other things programmers may want to know is UAC--it is a very
129
+   simplictic code which allows you to generate your own
130
+   transactions. Particularly useful for things like NOTIFYs or
131
+   IM gateways. The UAC takes care of all the transaction
132
+   machinery: retransmissions , FR timeouts, forking, etc. See
133
+   t_uac prototype in uac.h for more details. Who wants to see
134
+   the transaction result may register for a callback.
135
+     _________________________________________________________
136
+
137
+1.2. Dependencies
138
+
139
+1.2.1. SER Modules
140
+
141
+   The following modules must be loaded before this module:
142
+
143
+     * No dependencies on other SER modules.
144
+     _________________________________________________________
145
+
146
+1.2.2. External Libraries or Applications
147
+
148
+   The following libraries or applications must be installed
149
+   before running SER with this module loaded:
150
+
151
+     * None.
152
+     _________________________________________________________
153
+
154
+1.3. Exported Parameters
155
+
156
+1.3.1. fr_timer (integer)
157
+
158
+   Timer which hits if no final reply for a request or ACK for a
159
+   negative INVITE reply arrives (in seconds).
160
+
161
+   Default value is 30 seconds. 
162
+
163
+   Example 1-1. Set fr_timer parameter
164
+...
165
+modparam("tm", "fr_timer", 10)
166
+...
167
+     _________________________________________________________
168
+
169
+1.3.2. fr_inv_timer (integer)
170
+
171
+   Timer which hits if no final reply for an INVITE arrives after
172
+   a provisional message was received (in seconds).
173
+
174
+   Default value is 120 seconds. 
175
+
176
+   Example 1-2. Set fr_inv_timer parameter
177
+...
178
+modparam("tm", "fr_inv_timer", 200)
179
+...
180
+     _________________________________________________________
181
+
182
+1.3.3. wt_timer (integer)
183
+
184
+   Time for which a transaction stays in memory to absorb delayed
185
+   messages after it completed; also, when this timer hits,
186
+   retransmission of local cancels is stopped (a puristic but
187
+   complex behviour would be not to enter wait state until local
188
+   branches are finished by a final reply or FR timer--we
189
+   simplified).
190
+
191
+   Default value is 5 seconds. 
192
+
193
+   Example 1-3. Set wt_timer parameter
194
+...
195
+modparam("tm", "wt_timer", 10)
196
+...
197
+     _________________________________________________________
198
+
199
+1.3.4. delete_timer (integer)
200
+
201
+   Time after which a to-be-deleted transaction currently ref-ed
202
+   by a process will be tried to be deleted again.
203
+
204
+   Default value is 2 seconds. 
205
+
206
+   Example 1-4. Set delete_timer parameter
207
+...
208
+modparam("tm", "delete_timer", 5)
209
+...
210
+     _________________________________________________________
211
+
212
+1.3.5. retr_timer1p1 (integer)
213
+
214
+   Retransmission period.
215
+
216
+   Default value is 1 second. 
217
+
218
+   Example 1-5. Set retr_timer1p1 parameter
219
+...
220
+modparam("tm", "retr_timer1p1", 2)
221
+...
222
+     _________________________________________________________
223
+
224
+1.3.6. retr_timer1p2 (integer)
225
+
226
+   Retransmission period.
227
+
228
+   Default value is 2 * retr_timer1p1 second. 
229
+
230
+   Example 1-6. Set retr_timer1p2 parameter
231
+...
232
+modparam("tm", "retr_timer1p2", 4)
233
+...
234
+     _________________________________________________________
235
+
236
+1.3.7. retr_timer1p3 (integer)
237
+
238
+   Retransmission period.
239
+
240
+   Default value is 4 * retr_timer1p1 second. 
241
+
242
+   Example 1-7. Set retr_timer1p4 parameter
243
+...
244
+modparam("tm", "retr_timer1p3", 8)
245
+...
246
+     _________________________________________________________
247
+
248
+1.3.8. retr_timer2 (integer)
249
+
250
+   Maximum retransmission period.
251
+
252
+   Default value is 4 seconds. 
253
+
254
+   Example 1-8. Set retr_timer2 parameter
255
+...
256
+modparam("tm", "retr_timer2", 8)
257
+...
258
+     _________________________________________________________
259
+
260
+1.3.9. noisy_ctimer (integer)
261
+
262
+   If set, on FR timer INVITE transactions will be explicitly
263
+   cancelled if possible, silently dropped otherwise. Preferably,
264
+   it is turned off to allow very long ringing. This behaviour is
265
+   overridden if a request is forked, or some functionality
266
+   explicitly turned it off for a transaction (like acc does to
267
+   avoid unaccounted transactions due to expired timer).
268
+
269
+   Default value is 0 (false). 
270
+
271
+   Example 1-9. Set noisy_ctimer parameter
272
+...
273
+modparam("tm", "noisy_ctimer", 1)
274
+...
275
+     _________________________________________________________
276
+
277
+1.4. Exported Functions
278
+
279
+1.4.1. t_relay_to(ip, port)
280
+
281
+   Relay a message statefuly to a fixed destination. This along
282
+   with t_relay is the function most users want to use--all other
283
+   are mostly for programming. Programmers interested in writing
284
+   TM logic should review how t_relay is implemented in tm.c and
285
+   how TM callbacks work.
286
+
287
+   Meaning of the parameters is as follows:
288
+
289
+     * ip - IP address where the message should be sent.
290
+     * port - Port number.
291
+
292
+   Example 1-10. t_relay_to usage
293
+...
294
+t_relay_to("1.2.3.4", "5060");
295
+...
296
+     _________________________________________________________
297
+
298
+1.4.2. t_relay()
299
+
300
+   Relay a message statefuly to destination indicated in current
301
+   URI. (If the original URI was rewritten by UsrLoc, RR,
302
+   strip/prefix, etc., the new URI will be taken). Returns a
303
+   negative value on failure--you may still want to send a
304
+   negative reply upstream statelessly not to leave upstream UAC
305
+   in lurch.
306
+
307
+   Example 1-11. t_relay usage
308
+...
309
+if (!t_relay()) { sl_reply_error(); break; };
310
+...
311
+     _________________________________________________________
312
+
313
+1.4.3. t_on_negative(reply_route)
314
+
315
+   Sets reply routing block, to which control is passed after a
316
+   transaction completed with a negative result but before
317
+   sending a final reply. In the refered block, you can either
318
+   start a new branch (good for services such as
319
+   forward_on_no_reply) or send a final reply on your own (good
320
+   for example for message silo, which received a negative reply
321
+   from upstream and wants to tell upstream "202 I will take care
322
+   of it"). Note that the set of command which are useable within
323
+   reply_routes is strictly limited to rewriting URI, initiating
324
+   new branches, logging, and sending stateful replies (t_reply).
325
+   Any other commands may result in unpredictable behaviour and
326
+   possible server failure. Note that whenever reply_route is
327
+   entered, uri is reset to value which it had on relaying. If it
328
+   temporarily changed during a reply_route processing,
329
+   subsequent reply_route will ignore the changed value and use
330
+   again the original one.
331
+
332
+   Meaning of the parameters is as follows:
333
+
334
+     * reply_route - Reply route block to be called.
335
+
336
+   Example 1-12. t_on_negative usage
337
+...
338
+route {
339
+    t_on_negative("1");
340
+    t_relay();
341
+}
342
+
343
+reply_route[1] {
344
+    revert_uri();
345
+    setuser("voicemail");
346
+    append_branch();
347
+}
348
+...
349
+
350
+   See test/onr.cfg for a more complex example of combination of
351
+   serial with parallel forking.
352
+     _________________________________________________________
353
+
354
+1.4.4. append_branch()
355
+
356
+   Similarly to t_fork_to, it extends destination set by a new
357
+   entry. The difference is that current URI is taken as new
358
+   entry.
359
+
360
+   Example 1-13. append_branch usage
361
+...
362
+set_user("john");
363
+t_fork();
364
+set_user("alice");
365
+t_fork();
366
+t_relay();
367
+...
368
+     _________________________________________________________
369
+
370
+1.4.5. t_newtran()
371
+
372
+   Creates a new transaction, returns a negative value on error.
373
+   This is the only way a script can add a new transaction in an
374
+   atomic way. Typically, it is used to deploy a UAS.
375
+
376
+   Example 1-14. t_newtran usage
377
+...
378
+if (t_newtran()) {
379
+    log("UAS logic");
380
+    t_reply("999","hello");
381
+} else sl_reply_error();
382
+...
383
+
384
+   See test/uas.cfg for more examples.
385
+     _________________________________________________________
386
+
387
+1.4.6. t_reply(code, reason_phrase)
388
+
389
+   Sends a stateful reply after a transaction has been
390
+   established. See t_newtran for usage.
391
+
392
+   Meaning of the parameters is as follows:
393
+
394
+     * code - Reply code number.
395
+     * reason_phrase - Reason string.
396
+
397
+   Example 1-15. t_reply usage
398
+...
399
+t_reply("404", "Not found");
400
+...
401
+     _________________________________________________________
402
+
403
+1.4.7. t_lookup_request()
404
+
405
+   Checks if a transaction exists. Returns a positive value if
406
+   so, negative otherwise. Most likely you will not want to use
407
+   it, as a typicall application of a looku-up is to introduce a
408
+   new transaction if none was found. However this is safely
409
+   (atomically) done using t_newtran.
410
+
411
+   Example 1-16. t_lookup_request usage
412
+...
413
+if (t_lookup_request()) {
414
+    ...
415
+};
416
+...
417
+     _________________________________________________________
418
+
419
+1.4.8. t_retransmit_reply()
420
+
421
+   Retransmits a reply sent previously by UAS transaction.
422
+
423
+   Example 1-17. t_retransmit_reply usage
424
+...
425
+t_retransmit_reply();
426
+...
427
+     _________________________________________________________
428
+
429
+1.4.9. t_release()
430
+
431
+   Remove transaction from memory (it will be first put on a wait
432
+   timer to absorb delayed messages).
433
+
434
+   Example 1-18. t_release usage
435
+...
436
+t_release();
437
+...
438
+     _________________________________________________________
439
+
440
+1.4.10. t_forward_nonack(ip, port)
441
+
442
+   mainly for internal usage--forward a non-ACK request
443
+   statefuly.
444
+
445
+   Meaning of the parameters is as follows:
446
+
447
+     * ip - IP address where the message should be sent.
448
+     * port - Port number.
449
+
450
+   Example 1-19. t_forward_nonack usage
451
+...
452
+t_forward_nonack("1.2.3.4", "5060");
453
+...
454
+     _________________________________________________________
455
+
456
+1.4.11. External Usage of TM
457
+
458
+   There are applications which would like to generate SIP
459
+   transactions without too big involvement in SIP stack,
460
+   transaction management, etc. An example of such an application
461
+   is sending instant messages from a website. To address needs
462
+   of such apps, SER accepts requests for new transactions via
463
+   fifo pipes too. If you want to enable this feature, start FIFO
464
+   server with configuration option.
465
+
466
+   fifo="/tmp/ser_fifo"
467
+
468
+   Then, an application can easily launch a new transaction by
469
+   writing a transaction request to this named pipe. The request
470
+   must follow very simple format, which is
238 471
  :t_uac_from:[<file_name>]\n
239 472
  <method>\n
240 473
  <sender's uri>\n
... ...
@@ -249,15 +477,12 @@ must follow very simple format, which is
249 477
  .\n
250 478
  \n
251 479
 
252
-(Filename is to where a report will be dumped. ser assumes /tmp
253
-as file's directory.)
480
+   (Filename is to where a report will be dumped. ser assumes
481
+   /tmp as file's directory.)
254 482
 
255
-Note the the request write must be atomic, otherwise it
256
-might get intermixed with writes from other writers.
257
-You can easily use it via Unix command-line tools, see 
258
-the following
259
-example:
483
+   Note the the request write must be atomic, otherwise it might
484
+   get intermixed with writes from other writers. You can easily
485
+   use it via Unix command-line tools, see the following example:
260 486
 [jiri@bat jiri]$ cat > /tmp/ser_fifo
261 487
 :t_uac_from:xxx
262 488
 MESSAGE
... ...
@@ -273,58 +498,111 @@ yet body
273 498
 end of body
274 499
 .
275 500
 
276
-or cat test/transaction.fifo > /tmp/ser_fifo
277
-
278
-Defines
279
-- ACK_TAG enables stricter matching of acknowledgemnts including to-tags;
280
-  without it, to-tags are ignored; it is disabled by default for two reasons:
281
-  a) it eliminates an unlikely race condition in which
282
-     transaction's to-tag is being rewritten by a 200 OK
283
-     whereas an ACK is being looked up by to-tag
284
-  b) it makes UACs happy who set wrong to-tags
285
-
286
-  It should not make a difference, as there may be only one
287
-  negative reply sent upstream and 200/ACKs are not matched
288
-  as they consititute another transaction. It will make no
289
-  difference at all when the new magic cookie matching is
290
-  enabled anyway.
291
-- CANCEL_TAG similarly enables strict matching of CANCELs 
292
-  including to-tags -- act of mercy to UACs, who screw up
293
-  the to-tags (however, it still depends on how forgiving
294
-  the downstream UAS is); like with ACK_TAG, all this
295
-  complex transactions matching goes with RFC3261's
296
-  magic cookie away anyway
297
-
298
-
299
-
300
-Known Issues
301
-- we don't have authentication merging on forking
302
-- local ACK/CANCELs copy'n'pastes Route and ignores deleted
303
-  Routes
304
-- 6xx should be delayed
305
-- possibly, performance could be improved by not parsing non-INVITEs,
306
-  as they do not be replied with 100, and do not result in ACK/CANCELs,
307
-  and other things which take parsing. However, we need to rethink
308
-  whether we don't need parsed headers later for something else.
309
-  Remember, when we now conserver a request in sh_mem, we can't apply
310
-  any pkg_mem operations to it any more. (that might be redesigned too)
311
-- another performance improvement may be achieved by not parsing
312
-  CSeq in replies until reply branch matches branch of an INVITE/CANCEL
313
-  in transaction table
314
-- t_replicate should be done more cleanly -- Vias, Routes, etc. should
315
-  be removed from a message prior to replicating it (well, does not matter
316
-  any longer so much as there is a new replication module)
317
-- SNMP support (as nobody cares about SNMP, in particular for TM, I will
318
-  drop this item soon)
319
-
320
-
321
- * ***************************************************
322
- *             IMPORTANT NOTE
323
- *
324
- *    All UACs but t_uac_dlg are being deprecated now
325
- *    and will be removed from future versions of TM
326
- *    module. Eliminate all dependancies on them asap.
327
- *
328
- * ****************************************************
501
+   or cat test/transaction.fifo > /tmp/ser_fifo
502
+     _________________________________________________________
503
+
504
+1.4.12. Known Issues
505
+
506
+     * We don't have authentication merging on forking.
507
+     * Local ACK/CANCELs copy'n'pastes Route and ignores deleted
508
+       Routes.
509
+     * 6xx should be delayed.
510
+     * Possibly, performance could be improved by not parsing
511
+       non-INVITEs, as they do not be replied with 100, and do
512
+       not result in ACK/CANCELs, and other things which take
513
+       parsing. However, we need to rethink whether we don't need
514
+       parsed headers later for something else. Remember, when we
515
+       now conserver a request in sh_mem, we can't apply any
516
+       pkg_mem operations to it any more. (that might be
517
+       redesigned too).
518
+     * Another performance improvement may be achieved by not
519
+       parsing CSeq in replies until reply branch matches branch
520
+       of an INVITE/CANCEL in transaction table.
521
+     * t_replicate should be done more cleanly--Vias, Routes,
522
+       etc. should be removed from a message prior to replicating
523
+       it (well, does not matter any longer so much as there is a
524
+       new replication module).
525
+     * SNMP support (as nobody cares about SNMP, in particular
526
+       for TM, I will drop this item soon).
527
+     _________________________________________________________
528
+
529
+Chapter 2. Developer's Guide
530
+
531
+   The module does not provide any sort of API to use in other
532
+   SER modules.
533
+     _________________________________________________________
534
+
535
+2.1. Defines
536
+
537
+     * ACK_TAG enables stricter matching of acknowledgemnts
538
+       including to-tags. Without it, to-tags are ignored. It is
539
+       disabled by default for two reasons:
540
+          + It eliminates an unlikely race condition in which
541
+            transaction's to-tag is being rewritten by a 200 OK
542
+            whereas an ACK is being looked up by to-tag.
543
+          + It makes UACs happy who set wrong to-tags.
544
+       It should not make a difference, as there may be only one
545
+       negative reply sent upstream and 200/ACKs are not matched
546
+       as they consititute another transaction. It will make no
547
+       difference at all when the new magic cookie matching is
548
+       enabled anyway.
549
+     * CANCEL_TAG similarly enables strict matching of CANCELs
550
+       including to-tags--act of mercy to UACs, who screw up the
551
+       to-tags (however, it still depends on how forgiving the
552
+       downstream UAS is). Like with ACK_TAG, all this complex
553
+       transactions matching goes with RFC3261's magic cookie
554
+       away anyway.
555
+     _________________________________________________________
556
+
557
+2.2. Functions
558
+
559
+2.2.1. register_tmcb(cb_type, cb_func)
560
+
561
+   For programmatic use only--register a function to be called
562
+   back on an event. See t_hooks.h for more details.
563
+
564
+   Meaning of the parameters is as follows:
565
+
566
+     * cb_type - Callback type.
567
+     * cb_func - Callback function.
568
+     _________________________________________________________
569
+
570
+2.2.2. load_tm(*import_structure)
571
+
572
+   For programmatic use only--import exported TM functions. See
573
+   the acc module for an example of use.
574
+
575
+   Meaning of the parameters is as follows:
576
+
577
+     * import_structure - Pointer to the import structure.
578
+     _________________________________________________________
579
+
580
+Chapter 3. Frequently Asked Questions
581
+
582
+   3.1. Where can I find more about SER?
583
+   3.2. Where can I post a question about this module?
584
+   3.3. How can I report a bug?
585
+
586
+   3.1. Where can I find more about SER?
587
+
588
+   Take a look at http://iptel.org/ser.
589
+
590
+   3.2. Where can I post a question about this module?
591
+
592
+   First at all check if your question was already answered on
593
+   one of our mailing lists:
594
+
595
+     * http://mail.iptel.org/mailman/listinfo/serusers
596
+     * http://mail.iptel.org/mailman/listinfo/serdev
597
+
598
+   E-mails regarding any stable version should be sent to
599
+   <serusers@iptel.org> and e-mail regarding development versions
600
+   or CVS snapshots should be send to <serdev@iptel.org>.
601
+
602
+   If you want to keep the mail private, send it to
603
+   <serhelp@iptel.org>.
604
+
605
+   3.3. How can I report a bug?
606
+
607
+   Please follow the guidelines provided at:
608
+   http://iptel.org/ser/bugs
329 609
new file mode 100644
... ...
@@ -0,0 +1,52 @@
1
+<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
2
+
3
+
4
+<!ENTITY user SYSTEM "tm_user.sgml">
5
+<!ENTITY devel SYSTEM "tm_devel.sgml">
6
+<!ENTITY faq SYSTEM "tm_faq.sgml">
7
+
8
+<!-- Include general SER documentation entities -->
9
+<!ENTITY % serentities SYSTEM "../../../doc/ser_entities.sgml">
10
+%serentities;
11
+
12
+]>
13
+
14
+<book>
15
+    <bookinfo>
16
+	<title>tm Module</title>
17
+	<productname class="trade">&sername;</productname>
18
+	<authorgroup>
19
+	    <author>
20
+		<firstname>Jiri</firstname>
21
+		<surname>Kuthan</surname>
22
+		<affiliation><orgname>&fhg;</orgname></affiliation>
23
+		<address>
24
+		    <email>jiri@iptel.org</email>
25
+		</address>
26
+	    </author>
27
+	    <editor>
28
+		<firstname>Jiri</firstname>
29
+		<surname>Kuthan</surname>
30
+		<address>
31
+		    <email>jiri@iptel.org</email>
32
+		</address>
33
+	    </editor>
34
+	</authorgroup>
35
+	<copyright>
36
+	    <year>2003</year>
37
+	    <holder>&fhg;</holder>
38
+	</copyright>
39
+	<revhistory>
40
+	    <revision>
41
+		<revnumber>$Revision$</revnumber>
42
+		<date>$Date$</date>
43
+	    </revision>
44
+	</revhistory>
45
+    </bookinfo>
46
+    <toc></toc>
47
+    
48
+    &user;
49
+    &devel;
50
+    &faq;
51
+    
52
+</book>
0 53
new file mode 100644
... ...
@@ -0,0 +1,106 @@
1
+<!-- Module Developer's Guide -->
2
+
3
+<chapter>
4
+    <chapterinfo>
5
+	<revhistory>
6
+	    <revision>
7
+		<revnumber>$Revision$</revnumber>
8
+		<date>$Date$</date>
9
+	    </revision>
10
+	</revhistory>
11
+    </chapterinfo>
12
+    <title>Developer's Guide</title>
13
+    <para>
14
+	The module does not provide any sort of <acronym>API</acronym> to use in other &ser; modules.	
15
+    </para>
16
+    <section>
17
+	<title>Defines</title>
18
+	<itemizedlist>
19
+	    <listitem>
20
+		<para>
21
+		    ACK_TAG enables stricter matching of acknowledgemnts including to-tags. Without
22
+		    it, to-tags are ignored. It is disabled by default for two reasons: 
23
+		</para>
24
+		<itemizedlist>
25
+		    <listitem>
26
+			<para>
27
+			    It eliminates an unlikely race condition in which transaction's to-tag
28
+			    is being rewritten by a 200 OK whereas an ACK is being looked up by
29
+			    to-tag.
30
+			</para>
31
+		    </listitem>
32
+		</itemizedlist>
33
+		<itemizedlist>
34
+		    <listitem>
35
+			<para>
36
+			    It makes &uac;s happy who set wrong to-tags.
37
+			</para>
38
+		    </listitem>
39
+		</itemizedlist>
40
+		<para>
41
+		    It should not make a difference, as there may be only one
42
+		    negative reply sent upstream and 200/ACKs are not matched
43
+		    as they consititute another transaction. It will make no
44
+		    difference at all when the new magic cookie matching is
45
+		    enabled anyway.
46
+		</para>
47
+	    </listitem>
48
+	    <listitem>
49
+		<para>
50
+		    CANCEL_TAG similarly enables strict matching of CANCELs 
51
+		    including to-tags--act of mercy to &uac;s, who screw up
52
+		    the to-tags (however, it still depends on how forgiving
53
+		    the downstream UAS is). Like with ACK_TAG, all this
54
+		    complex transactions matching goes with &rfc3261;'s
55
+		    magic cookie away anyway.
56
+		</para>
57
+	    </listitem>
58
+	</itemizedlist>
59
+    </section>
60
+    <section>
61
+	<title>Functions</title>
62
+	<section>
63
+	    <title>
64
+		<function moreinfo="none">register_tmcb(cb_type, cb_func)</function>
65
+	    </title>
66
+	    <para>
67
+		For programmatic use only--register a function to be called back on an event. See
68
+		t_hooks.h for more details.
69
+	    </para>
70
+	    <para>Meaning of the parameters is as follows:</para>
71
+	    <itemizedlist>
72
+		<listitem>
73
+		    <para><emphasis>cb_type</emphasis> - Callback type.
74
+		    </para>
75
+		</listitem>
76
+		<listitem>
77
+		    <para><emphasis>cb_func</emphasis> - Callback function.
78
+		    </para>
79
+		</listitem>
80
+	    </itemizedlist>
81
+	</section>
82
+
83
+	<section>
84
+	    <title>
85
+		<function moreinfo="none">load_tm(*import_structure)</function>
86
+	    </title>
87
+	    <para>
88
+		For programmatic use only--import exported <acronym>TM</acronym> functions.
89
+		See the acc module for an example of use.
90
+	    </para>
91
+	    <para>Meaning of the parameters is as follows:</para>
92
+	    <itemizedlist>
93
+		<listitem>
94
+		    <para><emphasis>import_structure</emphasis> - Pointer to the import structure.
95
+		    </para>
96
+		</listitem>
97
+	    </itemizedlist>
98
+	</section>
99
+    </section>
100
+</chapter>
101
+
102
+<!-- Keep this element at the end of the file
103
+Local Variables:
104
+sgml-parent-document: ("tm.sgml" "book" "chapter")
105
+End:
106
+-->
0 107
new file mode 100644
... ...
@@ -0,0 +1,67 @@
1
+<!-- Module FAQ -->
2
+
3
+<chapter>
4
+    <chapterinfo>
5
+	<revhistory>
6
+	    <revision>
7
+		<revnumber>$Revision$</revnumber>
8
+		<date>$Date$</date>
9
+	    </revision>
10
+	</revhistory>
11
+    </chapterinfo>
12
+    <title>Frequently Asked Questions</title>
13
+    <qandaset defaultlabel="number">
14
+	<qandaentry>
15
+	    <question>
16
+		<para>Where can I find more about &ser;?</para>
17
+	    </question>
18
+	    <answer>
19
+		<para>
20
+		    Take a look at &serhomelink;.
21
+		</para>
22
+	    </answer>
23
+	</qandaentry>
24
+	<qandaentry>
25
+	    <question>
26
+		<para>Where can I post a question about this module?</para>
27
+	    </question>
28
+	    <answer>
29
+		<para>
30
+		    First at all check if your question was already answered on one of
31
+		    our mailing lists: 
32
+		</para>
33
+		<itemizedlist>
34
+		    <listitem>
35
+			<para>&seruserslink;</para>
36
+		    </listitem>
37
+		    <listitem>
38
+			<para>&serdevlink;</para>
39
+		    </listitem>
40
+		</itemizedlist>
41
+		<para>
42
+		    E-mails regarding any stable version should be sent to &serusersmail; and e-mail
43
+		    regarding development versions or CVS snapshots should be send to &serdevmail;.
44
+		</para>
45
+		<para>
46
+		    If you want to keep the mail private, send it to &serhelpmail;.
47
+		</para>
48
+	    </answer>
49
+	</qandaentry>
50
+	<qandaentry>
51
+	    <question>
52
+		<para>How can I report a bug?</para>
53
+	    </question>
54
+	    <answer>
55
+		<para>
56
+		    Please follow the guidelines provided at: &serbugslink;
57
+		</para>
58
+	    </answer>
59
+	</qandaentry>
60
+    </qandaset>
61
+</chapter>
62
+
63
+<!-- Keep this element at the end of the file
64
+Local Variables:
65
+sgml-parent-document: ("tm.sgml" "Book" "chapter")
66
+End:
67
+-->
0 68
new file mode 100644
... ...
@@ -0,0 +1,666 @@
1
+<!-- Module User's Guide -->
2
+
3
+<chapter>
4
+    <chapterinfo>
5
+	<revhistory>
6
+	    <revision>
7
+		<revnumber>$Revision$</revnumber>
8
+		<date>$Date$</date>
9
+	    </revision>
10
+	</revhistory>
11
+    </chapterinfo>
12
+    <title>User's Guide</title>
13
+    
14
+    <section>
15
+	<title>Overview</title>
16
+	<para>
17
+	    <acronym>TM</acronym> module enables stateful processing of &sip; transactions. The main
18
+	    use of stateful logic, which is costly in terms of memory and <acronym>CPU</acronym>, is
19
+	    some services inherently need state. For example, transaction-based accounting (module
20
+	    acc) needs to process transaction state as opposed to individual messages, and any kinds
21
+	    of forking must be implemented statefuly. Other use of stateful processing is it trading
22
+	    <acronym>CPU</acronym> caused by retransmission processing for memory. That makes
23
+	    however only sense if <acronym>CPU</acronym> consumption per request is huge. For
24
+	    example, if you want to avoid costly <acronym>DNS</acronym> resolution for every
25
+	    retransmission of a request to an unresolveable destination, use stateful mode. Then,
26
+	    only the initial message burdens server by <acronym>DNS</acronym> queries, subsequent
27
+	    retranmissions will be dropped and will not result in more processes blocked by
28
+	    <acronym>DNS</acronym> resolution. The price is more memory consumption and higher
29
+	    processing latency.
30
+	</para>
31
+	<para>
32
+	    From user's perspective, there are two major functions : t_relay and t_relay_to. Both
33
+	    setup transaction state, absorb retransmissions from upstream, generate downstream
34
+	    retransmissions and correlate replies to requests. t_relay forwards to current &uri; (be
35
+	    it original request's &uri; or a &uri; changed by some of &uri;-modifying functions,
36
+	    such as sethost). t_relay_to forwards to a specific address.
37
+	</para>
38
+	<para>
39
+	    In general, if <acronym>TM</acronym> is used, it copies clones of received &sip;
40
+	    messages in shared memory. That costs the memory and also <acronym>CPU</acronym> time
41
+	    (memcpys, lookups, shmem locks, etc.)  Note that non-<acronym>TM</acronym> functions
42
+	    operate over the received message in private memory, that means that any core operations
43
+	    will have no effect on statefuly processed messages after creating the transactional
44
+	    state. For example, calling record_route <emphasis>after</emphasis> t_relay is pretty
45
+	    useless, as the <acronym>RR</acronym> is added to privately held message whereas its
46
+	    <acronym>TM</acronym> clone is being forwarded.
47
+	</para>
48
+	<para>
49
+	    <acronym>TM</acronym> is quite big and uneasy to programm--lot of mutexes, shared memory
50
+	    access, malloc & free, timers--you really need to be careful when you do anything. To
51
+	    simplify <acronym>TM</acronym> programming, there is the instrument of callbacks. The
52
+	    callback mechanisms allow programmers to register their functions to specific event. See
53
+	    t_hooks.h for a list of possible events.
54
+	</para>
55
+	<para>
56
+	    Other things programmers may want to know is &uac;--it is a very simplictic code which
57
+	    allows you to generate your own transactions. Particularly useful for things like
58
+	    NOTIFYs or <acronym>IM</acronym> gateways. The &uac; takes care of all the transaction
59
+	    machinery: retransmissions , FR timeouts, forking, etc.  See t_uac prototype in uac.h
60
+	    for more details. Who wants to see the transaction result may register for a callback.
61
+	</para>
62
+    </section>
63
+    <section>
64
+	<title>Dependencies</title>
65
+	<section>
66
+	    <title>&ser; Modules</title>
67
+	    <para>
68
+		The following modules must be loaded before this module:
69
+	    	<itemizedlist>
70
+		    <listitem>
71
+			<para>
72
+			    <emphasis>No dependencies on other &ser; modules</emphasis>.
73
+			</para>
74
+		    </listitem>
75
+	    	</itemizedlist>
76
+	    </para>
77
+	</section>
78
+	<section>
79
+	    <title>External Libraries or Applications</title>
80
+	    <para>
81
+		The following libraries or applications must be installed before running
82
+		&ser; with this module loaded:
83
+	    	<itemizedlist>
84
+		    <listitem>
85
+			<para>
86
+			    <emphasis>None</emphasis>.
87
+			</para>
88
+		    </listitem>
89
+	    	</itemizedlist>
90
+	    </para>
91
+	</section>
92
+    </section>
93
+    <section>
94
+	<title>Exported Parameters</title>
95
+	<section>
96
+	    <title><varname>fr_timer</varname> (integer)</title>
97
+	    <para>
98
+		Timer which hits if no final reply for a request or ACK for a negative INVITE reply
99
+		arrives (in seconds).
100
+	    </para>
101
+	    <para>
102
+		<emphasis>
103
+		    Default value is 30 seconds.
104
+		</emphasis>
105
+	    </para>
106
+	    <example>
107
+		<title>Set <varname>fr_timer</varname> parameter</title>
108
+		<programlisting format="linespecific">
109
+...
110
+modparam("tm", "fr_timer", 10)
111
+...
112
+</programlisting>
113
+	    </example>
114
+	</section>
115
+
116
+	<section>
117
+	    <title><varname>fr_inv_timer</varname> (integer)</title>
118
+	    <para>
119
+		Timer which hits if no final reply for an INVITE arrives after a provisional message
120
+		was received (in seconds).
121
+	    </para>
122
+	    <para>
123
+		<emphasis>
124
+		    Default value is 120 seconds.
125
+		</emphasis>
126
+	    </para>
127
+	    <example>
128
+		<title>Set <varname>fr_inv_timer</varname> parameter</title>
129
+		<programlisting format="linespecific">
130
+...
131
+modparam("tm", "fr_inv_timer", 200)
132
+...
133
+</programlisting>
134
+	    </example>
135
+	</section>
136
+
137
+	<section>
138
+	    <title><varname>wt_timer</varname> (integer)</title>
139
+	    <para>
140
+		Time for which a transaction stays in memory to absorb delayed messages after it
141
+		completed; also, when this timer hits, retransmission of local cancels is stopped (a
142
+		puristic but complex behviour would be not to enter wait state until local branches
143
+		are finished by a final reply or FR timer--we simplified).
144
+	    </para>
145
+	    <para>
146
+		<emphasis>
147
+		    Default value is 5 seconds.
148
+		</emphasis>
149
+	    </para>
150
+	    <example>
151
+		<title>Set <varname>wt_timer</varname> parameter</title>
152
+		<programlisting format="linespecific">
153
+...
154
+modparam("tm", "wt_timer", 10)
155
+...
156
+</programlisting>
157
+	    </example>
158
+	</section>
159
+
160
+	<section>
161
+	    <title><varname>delete_timer</varname> (integer)</title>
162
+	    <para>
163
+		Time after which a to-be-deleted transaction currently ref-ed by a process will be
164
+		tried to be deleted again.
165
+	    </para>
166
+	    <para>
167
+		<emphasis>
168
+		    Default value is 2 seconds.
169
+		</emphasis>
170
+	    </para>
171
+	    <example>
172
+		<title>Set <varname>delete_timer</varname> parameter</title>
173
+		<programlisting format="linespecific">
174
+...
175
+modparam("tm", "delete_timer", 5)
176
+...
177
+</programlisting>
178
+	    </example>
179
+	</section>
180
+
181
+	<section>
182
+	    <title><varname>retr_timer1p1</varname> (integer)</title>
183
+	    <para>
184
+		Retransmission period.
185
+	    </para>
186
+	    <para>
187
+		<emphasis>
188
+		    Default value is 1 second.
189
+		</emphasis>
190
+	    </para>
191
+	    <example>
192
+		<title>Set <varname>retr_timer1p1</varname> parameter</title>
193
+		<programlisting format="linespecific">
194
+...
195
+modparam("tm", "retr_timer1p1", 2)
196
+...
197
+</programlisting>
198
+	    </example>
199
+	</section>
200
+
201
+	<section>
202
+	    <title><varname>retr_timer1p2</varname> (integer)</title>
203
+	    <para>
204
+		Retransmission period.
205
+	    </para>
206
+	    <para>
207
+		<emphasis>
208
+		    Default value is 2 * <varname>retr_timer1p1</varname> second.
209
+		</emphasis>
210
+	    </para>
211
+	    <example>
212
+		<title>Set <varname>retr_timer1p2</varname> parameter</title>
213
+		<programlisting format="linespecific">
214
+...
215
+modparam("tm", "retr_timer1p2", 4)
216
+...
217
+</programlisting>
218
+	    </example>
219
+	</section>
220
+
221
+	<section>
222
+	    <title><varname>retr_timer1p3</varname> (integer)</title>
223
+	    <para>
224
+		Retransmission period.
225
+	    </para>
226
+	    <para>
227
+		<emphasis>
228
+		    Default value is 4 * <varname>retr_timer1p1</varname> second.
229
+		</emphasis>
230
+	    </para>
231
+	    <example>
232
+		<title>Set <varname>retr_timer1p4</varname> parameter</title>
233
+		<programlisting format="linespecific">
234
+...
235
+modparam("tm", "retr_timer1p3", 8)
236
+...
237
+</programlisting>
238
+	    </example>
239
+	</section>
240
+
241
+	<section>
242
+	    <title><varname>retr_timer2</varname> (integer)</title>
243
+	    <para>
244
+		Maximum retransmission period.
245
+	    </para>
246
+	    <para>
247
+		<emphasis>
248
+		    Default value is 4 seconds.
249
+		</emphasis>
250
+	    </para>
251
+	    <example>
252
+		<title>Set <varname>retr_timer2</varname> parameter</title>
253
+		<programlisting format="linespecific">
254
+...
255
+modparam("tm", "retr_timer2", 8)
256
+...
257
+</programlisting>
258
+	    </example>
259
+	</section>
260
+
261
+	<section>
262
+	    <title><varname>noisy_ctimer</varname> (integer)</title>
263
+	    <para>
264
+		If set, on FR timer INVITE transactions will be explicitly cancelled if possible,
265
+		silently dropped otherwise. Preferably, it is turned off to allow very long ringing.
266
+		This behaviour is overridden if a request is forked, or some functionality
267
+		explicitly turned it off for a transaction (like acc does to avoid unaccounted
268
+		transactions due to expired timer).
269
+	    </para>
270
+	    <para>
271
+		<emphasis>
272
+		    Default value is 0 (false).
273
+		</emphasis>
274
+	    </para>
275
+	    <example>
276
+		<title>Set <varname>noisy_ctimer</varname> parameter</title>
277
+		<programlisting format="linespecific">
278
+...