Browse code

- missing docs for the cancel_b_method tm parameter

Andrei Pelinescu-Onciul authored on 10/03/2008 09:58:15
Showing 3 changed files
... ...
@@ -18,7 +18,9 @@ modules:
18 18
  - blst      - new module containing script blacklist manipulations functions
19 19
                (the source of a message can be blacklisted, removed from the
20 20
                 blacklist or checked for presence in the blacklist).
21
- - tm        - support for adding a 503 reply source to the blacklist for
21
+ - tm        - method for canceling unreplied branches can now be selected
22
+               using the new cancel_b_method tm parameter.
23
+             - support for adding a 503 reply source to the blacklist for
22 24
                the time specified in the Retry-After header (see the new tm
23 25
                parameters blst_503, blst_503_def_timeout, blst_503_min_timeout
24 26
                and blst_503_max_timeout).
... ...
@@ -50,6 +52,17 @@ modules:
50 50
              - behaviour when receiving a CANCEL which doesn't match any 
51 51
                transaction can be selected using the unmatched_cancel param.
52 52
              - params: 
53
+                        - cancel_b_method - selects one of the three methods
54
+                          for dealing with unreplied branches when the 
55
+                          transaction must be canceled. The possible values
56
+                          are 0 (default and old behaviour) for stopping 
57
+                          request retransmission on the branch and act as if 
58
+                          the branch was immediately replied with a 487,
59
+                          1 for continuing to retransmit the request until an
60
+                          answer is received or the timeout kicks in and
61
+                          2 for stopping the request retransmission and sending
62
+                          CANCEL on the branch (not rfc conforming).
63
+                          For more information see tm docs.
53 64
                         - blst_503 - if set and if the blacklist is used
54 65
                           (use_dst_blacklist=1), add the source of a 503 reply
55 66
                           to the blacklist
... ...
@@ -92,6 +105,10 @@ modules:
92 92
                            received bogus CANCEL will create a new transaction 
93 93
                            that will live by default 30s).
94 94
              - functions:
95
+                        - t_grep_status("code") -- returns true if any branch
96
+                          received code as the final reply (or if no final 
97
+                          reply was yet received, but a "code" provisional 
98
+                          reply).
95 99
                         - t_set_auto_inv_100(on/off) - switch automatically
96 100
                           sending 100 replies to INVITEs on/off on a per
97 101
                           transaction basis. It overrides the tm param.
... ...
@@ -102,6 +119,8 @@ modules:
102 102
                         - t_set_retr(t1, t2) - changes the retransmissions
103 103
                            intervals on the fly, on a per transaction basis.
104 104
 core:
105
+             - most of the config variables can now be changed on the fly,
106
+               without ser restart  (migration work in progress)
105 107
              - tcp improvements (better tcp timers, send fd cache, special
106 108
                 options support)
107 109
              - dns naptr support (see dns_try_naptr and dns_<proto>_pref)
... ...
@@ -1,366 +1,532 @@
1
-
2
-tm Module
1
+TM Module
3 2
 
4 3
 Jiri Kuthan
5 4
 
6 5
    FhG FOKUS
7 6
 
8
-Edited by
9
-
10
-Jiri Kuthan
11
-
12 7
    Copyright � 2003 FhG FOKUS
