- Requests after a DNS failover are constructed from the outgoing
[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 30 seconds.
25         </para>
26         <example>
27             <title>Set <varname>fr_timer</varname> parameter</title>
28             <programlisting>
29 ...
30 modparam("tm", "fr_timer", 10)
31 ...
32             </programlisting>
33         </example>
34     </section>
35
36     <section id="fr_inv_timer">
37         <title><varname>fr_inv_timer</varname> (integer)</title>
38         <para>
39             Timer which hits if no final reply for an INVITE arrives after a
40             provisional message was received (in milliseconds).
41         </para>
42         <para>
43             Default value is 120 seconds.
44         </para>
45         <example>
46             <title>Set <varname>fr_inv_timer</varname> parameter</title>
47             <programlisting>
48 ...
49 modparam("tm", "fr_inv_timer", 200)
50 ...
51             </programlisting>
52         </example>
53     </section>
54
55     <section id="wt_timer">
56         <title><varname>wt_timer</varname> (integer)</title>
57         <para>
58             Time for which a transaction stays in memory to absorb delayed
59             messages after it completed; also, when this timer hits,
60             retransmission of local cancels is stopped (a puristic but complex
61             behavior would be not to enter wait state until local branches are
62             finished by a final reply or FR timer--we simplified).
63         </para>
64         <para>
65             Default value is 5 seconds.
66         </para>
67         <example>
68             <title>Set <varname>wt_timer</varname> parameter</title>
69             <programlisting>
70 ...
71 modparam("tm", "wt_timer", 10)
72 ...
73             </programlisting>
74         </example>
75     </section>
76
77     <section id="delete_timer">
78         <title><varname>delete_timer</varname> (integer)</title>
79         <para>
80             Time after which a to-be-deleted transaction currently ref-ed by a
81             process will be tried to be deleted again.
82         </para>
83         <para>
84             Default value is 200 milliseconds.
85         </para>
86         <example>
87             <title>Set <varname>delete_timer</varname> parameter</title>
88             <programlisting>
89 ...
90 modparam("tm", "delete_timer", 5)
91 ...
92             </programlisting>
93         </example>
94     </section>
95     
96     <section id="retr_timer1">
97         <title><varname>retr_timer1</varname> (integer)</title>
98         <para>
99             Initial retransmission period (in milliseconds).
100         </para>
101         <para>
102             Default value is 500 milliseconds.
103         </para>
104         <example>
105             <title>Set <varname>retr_timer1</varname> parameter</title>
106             <programlisting>
107 ...
108 modparam("tm", "retr_timer1", 1000)
109 ...
110             </programlisting>
111         </example>
112     </section>
113
114     <section id="retr_timer2">
115         <title><varname>retr_timer2</varname> (integer)</title>
116         <para>
117             Maximum retransmission period (in milliseconds). The retransmission
118                 interval starts with <varname>retr_timer1</varname> and increases until
119                 it reaches this value. After this it stays constant at 
120                 <varname>retr_timer2</varname>.
121         </para>
122         <para>
123             Default value is 4000 milliseconds.
124         </para>
125         <example>
126             <title>Set <varname>retr_timer2</varname> parameter</title>
127             <programlisting>
128 ...
129 modparam("tm", "retr_timer2", 2000)
130 ...
131             </programlisting>
132         </example>
133     </section>
134
135     <section id="noisy_ctimer">
136         <title><varname>noisy_ctimer</varname> (integer)</title>
137         <para>
138             If set, INVITE transactions that time-out (FR INV timer) will be 
139                 always replied. If it's not set, the transaction has only one
140                 branch and no response was ever received on this branch, it 
141                 will be silently dropped (no 408 reply will be generated)
142                 This behavior is overridden if a request is forked, the transaction
143                  has a failure route or callback, or some functionality explicitly 
144                  turned it on  for a transaction (like acc does to avoid unaccounted
145                  transactions due to expired timer).
146                 Turn this off only if you know the client UACs will timeout and their
147                 timeout interval fro INVITEs is lower or equal than tm's
148                 <varname>fr_inv_timer</varname>.
149         </para>
150         <para>
151             Default value is 1 (on).
152         </para>
153         <example>
154             <title>Set <varname>noisy_ctimer</varname> parameter</title>
155             <programlisting>
156 ...
157 modparam("tm", "noisy_ctimer", 1)
158 ...
159             </programlisting>
160         </example>
161     </section>
162
163         <section id="unix_tx_timeout">
164         <title><varname>unix_tx_timeout</varname> (integer)</title>
165         <para>
166                 Unix socket transmission timeout, in milliseconds.
167         </para>
168         <para>
169                 If unix sockets are used (e.g.: to communicate with sems) and sending
170                 a message on a unix socket takes longer then 
171                 <varname>unix_tx_timeout</varname>, the send will fail.
172         </para>
173         <para>
174             The default value is 500 milliseconds.
175         </para>
176         <example>
177             <title>Set <varname>unix_tx_timeout</varname> parameter</title>
178             <programlisting>
179 ...
180 modparam("tm", "unix_tx_timeout", 250)
181 ...
182             </programlisting>
183         </example>
184         </section>
185
186     <section id="aggregate_challenges">
187         <title><varname>aggregate_challenges</varname> (integer)</title>
188         <para>
189                 If set (default), the final reply is a 401 or a 407 and more then
190                 one branch received a 401 or 407, then all the WWW-Authenticate and 
191                 Proxy-Authenticate headers from all the 401 and 407 replies will 
192                 be aggregated in a new final reply. If only one branch received the
193                  winning 401 or 407 then this reply will be forwarded (no new one
194                  will be built).
195                 If 0 only the first 401, or if no 401 was received the first 407,  will
196                 be forwarded (no header aggregation).
197         </para>
198         <para>
199             Default value is 1 (required by rfc3261).
200         </para>
201         <example>
202             <title>Set <varname>aggregate_challenges</varname> parameter</title>
203             <programlisting>
204 ...
205 modparam("tm", "aggregate_challenges", 0)
206 ...
207             </programlisting>
208         </example>
209     </section>
210
211     <section id="reparse_invite">
212         <title><varname>reparse_invite</varname> (integer)</title>
213         <para>
214                 If set (default), the CANCEL and negative ACK requests are
215                 constructed from the INVITE message which was sent out instead
216                 of building them from the received request. The disadvantage is
217                 that the outgoing INVITE has to be partially re-parsed, the advantage
218                 is that the CANCEL/ACK is always RFC 3261-compliant, it always
219                 contains the same route-set as the INVITE message. Do not disable
220                 the INVITE re-parsing for example in the following cases:
221         </para>
222         <para>
223                 - The INVITE contains a preloaded route-set, and SER forwards
224                 the message to the next hop according to the Route header. The
225                 Route header is not removed in the CANCEL without
226                 <varname>reparse_invite</varname>=1.
227         </para>
228         <para>
229                 - SER record-routes, thus an in-dialog INVITE contains a Route
230                 header which is removed during loose routing. If the in-dialog
231                 INVITE is rejected, the negative ACK still contains the Route
232                 header without <varname>reparse_invite</varname>=1.
233         </para>
234         <para>
235             Default value is 1.
236         </para>
237         <example>
238             <title>Set <varname>reparse_invite</varname> parameter</title>
239             <programlisting>
240 ...
241 modparam("tm", "reparse_invite", 0)
242 ...
243             </programlisting>
244         </example>
245     </section>
246
247     <section id="ac_extra_hdrs">
248         <title><varname>ac_extra_hdrs</varname> (string)</title>
249         <para>
250                 Header fields prefixed by this parameter value are included
251                 in the CANCEL and negative ACK messages if they were present
252                 in the outgoing INVITE.
253         </para>
254         <para>
255                 Note, that the parameter value effects only those headers
256                 which are not covered by RFC-3261 (which are neither mandatory
257                 nor prohibited in CANCEL and ACK), and the parameter can be used
258                 only together with <varname>reparse_invite</varname>=1.
259         </para>
260         <para>
261             Default value is "".
262         </para>
263         <example>
264             <title>Set <varname>ac_extra_hdrs</varname> parameter</title>
265             <programlisting>
266 ...
267 modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
268 ...
269             </programlisting>
270         </example>
271     </section>
272
273     <section id="blst_503">
274         <title><varname>blst_503</varname> (integer)</title>
275         <para>
276                 If set and the blacklist support is enabled, every 503 reply source is
277                 added to the blacklist. The initial blacklist timeout (or ttl) depends
278                 on the presence of a Retry-After header in the reply and the values of
279                 the following tm parameters: <varname>blst_503_def_timeout</varname>, 
280                 <varname>blst_503_min_timeout</varname> and 
281                 <varname>blst_503_max_timeout</varname>.
282         </para>
283         <para>
284                 <emphasis>WARNING:</emphasis>blindly allowing 503 blacklisting could 
285                 be very easily exploited for DOS attacks in most network setups.
286         </para>
287         <para>
288                 The default value is 0 (disabled due to the reasons above).
289         </para>
290         <example>
291             <title>Set <varname>blst_503</varname> parameter</title>
292             <programlisting>
293 ...
294 modparam("tm", "blst_503", 1)
295 ...
296             </programlisting>
297         </example>
298     </section>
299
300     <section id="blst_503_def_timeout">
301         <title><varname>blst_503_def_timeout</varname> (integer)</title>
302         <para>
303                 
304                 Blacklist interval in seconds for a 503 reply with no Retry-After 
305                 header.
306                 See also <varname>blst_503</varname>, 
307                 <varname>blst_503_min_timeout</varname> and 
308                 <varname>blst_503_max_timeout</varname>.
309         </para>
310         <para>
311                 The default value is 0, which means that if no Retry-After header is
312                 present, the 503 reply source will not be blacklisted (rfc conformant
313                  behaviour).
314         </para>
315         <example>
316             <title>Set <varname>blst_503_def_timeout</varname> parameter</title>
317             <programlisting>
318 ...
319 modparam("tm", "blst_503_def_timeout", 120)
320 ...
321             </programlisting>
322         </example>
323     </section>
324
325     <section id="blst_503_min_timeout">
326         <title><varname>blst_503_min_timeout</varname> (integer)</title>
327         <para>
328                 
329                 Minimum blacklist interval in seconds for a 503 reply with a 
330                 Retry-After header. It will be used if the Retry-After value is 
331                 smaller.
332                 See also <varname>blst_503</varname>, 
333                 <varname>blst_503_def_timeout</varname> and 
334                 <varname>blst_503_max_timeout</varname>.
335         </para>
336         <para>
337                 The default value is 0 
338         </para>
339         <example>
340             <title>Set <varname>blst_503_min_timeout</varname> parameter</title>
341             <programlisting>
342 ...
343 modparam("tm", "blst_503_min_timeout", 30)
344 ...
345             </programlisting>
346         </example>
347     </section>
348
349     <section id="blst_503_max_timeout">
350         <title><varname>blst_503_max_timeout</varname> (integer)</title>
351         <para>
352                 
353                 Maximum blacklist interval in seconds for a 503 reply with a 
354                 Retry-After header. It will be used if the Retry-After value is 
355                 greater.
356                 See also <varname>blst_503</varname>, 
357                 <varname>blst_503_def_timeout</varname> and 
358                 <varname>blst_503_min_timeout</varname>.
359         </para>
360         <para>
361                 The default value is 3600 
362         </para>
363         <example>
364             <title>Set <varname>blst_503_max_timeout</varname> parameter</title>
365             <programlisting>
366 ...
367 modparam("tm", "blst_503_max_timeout", 604800)
368 ...
369             </programlisting>
370         </example>
371     </section>
372
373     <section id="blst_methods_add">
374         <title><varname>blst_methods_add</varname> (unsigned integer)</title>
375         <para>
376                 Bitmap of method types that trigger blacklisting on
377                 transaction timeouts. (This setting has no
378                 effect on blacklisting because of send failures.)
379         </para>
380         <para>
381                 The following values are associated to the request methods:
382                 INVITE=1, CANCEL=2, ACK=4 (not retransmitted, thus, never
383                 times-out), BYE=8, INFO=16, REGISTER=32, SUBSCRIBE=64,
384                 NOTIFY=126, OTHER=256 (all the unknown types).
385                 Check parser/msg_parser.h for farther details.
386         </para>
387         <para>
388                 Change the value carefully, because requests not having
389                 provisional response (everything but INVITE) can easily
390                 cause the next hop to be inserted into the blacklist
391                 by mistake. For exmaple the next hop is a proxy, it is alive,
392                 but waiting for the response of the UAS, and has higher
393                 fr_timer value.
394         </para>
395         <para>
396                 The default value is 1, only INVITEs trigger blacklisting
397         </para>
398         <example>
399             <title>Set <varname>blst_methods_add</varname> parameter</title>
400             <programlisting>
401 ...
402 # INVITEs and REGISTERs trigger blacklisting
403 modparam("tm", "blst_methods_add", 33)
404 ...
405             </programlisting>
406         </example>
407     </section>
408
409     <section id="blst_methods_lookup">
410         <title><varname>blst_methods_lookup</varname> (unsigned integer)</title>
411         <para>
412                 Bitmap of method types that are looked-up in the blacklist
413                 before statefull forwarding.
414                 See also <varname>blst_methods_add</varname>
415         </para>
416         <para>
417                 The default value is 4294967287, every method type except BYE.
418                 (We try to deliver BYEs no matter what)
419         </para>
420         <example>
421             <title>Set <varname>blst_methods_lookup</varname> parameter</title>
422             <programlisting>
423 ...
424 # lookup only INVITEs
425 modparam("tm", "blst_methods_lookup", 1)
426 ...
427             </programlisting>
428         </example>
429     </section>
430
431     <section id="cancel_b_method">
432         <title><varname>cancel_b_method</varname> (integer)</title>
433         <para>
434                 Method used when attempting to CANCEL an unreplied transaction branch
435                 (a branch where no reply greater the 99 was received).
436                 The possible values are 0, 1, and 2.
437         </para>
438         <para>
439                 <emphasis>0</emphasis> will immediately stop the request (INVITE) 
440                 retrasmission on the branch and it will behave as if the branch was 
441                 immediately replied with a 487 (a fake internal 487 reply). The 
442                 advantage is the unreplied branches will be terminated immediately.
443                 However it introduces a race risk with a possible slightly delayed
444                  2xx reply. In this case we could have an UA receiving a 2xx after a
445                  487. Moreover this risk is greatly amplified by packet loss
446                 (e.g. if an 180 is lost the branch will look as unreplied and
447                  a CANCEL will silently drop the branch, but a 2xx can still come at
448                  a later time).
449         </para>
450         <para>
451                 <emphasis>1</emphasis> will keep retransmitting the request on 
452                 unreplied branches. If a provisional answer is later received a CANCEL
453                 will be immediately sent back (attempting to quickly trigger a 487). 
454                 This approach is race free and avoids the 2xx after 487 problem, but
455                  it's more resource intensive: faced with a branch towards and UA that
456                  doesn't answer, a CANCEL attempt will keep the transaction alive for
457                  the whole timeout interval (<varname>fr_timer</varname>).
458         </para>
459         <para>
460                 <emphasis>2</emphasis> will send and retransmit CANCEL even on 
461                 unreplied branches, stopping the request retransmissions. This has the
462                 same advantages as <emphasis>1</emphasis> and also avoids the extra 
463                 roundtrip in the case of the provisional reply, but it's not RFC 3261 
464                 conforming (the RFC allows sending CANCELs only on pending branches).
465         </para>
466         <para>
467                 The default value is 0 (the same behaviour as ser versions
468                 less then 2.1).
469         </para>
470         <example>
471             <title>Set <varname>cancel_b_method</varname> parameter</title>
472             <programlisting>
473 ...
474 modparam("tm", "cancel_b_method", 1)
475 ...
476             </programlisting>
477         </example>
478     </section>
479
480     <section id="reparse_on_dns_failover">
481         <title><varname>reparse_on_dns_failover</varname> (integer)</title>
482         <para>
483                 If set to 1, the SIP message after a DNS failover is constructed
484                 from the outgoing message buffer of the failed branch instead of
485                 from the received request.
486         </para>
487         <para>
488                 It must be set if multiple branches are installed, the SIP message is
489                 modified differently in them, and at least one of them can result
490                 in DNS failover. If the parameter is not set the per-branch modifications
491                 are lost after the failover.
492         </para>
493         <para>
494                 Note: If the parameter is set, branch route block and TMCB_REQUEST_FWDED
495                 callback are not called in case of the failover.
496         </para>
497         <para>
498                 Disadvantage: only the via header is replaced in the message buffer, so
499                 the outgoing socket address is not corrected in any other part of the message.
500                 It is dangerous on multihomed hosts: when the new SIP request after
501                 the DNS failover is sent via different interface than the first request,
502                 the message can contain incorrect ip address in the Record-Route header
503                 for instance.
504         </para>
505         <para>
506                 Default value is 1.
507         </para>
508         <example>
509             <title>Set <varname>reparse_on_dns_failover</varname> parameter</title>
510             <programlisting>
511 ...
512 modparam("tm", "reparse_on_dns_failover", 0)
513 ...
514             </programlisting>
515        </example>
516     </section>
517
518 </section>