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