13
-     _________________________________________________________
14
-
15
-   Table of Contents
16
-   1. User's Guide
17
-
18
-        1.1. Overview
19
-        1.2. Dependencies
20
-
21
-              1.2.1. SER Modules
22
-              1.2.2. External Libraries or Applications
23
-
24
-        1.3. Exported Parameters
25
-
26
-              1.3.1. fr_timer (integer)
27
-              1.3.2. fr_inv_timer (integer)
28
-              1.3.3. wt_timer (integer)
29
-              1.3.4. delete_timer (integer)
30
-              1.3.5. retr_timer1p1 (integer)
31
-              1.3.6. retr_timer1p2 (integer)
32
-              1.3.7. retr_timer1p3 (integer)
33
-              1.3.8. retr_timer2 (integer)
34
-              1.3.9. noisy_ctimer (integer)
35
-
36
-        1.4. Exported Functions
37
-
38
-              1.4.1. t_relay_to_udp(ip, port), t_relay_to_tcp(ip,
39
-                      port)
40
-
41
-              1.4.2. t_relay()
42
-              1.4.3. t_on_negative(reply_route)
43
-              1.4.4. append_branch()
44
-              1.4.5. t_newtran()
45
-              1.4.6. t_reply(code, reason_phrase)
46
-              1.4.7. t_lookup_request()
47
-              1.4.8. t_retransmit_reply()
48
-              1.4.9. t_release()
49
-              1.4.10. t_forward_nonack(ip, port)
50
-              1.4.11. External Usage of TM
51
-              1.4.12. Known Issues
52
-
53
-   2. Developer's Guide
54
-
55
-        2.1. Defines
56
-        2.2. Functions
57
-
58
-              2.2.1. register_tmcb(cb_type, cb_func)
59
-              2.2.2. load_tm(*import_structure)
60
-
61
-   3. Frequently Asked Questions
62
-
63
-   List of Examples
64
-   1-1. Set fr_timer parameter
65
-   1-2. Set fr_inv_timer parameter
66
-   1-3. Set wt_timer parameter
67
-   1-4. Set delete_timer parameter
68
-   1-5. Set retr_timer1p1 parameter
69
-   1-6. Set retr_timer1p2 parameter
70
-   1-7. Set retr_timer1p4 parameter
71
-   1-8. Set retr_timer2 parameter
72
-   1-9. Set noisy_ctimer parameter
73
-   1-10. t_relay_to_udp usage
74
-   1-11. t_relay usage
75
-   1-12. t_on_negative usage
76
-   1-13. append_branch usage
77
-   1-14. t_newtran usage
78
-   1-15. t_reply usage
79
-   1-16. t_lookup_request usage
80
-   1-17. t_retransmit_reply usage
81
-   1-18. t_release usage
82
-   1-19. t_forward_nonack usage
83
-     _________________________________________________________
84
-
85
-Chapter 1. User's Guide
86
-
87
-1.1. Overview
88
-
89
-   TM module enables stateful processing of SIP transactions. The
90
-   main use of stateful logic, which is costly in terms of memory
91
-   and CPU, is some services inherently need state. For example,
92
-   transaction-based accounting (module acc) needs to process
93
-   transaction state as opposed to individual messages, and any
94
-   kinds of forking must be implemented statefully. Other use of
95
-   stateful processing is it trading CPU caused by retransmission
96
-   processing for memory. That makes however only sense if CPU
97
-   consumption per request is huge. For example, if you want to
98
-   avoid costly DNS resolution for every retransmission of a
99
-   request to an unresolvable destination, use stateful mode.
100
-   Then, only the initial message burdens server by DNS queries,
101
-   subsequent retransmissions will be dropped and will not result
102
-   in more processes blocked by DNS resolution. The price is more
103
-   memory consumption and higher processing latency.
104
-
105
-   From user's perspective, there are these major functions :
106
-   t_relay, t_relay_to_udp and t_relay_to_tcp. All of them setup
107
-   transaction state, absorb retransmissions from upstream,
108
-   generate downstream retransmissions and correlate replies to
109
-   requests. t_relay forwards to current URI (be it original
110
-   request's URI or a URI changed by some of URI-modifying
111
-   functions, such as sethost). t_relay_to_udp and t_relay_to_tcp
112
-   forward to a specific address over UDP or TCP respectively.
113
-
114
-   In general, if TM is used, it copies clones of received SIP
115
-   messages in shared memory. That costs the memory and also CPU
116
-   time (memcpys, lookups, shmem locks, etc.) Note that non-TM
117
-   functions operate over the received message in private memory,
118
-   that means that any core operations will have no effect on
119
-   statefully processed messages after creating the transactional
120
-   state. For example, calling record_route after t_relay is
121
-   pretty useless, as the RR is added to privately held message
122
-   whereas its TM clone is being forwarded.
123
-
124
-   TM is quite big and uneasy to program--lot of mutexes, shared
125
-   memory access, malloc & free, timers--you really need to be
126
-   careful when you do anything. To simplify TM programming,
127
-   there is the instrument of callbacks. The callback mechanisms
128
-   allow programmers to register their functions to specific
129
-   event. See t_hooks.h for a list of possible events.
8
+   Revision History
9
+   Revision $Revision$ $Date$
10
+     __________________________________________________________________
11
+
12
+Overview
13
+
14
+   TM module enables stateful processing of SIP transactions. The main use
15
+   of stateful logic, which is costly in terms of memory and CPU, is some
16
+   services inherently need state. For example, transaction-based
17
+   accounting (module acc) needs to process transaction state as opposed
18
+   to individual messages, and any kinds of forking must be implemented
19
+   statefully. Other use of stateful processing is it trading CPU caused
20
+   by retransmission processing for memory. That makes however only sense
21
+   if CPU consumption per request is huge. For example, if you want to
22
+   avoid costly DNS resolution for every retransmission of a request to an
23
+   unresolvable destination, use stateful mode. Then, only the initial
24
+   message burdens server by DNS queries, subsequent retransmissions will
25
+   be dropped and will not result in more processes blocked by DNS
26
+   resolution. The price is more memory consumption and higher processing
27
+   latency.
28
+
29
+   From user's perspective, there are these major functions : t_relay,
30
+   t_relay_to_udp and t_relay_to_tcp. All of them setup transaction state,
31
+   absorb retransmissions from upstream, generate downstream
32
+   retransmissions and correlate replies to requests. t_relay forwards to
33
+   current URI (be it original request's URI or a URI changed by some of
34
+   URI-modifying functions, such as sethost). t_relay_to_udp and
35
+   t_relay_to_tcp forward to a specific address over UDP or TCP
36
+   respectively.
37
+
38
+   In general, if TM is used, it copies clones of received SIP messages in
39
+   shared memory. That costs the memory and also CPU time (memcpys,
40
+   lookups, shmem locks, etc.) Note that non-TM functions operate over the
41
+   received message in private memory, that means that any core operations
42
+   will have no effect on statefully processed messages after creating the
43
+   transactional state. For example, calling record_route after t_relay is
44
+   pretty useless, as the RR is added to privately held message whereas
45
+   its TM clone is being forwarded.
46
+
47
+   TM is quite big and uneasy to program--lot of mutexes, shared memory
48
+   access, malloc and free, timers--you really need to be careful when you
49
+   do anything. To simplify TM programming, there is the instrument of
50
+   callbacks. The callback mechanisms allow programmers to register their
51
+   functions to specific event. See t_hooks.h for a list of possible
52
+   events.
130 53
 
131 54
    Other things programmers may want to know is UAC--it is a very
132
-   simplistic code which allows you to generate your own
133
-   transactions. Particularly useful for things like NOTIFYs or
134
-   IM gateways. The UAC takes care of all the transaction
135
-   machinery: retransmissions , FR timeouts, forking, etc. See
136
-   t_uac prototype in uac.h for more details. Who wants to see
137
-   the transaction result may register for a callback.
138
-     _________________________________________________________
139
-
140
-1.2. Dependencies
141
-
142
-1.2.1. SER Modules
55
+   simplistic code which allows you to generate your own transactions.
56
+   Particularly useful for things like NOTIFYs or IM gateways. The UAC
57
+   takes care of all the transaction machinery: retransmissions , FR
58
+   timeouts, forking, etc. See t_uac prototype in uac.h for more details.
59
+   Who wants to see the transaction result may register for a callback.
143 60
 
144
-   The following modules must be loaded before this module:
61
+Known Issues
145 62
 
146
-     * No dependencies on other SER modules.
147
-     _________________________________________________________
148
-
149
-1.2.2. External Libraries or Applications
150
-
151
-   The following libraries or applications must be installed
152
-   before running SER with this module loaded:
63
+     * We don't have authentication merging on forking.
64
+     * Local ACK/CANCELs copy'n'pastes Route and ignores deleted Routes.
65
+     * 6xx should be delayed.
66
+     * Possibly, performance could be improved by not parsing non-INVITEs,
67
+       as they do not be replied with 100, and do not result in
68
+       ACK/CANCELs, and other things which take parsing. However, we need
69
+       to rethink whether we don't need parsed headers later for something
70
+       else. Remember, when we now conserver a request in sh_mem, we can't
71
+       apply any pkg_mem operations to it any more. (that might be
72
+       redesigned too).
73
+     * Another performance improvement may be achieved by not parsing CSeq
74
+       in replies until reply branch matches branch of an INVITE/CANCEL in
75
+       transaction table.
76
+     * t_replicate should be done more cleanly--Vias, Routes, etc. should
77
+       be removed from a message prior to replicating it (well, does not
78
+       matter any longer so much as there is a new replication module).
79
+     * SNMP support (as nobody cares about SNMP, in particular for TM, I
80
+       will drop this item soon).
153 81
 
154
-     * None.
155
-     _________________________________________________________
82
+Parameters
156 83
 
157
-1.3. Exported Parameters
84
+   Revision History
85
+   Revision $Revision$ $Date$
158 86
 
159
-1.3.1. fr_timer (integer)
87
+fr_timer (integer)
160 88
 
161
-   Timer which hits if no final reply for a request or ACK for a
162
-   negative INVITE reply arrives (in seconds).
89
+   Timer which hits if no final reply for a request or ACK for a negative
90
+   INVITE reply arrives (in milliseconds).
163 91
 
164
-   Default value is 30 seconds. 
92
+   Default value is 30 seconds.
165 93
 
166
-   Example 1-1. Set fr_timer parameter
94
+   Example 1. Set fr_timer parameter
167 95
 ...
168 96
 modparam("tm", "fr_timer", 10)
169 97
 ...
170
-     _________________________________________________________
171 98
 
