6a11084674a1d206c724eafacaed1cd56eff010c
[sip-router] / modules / tm / doc / params.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
3    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <section id="tm.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
6     <sectioninfo>
7         <revhistory>
8             <revision>
9                 <revnumber>$Revision$</revnumber>
10                 <date>$Date$</date>
11             </revision>
12         </revhistory>
13     </sectioninfo>
14
15     <title>Parameters</title>
16
17     <section id="fr_timer">
18         <title><varname>fr_timer</varname> (integer)</title>
19         <para>
20             Timer which hits if no final reply for a request or ACK for a
21             negative INVITE reply arrives (in milliseconds).
22         </para>
23         <para>
24             Default value is 30000 ms (30 seconds).
25         </para>
26         <para>
27                 See also: <function>t_set_fr()</function>,
28                                 <varname>max_noninv_lifetime</varname>.
29         </para>
30         <example>
31             <title>Set <varname>fr_timer</varname> parameter</title>
32             <programlisting>
33 ...
34 modparam("tm", "fr_timer", 10000)
35 ...
36             </programlisting>
37         </example>
38     </section>
39
40     <section id="fr_inv_timer">
41         <title><varname>fr_inv_timer</varname> (integer)</title>
42         <para>
43             Timer which hits if no final reply for an INVITE arrives after a
44             provisional message was received (in milliseconds).
45         </para>
46         <para>
47         </para>
48                 Note: this timer can be restarted when a provisional response is
49                 received. For more details see
50                 <varname>restart_fr_on_each_reply</varname>.
51         <para>
52             Default value is 120000 ms (120 seconds).
53         </para>
54         <para>
55                 See also: <function>t_set_fr()</function>,
56                                 <varname>max_inv_lifetime</varname>.
57         </para>
58         <example>
59             <title>Set <varname>fr_inv_timer</varname> parameter</title>
60             <programlisting>
61 ...
62 modparam("tm", "fr_inv_timer", 180000)
63 ...
64             </programlisting>
65         </example>
66     </section>
67
68         <section id="max_inv_lifetime">
69         <title><varname>max_inv_lifetime</varname> (integer)</title>
70         <para>
71                 Maximum time an INVITE transaction is allowed to be active (in 
72                 milliseconds). After this interval has passed from the transaction
73                 creation, the transaction will be either moved into the wait state
74                 or in the final response retransmission state, irrespective of the
75                 transaction  <varname>fr_inv_timer</varname> and
76                 <varname>fr_timer</varname> values.
77         </para>
78         <para>
79                 An INVITE transaction will be kept in memory for maximum:
80                 <varname>max_inv_lifetime</varname>+<varname>fr_timer</varname>(from 
81                 the ack to the final reply wait)+<varname>wt_timer</varname>.
82         </para>
83         <para>
84                 The main difference between this timer and 
85                 <varname>fr_inv_timer</varname> is that the 
86                 <varname>fr_inv_timer</varname> is per branch, while 
87                 <varname>max_inv_lifetime</varname> is per the whole transaction.
88                 Even on a per branch basis <varname>fr_inv_timer</varname> could be 
89                 restarted. For example, by default if 
90                 <varname>restart_fr_on_each_reply</varname> is not cleared, the 
91                 <varname>fr_inv_timer</varname> will be restarted for each received 
92                 provisional reply. Even if <varname>restart_fr_on_each_reply</varname>
93                 is not set the <varname>fr_inv_timer</varname> will still be restarted
94                 for each increasing reply (e.g. 180, 181, 182, ...). 
95                 Another example when a transaction can live substantially more then its
96                 <varname>fr_inv_timer</varname> and where
97                 <varname>max_inv_lifetime</varname> will help is when dns failover is 
98                 used (each failed dns destination can introduce a new branch).
99         </para>
100         <para>
101                 The default value is 180000 ms (180 seconds - the rfc3261 
102                 timer C value).
103         </para>
104         <para>
105                 See also: <varname>max_noninv_lifetime</varname>,
106                                         <function>t_set_max_lifetime()</function> (allows changing
107                                         <varname>max_inv_lifetime</varname> on a per transaction
108                                         basis),
109                                         <function>t_reset_max_lifetime</function>
110                                         <varname>fr_timer</varname>,
111                                         <varname>wt_timer</varname>,
112                                         <varname>restart_fr_on_each_reply</varname>.
113         </para>
114         <example>
115             <title>Set <varname>max_inv_lifetime</varname> parameter</title>
116             <programlisting>
117 ...
118 modparam("tm", "max_inv_lifetime", 150000)
119 ...
120             </programlisting>
121         </example>
122     </section>
123
124         <section id="max_noninv_lifetime">
125         <title><varname>max_noninv_lifetime</varname> (integer)</title>
126         <para>
127                 Maximum time a non-INVITE transaction is allowed to be active (in 
128                 milliseconds). After this interval has passed from the transaction
129                 creation, the transaction will be either moved into the wait state
130                 or in the final response retransmission state, irrespective of the
131                 transaction <varname>fr_timer</varname> value.
132                 It's the same as <varname>max_inv_lifetime</varname>, but for 
133                 non-INVITEs.
134         </para>
135         <para>
136                 A non-INVITE transaction will be kept in memory for maximum:
137                 <varname>max_noninv_lifetime</varname>+<varname>wt_timer</varname>.
138         </para>
139         <para>
140                 The main difference between this timer and 
141                 <varname>fr_timer</varname> is that the 
142                 <varname>fr_timer</varname> is per branch, while 
143                 <varname>max_noninv_lifetime</varname> is per the whole transaction.
144                 An example when a transaction can live substantially more then its
145                 <varname>fr_timer</varname> and where
146                 <varname>max_noninv_lifetime</varname> will help is when dns failover
147                 is used (each failed dns destination can introduce a new branch).
148         </para>
149         <para>
150                 The default value is 32000 ms (32 seconds - the rfc3261 timer F value).
151         </para>
152         <para>
153                 See also: <varname>max_inv_lifetime</varname>,
154                                         <function>t_set_max_lifetime()</function> (allows changing
155                                         <varname>max_noninv_lifetime</varname> on a per transaction
156                                         basis),
157                                         <function>t_reset_max_lifetime</function>
158                                         <varname>fr_timer</varname>,
159                                         <varname>wt_timer</varname>.
160         </para>
161         <example>
162             <title>Set <varname>max_noninv_lifetime</varname> parameter</title>
163             <programlisting>
164 ...
165 modparam("tm", "max_inv_lifetime", 30000)
166 ...
167             </programlisting>
168         </example>
169     </section>
170
171     <section id="wt_timer">
172         <title><varname>wt_timer</varname> (integer)</title>
173         <para>
174             Time for which a transaction stays in memory to absorb delayed
175             messages after it completed (in milliseconds); also, when this 
176             timer hits,
177             retransmission of local cancels is stopped (a puristic but complex
178             behavior would be not to enter wait state until local branches are
179             finished by a final reply or FR timer--we simplified).
180         </para>
181         <para>
182             Default value is 5000 ms (5 seconds).
183         </para>
184         <example>
185             <title>Set <varname>wt_timer</varname> parameter</title>
186             <programlisting>
187 ...
188 modparam("tm", "wt_timer", 1000)
189 ...
190             </programlisting>
191         </example>
192     </section>
193
194     <section id="delete_timer">
195         <title><varname>delete_timer</varname> (integer)</title>
196         <para>
197             Time after which a to-be-deleted transaction currently ref-ed by a
198             process will be tried to be deleted again (in milliseconds).
199         </para>
200         <para>
201             Note: this parameter is obsolete for ser 2.1 (in 2.1 the transaction
202                  is deleted the moment it's not referenced anymore).
203         </para>
204         <para>
205             Default value is 200 milliseconds.
206         </para>
207         <example>
208             <title>Set <varname>delete_timer</varname> parameter</title>
209             <programlisting>
210 ...
211 modparam("tm", "delete_timer", 100)
212 ...
213             </programlisting>
214         </example>
215     </section>
216     
217     <section id="retr_timer1">
218         <title><varname>retr_timer1</varname> (integer)</title>
219         <para>
220             Initial retransmission period (in milliseconds).
221         </para>
222         <para>
223             Default value is 500 milliseconds.
224         </para>
225         <example>
226             <title>Set <varname>retr_timer1</varname> parameter</title>
227             <programlisting>
228 ...
229 modparam("tm", "retr_timer1", 1000)
230 ...
231             </programlisting>
232         </example>
233     </section>
234
235     <section id="retr_timer2">
236         <title><varname>retr_timer2</varname> (integer)</title>
237         <para>
238             Maximum retransmission period (in milliseconds). The retransmission
239                 interval starts with <varname>retr_timer1</varname> and increases until
240                 it reaches this value. After this it stays constant at 
241                 <varname>retr_timer2</varname>.
242         </para>
243         <para>
244             Default value is 4000 milliseconds.
245         </para>
246         <example>
247             <title>Set <varname>retr_timer2</varname> parameter</title>
248             <programlisting>
249 ...
250 modparam("tm", "retr_timer2", 2000)
251 ...
252             </programlisting>
253         </example>
254     </section>
255
256     <section id="noisy_ctimer">
257         <title><varname>noisy_ctimer</varname> (integer)</title>
258         <para>
259             If set, INVITE transactions that time-out (FR INV timer) will be 
260                 always replied. If it's not set, the transaction has only one
261                 branch and no response was ever received on this branch, it 
262                 will be silently dropped (no 408 reply will be generated)
263                 This behavior is overridden if a request is forked, the transaction
264                  has a failure route or callback, or some functionality explicitly 
265                  turned it on  for a transaction (like acc does to avoid unaccounted
266                  transactions due to expired timer).
267                 Turn this off only if you know the client UACs will timeout and their
268                 timeout interval for INVITEs is lower or equal than tm's
269                 <varname>fr_inv_timer</varname>.
270         </para>
271         <para>
272             Default value is 1 (on).
273         </para>
274         <example>
275             <title>Set <varname>noisy_ctimer</varname> parameter</title>
276             <programlisting>
277 ...
278 modparam("tm", "noisy_ctimer", 1)
279 ...
280             </programlisting>
281         </example>
282     </section>
283
284         <section id="restart_fr_on_each_reply">
285         <title><varname>restart_fr_on_each_reply</varname> (integer)</title>
286         <para>
287                 If set (default), the <varname>fr_inv_timer</varname> for an INVITE
288                 transaction will be restarted for each provisional reply received
289                 (rfc3261 mandated behaviour). If not set, the 
290                 <varname>fr_inv_timer</varname> will be restarted only for the first
291                 provisional replies and for increasing replies greater or equal 180
292                 (e.g. 180, 181, 182, 185, ...).
293         </para>
294         <para>
295                 Setting it to 0 is especially useful when dealing with bad UAs that
296                 continuously retransmit 180s, not allowing the transaction to timeout 
297                 (and thus making impossible the implementation of certain services,
298                 like automatic voicemail after x seconds).
299         </para>
300         <para>
301                 Default value is 1 (on).
302         </para>
303         <para>
304                 See also: <varname>fr_inv_timer</varname>,
305                                 <varname>max_inv_lifetime</varname>.
306         </para>
307         <example>
308                 <title>Set <varname>restart_fr_on_each_reply</varname>
309                                 parameter</title>
310                 <programlisting>
311 ...
312 modparam("tm", "restart_fr_on_each_reply", 0)
313 ...
314             </programlisting>
315         </example>
316         </section>
317
318         <section id="auto_inv_100">
319         <title><varname>auto_inv_100</varname> (integer)</title>
320         <para>
321                 If set (default) tm will automatically send and 100 reply to INVITEs.
322         </para>
323         <para>
324                 Setting it to 0 one can be used to enable doing first some tests or
325                 pre-processing on the INVITE and only if some conditions are met
326                 manually send a 100 (using <function>t_reply()</function>). Note 
327                 however that in this case all the 100s have to be sent "by hand".
328                 <function>t_set_auto_inv_100()</function> might  help to selectively
329                 turn off this feature only for some specific transactions.
330         </para>
331         <para>
332                 Default value is 1 (on).
333         </para>
334         <para>
335                 See also: <function>t_set_auto_inv_100()</function>
336                                   <varname>auto_inv_100_reason</varname>. 
337         </para>
338         <example>
339                 <title>Set <varname>auto_inv_100</varname> parameter</title>
340                 <programlisting>
341 ...
342 modparam("tm", "auto_inv_100", 0)
343 ...
344             </programlisting>
345         </example>
346         </section>
347
348         <section id="auto_inv_100_reason">
349         <title><varname>auto_inv_100_reason</varname> (string)</title>
350         <para>
351                 Set reason text of the automatically send 100 to an INVITE.
352         </para>
353         <para>
354                 Default value is "trying -- your call is important to us".
355         </para>
356         <para>
357                 See also: <varname>auto_inv_100</varname>.
358         </para>
359         <example>
360                 <title>Set <varname>auto_inv_100_reason</varname> parameter</title>
361                 <programlisting>
362 ...
363 modparam("tm", "auto_inv_100_reason", "Trying")
364 ...
365             </programlisting>
366         </example>
367         </section>
368
369         <section id="unix_tx_timeout">
370         <title><varname>unix_tx_timeout</varname> (integer)</title>
371         <para>
372                 Unix socket transmission timeout, in milliseconds.
373         </para>
374         <para>
375                 If unix sockets are used (e.g.: to communicate with sems) and sending
376                 a message on a unix socket takes longer then 
377                 <varname>unix_tx_timeout</varname>, the send will fail.
378         </para>
379         <para>
380             The default value is 500 milliseconds.
381         </para>
382         <example>
383             <title>Set <varname>unix_tx_timeout</varname> parameter</title>
384             <programlisting>
385 ...
386 modparam("tm", "unix_tx_timeout", 250)
387 ...
388             </programlisting>
389         </example>
390         </section>
391
392     <section id="aggregate_challenges">
393         <title><varname>aggregate_challenges</varname> (integer)</title>
394         <para>
395                 If set (default), the final reply is a 401 or a 407 and more then
396                 one branch received a 401 or 407, then all the WWW-Authenticate and 
397                 Proxy-Authenticate headers from all the 401 and 407 replies will 
398                 be aggregated in a new final reply. If only one branch received the
399                  winning 401 or 407 then this reply will be forwarded (no new one
400                  will be built).
401                 If 0 only the first 401, or if no 401 was received the first 407,  will
402                 be forwarded (no header aggregation).
403         </para>
404         <para>
405             Default value is 1 (required by rfc3261).
406         </para>
407         <example>
408             <title>Set <varname>aggregate_challenges</varname> parameter</title>
409             <programlisting>
410 ...
411 modparam("tm", "aggregate_challenges", 0)
412 ...
413             </programlisting>
414         </example>
415     </section>
416
417     <section id="reparse_invite">
418         <title><varname>reparse_invite</varname> (integer)</title>
419         <para>
420                 If set (default), the CANCEL and negative ACK requests are
421                 constructed from the INVITE message which was sent out instead
422                 of building them from the received request. The disadvantage is
423                 that the outgoing INVITE has to be partially re-parsed, the advantage
424                 is that the CANCEL/ACK is always RFC 3261-compliant, it always
425                 contains the same route-set as the INVITE message. Do not disable
426                 the INVITE re-parsing for example in the following cases:
427         </para>
428         <para>
429                 - The INVITE contains a preloaded route-set, and SER forwards
430                 the message to the next hop according to the Route header. The
431                 Route header is not removed in the CANCEL without
432                 <varname>reparse_invite</varname>=1.
433         </para>
434         <para>
435                 - SER record-routes, thus an in-dialog INVITE contains a Route
436                 header which is removed during loose routing. If the in-dialog
437                 INVITE is rejected, the negative ACK still contains the Route
438                 header without <varname>reparse_invite</varname>=1.
439         </para>
440         <para>
441             Default value is 1.
442         </para>
443         <example>
444             <title>Set <varname>reparse_invite</varname> parameter</title>
445             <programlisting>
446 ...
447 modparam("tm", "reparse_invite", 0)
448 ...
449             </programlisting>
450         </example>
451     </section>
452
453     <section id="ac_extra_hdrs">
454         <title><varname>ac_extra_hdrs</varname> (string)</title>
455         <para>
456                 Header fields prefixed by this parameter value are included
457                 in the CANCEL and negative ACK messages if they were present
458                 in the outgoing INVITE.
459         </para>
460         <para>
461                 Note, that the parameter value effects only those headers
462                 which are not covered by RFC-3261 (which are neither mandatory
463                 nor prohibited in CANCEL and ACK), and the parameter can be used
464                 only together with <varname>reparse_invite</varname>=1.
465         </para>
466         <para>
467             Default value is "".
468         </para>
469         <example>
470             <title>Set <varname>ac_extra_hdrs</varname> parameter</title>
471             <programlisting>
472 ...
473 modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
474 ...
475             </programlisting>
476         </example>
477     </section>
478
479     <section id="blst_503">
480         <title><varname>blst_503</varname> (integer)</title>
481         <para>
482                 If set and the blacklist support is enabled, every 503 reply source is
483                 added to the blacklist. The initial blacklist timeout (or ttl) depends
484                 on the presence of a Retry-After header in the reply and the values of
485                 the following tm parameters: <varname>blst_503_def_timeout</varname>, 
486                 <varname>blst_503_min_timeout</varname> and 
487                 <varname>blst_503_max_timeout</varname>.
488         </para>
489         <para>
490                 <emphasis>WARNING:</emphasis>blindly allowing 503 blacklisting could 
491                 be very easily exploited for DOS attacks in most network setups.
492         </para>
493         <para>
494                 The default value is 0 (disabled due to the reasons above).
495         </para>
496         <example>
497             <title>Set <varname>blst_503</varname> parameter</title>
498             <programlisting>
499 ...
500 modparam("tm", "blst_503", 1)
501 ...
502             </programlisting>
503         </example>
504     </section>
505
506     <section id="blst_503_def_timeout">
507         <title><varname>blst_503_def_timeout</varname> (integer)</title>
508         <para>
509                 
510                 Blacklist interval in seconds for a 503 reply with no Retry-After 
511                 header.
512                 See also <varname>blst_503</varname>, 
513                 <varname>blst_503_min_timeout</varname> and 
514                 <varname>blst_503_max_timeout</varname>.
515         </para>
516         <para>
517                 The default value is 0, which means that if no Retry-After header is
518                 present, the 503 reply source will not be blacklisted (rfc conformant
519                  behaviour).
520         </para>
521         <example>
522             <title>Set <varname>blst_503_def_timeout</varname> parameter</title>
523             <programlisting>
524 ...
525 modparam("tm", "blst_503_def_timeout", 120)
526 ...
527             </programlisting>
528         </example>
529     </section>
530
531     <section id="blst_503_min_timeout">
532         <title><varname>blst_503_min_timeout</varname> (integer)</title>
533         <para>
534                 
535                 Minimum blacklist interval in seconds for a 503 reply with a 
536                 Retry-After header. It will be used if the Retry-After value is 
537                 smaller.
538                 See also <varname>blst_503</varname>, 
539                 <varname>blst_503_def_timeout</varname> and 
540                 <varname>blst_503_max_timeout</varname>.
541         </para>
542         <para>
543                 The default value is 0 
544         </para>
545         <example>
546             <title>Set <varname>blst_503_min_timeout</varname> parameter</title>
547             <programlisting>
548 ...
549 modparam("tm", "blst_503_min_timeout", 30)
550 ...
551             </programlisting>
552         </example>
553     </section>
554
555     <section id="blst_503_max_timeout">
556         <title><varname>blst_503_max_timeout</varname> (integer)</title>
557         <para>
558                 
559                 Maximum blacklist interval in seconds for a 503 reply with a 
560                 Retry-After header. It will be used if the Retry-After value is 
561                 greater.
562                 See also <varname>blst_503</varname>, 
563                 <varname>blst_503_def_timeout</varname> and 
564                 <varname>blst_503_min_timeout</varname>.
565         </para>
566         <para>
567                 The default value is 3600 
568         </para>
569         <example>
570             <title>Set <varname>blst_503_max_timeout</varname> parameter</title>
571             <programlisting>
572 ...
573 modparam("tm", "blst_503_max_timeout", 604800)
574 ...
575             </programlisting>
576         </example>
577     </section>
578
579     <section id="blst_methods_add">
580         <title><varname>blst_methods_add</varname> (unsigned integer)</title>
581         <para>
582                 Bitmap of method types that trigger blacklisting on
583                 transaction timeouts. (This setting has no
584                 effect on blacklisting because of send failures.)
585         </para>
586         <para>
587                 The following values are associated to the request methods:
588                 INVITE=1, CANCEL=2, ACK=4 (not retransmitted, thus, never
589                 times-out), BYE=8, INFO=16, REGISTER=32, SUBSCRIBE=64,
590                 NOTIFY=126, OTHER=256 (all the unknown types).
591                 Check parser/msg_parser.h for farther details.
592         </para>
593         <para>
594                 Change the value carefully, because requests not having
595                 provisional response (everything but INVITE) can easily
596                 cause the next hop to be inserted into the blacklist
597                 by mistake. For exmaple the next hop is a proxy, it is alive,
598                 but waiting for the response of the UAS, and has higher
599                 fr_timer value.
600         </para>
601         <para>
602                 The default value is 1, only INVITEs trigger blacklisting
603         </para>
604         <example>
605             <title>Set <varname>blst_methods_add</varname> parameter</title>
606             <programlisting>
607 ...
608 # INVITEs and REGISTERs trigger blacklisting
609 modparam("tm", "blst_methods_add", 33)
610 ...
611             </programlisting>
612         </example>
613     </section>
614
615     <section id="blst_methods_lookup">
616         <title><varname>blst_methods_lookup</varname> (unsigned integer)</title>
617         <para>
618                 Bitmap of method types that are looked-up in the blacklist
619                 before statefull forwarding.
620                 See also <varname>blst_methods_add</varname>
621         </para>
622         <para>
623                 The default value is 4294967287, every method type except BYE.
624                 (We try to deliver BYEs no matter what)
625         </para>
626         <example>
627             <title>Set <varname>blst_methods_lookup</varname> parameter</title>
628             <programlisting>
629 ...
630 # lookup only INVITEs
631 modparam("tm", "blst_methods_lookup", 1)
632 ...
633             </programlisting>
634         </example>
635     </section>
636
637     <section id="cancel_b_method">
638         <title><varname>cancel_b_method</varname> (integer)</title>
639         <para>
640                 Method used when attempting to CANCEL an unreplied transaction branch
641                 (a branch where no reply greater the 99 was received).
642                 The possible values are 0, 1, and 2.
643         </para>
644         <para>
645                 <emphasis>0</emphasis> will immediately stop the request (INVITE) 
646                 retransmission on the branch and it will behave as if the branch was 
647                 immediately replied with a 487 (a fake internal 487 reply). The 
648                 advantage is the unreplied branches will be terminated immediately.
649                 However it introduces a race risk with a possible slightly delayed
650                  2xx reply. In this case we could have an UA receiving a 2xx after a
651                  487. Moreover this risk is greatly amplified by packet loss
652                 (e.g. if an 180 is lost the branch will look as unreplied and
653                  a CANCEL will silently drop the branch, but a 2xx can still come at
654                  a later time). This is the behaviour for ser versions older then 2.1.
655         </para>
656         <para>
657                 <emphasis>1</emphasis> will keep retransmitting the request on 
658                 unreplied branches. If a provisional answer is later received a CANCEL
659                 will be immediately sent back (attempting to quickly trigger a 487). 
660                 This approach is race free and avoids the 2xx after 487 problem, but
661                  it's more resource intensive: faced with a branch towards and UA that
662                  doesn't answer, a CANCEL attempt will keep the transaction alive for
663                  the whole timeout interval (<varname>fr_timer</varname>).
664         </para>
665         <para>
666                 <emphasis>2</emphasis> will send and retransmit CANCEL even on 
667                 unreplied branches, stopping the request retransmissions. This has the
668                 same advantages as <emphasis>1</emphasis> and also avoids the extra 
669                 roundtrip in the case of the provisional reply, but it's not RFC 3261 
670                 conforming (the RFC allows sending CANCELs only on pending branches).
671         </para>
672         <para>
673                 The default value is 1.
674         </para>
675         <example>
676             <title>Set <varname>cancel_b_method</varname> parameter</title>
677             <programlisting>
678 ...
679 modparam("tm", "cancel_b_method", 1)
680 ...
681             </programlisting>
682         </example>
683     </section>
684
685     <section id="reparse_on_dns_failover">
686         <title><varname>reparse_on_dns_failover</varname> (integer)</title>
687         <para>
688                 If set to 1, the SIP message after a DNS failover is constructed
689                 from the outgoing message buffer of the failed branch instead of
690                 from the received request.
691         </para>
692         <para>
693                 It must be set if multiple branches are installed, the SIP message is
694                 modified differently in them, and at least one of them can result
695                 in DNS failover. If the parameter is not set the per-branch modifications
696                 are lost after the failover.
697         </para>
698         <para>
699                 Note: If the parameter is set, branch route block and TMCB_REQUEST_FWDED
700                 callback are not called in case of the failover.
701         </para>
702         <para>
703                 Disadvantage: only the via header is replaced in the message buffer, so
704                 the outgoing socket address is not corrected in any other part of the message.
705                 It is dangerous on multihomed hosts: when the new SIP request after
706                 the DNS failover is sent via different interface than the first request,
707                 the message can contain incorrect ip address in the Record-Route header
708                 for instance.
709         </para>
710         <para>
711                 Default value is 1.
712         </para>
713         <example>
714             <title>Set <varname>reparse_on_dns_failover</varname> parameter</title>
715             <programlisting>
716 ...
717 modparam("tm", "reparse_on_dns_failover", 0)
718 ...
719             </programlisting>
720         </example>
721     </section>
722
723     <section id="on_sl_reply">
724         <title><varname>on_sl_reply</varname> (string)</title>
725         <para>
726                 Sets reply route block, to which control is passed when a
727                 reply is received that has no associated transaction.
728                 The reply is passed to the core for stateless forwarding after
729                 the route block execution unless it returns 0.
730         </para>
731         <example>
732             <title>Set <varname>on_sl_reply</varname> parameter</title>
733             <programlisting>
734 ...
735 modparam("tm", "on_sl_reply", "stateless_replies")
736 ...
737
738 onreply_route["stateless_replies"] {
739         # do not allow stateless replies to be forwarded
740         return 0;
741 }
742             </programlisting>
743         </example>
744     </section>
745
746         <section>
747           <title><varname>fr_inv_timer_next</varname> (integer)</title>
748           <para>
749                 This parameter can be used to configure an alternative value for the
750                 fr_inv_timer timer. This alternative value is used in place
751                 of <varname>fr_inv_timer</varname> when serial forking takes place. It
752                 is used for all branches during serial forking except the last one.
753                 The last branch (or a set of parallel branches) use the original value
754                 from <varname>fr_inv_timer</varname> again.
755           </para>
756           <para>
757                 The purpose of the timer is to allow an administrator to configure a
758                 shorter version of <varname>fr_inv_timer</varname> that is used only
759                 when serial forking takes place. Forwarding branches one after another
760                 is much more time consuming, because every serial branch has to wait
761                 for the result of the previous one. That can take up to the value
762                 of <varname>fr_inv_timer</varname> and this timer is configured to two
763                 minutes by default. Hence, if you have three serial branches then
764                 completing the transaction can take six minutes with default timer values.
765           </para>
766           <para>
767                 In practise, the transaction will be terminated sooner, because the
768                 timer <varname>max_inv_lifetime</varname> hits after three minutes.
769                 Thus, some of the serial branches might not be forwarded at all. And
770                 this is exactly what <varname>fr_inv_timer_next</varname> is for. You
771                 can configure the timer to a shorter value to ensure that all serial
772                 branches are tried before the
773                 timer <varname>max_inv_lifetime</varname> hits.
774           </para>
775           <para>
776                 Note that if there is only one branch or if the current serial branch
777                 is the last one (i.e. no more serial forking takes place after this
778                 branch is finished) then <varname>fr_inv_timer_next</varname> is not
779                 used, instead the branch uses the
780                 longer <varname>fr_inv_timer</varname>.
781           </para>
782           <para>
783         Function <function>t_next_contacts()</function>
784         sets <varname>fr_inv_timer</varname>
785         to <varname>fr_inv_timer_next</varname> if serial forking takes place
786         and there is more than one serial branch.
787           </para>
788           <para>
789                 The administrator can configure the value of this timer using the
790                 configuration framework on the fly. But
791                 unlike <varname>fr_inv_timer</varname>, it is not possible to
792                 configure the value of this timer on per-transaction basis.
793           </para>
794           <para>
795                 <emphasis>
796                   The value of this timer is to be specified in milliseconds. The
797                   default value is 30000ms.
798                 </emphasis>
799           </para>
800           <example>
801                 <title>Set <varname>fr_inv_timer_next</varname> parameter</title>
802                 <programlisting format="linespecific">
803 ...
804 modparam("tm", "fr_inv_timer_next", 10000)
805 ...
806                 </programlisting>
807           </example>
808         </section>
809         
810         <section>
811                 <title><varname>contacts_avp</varname> (string)</title>
812                 <para>
813                   This is the name or Id of an AVP
814                 that <function>t_load_contacts()</function> function uses to
815                 store contacts of the destination set and that
816                 <function>t_next_contacts()</function> function uses to
817                 restore those contacts.
818                 </para>
819                 <para>
820                 <emphasis>
821                         Default value is "NULL"
822                         (t_load_contacts()/t_next_contacts() functions
823                         are disabled).
824                 </emphasis>
825                 </para>
826                 <example>
827                 <title>Set <varname>contacts_avp</varname> parameter</title>
828                 <programlisting format="linespecific">
829 ...
830 modparam("tm", "contacts_avp", "$avp(i:25)")
831 ...
832 </programlisting>
833                 </example>
834         </section>
835
836         <section id="fr_timer_avp">
837                 <title><varname>fr_timer_avp</varname> (string)</title>
838                 <para>
839                         The value of fr_timer timer can be overriden on per-transaction
840                         basis. The administrator can provide a value to be used for a
841                         particular transaction in an AVP. This parameter contains the name
842                         of the AVP that will be checked. If the AVP exists then its value
843                         will be used for the fr_timer timer, effectively overriding the
844                         value configured in <varname>fr_timer</varname> parameter for the
845                         current transaction.
846                 </para>
847                 <para>
848                         The value of this parameter is the the name of the AVP to be
849                         checked, without the $ character or "$avp" prefix.
850                 </para>
851                 <note><para>
852                         The value of the AVP is expected to be expressed in 
853                         <emphasis>seconds</emphasis> and not milliseconds (unlike the rest
854                         of the timers).
855                 </para></note>
856                 <para>
857                         This parameter is kept for backwards compatibility (hence its
858                         value expressed in seconds instead of milliseconds and its arcane
859                         way of specifying the avps). The recommended replacement is using
860                         <function>t_set_fr()</function> on a per transaction basis.
861                 </para>
862                 <para>
863                         See also: <function>t_set_fr()</function>,
864                         <varname>fr_timer</varname>.
865                 </para>
866                 <example>
867                         <title>Set <varname>fr_timer_avp</varname> parameter</title>
868                         <programlisting>
869 ...
870 modparam("tm", "fr_timer_avp", "i:708")
871 ...
872                         </programlisting>
873                 </example>
874         </section>
875         
876         <section id="fr_inv_timer_avp">
877                 <title><varname>fr_inv_timer_avp</varname> (string)</title>
878                 <para>
879                         The value of fr_inv_timer timer can be overriden on
880                         per-transaction basis. The administrator can provide a value to be
881                         used for a particular transaction in an AVP. This parameter
882                         contains the name of the AVP that will be checked. If the AVP
883                         exists, is non-empty and non-zero then its value will be used 
884                         for the fr_inv_timer timer, effectively overriding the value 
885                         configured in <varname>fr_inv_timer</varname> parameter for the
886                         current transaction.
887                 </para>
888                 <para>
889                         The value of this parameter is the the name of the AVP to be
890                         checked, without the $ character or "$avp" prefix.
891                 </para>
892                 <note><para>
893                         The value of the AVP is expected to be expressed in
894                         <emphasis>seconds</emphasis> and not milliseconds (unlike the rest
895                         of the timers).
896                 </para></note>
897                 <para>
898                         This parameter is kept for backwards compatibility (hence its
899                         value expressed in seconds instead of milliseconds and its arcane
900                         way of specifying the avps). The recommended replacement is using
901                         <function>t_set_fr()</function> on a per transaction basis.
902                 </para>
903                 <para>
904                         See also: <function>t_set_fr()</function>,
905                         <varname>fr_inv_timer</varname>.
906                 </para>
907                 <example>
908                         <title>Set <varname>fr_inv_timer_avp</varname> parameter</title>
909                         <programlisting>
910 ...
911 modparam("tm", "fr_inv_timer_avp", "my_fr_inv_timer")
912 ...
913                         </programlisting>
914                 </example>
915         </section>
916
917         <section id="unmatched_cancel">
918                 <title><varname>unmatched_cancel</varname> (string)</title>
919                 <para>
920                         This parameter selects between forwarding CANCELs
921                         that do not match any transaction statefully (0,
922                         default value), statelessly (1) or dropping them
923                         (2). Note that the statefull forwarding has an
924                         additional hidden advantage: tm will be able to
925                         recognize INVITEs that arrive after their CANCEL.
926                         Note also that this feature could be used to try
927                         a memory exhaustion DOS attack against a proxy that
928                         authenticates all requests, by continuously flooding
929                         the victim with CANCELs to random destinations
930                         (since the CANCEL cannot be authenticated, each
931                         received bogus CANCEL will create a new transaction
932                         that will live by default 30s).
933                 </para>
934                 <para>
935                         Default value is 0.
936                 </para>
937                 <example>
938                         <title>Set <varname>unmatched_cancel</varname> parameter</title>
939                         <programlisting>
940 ...
941 modparam("tm", "unmatched_cancel", "2")
942 ...
943                         </programlisting>
944                 </example>
945         </section>
946
947         <section id="ruri_matching">
948         <title><varname>ruri_matching</varname> (integer)</title>
949         <para>
950                 If set it will also try to match the request uri  when doing
951                 pre-3261 transaction matching (the via branch parameter does
952                 not contain the 3261 cookie).
953         </para>
954         <para>
955                 The only reason to have it not set is for interoperability with old,
956                 broken implementations.
957         </para>
958         <para>
959                 Default value is 1 (on).
960         </para>
961         <para>
962                 Can be set at runtime, e.g.:
963                 <programlisting>
964         $ sercmd cfg.set_now_int tm ruri_matching 0
965                 </programlisting>
966         </para>
967         <example>
968                 <title>Set <varname>ruri_matching</varname> parameter</title>
969                 <programlisting>
970 ...
971 modparam("tm", "ruri_matching", 1)
972 ...
973             </programlisting>
974         </example>
975         </section>
976
977         <section id="via1_matching">
978         <title><varname>via1_matching</varname> (integer)</title>
979         <para>
980                 If set it will also try to match the topmost via when doing
981                 pre-3261 transaction matching (the via branch parameter does
982                 not contain the 3261 cookie).
983         </para>
984         <para>
985                 The only reason to have it not set is for interoperability with old,
986                 broken implementations.
987         </para>
988         <para>
989                 Default value is 1 (on).
990         </para>
991         <para>
992                 Can be set at runtime, e.g.:
993                 <programlisting>
994         $ sercmd cfg.set_now_int tm via1_matching 0
995                 </programlisting>
996         </para>
997         <example>
998                 <title>Set <varname>via1_matching</varname> parameter</title>
999                 <programlisting>
1000 ...
1001 modparam("tm", "via1_matching", 1)
1002 ...
1003             </programlisting>
1004         </example>
1005         </section>
1006
1007         <section id="pass_provisional_replies">
1008         <title><varname>pass_provisional_replies</varname> (integer)</title>
1009         <para>
1010                 If set, TMCB_LOCAL_REPONSE_OUT tm registered callbacks will be called
1011                 also for provisional replies.
1012         </para>
1013         <para>
1014                 Default value is 0 (off).
1015         </para>
1016         <para>
1017                 Can be set at runtime, e.g.:
1018                 <programlisting>
1019         $ sercmd cfg.set_now_int tm pass_provisional_replies 1
1020                 </programlisting>
1021         </para>
1022         <example>
1023                 <title>Set <varname>pass_provisional_replies</varname> parameter
1024                 </title>
1025                 <programlisting>
1026 ...
1027 modparam("tm", "pass_provisional_replies", 1)
1028 ...
1029             </programlisting>
1030         </example>
1031         </section>
1032
1033         <section id="default_code">
1034         <title><varname>default_code</varname> (integer)</title>
1035         <para>
1036                 Default response code sent by <function>t_reply()</function> if it
1037                 cannot retrieve its parameters (e.g. inexistent avp).
1038                 Valid values are between 400 and 699.
1039         </para>
1040         <para>
1041                 Default value is 500.
1042         </para>
1043         <para>
1044                 Can be set at runtime, e.g.:
1045                 <programlisting>
1046         $ sercmd cfg.set_now_int tm default_code 505
1047                 </programlisting>
1048         </para>
1049         <example>
1050                 <title>Set <varname>default_code</varname> parameter </title>
1051                 <programlisting>
1052 ...
1053 modparam("tm", "default_code", 501)
1054 ...
1055             </programlisting>
1056         </example>
1057         </section>
1058
1059         <section id="default_reason">
1060         <title><varname>default_reason</varname> (string)</title>
1061         <para>
1062                 Default SIP reason phrase sent by <function>t_reply()</function> if it
1063                 cannot retrieve its parameters (e.g. inexistent avp).
1064         </para>
1065         <para>
1066                 Default value is "Server Internal Error".
1067         </para>
1068         <para>
1069                 Can be set at runtime, e.g.:
1070                 <programlisting>
1071         $ sercmd cfg.set_now_string tm default_reason "Unknown error"
1072                 </programlisting>
1073         </para>
1074         <example>
1075                 <title>Set <varname>default_reason</varname> parameter </title>
1076                 <programlisting>
1077 ...
1078 modparam("tm", "default_reason", "Unknown reason")
1079 ...
1080             </programlisting>
1081         </example>
1082         </section>
1083
1084         <section id="disable_6xx_block">
1085         <title><varname>disable_6xx_block</varname> (integer)</title>
1086         <para>
1087                 If set tm will treat all the 6xx replies like normal replies 
1088                 (warning: this would be non-rfc conformant behaviour).
1089         </para>
1090         <para>
1091                 If not set (default) receiving a 6xx will cancel all the running
1092                 parallel branches, will stop dns failover and forking. However
1093                 serial forking using <function>append_branch()</function> in the
1094                 <function>failure_route</function> will still work.
1095         </para>
1096         <para>
1097                 It can be overwritten on a per transaction basis using
1098                 <function>t_set_disable_6xx()</function>.
1099         </para>
1100         <para>
1101                 Default value is 0 (off, rfc conformant behaviour).
1102         </para>
1103         <para>
1104                 Can be set at runtime, e.g.:
1105                 <programlisting>
1106         $ sercmd cfg.set_now_int tm disable_6xx_block 0
1107                 </programlisting>
1108         </para>
1109         <para>
1110                 See also: <function>t_set_disable_6xx()</function>.
1111         </para>
1112         <example>
1113                 <title>Set <varname>disable_6xx_block</varname> parameter</title>
1114                 <programlisting>
1115 ...
1116 modparam("tm", "disable_6xx_block", 1)
1117 ...
1118             </programlisting>
1119         </example>
1120         </section>
1121
1122 <section id="local_ack_mode">
1123         <title><varname>local_ack_mode</varname> (integer)</title>
1124         <para>
1125                 It controls where locally generated ACKs for 2xx replies to local
1126                 transactions (transactions created via <function>t_uac*()</function>
1127                 either thorugh the tm api or via RPC/mi/fifo) are sent.
1128         </para>
1129         <para> It has 3 possible values:</para>
1130         <itemizedlist>
1131                 <listitem><para>
1132                 <emphasis>0</emphasis> - the ACK destination is choosen according to
1133                 the rfc: the next hop is found using the contact and the route set and
1134                 then DNS resolution is used on it.
1135                 </para></listitem>
1136                 <listitem><para>
1137                 <emphasis>1</emphasis> - the ACK is sent to the same address as the
1138                 corresponding INVITE branch.
1139                 </para></listitem>
1140                 <listitem><para>
1141                 <emphasis>2</emphasis> - the ACK is sent to the source of the 2xx
1142                 reply.
1143                 </para></listitem>
1144         </itemizedlist>
1145         <note>
1146         Mode 1 and 2 break the rfc, but are useful to deal with some simple UAs
1147         behind the NAT cases (no different routing for the ACK and the contact 
1148         contains an address behind the NAT).
1149         </note>
1150         <para>
1151                 The default value is 0 (rfc conformant behaviour).
1152         </para>
1153         <para>
1154                 Can be set at runtime, e.g.:
1155                 <programlisting>
1156         $ sercmd cfg.set_now_int tm local_ack_mode 0
1157                 </programlisting>
1158         </para>
1159         <example>
1160                 <title>Set <varname>local_ack_mode</varname> parameter</title>
1161                 <programlisting>
1162 ...
1163 modparam("tm", "local_ack_mode", 1)
1164 ...
1165             </programlisting>
1166         </example>
1167         </section>
1168
1169 </section>