172
-1.3.2. fr_inv_timer (integer)
99
+fr_inv_timer (integer)
173 100
 
174
-   Timer which hits if no final reply for an INVITE arrives after
175
-   a provisional message was received (in seconds).
101
+   Timer which hits if no final reply for an INVITE arrives after a
102
+   provisional message was received (in milliseconds).
176 103
 
177
-   Default value is 120 seconds. 
104
+   Default value is 120 seconds.
178 105
 
179
-   Example 1-2. Set fr_inv_timer parameter
106
+   Example 2. Set fr_inv_timer parameter
180 107
 ...
181 108
 modparam("tm", "fr_inv_timer", 200)
182 109
 ...
183
-     _________________________________________________________
184 110
 
185
-1.3.3. wt_timer (integer)
111
+wt_timer (integer)
186 112
 
187
-   Time for which a transaction stays in memory to absorb delayed
188
-   messages after it completed; also, when this timer hits,
189
-   retransmission of local cancels is stopped (a puristic but
190
-   complex behavior would be not to enter wait state until local
191
-   branches are finished by a final reply or FR timer--we
192
-   simplified).
113
+   Time for which a transaction stays in memory to absorb delayed messages
114
+   after it completed; also, when this timer hits, retransmission of local
115
+   cancels is stopped (a puristic but complex behavior would be not to
116
+   enter wait state until local branches are finished by a final reply or
117
+   FR timer--we simplified).
193 118
 
194
-   Default value is 5 seconds. 
119
+   Default value is 5 seconds.
195 120
 
196
-   Example 1-3. Set wt_timer parameter
121
+   Example 3. Set wt_timer parameter
197 122
 ...
198 123
 modparam("tm", "wt_timer", 10)
199 124
 ...
200
-     _________________________________________________________
201 125
 
202
-1.3.4. delete_timer (integer)
126
+delete_timer (integer)
203 127
 
204
-   Time after which a to-be-deleted transaction currently ref-ed
205
-   by a process will be tried to be deleted again.
128
+   Time after which a to-be-deleted transaction currently ref-ed by a
129
+   process will be tried to be deleted again.
206 130
 
207
-   Default value is 2 seconds. 
131
+   Default value is 200 milliseconds.
208 132
 
209
-   Example 1-4. Set delete_timer parameter
133
+   Example 4. Set delete_timer parameter
210 134
 ...
211 135
 modparam("tm", "delete_timer", 5)
212 136
 ...
213
-     _________________________________________________________
214 137
 
215
-1.3.5. retr_timer1p1 (integer)
138
+retr_timer1 (integer)
216 139
 
217
-   Retransmission period.
140
+   Initial retransmission period (in milliseconds).
218 141
 
219
-   Default value is 1 second. 
142
+   Default value is 500 milliseconds.
220 143
 
221
-   Example 1-5. Set retr_timer1p1 parameter
144
+   Example 5. Set retr_timer1 parameter
222 145
 ...
223
-modparam("tm", "retr_timer1p1", 2)
146
+modparam("tm", "retr_timer1", 1000)
224 147
 ...
225
-     _________________________________________________________
226 148
 
227
-1.3.6. retr_timer1p2 (integer)
149
+retr_timer2 (integer)
228 150
 
229
-   Retransmission period.
151
+   Maximum retransmission period (in milliseconds). The retransmission
152
+   interval starts with retr_timer1 and increases until it reaches this
153
+   value. After this it stays constant at retr_timer2.
230 154
 
231
-   Default value is 2 * retr_timer1p1 second. 
155
+   Default value is 4000 milliseconds.
232 156
 
233
-   Example 1-6. Set retr_timer1p2 parameter
157
+   Example 6. Set retr_timer2 parameter
234 158
 ...
235
-modparam("tm", "retr_timer1p2", 4)
159
+modparam("tm", "retr_timer2", 2000)
236 160
 ...
237
-     _________________________________________________________
238 161
 
239
-1.3.7. retr_timer1p3 (integer)
162
+noisy_ctimer (integer)
240 163
 
241
-   Retransmission period.
164
+   If set, INVITE transactions that time-out (FR INV timer) will be always
165
+   replied. If it's not set, the transaction has only one branch and no
166
+   response was ever received on this branch, it will be silently dropped
167
+   (no 408 reply will be generated) This behavior is overridden if a
168
+   request is forked, the transaction has a failure route or callback, or
169
+   some functionality explicitly turned it on for a transaction (like acc
170
+   does to avoid unaccounted transactions due to expired timer). Turn this
171
+   off only if you know the client UACs will timeout and their timeout
172
+   interval fro INVITEs is lower or equal than tm's fr_inv_timer.
242 173
 
243
-   Default value is 4 * retr_timer1p1 second. 
174
+   Default value is 1 (on).
244 175
 
245
-   Example 1-7. Set retr_timer1p4 parameter
176
+   Example 7. Set noisy_ctimer parameter
246 177
 ...
247
-modparam("tm", "retr_timer1p3", 8)
178
+modparam("tm", "noisy_ctimer", 1)
248 179
 ...
249
-     _________________________________________________________
250 180
 
251
-1.3.8. retr_timer2 (integer)
181
+unix_tx_timeout (integer)
182
+
183
+   Unix socket transmission timeout, in milliseconds.
252 184
 
253
-   Maximum retransmission period.
185
+   If unix sockets are used (e.g.: to communicate with sems) and sending a
186
+   message on a unix socket takes longer then unix_tx_timeout, the send
187
+   will fail.
254 188
 
255
-   Default value is 4 seconds. 
189
+   The default value is 500 milliseconds.
256 190
 
257
-   Example 1-8. Set retr_timer2 parameter
191
+   Example 8. Set unix_tx_timeout parameter
258 192
 ...
259
-modparam("tm", "retr_timer2", 8)
193
+modparam("tm", "unix_tx_timeout", 250)
260 194
 ...
261
-     _________________________________________________________
262 195
 
263
-1.3.9. noisy_ctimer (integer)
196
+aggregate_challenges (integer)
264 197
 
265
-   If set, on FR timer INVITE transactions will be explicitly
266
-   canceled if possible, silently dropped otherwise. Preferably,
267
-   it is turned off to allow very long ringing. This behavior is
268
-   overridden if a request is forked, or some functionality
269
-   explicitly turned it off for a transaction (like acc does to
270
-   avoid unaccounted transactions due to expired timer).
198
+   If set (default), the final reply is a 401 or a 407 and more then one
199
+   branch received a 401 or 407, then all the WWW-Authenticate and
200
+   Proxy-Authenticate headers from all the 401 and 407 replies will be
201
+   aggregated in a new final reply. If only one branch received the
202
+   winning 401 or 407 then this reply will be forwarded (no new one will
203
+   be built). If 0 only the first 401, or if no 401 was received the first
204
+   407, will be forwarded (no header aggregation).
271 205
 
272
-   Default value is 0 (false). 
206
+   Default value is 1 (required by rfc3261).
273 207
 
274
-   Example 1-9. Set noisy_ctimer parameter
208
+   Example 9. Set aggregate_challenges parameter
275 209
 ...
276
-modparam("tm", "noisy_ctimer", 1)
210
+modparam("tm", "aggregate_challenges", 0)
277 211
 ...
278
-     _________________________________________________________
279 212
 
280
-1.4. Exported Functions
213
+reparse_invite (integer)
281 214
 
282
-1.4.1. t_relay_to_udp(ip, port), t_relay_to_tcp(ip, port)
215
+   If set (default), the CANCEL and negative ACK requests are constructed
216
+   from the INVITE message which was sent out instead of building them
217
+   from the received request. The disadvantage is that the outgoing INVITE
218
+   has to be partially re-parsed, the advantage is that the CANCEL/ACK is
219
+   always RFC 3261-compliant, it always contains the same route-set as the
220
+   INVITE message. Do not disable the INVITE re-parsing for example in the
221
+   following cases:
283 222
 
284
-   Relay a message statefully to a fixed destination. This along
285
-   with t_relay is the function most users want to use--all other
286
-   are mostly for programming. Programmers interested in writing
287
-   TM logic should review how t_relay is implemented in tm.c and
288
-   how TM callbacks work.
223
+   - The INVITE contains a preloaded route-set, and SER forwards the
224
+   message to the next hop according to the Route header. The Route header
225
+   is not removed in the CANCEL without reparse_invite=1.
289 226
 
290
-   Meaning of the parameters is as follows:
227
+   - SER record-routes, thus an in-dialog INVITE contains a Route header
228
+   which is removed during loose routing. If the in-dialog INVITE is
229
+   rejected, the negative ACK still contains the Route header without
230
+   reparse_invite=1.
231
+
232
+   Default value is 1.
233
+
234
+   Example 10. Set reparse_invite parameter
235
+...
236
+modparam("tm", "reparse_invite", 0)
237
+...
238
+
239
+ac_extra_hdrs (string)
240
+
241
+   Header fields prefixed by this parameter value are included in the
242
+   CANCEL and negative ACK messages if they were present in the outgoing
243
+   INVITE.
244
+
245
+   Note, that the parameter value effects only those headers which are not
246
+   covered by RFC-3261 (which are neither mandatory nor prohibited in
247
+   CANCEL and ACK), and the parameter can be used only together with
248
+   reparse_invite=1.
249
+
250
+   Default value is "".
251
+
252
+   Example 11. Set ac_extra_hdrs parameter
253
+...
254
+modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
255
+...
256
+
257
+blst_503 (integer)
258
+
259
+   If set and the blacklist support is enabled, every 503 reply source is
260
+   added to the blacklist. The initial blacklist timeout (or ttl) depends
261
+   on the presence of a Retry-After header in the reply and the values of
262
+   the following tm parameters: blst_503_def_timeout, blst_503_min_timeout
263
+   and blst_503_max_timeout.
264
+
265
+   WARNING:blindly allowing 503 blacklisting could be very easily
266
+   exploited for DOS attacks in most network setups.
267
+
268
+   The default value is 0 (disabled due to the reasons above).
269
+
270
+   Example 12. Set blst_503 parameter
271
+...
272
+modparam("tm", "blst_503", 1)
273
+...
274
+
275
+blst_503_def_timeout (integer)
276
+
277
+   Blacklist interval in seconds for a 503 reply with no Retry-After
278
+   header. See also blst_503, blst_503_min_timeout and
279
+   blst_503_max_timeout.
280
+
281
+   The default value is 0, which means that if no Retry-After header is
282
+   present, the 503 reply source will not be blacklisted (rfc conformant
283
+   behaviour).
284
+
285
+   Example 13. Set blst_503_def_timeout parameter
286
+...
287
+modparam("tm", "blst_503_def_timeout", 120)
288
+...
289
+
290
+blst_503_min_timeout (integer)
291
+
292
+   Minimum blacklist interval in seconds for a 503 reply with a
293
+   Retry-After header. It will be used if the Retry-After value is
294
+   smaller. See also blst_503, blst_503_def_timeout and
295
+   blst_503_max_timeout.
296
+
297
+   The default value is 0
298
+
299
+   Example 14. Set blst_503_min_timeout parameter
300
+...
301
+modparam("tm", "blst_503_min_timeout", 30)
302
+...
303
+
304
+blst_503_max_timeout (integer)
305
+
306
+   Maximum blacklist interval in seconds for a 503 reply with a
307
+   Retry-After header. It will be used if the Retry-After value is
308
+   greater. See also blst_503, blst_503_def_timeout and
309
+   blst_503_min_timeout.
310
+
311
+   The default value is 3600
312
+
313
+   Example 15. Set blst_503_max_timeout parameter
314
+...
315
+modparam("tm", "blst_503_max_timeout", 604800)
316
+...
317
+
318
+blst_methods_add (unsigned integer)
319
+
320
+   Bitmap of method types that trigger blacklisting on transaction
321
+   timeouts. (This setting has no effect on blacklisting because of send
322
+   failures.)
323
+
324
+   The following values are associated to the request methods: INVITE=1,
325
+   CANCEL=2, ACK=4 (not retransmitted, thus, never times-out), BYE=8,
326
+   INFO=16, REGISTER=32, SUBSCRIBE=64, NOTIFY=126, OTHER=256 (all the
327
+   unknown types). Check parser/msg_parser.h for farther details.
328
+
329
+   Change the value carefully, because requests not having provisional
330
+   response (everything but INVITE) can easily cause the next hop to be
331
+   inserted into the blacklist by mistake. For exmaple the next hop is a
332
+   proxy, it is alive, but waiting for the response of the UAS, and has
333
+   higher fr_timer value.
334
+
335
+   The default value is 1, only INVITEs trigger blacklisting
336
+
337
+   Example 16. Set blst_methods_add parameter
338
+...
339
+# INVITEs and REGISTERs trigger blacklisting
340
+modparam("tm", "blst_methods_add", 33)
341
+...
342
+
343
+blst_methods_lookup (unsigned integer)
344
+
345
+   Bitmap of method types that are looked-up in the blacklist before
346
+   statefull forwarding. See also blst_methods_add
347
+
348
+   The default value is 4294967287, every method type except BYE. (We try
349
+   to deliver BYEs no matter what)
350
+
351
+   Example 17. Set blst_methods_lookup parameter
352
+...
353
+# lookup only INVITEs
354
+modparam("tm", "blst_methods_lookup", 1)
355
+...
356
+
357
+cancel_b_method (integer)
291 358
 
359
+   Method used when attempting to CANCEL an unreplied transaction branch
360
+   (a branch where no reply greater the 99 was received). The possible
361
+   values are 0, 1, and 2.
362
+
363
+   0 will immediately stop the request (INVITE) retrasmission on the
364
+   branch and it will behave as if the branch was immediately replied with
365
+   a 487 (a fake internal 487 reply). The advantage is the unreplied
366
+   branches will be terminated immediately. However it introduces a race
367
+   risk with a possible slightly delayed 2xx reply. In this case we could
368
+   have an UA receiving a 2xx after a 487. Moreover this risk is greatly
369
+   amplified by packet loss (e.g. if an 180 is lost the branch will look
370
+   as unreplied and a CANCEL will silently drop the branch, but a 2xx can
371
+   still come at a later time).
372
+
373
+   1 will keep retransmitting the request on unreplied branches. If a
374
+   provisional answer is later received a CANCEL will be immediately sent
375
+   back (attempting to quickly trigger a 487). This approach is race free
376
+   and avoids the 2xx after 487 problem, but it's more resource intensive:
377
+   faced with a branch towards and UA that doesn't answer, a CANCEL
378
+   attempt will keep the transaction alive for the whole timeout interval
379
+   (fr_timer).
380
+
381
+   2 will send and retransmit CANCEL even on unreplied branches, stopping
382
+   the request retransmissions. This has the same advantages as 1 and also
383
+   avoids the extra roundtrip in the case of the provisional reply, but
384
+   it's not RFC 3261 conforming (the RFC allows sending CANCELs only on
385
+   pending branches).
386
+
387
+   The default value is 0 (the same behaviour as ser versions less then
388
+   2.1).
389
+
390
+   Example 18. Set cancel_b_method parameter
391
+...
392
+modparam("tm", "cancel_b_method", 1)
393
+...
394
+
395
+Functions
396
+
397
+   Revision History
398
+   Revision $Revision$ $Date$
399
+
400
+t_relay_to_udp(ip, port), t_relay_to_tcp(ip, port)
401
+
402
+   Relay a message statefully to a fixed destination. This along with
403
+   t_relay is the function most users want to use--all other are mostly
404
+   for programming. Programmers interested in writing TM logic should
405
+   review how t_relay is implemented in tm.c and how TM callbacks work.
406
+
407
+   Meaning of the parameters is as follows:
292 408
      * ip - IP address where the message should be sent.
293 409
      * port - Port number.
294 410
 
295
-   Example 1-10. t_relay_to_udp usage
411
+   Example 19. t_relay_to_udp usage
296 412
 ...
297 413
 t_relay_to_udp("1.2.3.4", "5060");
298 414
 ...
299
-     _________________________________________________________
300 415
 
301
-1.4.2. t_relay()
416
+t_relay()
302 417
 
303
-   Relay a message statefully to destination indicated in current
304
-   URI. (If the original URI was rewritten by UsrLoc, RR,
305
-   strip/prefix, etc., the new URI will be taken). Returns a
306
-   negative value on failure--you may still want to send a
307
-   negative reply upstream statelessly not to leave upstream UAC
308
-   in lurch.
418
+   Relay a message statefully to destination indicated in current URI. (If
419
+   the original URI was rewritten by UsrLoc, RR, strip/prefix, etc., the
420
+   new URI will be taken). Returns a negative value on failure--you may
421
+   still want to send a negative reply upstream statelessly not to leave
422
+   upstream UAC in lurch.
309 423
 
310
-   Example 1-11. t_relay usage
424
+   Example 20. t_relay usage
311 425
 ...
312
-if (!t_relay()) { sl_reply_error(); break; };
426
+if (!t_relay())
427
+{
428
+    sl_reply_error();
429
+    break;
430
+};
313 431
 ...
314
-     _________________________________________________________
315 432
 
316
-1.4.3. t_on_negative(reply_route)
433
+t_on_failure(failure_route)
317 434
 
318
-   Sets reply routing block, to which control is passed after a
319
-   transaction completed with a negative result but before
320
-   sending a final reply. In the referred block, you can either
321
-   start a new branch (good for services such as
322
-   forward_on_no_reply) or send a final reply on your own (good
323
-   for example for message silo, which received a negative reply
324
-   from upstream and wants to tell upstream "202 I will take care
325
-   of it"). Note that the set of command which are usable within
326
-   reply_routes is strictly limited to rewriting URI, initiating
327
-   new branches, logging, and sending stateful replies (t_reply).
328
-   Any other commands may result in unpredictable behavior and
329
-   possible server failure. Note that whenever reply_route is
330
-   entered, uri is reset to value which it had on relaying. If it
331
-   temporarily changed during a reply_route processing,
332
-   subsequent reply_route will ignore the changed value and use
333
-   again the original one.
435
+   Sets failure routing block, to which control is passed after a
436
+   transaction completed with a negative result but before sending a final
437
+   reply. In the referred block, you can either start a new branch (good
438
+   for services such as forward_on_no_reply) or send a final reply on your
439
+   own (good for example for message silo, which received a negative reply
440
+   from upstream and wants to tell upstream "202 I will take care of it").
441
+   Note that the set of commands which are usable within failure_routes is
442
+   strictly limited to rewriting URI, initiating new branches, logging,
443
+   and sending stateful replies (t_reply). Any other commands may result
444
+   in unpredictable behavior and possible server failure. Note that
445
+   whenever failure_route is entered, uri is reset to value which it had
446
+   on relaying. If it temporarily changed during a reply_route processing,
447
+   subsequent reply_route will ignore the changed value and use again the
448
+   original one.
334 449
 
335 450
    Meaning of the parameters is as follows:
451
+     * failure_route - Failure route block to be called.
336 452
 
337
-     * reply_route - Reply route block to be called.
338
-
339
-   Example 1-12. t_on_negative usage
453
+   Example 21. t_on_failure usage
340 454
 ...
341 455
 route {
342
-    t_on_negative("1");
456
+    t_on_failure("1");
343 457
     t_relay();
344 458
 }
345 459
 
346
-reply_route[1] {
460
+failure_route[1] {
347 461
     revert_uri();
348 462
     setuser("voicemail");
349 463
     append_branch();
350 464
 }
351 465
 ...
352 466
 
353
-   See test/onr.cfg for a more complex example of combination of
354
-   serial with parallel forking.
355
-     _________________________________________________________
467
+   See test/onr.cfg for a more complex example of combination of serial
468
+   with parallel forking.
469
+
470
+t_on_reply(onreply_route)
356 471
 
357
-1.4.4. append_branch()
472
+   Sets the reply routing block, to which control is passed when a reply
473
+   for the current transaction is received. Note that the set of commands
474
+   which are usable within onreply_routes is limited.
358 475
 
359
-   Similarly to t_fork_to, it extends destination set by a new
360
-   entry. The difference is that current URI is taken as new
361
-   entry.
476
+   Meaning of the parameters is as follows:
477
+     * onreply_route - Onreply route block to be called.
362 478
 
363
-   Example 1-13. append_branch usage
479
+   Example 22. t_on_reply usage
480
+...
481
+loadmodule "/usr/local/lib/ser/modules/nathelper.so"
482
+...
483
+route {
484
+        /* if natted */
485
+        t_on_reply("1");
486
+        t_relay();
487
+}
488
+
489
+onreply_route[1] {
490
+        if (status=~ "(183)|2[0-9][0-9]"){
491
+                force_rtp_proxy();
492
+                search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=y
493
+es');
494
+        }
495
+        if (nat_uac_test("1")){
496
+                fix_nated_contact();
497
+        }
498
+}
499
+
500
+t_on_branch(branch_route)
501
+
502
+   Sets the branch routing block, to which control is passed after forking
503
+   (when a new branch is created). For now branch routes are intended only
504
+   for last minute changes of the SIP messages (like adding new headers).
505
+   Note that the set of commands which are usable within branch_routes is
506
+   very limited. It is not possible to drop a message or generate a reply.
507
+
508
+   Meaning of the parameters is as follows:
509
+     * branch_route - branch route block to be called.
510
+
511
+   Example 23. t_on_branch usage
512
+...
513
+route {
514
+        t_on_branch("1");
515
+        t_relay();
516
+}
517
+
518
+branch_route[1] {
519
+        if (uri=~"sip:[0-9]+"){
520
+                append_hf("P-Warn: numeric uri\r\n");
521
+        }
522
+}
523
+
524
+append_branch()
525
+
526
+   Similarly to t_fork_to, it extends destination set by a new entry. The
527
+   difference is that current URI is taken as new entry.
528
+
529
+   Example 24. append_branch usage
364 530
 ...
365 531
 set_user("john");
366 532
 t_fork();
... ...
@@ -368,15 +534,14 @@ set_user("alice");
368 368
 t_fork();
369 369
 t_relay();
370 370
 ...
371
-     _________________________________________________________
372 371
 
373
-1.4.5. t_newtran()
372
+t_newtran()
374 373
 
375
-   Creates a new transaction, returns a negative value on error.
376
-   This is the only way a script can add a new transaction in an
377
-   atomic way. Typically, it is used to deploy a UAS.
374
+   Creates a new transaction, returns a negative value on error. This is
375
+   the only way a script can add a new transaction in an atomic way.
376
+   Typically, it is used to deploy a UAS.
378 377
 
379
-   Example 1-14. t_newtran usage
378
+   Example 25. t_newtran usage
380 379
 ...
381 380
 if (t_newtran()) {
382 381
     log("UAS logic");
... ...
@@ -385,92 +550,276 @@ if (t_newtran()) {
385 385
 ...
386 386
 
387 387
    See test/uas.cfg for more examples.
388
-     _________________________________________________________
389 388
 
390
-1.4.6. t_reply(code, reason_phrase)
389
+t_reply(code, reason_phrase)
391 390
 
392
-   Sends a stateful reply after a transaction has been
393
-   established. See t_newtran for usage.
391
+   Sends a stateful reply after a transaction has been established. See
392
+   t_newtran for usage.
394 393
 
395 394
    Meaning of the parameters is as follows:
396
-
397 395
      * code - Reply code number.
398 396
      * reason_phrase - Reason string.
399 397
 
400
-   Example 1-15. t_reply usage
398
+   Example 26. t_reply usage
401 399
 ...
402 400
 t_reply("404", "Not found");
403 401
 ...
404
-     _________________________________________________________
405 402
 
406
-1.4.7. t_lookup_request()
403
+t_lookup_request()
407 404
 
408
-   Checks if a transaction exists. Returns a positive value if
409
-   so, negative otherwise. Most likely you will not want to use
410
-   it, as a typical application of a looku-up is to introduce a
411
-   new transaction if none was found. However this is safely
412
-   (atomically) done using t_newtran.
405
+   Checks if a transaction exists. Returns a positive value if so,
406
+   negative otherwise. Most likely you will not want to use it, as a
407
+   typical application of a looku-up is to introduce a new transaction if
408
+   none was found. However this is safely (atomically) done using
409
+   t_newtran.
413 410
 
414
-   Example 1-16. t_lookup_request usage
411
+   Example 27. t_lookup_request usage
415 412
 ...
416 413
 if (t_lookup_request()) {
417 414
     ...
418 415
 };
419 416
 ...
420
-     _________________________________________________________
421 417
 
422
-1.4.8. t_retransmit_reply()
418
+t_retransmit_reply()
423 419
 
424 420
    Retransmits a reply sent previously by UAS transaction.
425 421
 
426
-   Example 1-17. t_retransmit_reply usage
422
+   Example 28. t_retransmit_reply usage
427 423
 ...
428 424
 t_retransmit_reply();
429 425
 ...
430
-     _________________________________________________________
431 426
 
432
-1.4.9. t_release()
427
+t_release()
433 428
 
434
-   Remove transaction from memory (it will be first put on a wait
435
-   timer to absorb delayed messages).
429
+   Remove transaction from memory (it will be first put on a wait timer to
430
+   absorb delayed messages).
436 431
 
437
-   Example 1-18. t_release usage
432
+   Example 29. t_release usage
438 433
 ...
439 434
 t_release();
440 435
 ...
441
-     _________________________________________________________
442 436
 
443
-1.4.10. t_forward_nonack(ip, port)
437
+t_forward_nonack(ip, port)
444 438
 
445
-   mainly for internal usage--forward a non-ACK request
446
-   statefully.
439
+   mainly for internal usage--forward a non-ACK request statefully.
447 440
 
448 441
    Meaning of the parameters is as follows:
449
-
450 442
      * ip - IP address where the message should be sent.
451 443
      * port - Port number.
452 444
 
453
-   Example 1-19. t_forward_nonack usage
445
+   Example 30. t_forward_nonack usage
454 446
 ...
455 447
 t_forward_nonack("1.2.3.4", "5060");
456 448
 ...
457
-     _________________________________________________________
458 449
 
459
-1.4.11. External Usage of TM
450
+t_set_fr(fr_inv_timeout [, fr_timeout])
451
+
452
+   Sets the fr_inv_timeout and optionally fr_timeout for the current
453
+   transaction or for transactions created during the same script
454
+   invocation, after calling this function. If the transaction is already
455
+   created (e.g called after t_relay() or in an onreply_route) all the
456
+   branches will have their final response timeout updated on-the-fly. If
457
+   one of the parameters is 0, it's value won't be changed.
458
+
459
+   Meaning of the parameters is as follows:
460
+     * fr_inv_timeout - new final response timeout (in milliseconds) for
461
+       INVITEs. See also fr_inv_timer.
462
+       fr_timeout - new final response timeout (in milliseconds) for
463
+       non-INVITE transaction, or INVITEs which haven't received yet a
464
+       provisional response. See also fr_timer.
465
+
466
+   Example 31. t_set_fr usage
467
+...
468
+route {
469
+        t_set_fr(10000); # set only fr invite timeout to 10s
470
+        t_on_branch("1");
471
+        t_relay();
472
+}
473
+
474
+branch_route[1] {
475
+        # if we are calling the pstn, extend the invite timeout to 50s
476
+        # for all the branches, and set the no-reply-received timeout to 2s
477
+        if (uri=~"sip:[0-9]+"){
478
+                t_set_fr(50000, 2000);
479
+        }
480
+}
481
+
482
+t_set_retr(retr_t1_interval, retr_t2_interval)
483
+
484
+   Sets the retr_t1_interval and retr_t2_interval for the current
485
+   transaction or for transactions created during the same script
486
+   invocation, after calling this function. If one of the parameters is 0,
487
+   it's value won't be changed. If the transaction is already created (e.g
488
+   called after t_relay() or in an onreply_route) all the existing
489
+   branches will have their retransmissions intervals updated on-the-fly:
490
+   if the retransmission interval for the branch has not yet reached T2
491
+   the interval will be reset to retr_t1_interval, else to
492
+   retr_t2_interval. Note that the change will happen after the current
493
+   interval expires (after the next retransmission, the next-next
494
+   retransmission will take place at retr_t1_interval or
495
+   retr_t2_interval). All new branches of the same transaction will start
496
+   with the new values. This function will work even if it's called in the
497
+   script before a transaction creating function (e.g.: t_set_retr(500,
498
+   4000); t_relay()). All new transaction created after this function
499
+   call, during the same script invocation will use the new values. Note
500
+   that this function will work only if tm is compile with
501
+   -DTM_DIFF_RT_TIMEOUT (which increases every transaction size with 4
502
+   bytes).
503
+
504
+   Meaning of the parameters is as follows:
505
+     * retr_t1_interval - new T1 retransmission interval (in
506
+       milliseconds). See also retr_t1_timeout.
507
+       retr_t2_interval - new T2 (or maximum) retransmission interval (in
508
+       milliseconds). See also retr_t2_timeout.
509
+
510
+   Example 32. t_set_retr usage
511
+...
512
+route {
513
+        t_set_retr(250, 0); # set only T1 to 250 ms
514
+        t_on_branch("1");
515
+        t_relay();
516
+}
517
+
518
+branch_route[1] {
519
+        # if we are calling the a remote pstn, extend T1 and decrease T2
520
+        # for all the branches
521
+        if (uri=~"sip:[0-9]+"){
522
+                t_set_retr(500, 2000);
523
+        }
524
+}
525
+
526
+t_branch_timeout()
527
+
528
+   Returns true if the failure route is executed for a branch that did
529
+   timeout. It can be used only from the failure_route.
530
+
531
+   Example 33. t_branch_timeout usage
532
+...
533
+failure_route[0]{
534
+        if (t_branch_timeout()){
535
+                log("timeout\n");
536
+                # ...
537
+        }
538
+}
539
+
540
+t_branch_replied()
541
+
542
+   Returns true if the failure route is executed for a branch that did
543
+   receive at least one reply in the past (the "current" reply is not
544
+   taken into account). It can be used only from the failure_route.
545
+
546
+   Example 34. t_branch_replied usage
547
+...
548
+failure_route[0]{
549
+        if (t_branch_timeout()){
550
+                if (t_branch_replied())
551
+                        log("timeout after receiving a reply (no answer?)\n");
552
+                else
553
+                        log("timeout, remote side seems to be down\n");
554
+                # ...
555
+        }
556
+}
460 557
 
461
-   There are applications which would like to generate SIP
462
-   transactions without too big involvement in SIP stack,
463
-   transaction management, etc. An example of such an application
464
-   is sending instant messages from a website. To address needs
465
-   of such apps, SER accepts requests for new transactions via
466
-   fifo pipes too. If you want to enable this feature, start FIFO
467
-   server with configuration option.
558
+t_any_timeout()
559
+
560
+   Returns true if at least one of the current transactions branches did
561
+   timeout.
562
+
563
+   Example 35. t_any_timeout usage
564
+...
565
+failure_route[0]{
566
+        if (!t_branch_timeout()){
567
+                if (t_any_timeout()){
568
+                        log("one branch did timeout\n");
569
+                        sl_send_reply("408", "Timeout");
570
+                }
571
+        }
572
+}
573
+
574
+t_any_replied()
575
+
576
+   Returns true if at least one of the current transactions branches did
577
+   receive some reply in the past. If called from a failure or onreply
578
+   route, the "current" reply is not taken into account.
579
+
580
+   Example 36. t_any_replied usage
581
+...
582
+onreply_route[0]{
583
+        if (!t_any_replied()){
584
+                log("first reply received\n");
585
+                # ...
586
+        }
587
+}
588
+
589
+t_grep_status("code")
590
+
591
+   Returns true if "code" is the the final reply received (or locally
592
+   generated) in at least one of the current transactions branches.
593
+
594
+   Example 37. t_grep_status usage
595
+...
596
+onreply_route[0]{
597
+        if (t_grep_status("486")){
598
+                /* force a 486 reply, even if this is not the winning branch */
599
+                t_reply("486", "Busy");
600
+        }
601
+}
602
+
603
+t_is_canceled()
604
+
605
+   Returns true if the current transaction was canceled.
606
+
607
+   Example 38. t_is_canceled usage
608
+...
609
+failure_route[0]{
610
+        if (t_is_canceled()){
611
+                log("transaction canceled\n");
612
+                # ...
613
+        }
614
+}
615
+
616
+t_relay_cancel()
617
+
618
+   Forwards the CANCEL if the corresponding INVITE transaction exists. The
619
+   function is supposed to be used at the very beginning of the script,
620
+   because the CANCELs can be caught and the rest of the script can be
621
+   bypassed this way. Do not disable reparse_invite module parameter, and
622
+   call t_relay_cancel() right after the sanity tests.
623
+
624
+   Return value is 0 (drop) if the corresponding INVITE was found and the
625
+   CANCELs were successfully sent to the pending branches, true if the
626
+   INVITE was not found, and false in case of any error.
627
+
628
+   Example 39. t_relay_cancel usage
629
+if (method == CANCEL) {
630
+        if (!t_relay_cancel()) {  # implicit drop if relaying was successful,
631
+                                  # nothing to do
632
+
633
+                # corresponding INVITE transaction found but error occurred
634
+                sl_reply("500", "Internal Server Error");
635
+                drop;
636
+        }
637
+        # bad luck, corresponding INVITE transaction is missing,
638
+        # do the same as for INVITEs
639
+}
640
+
641
+TM Module API
642
+
643
+   Revision History
644
+   Revision $Revision$ $Date$
645
+
646
+   There are applications which would like to generate SIP transactions
647
+   without too big involvement in SIP stack, transaction management, etc.
648
+   An example of such an application is sending instant messages from a
649
+   website. To address needs of such apps, SER accepts requests for new
650
+   transactions via fifo pipes too. If you want to enable this feature,
651
+   start FIFO server with configuration option.
468 652
 
469 653
    fifo="/tmp/ser_fifo"
470 654
 
471
-   Then, an application can easily launch a new transaction by
472
-   writing a transaction request to this named pipe. The request
473
-   must follow very simple format, which is
655
+   Then, an application can easily launch a new transaction by writing a
656
+   transaction request to this named pipe. The request must follow very
657
+   simple format, which is
474 658
  :t_uac_from:[<file_name>]\n
475 659
  <method>\n
476 660
  <sender's uri>\n
... ...
@@ -480,12 +829,12 @@ t_forward_nonack("1.2.3.4", "5060");
480 480
  .\n
481 481
  \n
482 482
 
483
-   (Filename is to where a report will be dumped. ser assumes
484
-   /tmp as file's directory.)
483
+   (Filename is to where a report will be dumped. ser assumes /tmp as
484
+   file's directory.)
485 485
 
486
-   Note the the request write must be atomic, otherwise it might
487
-   get intermixed with writes from other writers. You can easily
488
-   use it via Unix command-line tools, see the following example:
486
+   Note the the request write must be atomic, otherwise it might get
487
+   intermixed with writes from other writers. You can easily use it via
488
+   Unix command-line tools, see the following example:
489 489
 [jiri@bat jiri]$ cat > /tmp/ser_fifo
490 490
 :t_uac_from:xxx
491 491
 MESSAGE
... ...
@@ -502,108 +851,41 @@ end of body
502 502
 .
503 503
 
504 504
    or cat test/transaction.fifo > /tmp/ser_fifo
505
-     _________________________________________________________
506 505
 
507
-1.4.12. Known Issues
506
+Defines
508 507
 
509
-     * We don't have authentication merging on forking.
510
-     * Local ACK/CANCELs copy'n'pastes Route and ignores deleted
511
-       Routes.
512
-     * 6xx should be delayed.
513
-     * Possibly, performance could be improved by not parsing
514
-       non-INVITEs, as they do not be replied with 100, and do
515
-       not result in ACK/CANCELs, and other things which take
516
-       parsing. However, we need to rethink whether we don't need
517
-       parsed headers later for something else. Remember, when we
518
-       now conserver a request in sh_mem, we can't apply any
519
-       pkg_mem operations to it any more. (that might be
520
-       redesigned too).
521
-     * Another performance improvement may be achieved by not
522
-       parsing CSeq in replies until reply branch matches branch
523
-       of an INVITE/CANCEL in transaction table.
524
-     * t_replicate should be done more cleanly--Vias, Routes,
525
-       etc. should be removed from a message prior to replicating
526
-       it (well, does not matter any longer so much as there is a
527
-       new replication module).
528
-     * SNMP support (as nobody cares about SNMP, in particular
529
-       for TM, I will drop this item soon).
530
-     _________________________________________________________
531
-
532
-Chapter 2. Developer's Guide
533
-
534
-   The module does not provide any sort of API to use in other
535
-   SER modules.
536
-     _________________________________________________________
537
-
538
-2.1. Defines
539
-
540
-     * ACK_TAG enables stricter matching of acknowledgments
541
-       including to-tags. Without it, to-tags are ignored. It is
542
-       disabled by default for two reasons:
508
+     * ACK_TAG enables stricter matching of acknowledgments including
509
+       to-tags. Without it, to-tags are ignored. It is disabled by default
510
+       for two reasons:
543 511
           + It eliminates an unlikely race condition in which
544
-            transaction's to-tag is being rewritten by a 200 OK
545
-            whereas an ACK is being looked up by to-tag.
512
+            transaction's to-tag is being rewritten by a 200 OK whereas an
513
+            ACK is being looked up by to-tag.
546 514
           + It makes UACs happy who set wrong to-tags.
547
-       It should not make a difference, as there may be only one
548
-       negative reply sent upstream and 200/ACKs are not matched
549
-       as they constitute another transaction. It will make no
550
-       difference at all when the new magic cookie matching is
551
-       enabled anyway.
552
-     * CANCEL_TAG similarly enables strict matching of CANCELs
553
-       including to-tags--act of mercy to UACs, who screw up the
554
-       to-tags (however, it still depends on how forgiving the
555
-       downstream UAS is). Like with ACK_TAG, all this complex
556
-       transactions matching goes with RFC3261's magic cookie
557
-       away anyway.
558
-     _________________________________________________________
559
-
560
-2.2. Functions
561
-
562
-2.2.1. register_tmcb(cb_type, cb_func)
563
-
564
-   For programmatic use only--register a function to be called
565
-   back on an event. See t_hooks.h for more details.
515
+       It should not make a difference, as there may be only one negative
516
+       reply sent upstream and 200/ACKs are not matched as they constitute
517
+       another transaction. It will make no difference at all when the new
518
+       magic cookie matching is enabled anyway.
519
+     * CANCEL_TAG similarly enables strict matching of CANCELs including
520
+       to-tags--act of mercy to UACs, who screw up the to-tags (however,
521
+       it still depends on how forgiving the downstream UAS is). Like with
522
+       ACK_TAG, all this complex transactions matching goes with RFC3261's
523
+       magic cookie away anyway.
566 524
 
567
-   Meaning of the parameters is as follows:
525
+Functions
568 526
 
527
+register_tmcb(cb_type, cb_func)
528
+
529
+   For programmatic use only--register a function to be called back on an
530
+   event. See t_hooks.h for more details.
531
+
532
+   Meaning of the parameters is as follows:
569 533
      * cb_type - Callback type.
570 534
      * cb_func - Callback function.
571
-     _________________________________________________________
572 535
 
573
-2.2.2. load_tm(*import_structure)
536
+load_tm(*import_structure)
574 537
 
575
-   For programmatic use only--import exported TM functions. See
576
-   the acc module for an example of use.
538
+   For programmatic use only--import exported TM functions. See the acc
539
+   module for an example of use.
577 540
 
578 541
    Meaning of the parameters is as follows:
579
-
580 542
      * import_structure - Pointer to the import structure.
581
-     _________________________________________________________
582
-
583
-Chapter 3. Frequently Asked Questions
584
-
585
-   3.1. Where can I find more about SER?
586
-   3.2. Where can I post a question about this module?
587
-   3.3. How can I report a bug?
588
-
589
-   3.1. Where can I find more about SER?
590
-
591
-   Take a look at http://iptel.org/ser.
592
-
593
-   3.2. Where can I post a question about this module?
594
-
595
-   First at all check if your question was already answered on
596
-   one of our mailing lists:
597
-
598
-     * http://mail.iptel.org/mailman/listinfo/serusers
599
-     * http://mail.iptel.org/mailman/listinfo/serdev
600
-
601
-   E-mails regarding any stable version should be sent to
602
-   <serusers@iptel.org> and e-mail regarding development versions
603
-   or CVS snapshots should be send to <serdev@iptel.org>.
604
-
605
-
606
-   3.3. How can I report a bug?
607
-
608
-   Please follow the guidelines provided at:
609
-   http://iptel.org/ser/bugs
... ...
@@ -427,4 +427,54 @@ modparam("tm", "blst_methods_lookup", 1)
427 427
 	    </programlisting>
428 428
 	</example>
429 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
+
430 480
 </section>